mdinterface 1.3.0__tar.gz → 1.5.0__tar.gz

mdinterface-1.5.0/MANIFEST.in

@@ -0,0 +1,26 @@
+# Include important files
+include README.md
+include LICENSE
+include requirements.txt
+include pyproject.toml
+
+# Include package data
+recursive-include mdinterface *.py
+recursive-include mdinterface/database *.json *.txt *.dat
+recursive-include mdinterface/examples *.py
+recursive-include mdinterface/config *.ini
+
+# Include documentation and assets if they exist
+recursive-include docs *
+include assets/*
+
+# Exclude unwanted files
+exclude *.pyc
+exclude *~
+exclude *.bak
+exclude .DS_Store
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]
+recursive-exclude * .git*
+recursive-exclude * .tox*
+recursive-exclude * .pytest_cache*

mdinterface-1.5.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: mdinterface
+Version: 1.5.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://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
+Requires-Dist: libarvo
+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)
+
+`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
+
+- **Fluent `BoxBuilder` API** -- stack slabs, solvent regions, and vacuum gaps layer by layer; call `.build()` when done.
+- **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.
+- **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](https://github.com/Isra3l/ligpargen).
+- **Polymer builder** -- generate chains of arbitrary length from a monomer `Specie`.
+- **RESP charges** -- estimate partial charges with [PySCF](https://github.com/pyscf/pyscf) / [gpu4pyscf](https://github.com/pyscf/gpu4pyscf) (optional).
+- **AIMD with FAIRChem** -- run ML-potential dynamics via [FAIRChem](https://github.com/facebookresearch/fairchem) (optional).
+- **LAMMPS output** -- writes data files and force-field coefficient blocks ready to run.
+- **MDAnalysis integration** -- every object converts to `mda.Universe` with a single call.
+
+## 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 directory via `config.ini`:
+
+```ini
+# ~/.config/mdinterface/config.ini  (path is OS-dependent)
+[settings]
+BOSSdir = /path/to/boss
+```
+
+#### 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
+
+### Define species
+
+```python
+from mdinterface import BoxBuilder
+from mdinterface.database import Water, Ion, Metal111
+
+water = Water(model="ewald")
+na    = Ion("Na", ffield="Cheatham")
+cl    = Ion("Cl", ffield="Cheatham")
+gold  = Metal111("Au")
+```
+
+### Build a gold / NaCl electrolyte / gold sandwich
+
+```python
+simbox = BoxBuilder(xysize=[15, 15], verbose=True)
+
+simbox.add_slab(gold, nlayers=3)
+simbox.add_solvent(water, ions=[na, cl], nions=[5, 5], zdim=25, density=1.0)
+simbox.add_slab(gold, nlayers=3)
+simbox.add_vacuum(zdim=5)
+
+simbox.build(padding=0.5)
+simbox.write_lammps("data.lammps", atom_style="full", write_coeff=True)
+```
+
+### Mixed-solvent box (water + methanol)
+
+```python
+from mdinterface.core.specie import Specie
+
+methanol = Specie("CH3OH", ligpargen=True)
+
+simbox = BoxBuilder(xysize=[25, 25])
+simbox.add_solvent(
+    [water, methanol],
+    ratio=[3, 1],      # 3 water : 1 methanol by mole
+    density=0.95,
+    zdim=30,
+    ions=[na, cl],
+    nions=[5, 5],
+)
+simbox.build(padding=0.5)
+simbox.write_lammps("data_mixture.lammps", atom_style="full", write_coeff=True)
+```
+
+### Convert to ASE or MDAnalysis
+
+```python
+atoms    = simbox.to_ase()       # ase.Atoms with cell and PBC
+universe = simbox.universe       # mda.Universe
+```
+
+See the [examples/box_builder/](examples/box_builder/) directory for more complete scripts:
+
+| Script | What it shows |
+|--------|--------------|
+| `builder_electrode_interface.py` | Au / NaCl electrolyte / Au sandwich |
+| `builder_solvent_box.py` | Pure solvent + dissolved species |
+| `builder_multisolvent_box.py` | Mixed-solvent box with ratio/density/count modes |
+| `builder_multilayer.py` | Five-layer multi-slab system |
+| `builder_sandwich_from_traj.py` | Load a relaxed structure via `hijack` |
+
+The legacy `SimulationBox` API is still available and unchanged; see [examples/simulation_box/](examples/simulation_box/).
+
+## 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.0/README.md

@@ -0,0 +1,153 @@
+<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)
+
+`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
+
+- **Fluent `BoxBuilder` API** -- stack slabs, solvent regions, and vacuum gaps layer by layer; call `.build()` when done.
+- **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.
+- **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](https://github.com/Isra3l/ligpargen).
+- **Polymer builder** -- generate chains of arbitrary length from a monomer `Specie`.
+- **RESP charges** -- estimate partial charges with [PySCF](https://github.com/pyscf/pyscf) / [gpu4pyscf](https://github.com/pyscf/gpu4pyscf) (optional).
+- **AIMD with FAIRChem** -- run ML-potential dynamics via [FAIRChem](https://github.com/facebookresearch/fairchem) (optional).
+- **LAMMPS output** -- writes data files and force-field coefficient blocks ready to run.
+- **MDAnalysis integration** -- every object converts to `mda.Universe` with a single call.
+
+## 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 directory via `config.ini`:
+
+```ini
+# ~/.config/mdinterface/config.ini  (path is OS-dependent)
+[settings]
+BOSSdir = /path/to/boss
+```
+
+#### 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
+
+### Define species
+
+```python
+from mdinterface import BoxBuilder
+from mdinterface.database import Water, Ion, Metal111
+
+water = Water(model="ewald")
+na    = Ion("Na", ffield="Cheatham")
+cl    = Ion("Cl", ffield="Cheatham")
+gold  = Metal111("Au")
+```
+
+### Build a gold / NaCl electrolyte / gold sandwich
+
+```python
+simbox = BoxBuilder(xysize=[15, 15], verbose=True)
+
+simbox.add_slab(gold, nlayers=3)
+simbox.add_solvent(water, ions=[na, cl], nions=[5, 5], zdim=25, density=1.0)
+simbox.add_slab(gold, nlayers=3)
+simbox.add_vacuum(zdim=5)
+
+simbox.build(padding=0.5)
+simbox.write_lammps("data.lammps", atom_style="full", write_coeff=True)
+```
+
+### Mixed-solvent box (water + methanol)
+
+```python
+from mdinterface.core.specie import Specie
+
+methanol = Specie("CH3OH", ligpargen=True)
+
+simbox = BoxBuilder(xysize=[25, 25])
+simbox.add_solvent(
+    [water, methanol],
+    ratio=[3, 1],      # 3 water : 1 methanol by mole
+    density=0.95,
+    zdim=30,
+    ions=[na, cl],
+    nions=[5, 5],
+)
+simbox.build(padding=0.5)
+simbox.write_lammps("data_mixture.lammps", atom_style="full", write_coeff=True)
+```
+
+### Convert to ASE or MDAnalysis
+
+```python
+atoms    = simbox.to_ase()       # ase.Atoms with cell and PBC
+universe = simbox.universe       # mda.Universe
+```
+
+See the [examples/box_builder/](examples/box_builder/) directory for more complete scripts:
+
+| Script | What it shows |
+|--------|--------------|
+| `builder_electrode_interface.py` | Au / NaCl electrolyte / Au sandwich |
+| `builder_solvent_box.py` | Pure solvent + dissolved species |
+| `builder_multisolvent_box.py` | Mixed-solvent box with ratio/density/count modes |
+| `builder_multilayer.py` | Five-layer multi-slab system |
+| `builder_sandwich_from_traj.py` | Load a relaxed structure via `hijack` |
+
+The legacy `SimulationBox` API is still available and unchanged; see [examples/simulation_box/](examples/simulation_box/).
+
+## 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.0/examples/box_builder/builder_electrode_interface.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+BoxBuilder example: Au(111) / NaCl electrolyte / Au(111) sandwich.
+
+Equivalent to make_box.py but using the fluent BoxBuilder API.
+Layers are added in the order they appear in the cell (bottom → top).
+
+Author: roncofaber
+"""
+
+from mdinterface import BoxBuilder
+from mdinterface.database import Water, Ion, Metal111
+
+#%% Define species
+
+water = Water(model="ewald")
+
+na = Ion("Na", ffield="Cheatham")
+cl = Ion("Cl", ffield="Cheatham")
+
+gold = Metal111("Au")
+
+#%% Set up simulation box
+
+simbox = BoxBuilder(
+    xysize=[15, 15],
+    verbose=True,   # True → INFO, "DEBUG" → DEBUG, False/None → silent
+)
+
+#%% Add layers  (bottom → top)
+
+simbox.add_slab(gold, nlayers=1)
+
+simbox.add_solvent(
+    water,
+    ions=[na, cl],
+    nions=[5, 5],           # 5 Na⁺ and 5 Cl⁻
+    zdim=25,
+    density=1.0,
+    # dilate=1.25,          # for concentrated systems: packs into a box 25%
+    #                       # taller so PACKMOL has breathing room; NpT MD
+    #                       # will compress back to the correct density
+    # packmol_tolerance=1.5,# lower from default 2.0 Å if PACKMOL fails to pack
+)
+
+simbox.add_slab(gold, nlayers=1)
+
+simbox.add_vacuum(zdim=5)
+
+#%% Build
+
+simbox.build(
+    padding=0.5,
+    center=False,   # set True to center the first slab in the box
+    layered=False,  # set True to tag each slab layer with a unique mol-id
+    # hijack=atoms, # override positions + cell from an external ase.Atoms
+    #               # (e.g. a pre-relaxed slab); topology is preserved
+)
+
+#%% Output
+
+# Write LAMMPS data file (with force-field coefficients)
+simbox.write_lammps("data.lammps", atom_style="full", write_coeff=True)
+
+# Convert to ASE Atoms (e.g. for visualisation or further manipulation)
+atoms = simbox.to_ase()
+
+# Access the raw MDAnalysis Universe if needed
+universe = simbox.universe

mdinterface-1.5.0/examples/box_builder/builder_multilayer.py

@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+BoxBuilder example: multi-layer cell with heterogeneous electrolyte regions.
+
+This setup is impractical to express with the old SimulationBox API (which
+only supports one interface, one enderface, and one miderface slot). With
+BoxBuilder you can stack as many slabs and solvent regions as needed.
+
+Layout (bottom to top):
+    Au(111) slab        — bottom electrode
+    NaCl solution       — first electrolyte region
+    Pt(111) slab        — middle electrode
+    KF solution         — second electrolyte region
+    Pt(111) slab        — top electrode
+    vacuum gap
+
+Author: roncofaber
+"""
+
+from mdinterface import BoxBuilder
+from mdinterface.database import Water, Ion, Metal111
+
+#%% Define species
+
+water = Water(model="ewald")
+
+na = Ion("Na", ffield="Cheatham")
+cl = Ion("Cl", ffield="Cheatham")
+k  = Ion("K",  ffield="Cheatham")
+f  = Ion("F",  ffield="Dang")
+
+gold     = Metal111("Au")
+platinum = Metal111("Pt")
+
+#%% Set up simulation box
+
+simbox = BoxBuilder(xysize=[20, 20])
+
+#%% Add layers  (bottom → top)
+
+simbox.add_slab(gold, nlayers=3)                                        # bottom electrode
+
+simbox.add_solvent(water, ions=[na, cl], nions=[4, 4], zdim=20, density=1.0)  # NaCl region
+
+simbox.add_slab(platinum, nlayers=2)                                    # middle electrode
+
+simbox.add_solvent(water, ions=[k, f], nions=[4, 4], zdim=20, density=1.0)   # KF region
+
+simbox.add_slab(platinum, nlayers=2)                                    # top electrode
+
+simbox.add_vacuum(zdim=10)                                              # gap at periodic boundary
+
+#%% Build
+
+simbox.build(padding=0.5)
+
+#%% Output
+
+# Write LAMMPS data file (with force-field coefficients)
+simbox.write_lammps("data_multilayer.lammps", atom_style="full", write_coeff=True)
+
+# Convert to ASE Atoms (e.g. for visualisation or further manipulation)
+atoms = simbox.to_ase()
+
+# Access the raw MDAnalysis Universe if needed
+universe = simbox.universe

mdinterface-1.5.0/examples/box_builder/builder_multisolvent_box.py

@@ -0,0 +1,83 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+BoxBuilder example: mixed-solvent box (water + methanol).
+
+Demonstrates the three ways to specify solvent composition when multiple
+solvent species are present.  A dissolved NaCl salt is added on top.
+
+Mixing modes (choose one):
+
+  A) ratio + density   -- most physical: volumes/masses set the count
+  B) ratio + nsolvent  -- fix total molecule count, split by ratio
+  C) nsolvent (list)   -- full manual control, one count per species
+
+Author: roncofaber
+"""
+
+from mdinterface import BoxBuilder
+from mdinterface.database import Water, Ion
+from mdinterface.core.specie import Specie
+
+#%% Define species
+
+# Solvents
+water    = Water(model="ewald")
+methanol = Specie("CH3OH", ligpargen=True)
+
+# Dissolved ions (optional — comment out if not needed)
+na = Ion("Na", ffield="Cheatham")
+cl = Ion("Cl", ffield="Cheatham")
+
+#%% Set up simulation box
+
+simbox = BoxBuilder(
+    xysize=[25, 25],
+    verbose=True,
+)
+
+#%% Add mixed-solvent layer
+
+# --- Mode A: ratio + density (recommended for liquid mixtures) ---
+# 3 water molecules for every 1 methanol, total density 0.95 g/cm³.
+# Molecule counts are derived automatically from the molar masses.
+simbox.add_solvent(
+    [water, methanol],
+    ratio=[3, 1],           # molar mixing ratio (water : methanol)
+    density=0.95,           # mixture density in g/cm³
+    zdim=30,                # region thickness in Å
+    ions=[na, cl],
+    nions=[5, 5],           # 5 Na+ and 5 Cl-
+)
+
+# --- Mode B: ratio + fixed total count ---
+# Uncomment to use instead of Mode A.
+# simbox.add_solvent(
+#     [water, methanol],
+#     ratio=[3, 1],
+#     nsolvent=200,          # 150 water + 50 methanol (split proportionally)
+#     zdim=30,
+#     ions=[na, cl],
+#     nions=[5, 5],
+# )
+
+# --- Mode C: explicit per-species counts ---
+# Uncomment to use instead of Mode A.
+# simbox.add_solvent(
+#     [water, methanol],
+#     nsolvent=[150, 50],    # exactly 150 water and 50 methanol
+#     zdim=30,
+#     ions=[na, cl],
+#     nions=[5, 5],
+# )
+
+#%% Build
+
+simbox.build(padding=0.5)
+
+#%% Output
+
+simbox.write_lammps("data_multisolvent.lammps", atom_style="full", write_coeff=True)
+
+atoms    = simbox.to_ase()
+universe = simbox.universe

mdinterface-1.5.0/examples/box_builder/builder_sandwich_from_traj.py

@@ -0,0 +1,91 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+BoxBuilder example: Pt(111) / polymer slab / Pt(111) sandwich loaded from a
+LAMMPS dump trajectory.
+
+The polymer slab positions come from a prior MD run rather than being built
+from scratch.  The topology object (Specie / Polymer) is defined here — in a
+real workflow it would be loaded from a pickle saved during chain building.
+
+A minimal single-frame dump is provided in data/water_frame.dump so the
+example is self-contained.  Replace DUMP_FILE with the path to your own
+production dump to reproduce the real workflow.
+
+Workflow
+--------
+1. Define / load the polymer topology (Specie or Polymer with FF params).
+2. Point DUMP_FILE at a LAMMPS dump from a prior MD run.
+3. Read the target frame with read_lammps_nth_frame — streams the file and
+   never loads the full trajectory into memory.
+4. Inject those positions into the topology object with update_positions().
+5. Stack everything with BoxBuilder as usual.
+
+Author: roncofaber
+"""
+
+from pathlib import Path
+
+from mdinterface import BoxBuilder
+from mdinterface.database import Water, Metal111
+from mdinterface.io import read_lammps_nth_frame
+
+#%% Paths
+
+# Minimal 1-frame dump shipped with this example.
+# In a real workflow: DUMP_FILE = "/path/to/production.dump"
+DUMP_FILE = Path(__file__).parent / "data" / "water_frame.dump"
+
+#%% Define species
+# Water is used here as a stand-in for a Nafion polymer.
+# In practice you would do:  polymer = pickle.load(open("nafi_20.pkl", "rb"))
+
+water    = Water(model="ewald")
+platinum = Metal111("Pt")
+
+#%% Read one frame from the dump
+# frame=-1  -> last frame (default)
+# frame=0   -> first frame
+# The file is streamed; only the requested frame is parsed.
+
+last_frame = read_lammps_nth_frame(DUMP_FILE, frame=-1)
+
+#%% Inject trajectory positions into the topology object
+# prune_z=True trims any vacuum that accumulated during MD along z.
+# The cell is also updated, so BoxBuilder picks up the correct XY dimensions.
+
+water.update_positions(atoms=last_frame, prune_z=True)
+
+#%% Set up simulation box
+# xysize is a tiling hint for the electrode slabs.
+# match_cell=water overrides the final XY to the polymer's exact cell,
+# so the starting guess here only needs to be in the right ballpark.
+
+simbox = BoxBuilder(
+    xysize=[20, 20],
+    verbose=True,
+)
+
+#%% Add layers (bottom -> top)
+
+simbox.add_slab(platinum, nlayers=2)
+
+simbox.add_slab(water, nlayers=1)       # polymer: cell already matches, no tiling
+
+simbox.add_slab(platinum, nlayers=2)
+
+#%% Build
+# match_cell=water locks XY to the polymer's cell.
+# Pt slabs are stretched to conform; the polymer itself is left unscaled.
+
+simbox.build(
+    padding=0.5,
+    match_cell=platinum,
+)
+
+#%% Output
+
+simbox.write_lammps("data.lammps", atom_style="full", write_coeff=True)
+
+atoms    = simbox.to_ase()
+universe = simbox.universe