Other Interfaces API#

Additional interfaces and utilities in mmml.

ASE Interface#

mmml.aseInterface.mmml_ase.MMMLCalculator(atoms, model_params, cutoff=4.0)#

ASE calculator for MMML models.

Parameters:

  • atoms – ASE Atoms object

  • model_params – Trained model parameters

  • cutoff – Distance cutoff

Returns:

ASE calculator instance

PyCharmm Interface#

Note

These interfaces rely on the bundled pycharmm package and a compiled CHARMM shared library (set CHARMM_HOME / CHARMM_LIB_DIR so libcharmm can be found).

mmml.pycharmmInterface.dyna.run_dynamics(psf_file, pdb_file, res_file, output_prefix, num_steps=1000, dt=0.001, temperature=300.0)#

Run molecular dynamics with PyCharmm.

Parameters:

  • psf_file – PSF topology file

  • pdb_file – PDB coordinate file

  • res_file – RES parameter file

  • output_prefix – Output file prefix

  • num_steps – Number of MD steps

  • dt – Time step in ps

  • temperature – Temperature in K

Returns:

None

mmml.pycharmmInterface.setupBox.setup_box(psf_file, pdb_file, res_file, output_prefix, box_size=50.0, water_model='TIP3')#

Set up simulation box with solvent.

Parameters:

  • psf_file – PSF topology file

  • pdb_file – PDB coordinate file

  • res_file – RES parameter file

  • output_prefix – Output file prefix

  • box_size – Box size in Angstrom

  • water_model – Water model name

Returns:

None

OpenMM Interface#

mmml.openmmInterface.interface.setup_openmm_system(pdb_file, forcefield='amber14-all.xml', water_model='tip3p')#

Set up OpenMM system.

Parameters:

  • pdb_file – PDB coordinate file

  • forcefield – Force field XML file

  • water_model – Water model name

Returns:

OpenMM system object

JAX-MD Interface#

mmml.jaxmdInterface.jaxmdInterface.run_jaxmd_simulation(positions, masses, forces, num_steps=1000, dt=0.001, temperature=300.0)#

Run molecular dynamics with JAX-MD.

Parameters:

  • positions – Initial positions

  • masses – Atomic masses

  • forces – Force function

  • num_steps – Number of MD steps

  • dt – Time step

  • temperature – Temperature

Returns:

Trajectory array

Data Processing#

mmml.io.parseCharmmOutput.parse_dcd(dcd_file)#

Parse CHARMM DCD trajectory file.

Parameters:

dcd_file – DCD file path

Returns:

Trajectory data

mmml.io.parseOpenMMOutput.parse_dcd(dcd_file)#

Parse OpenMM DCD trajectory file.

Parameters:

dcd_file – DCD file path

Returns:

Trajectory data

Visualization#

mmml.visualize.ase_x3d.write_x3d(atoms, filename, trajectory=None)#

Write ASE atoms to X3D format.

Parameters:

  • atoms – ASE Atoms object

  • filename – Output file path

  • trajectory – Optional trajectory data

Returns:

None

mmml.plotting.esp.plot_esp_surface(esp_data, grid_coords, output_file)#

Plot ESP on molecular surface.

Parameters:

  • esp_data – ESP values

  • grid_coords – Grid coordinates

  • output_file – Output file path

Returns:

None

Utilities#

mmml.transformations.pca.apply_pca(data, n_components=2)#

Apply PCA dimensionality reduction.

Parameters:

  • data – Input data array

  • n_components – Number of components

Returns:

Transformed data

PyCharmm MMML Calculator#

High-level calculator that couples ML and MM terms with smooth switching for monomer/dimer systems.

class mmml.pycharmmInterface.mmml_calculator.CutoffParameters(ml_cutoff=2.0, mm_switch_on=5.0, mm_cutoff=1.0)#

Parameters controlling ML/MM switching distances.

Parameters:

  • ml_cutoff – Distance where ML potential is cut off

  • mm_switch_on – Distance where MM potential starts switching on

  • mm_cutoff – Final cutoff for MM potential

class mmml.pycharmmInterface.mmml_calculator.ModelOutput(energy, forces, dH, internal_E, internal_F, mm_E, mm_F, ml_2b_E, ml_2b_F)#

Structured output for energies and forces.

Variables:

  • energy – Total energy (kcal/mol)

  • forces – Forces (kcal/mol/Å)

  • dH – Interaction energy

  • internal_E – Sum of monomer energies

  • internal_F – Monomer forces

  • mm_E – Classical MM energy

  • mm_F – Classical MM forces

  • ml_2b_E – ML two-body interaction energy

  • ml_2b_F – ML two-body interaction forces

mmml.pycharmmInterface.mmml_calculator.prepare_batches_md(data, batch_size, data_keys=None, num_atoms=60, dst_idx=None, src_idx=None, include_id=False, debug_mode=False)#

Prepare batched inputs for the underlying JAX model with precomputed indices and masks.

Parameters:

  • data – Dataset with keys like ‘R’, ‘Z’, ‘N’, optionally ‘F’, ‘E’, etc.

  • batch_size – Batch size

  • data_keys – Keys to include; defaults to all

  • num_atoms – Max atoms per system

  • dst_idx – Optional destination indices for pairs

  • src_idx – Optional source indices for pairs

  • include_id – Include ‘id’ if present

  • debug_mode – Extra checks/assertions

Returns:

List of batch dictionaries

mmml.pycharmmInterface.mmml_calculator.setup_calculator(ATOMS_PER_MONOMER, N_MONOMERS=2, ml_cutoff_distance=2.0, mm_switch_on=5.0, mm_cutoff=1.0, doML=True, doMM=True, doML_dimer=True, debug=False, ep_scale=None, sig_scale=None, model_restart_path=None, MAX_ATOMS_PER_SYSTEM=100)#

Build a configured calculator factory that computes energies and forces combining ML and MM with switching.

Parameters:

  • ATOMS_PER_MONOMER – Number of atoms in a monomer

  • N_MONOMERS – Number of monomers in the system

  • ml_cutoff_distance – ML cutoff distance

  • mm_switch_on – Distance where MM switches on

  • mm_cutoff – MM cutoff distance

  • doML – Include ML term

  • doMM – Include MM term

  • doML_dimer – Include ML two-body interactions

  • debug – Enable verbose debug

  • ep_scale – Optional epsilon scaling per atom type

  • sig_scale – Optional sigma scaling per atom type

  • model_restart_path – Path to trained model checkpoint

  • MAX_ATOMS_PER_SYSTEM – Padding size for batching

Returns:

A factory function to create an ASE calculator and the core compute function

mmml.transformations.tsne.apply_tsne(data, n_components=2, perplexity=30.0)#

Apply t-SNE dimensionality reduction.

Parameters:

  • data – Input data array

  • n_components – Number of components

  • perplexity – Perplexity parameter

Returns:

Transformed data