mdinterface 1.3.0__tar.gz → 1.4.0__tar.gz

mdinterface-1.4.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.3.0 → mdinterface-1.4.0}/PKG-INFO

@@ -1,33 +1,45 @@
 Metadata-Version: 2.4
 Name: mdinterface
-Version: 1.3.0
+Version: 1.4.0
 Summary: Build Interface Systems for Molecular Dynamics Simulations
-Home-page: https://gitlab.com/roncofaber/mdinterface
-Author: Fabrice Roncoroni
-Author-email: fabrice.roncoroni@gmail.com
-License: Apache-2.0
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: Apache Software License
+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: Topic :: Software Development
+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
-Requires-Dist: ase
-Requires-Dist: numpy
-Requires-Dist: networkx
-Requires-Dist: platformdirs
-Requires-Dist: configparser
-Provides-Extra: volume
-Requires-Dist: libarvo; extra == "volume"
+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; 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: libarvo; extra == "all"
-Requires-Dist: pyscf; 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;">
@@ -50,6 +62,7 @@ Using `mdinterface` you can:
 - Import common molecules/metals/polymers with pre-defined classical force fields parameters from the database, or automatically generate new OPLS-AA force field parameters using [LigParGen](https://github.com/Isra3l/ligpargen).
 - Generate polymer chains of any length from a starting monomer.
 - Estimate the RESP charges of molecules using the [PySCF  electronic structure code](https://github.com/pyscf/pyscf).
+- Perform Ab Initio Molecular Dynamics (AIMD) simulations using [FAIRChem](https://github.com/facebookresearch/fairchem) machine learning potentials (optional).
 - Automatically write LAMMPS data files and coefficients, so you can start making them atoms dance as soon as possible!
 - Integrate your workflow with [MDAnalysis](https://github.com/MDAnalysis/mdanalysis): create your molecules with `mdinterface` and convert them to `mda.Universe` objects with a simple interface.
 
@@ -79,58 +92,124 @@ BOSSdir = /path/to/your/boss/dir
 
 The config directory is found using [`platformdirs`](https://pypi.org/project/platformdirs/) and is OS dependent.
 
-### RESP charge analysis with PySCF
+#### RESP charge analysis with PySCF
 
 To use the RESP charge analysis feature, you need to install [PySCF](https://github.com/pyscf/pyscf) and [PyMBXAS](https://gitlab.com/roncofaber/pymbxas). To my knowledge, the RESP feature is only implemented in [gpu4pyscf](https://github.com/pyscf/gpu4pyscf) at the moment, so follow the repo instructions on how to install it.
 
-## Installation
+#### AIMD simulations with FAIRChem
 
-### Install using `pip`
-
-You can simply install the latest release of the package and all dependencies using:
+For Ab Initio Molecular Dynamics (AIMD) simulations, you need to install [FAIRChem](https://github.com/facebookresearch/fairchem). This provides machine learning potentials for accelerated quantum mechanical simulations. Install it with:
 
 ```bash
-pip install mdinterface
+pip install fairchem-core
 ```
 
-### Install directly the source code
+This functionality is completely optional and the package will work without it for all other features.
+
+## Installation
+
+### System Requirements
+
+- **Python**: 3.8 or higher
+- **PACKMOL**: Required for molecular packing (see below)
+- **Operating System**: Linux, macOS, Windows (with some limitations on Windows)
+
+### Core Installation
 
-Alternatively you can obtain `mdinterface` directly from the repository by following these steps:
+#### Option 1: Install from PyPI (Recommended)
 
-Clone the repository in the desired location:
+Install the latest stable release with all core dependencies:
 
 ```bash
-git clone git@gitlab.com:roncofaber/mdinterface.git
+pip install mdinterface
 ```
 
-Install the package:
+#### Option 2: Install from Source
+
+For the latest development version or to contribute:
 
 ```bash
+# Clone the repository
+git clone https://gitlab.com/roncofaber/mdinterface.git
 cd mdinterface
+
+# Install in normal mode
 pip install .
+
+# Or install in development mode (for contributors)
+pip install -e .
 ```
 
-### Install a development environment
+### Installing PACKMOL
 
-If you plan of making changes, clone the package and add it to your development environment with:
+PACKMOL is required for molecular packing and must be installed separately:
 
+#### Using conda (Recommended):
 ```bash
-pip install --no-build-isolation -e .
+conda install -c conda-forge packmol
 ```
 
-### Install optional packages
+#### From source:
+Follow instructions at [https://m3g.github.io/packmol/](https://m3g.github.io/packmol/)
 
-You can install optional dependencies with the following commands:
+### Optional Dependencies
+
+Install additional features as needed:
 
 ```bash
-# install libarvo to estimate species:
-pip install mdinterface[volume] volumes
-# install pyscf and pymbxas (you still need gpu4pyscf):
+# RESP charge analysis (requires additional setup)
 pip install mdinterface[resp]
-# install all of the above options:
+
+# AIMD simulations with FAIRChem
+pip install mdinterface[aimd]
+
+# All optional dependencies
 pip install mdinterface[all]
 ```
 
+### Verifying Installation
+
+Test your installation:
+
+```python
+import mdinterface
+from mdinterface import SimulationBox, Specie
+print(f"mdinterface version: {mdinterface.__version__}")
+```
+
+### Troubleshooting
+
+#### Common Issues:
+
+1. **PACKMOL not found**: Ensure PACKMOL is in your PATH or install via conda
+2. **Import errors**: Check that all dependencies are properly installed
+3. **Version conflicts**: Use a clean virtual environment
+
+#### Python Environment Setup:
+
+We recommend using a virtual environment:
+
+```bash
+# Create virtual environment
+python -m venv mdinterface-env
+source mdinterface-env/bin/activate  # On Windows: mdinterface-env\Scripts\activate
+
+# Install mdinterface
+pip install mdinterface
+```
+
+#### For conda users:
+
+```bash
+# Create conda environment
+conda create -n mdinterface python=3.10
+conda activate mdinterface
+
+# Install dependencies
+conda install -c conda-forge packmol
+pip install mdinterface
+```
+
 ## Usage
 
 Creating a new Specie (with its topology attributes) is as simple as doing:

mdinterface-1.3.0/mdinterface.egg-info/PKG-INFO → mdinterface-1.4.0/README.md

@@ -1,35 +1,3 @@
-Metadata-Version: 2.4
-Name: mdinterface
-Version: 1.3.0
-Summary: Build Interface Systems for Molecular Dynamics Simulations
-Home-page: https://gitlab.com/roncofaber/mdinterface
-Author: Fabrice Roncoroni
-Author-email: fabrice.roncoroni@gmail.com
-License: Apache-2.0
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Operating System :: OS Independent
-Classifier: Topic :: Software Development
-Classifier: Topic :: Scientific/Engineering
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: mdanalysis
-Requires-Dist: ase
-Requires-Dist: numpy
-Requires-Dist: networkx
-Requires-Dist: platformdirs
-Requires-Dist: configparser
-Provides-Extra: volume
-Requires-Dist: libarvo; extra == "volume"
-Provides-Extra: resp
-Requires-Dist: pyscf; extra == "resp"
-Requires-Dist: pymbxas; extra == "resp"
-Provides-Extra: all
-Requires-Dist: libarvo; extra == "all"
-Requires-Dist: pyscf; 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;">
@@ -50,6 +18,7 @@ Using `mdinterface` you can:
 - Import common molecules/metals/polymers with pre-defined classical force fields parameters from the database, or automatically generate new OPLS-AA force field parameters using [LigParGen](https://github.com/Isra3l/ligpargen).
 - Generate polymer chains of any length from a starting monomer.
 - Estimate the RESP charges of molecules using the [PySCF  electronic structure code](https://github.com/pyscf/pyscf).
+- Perform Ab Initio Molecular Dynamics (AIMD) simulations using [FAIRChem](https://github.com/facebookresearch/fairchem) machine learning potentials (optional).
 - Automatically write LAMMPS data files and coefficients, so you can start making them atoms dance as soon as possible!
 - Integrate your workflow with [MDAnalysis](https://github.com/MDAnalysis/mdanalysis): create your molecules with `mdinterface` and convert them to `mda.Universe` objects with a simple interface.
 
@@ -79,58 +48,124 @@ BOSSdir = /path/to/your/boss/dir
 
 The config directory is found using [`platformdirs`](https://pypi.org/project/platformdirs/) and is OS dependent.
 
-### RESP charge analysis with PySCF
+#### RESP charge analysis with PySCF
 
 To use the RESP charge analysis feature, you need to install [PySCF](https://github.com/pyscf/pyscf) and [PyMBXAS](https://gitlab.com/roncofaber/pymbxas). To my knowledge, the RESP feature is only implemented in [gpu4pyscf](https://github.com/pyscf/gpu4pyscf) at the moment, so follow the repo instructions on how to install it.
 
-## Installation
-
-### Install using `pip`
+#### AIMD simulations with FAIRChem
 
-You can simply install the latest release of the package and all dependencies using:
+For Ab Initio Molecular Dynamics (AIMD) simulations, you need to install [FAIRChem](https://github.com/facebookresearch/fairchem). This provides machine learning potentials for accelerated quantum mechanical simulations. Install it with:
 
 ```bash
-pip install mdinterface
+pip install fairchem-core
 ```
 
-### Install directly the source code
+This functionality is completely optional and the package will work without it for all other features.
+
+## Installation
+
+### System Requirements
+
+- **Python**: 3.8 or higher
+- **PACKMOL**: Required for molecular packing (see below)
+- **Operating System**: Linux, macOS, Windows (with some limitations on Windows)
 
-Alternatively you can obtain `mdinterface` directly from the repository by following these steps:
+### Core Installation
 
-Clone the repository in the desired location:
+#### Option 1: Install from PyPI (Recommended)
+
+Install the latest stable release with all core dependencies:
 
 ```bash
-git clone git@gitlab.com:roncofaber/mdinterface.git
+pip install mdinterface
 ```
 
-Install the package:
+#### Option 2: Install from Source
+
+For the latest development version or to contribute:
 
 ```bash
+# Clone the repository
+git clone https://gitlab.com/roncofaber/mdinterface.git
 cd mdinterface
+
+# Install in normal mode
 pip install .
+
+# Or install in development mode (for contributors)
+pip install -e .
 ```
 
-### Install a development environment
+### Installing PACKMOL
 
-If you plan of making changes, clone the package and add it to your development environment with:
+PACKMOL is required for molecular packing and must be installed separately:
 
+#### Using conda (Recommended):
 ```bash
-pip install --no-build-isolation -e .
+conda install -c conda-forge packmol
 ```
 
-### Install optional packages
+#### From source:
+Follow instructions at [https://m3g.github.io/packmol/](https://m3g.github.io/packmol/)
+
+### Optional Dependencies
 
-You can install optional dependencies with the following commands:
+Install additional features as needed:
 
 ```bash
-# install libarvo to estimate species:
-pip install mdinterface[volume] volumes
-# install pyscf and pymbxas (you still need gpu4pyscf):
+# RESP charge analysis (requires additional setup)
 pip install mdinterface[resp]
-# install all of the above options:
+
+# AIMD simulations with FAIRChem
+pip install mdinterface[aimd]
+
+# All optional dependencies
 pip install mdinterface[all]
 ```
 
+### Verifying Installation
+
+Test your installation:
+
+```python
+import mdinterface
+from mdinterface import SimulationBox, Specie
+print(f"mdinterface version: {mdinterface.__version__}")
+```
+
+### Troubleshooting
+
+#### Common Issues:
+
+1. **PACKMOL not found**: Ensure PACKMOL is in your PATH or install via conda
+2. **Import errors**: Check that all dependencies are properly installed
+3. **Version conflicts**: Use a clean virtual environment
+
+#### Python Environment Setup:
+
+We recommend using a virtual environment:
+
+```bash
+# Create virtual environment
+python -m venv mdinterface-env
+source mdinterface-env/bin/activate  # On Windows: mdinterface-env\Scripts\activate
+
+# Install mdinterface
+pip install mdinterface
+```
+
+#### For conda users:
+
+```bash
+# Create conda environment
+conda create -n mdinterface python=3.10
+conda activate mdinterface
+
+# Install dependencies
+conda install -c conda-forge packmol
+pip install mdinterface
+```
+
 ## Usage
 
 Creating a new Specie (with its topology attributes) is as simple as doing:

{mdinterface-1.3.0 → mdinterface-1.4.0}/mdinterface/__init__.py

@@ -6,8 +6,8 @@ Initially developed to construct electrolyte/electrode interfaces, it is also we
 
 """
 
-__version__ = '1.3.0'
-__date__ = '17 Jul. 2025'
+__version__ = '1.4.0'
+__date__ = '14 Oct. 2025'
 __author__ = 'Fabrice Roncoroni'
 __all__ = ['SimulationBox', "Specie", "Polymer"]
 

{mdinterface-1.3.0 → mdinterface-1.4.0}/mdinterface/build/box.py

@@ -6,6 +6,7 @@ Created on Tue Jan 14 10:23:57 2025
 @author: roncofaber
 """
 
+from typing import List, Optional, Union, Tuple, Dict, Any
 from mdinterface.io.packmol import header, box_place, fix_place
 from mdinterface.build.continuum2sim import discretize_concentration
 
@@ -18,13 +19,129 @@ import subprocess
 
 #%%
 
-def make_solvent_box(species, solvent, ions, volume, density, nions, concentration,
-                     conmodel, ion_pos):
-    
-    # make sure info is sound
-    assert not( nions is not None and concentration is not None),\
-        "'nions' and 'concentration' cannot both be not None"
-    
+def _validate_solvent_box_parameters(
+    nions: Optional[Union[int, List[int]]],
+    concentration: Optional[float],
+    conmodel: Optional[Dict[int, Tuple[List[float], List[float]]]],
+    ions: Optional[List[Any]],
+    solvent: Optional[Any],
+    density: Optional[float],
+    nsolvent: Optional[int] = None
+) -> None:
+    """
+    Validate parameter combinations for make_solvent_box function.
+
+    Raises appropriate errors for invalid parameter combinations.
+    """
+
+    # Basic mutual exclusivity check
+    if nions is not None and concentration is not None:
+        raise ValueError("Cannot specify both 'nions' and 'concentration'. Use one or the other.")
+
+    # If concentration model is provided, ions must be provided
+    if conmodel is not None and (ions is None or len(ions) == 0):
+        raise ValueError("When using 'conmodel', 'ions' must be provided and non-empty.")
+
+    # If nions is a list, it must match the number of ion species
+    if isinstance(nions, (list, tuple)) and ions is not None:
+        if len(nions) != len(ions):
+            raise ValueError(f"Length of 'nions' ({len(nions)}) must match number of ion species ({len(ions)}).")
+
+    # Validate density vs nsolvent mutual exclusivity
+    if density is not None and nsolvent is not None:
+        import warnings
+        warnings.warn(
+            "Both 'density' and 'nsolvent' are specified. Using 'nsolvent' and ignoring 'density'.",
+            UserWarning, stacklevel=4
+        )
+
+    # If solvent density or nsolvent is provided but no solvent, warn the user
+    if (density is not None or nsolvent is not None) and solvent is None:
+        import warnings
+        warnings.warn("Density or nsolvent specified but no solvent provided. Will be ignored.",
+                     UserWarning, stacklevel=4)
+
+    # If no solvent and no ions, nothing to do
+    if solvent is None and (ions is None or len(ions) == 0):
+        import warnings
+        warnings.warn("No solvent or ions specified. Empty box will be created.",
+                     UserWarning, stacklevel=3)
+
+def make_solvent_box(
+    species: List[Any],
+    solvent: Optional[Any],
+    ions: Optional[List[Any]],
+    volume: List[float],
+    density: Optional[float],
+    nions: Optional[Union[int, List[int]]],
+    concentration: Optional[float],
+    conmodel: Optional[Dict[int, Tuple[List[float], List[float]]]],
+    ion_pos: Optional[str],
+    nsolvent: Optional[int] = None
+) -> Optional[mda.Universe]:
+    """
+    Build a solvent box with optional ionic species.
+
+    This function creates a simulation box containing solvent molecules and ionic species
+    using PACKMOL for molecular packing. It supports various placement strategies and
+    concentration models.
+
+    Parameters:
+    -----------
+    species : list
+        List of all available species in the simulation
+    solvent : object or None
+        Solvent molecule object (e.g., Water). If None, only ions are placed.
+    ions : list or None
+        List of ionic species to add to the box
+    volume : list
+        Box dimensions [x, y, z] in Angstroms
+    density : float or None
+        Solvent density in g/cm³. Ignored if solvent is None or if nsolvent is specified.
+    nions : int, list, or None
+        Number of each ionic species. Can be:
+        - int: Same number for all ion types
+        - list: Different number for each ion type (must match len(ions))
+        - None: No ions added
+    concentration : float or None
+        Ionic concentration in Molar. Alternative to nions.
+        Cannot be used simultaneously with nions.
+    conmodel : dict or None
+        Advanced concentration model for spatially varying concentrations.
+        Format: {ion_index: (z_coords, concentration_profile)}
+    ion_pos : str or None
+        Ion placement strategy:
+        - "random": Random placement (default)
+        - "center": Place all ions at box center
+        - "box": Use PACKMOL box placement
+        - "left": Constrain to left half of box
+        - None: Defaults to "random"
+    nsolvent : int or None
+        Number of solvent molecules to place. If specified, takes precedence over density.
+        Cannot be used simultaneously with density.
+
+    Returns:
+    --------
+    MDAnalysis.Universe or None
+        Merged universe containing solvent and ions, or None if no components
+
+    Examples:
+    ---------
+    # Simple water box with NaCl
+    make_solvent_box(species, water, [na, cl], [20, 20, 20], 1.0, [5, 5], None, None, "random")
+
+    # Concentration-based approach
+    make_solvent_box(species, water, [na, cl], [20, 20, 20], 1.0, None, 0.1, None, "random")
+
+    # Complex polymer solution
+    make_solvent_box(species, None, [polymer, hydronium, water], [50, 50, 50], None, [10, 50, 200], None, None, "box")
+    """
+
+    # Validate parameter combinations
+    _validate_solvent_box_parameters(nions, concentration, conmodel, ions, solvent, density, nsolvent)
+
+    # Legacy parameter compatibility is handled in the calling function (simulationbox.py)
+
     # convert concentration to number of ions
     if concentration is not None:
         nions = int(concentration*np.prod(volume)*units.mol/((units.m/10)**3))
@@ -40,12 +157,18 @@ def make_solvent_box(species, solvent, ions, volume, density, nions, concentrati
     
     # add solvent
     if solvent is not None:
-        solvent_volume   = 1e-24*np.prod(volume)
-        mass = solvent.atoms.masses.sum()
+        if nsolvent is not None:
+            # Use directly specified number of solvent molecules
+            nummols = nsolvent
+        elif density is not None:
+            # Calculate number of solvent molecules from density
+            solvent_volume = 1e-24*np.prod(volume)
+            mass = solvent.atoms.masses.sum()
+            nummols = int(units.mol*density*(1.0/mass)*solvent_volume)
+        else:
+            # This should be caught by validation, but defensive programming
+            raise ValueError("Either 'density' or 'nsolvent' must be specified for solvent placement")
 
-        # number of solvent molecules
-        nummols = int(units.mol*density*(1.0/mass)*solvent_volume)
-        
         instructions.append([solvent, nummols, "box"])
 
     # generate universe file
@@ -70,9 +193,12 @@ def make_solvent_box(species, solvent, ions, volume, density, nions, concentrati
     
     return solution
     
-# populate a box with solvent and ions
-def populate_box(volume, instructions, input_file="input_packmol.in",
-                 output_file="system.pdb"):
+def populate_box(
+    volume: List[float],
+    instructions: List[Tuple[Any, Union[int, List[float]], str]],
+    input_file: str = "input_packmol.in",
+    output_file: str = "system.pdb"
+) -> Optional[mda.Universe]:
 
     if not instructions:
         return None
@@ -168,6 +294,7 @@ def make_interface_slab(interface_uc, xsize, ysize, layers=1):
 
 #THANKS CHATGPT (but mostly me tbh)
 def populate_with_ions(ions, nions, volume, ion_pos=False, conmodel=None):
+    
     def place_ion(ion, volume, ion_coords, ion_radii, zpos=None, max_attempts=100):
         ion_radius = ion.estimate_specie_radius()
         for _ in range(max_attempts):