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

Check requirements.txt for mandatory dependencies. pip install mdinterface handles them automatically.

You also need packmol installed and on your PATH:

conda install -c conda-forge packmol

Optional packages

LigParGen (automatic OPLS-AA parameters)

Follow the instructions on the LigParGen GitHub (or try this fork if you hit installation issues). 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

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.

RESP charges with PySCF

Install PySCF and PyMBXAS. RESP fitting currently requires gpu4pyscf.

AIMD with FAIRChem

pip install fairchem-core

Installation

• Python 3.8+
• PACKMOL (see above)

# 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

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

The legacy SimulationBox API is still available and unchanged; see examples/legacy/.

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!