torchref.restraints package
Restraints module for crystallographic refinement.
This module provides classes for building and managing geometry restraints (bonds, angles, torsions, planes, chirals, VDW contacts) from CIF dictionaries.
Restraint geometry parameters are sourced from the CCP4 Monomer Library, which derives ideal values from the Cambridge Structural Database.
References
- Long, F., et al. (2017). AceDRG: a stereochemical description generator
for ligands. Acta Cryst. D73, 112-122.
- Sherri, L.N., et al. (2018). Updated CCP4 Monomer Library.
Acta Cryst. D74, 641-655.
Classes
- RestraintsNew
Refactored restraints handler using builder pattern (faster, more testable).
- ResidueIterator
Efficient iterator over residues with pre-grouped data.
- RestraintBuilder
Abstract base class for restraint builders.
- BondRestraintBuilder
Builder for bond length restraints.
- AngleRestraintBuilder
Builder for angle restraints.
- TorsionRestraintBuilder
Builder for torsion angle restraints.
- PlaneRestraintBuilder
Builder for planarity restraints.
- ChiralRestraintBuilder
Builder for chiral volume restraints.
- InterResidueBondBuilder
Builder for inter-residue bond restraints (peptide, disulfide).
- InterResidueAngleBuilder
Builder for inter-residue angle restraints.
- InterResidueTorsionBuilder
Builder for inter-residue torsion restraints (phi, psi, omega).
- InterResiduePlaneBuilder
Builder for inter-residue plane restraints.
- torchref.restraints.Restraints
alias of
RestraintsNew
- class torchref.restraints.ResidueIterator(pdb, filter_atom_type=None)[source]
Bases:
objectEfficient iterator over residues with pre-grouped data.
Pre-groups PDB data by (chainid, resseq) once at initialization, avoiding O(N) DataFrame filtering per residue. This reduces the complexity from O(N×R) to O(N log N) where N is the number of atoms and R is the number of residues.
- Parameters:
pdb (pd.DataFrame) – PDB DataFrame with columns ‘chainid’, ‘resseq’, ‘resname’, ‘name’, ‘index’.
filter_atom_type (str, optional) – If provided, only include atoms with this ATOM type (e.g., ‘ATOM’ for protein).
- pdb
Reference to the input DataFrame.
- Type:
pd.DataFrame
Examples
iterator = ResidueIterator(model.pdb) for chain_id, resseq, residue_df in iterator: print(f"Processing {chain_id}:{resseq}")
- class torchref.restraints.RestraintBuilder(verbose=0)[source]
Bases:
ABCAbstract base class for restraint builders.
Provides common functionality for accumulating restraint data during residue iteration and finalizing to sorted tensors. Child classes implement the specific logic for each restraint type.
- Parameters:
verbose (int, default 0) – Verbosity level for debug output.
- abstractmethod process_residue(residue, cif_restraints)[source]
Process a single residue, matching atoms to CIF restraints.
- Parameters:
residue (pd.DataFrame) – Residue atoms with ‘name’ and ‘index’ columns.
cif_restraints (pd.DataFrame) – Restraints from CIF dictionary for this residue type.
- Returns:
Number of restraints added.
- Return type:
- finalize(device, sort_indices=True, min_sigma=0.0001)[source]
Convert accumulated data to sorted tensors.
- Parameters:
device (torch.device) – Target device for tensors.
sort_indices (bool, default True) – Whether to sort by first atom index for memory locality.
min_sigma (float, default 1e-4) – Minimum sigma value to avoid division by zero.
- Returns:
Dictionary with ‘indices’, ‘references’, ‘sigmas’ tensors, or None if no restraints were accumulated.
- Return type:
dict or None
- class torchref.restraints.BondRestraintBuilder(verbose=0)[source]
Bases:
RestraintBuilderBuilder for bond length restraints.
Bond restraints define expected distances between pairs of bonded atoms. Each restraint specifies: atom1, atom2, target_distance, sigma.
Examples
builder = BondRestraintBuilder() for residue in residues: builder.process_residue(residue, cif_bonds) result = builder.finalize(device) print(result['indices'].shape) # (n_bonds, 2)
- process_residue(residue, cif_restraints)[source]
Process bond restraints for a single residue.
- Parameters:
residue (pd.DataFrame) – Residue atoms with ‘name’ and ‘index’ columns.
cif_restraints (pd.DataFrame) – Bond restraints with ‘atom1’, ‘atom2’, ‘value’, ‘sigma’ columns.
- Returns:
Number of bond restraints added.
- Return type:
- class torchref.restraints.AngleRestraintBuilder(verbose=0)[source]
Bases:
RestraintBuilderBuilder for angle restraints.
Angle restraints define expected angles between three atoms (1-2-3). The angle is measured at the central atom (atom2).
Examples
builder = AngleRestraintBuilder() for residue in residues: builder.process_residue(residue, cif_angles) result = builder.finalize(device) print(result['indices'].shape) # (n_angles, 3)
- process_residue(residue, cif_restraints)[source]
Process angle restraints for a single residue.
- Parameters:
residue (pd.DataFrame) – Residue atoms with ‘name’ and ‘index’ columns.
cif_restraints (pd.DataFrame) – Angle restraints with ‘atom1’, ‘atom2’, ‘atom3’, ‘value’, ‘sigma’ columns.
- Returns:
Number of angle restraints added.
- Return type:
- class torchref.restraints.TorsionRestraintBuilder(verbose=0)[source]
Bases:
RestraintBuilderBuilder for torsion angle restraints.
Torsion restraints define expected dihedral angles between four atoms. Includes periodicity information for symmetric torsions (e.g., period=3 for methyl groups).
Examples
builder = TorsionRestraintBuilder() for residue in residues: builder.process_residue(residue, cif_torsions) result = builder.finalize(device) print(result['indices'].shape) # (n_torsions, 4) print(result['periods'].shape) # (n_torsions,)
- process_residue(residue, cif_restraints)[source]
Process torsion restraints for a single residue.
Filters out torsions with sigma=0 (undefined/flexible torsions).
- Parameters:
residue (pd.DataFrame) – Residue atoms with ‘name’ and ‘index’ columns.
cif_restraints (pd.DataFrame) – Torsion restraints with ‘atom1’-‘atom4’, ‘value’, ‘sigma’, and optionally ‘periodicity’ columns.
- Returns:
Number of torsion restraints added.
- Return type:
- finalize(device, sort_indices=True, min_sigma=0.0001)[source]
Convert accumulated data to sorted tensors, including periods.
- Parameters:
device (torch.device) – Target device for tensors.
sort_indices (bool, default True) – Whether to sort by first atom index for memory locality.
min_sigma (float, default 1e-4) – Minimum sigma value.
- Returns:
Dictionary with ‘indices’, ‘references’, ‘sigmas’, ‘periods’ tensors.
- Return type:
dict or None
- class torchref.restraints.PlaneRestraintBuilder(verbose=0)[source]
Bases:
RestraintBuilderBuilder for planarity restraints.
Plane restraints define groups of atoms that should be coplanar. Unlike other restraints, planes have variable atom counts (3-10 atoms). Results are grouped by atom count for efficient tensor operations.
Examples
builder = PlaneRestraintBuilder() for residue in residues: builder.process_residue(residue, cif_planes) result = builder.finalize(device) # Returns dict like {'4_atoms': {...}, '6_atoms': {...}}
- process_residue(residue, cif_restraints)[source]
Process plane restraints for a single residue.
Groups plane atoms by plane_id and stores separately by atom count.
- Parameters:
residue (pd.DataFrame) – Residue atoms with ‘name’ and ‘index’ columns.
cif_restraints (pd.DataFrame) – Plane restraints with ‘plane_id’, ‘atom’, ‘sigma’ columns.
- Returns:
Number of plane restraints added.
- Return type:
- finalize(device, sort_indices=True, min_sigma=0.0001)[source]
Convert accumulated data to tensors grouped by atom count.
- Parameters:
device (torch.device) – Target device for tensors.
sort_indices (bool, default True) – Whether to sort by first atom index.
min_sigma (float, default 1e-4) – Minimum sigma value.
- Returns:
Dictionary with keys like ‘4_atoms’, ‘6_atoms’, each containing ‘indices’ and ‘sigmas’ tensors.
- Return type:
dict or None
- class torchref.restraints.ChiralRestraintBuilder(ideal_volume=2.5, sigma=0.2, verbose=0)[source]
Bases:
RestraintBuilderBuilder for chiral volume restraints.
Chiral restraints define the expected handedness (R/S configuration) of tetrahedral centers. Each restraint specifies a center atom and three neighbors, with a signed ideal volume.
- _ideal_volumes
Accumulated ideal volume arrays (signed based on chirality).
- Type:
list of np.ndarray
Examples
builder = ChiralRestraintBuilder(ideal_volume=2.5, sigma=0.2) for residue in residues: builder.process_residue(residue, cif_chirals) result = builder.finalize(device) print(result['indices'].shape) # (n_chirals, 4) print(result['ideal_volumes'].shape) # (n_chirals,)
- process_residue(residue, cif_restraints)[source]
Process chiral restraints for a single residue.
- Parameters:
residue (pd.DataFrame) – Residue atoms with ‘name’ and ‘index’ columns.
cif_restraints (pd.DataFrame) – Chiral restraints with ‘atom_centre’, ‘atom1’, ‘atom2’, ‘atom3’, ‘volume_sign’ columns.
- Returns:
Number of chiral restraints added.
- Return type:
- finalize(device, sort_indices=True, min_sigma=0.0001)[source]
Convert accumulated data to sorted tensors.
- Parameters:
device (torch.device) – Target device for tensors.
sort_indices (bool, default True) – Whether to sort by first atom index.
min_sigma (float, default 1e-4) – Minimum sigma value.
- Returns:
Dictionary with ‘indices’, ‘ideal_volumes’, ‘sigmas’ tensors.
- Return type:
dict or None
- class torchref.restraints.InterResidueBondBuilder(verbose=0)[source]
Bases:
objectBuilder for inter-residue bond restraints (peptide bonds, disulfide bonds).
Unlike intra-residue builders, this handles bonds between atoms in different residues. It processes residue pairs and link definitions.
- Parameters:
verbose (int, default 0) – Verbosity level for debug output.
Examples
builder = InterResidueBondBuilder() for res_i, res_next in iterator.get_consecutive_pairs(): builder.process_peptide_bond(res_i, res_next, trans_link) result = builder.finalize(device)
- process_peptide_bond(residue_i, residue_next, link_bonds)[source]
Process peptide bond restraints between consecutive residues.
- Parameters:
residue_i (pd.DataFrame) – First residue (C-terminal of bond).
residue_next (pd.DataFrame) – Second residue (N-terminal of bond).
link_bonds (pd.DataFrame) – Bond definitions from link dictionary with columns: ‘atom_1_comp_id’, ‘atom1’, ‘atom_2_comp_id’, ‘atom2’, ‘value’, ‘sigma’.
- Returns:
Number of bond restraints added.
- Return type:
- process_disulfide_bond(sg1_idx, sg2_idx, bond_length, bond_sigma)[source]
Process a single disulfide bond restraint.
- finalize(device, sort_indices=True, min_sigma=0.0001)[source]
Convert accumulated data to sorted tensors.
- Parameters:
device (torch.device) – Target device for tensors.
sort_indices (bool, default True) – Whether to sort by first atom index.
min_sigma (float, default 1e-4) – Minimum sigma value.
- Returns:
Dictionary with ‘indices’, ‘references’, ‘sigmas’ tensors.
- Return type:
dict or None
- class torchref.restraints.InterResidueAngleBuilder(verbose=0)[source]
Bases:
objectBuilder for inter-residue angle restraints (peptide angles).
Handles angles that span two consecutive residues.
- Parameters:
verbose (int, default 0) – Verbosity level for debug output.
- process_peptide_angles(residue_i, residue_next, link_angles)[source]
Process peptide angle restraints between consecutive residues.
- Parameters:
residue_i (pd.DataFrame) – First residue.
residue_next (pd.DataFrame) – Second residue.
link_angles (pd.DataFrame) – Angle definitions from link dictionary.
- Returns:
Number of angle restraints added.
- Return type:
- process_disulfide_angles(res1_atoms, res2_atoms, link_angles)[source]
Process disulfide angle restraints.
- Parameters:
res1_atoms (pd.DataFrame) – First cysteine residue atoms.
res2_atoms (pd.DataFrame) – Second cysteine residue atoms.
link_angles (pd.DataFrame) – Angle definitions from disulfide link.
- Returns:
Number of angle restraints added.
- Return type:
- class torchref.restraints.InterResidueTorsionBuilder(verbose=0)[source]
Bases:
objectBuilder for inter-residue torsion restraints (phi, psi, omega).
Handles backbone torsion angles that span consecutive residues. Separates phi, psi, and omega angles for different treatment.
- Parameters:
verbose (int, default 0) – Verbosity level for debug output.
- process_peptide_torsions(residue_i, residue_next, link_torsions)[source]
Process backbone torsion restraints between consecutive residues.
- Parameters:
residue_i (pd.DataFrame) – First residue.
residue_next (pd.DataFrame) – Second residue.
link_torsions (pd.DataFrame) – Torsion definitions from link dictionary with ‘id’ column indicating ‘phi’, ‘psi’, or ‘omega’.
- Returns:
Number of (phi, psi, omega) torsions added.
- Return type:
- process_disulfide_torsions(res1_atoms, res2_atoms, link_torsions)[source]
Process disulfide torsion restraints.
- Parameters:
res1_atoms (pd.DataFrame) – First cysteine residue atoms.
res2_atoms (pd.DataFrame) – Second cysteine residue atoms.
link_torsions (pd.DataFrame) – Torsion definitions from disulfide link.
- Returns:
Number of torsion restraints added.
- Return type:
- class torchref.restraints.InterResiduePlaneBuilder(verbose=0)[source]
Bases:
objectBuilder for inter-residue plane restraints (peptide planes).
Handles planes that span consecutive residues (e.g., the planar peptide bond group).
- Parameters:
verbose (int, default 0) – Verbosity level for debug output.
- process_peptide_planes(residue_i, residue_next, link_planes)[source]
Process peptide plane restraints between consecutive residues.
- Parameters:
residue_i (pd.DataFrame) – First residue.
residue_next (pd.DataFrame) – Second residue.
link_planes (pd.DataFrame) – Plane definitions from link dictionary with ‘plane_id’, ‘atom_comp_id’, ‘atom’, ‘sigma’ columns.
- Returns:
Number of plane restraints added.
- Return type:
- torchref.restraints.get_library_manager(verbose=1)[source]
Get the global MonomerLibraryManager singleton.
- Parameters:
verbose (int, optional) – Verbosity level (only used on first call).
- Return type:
Submodules
- torchref.restraints.builders module
- Classes
ResidueIteratorRestraintBuilderRestraintBuilder._indicesRestraintBuilder._referencesRestraintBuilder._sigmasRestraintBuilder._countRestraintBuilder.restraint_typeRestraintBuilder.atom_columnsRestraintBuilder.n_atomsRestraintBuilder.__init__()RestraintBuilder.reset()RestraintBuilder.process_residue()RestraintBuilder.finalize()RestraintBuilder.count
BondRestraintBuilderAngleRestraintBuilderTorsionRestraintBuilderPlaneRestraintBuilderChiralRestraintBuilderChiralRestraintBuilder._ideal_volumesChiralRestraintBuilder.ideal_volumeChiralRestraintBuilder.sigmaChiralRestraintBuilder.restraint_typeChiralRestraintBuilder.atom_columnsChiralRestraintBuilder.n_atomsChiralRestraintBuilder.__init__()ChiralRestraintBuilder.reset()ChiralRestraintBuilder.process_residue()ChiralRestraintBuilder.finalize()
InterResidueBondBuilderInterResidueBondBuilder._indicesInterResidueBondBuilder._referencesInterResidueBondBuilder._sigmasInterResidueBondBuilder.__init__()InterResidueBondBuilder.reset()InterResidueBondBuilder.process_peptide_bond()InterResidueBondBuilder.process_disulfide_bond()InterResidueBondBuilder.finalize()InterResidueBondBuilder.count
InterResidueAngleBuilderInterResidueTorsionBuilderInterResidueTorsionBuilder.__init__()InterResidueTorsionBuilder.reset()InterResidueTorsionBuilder.process_peptide_torsions()InterResidueTorsionBuilder.process_disulfide_torsions()InterResidueTorsionBuilder.finalize_phi()InterResidueTorsionBuilder.finalize_psi()InterResidueTorsionBuilder.finalize_omega()InterResidueTorsionBuilder.finalize_disulfide()
InterResiduePlaneBuilder
- torchref.restraints.builders_fast module
PreprocessedPDBPreprocessedCIFRestraintBuilderBondRestraintBuilderAngleRestraintBuilderTorsionRestraintBuilderPlaneRestraintBuilderChiralRestraintBuilderbuild_all_restraints()PreprocessedLinkDataInterResidueBondBuilderInterResidueAngleBuilderInterResidueTorsionBuilderInterResiduePlaneBuilderResidueIterator
- torchref.restraints.builders_numba module
- torchref.restraints.hydrogen_topology module
HydrogenTopologyHydrogenTopology.h_parent_idxHydrogenTopology.h_bond_lengthHydrogenTopology.h_vdw_radiusHydrogenTopology.h_placement_typeHydrogenTopology.h_slot_in_parentHydrogenTopology.parent_neighbor_idxHydrogenTopology.parent_neighbor_countHydrogenTopology.h_chainid_encHydrogenTopology.h_resseqHydrogenTopology.__init__()HydrogenTopology.n_hydrogensHydrogenTopology.has_candidates
build_hydrogen_topology()place_riding_hydrogens()build_h_candidate_pairs()
- torchref.restraints.library module
- torchref.restraints.neighbor_search module
- torchref.restraints.ramachandran module
- torchref.restraints.restraints module
RestraintsNewRestraintsNew.pdbRestraintsNew.xyz_fnRestraintsNew.adp_fnRestraintsNew.vdw_radii_fnRestraintsNew.cif_dictRestraintsNew.restraintsRestraintsNew.__init__()RestraintsNew.xyz()RestraintsNew.adp()RestraintsNew.get_vdw_radii()RestraintsNew.restraintsRestraintsNew.expand_altloc()RestraintsNew.build_restraints()RestraintsNew.h_topoRestraintsNew.h_excl_hashRestraintsNew.rebuild_vdw_restraints()RestraintsNew.summary()RestraintsNew.__repr__()RestraintsNew.bond_lengths()RestraintsNew.copy()RestraintsNew.bond_deviations()RestraintsNew.nll_bonds()RestraintsNew.angles()RestraintsNew.angle_deviations()RestraintsNew.nll_angles()RestraintsNew.cat_dict()RestraintsNew.torsions()RestraintsNew.torsion_deviations()RestraintsNew.torsion_deviations_with_sigmas()RestraintsNew.nll_torsions()RestraintsNew.nll_planes()RestraintsNew.nll_vdw()RestraintsNew.adp_b_differences()RestraintsNew.adp_similarity_loss()
- torchref.restraints.restraints_helper module
validate_restraint_data()read_cif()split_respecting_quotes()find_cif_file_in_library()read_link_definitions()build_restraints_bondlength()build_restraints_angles()build_restraints_torsion()build_restraints_planes()build_restraints()calculate_restraints_bondlength()calculate_restraints_angles()calculate_restraints_torsion()calculate_restraints_all()read_for_component()read_comp_list()