Metadata-Version: 2.4
Name: mdinterface
Version: 2.0.0
Summary: Build Interface Systems for Molecular Dynamics Simulations
Author-email: Fabrice Roncoroni <fabrice.roncoroni@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/roncofaber/mdinterface
Project-URL: Repository, https://github.com/roncofaber/mdinterface.git
Project-URL: Documentation, https://roncofaber.github.io/mdinterface
Project-URL: Bug Tracker, https://github.com/roncofaber/mdinterface/issues
Keywords: molecular dynamics,simulation,interface,chemistry,materials science
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mdanalysis>=2.0.0
Requires-Dist: ase>=3.22.0
Requires-Dist: numpy>=1.20.0
Requires-Dist: networkx>=2.5
Requires-Dist: platformdirs>=2.0.0
Requires-Dist: configparser>=5.0.0
Requires-Dist: packmol>=21.2.3
Requires-Dist: rdkit>=2024.3.5
Provides-Extra: resp
Requires-Dist: pyscf>=2.0.0; extra == "resp"
Requires-Dist: pymbxas; extra == "resp"
Provides-Extra: aimd
Requires-Dist: fairchem-core; extra == "aimd"
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Requires-Dist: pytest-cov>=4; extra == "test"
Provides-Extra: all
Requires-Dist: pyscf>=2.0.0; extra == "all"
Requires-Dist: pymbxas; extra == "all"
Requires-Dist: fairchem-core; extra == "all"
Dynamic: license-file

<h1>
  <img src="./assets/mdinterface.png" alt="Logo" width="60" style="vertical-align: middle; margin-right: 10px;">
  mdinterface: Build Interface Systems for Molecular Dynamics Simulations
</h1>

[![PyPI version](https://badge.fury.io/py/mdinterface.svg?icon=si%3Apython)](https://pypi.org/project/mdinterface/) [![GitHub version](https://badge.fury.io/gh/roncofaber%2Fmdinterface.svg?icon=si%3Agithub)](https://github.com/roncofaber/mdinterface) [![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://roncofaber.github.io/mdinterface)

`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](pyproject.toml). `pip install mdinterface` installs them automatically, including RDKit and the upstream PACKMOL package and executable; [requirements.txt](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`:

```bash
pip install libarvo
```

#### LigParGen (automatic OPLS-AA parameters)

Install the [mdinterface-compatible LigParGen fork](https://github.com/roncofaber/ligpargen) in the same environment and verify that `ligpargen -h` works:

```bash
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`:

```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](https://github.com/roncofaber/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.

```bash
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](https://github.com/pyscf/gpu4pyscf), which is not installed by the extra.

#### AIMD with FAIRChem

```bash
pip install fairchem-core
```

## Installation

- **Python** 3.10-3.14

```bash
# Stable release
pip install mdinterface

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

Optional extras:

```bash
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

```python
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:

```python
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/](examples/) directory:

| Script | What it shows |
|--------|--------------|
| `electrode_interface.py` | Au / NaCl electrolyte / Au sandwich |
| `smiles_box.py` | Unparameterized ethanol packing from SMILES |
| `solvent_box.py` | Pure solvent + dissolved species |
| `multisolvent_box.py` | Mixed-solvent box with ratio/density/count modes |
| `multilayer.py` | Five-layer multi-slab system |
| `sandwich_from_traj.py` | Electrode / membrane / electrode sandwich from an equilibrated MD trajectory |
| `polymer/polymer_from_smiles.py` | Mapped-SMILES attachment sites, charged polymer preparation, and neutralized LAMMPS export |
| `polymer/polymer_piperion.py` | RDKit chain geometry, LigParGen junction refinement with charge audit, and hydrated membrane packing |

Full API reference and user guide: [roncofaber.github.io/mdinterface](https://roncofaber.github.io/mdinterface)

Development setup and contribution guidance are in [CONTRIBUTING.md](CONTRIBUTING.md).

Version 2.0.0 removes `SimulationBox` and `BoxBuilder`; use `SimCell`. See the [2.0 migration guide](docs/guide/migration-2.md) for API replacements and coordinate changes.

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

```python
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](https://roncofaber.github.io/mdinterface/guide/polymer/) 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!
