Skip to content

Integrators

integrators

Graph-capturable MD integrators over SimulationState and a ForceField (SPEC §10).

This package's namespace is fm.integrators: the public integrator records (plan task 1b-T01), which a Simulation takes as integrator= and which map onto IntegratorConfig. The implementations (langevin.py, baoab.py) are built from that config by the planner only (SPEC §5); importing this package imports neither them nor torch.

Units at the API (SPEC §7.3): fs, K, GPa and friction per fs. IntegratorConfig.friction is in inverse ASE time units, as in main.py; to_config converts (friction_per_fs / units.fs).

Phase 4 (plan task 4-T01, conductor's choice 1) adds the records of the new schemes: NVE, CSVR, NoseHooverChain, MTK and Berendsen. Their scheme settings travel in IntegratorConfig.parameters in the record's units (fs, K, GPa); the implementations (4-T02, 4-T03) convert. Time constants have no defaults, as in ASE: physics is never chosen silently. A record whose scheme is not registered yet plans to a scheme-unknown refusal (rule 1).

fixcm of the schemes that take FixAtoms (Langevin, NVE, CSVR, Berendsen; plan task 4-T04) defaults to "auto": off when the structure has fixed atoms, which pin the frame already, on otherwise. to_config resolves it from fixed_atoms (the Simulation passes whether its Atoms carry FixAtoms); an explicit fixcm=True with fixed atoms is refused by rule 1 (owner decision 44).

Langevin dataclass

Langevin NVT, ASE's Langevin on the graph engine (SPEC §10.2).

fm.integrators.Langevin(timestep_fs=0.5, temperature_K=300, friction_per_fs=0.002) (about fm.md's friction, quick.default_friction_per_fs). temperature_K is the starting target; a schedule (Simulation.run(schedule=…)) moves it. fixcm_projection is how fixcm projects the noise (IntegratorConfig.fixcm_projection; docs/design/fixcm-projection.md): "ase", ASE's, "mass_weighted", canonical at a fixed centre of mass for unequal masses too, or "auto", the planner's choice ("mass_weighted" under fixcm, for MD as for MC (decision 37), else "ase"). fixcm: "auto" (off with FixAtoms, on otherwise), True or False.

to_config 

to_config(
    *, seed: int, fixed_atoms: bool = False
) -> IntegratorConfig

The IntegratorConfig of this record with seed (the Simulation's); fixed_atoms: whether the structure has FixAtoms (fixcm="auto").

LangevinBAOAB dataclass

Langevin-Hoover NPT, ASE 3.27's LangevinBAOAB on the graph engine (SPEC §10.2).

  • friction_per_fs: the thermostat friction; ASE's T_tau is 1 / friction, as in main.py (workflow.baoab_settings);
  • pressure_GPa or external_stress_GPa (ASE's externalstress sign: a scalar or six Voigt components), not both;
  • cell_mode: "hydrostatic" (ASE hydrostatic=True) or "full";
  • barostat_tau_fs: ASE's P_tau, None = ASE's default 20 T_tau;
  • barostat_mass_factor: ASE's P_mass_factor;
  • disable_cell_langevin: as ASE;
  • max_volume_ratio and max_cell_length_A: the cell-divergence stop (3b-T07). A Simulation stops with CellDivergedError (restart and metadata written first) once the volume leaves [V0 / ratio, V0 ratio], V0 the run's starting volume, or a cell vector is longer than max_cell_length_A (1000 Å: float32 coordinates still resolve 6e-5 Å there). A vapour at a low pressure expands without bound otherwise, until the coordinates lose their precision. None turns a limit off;
  • fixcm: False only. BAOAB, as ASE's, never removes the total momentum, so the record does not claim a fixed centre of mass (MC velocity treatments and refusals follow it).

The production drag term is the corrected one (SPEC §12.1, 1b-T09); ASE's own variant stays an IntegratorConfig option for comparisons with ASE.

to_config 

to_config(
    *, seed: int, fixed_atoms: bool = False
) -> IntegratorConfig

The IntegratorConfig of this record with seed (the Simulation's). fixed_atoms is accepted as by every record; rule 1 refuses FixAtoms with a variable cell.

NVE dataclass

Velocity Verlet, ASE's VelocityVerlet on the graph engine (SPEC §10.2; 4-T02).

fixcm: remove the total momentum at the start and project it out each step (owner decision D2); "auto" turns it off with FixAtoms. dof: "auto" (3N - 3 under fixcm, 3(N - n_fixed) with FixAtoms; the same as "fastmace") or "ase" (ASE's count), for the reported temperature. The conserved quantity is E_kin + E_pot.

to_config 

to_config(
    *, seed: int, fixed_atoms: bool = False
) -> IntegratorConfig

The IntegratorConfig of this record with seed (the Simulation's).

CSVR dataclass

Canonical sampling through velocity rescaling, ASE 3.27's Bussi on the graph engine (4-T02).

tau_fs is ASE's taut. The noise is ASE's stream from the Simulation's seed (conductor's choice 3). The conserved quantity adds the energy the thermostat transferred, as ASE's Bussi.

to_config 

to_config(
    *, seed: int, fixed_atoms: bool = False
) -> IntegratorConfig

The IntegratorConfig of this record with seed (the Simulation's).

NoseHooverChain dataclass

Nose-Hoover chains, ASE 3.27's NoseHooverChainNVT on the graph engine (4-T03).

tdamp_fs, tchain and tloop as ASE's tdamp, tchain, tloop. The thermostat masses come from the construction temperature, as ASE's (conductor's choice 4). fixcm and dof follow D2.

to_config 

to_config(
    *, seed: int, fixed_atoms: bool = False
) -> IntegratorConfig

The IntegratorConfig of this record with seed (the Simulation's); rule 1 refuses FixAtoms here (decision 44).

MTK dataclass

Martyna-Tobias-Klein NPT with Nose-Hoover chains, ASE 3.27's IsotropicMTKNPT (cell_mode= "hydrostatic") and MTKNPT ("full") on the graph engine (4-T03). Experimental: not yet qualified, as BAOAB (SPEC §10.2).

pressure_GPa is ASE's pressure_au in GPa; tdamp_fs, pdamp_fs, tchain, pchain, tloop and ploop as ASE's. fixcm and dof follow D2.

to_config 

to_config(
    *, seed: int, fixed_atoms: bool = False
) -> IntegratorConfig

The IntegratorConfig of this record with seed (the Simulation's); rule 1 refuses FixAtoms here (decision 44).

Berendsen dataclass

Berendsen thermostat and barostat: ASE 3.27's NVTBerendsen (no pressure), NPTBerendsen (pressure_GPa) and Inhomogeneous_NPTBerendsen (pressure_GPa and mask) on the graph engine (4-T02). Non-canonical: equilibration only; the plan warns.

taut_fs, taup_fs and compressibility_per_GPa as ASE's taut, taup and compressibility_au in fs and 1/GPa; mask: three 0/1 flags of the scaled cell directions, ASE's mask. A pressure needs taup_fs and compressibility_per_GPa.

to_config 

to_config(
    *, seed: int, fixed_atoms: bool = False
) -> IntegratorConfig

The IntegratorConfig of this record with seed (the Simulation's); FixAtoms runs with NVT only (rule 1).