mdinterface 1.0.0__tar.gz → 1.2.0__tar.gz

mdinterface-1.2.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.2
+Name: mdinterface
+Version: 1.2.0
+Summary: mdinterface: A package for building interface systems in Molecular Dynamics simulations.
+Home-page: https://gitlab.com/roncofaber/mdinterface
+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.6
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mdanalysis
+Requires-Dist: ase
+Requires-Dist: numpy
+Requires-Dist: networkx
+Requires-Dist: libarvo
+Requires-Dist: platformdirs
+Requires-Dist: configparser
+
+<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 [https://github.com/Isra3l/ligpargen](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).
+- Automatically write LAMMPS data files and coefficients, so you can start making them atoms dance!
+
+## 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.
+
+Additionaly, 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). 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).
+
+## Installation
+
+### Install using `pip`
+
+You can simply install the latest release of the package and all dependencies using:
+
+```bash
+pip install mdinterface
+```
+
+### Install directly the source code
+
+Alternatively you can obtain `mdinterface` directly from the repository by following these steps:
+
+Clone the repository in the desired location:
+
+```bash
+git clone git@gitlab.com:roncofaber/mdinterface.git
+```
+
+Install the required packages:
+
+```bash
+cd mdinterface
+conda install -c conda-forge --file requirements.txt
+```
+
+Install the package with pip:
+
+```bash
+pip install .
+```
+
+### Install a development environment
+
+If you plan of making changes, clone the package and install the requirements but then add it to your development environment with:
+
+```bash
+pip install --no-build-isolation --no-deps -e .
+```
+
+## 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
+```
+
+Please, check the files in [examples](mdinterface/examples/) to learn how to use the package. Including setting up simulation boxes, creating polymers 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/README.md

@@ -0,0 +1,111 @@
+<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 [https://github.com/Isra3l/ligpargen](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).
+- Automatically write LAMMPS data files and coefficients, so you can start making them atoms dance!
+
+## 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.
+
+Additionaly, 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). 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).
+
+## Installation
+
+### Install using `pip`
+
+You can simply install the latest release of the package and all dependencies using:
+
+```bash
+pip install mdinterface
+```
+
+### Install directly the source code
+
+Alternatively you can obtain `mdinterface` directly from the repository by following these steps:
+
+Clone the repository in the desired location:
+
+```bash
+git clone git@gitlab.com:roncofaber/mdinterface.git
+```
+
+Install the required packages:
+
+```bash
+cd mdinterface
+conda install -c conda-forge --file requirements.txt
+```
+
+Install the package with pip:
+
+```bash
+pip install .
+```
+
+### Install a development environment
+
+If you plan of making changes, clone the package and install the requirements but then add it to your development environment with:
+
+```bash
+pip install --no-build-isolation --no-deps -e .
+```
+
+## 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
+```
+
+Please, check the files in [examples](mdinterface/examples/) to learn how to use the package. Including setting up simulation boxes, creating polymers 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/__init__.py

@@ -0,0 +1,20 @@
+"""
+mdinterface: Build Interface Systems for Molecular Dynamics Simulations
+
+`mdinterface` is a Python package designed to build systems for Molecular Dynamics (MD) simulations.
+Initially developed to construct electrolyte/electrode interfaces, it is also well-suited for generating MD boxes of liquids, electrolyte systems, and polymer networks.
+
+"""
+
+__version__ = '1.2.0'
+__date__ = '28 Mar. 2025'
+__author__ = 'Fabrice Roncoroni'
+__all__ = ['SimulationBox', "Specie", "Polymer"]
+
+from .simulationbox import SimulationBox
+from .core.specie import Specie
+from .core.polymer import Polymer
+
+# load configuration file
+from .config import load_config
+load_config()

mdinterface-1.2.0/mdinterface/build/__init__.py

@@ -0,0 +1,3 @@
+from .polymerize import *
+from .box import *
+from .continuum2sim import *

mdinterface-1.2.0/mdinterface/build/box.py

@@ -0,0 +1,254 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created on Tue Jan 14 10:23:57 2025
+
+@author: roncofaber
+"""
+
+from mdinterface.io.packmol import header, box_place, fix_place
+from mdinterface.build.continuum2sim import discretize_concentration
+
+import MDAnalysis as mda
+from ase import units
+
+import numpy as np
+
+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"
+    
+    # convert concentration to number of ions
+    if concentration is not None:
+        nions = int(concentration*np.prod(volume)*units.mol/((units.m/10)**3))
+    
+    # define instructions for packmol
+    instructions = []
+     
+    # populate ions
+    if (conmodel is not None) or (nions is not None and ions is not None):
+        ion_instr = populate_with_ions(ions, nions, volume, ion_pos=ion_pos,
+                                       conmodel=conmodel)
+        instructions.extend(ion_instr)
+    
+    # add solvent
+    if solvent is not None:
+        solvent_volume   = 1e-24*np.prod(volume)
+        mass = solvent.atoms.masses.sum()
+
+        # number of solvent molecules
+        nummols = int(units.mol*density*(1.0/mass)*solvent_volume)
+        
+        instructions.append([solvent, nummols, "box"])
+
+    # generate universe file
+    universe = populate_box(volume, instructions)
+    
+    if universe is None:
+        return None
+    
+    # Create a dictionary for quick lookup of species by residue name
+    species_dict = {specie.residues.resnames[0]: specie for specie in species}
+    
+    alist = []
+    for res in universe.residues:
+        resname = res.resname
+        if resname in species_dict:
+            nmol = species_dict[resname].copy()
+            nmol.atoms.positions = res.atoms.positions
+            alist.append(nmol.atoms)
+    
+    solution = mda.Merge(*alist)
+    solution.dimensions = volume + [90,90,90]
+    
+    return solution
+    
+# populate a box with solvent and ions
+def populate_box(volume, instructions, input_file="input_packmol.in",
+                 output_file="system.pdb"):
+
+    if not instructions:
+        return None
+
+    # check volume
+    assert len(volume) == 3, "Check volume!"
+    
+    # generate box boundaries with 1 AA padding
+    box = np.concatenate(([1,1,1], np.asarray(volume)-1)).tolist()
+    
+    tmp_files = ["packmol.log", "input_packmol.in", "system.pdb"]
+    with open(input_file, "w") as fout:
+        
+        fout.write(header.format(output_file, np.random.randint(100000)))
+        
+        for cc, instruction in enumerate(instructions):
+            
+            # unpack instructions
+            mol = instruction[0]
+            rep = instruction[1]
+            typ = instruction[2]
+            
+            if isinstance(rep, int):
+                if not rep:
+                    continue
+            
+            if typ == "box": # normal add
+                fout.write(box_place.format(cc, rep, " ".join(map(str, box))))
+            
+            elif typ == "fixed": # coordinate -> fixed point
+                fout.write(fix_place.format(cc, *rep))
+                
+            elif typ == "zfixed": # small bin to use in CM
+                tbox = box.copy()
+                tbox[2] = tbox[2] - mol.estimate_specie_radius()
+                tbox[5] = tbox[5] + mol.estimate_specie_radius()
+                fout.write(box_place.format(cc, 1, " ".join(map(str, tbox))))
+                mol = mol.to_universe()
+            
+            else:
+                raise "Wrong instructions"
+            
+            # write tmp pdb file and store info
+            mol.atoms.write("mol_{}.pdb".format(cc))
+            tmp_files.append("mol_{}.pdb".format(cc))
+            
+    # run packmol
+    try:
+        subprocess.run(['packmol < {} > packmol.log'.format(input_file)],
+                       shell=True, check=True, text=True)
+
+    except:
+        print("WARNING: packmol might not have worked, check system.")
+    
+    try:
+        universe = mda.Universe(output_file)
+    except:
+        universe = None
+
+    # remove temp mol files and packmol files
+    subprocess.call(['rm'] + tmp_files)
+    
+    return universe
+
+# generate a slab from a unit cell
+def make_interface_slab(interface_uc, xsize, ysize, layers=1):
+    
+    if layers == 0 or interface_uc is None:
+        return None
+    
+    xrep = int(np.round(xsize/interface_uc.atoms.get_cell()[0][0]))
+    yrep = int(np.round(ysize/interface_uc.atoms.get_cell()[1][1]))
+    
+    slab = interface_uc.copy()
+    
+    if not np.isclose(np.dot(slab.atoms.cell[0], [1,0,0]), slab.atoms.cell[0][0]):
+        xrep +=1
+        print("WARNING: check interface if pattern matches")
+    
+    if not np.isclose(np.dot(slab.atoms.cell[1], [0,1,0]), slab.atoms.cell[1][1]):
+        yrep +=1
+        print("WARNING: check interface if pattern matches")
+        
+    slab.repeat((xrep, yrep, 1), make_cubic=True)
+    
+    if layers > 1: # helps with indexing
+        slab.repeat([1,1,layers])
+    
+    slab.atoms.center()
+    # slab.atoms.rattle()
+    
+    return slab
+
+#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):
+            new_coord = ion_radius + 1 + np.random.rand(3) * (volume - 2 * (ion_radius + 1))
+            if zpos is not None:
+                new_coord[2] = zpos
+                
+            if not ion_coords or np.all(np.linalg.norm(ion_coords - new_coord, axis=1) >= np.array(ion_radii) + ion_radius + 1):
+                return new_coord
+        print(f"Warning: Failed to place ion {ion} after {max_attempts} attempts")
+        return None
+
+    def place_ions_conmodel(ions, conmodel, volume, max_attempts=100):
+        instructions = []
+        ion_coords = []
+        ion_radii = []
+        for cc, ion in enumerate(ions):
+            z_coords, conc_profile = conmodel[cc]
+            z_positions = discretize_concentration(ion, conc_profile, z_coords, volume)
+            for zpos in z_positions:
+                new_coord = place_ion(ion, volume, ion_coords, ion_radii, zpos=zpos,
+                                      max_attempts=max_attempts)
+                if new_coord is not None:
+                    ion_coords.append(new_coord)
+                    ion_radii.append(ion.estimate_specie_radius())
+                    instructions.append((ion.to_universe(), new_coord, "fixed"))
+        return instructions
+
+    def place_ions_random(ions, nions, volume, to_center, max_attempts=100):
+        instructions = []
+        ion_coords = []
+        ion_radii = []
+        for cc, ion in enumerate(ions):
+            nrep = nions if isinstance(nions, int) else nions[cc]
+            for _ in range(nrep):
+                new_coord = volume / 2 if to_center else place_ion(ion, volume,
+                                                                   ion_coords,
+                                                                   ion_radii,
+                                                                   max_attempts=max_attempts)
+                if new_coord is not None:
+                    ion_coords.append(new_coord)
+                    ion_radii.append(ion.estimate_specie_radius())
+                    instructions.append((ion.to_universe(), new_coord, "fixed"))
+        return instructions
+
+    max_attempts = 100  # Limit placement attempts to avoid infinite loop
+    volume = np.array(volume)
+
+    if conmodel is not None:
+        assert len(conmodel) == len(ions), "Need one profile per specie"
+        return place_ions_conmodel(ions, conmodel, volume, max_attempts=max_attempts)
+
+    if ion_pos == "box":
+        return [(ion.to_universe(), nions if isinstance(nions, int) else nions[cc], "box") for cc, ion in enumerate(ions)]
+
+    to_center = ion_pos == "center"
+    if ion_pos == "left":
+        volume[2] /= 2
+
+    return place_ions_random(ions, nions, volume, to_center, max_attempts=max_attempts)
+
+
+# add a component to the system
+def add_component(system, component, zdim, padding=0):
+    
+    # nothing to add here
+    if component is None:
+        return system, zdim
+    
+    # ohh, let's lego the shit out of this
+    component = component.copy()
+    
+    # component: "look at me, I am the system now."
+    if system is None:
+        component.atoms.translate([0, 0, zdim])
+        system = component
+        zdim += component.dimensions[2]
+    
+    # make space and add it to the pile
+    else:
+        component.atoms.translate([0, 0, zdim + padding])
+        system = mda.Merge(system.atoms, component.atoms)
+        zdim += component.dimensions[2] + padding
+    return system, zdim

mdinterface-1.2.0/mdinterface/build/charges.py

@@ -0,0 +1,8 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created on Mon Feb  3 14:50:47 2025
+
+@author: roncofaber
+"""
+

mdinterface-1.2.0/mdinterface/build/continuum2sim.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created on Tue Jan 14 10:34:26 2025
+
+@author: roncofaber
+"""
+
+from ase import units
+import numpy as np
+from scipy import integrate
+
+#%%
+# return a discrete concentration profile given a "continuum" conc. profile
+# for a specie. Return positions of the bins where ion should be.
+def discretize_concentration(specie, conc_profile, z_coords, volume):
+    
+    xsize, ysize, zsize = volume
+
+    conv = units.mol/1e27
+    area = xsize*ysize
+
+    # integrate conc. prof. over area
+    cumsum = integrate.cumulative_trapezoid(conc_profile, z_coords, initial=0, axis=0)
+    cumsum_conv = cumsum*conv*area
+
+    # generate bins (1 atom in each one) for K
+    Nions = 0
+    bins = []
+    for ii, con in enumerate(cumsum_conv):
+        if con > np.maximum(cumsum_conv.max()/100, Nions):
+            Nions += 1
+            bins.append(z_coords[ii])        
+    
+    # now find middle point of bins
+    z_pos = []
+    for ii, pos in enumerate(bins[:-1]):
+        z_pos.append((bins[ii] + bins[ii+1])/2)
+        
+    # add one last ion
+    if cumsum_conv.max() % 1 > 0.5:
+        z_pos.append((z_coords.max()+bins[-1])/2)
+        Nions += 1
+    
+    return z_pos

mdinterface-1.2.0/mdinterface/build/polymerize.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created on Tue Oct 22 17:17:30 2024
+
+@author: roncofaber
+"""
+
+import numpy as np
+import ase
+import ase.build
+
+#%%
+
+def build_polymer(monomer, substitute, nrep, start_end_idxs=None, target_distance=1.600):
+    """
+    Build a polymer by replicating a monomer structure and replacing 'X' atoms with a substitute.
+
+    Parameters:
+    - monomer (ase.Atoms): The monomer structure as an ASE Atoms object.
+    - substitute (str): Chemical symbol to replace 'X' with after replication.
+    - nrep (int): Number of times to replicate the monomer.
+    - target_distance (float, optional): Desired bond distance at the joining points (in angstroms). 
+      If None, the original distance between 'X' atoms is used.
+
+    Returns:
+    - sout (ase.Atoms): The replicated and modified polymer structure.
+    """
+    
+    # make sure we don't mess nothing
+    monomer = monomer.copy()
+    
+    # if start end is provided, do substitution here
+    if start_end_idxs is not None:
+        assert len(start_end_idxs) == 2
+        symbols = monomer.get_chemical_symbols()
+        symbols[start_end_idxs[0]] = "X"
+        symbols[start_end_idxs[1]] = "X"
+        monomer.set_chemical_symbols(symbols)
+    
+    # Check if nrep is at least 1
+    if nrep < 1:
+        raise ValueError("nrep must be at least 1")
+
+    # Find the indices of the 'X' atoms
+    x_idxs = np.where(np.array(monomer.get_chemical_symbols()) == "X")[0]
+    if len(x_idxs) != 2:
+        raise ValueError("The monomer should contain exactly two 'X' atoms.")
+
+    # Find atoms connected to X
+    ini_idx = ase.build.connected_indices(monomer, x_idxs[0])[1]
+    end_idx = ase.build.connected_indices(monomer, x_idxs[1])[1]
+
+    bnd_vec = monomer.get_distance(end_idx, x_idxs[1], vector=True)
+    bnd_vec = target_distance * bnd_vec / np.linalg.norm(bnd_vec)
+
+    ini_pos = monomer.get_positions()[ini_idx]
+    end_pos = monomer.get_positions()[end_idx] + bnd_vec
+
+    # Get the vector between the two 'X' atoms
+    X_vec = end_pos - ini_pos
+    
+    # remember connecting points
+    is_connected = np.array(len(monomer)*[False])
+    is_connected[ini_idx] = True
+    is_connected[end_idx] = True
+    monomer.new_array("is_connected", is_connected)
+    
+    # Start with a copy of the monomer
+    sout = monomer.copy()
+    sout.new_array("mon_id", np.array(len(sout)*[0]))
+    
+    # Replicate the monomer
+    if nrep > 1:
+        del sout[x_idxs[1]]  # Remove the second 'X' atom in the first monomer
+
+    for ii in range(nrep - 1):
+        sadd = monomer.copy()
+
+        if ii < nrep - 2:
+            del sadd[x_idxs]  # Remove both 'X' atoms in the intermediate monomers
+        else:
+            del sadd[x_idxs[0]]  # Remove the first 'X' atom in the last monomer
+
+        sadd.translate((ii + 1) * X_vec)
+        sadd.set_array("mon_id", np.array(len(sadd)*[ii+1]))
+        sout += sadd
+
+    # Replace 'X' with the substitute
+    symbols = np.array(sout.get_chemical_symbols())
+    symbols[symbols == "X"] = substitute
+    sout.set_chemical_symbols(symbols)
+    sout.center()
+
+    return sout