mdinterface 1.5.4__tar.gz → 2.0.0__tar.gz

mdinterface-2.0.0/CHANGELOG.md

@@ -0,0 +1,177 @@
+# Changelog
+
+All notable changes to mdinterface are documented here.
+
+## [Unreleased]
+
+## [2.0.0] - 2026-09-28
+
+Makes `SimCell` the sole system builder, removing the deprecated `SimulationBox` and `BoxBuilder` APIs and adding spatially constrained solvent regions and optional LAMMPS structural metadata. This major release also changes explicit centering behavior, requires Python 3.10 or newer, and adds RDKit molecular preparation, atomic force-field parameterization, export validation, and improved external-tool diagnostics.
+
+### Added
+- `Specie.parameterize()` applies complete LigParGen results atomically and returns a charge audit for direct or segmented parameterization.
+- `Specie.mark_attachment_sites()` selects validated polymer leaving atoms using atom maps.
+- `Specie.validate_force_field()` and coefficient-bearing LAMMPS exports check parameter completeness, with optional `expected_charge` validation at export.
+- `Specie.generate_conformer()` and `minimize_geometry()`, inherited by `Polymer`, provide separate or combined RDKit embedding and MMFF94 minimization while preserving simulation parameters.
+- A mapped-SMILES polymer example prepares and parameterizes a charged chain and exports it with counterions.
+- `Specie(smiles=...)` and RDKit molecule inputs preserve chemical graphs, formal charges, stereochemistry, and atom maps, with `to_rdkit()` and `to_smiles()` conversion.
+- `SimCell.write_lammps(metadata=...)` optionally exports versioned structural JSON with final atom/type IDs, species groups, connectivity, coefficients and a data-file checksum, without choosing simulation settings.
+- `Sphere`, `Box`, and `Cylinder` regions for spatially constrained PACKMOL placement
+- `Region.fill()` for assigning content to a region
+- `SimCell.add_solvent(regions=...)` for spatially heterogeneous solvent layers
+- Nested regions through `Region.fill(regions=...)`
+- Reproducible automatic region placement through `center="random"` and `SimCell.add_solvent(seed=...)`
+
+### Changed
+- `Polymer` inherits force-field parameters from `Specie` monomers with distinct labels per repeat unless explicit topology overrides are supplied.
+- Large-molecule parameterization uses explicit charge-correction options and checks capped segment and expanded junction sizes before running LigParGen.
+- `Polymer.refine_junctions(snippet_radius=..., charge_correction=..., cap_element=...)` replaces `refine_polymer_topology()` and returns a charge audit, with public `junction_bonds` for connectivity.
+- The piperion example prepares geometry with RDKit and prints the refinement charge audit instead of recommending a neutral-charge ML relaxation for an ionic chain.
+- RDKit is now a required core dependency for molecular graph handling and SMILES support.
+- `Polymer` preserves explicit junction bonds and validates monomer chemistry instead of deriving junction connectivity from coordinates.
+- RDKit-backed LigParGen inputs use MOL files, and installation instructions and the full environment pin the compatible fork to commit `ad78036` to preserve chemistry during atom reordering.
+- `SimulationBox`, its module `mdinterface.simulationbox`, and the `BoxBuilder` alias are removed; migrate to `SimCell` using the 2.0 migration guide.
+- Legacy examples are removed from the repository and source distribution; current examples use `SimCell` and `Polymer`.
+- `SimCell.build(center=True)` now places the first layer at the box midpoint instead of across the periodic boundary; the default remains `False`.
+- Minimum supported Python version is now 3.10
+- Supported Python versions are now tested through Python 3.14
+- PACKMOL is now installed automatically from its upstream PyPI package
+- Importing `mdinterface` no longer loads optional AIMD and plotting dependencies or reads user configuration
+- PACKMOL execution and output failures now raise `PackmolError` with retained diagnostic file locations instead of returning `None`
+- LigParGen setup, execution, and output failures now raise `LigParGenError` with actionable installation or configuration guidance and retained diagnostic file locations
+- `build.box.populate_box()` now accepts `Specie` objects and returns `ase.Atoms`
+- PACKMOL templates now use ASE instead of MDAnalysis, eliminating PDB-completeness warnings for temporary files
+
+### Fixed
+- Source distributions include the full parameterization environment and MkDocs configuration referenced by the bundled setup instructions.
+- SMILES parsing preserves explicit hydrogen atom maps used to select polymer attachment sites.
+- `Specie.repeat()` scales the stored molecular charge and preserves the original copy's atom maps.
+- Junction refinement retains distinct improper assignments with identical coefficients.
+- Database ions retain their formal molecular charge independently of scaled force-field partial charges.
+- LAMMPS coefficient export uses unique temporary files instead of overwriting `tmp_data.lammps` in the working directory.
+- Explicit zero-valued bonded parameters are retained instead of being discarded during type mapping.
+- Imported LAMMPS bond connectivity survives trajectory coordinate updates, atom reordering, and `Specie.repeat()` without distance-based bond inference.
+- Junction refinement leaves the original chain unchanged if any parameterization fails.
+- Charge estimation uses the stored molecular charge, rejects conflicting overrides, and passes the charge through the Open Babel and RESP backends.
+- `Specie(ligpargen=True)` now retains the partial charges returned by parameterization.
+- Polymer refinement preserves charged groups, uses neutral snippet caps, and no longer reuses parameters based only on element strings.
+- The piperion example locates its charged nitrogen correctly and validates charge neutrality after refinement.
+- Nested regions now remain inside their parent's actual shape, including randomly placed regions.
+- `Region.fill()` validates content parameters, and solvent mixtures reject ambiguous scalar counts without a mixing ratio instead of silently omitting species.
+- Bulk solutes now exclude filled regions and use the remaining volume for concentration-based counts; incompatible fixed-center and concentration-profile placement raises an error.
+- Water model documentation now describes `Water(model="ewald")` as modified TIP3P for Ewald electrostatics (its parameters were always TIP3P-Ewald, not SPC/E) and no longer swaps variable names in the database guide
+- Slab tiling producing cells smaller than the requested XY dimensions when the nearest repeat count rounded down
+- Spurious MDAnalysis topology-guessing warnings in `Specie.to_universe()` and `build.box.populate_box()`
+- Missing `elements` topology data in universes created by `Specie.to_universe()`
+- Region-constrained PACKMOL placements exceeding requested boundaries because of loose default solver precision
+- Wheels including repository documentation, examples, tests, and local planning files because package discovery was not limited to `mdinterface`
+- Missing `mdinterface/config.ini` in wheels, which broke the default configuration fallback after installation
+
+### Deprecated
+- `add_solvent(solute_pos="left"/"right")` - pass an equivalent `Region`, such as `Box.from_bounds(...)`, instead
+
+---
+
+## [1.5.4] - 2026-08-12
+
+Automates PyPI releases with a test gate and a required changelog summary, and fixes `SimulationBox` crashing on its most common usage (density-based single solvent) while making its deprecation warning actually visible.
+
+### Changed
+- Release process: `publish.yml` replaced by `release.yml` - now runs the test suite and requires a changelog summary paragraph before publishing to PyPI, and creates a draft (not published) GitHub release with changelog-sourced notes instead of autogenerated commit notes
+- `.github/workflows/release.yml` also accepts manual `workflow_dispatch` (with a `tag` input) for re-running a release without re-tagging
+
+### Added
+- `.claude/skills/release` documenting the version-bump/changelog/tag procedure
+- `scripts/extract_changelog_summary.py` for extracting a version's changelog summary paragraph
+
+### Deprecated
+- `SimulationBox` now emits a `DeprecationWarning` on construction; use `SimCell` instead
+
+### Fixed
+- `simulationbox.py` called `warnings.filterwarnings('ignore')` at import time, silently suppressing all warnings process-wide for the rest of the program (including the existing `BoxBuilder` deprecation warning and this module's own warnings) - removed
+- `SimulationBox` crashed with `AttributeError: AtomGroup has no attribute get_masses` when using a single solvent with density (no `ratio`/`nsolvent`) - its most common usage
+
+---
+
+## [1.5.3] — 2026-07-09
+
+### Fixed
+- `NameError` in `DATAWriter` when `convert_units=False` (`coordinates` and `triv` were only assigned inside the conditional branch)
+- Improper type label in LAMMPS coefficient output was silently truncated to the first atom; now writes the full four-atom type string
+- `NameError` in `Specie.estimate_charges(assign=True)` for non-RESP methods (`atoms` was only defined in the RESP branch)
+- Wrong return-type annotation on `SimCell._stack_layers` (declared 2-tuple, returns 3-tuple)
+- `map_impropers(None)` returned a 2-tuple instead of the consistent 3-tuple returned by all other `map_*` functions
+- Dead unreachable error-checking code removed from `generate_missing_interactions`
+
+### Changed
+- Canonical repository moved from GitLab to GitHub
+- Deployment: tag/version consistency check and GitHub Release creation added to publish workflow
+- Deployment: docs workflow now only rebuilds when source files change
+
+---
+
+## [1.5.2] — 2026-03-31
+
+### Fixed
+- Topology label mismatch for large molecules in LigParGen segmentation
+
+---
+
+## [1.5.1] — 2026-03-31
+
+### Added
+- GitHub Actions workflow for automated PyPI publishing on version tags
+- GROMACS output: `write_gromacs_itp`, `write_gromacs_top`, `Specie.write_gro()`
+- `refine_large_specie_topology` for LigParGen parameterisation of molecules with more than 200 atoms
+- `Specie.write_gro()` for writing GROMACS structure files
+- `BOSSdir` config key supporting local install, container, and direct-path modes
+
+### Fixed
+- Junction LJ type correction in segment and polymer refinement
+- Docs CI: use `--no-deps` to avoid building compiled dependencies (libarvo)
+- PACKMOL and LigParGen now use a temp directory; kept on failure for inspection
+
+### Changed
+- `libarvo` made optional; only required for volume/radius estimation
+- Logging style updated throughout; improved SimCell and externals API docs
+
+---
+
+## [1.5.0] — 2026-02-01
+
+### Added
+- MkDocs documentation site with Material theme
+- Polymer guide and reorganised examples
+- `SimCell` fluent builder API (replaces `BoxBuilder`)
+- Multi-solvent support with `ratio` and mixed `nsolvent` lists
+- `solvent.py` extracted from `build.py` for clarity
+- `dilate` and `packmol_tolerance` parameters on `add_solvent`
+- `hijack`, `stack_axis`, `match_cell` options on `SimCell.build()`
+- Logging infrastructure with `set_verbosity` and structured headers
+
+### Changed
+- `ions`/`nions` renamed to `solute`/`nsolute` throughout
+- `populate_with_ions` renamed to `populate_solutes`
+- `BoxBuilder` retained as a deprecated alias for `SimCell`
+- Examples reorganised into `simulation_box/` and `box_builder/` subfolders
+
+### Fixed
+- Duplicate log output caused by missing `propagate=False`
+- Mutable default arguments in several functions
+
+---
+
+## [1.4.0]
+
+### Added
+- Initial `BoxBuilder` fluent API for multi-layer simulation box assembly
+- `to_ase()` output method
+- Noble gases in database
+
+### Fixed
+- Shell injection and insecure temp file naming
+- Bare `except` clauses replaced throughout
+- Raise-string bugs fixed
+- Improper detection corrected
+
+---

mdinterface-2.0.0/CONTRIBUTING.md

@@ -0,0 +1,67 @@
+# Contributing to mdinterface
+
+## Development setup
+
+Create and activate a Python environment, then install the package with its test dependencies in editable mode. This also installs the upstream PACKMOL package and executable:
+
+```bash
+pip install -e .[test]
+```
+
+Install optional dependencies only when working on the corresponding feature:
+
+```bash
+pip install -e .[resp]
+pip install -e .[aimd]
+```
+
+RESP fitting also requires the platform-specific `gpu4pyscf` package, which is not installed by the `resp` extra.
+
+Install `libarvo` separately when working on molecular volume or radius estimation.
+
+### Full parameterization environment
+
+Use the reproducible full environment when working on LigParGen, BOSS integration, or the planned OpenFF backend:
+
+```bash
+mamba env create -f environment-full.yml
+mamba activate mdinterface-full
+```
+
+The environment uses Python 3.12 and NumPy 1.x for compatibility with the current AmberTools dependency stack. It includes CPU-only NAGL and PyTorch, AmberTools, Open Babel, OpenFF Toolkit and Interchange, PACKMOL, tests, and documentation tooling. It installs the mdinterface-compatible LigParGen fork from GitHub at the verified commit pinned in `environment-full.yml`. Developers with a sibling LigParGen checkout containing commit `ad78036` (chemistry-preserving atom reordering) can use it instead:
+
+```bash
+python -m pip install -e ../ligpargen
+```
+
+BOSS is never included in the environment and must be obtained and configured separately. Set `BOSSdir` in the platform-specific mdinterface `config.ini` or export it before running LigParGen tests.
+
+## Tests
+
+Run the relevant test module while developing, then run the complete suite before submitting a change:
+
+```bash
+pytest -q tests/test_builder.py
+pytest -q
+```
+
+Tests marked `integration` execute PACKMOL. Run only unit tests with `pytest -q -m "not integration"` or only integration tests with `pytest -q -m integration`. Changes to LAMMPS output should verify section structure and counts, and should load the generated data with LAMMPS when that executable is available.
+
+Generate an informational coverage report with `pytest -q --cov=mdinterface --cov-report=term-missing`. The project does not currently enforce a coverage threshold.
+
+## Documentation
+
+Install the documentation dependencies and build the site with warnings treated strictly:
+
+```bash
+pip install -r docs/requirements.txt
+mkdocs build --strict
+```
+
+Update the relevant guide when changing a documented public API or workflow. API reference pages are generated from NumPy-style docstrings, so keep public docstrings current.
+
+## Changelog
+
+Add every user-visible change to `CHANGELOG.md` under `Unreleased`, grouped under `Added`, `Changed`, `Fixed`, or `Deprecated`. Write one concise, unwrapped sentence per bullet and describe one observable change. Omit internal refactoring, agent instructions, contributor-only documentation, CI maintenance, and release-process changes unless they affect what package users install or receive.
+
+See `docs/development/releasing.md` for the release process.

{mdinterface-1.5.4 → mdinterface-2.0.0}/MANIFEST.in

@@ -1,17 +1,22 @@
 # Include important files
 include README.md
 include LICENSE
+include CHANGELOG.md
+include CONTRIBUTING.md
 include requirements.txt
 include pyproject.toml
+include environment-full.yml
+include mkdocs.yml
 
 # 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 mdinterface/config.ini
 
-# Include documentation and assets if they exist
+# Include development material in the source distribution
 recursive-include docs *
+recursive-include examples *
+recursive-include scripts *.py
+recursive-include tests *.py
 include assets/*
 
 # Exclude unwanted files
@@ -24,3 +29,4 @@ recursive-exclude * *.py[co]
 recursive-exclude * .git*
 recursive-exclude * .tox*
 recursive-exclude * .pytest_cache*
+prune docs/superpowers

{mdinterface-1.5.4/mdinterface.egg-info → mdinterface-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mdinterface
-Version: 1.5.4
+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
@@ -13,15 +13,15 @@ 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: 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.8
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: mdanalysis>=2.0.0
@@ -30,11 +30,16 @@ 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"
@@ -67,19 +72,32 @@ Dynamic: license-file
 
 ## Requirements
 
-Check [requirements.txt](requirements.txt) for mandatory dependencies. `pip install mdinterface` handles them automatically.
+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.
 
-You also need `packmol` installed and on your `PATH`:
+### Optional packages
+
+#### Molecular volume estimation
+
+`Specie.estimate_specie_volume()` and `Specie.estimate_specie_radius()` require `libarvo`:
 
 ```bash
-conda install -c conda-forge packmol
+pip install libarvo
 ```
 
-### 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`:
+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)
@@ -89,11 +107,26 @@ BOSSdir = /path/to/boss          # native directory
 # 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 [PySCF](https://github.com/pyscf/pyscf) and [PyMBXAS](https://gitlab.com/roncofaber/pymbxas). RESP fitting currently requires [gpu4pyscf](https://github.com/pyscf/gpu4pyscf).
+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
 
@@ -103,8 +136,7 @@ pip install fairchem-core
 
 ## Installation
 
-- **Python** 3.8+
-- **PACKMOL** (see above)
+- **Python** 3.10-3.14
 
 ```bash
 # Stable release
@@ -124,6 +156,10 @@ 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
@@ -138,7 +174,7 @@ 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
+atoms = simbox.to_ase()    # ase.Atoms, ready for AIMD, ML-MD, or any other tool
 ```
 
 For LAMMPS, add ions and call `write_lammps()` instead:
@@ -162,15 +198,34 @@ 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_piperion.py` | Co-polymer membrane box with explicit hydration number |
+| `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)
 
-The legacy `SimulationBox` API is still available and unchanged; see [examples/legacy/](examples/legacy/).
+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
 

{mdinterface-1.5.4 → mdinterface-2.0.0}/README.md

@@ -24,19 +24,32 @@
 
 ## Requirements
 
-Check [requirements.txt](requirements.txt) for mandatory dependencies. `pip install mdinterface` handles them automatically.
+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.
 
-You also need `packmol` installed and on your `PATH`:
+### Optional packages
+
+#### Molecular volume estimation
+
+`Specie.estimate_specie_volume()` and `Specie.estimate_specie_radius()` require `libarvo`:
 
 ```bash
-conda install -c conda-forge packmol
+pip install libarvo
 ```
 
-### 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`:
+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)
@@ -46,11 +59,26 @@ BOSSdir = /path/to/boss          # native directory
 # 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 [PySCF](https://github.com/pyscf/pyscf) and [PyMBXAS](https://gitlab.com/roncofaber/pymbxas). RESP fitting currently requires [gpu4pyscf](https://github.com/pyscf/gpu4pyscf).
+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
 
@@ -60,8 +88,7 @@ pip install fairchem-core
 
 ## Installation
 
-- **Python** 3.8+
-- **PACKMOL** (see above)
+- **Python** 3.10-3.14
 
 ```bash
 # Stable release
@@ -81,6 +108,10 @@ 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
@@ -95,7 +126,7 @@ 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
+atoms = simbox.to_ase()    # ase.Atoms, ready for AIMD, ML-MD, or any other tool
 ```
 
 For LAMMPS, add ions and call `write_lammps()` instead:
@@ -119,15 +150,34 @@ 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_piperion.py` | Co-polymer membrane box with explicit hydration number |
+| `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)
 
-The legacy `SimulationBox` API is still available and unchanged; see [examples/legacy/](examples/legacy/).
+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
 

{mdinterface-1.5.4 → mdinterface-2.0.0}/docs/api/externals.md

@@ -4,6 +4,10 @@ Optional integrations with third-party tools.
 
 ## LigParGen (OPLS-AA parameters)
 
+::: mdinterface.externals.ligpargen.LigParGenError
+
+::: mdinterface.externals.ligpargen.run_ligpargen
+
 ::: mdinterface.externals.ligpargen.refine_large_specie_topology
 
 ## RESP charges (PySCF)

{mdinterface-1.5.4 → mdinterface-2.0.0}/docs/api/io.md

@@ -1,5 +1,9 @@
 # I/O
 
+## PACKMOL
+
+::: mdinterface.build.box.PackmolError
+
 ## Reading structures
 
 ::: mdinterface.io.read.read_lammps_data_file