Glossary

Glossary¶

Quick definitions for MolPy's core terminology. Each entry links to the page that covers the concept in depth.

Data structures¶

Atomistic: An editable molecular graph where atoms are nodes and bonds are edges. Use it when the structure is still under construction — adding atoms, removing leaving groups, querying neighbors. See Atomistic and Topology.
NodeRef: A live handle onto one graph node (mp.NodeRef); Atom and Bead are node views. Dictionary-like: read and write properties with bracket notation. Hashing is by identity, not by value.
Atom: A node view representing one atom. Carries arbitrary key-value properties (element, charge, type, etc.).
Bead: A node view representing one coarse-grained site.
RelationRef: A live handle onto one topology connection (mp.RelationRef). Holds an ordered tuple of node endpoints. Relation views: Bond, Angle, Dihedral, Improper.
Graph: Native base class (mp.Graph) holding nodes, relations and ports. Atomistic and CoarseGrain derive from it; molpy re-exports all three by identity.
Topology: Bonded terms derived from an Atomistic's bond graph by the native kernels. generate_topology(gen_angle=..., gen_dihedral=...) perceives angles and dihedrals in place and returns the counts it added (use .copy() first when you need an independent graph); topo_distances(handle, max_hops=...) answers bond-graph distance queries. On the tabular side, mp.Topology.from_frame(frame) reads a Frame's bonds, for example connected_components() to number its molecules. See Atomistic and Topology.
Block: A columnar table mapping string keys to NumPy arrays. All columns share the same row count. Used inside Frame to store atoms, bonds, angles, etc. See Block and Frame.
Frame: A named collection of Block objects plus an optional simulation box and dict-like meta. Represents one complete system snapshot. The universal exchange object for I/O. See Block and Frame.
Box: A simulation cell defined by a 3x3 lattice matrix and periodic boundary conditions. Provides wrapping, minimum-image distances, and coordinate conversion. See Box and Periodicity.
Trajectory: An ordered sequence of Frame objects. Supports lazy access via generators and map transforms. See Trajectory.

Force field¶

ForceField: A container that holds all styles, types, and parameters for a molecular system. Created manually or loaded from XML/LAMMPS/AMBER files.
Style: An interaction family within a force field — for example, harmonic bonds or lj/cut pairs — defined with ff.def_style(category, name). Subclasses: AtomStyle, BondStyle, AngleStyle, DihedralStyle, ImproperStyle, PairStyle.
Type: One concrete parameter record within a style, defined with style.def_type(name, *endpoints, **params). For example, a bond type CT-OH between the atom types CT and OH with k=320.0 and r0=1.41. Subclasses: AtomType, BondType, AngleType, DihedralType, ImproperType, PairType.
Potential: The numerical realization of a force field's styles and types, ready for energy/force computation. Produced by mp.PotentialCompiler(ff).compile(frame) (or .defer() for a Potentials bound later) and evaluated against a typed Frame via pots.calc_energy(frame) / pots.calc_forces(frame); the kernels run in the high-performance backend. See Force Field.

Modules¶

Parsing: mp.SmilesIR and mp.SmartsPattern convert SMILES and SMARTS strings into MolPy structures; CGSmilesIR parses CGsmiles into ported units and site graphs. BigSMILES is not parsed. See Parsing Chemistry.
Reaction: A reaction SMARTS. It matches the reactant patterns, forms and breaks bonds, and deletes the atoms that appear on the left and not on the right (the leaving groups). See Parser.
Assembler: mp.Assembler(library, placer, orienter=None) builds one world from a site graph: one copy of library[bead_type] per site, each site bond joining one accepting port of each end. Every atom gets frag_id (its site's ordinal) and mol_id (its connected component, from 1). See Assembly.
Port: A place where a unit may bond: an (anchor, handle) pair, where the handle is a real atom bonded to the anchor (usually the capping hydrogen) that leaves when the bond forms. Its kind decides its partner — < joins >, $ joins $, ! joins ! — and a label and bond order must match. In CGsmiles, ports are the bonding descriptors ([<]OCC[>]).
Site graph: The topology of an assembly: an mp.CoarseGrain whose beads name library units (bead_type) and whose bonds say which units join. It comes from CGsmiles notation (CGSmilesIR(...).to_coarsegrain()) or from coarsening a CG model (Coarsener), in which case each site also has a position and an axis.
Placer: The assembler's rule for each copy's pose. GrowthPlacer grows each molecule onto its parents' ports and needs no coordinates; SitePlacer puts each copy's centre of mass on its site.
Orienter: The optional rule that turns each copy before it is placed. AxisOrienter aligns a unit with its site's axis and bonds; it needs site positions.
Typifier: Assigns force field types to atoms, bonds, angles, and dihedrals: implements match, and the base's typify returns a typed copy while forcefield() accumulates the assigned types. Native: OPLSAATypifier, MMFF94Typifier, MMFF94STypifier, ElementTypifier. GAFF / GAFF2 through AmberTools: AntechamberTypifier, TLeapTypifier (see AmberTools Integration). See Force Field Typification.
Selector: A composable predicate that filters atoms in a Block by element, type, coordinate range, or distance. Combinable with &, |, ~. See Selector.
Wrapper: Runs an external executable (antechamber, tleap, …) as a subprocess and captures its results. Crosses an execution boundary. Packing uses molpack in-process, not a wrapper. See Wrapper and Adapter.
Adapter: Translates between MolPy objects and another library's in-memory objects (RDKit, OpenBabel). Crosses a representation boundary. See Wrapper and Adapter.

Naming conventions¶

atomi / atomj / atomk / atoml: Integer atom indices used in Frame and Block (the data-interchange layer). Always 0-based. Never store object references.
itom / jtom, endpoints: Atom views on graph-level topology: bond.itom / bond.jtom are a bond's two atoms, and every relation (Bond, Angle, Dihedral, Improper) lists its atoms in order as .endpoints. They are views, never integers. See Naming Conventions.

Compute terminology¶

Acronyms used across the Compute analyses.

RDF — radial distribution function g(r): Probability of finding a neighbour at distance r relative to an ideal gas. See RDF.
MSD — mean-squared displacement: ⟨|r(t) − r(0)|²⟩; its slope gives the self-diffusion coefficient. See MSD.
VACF — velocity autocorrelation function: ⟨v(0)·v(t)⟩; its integral (Green–Kubo) gives diffusion, its FFT gives the VDOS. See VACF.
VDOS — vibrational density of states: Spectral density of atomic motion, ∝ FFT[VACF]. See VACF.
MCD — mean-displacement correlation (distinct diffusion): Cross-correlated displacements between different species — the distinct part of diffusion, beyond the single-particle MSD. See MSD.
PMSD — polarization / charge-dipole mean-squared displacement: MSD of $\mathbf{M}(t)=\sum q_a\mathbf{r}_a$ (unwrapped); raw curve from EinsteinConductivity. Fit $\sigma$ with LinearFit + SI scale. See MSD.
Current ACF — $\langle\mathbf{J}(0)\cdot\mathbf{J}(t)\rangle$: From GreenKuboConductivity with $\mathbf{J}=\sum q\mathbf{v}$. Integrate with CumulativeTrapezoid then SI-scale for $\sigma$.
SDF — spatial distribution function: Three-dimensional density of neighbours around a reference frame (angular structure, not just radial). See Distribution.
CDF — combined distribution function: A joint histogram over two geometric observables (e.g. distance × angle). See Distribution.
PMFT — potential of mean force and torque: Free energy −k_BT ln g over relative position/orientation coordinates. See Distribution.
ROA / VCD — Raman optical activity / vibrational circular dichroism: Chiroptical vibrational spectra derived from correlation functions of the polarizability / magnetic-dipole responses. See Spectra.