Refinement Guide

This guide covers the refinement framework in TorchRef.

Overview

The Refinement class is the central component for crystallographic refinement. It coordinates:

  • Atomic model (coordinates, B-factors, occupancies)

  • Reflection data (observed structure factors)

  • Scaling (overall scale, anisotropy, bulk solvent)

  • Geometry restraints (bonds, angles, torsions, planes)

  • Target functions (least squares, maximum likelihood)

Basic Usage

from torchref import LBFGSRefinement
import torch

# Initialize
refinement = Refinement(
    data_file="data.mtz",
    pdb="model.pdb",
    device=torch.device("cuda")
)

# Run refinement with xyz and B-factors/occupancies in separate cycles
refinement.refine(
    macro_cycles=5,
)

# Or refine all parameters together
refinement.refine_everything(
    macro_cycles=5,
)

Refinement Parameters

The refinement optimizes these parameters:

  • Coordinates (xyz): Atomic positions in Ångströms

  • B-factors (b): Isotropic displacement parameters in Ų

  • Anisotropic U (u): Anisotropic displacement tensors (6 components)

  • The model automatically detects when to use Anisotropic B-factors based the input model.

  • Occupancies: Atomic occupancies (0-1)

Parameter Selection

Control which parameters are refined:

refinement.model.freeze('xyz')      # Freeze coordinates options are: 'xyz', 'b', 'u', 'occ'

refinement.model.unfreeze('b')      # Unfreeze B-factors

refinement.model.freeze_selection("chain A and resseq 10:20")  # Freeze selection
refinement.model.unfreeze_selection("all")                     # Unfreeze all

Monitoring Progress

Access refinement statistics:

# R-factors
r_work, rfree = refinement.get_rfactor()

# Dictionary with all metrics.
print(refinement.collect_metrics())