Models

The models module provides a single entry point for building the TOPO coarse-grained system: buildCoarseGrainModel(). It reads a structure, keeps the alpha-carbon atoms, and assembles the full force field (bonds, angles, periodic torsions, Yukawa electrostatics, and the structure-based contact potential), returning a topo.core.system.system object ready to simulate.

Note

The complete force-field theory — every energy term, its functional form, all constants, and where the parameters come from — lives in The TOPO model: theory and force field. For programmatic use (arguments, the returned object’s attributes and methods) see Using TOPO from Python. This page is a short summary plus the autodoc reference.

Coarse-grained alpha-carbon (CA) model

TOPO represents the protein as one bead per residue, centred on the alpha carbon. The Hamiltonian is

\[U_\mathrm{total} = \sum_\mathrm{bonds} U_\mathrm{bond} + \sum_\mathrm{angles} U_\mathrm{angle} + \sum_\mathrm{torsions} U_\mathrm{torsion} + \sum_{i<j} U^\mathrm{el}_{ij} + \sum_{i<j} U^\mathrm{nb}_{ij}\]

with the terms summarised below (full details and constants: The TOPO model: theory and force field).

Bonds. Rigid distance constraints at \(r_0 = 0.381\) nm by default (constraints = AllBonds); or, with constraints = None, a harmonic force \(U_\mathrm{bond} = \tfrac12 k_b (r-r_0)^2\), \(k_b = 20920\ \mathrm{kJ\,mol^{-1}\,nm^{-2}}\).

Angles (bimodal Gaussian).

\[U_\mathrm{angle}(\theta) = -\frac{1}{\gamma} \ln\!\Big[ e^{-\gamma[\,k_\alpha (\theta-\theta_\alpha)^2 + \varepsilon_\alpha\,]} + e^{-\gamma k_\beta (\theta-\theta_\beta)^2} \Big]\]

with two basins at \(\theta_\alpha = 91.7^\circ\) and \(\theta_\beta = 130.0^\circ\).

Torsions (periodic, sequence-dependent). A standard periodic torsion with four periodicities,

\[U_\mathrm{torsion}(\varphi) = \sum_{n=1}^{4} k_{D,n}\,\big[\,1 + \cos(n\varphi - \delta_n)\,\big],\]

where \(k_{D,n}\) and \(\delta_n\) depend on the two central residues of the dihedral (table topo/parameters/data/dihedral_params.csv, scaled by 0.756). This is implemented by addPeriodicTorsionForce().

Electrostatics (Debye–Hückel / Yukawa).

\[U^\mathrm{el}_{ij}(r) = f\,\frac{q_i q_j}{\varepsilon_r\, r}\, e^{-r/l_D}\]

with \(f = 138.935458\), \(\varepsilon_r = 78.5\), \(l_D = 1.0\) nm, a 2.0 nm cutoff and switching at 1.8 nm. Only ASP/GLU (−1) and ARG/LYS (+1) carry charge.

Structure-based contacts (12-10-6).

\[U^\mathrm{nb}_{ij}(r) = \varepsilon_{ij} \Big[\,13(R_{ij}/r)^{12} - 18(R_{ij}/r)^{10} + 4(R_{ij}/r)^{6}\,\Big]\]

with the well minimum \(-\varepsilon_{ij}\) at \(r = R_{ij}\). For native contacts \(R_{ij}\) is the native Cα–Cα distance and \(\varepsilon_{ij}\) sums hydrogen-bond (STRIDE), backbone–sidechain, and (domain-scaled) sidechain–sidechain energies; non-native pairs get a soft excluded-volume repulsion. Built by topo.utils.nonbonded.build_nonbonded_interaction(); see Structure-based contacts — the heart of the model.

Non-bonded exclusions. Pairs two or fewer bonds apart (1–2 bonded and 1–3 angle neighbours) are excluded from both non-bonded forces (bonded_exclusions_index = 2).

API reference

class topo.core.models.models[source]

A class to hold functions for the automated generation of default TOPO models.

static buildCoarseGrainModel(structure_file: str, minimize: bool = False, model: str = 'topo', domain_def: str | None = None, stride_output_file: str | None = None, box_dimension: Any | None = None, constraints: Any = 'AllBonds', check_forces: bool = True)[source]

Build a topology-based coarse-grained model for a folded protein system.

Creates an alpha-carbon only system with bonds, angles, periodic torsions, Yukawa electrostatics, and structure-based (contact) non-bonded interactions. Optionally uses domain definitions and STRIDE output for contact-based potentials.

Parameters:

  • structure_file (str) – Path to the input structure file (PDB/CIF).

  • minimize (bool, optional (default: False)) – If True, run energy minimization on the initial structure.

  • model (str, optional (default: 'topo')) – Model name; currently only ‘topo’ is supported.

  • domain_def (str, optional) – Path to domain definition file (e.g. domain.yaml) for contact-based non-bonded.

  • stride_output_file (str, optional) – Path to STRIDE output file for secondary structure.

  • box_dimension (float or array, optional) – If set, use PBC (cubic if float, rectangular if [x,y,z]).

  • constraints (str or None, optional (default: 'AllBonds')) –

    Controls the treatment of covalent bonds. These two modes are mutually exclusive (a bond is never both constrained and harmonic):

    • ’AllBonds’ : rigid bonds. A distance constraint is added at each bond’s equilibrium length and no harmonic bond force is created.

    • None (or the string ‘None’/’none’) : flexible bonds. A harmonic bond force is created and no constraints are added.

  • check_forces (bool, optional (default: True)) – If True, run the build-time energy/large-force check on the initial input structure. Set False when restarting from a checkpoint, where the input-structure energy is irrelevant (the loaded state, not the PDB geometry, is what gets simulated).

Returns:

topo_model – Initialized coarse-grained system ready for simulation.

Return type:

topo.core.system