mdinterface 1.4.0__tar.gz → 1.5.1__tar.gz

mdinterface-1.5.1/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: mdinterface
+Version: 1.5.1
+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://gitlab.com/roncofaber/mdinterface
+Project-URL: Repository, https://gitlab.com/roncofaber/mdinterface.git
+Project-URL: Documentation, https://gitlab.com/roncofaber/mdinterface
+Project-URL: Bug Tracker, https://gitlab.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.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.8
+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
+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: all
+Requires-Dist: pyscf>=2.0.0; extra == "all"
+Requires-Dist: pymbxas; extra == "all"
+Requires-Dist: fairchem-core; extra == "all"
+Dynamic: license-file
+
+<div style="display: flex; align-items: center;">
+  <img src="./assets/mdinterface.png" alt="Logo" width="80"  style="margin-right: 10px;">
+  <div style="display: flex; flex-direction: column;">
+    <h1 style="margin: 0;">mdinterface: Build Interface Systems for Molecular Dynamics Simulations</h1>
+  </div>
+</div>
+
+[![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
+
+Check [requirements.txt](requirements.txt) for mandatory dependencies. `pip install mdinterface` handles them automatically.
+
+You also need `packmol` installed and on your `PATH`:
+
+```bash
+conda install -c conda-forge packmol
+```
+
+### Optional packages
+
+#### LigParGen (automatic OPLS-AA parameters)
+
+Follow the instructions on the [LigParGen GitHub](https://github.com/Isra3l/ligpargen) (or try [this fork](https://github.com/roncofaber/ligpargen) if you hit installation issues). 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
+```
+
+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.
+
+#### RESP charges with PySCF
+
+Install [PySCF](https://github.com/pyscf/pyscf) and [PyMBXAS](https://gitlab.com/roncofaber/pymbxas). RESP fitting currently requires [gpu4pyscf](https://github.com/pyscf/gpu4pyscf).
+
+#### AIMD with FAIRChem
+
+```bash
+pip install fairchem-core
+```
+
+## Installation
+
+- **Python** 3.8+
+- **PACKMOL** (see above)
+
+```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
+```
+
+## 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 |
+| `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_piperion.py` | Co-polymer membrane box with explicit hydration number |
+
+Full API reference and user guide: [roncofaber.github.io/mdinterface](https://roncofaber.github.io/mdinterface)
+
+The legacy `SimulationBox` API is still available and unchanged; see [examples/legacy/](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!

mdinterface-1.5.1/README.md

@@ -0,0 +1,140 @@
+<div style="display: flex; align-items: center;">
+  <img src="./assets/mdinterface.png" alt="Logo" width="80"  style="margin-right: 10px;">
+  <div style="display: flex; flex-direction: column;">
+    <h1 style="margin: 0;">mdinterface: Build Interface Systems for Molecular Dynamics Simulations</h1>
+  </div>
+</div>
+
+[![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
+
+Check [requirements.txt](requirements.txt) for mandatory dependencies. `pip install mdinterface` handles them automatically.
+
+You also need `packmol` installed and on your `PATH`:
+
+```bash
+conda install -c conda-forge packmol
+```
+
+### Optional packages
+
+#### LigParGen (automatic OPLS-AA parameters)
+
+Follow the instructions on the [LigParGen GitHub](https://github.com/Isra3l/ligpargen) (or try [this fork](https://github.com/roncofaber/ligpargen) if you hit installation issues). 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
+```
+
+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.
+
+#### RESP charges with PySCF
+
+Install [PySCF](https://github.com/pyscf/pyscf) and [PyMBXAS](https://gitlab.com/roncofaber/pymbxas). RESP fitting currently requires [gpu4pyscf](https://github.com/pyscf/gpu4pyscf).
+
+#### AIMD with FAIRChem
+
+```bash
+pip install fairchem-core
+```
+
+## Installation
+
+- **Python** 3.8+
+- **PACKMOL** (see above)
+
+```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
+```
+
+## 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 |
+| `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_piperion.py` | Co-polymer membrane box with explicit hydration number |
+
+Full API reference and user guide: [roncofaber.github.io/mdinterface](https://roncofaber.github.io/mdinterface)
+
+The legacy `SimulationBox` API is still available and unchanged; see [examples/legacy/](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!

mdinterface-1.5.1/docs/api/database.md

@@ -0,0 +1,23 @@
+# Database
+
+## Metals
+
+::: mdinterface.database.metals.Metal111
+
+## Water
+
+::: mdinterface.database.molecules.Water
+
+## Ions
+
+::: mdinterface.database.ions.Ion
+
+::: mdinterface.database.ions.lookup_parameters
+
+## Noble gases
+
+::: mdinterface.database.nobles.NobleGas
+
+## Graphene
+
+::: mdinterface.database.graphene.Graphene

mdinterface-1.5.1/docs/api/externals.md

@@ -0,0 +1,19 @@
+# Externals
+
+Optional integrations with third-party tools.
+
+## LigParGen (OPLS-AA parameters)
+
+::: mdinterface.externals.ligpargen.refine_large_specie_topology
+
+## RESP charges (PySCF)
+
+::: mdinterface.externals.pyscf.calculate_RESP_charges
+
+## Structure relaxation (ASE)
+
+::: mdinterface.externals.optimization.relax_structure
+
+## AIMD (FAIRChem)
+
+::: mdinterface.externals.aimd.run_aimd

mdinterface-1.5.1/docs/api/io.md

@@ -0,0 +1,27 @@
+# I/O
+
+## Reading structures
+
+::: mdinterface.io.read.read_lammps_data_file
+
+::: mdinterface.io.read.read_lammps_nth_frame
+
+## GROMACS writer
+
+!!! warning
+    GROMACS output is experimental.  Verify results against a reference
+    before production use.
+
+::: mdinterface.io.gromacswriter.write_gromacs_itp
+
+::: mdinterface.io.gromacswriter.write_gromacs_top
+
+## Logging utilities
+
+::: mdinterface.utils.logger.set_verbosity
+
+::: mdinterface.utils.logger.log_header
+
+::: mdinterface.utils.logger.log_subheader
+
+::: mdinterface.utils.logger.log_banner

mdinterface-1.5.1/docs/api/polymer.md

@@ -0,0 +1,3 @@
+# Polymer
+
+::: mdinterface.core.polymer.Polymer

mdinterface-1.5.1/docs/api/simcell.md

@@ -0,0 +1,3 @@
+# SimCell
+
+::: mdinterface.build.builder.SimCell

mdinterface-1.5.1/docs/api/specie.md

@@ -0,0 +1,3 @@
+# Specie
+
+::: mdinterface.core.specie.Specie

mdinterface-1.5.1/docs/guide/database.md

@@ -0,0 +1,86 @@
+# Database
+
+`mdinterface` ships a built-in database of common species with pre-defined force-field parameters. All entries are importable from `mdinterface.database`.
+
+## Metals
+
+```python
+from mdinterface.database import Metal111
+
+gold    = Metal111("Au")
+silver  = Metal111("Ag")
+platinum = Metal111("Pt")
+copper  = Metal111("Cu")
+```
+
+`Metal111` generates an FCC (111) surface slab. The element symbol selects the lattice parameter and Lennard-Jones parameters.
+
+## Water models
+
+```python
+from mdinterface.database import Water
+
+water_spce  = Water(model="ewald") # modified tip3p model
+water_tip4p = Water(model="spce")  # SPC/E water
+```
+
+## Ions
+
+```python
+from mdinterface.database import Ion
+
+na = Ion("Na", ffield="Cheatham")
+cl = Ion("Cl", ffield="Cheatham")
+li = Ion("Li", ffield="Cheatham")
+k  = Ion("K",  ffield="Cheatham")
+```
+
+Currently, the following force field parameters for monovalent ions have been implemented:
+
+- **Aqvist**   : J. Phys. Chem. B 2008, [https://pubs.acs.org/doi/10.1021/jp8001614](https://pubs.acs.org/doi/10.1021/jp8001614),
+- **Jorgensen**: J. Chem. Theory Comput. 2006, [https://pubs.acs.org/doi/10.1021/ct600252r](https://pubs.acs.org/doi/10.1021/ct600252r)
+- **Cheatham** : J. Phys. Chem. B 2008, [https://pubs.acs.org/doi/10.1021/jp8001614](https://pubs.acs.org/doi/10.1021/jp8001614)
+- **Sengupta** : J. Chem. Inf. Model. 2021, [https://pubs.acs.org/doi/10.1021/acs.jcim.0c01390](https://pubs.acs.org/doi/10.1021/acs.jcim.0c01390)
+- **Dang**     : J. Chem. Phys. 1992/1994
+- **OPLS-AA**  : J. Chem. Theory Comput. 2009, [https://pubs.acs.org/doi/10.1021/ct900009a](https://pubs.acs.org/doi/10.1021/ct900009a)
+
+Special ion species also available:
+
+```python
+from mdinterface.database import Perchlorate, Hydronium, Hydroxide
+```
+
+If the parameter set you are looking for are not present, you can always create a Specie explicitly:
+
+```python
+from mdinterface import Specie
+
+Li = Specie("Li", charges=1, lj={"Li": [0.33673, 1.40940]})
+```
+
+
+
+## Noble gases
+
+```python
+from mdinterface.database import Neon, Argon, Krypton, Xenon, NobleGas
+
+ar = Argon()
+xe = Xenon()
+# or generically:
+gas = NobleGas("Kr")
+```
+
+## Graphene
+
+```python
+from mdinterface.database import Graphene
+
+grap = Graphene()
+```
+
+## Small molecules
+
+```python
+from mdinterface.database import Oxygen, Hydrogen, Nitrogen
+```

mdinterface-1.5.1/docs/guide/logging.md

@@ -0,0 +1,52 @@
+# Logging
+
+`mdinterface` uses Python's standard `logging` module. By default all log output is suppressed (a `NullHandler` is installed at import time, following standard library practice).
+
+## Enabling output
+
+**Package-wide** — the recommended approach:
+
+```python
+import mdinterface
+
+mdinterface.set_verbosity(1)        # INFO  (normal detail)
+mdinterface.set_verbosity(2)        # DEBUG (maximum detail)
+mdinterface.set_verbosity(0)        # WARNING (quiet)
+mdinterface.set_verbosity("DEBUG")  # string form
+mdinterface.set_verbosity(True)     # same as 1 / INFO
+mdinterface.set_verbosity(False)    # same as 0 / WARNING
+```
+
+**Via SimCell constructor** — convenient for one-off scripts:
+
+```python
+from mdinterface import SimCell
+
+simbox = SimCell(xysize=[15, 15], verbose=True)   # INFO
+simbox = SimCell(xysize=[15, 15], verbose=2)      # DEBUG
+```
+
+## Verbosity levels
+
+| Value | Level | Typical output |
+|-------|-------|----------------|
+| `0` / `False` | WARNING | Only warnings and errors |
+| `1` / `True` | INFO | Build summary, layer sizes, molecule counts |
+| `2` | DEBUG | PACKMOL details, internal operations |
+| `"DEBUG"` / `"INFO"` / ... | raw Python level | Passed directly to `logging` |
+
+## Log format
+
+All messages are prefixed with `[mdi]` and a compact 4-character level name:
+
+```
+[mdi] INFO | ===  Build  ================================
+[mdi] INFO |
+[mdi] INFO | --  Layer [1/3]  --------------------------
+[mdi] INFO |   >> Au (111):  14.421 x 14.421 x 6.657 Å,  480 atoms
+[mdi] INFO |   >> layer z: +6.66 Å  |  total z: 6.66 Å
+```
+
+## Integration with existing logging config
+
+Since `mdinterface` uses a dedicated `"mdinterface"` logger subtree, it coexists cleanly with any logging configuration you already have in your application. `set_verbosity` only affects the `"mdinterface"` logger family and does not touch the root logger.