xnn.ffnn.models.topology.MolecularTopology#

class xnn.ffnn.models.topology.MolecularTopology(types, bonds, bond_orders=<factory>, angles=<factory>, dihedrals=<factory>, impropers=<factory>, improper_keys=<factory>, exclusions=<factory>, pairs14=<factory>)[source]#

Bases: object

Atom types and fixed valence connectivity for one structure.

Build instances with from_bonds() (which derives angles, proper dihedrals, exclusions and 1,4 pairs from the bond list) rather than by filling every field manually.

Parameters and attributes#

typeslist[str]

Per-atom type names (e.g. "opls_135"), length n_atoms.

bondslist[tuple[int, int]]

Bonds as (i, j) with i < j.

bond_orderslist[float]

Bond order per entry of bonds (1, 1.5, 2, 3); empty means all single bonds. Only rule-generated force fields (DREIDING) consume these; OPLS ignores them.

angleslist[tuple[int, int, int]]

Angles (i, j, k) with center j and i < k.

dihedralslist[tuple[int, int, int, int]]

Proper dihedrals (i, j, k, l) around the central bond j-k.

improperslist[tuple[int, int, int, int]]

Improper dihedrals, evaluated with the same four-atom dihedral angle as propers over the atoms in the order given.

improper_keyslist[str]

Improper type key per entry of impropers (e.g. "Z-CM-X-Y"), resolved by the consuming force field.

exclusionslist[tuple[int, int]]

Nonbonded exclusions: all 1,2 and 1,3 pairs, i < j.

pairs14list[tuple[int, int]]

1,4 pairs (dihedral end atoms, minus any that are also 1,2 or 1,3 pairs in rings), i < j; the force field scales these.

property n_atoms: int#

Number of atoms in the topology.

Type:

int

classmethod from_bonds(types, bonds, impropers=(), improper_keys=(), bond_orders=None)[source]#

Build a topology from atom types and a bond list.

Angles are every unordered pair of bonded neighbors of a common center; proper dihedrals are enumerated once around every bond; exclusions are the 1,2 and 1,3 pairs; 1,4 pairs are the dihedral end atoms that are not themselves 1,2 or 1,3 pairs (each pair counted once, so fused rings are handled correctly).

Parameters:

  • types (sequence of str) – Per-atom type names.

  • bonds (sequence of (int, int)) – Bonded atom index pairs (order within a pair does not matter).

  • impropers (sequence of (int, int, int, int), optional) – Improper dihedrals, in evaluation order.

  • improper_keys (sequence of str, optional) – Exact improper type key per improper (same length as impropers). Leave empty to let the force field resolve each improper from the classes of its atoms (center third).

  • bond_orders (sequence of float, optional) – Bond order per entry of bonds (1, 1.5, 2, 3), in the input bond order; omitted means all single bonds.

Returns:

The completed topology.

Return type:

MolecularTopology

Raises:

ValueError – If a bond index is out of range, a bond is duplicated or joins an atom to itself, impropers and improper_keys disagree in length, or bond_orders does not match bonds.

classmethod from_ase(atoms, types=None, bonds=None, scale=1.2, impropers=(), improper_keys=(), *, forcefield=None, charge=0, bond_orders=None)[source]#

Build a topology for an ASE Atoms object.

Parameters:

  • atoms (ase.Atoms) – The structure (used for positions, atomic numbers, and the cell when bonds are guessed).

  • types (sequence of str, optional) – Per-atom type names, in atoms order. When omitted, forcefield must be given and the types are assigned from its SMARTS templates (assign_atom_types()).

  • bonds (sequence of (int, int), optional) – Explicit bond list; when omitted, bonds are perceived by RDKit together with the typing when forcefield is given, else guessed from covalent radii with guess_bonds().

  • scale (float, optional) – Covalent-radius multiplier for bond guessing, by default 1.2.

  • impropers (sequence, optional) – Improper dihedrals and their type keys (see from_bonds()).

  • improper_keys (sequence, optional) – Improper dihedrals and their type keys (see from_bonds()).

  • forcefield (ForceField, OPLSLibrary or str, optional) – Source of typing templates (a resolved force field, a library read from a .frc file, or a spec such as "oplsaa").

  • charge (int, optional) – Total charge, for bond-order perception.

  • bond_orders (Sequence[float] | None)

Returns:

The completed topology.

Return type:

MolecularTopology

Raises:

ValueError – If types does not match the number of atoms, or neither types nor forcefield is given.

replicate(n_copies)[source]#

Tile this topology into n_copies consecutive molecules.

Atom a of copy c becomes atom c * n_atoms + a; this matches the atom ordering of ase.Atoms multiplication and of packing tools that concatenate whole molecules.

Parameters:

n_copies (int) – Number of copies (>= 1).

Returns:

The tiled topology.

Return type:

MolecularTopology

save(path)[source]#

Write the topology as JSON (round-tripped by read_topology()).

Parameters:

path (str or Path) – Output file path.

Return type:

None

Parameters: