mdinterface: Build Interface Systems for Molecular Dynamics Simulations

mdinterface is a Python package for building systems for Molecular Dynamics (MD) simulations. Initially developed for electrolyte/electrode solid-liquid interfaces, it is equally suited for pure solvent boxes, mixed-solvent electrolytes, and polymer networks.

Features

• Layer-by-layer SimCell builder: add slabs, solvent regions, and vacuum gaps one step at a time; call .build() when done.
• ASE & MDAnalysis integration: the assembled box converts to ase.Atoms or mda.Universe with a single call, ready for any downstream tool.
• Multi-solvent support: mix solvents by molar ratio + density, ratio + total count, or explicit per-species molecule counts.
• Ion placement: dissolve ions by count, molar concentration, or a spatially-varying concentration profile.
• PACKMOL integration: handles molecular packing automatically; tolerance and dilation are tunable per layer.
• Configurable stacking axis: build along Z (default) and permute to X or Y at the end.
• Polymer builder: generate chains of arbitrary length from a monomer Specie.
• AIMD with FAIRChem: run ML-potential dynamics via FAIRChem (optional).
• RESP charges: estimate partial charges with PySCF / gpu4pyscf (optional).
• Force-field database: pre-defined parameters for common metals, noble gases, water models, and ions; or generate OPLS-AA parameters on the fly with LigParGen.
• LAMMPS output: writes data files and force-field coefficient blocks ready to run.
• GROMACS output (experimental): write .gro, .top, and per-species .itp files directly from SimCell.write_gromacs() or Specie.write_gromacs_itp().

Requirements

Mandatory dependencies are declared in pyproject.toml. pip install mdinterface installs them automatically, including RDKit and the upstream PACKMOL package and executable; requirements.txt is a convenience list of the same core dependencies.

Optional packages

Molecular volume estimation

Specie.estimate_specie_volume() and Specie.estimate_specie_radius() require libarvo:

pip install libarvo

LigParGen (automatic OPLS-AA parameters)

Install the mdinterface-compatible LigParGen fork in the same environment and verify that ligpargen -h works:

python -m pip install "git+https://github.com/roncofaber/ligpargen.git@ad78036842318f166531be41cfcbc3563d7c5476"
conda install -c conda-forge openbabel
ligpargen -h
obabel -V

The pinned LigParGen revision preserves molecular chemistry during atom reordering. Open Babel is needed for coordinate-only ASE inputs; RDKit-backed inputs use MOL files.

Point mdinterface to your BOSS backend via config.ini:

# ~/.config/mdinterface/config.ini  (path is OS-dependent)
[settings]
BOSSdir = /path/to/boss          # native directory
# BOSSdir = /path/to/boss.sif   # Apptainer/Singularity container
# BOSSdir = boss-container:latest  # Docker image

The configuration file is read when LigParGen is invoked. An existing BOSSdir environment variable takes precedence over the file value.

BOSS is a 32-bit binary that can be awkward to run on modern systems. The boss-container repo provides a ready-to-build Docker/Apptainer image that handles the 32-bit library setup.

The container recipe does not distribute BOSS. Each licensed user builds a private image from their own BOSS installation. The resulting Docker image or Apptainer file contains BOSS and must not be published or shared beyond what the BOSS license permits.

Full parameterization development environment

The reproducible development environment combines mdinterface, LigParGen, Open Babel, AmberTools, and the CPU-only OpenFF stack. It uses Python 3.12 and NumPy 1.x to satisfy the current AmberTools dependency stack; the core package still supports Python 3.10-3.14.

mamba env create -f environment-full.yml
mamba activate mdinterface-full

OpenFF-to-mdinterface parameter import has been validated on Python 3.14, but OpenFF is not yet exposed as a supported Specie parameterization backend. The environment exists for developing and testing that integration. The normal mdinterface installation remains pip-installable and does not require OpenFF.

RESP charges with PySCF

Install the resp extra for PySCF and PyMBXAS. RESP fitting currently also requires the platform-specific gpu4pyscf, which is not installed by the extra.

AIMD with FAIRChem

pip install fairchem-core

Installation

• Python 3.10-3.14

# Stable release
pip install mdinterface

# Development version
git clone https://github.com/roncofaber/mdinterface.git
cd mdinterface
pip install -e .

Optional extras:

pip install mdinterface[resp]   # RESP charge analysis
pip install mdinterface[aimd]   # FAIRChem AIMD
pip install mdinterface[all]    # everything

The resp and all extras do not install gpu4pyscf; install the compatible build separately when using RESP fitting.

Contributors working on every parameterization backend can instead create the full environment described above with mamba env create -f environment-full.yml.

Quick start

from mdinterface import SimCell
from mdinterface.database import Water, Metal111

water = Water()
gold  = Metal111("Au")

simbox = SimCell(xysize=[15, 15])
simbox.add_slab(gold, nlayers=3)
simbox.add_solvent(water, zdim=20, density=1.0)
simbox.build()

atoms = simbox.to_ase()    # ase.Atoms, ready for AIMD, ML-MD, or any other tool

For LAMMPS, add ions and call write_lammps() instead:

from mdinterface.database import Ion

na = Ion("Na", ffield="Cheatham")
cl = Ion("Cl", ffield="Cheatham")

simbox = SimCell(xysize=[15, 15], verbose=True)
simbox.add_slab(gold, nlayers=3)
simbox.add_solvent(water, solute=[na, cl], nsolute=[5, 5], zdim=25, density=1.0)
simbox.add_slab(gold, nlayers=3)
simbox.build(padding=0.5)
simbox.write_lammps("data.lammps", atom_style="full", write_coeff=True)

More complete scripts are in the examples/ directory:

Full API reference and user guide: roncofaber.github.io/mdinterface

Development setup and contribution guidance are in CONTRIBUTING.md.

Version 2.0.0 removes SimulationBox and BoxBuilder; use SimCell. See the 2.0 migration guide for API replacements and coordinate changes.

For molecular and polymer preparation, parameterized monomers carry their force-field data into the chain:

from mdinterface import Specie, Polymer

monomer = Specie(smiles="[CH3:1][CH3:2]")
monomer.parameterize()
monomer.mark_attachment_sites(head_map=1, tail_map=2)
chain = Polymer(monomer, nrep=3)
chain.generate_conformer(seed=42, minimize=True)
report = chain.refine_junctions(charge_correction="uniform")

See the polymer guide for preparation, charge auditing, and export validation. Parameterization requires LigParGen and BOSS.

Roadmap

Since the original idea was to make a package to build MD boxes layer by layer, I am strongly debating renaming everything as "Workflow for Easy Molecular DYnamics Simulations", aka WEMDYS.

Questions & Issues

Sir, this is a WEMDY'S. Please contact me or open an issue, glad to talk about ideas and improvements!