torchref.restraints.restraints_helper module

torchref.restraints.restraints_helper.validate_restraint_data(residue_data, cif_path)[source]

Validate that the CIF file contains actual restraint parameters.

Parameters:

  • residue_data (dict) – Dictionary of residue restraint data from CIF file.

  • cif_path (str or Path) – Path to the CIF file being validated.

Raises:

ValueError – If the file doesn’t contain proper restraint data.

torchref.restraints.restraints_helper.read_cif(cif_path)[source]

Read restraint CIF file using the new RestraintCIFReader.

Returns dictionary with standardized keys for compatibility with restraints.py.

Parameters:

cif_path (str or Path) – Path to restraint CIF file.

Returns:

Dictionary mapping compound IDs to restraint data with standardized keys:

{
    'comp_id': {
        'bond': DataFrame with bond restraints,
        'angle': DataFrame with angle restraints,
        'torsion': DataFrame with torsion restraints,
        'plane': DataFrame with planarity restraints,
        'chiral': DataFrame with chirality definitions,
        'atom': DataFrame with atom definitions
    }
}

Return type:

dict

torchref.restraints.restraints_helper.split_respecting_quotes(line)[source]

Split a line by whitespace, but preserve quoted strings intact.

Handles both single and double quotes.

Parameters:

line (str) – Input line to split.

Returns:

List of tokens split by whitespace, with quoted strings preserved.

Return type:

list of str

torchref.restraints.restraints_helper.find_cif_file_in_library(resname)[source]

Find a CIF file in the monomer library based on residue name.

Resolves files using the MonomerLibraryManager priority chain: environment variable > bundled package data > user cache > legacy external_monomer_library > on-demand download.

Parameters:

resname (str) – Residue name (e.g., ‘ALA’, ‘GLY’, ‘ATP’).

Returns:

Path object pointing to the CIF file, or None if not found.

Return type:

Path or None

Read link definitions from mon_lib_list.cif.

Returns:

A tuple of (link_dict, link_list) where:

  • link_dictdict

    Dictionary where keys are link IDs (e.g., ‘TRANS’, ‘CIS’) and values are dictionaries containing:

    • ’bonds’: DataFrame of inter-residue bonds

    • ’angles’: DataFrame of inter-residue angles

    • ’torsions’: DataFrame of inter-residue torsions

  • link_listDataFrame

    DataFrame containing the list of all link definitions.

Return type:

tuple

torchref.restraints.restraints_helper.build_restraints_bondlength(cif, pdb)[source]

Build bond length restraints from CIF dictionary and PDB DataFrame.

Parameters:

  • cif (dict) – CIF dictionary containing bond restraint definitions.

  • pdb (pandas.DataFrame) – PDB DataFrame with atomic coordinates.

Returns:

List containing [column1, column2, references, sigmas] tensors.

Return type:

list

torchref.restraints.restraints_helper.build_restraints_angles(cif, pdb)[source]

Build angle restraints from CIF dictionary and PDB DataFrame.

Parameters:

  • cif (dict) – CIF dictionary containing angle restraint definitions.

  • pdb (pandas.DataFrame) – PDB DataFrame with atomic coordinates.

Returns:

List containing [column1, column2, column3, references, sigmas] tensors.

Return type:

list

torchref.restraints.restraints_helper.build_restraints_torsion(cif, pdb)[source]

Build torsion angle restraints from CIF dictionary and PDB DataFrame.

Parameters:

  • cif (dict) – CIF dictionary containing torsion restraint definitions.

  • pdb (pandas.DataFrame) – PDB DataFrame with atomic coordinates.

Returns:

List containing [column1, column2, column3, column4, references, sigmas] tensors.

Return type:

list

torchref.restraints.restraints_helper.build_restraints_planes(cif, pdb)[source]

Build planarity restraints from CIF dictionary and PDB DataFrame.

Parameters:

  • cif (dict) – CIF dictionary containing plane restraint definitions.

  • pdb (pandas.DataFrame) – PDB DataFrame with atomic coordinates.

Returns:

List containing [column1, plane_numbers, sigmas] tensors.

Return type:

list

torchref.restraints.restraints_helper.build_restraints(cif, pdb)[source]

Build all restraints from CIF dictionary and PDB DataFrame.

Parameters:

  • cif (dict) – CIF dictionary containing restraint definitions.

  • pdb (pandas.DataFrame) – PDB DataFrame with atomic coordinates.

Returns:

Dictionary with keys ‘bondlength’, ‘angles’, ‘torsion’, ‘planes’ containing the respective restraint data.

Return type:

dict

torchref.restraints.restraints_helper.calculate_restraints_bondlength(xyz, restraints_bondlength)[source]

Calculate bond length restraint energy.

Parameters:

  • xyz (torch.Tensor) – Atomic coordinates tensor of shape (N, 3).

  • restraints_bondlength (list) – List containing [column1, column2, reference, sigma] tensors.

Returns:

Total bond length restraint energy.

Return type:

torch.Tensor

torchref.restraints.restraints_helper.calculate_restraints_angles(xyz, restraints_angles)[source]

Calculate angle restraint energy.

Parameters:

  • xyz (torch.Tensor) – Atomic coordinates tensor of shape (N, 3).

  • restraints_angles (list) – List containing [column1, column2, column3, reference, sigma] tensors.

Returns:

Total angle restraint energy.

Return type:

torch.Tensor

torchref.restraints.restraints_helper.calculate_restraints_torsion(xyz, restraints_torsion)[source]

Calculate torsion angle restraint energy.

Parameters:

  • xyz (torch.Tensor) – Atomic coordinates tensor of shape (N, 3).

  • restraints_torsion (list) – List containing [column1, column2, column3, column4, reference, sigma] tensors.

Returns:

Total torsion angle restraint energy.

Return type:

torch.Tensor

torchref.restraints.restraints_helper.calculate_restraints_all(xyz, restraints)[source]

Calculate total restraint energy for all restraint types.

Parameters:

  • xyz (torch.Tensor) – Atomic coordinates tensor of shape (N, 3).

  • restraints (dict) – Dictionary containing ‘bondlength’, ‘angles’, and ‘torsion’ restraints.

Returns:

Total restraint energy (sum of bondlength, angles, and torsion energies).

Return type:

torch.Tensor

torchref.restraints.restraints_helper.read_for_component(lines, comp_id)[source]

Read CIF data for a specific component/compound ID.

Parameters:

  • lines (list of str) – Lines from CIF file.

  • comp_id (str) – Component ID to search for.

Returns:

Dictionary of DataFrames for different data types, or None if not found.

Return type:

dict or None

torchref.restraints.restraints_helper.read_comp_list(lines)[source]

Read the compound list from CIF file lines.

Parameters:

lines (list of str) – Lines from CIF file.

Returns:

DataFrame with compound list data, or None if not found.

Return type:

pandas.DataFrame or None