mdinterface 1.1.0__tar.gz → 1.3.0__tar.gz

mdinterface-1.3.0/PKG-INFO

@@ -0,0 +1,158 @@
+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;">
+    <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).
+- 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.
+
+## 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 package:
+
+```bash
+cd mdinterface
+pip install .
+```
+
+### Install a development environment
+
+If you plan of making changes, clone the package and add it to your development environment with:
+
+```bash
+pip install --no-build-isolation -e .
+```
+
+### Install optional packages
+
+You can install optional dependencies with the following commands:
+
+```bash
+# install libarvo to estimate species:
+pip install mdinterface[volume] volumes
+# install pyscf and pymbxas (you still need gpu4pyscf):
+pip install mdinterface[resp]
+# install all of the above options:
+pip install mdinterface[all]
+```
+
+## 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.3.0/README.md

@@ -0,0 +1,126 @@
+<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).
+- 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.
+
+## 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 package:
+
+```bash
+cd mdinterface
+pip install .
+```
+
+### Install a development environment
+
+If you plan of making changes, clone the package and add it to your development environment with:
+
+```bash
+pip install --no-build-isolation -e .
+```
+
+### Install optional packages
+
+You can install optional dependencies with the following commands:
+
+```bash
+# install libarvo to estimate species:
+pip install mdinterface[volume] volumes
+# install pyscf and pymbxas (you still need gpu4pyscf):
+pip install mdinterface[resp]
+# install all of the above options:
+pip install mdinterface[all]
+```
+
+## 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.3.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.3.0'
+__date__ = '17 Jul. 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.1.0 → mdinterface-1.3.0}/mdinterface/build/__init__.py

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

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

@@ -47,7 +47,7 @@ def make_solvent_box(species, solvent, ions, volume, density, nions, concentrati
         nummols = int(units.mol*density*(1.0/mass)*solvent_volume)
         
         instructions.append([solvent, nummols, "box"])
-    
+
     # generate universe file
     universe = populate_box(volume, instructions)
     
@@ -228,3 +228,27 @@ def populate_with_ions(ions, nions, volume, ion_pos=False, conmodel=None):
         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.3.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.1.0/mdinterface/build/polymer.py → mdinterface-1.3.0/mdinterface/build/polymerize.py

@@ -12,12 +12,12 @@ import ase.build
 
 #%%
 
-def build_polymer(system, substitute, nrep, target_distance=1.600):
+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:
-    - system (ase.Atoms): The monomer structure as an ASE Atoms object.
+    - 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). 
@@ -27,38 +27,47 @@ def build_polymer(system, substitute, nrep, target_distance=1.600):
     - sout (ase.Atoms): The replicated and modified polymer structure.
     """
     
-    system = system.copy()
+    # 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(system.get_chemical_symbols()) == "X")[0]
+    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(system, x_idxs[0])[1]
-    end_idx = ase.build.connected_indices(system, x_idxs[1])[1]
+    ini_idx = ase.build.connected_indices(monomer, x_idxs[0])[1]
+    end_idx = ase.build.connected_indices(monomer, x_idxs[1])[1]
 
-    bnd_vec = system.get_distance(end_idx, x_idxs[1], vector=True)
+    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 = system.get_positions()[ini_idx]
-    end_pos = system.get_positions()[end_idx] + 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(system)*[False])
+    is_connected = np.array(len(monomer)*[False])
     is_connected[ini_idx] = True
     is_connected[end_idx] = True
-    system.new_array("is_connected", is_connected)
+    monomer.new_array("is_connected", is_connected)
     
-    # Start with a copy of the system
-    sout = system.copy()
+    # Start with a copy of the monomer
+    sout = monomer.copy()
     sout.new_array("mon_id", np.array(len(sout)*[0]))
     
     # Replicate the monomer
@@ -66,7 +75,7 @@ def build_polymer(system, substitute, nrep, target_distance=1.600):
         del sout[x_idxs[1]]  # Remove the second 'X' atom in the first monomer
 
     for ii in range(nrep - 1):
-        sadd = system.copy()
+        sadd = monomer.copy()
 
         if ii < nrep - 2:
             del sadd[x_idxs]  # Remove both 'X' atoms in the intermediate monomers
@@ -81,5 +90,6 @@ def build_polymer(system, substitute, nrep, target_distance=1.600):
     symbols = np.array(sout.get_chemical_symbols())
     symbols[symbols == "X"] = substitute
     sout.set_chemical_symbols(symbols)
+    sout.center()
 
-    return sout#ase.build.sort(sout)
+    return sout

mdinterface-1.3.0/mdinterface/config.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Config file reader blatantly copied from ASE
+
+@author: roncofaber
+"""
+
+import os
+import configparser
+from platformdirs import user_config_dir
+
+def load_config():
+    # Determine the path to the user's configuration file
+    MDINT_CONFIG_DIR = user_config_dir("mdinterface")
+    user_config_file = MDINT_CONFIG_DIR + "/config.ini"
+    
+    os.environ["MDINT_CONFIG_DIR"] = MDINT_CONFIG_DIR
+    
+    # Check if the user's configuration file exists
+    if os.path.exists(user_config_file):
+        config_file = user_config_file
+    else:
+        # Fall back to the default configuration file in the package directory
+        print(f"No config.ini file found:\n{user_config_file}")
+        config_file = os.path.join(os.path.dirname(__file__), 'config.ini')
+        print(f"Defaulting on reading file:\n{config_file}")
+        print("Make sure it makes sense.")
+    
+    config = configparser.ConfigParser()
+    config.optionxform = str
+    config.read(config_file)
+    
+    if 'settings' in config:
+        for key in config['settings']:
+            os.environ[key] = config['settings'][key]
+
+# Load the configuration when the module is imported
+if __name__ == "__main__":
+    load_config()

{mdinterface-1.1.0 → mdinterface-1.3.0}/mdinterface/core/__init__.py

@@ -6,3 +6,4 @@ core: Core functionalities including related components.
 
 from .specie import *
 from .topology import *
+from .polymer import *

mdinterface-1.3.0/mdinterface/core/polymer.py

@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created on Mon Feb  3 15:00:01 2025
+
+@author: roncofaber
+"""
+
+# repo stuff
+from .specie import Specie
+from mdinterface.externals import run_ligpargen
+from mdinterface.build.polymerize import build_polymer
+
+# other stuff
+import ase
+import random
+import numpy as np
+
+#%%
+
+class Polymer(Specie):
+
+    def __init__(self, atoms=None, charges=None, atom_types=None, bonds=None,
+                 angles=None, dihedrals=None, impropers=None, lj={}, cutoff=1.0,
+                 name=None, lammps_data=None, fix_missing=False, chg_scaling=1.0,
+                 pbc=False, ligpargen=False, tot_charge=0, nrep=1, start_end_idxs=None,
+                 target_distance=1.600, substitute=None, refine_charges=False,
+                 offset=False):
+        
+        # initialize polymer stuff
+        self._snippet_cache = {}
+        
+        # polymerize
+        polymer = build_polymer(atoms, substitute, nrep, start_end_idxs=start_end_idxs,
+                      target_distance=target_distance)
+        
+        # Initialize the parent class
+        super().__init__(polymer, charges, atom_types, bonds, angles, dihedrals,
+                         impropers, lj, cutoff, name, lammps_data, fix_missing,
+                         chg_scaling, pbc, ligpargen, tot_charge)
+        
+        if refine_charges:
+            self.refine_charges(offset=offset)
+        
+        return
+    
+    # snip the polymer into a smaller molecule, return as ase.Atoms
+    def make_snippet(self, centers, Nmax, ending="F"):
+        
+        idxs = list(set(np.concatenate(self.find_relevant_distances(Nmax, centers=centers))))
+        edxs = list(set(np.concatenate(self.find_relevant_distances(Nmax+1, centers=centers, Nmin=Nmax))) - set([centers]))
+        
+        snippet_idxs = np.array(idxs + edxs)
+
+        
+        chain = self.atoms[idxs].copy()
+        term  = self.atoms[edxs].copy()
+        
+        term.set_chemical_symbols(len(term) * [ending])
+        snippet = ase.Atoms(chain + term)
+        
+        return snippet, snippet_idxs
+    
+    # return list of elements adjacent to a connection point
+    def _get_connection_elements(self):
+
+        # Get elements where there is a connection
+        centers = np.argwhere(self.atoms.arrays["is_connected"]).flatten()
+
+        poi = []
+        for center in centers:
+            idxs = set(self.find_relevant_distances(1, centers=center).flatten())
+            if not any([ii in poi for ii in idxs]):
+                poi.append(center)
+        return poi
+
+    def _update_charges(self, center, Nmax, charges, ending="F"):
+        """
+        Updates the charges for the specified species.
+    
+        Parameters:
+        specie (ase.Atoms): The species object containing the atoms.
+        center (int): The center atom index.
+        Nmax (int): The maximum number of neighbors to consider.
+        charges (np.ndarray): The array of charges to be updated.
+        ending (str): The chemical symbol for the terminal atoms.
+        """
+        
+        ldxs = list(set(np.concatenate(self.find_relevant_distances(3, centers=center))))
+        
+        snippet, snippet_idxs = self.make_snippet(center, Nmax, ending=ending)
+    
+        # Check if snippet already exists in cache
+        snippet_hash = ''.join(snippet.get_chemical_symbols())
+        
+        if snippet_hash in self._snippet_cache:
+            cached_charges = self._snippet_cache[snippet_hash]
+            mapping = [np.argwhere(snippet_idxs == ll)[0][0] for ll in ldxs]
+            charges[ldxs] = cached_charges[mapping]
+            return
+        
+        # snippet charge
+        if "nominal_charge" in snippet.arrays:
+            sn_charge = snippet.arrays["nominal_charge"].sum()
+        else:
+            sn_charge = None
+            
+        # run ligpargen
+        output = run_ligpargen(snippet, charge=sn_charge)
+        
+        # get charges
+        new_charges = output[0].get_initial_charges()
+        
+        # find mapping
+        mapping = [np.argwhere(snippet_idxs == ll)[0][0] for ll in ldxs]
+        
+        # update charges
+        charges[ldxs] = new_charges[mapping]
+    
+        # Store the new snippet and its charges in cache
+        self._snippet_cache[snippet_hash] = new_charges
+        
+        return
+    
+    # main driver that refines charges across the whole polymer
+    def refine_charges(self, Nmax=12, offset=False, ending="F"):
+        """
+        Refines the charges for the specified species.
+    
+        Parameters:
+        specie (ase.Atoms): The species object containing the atoms.
+        Nmax (int): The maximum number of neighbors to consider.
+        offset (bool): Whether to apply an offset to the charges.
+    
+        Returns:
+        np.ndarray: The refined charges.
+        """
+        
+        # get charges and connection elements
+        charges = self.charges
+        centers = self._get_connection_elements()
+        
+        # get charges at every point
+        for center in centers:
+            self._update_charges(center, Nmax, charges, ending=ending)
+            
+        # bring back to zero
+        if offset:
+            
+            if "nominal_charge" in self.atoms.arrays:
+                target = self.atoms.arrays["nominal_charge"].sum()
+            else:
+                target = 0
+            
+            charges -= ((charges.sum() - target) / len(charges))
+            
+        self.atoms.set_initial_charges(charges)
+        return