Topology¶

The topology defines the static structure of the simulation system: atom types, molecule types, bonds, and how molecules are placed in the simulation cell. It does not include dynamic state such as positions or velocities.

Atoms¶

Atom types define properties shared by all atoms of the same kind. An atom need not be a chemical element — it can represent any interaction site.

atoms:
  - name: OW
    mass: 16.0
    charge: -1.0
    element: O
    sigma: 3.4
    epsilon: 1.8
    hydrophobicity: !SurfaceTension 1.0
  - name: HW
    mass: 1.0
    sigma: 1.0
    eps: 0.5

Key	Required	Default	Description
`name`	yes		Unique atom type name
`mass`	no	0	Mass (g/mol)
`charge`	no	0	Charge (elementary charges)
`element`	no		Chemical symbol (e.g., `O`, `C`, `He`)
`sigma` / `σ`	no		Lennard-Jones diameter (Å)
`epsilon` / `ε` / `eps`	no		Lennard-Jones well depth (kJ/mol)
`hydrophobicity`	no		See below
`activity`	no		Activity of an implicit reaction species (molar)
`reservoir`	no	`false`	Reservoir counter atom (see Implicit Reservoirs)
`custom`	no	`{}`	Arbitrary key-value properties

Hydrophobicity¶

Variant	Example	Description
`Hydrophobic`	`hydrophobicity: Hydrophobic`	Flag as hydrophobic
`Hydrophilic`	`hydrophobicity: Hydrophilic`	Flag as hydrophilic
`!Gamma` / `!γ` / `!SurfaceTension`	`!Gamma 1.0`	Surface energy density, γ (kJ/mol/Å²)
`!Lambda` / `!λ`	`!Lambda 0.5`	Ashbaugh-Hatch scaling factor

Molecules¶

A molecule is a collection of atoms, optionally connected by bonds, torsions, and dihedrals.

molecules:
  - name: water
    atoms: [OW, HW, HW]
    bonds:
      - {index: [0, 1], kind: !Harmonic {k: 100.0, req: 1.0}}
      - {index: [0, 2], kind: !Harmonic {k: 100.0, req: 1.0}}
    torsions:
      - {index: [1, 0, 2], kind: !Harmonic {k: 50.0, aeq: 109.47}}
    excluded_neighbours: 1
    degrees_of_freedom: Free

Key	Required	Default	Description
`name`	yes		Unique molecule type name
`atoms`	no	`[]`	List of atom type names (omit if using `from_structure`)
`from_structure`	no		Structure source: file path, inline positions, or FASTA (see below)
`bonds`	no	`[]`	Intramolecular bonds
`torsions`	no	`[]`	Three-body angle potentials
`dihedrals`	no	`[]`	Four-body dihedral potentials
`excluded_neighbours`	no	0	Exclude nonbonded interactions within n bonds
`exclusions`	no	`[]`	Manual atom pair exclusions, e.g. `[[0, 4]]`
`keep_excluded_coulomb`	no	`false`	Add back Coulomb for excluded pairs (see energy)
`degrees_of_freedom`	no	`Free`	See below
`atom_names`	no	`[]`	Per-atom names (use `null` to skip)
`residues`	no	`[]`	Protein residues
`chains`	no	`[]`	Protein chains
`activity`	no		GCMC fugacity, or the activity of an implicit species named after this molecule (molar)
`has_com`	no	`true`	Whether center-of-mass makes sense
`atomic`	no	`false`	Pool all instances into a single group (see below). Auto-set for reservoir atoms
`custom`	no	`{}`	Arbitrary key-value properties

Structure Sources (`from_structure`)¶

The from_structure field accepts multiple formats:

File path — load atom names and reference positions from a structure file (XYZ, PDB, etc.):

molecules:
  - name: MOL1
    from_structure: "cppm-p18.xyz"

Inline positions — define atoms and coordinates directly (one atom per entry):

molecules:
  - name: water
    from_structure:
      - OW: [0.0, 0.0, 0.0]
      - HW: [0.58, 0.76, 0.0]
      - HW: [-0.58, 0.76, 0.0]

FASTA sequence — build a linear peptide from a FASTA sequence with harmonic bonds (provides atom names and bonds, but no reference positions — use !RandomWalk for insertion):

molecules:
  - name: peptide
    from_structure: {sequence: "nAGGKRc", k: 80.33, req: 3.8}
    excluded_neighbours: 1

Each letter is mapped to a three-letter atom type name following IUPAC-IUB conventions, and consecutive residues are connected by harmonic bonds. The atom types must be defined in the atoms section (or an included force field file).

Uppercase letters follow the standard one-letter codes for the 20 amino acids. Additional lowercase codes:

FASTA letter	Atom type	Description
`n`	NTR	N-terminus
`c`	CTR	C-terminus
`a`	ANK	Used for anchoring

Whitespace in the sequence is ignored and * terminates parsing.

If sequence ends with .fasta, it is read as a FASTA file where header lines (>) and comment lines (;) are skipped:

molecules:
  - name: my_protein
    from_structure: {sequence: "my_protein.fasta", k: 80.33, req: 3.8}

For the CALVADOS coarse-grained model, use k: 80.33 and req: 3.8 together with the calvados3.yaml force field:

include: [calvados3.yaml]
molecules:
  - name: histatin5
    from_structure: {sequence: "DSHAKRHHGYKRKFHEKHHSHRGY", k: 80.33, req: 3.8}
    excluded_neighbours: 1
system:
  blocks:
    - molecule: histatin5
      N: 1
      insert: !RandomWalk {bond_length: 3.8}

Degrees of Freedom¶

Value	Description
`Free`	All degrees of freedom are active (default)
`Frozen`	All degrees of freedom are frozen
`Rigid`	Rigid body — only translations and rotations; all intra-molecular nonbonded pairs excluded
`RigidAlchemical`	Like `Rigid` but with free alchemical degrees of freedom (charges, etc.); use with `keep_excluded_coulomb` for titration

Atomic Molecules¶

Setting atomic: true pools all instances of a single-atom molecule into one group instead of creating one group per atom. This reduces per-group overhead and enables O(1) group-pair iteration for the energy. The molecule must have exactly one atom type and no bonds.

molecules:
  - name: Na
    atoms: [Na]
    atomic: true
  - name: Cl
    atoms: [Cl]
    atomic: true

When atomic: true:

has_com is forced to false (no center-of-mass).
GCMC inserts/deletes individual atoms within the group via expand/shrink.
TranslateAtom works as usual; TranslateMolecule is not allowed.
The N field in blocks sets the group capacity (maximum atom count).
A one-to-one reaction (A = B) is not allowed, because it is read as a molecular swap: the whole group would have to move between full and empty, and every member of an atomic kind shares one group. Reactions with explicit stoichiometry, such as 2 Na = Ca, are insertions and deletions and work.

Bonds¶

Bonds connect pairs of atoms within a molecule.

bonds:
  - {index: [0, 1], kind: !Harmonic {k: 100.0, req: 1.0}, order: Single}
  - {index: [1, 2], kind: !FENE {k: 25.0, req: 1.5, rmax: 5.0}}
  - {index: [2, 3], kind: !Morse {k: 100.0, req: 1.0, d: 10.0}}
  - {index: [3, 4]}  # unspecified kind (topology only, no energy)

Bond kind	Parameters	Description
`!Harmonic`	`k`, `req`	Harmonic spring potential
`!FENE`	`k`, `req`, `rmax`	Finitely extensible nonlinear elastic
`!Morse`	`k`, `req`, `d`	Anharmonic Morse potential
`!UreyBradley`	`k`, `req`	Urey-Bradley potential

Parameter	Unit
`k`	kJ/mol/Å²
`req`	Å
`rmax`	Å
`d`	kJ/mol

Bond order can optionally be specified: Single, Double, Triple, Aromatic, etc.

Torsions (Three-Body Angles)¶

torsions:
  - {index: [0, 1, 2], kind: !Harmonic {k: 50.0, aeq: 109.47}}
  - {index: [1, 2, 3], kind: !Cosine {k: 50.0, aeq: 45.0}}

Torsion kind	Parameters	Description
`!Harmonic`	`k`, `aeq`	Harmonic angle bending
`!Cosine`	`k`, `aeq`	Cosine form (GROMOS-96)

Parameter	Unit
`k`	kJ/mol/deg²
`aeq`	degrees

Dihedrals (Four-Body Angles)¶

dihedrals:
  - index: [0, 1, 2, 3]
    kind: !ProperHarmonic {k: 100.0, aeq: 180.0}
    electrostatic_scaling: 0.5
    lj_scaling: 0.5
  - {index: [0, 1, 2, 3], kind: !ProperPeriodic {k: 10.0, n: 3, phi: 0.0}}
  - {index: [0, 1, 2, 3], kind: !ImproperHarmonic {k: 100.0, aeq: 90.0}}

Dihedral kind	Parameters	Description
`!ProperHarmonic`	`k`, `aeq`	Proper harmonic dihedral
`!ProperPeriodic`	`k`, `n`, `phi`	Proper periodic dihedral
`!ImproperHarmonic`	`k`, `aeq`	Improper harmonic dihedral
`!ImproperPeriodic`	`k`, `n`, `phi`	Improper periodic dihedral

Parameter	Unit
`k`	kJ/mol/deg² (harmonic) or kJ/mol (periodic)
`aeq`	degrees
`n`	integer
`phi`	degrees

Optional 1-4 scaling factors: electrostatic_scaling and lj_scaling.

Residues and Chains¶

For protein structures, residues and chains describe contiguous atom ranges:

residues:
  - {name: ALA, number: 2, range: [0, 3]}
  - {name: GLY, number: 3, range: [3, 6]}
chains:
  - {name: A, range: [0, 50]}

Ranges are half-open intervals [start, end). Residues and chains must not overlap.

System¶

The system section defines the simulation cell, molecule blocks, and optionally intermolecular bonded interactions.

system:
  medium:
    permittivity: !Vacuum
    temperature: 298.15

  cell: !Cuboid [30.0, 30.0, 30.0]

  blocks:
    - {molecule: water, N: 256, insert: !RandomCOM {rotate: true}}
    - {molecule: Na, N: 10, insert: !RandomAtomPos {}}

Simulation Cell¶

The cell field selects the geometry and boundary conditions.

Cell	PBC	Parameters	Description
`!Cuboid`	XYZ	`[x, y, z]`	Orthorhombic box with side lengths x, y, z
`!HexagonalPrism`	XYZ	`{side, height}`	Hexagonal cross-section prism
`!Slit`	XY	`[x, y, z]`	Cuboidal box, hard walls in Z
`!Cylinder`	Z	`{radius, height}`	Cylindrical cell, hard walls in XY
`!Sphere`	—	`{radius}`	Spherical cell, hard walls
`!Endless`	—		Infinite, open cell

Examples:

cell: !Cuboid [30.0, 30.0, 30.0]
cell: !HexagonalPrism {side: 15.0, height: 30.0}
cell: !Cylinder {radius: 10.0, height: 50.0}

Molecule Blocks¶

Blocks specify how many copies of each molecule to create and how to initialize their positions.

Key	Required	Default	Description
`molecule`	yes		Name of the molecule type
`N`	yes		Number of molecules
`active`	no	all	Number of initially active molecules
`insert`	no		Insertion policy (see below)

Insertion Policies¶

Policy	Example	Description
`!RandomCOM`	`{rotate: true, min_distance: 2.0}`	Random center-of-mass placement
`!RandomAtomPos`	`{directions: xy}`	Random position per atom
`!FixedCOM`	`{position: [0, 0, 0]}`	Place at specific position
`!FromFile`	`structure.xyz`	Read all positions from file
`!Manual`	`[[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]`	Explicit coordinates for all atoms
`!RandomWalk`	`{bond_length: 3.8}`	Self-avoiding walk; respects cell boundaries
`!GridCOM`	`{rotate: true}`	Simple cubic grid; cuboidal cells only

The directions field controls which axes are randomized: xyz (default), xy, xz, yz, x, y, or z. !RandomCOM, !FixedCOM, and !GridCOM use reference positions from the molecule's from_structure field. The optional min_distance field (Å) in !RandomCOM uses bounding sphere rejection to avoid molecular overlaps in dense systems. !GridCOM places molecules on a simple cubic lattice with auto-calculated spacing; requires !Cuboid or !Slit cells.

Intermolecular Bonded Interactions¶

Bonds, torsions, and dihedrals between atoms in different molecules use global atom indices:

system:
  intermolecular:
    bonds:
      - {index: [0, 220], kind: !Harmonic {k: 50.0, req: 3.0}}
    torsions:
      - {index: [1, 75, 128], kind: !Harmonic {k: 100.0, aeq: 120.0}}
    dihedrals:
      - {index: [1, 35, 75, 128], kind: !ProperHarmonic {k: 27.5, aeq: 105.0}}

Including Files¶

Topology files can include other YAML files. Paths are relative to the including file. Definitions in later files take precedence; definitions in the main file take precedence over all includes.

include: [forcefield.yaml, overrides.yaml]

Implicit Reservoirs¶

Reservoir counter atoms (reservoir: true) represent a finite amount of substance in another phase (e.g., a solid) that is never spatially represented in the simulation cell. A molecule containing a reservoir atom automatically becomes a pooled atomic group whose active count tracks the reservoir size.

This is distinct from activity (infinite bath at fixed chemical potential). Reservoirs have a finite, fluctuating count driven by speciation reactions, and the entropy bias is excluded entirely (solid activity = 1). A molecule cannot have both reservoir and activity. State persistence is automatic via group sizes.

Example: Ca(OH)₂ solubility (\(K_{sp} = 10^{-5.19}\)):

atoms:
  - {name: ca(oh)₂, mass: 0.0,  reservoir: true} # <-- this is a reservoir!
  - {name: ca²⁺,    mass: 40.0, charge: 2.0}
  - {name: oh⁻,     mass: 17.0, charge: -1.0}
molecules:
  - {name: Ca(OH)₂, atoms: [ca(oh)₂]} # auto implicit; never in simulation cell
  - {name: Ca²⁺,    atoms: [ca²⁺], atomic: true}
  - {name: OH⁻,     atoms: [oh⁻],  atomic: true}
system:
  blocks:
    - {molecule: Ca(OH)₂, N: 400} # finite reservoir; solid phase
    - {molecule: Ca²⁺, N: 800, active: 0, insert: !RandomAtomPos {}}
    - {molecule: OH⁻,  N: 800, active: 0, insert: !RandomAtomPos {}}

With the speciation move:

reactions:
  - ["Ca(OH)₂ = Ca²⁺ + OH⁻ + OH⁻", !pK 5.19]

At equilibrium: \([Ca^{2+}] \approx 0.012\;\text{M}\), \([OH^-] \approx 0.023\;\text{M}\).

Chemical Reactions¶

Chemical reactions are used for speciation moves in the grand canonical and semi-grand canonical ensembles. A participant is either an atom, a molecule, or an implicit participant. When parsing a reaction, atoms are prefixed with a dot or an atom sign, e.g. .Na or ⚛Na. Implicit participants are prefixed with a tilde or a ghost, e.g. ~H or 👻H. Molecules are not prefixed, e.g. Cl.

Participant	Example	Notes
Molecular	`A + A ⇌ D`	Possible arrows: `=`, `⇌`, `⇄`, `→`
Implicit	`RCOO- + 👻H+ ⇌ RCOOH`	Mark with `👻` or `~`
Atomic	`⚛Pb ⇄ ⚛Au`	Mark with `⚛` or `.`

An implicit participant takes its activity from the activity field of the atom type of that name, or, if no atom type carries it, of the molecule type — so an implicit molecular reservoir such as ~H2O is legal.

When a reaction has one molecular reactant and one molecular product with equal atom counts (e.g. A = B + ~H+), it is treated as a molecular swap: the source group is deactivated and a target group is activated with aligned positions. Both types must be non-atomic, and their intramolecular energy is left out of \(\Delta U\) (see Molecular swaps) — so if the two states differ in it, add exclusions covering their intramolecular pairs. Unicode names are supported in reactions and molecule definitions.

The following are rejected when the reaction is parsed, rather than silently sampled as a different reaction: an atom or molecule name matching no type; unbalanced atom stoichiometry, e.g. ⚛A + ⚛A = ⚛B; an equilibrium constant that is not positive and finite; and a reaction naming a molecule for which no blocks: entry allocates groups.