mdinterface 1.2.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.4.0/PKG-INFO

@@ -0,0 +1,237 @@
+Metadata-Version: 2.4
+Name: mdinterface
+Version: 1.4.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 designed to build systems for Molecular Dynamics (MD) simulations. Initially developed to construct electrolyte/electrode solid-liquid interfaces, it is also well-suited for generating MD boxes of liquids, electrolyte systems, and polymer networks.
+
+## Features
+
+Using `mdinterface` you can:
+
+- Create layered simulation boxes with solvents, solutes, and interface slabs.
+- Populate your system with ions and solvents using PACKMOL, and provide the starting concentration profile of the species to get the MD where you want it to be, but faster.
+- 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.
+
+## Requirements
+
+Check the file [requirements.txt](requirements.txt) to see which packages are needed. Installing the package using `pip` should already take care of all mandatory dependencies.
+
+Additionally, you need the `packmol` utility installed to generate MD boxes. You can follow the instructions at [https://m3g.github.io/packmol/](https://m3g.github.io/packmol/) to install it. Alternatively, you can install it using `conda`:
+
+```bash
+conda install -c conda-forge packmol
+```
+
+### Optional packages
+
+#### Automatic OPLS-AA force field generator with LigParGen
+
+If you want to use LigParGen, please follow the instructions on their [GitHub](https://github.com/Isra3l/ligpargen). If you are having trouble installing, you can try my own [fork](https://github.com/roncofaber/ligpargen) of the original repo. To make sure that BOSS is recognized by the package, specify the environment variable `BOSSdir`.
+
+You can do this manually every time, or just add the path to the `config.ini` file to your config directory:
+
+```bash
+# config.ini
+[settings]
+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
+
+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.
+
+#### AIMD simulations with FAIRChem
+
+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 fairchem-core
+```
+
+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
+
+#### Option 1: Install from PyPI (Recommended)
+
+Install the latest stable release with all core dependencies:
+
+```bash
+pip install mdinterface
+```
+
+#### 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 .
+```
+
+### Installing PACKMOL
+
+PACKMOL is required for molecular packing and must be installed separately:
+
+#### Using conda (Recommended):
+```bash
+conda install -c conda-forge packmol
+```
+
+#### From source:
+Follow instructions at [https://m3g.github.io/packmol/](https://m3g.github.io/packmol/)
+
+### Optional Dependencies
+
+Install additional features as needed:
+
+```bash
+# RESP charge analysis (requires additional setup)
+pip install mdinterface[resp]
+
+# 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:
+
+```python
+#%% Make a specie, and use LigParGen to estimate FF parameters
+my_specie = Specie("CH3ONO", ligpargen=True) # molecule is in ASE database
+
+# make a specie from any ASE readable file
+my_specie = Specie("methylnitrite.xyz", ligpargen=True)
+
+# convert specie to mdanalysis universe (and all the attributes!)
+my_specie.to_universe()
+
+```
+
+Please, check the files in [examples](mdinterface/examples/) to learn how to use the package. Including setting up simulation boxes, creating polymers, perform RESP analysis and much more!
+
+## 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.4.0/README.md

@@ -0,0 +1,193 @@
+<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 designed to build systems for Molecular Dynamics (MD) simulations. Initially developed to construct electrolyte/electrode solid-liquid interfaces, it is also well-suited for generating MD boxes of liquids, electrolyte systems, and polymer networks.
+
+## Features
+
+Using `mdinterface` you can:
+
+- Create layered simulation boxes with solvents, solutes, and interface slabs.
+- Populate your system with ions and solvents using PACKMOL, and provide the starting concentration profile of the species to get the MD where you want it to be, but faster.
+- 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.
+
+## Requirements
+
+Check the file [requirements.txt](requirements.txt) to see which packages are needed. Installing the package using `pip` should already take care of all mandatory dependencies.
+
+Additionally, you need the `packmol` utility installed to generate MD boxes. You can follow the instructions at [https://m3g.github.io/packmol/](https://m3g.github.io/packmol/) to install it. Alternatively, you can install it using `conda`:
+
+```bash
+conda install -c conda-forge packmol
+```
+
+### Optional packages
+
+#### Automatic OPLS-AA force field generator with LigParGen
+
+If you want to use LigParGen, please follow the instructions on their [GitHub](https://github.com/Isra3l/ligpargen). If you are having trouble installing, you can try my own [fork](https://github.com/roncofaber/ligpargen) of the original repo. To make sure that BOSS is recognized by the package, specify the environment variable `BOSSdir`.
+
+You can do this manually every time, or just add the path to the `config.ini` file to your config directory:
+
+```bash
+# config.ini
+[settings]
+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
+
+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.
+
+#### AIMD simulations with FAIRChem
+
+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 fairchem-core
+```
+
+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
+
+#### Option 1: Install from PyPI (Recommended)
+
+Install the latest stable release with all core dependencies:
+
+```bash
+pip install mdinterface
+```
+
+#### 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 .
+```
+
+### Installing PACKMOL
+
+PACKMOL is required for molecular packing and must be installed separately:
+
+#### Using conda (Recommended):
+```bash
+conda install -c conda-forge packmol
+```
+
+#### From source:
+Follow instructions at [https://m3g.github.io/packmol/](https://m3g.github.io/packmol/)
+
+### Optional Dependencies
+
+Install additional features as needed:
+
+```bash
+# RESP charge analysis (requires additional setup)
+pip install mdinterface[resp]
+
+# 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:
+
+```python
+#%% Make a specie, and use LigParGen to estimate FF parameters
+my_specie = Specie("CH3ONO", ligpargen=True) # molecule is in ASE database
+
+# make a specie from any ASE readable file
+my_specie = Specie("methylnitrite.xyz", ligpargen=True)
+
+# convert specie to mdanalysis universe (and all the attributes!)
+my_specie.to_universe()
+
+```
+
+Please, check the files in [examples](mdinterface/examples/) to learn how to use the package. Including setting up simulation boxes, creating polymers, perform RESP analysis and much more!
+
+## 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.2.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.2.0'
-__date__ = '28 Mar. 2025'
+__version__ = '1.4.0'
+__date__ = '14 Oct. 2025'
 __author__ = 'Fabrice Roncoroni'
 __all__ = ['SimulationBox', "Specie", "Polymer"]
 

{mdinterface-1.2.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):