Command-Line Tools

TorchRef provides several command-line tools installed as console scripts. After installation (pip install torchref), they are available directly in your shell.

Standard Refinement

torchref.refine

LBFGS crystallographic refinement. Defaults to the Bhattacharyya overlap X-ray target with first-principles model uncertainty and joint XYZ+ADP+scaler optimisation.

torchref.refine -m model.pdb -sf reflections.mtz -o output_dir/

Produces refined coordinates (PDB and/or mmCIF), structure factors (MTZ), and a refinement_history.json log.

Key options:

  • -n number of macro cycles (default 5)

  • --mode everything (joint, default) or refine (separated XYZ then ADP)

  • --xray-mode bhattacharyya (default), ml, ls, gaussian

  • --sigma-m-scale global multiplier on σ_m for the Bhattacharyya target

  • --dmin resolution cutoff

  • --device cpu / cuda

  • -v verbose

API:

torchref.cli.refine

Difference Refinement

torchref.difference-refine

Difference refinement for time-resolved crystallography. Refines a mixed model (dark + light state) against dark and light reflection data using amplitude-only difference targets with geometry, ADP, and maximum-likelihood restraints.

torchref.difference-refine \
    --dark-pdb dark.pdb --light-pdb light.pdb \
    --dark-mtz dark.mtz --light-mtz light.mtz \
    --fractions 0.63,0.37 -o output/

Key options: --weight-schedule annealing schedule (e.g. 5,3,2), -n macro-cycles.

API:

torchref.cli.difference_refine

Map & Validation Utilities

torchref.mtz2map

Convert MTZ map coefficients to a CCP4 map file. Reads amplitude and phase columns, expands to P1, and computes a real-space map via FFT.

torchref.mtz2map -f refined.mtz -F 2FOFCWT -P PH2FOFCWT -o map.ccp4

Key options: --high-res, --low-res resolution limits, --gridsize override, -n normalize to sigma units.

API:

torchref.cli.mtz2map

torchref.validate-ded

Validate difference electron density by correlating DFo and DFc maps. Computes real-space correlations and resolution-binned reciprocal-space CC.

torchref.validate-ded \
    --dark-mtz dark.mtz --light-mtz light.mtz \
    --dark-pdb dark.pdb --light-pdb light.pdb

Key options: --fraction, --selection (Phenix-style atom selection), --mask-radius, --n-bins.

API:

torchref.cli.validate_ded

torchref.phased-difference-map

Compute phased difference and extrapolated map coefficients without refinement. Uses the same pipeline as torchref.difference-refine but the input models are kept as-is.

torchref.phased-difference-map \
    --dark-pdb dark.pdb --light-pdb light.pdb \
    --dark-mtz dark.mtz --light-mtz light.mtz \
    --fractions 0.63,0.37 -o output/
API:

torchref.cli.phased_difference_map