Skip to content
mlx-atomistic

Real Molecular Mechanics Core

This milestone adds the first system-level molecular mechanics layer. The engine can now represent typed systems, assign force-field parameters, run a combined LJ+Coulomb nonbonded path, apply pair-distance constraints, and save/load simple structures and trajectories.

Systems And Parameters

Section titled “Systems And Parameters”

MMSystem stores the molecular state:

symbols, atom_names, atom_types
masses, charges
positions, velocities
topology, optional cell

ForceField assigns parameters from atom types:

  • AtomType
  • NonbondedParameter
  • BondParameter
  • AngleParameter
  • DihedralParameter

Bond parameters match atom-type pairs without order sensitivity. Angle and dihedral parameters match forward or reverse type tuples. Missing parameters raise errors with atom indices and type tuples so mistakes are visible.

Production Nonbonded Path

Section titled “Production Nonbonded Path”

NonbondedPotential combines Lennard-Jones and direct Coulomb terms in one pair loop. It supports:

  • per-atom σ, ε, and charge
  • Lorentz-Berthelot mixing
  • topology exclusions
  • independent LJ and Coulomb 1-4 scaling
  • cutoff and minimum-image behavior
  • optional LJ and Coulomb energy shifts

NVE/NVT diagnostics record component terms as:

nonbonded.lj
nonbonded.coulomb

This gives a realistic target for the future custom Metal pair kernel.

Constraints

Section titled “Constraints”

DistanceConstraints supports fixed pair distances. The current implementation uses iterative position projection and velocity projection:

  • position correction after position updates
  • velocity correction after force/velocity updates
  • dense constraint_max_error diagnostics for every step

This is intentionally limited to pair-distance constraints. It is enough for water-like toy systems and for measuring constraint overhead.

I/O

Section titled “I/O”

The I/O layer is deliberately small:

  • read_xyz(...)
  • write_xyz(...)
  • save_npz_trajectory(...)
  • load_npz_trajectory(...)
  • restart_state_from_trajectory(...)

XYZ is for quick structure interchange. NPZ is the native trajectory format and stores sampled frames, scalar diagnostics, energy decomposition, optional cell, symbols, and JSON metadata.

Examples

Section titled “Examples”

Programmatic examples now include:

  • water-like constrained molecule
  • butane-like torsion system
  • small ionic cluster
  • mixed typed LJ fluid

The notebook notebooks/workflows/01-md-molecular-mechanics.ipynb demonstrates the active MM workflow: system construction, force-field assignment, constraints, trajectory diagnostics, and energy decomposition.

Remaining Boundaries

Section titled “Remaining Boundaries”

Still out of scope:

  • unrestricted PME/Ewald production coverage beyond the accepted artifact gate
  • mature production NPT/barostat certification
  • unrestricted AMBER/CHARMM/GROMACS parsing beyond the accepted native subsets
  • DFT
  • custom Metal kernels

The next optimization decision should be based on benchmark evidence from the combined nonbonded and constraint paths.