API Reference¶
This reference is generated from source modules and includes functions/classes documented in each namespace.
The previous version of this page only listed a minimal subset while docs generation was being stabilized. This page now covers the main MMML modules.
Top-Level Package¶
mmml
¶
Molecular Mechanics and Machine Learned Force Fields
Data¶
Units¶
mmml.data.units
¶
Central unit conversion constants and helpers for MMML.
All conversion factors are defined here to avoid magic numbers and ensure consistency across train_joint, fix_and_split, DCMNet, PhysNet, and calculators.
Reference: CODATA 2018 / NIST
Canonical ML / hybrid inference units: energy eV, forces eV/Angstrom, coords Angstrom.
UnitsManifestV2
dataclass
¶
Recorded in units_manifest.json for downstream loaders (schema v2).
convert_energy(values, from_unit, to_unit)
¶
Convert energy values between supported units.
format_energy_ev_kcal(energy_ev, *, ev_digits=6, kcal_digits=4)
¶
Format hybrid/ML energy as X eV (Y kcal/mol).
format_energy_kcal_ev(energy_kcal, *, kcal_digits=4, ev_digits=6)
¶
Format CHARMM energy as X kcal/mol (Y eV).
format_grms_kcal_ev_a(grms_kcal_mol_a, *, kcal_digits=4, ev_digits=4)
¶
Format GRMS as X kcal/mol/Å (Y eV/Å).
format_fmax_ev_kcal_a(fmax_ev_a, *, ev_digits=4, kcal_digits=4)
¶
Format max force as X eV/Å (Y kcal/mol/Å).
convert_forces(values, from_unit, to_unit)
¶
Convert force values between supported units.
convert_coords(values, from_unit, to_unit)
¶
Convert coordinate values between Angstrom and Bohr.
convert_dipole(values, from_unit, to_unit)
¶
Convert dipole values between Debye and e·Angstrom.
energy_to_ev(values, unit)
¶
Convert energy to eV (convenience wrapper).
load_reference_energies_from_npz(data, *, path=None)
¶
Load per-frame reference energies and their unit from an NPZ.
reference_energy_ev_at_frame(data, frame, *, path=None, energy_unit=None)
¶
Return (energy_eV, unit, raw_value) for one reference frame.
forces_to_ev_angstrom(values, unit)
¶
Convert forces to eV/Angstrom (convenience wrapper).
subtract_atom_refs(energies, atomic_numbers, *, energy_unit='ev', level=None, charge_state=0)
¶
Subtract per-atom reference energies from total energies.
load_units_manifest(path)
¶
Load units_manifest.json from a file or directory.
find_units_manifest(npz_path)
¶
Search for units_manifest.json near an NPZ file.
units_from_npz(npz_path)
¶
Read embedded _mmml_units from NPZ if present, else nearby manifest.
infer_reference_energy_unit(npz_path=None, *, manifest=None, default='hartree')
¶
Best-effort energy unit for a reference NPZ.
normalize_to_canonical(data, manifest=None, *, allow_hartree=False)
¶
Convert NPZ-like dict arrays to canonical eV/eV-Å/Å where applicable.
pyscf_units_metadata()
¶
Native PySCF export units for embedding in NPZ.
attach_units_to_npz_payload(payload)
¶
Return payload copy with embedded _mmml_units JSON string.
calculator_results_units()
¶
Standard unit metadata for hybrid calculator ASE results.
Atomic References¶
mmml.data.atomic_references
¶
Utilities for loading atomic reference energies from JSON data.
list_reference_levels(data_path=None)
¶
Return the available reference levels contained in the JSON table.
get_atomic_reference_dict(*, level=DEFAULT_REFERENCE_LEVEL, charge_state=DEFAULT_CHARGE_STATE, unit=DEFAULT_UNIT, fallback_to_neutral=True, data_path=None)
¶
Return a mapping from atomic number to reference energy.
Parameters¶
level
Level of theory / basis entry inside the JSON table.
charge_state
Charge state to select (e.g. 0 for neutral atoms).
unit
Desired output energy unit. Supported units are hartree, eV,
kcal/mol and kJ/mol.
fallback_to_neutral
If True and the requested charge state is missing for an element,
fall back to the neutral value when available.
data_path
Optional path to an alternative JSON table.
get_atomic_reference_array(*, level=DEFAULT_REFERENCE_LEVEL, charge_state=DEFAULT_CHARGE_STATE, unit=DEFAULT_UNIT, size=None, fallback_to_neutral=True, data_path=None)
¶
Return reference energies as an array indexed by atomic number.
XML Conversion¶
mmml.data.xml_to_npz
¶
Convert Molpro XML output to standardized NPZ format.
This module bridges the Molpro XML parser (parse_molpro) with the standardized NPZ format used across all MMML models.
ConversionStats
dataclass
¶
Statistics from XML to NPZ conversion.
MolproConverter
¶
Convert Molpro XML files to standardized NPZ format.
Handles single files or batches of XML files, extracts all available properties, and creates NPZ files following the MMML schema.
Parameters¶
padding_atoms : int, optional Number of atoms to pad to (for fixed-size arrays), by default 60 include_variables : bool, optional Whether to include Molpro variables in metadata, by default True verbose : bool, optional Whether to print progress information, by default True
Examples¶
converter = MolproConverter() data = converter.convert_single('output.xml') converter.save_npz(data, 'output.npz')
convert_single(xml_file)
¶
convert_batch(xml_files, progress_bar=True)
¶
save_npz(data, output_file, validate=True)
¶
Save NPZ data to file with optional validation.
Parameters¶
data : dict NPZ dictionary output_file : str or Path Output file path validate : bool, optional Whether to validate before saving, by default True
get_statistics()
¶
Get conversion statistics.
print_summary()
¶
Print conversion summary.
convert_xml_to_npz(xml_file, output_file, **kwargs)
¶
batch_convert_xml(xml_files, output_file, padding_atoms=60, include_variables=True, use_last_geometry=True, verbose=True, **kwargs)
¶
Convenience function to convert multiple XML files to single NPZ.
Parameters¶
xml_files : list List of input XML files output_file : str or Path Output NPZ file padding_atoms : int, optional Number of atoms to pad to, by default 60 include_variables : bool, optional Include Molpro variables in output, by default True use_last_geometry : bool, optional Use last geometry from files with multiple geometries (e.g., optimization trajectories). If False, use first geometry. Default is True. verbose : bool, optional Print progress information, by default True **kwargs Additional arguments passed to MolproConverter
Returns¶
bool True if successful
Examples¶
batch_convert_xml(['file1.xml', 'file2.xml'], 'dataset.npz')
Utilities¶
Electrostatics¶
This module requires optional JAX dependencies at import time, so it is not auto-rendered by mkdocstrings in the default docs build environment.
Source: mmml/utils/electrostatics.py.
Simulation Utilities¶
This module requires optional JAX dependencies at import time, so it is not auto-rendered by mkdocstrings in the default docs build environment.
Source: mmml/utils/simulation_utils.py.
HDF5 Reporter¶
This module requires optional JAX dependencies at import time, so it is not auto-rendered by mkdocstrings in the default docs build environment.
Source: mmml/utils/hdf5_reporter.py.
Model Checkpoint Utilities¶
This module requires optional JAX dependencies at import time, so it is not auto-rendered by mkdocstrings in the default docs build environment.
Source: mmml/utils/model_checkpoint.py.
Interfaces¶
OpenMM Interface¶
The OpenMM integration provides helpers to set up and run CHARMM/OpenMM simulations (PSF/PDB, parameter sets, integrators, and schedules). It depends on the optional OpenMM Python package (pip install openmm).
Source: mmml/interfaces/openmmInterface/interface.py.
PyCHARMM Setup Box¶
This module currently requires a local PyCHARMM installation at import time, so it is not auto-rendered by mkdocstrings in the default docs build environment.
Source: mmml/interfaces/pycharmmInterface/setupBox.py.
PyCHARMM Setup Residue¶
This module currently requires a local PyCHARMM installation at import time, so it is not auto-rendered by mkdocstrings in the default docs build environment.
Source: mmml/interfaces/pycharmmInterface/setupRes.py.
PyCHARMM Commands¶
This module currently requires a local PyCHARMM installation at import time, so it is not auto-rendered by mkdocstrings in the default docs build environment.
Source: mmml/interfaces/pycharmmInterface/pycharmmCommands.py.
PySCF4GPU Calculations¶
This module requires optional PySCF dependencies at import time, so it is not auto-rendered by mkdocstrings in the default docs build environment.
Source: mmml/interfaces/pyscf4gpuInterface/calcs.py.
Models¶
External electric-field PhysNet (EFieldPhysNet)¶
Field-dependent energy/force model for Raman/IR and related spectroscopy. Formerly under mmml/models/EF/ (deprecated import path).
Source: mmml/models/efield/training.py.
E-field training CLI¶
Canonical command: mmml efield-train (replaces deprecated ef-train).
Source: mmml/models/efield/training.py.
E-field evaluation CLI¶
Canonical command: mmml efield-evaluate (replaces deprecated ef-evaluate).
Source: mmml/models/efield/evaluate.py.
Unified energy/forces providers¶
ML checkpoints (PhysNet, joint PhysNet+DCMNet, E-field) and QC backends (PySCF, ORCA, xTB, Molpro) share :class:~mmml.interfaces.energy_forces.EnergyForcesProvider.
Source: mmml/interfaces/energy_forces/.
Hybrid CHARMM monomer/dimer MLpot requires supports_decomposed_ml (PhysNet family only); use build_provider for single-structure inference and cross-check.
CLI¶
Entry Point¶
mmml.cli.__main__
¶
Shared CLI Utilities¶
mmml.cli.base
¶
Base functionality for MMML demo scripts.
This module contains common utilities and functions used across different demo scripts for the MMML package.
parse_base_args()
¶
Parse common command line arguments used across demo scripts.
resolve_dataset_path(arg)
¶
Resolve the dataset path from argument or environment variable.
resolve_checkpoint_paths(arg)
¶
Return (factory_base_dir, epoch_dir) for the supplied checkpoint.
Supports orbax checkpoints (manifest.ocdbt), JSON checkpoints (params.json or a portable .json file), and bundled HF aliases (best-forces, mmml-default, neutral_best_forces, etc. — see mmml.models.physnetjax.defaults).
load_physnet_params_and_ef_model(resolved_checkpoint, natoms, *, orbax_epoch_dir=None, prefer_ema=True)
¶
Return (params, EF) for :func:get_ase_calc.
Parameters¶
resolved_checkpoint
Path to a portable .json checkpoint or an Orbax experiment root.
natoms
Atom count passed into the EF model (overrides config).
orbax_epoch_dir
When resolved_checkpoint is Orbax, pass _latest_epoch_dir(root) (or any
epoch directory). Ignored for .json checkpoints.
prefer_ema
For Orbax checkpoints, load ema_params when present (default True).
Portable JSON files already store whatever was exported (training's
end-of-run JSON writes EMA under the "params" key).
resolve_desdimers_checkpoint(script_file=None)
¶
Resolve a default DES-family checkpoint path without hardcoding.
load_configuration(npz_path, index)
¶
Load a configuration from the dataset.
load_model_parameters(epoch_dir, natoms)
¶
Load model parameters from checkpoint (orbax or JSON format).
compute_force_metrics(delta_forces)
¶
Compute RMS and maximum absolute force metrics.
flatten_array(value)
¶
Flatten an array to 1D.
setup_ase_imports()
¶
Setup ASE imports with error handling.
setup_mmml_imports()
¶
Setup MMML imports with error handling.
get_conversion_factors(units)
¶
Get energy and force conversion factors based on units.
get_unit_labels(units)
¶
Get unit labels for energy and forces.