sea-urchin 1.0.1

The Electrolyte Machine is a set of Python tools to post-process trajectories from AIMD, MD and metadynamics simulations.

Electrolyte Machine

Sea Urchin is a set of Python tools to post-process trajectories from AIMD, MD and metadynamics simulations to extract and analyze local structure around atomic species. The outcome of the algorithm is a quantitative mapping of the multiple coordination environments present in the MD data.

Details on the Sea Urchin algorithm are presented in the paper:

Roncoroni, F., Sanz-Matias, A., Sundararaman, S., & Prendergast, D. Unsupervised learning of representative local atomic arrangements in molecular dynamics data. Phys. Chem. Chem. Phys., 25, 13741-13754 (2023) (https://doi.org/10.1039/D3CP00525A); arXiv preprint arXiv:2302.01465.

Applications of the Sea Urchin algorithm:

Sanz-Matias, A., Roncoroni, F., Sundararaman, S., & Prendergast, D. Ca-dimers, solvent layering, and dominant electrochemically active species in Ca(BH$_4$)$_2$ in THF Nature Communications 15, 1397 (2024) (https://doi.org/10.1038/s41467-024-45672-7) arXiv preprint [https://arxiv.org/pdf/2303.08261]

---

Requirements

Check the file requirements.txt to see which packages are needed. Installing the package using pip should already take care of all dependencies.

Installation instructions

Create a new virtual environment

Create a new Python environment. (You can also do it in a pre-existing environment, but make sure you don't break something):

conda create -n ele_machine python=3.11
conda activate ele_machine

Note that you may need to initialize your shell within conda, e.g., using conda init bash. You will know if the conda environment has been activated when you see that your shell prompt is modified with (ele_machine).

After activating your new (or existing) environment, follow the next steps.

Install using pip

You can simply install the latest release of the package and all dependencies using:

pip install sea_urchin

Install directly the source code

Alternatively you can obtain sea_urchin directly from the repository by following those steps:

Clone the repository in the desired location:

git clone [e-mail]:electrolyte-machine/sea_urchin.git

Install the required packages:

cd sea_urchin
conda install -c conda-forge --file requirements.txt

Install the package with pip:

pip install .

Note that gitlab uses ssh for access and you will have to set up a public key through your gitlab account and edit your local ssh config as described here.

Use alignment and clustering algorithm

To use the clustering algorithm and perform alignment of structures, you will need to install and compile some optional additional packages.

Fastoverlap

The original repository developed by M. Griffiths can be found on GitHub. Here, we will use a tweaked forked repository so that it is compatible with newer Python versions and with the alignment routines defined in the sea_urchin. The package can be found at https://gitlab.com/roncofaber/fastoverlap.

Attention: If you want to use FASTOVERLAP, you will need to follow those instructions:

• Install fftw and lapack, e.g.: conda install -c conda-forge fftw lapack

• Compile the fortran modules (not strictly necessary, but suggested):

  git clone https://gitlab.com/roncofaber/fastoverlap
  cd fastoverlap/
  python setup.py build_ext -i
  

• Add package to Python path:

  conda develop .
  

• Occasionally, if you update the conda environment stuff might break and you will have to rebuild the Fortran modules with python setup.py build_ext -i. You can always check if FASTOVERLAP can be run using Fortran by doing:

  import fastoverlap
  fastoverlap.f90.have_fortran
  

  If the answer is False, try reinstalling the Python fftw implementation with: conda install -c conda-forge fftw and proceeding again with python setup.py build_ext -i. The Fortran implementation is not strictly necessary, but improves the alignment performance a lot.

IterativeRotationsAssignments

Iterative Rotations and Assignments (IRA) is a shape matching algorithm that can be found at: https://github.com/mammasmias/IterativeRotationsAssignments

Visit the links above for details about its installation. To add the package to your Python path, do the following with your conda environment activated:

cd IterativeRotationsAssignments/interface
conda develop .

Usage - tutorial

A tutorial to introduce how to use the Sea Urchin for trajectory post-processing and structure clustering can be found in the folder sea_urchin/tutorial. For the scope of the tutorial you will need to download some additional files that you can find here. Download them (unzip if you downloaded as a zip) and change the path of the Jupyter Notebook accordingly to point to the folder.

Jupyter Notebooks - Open on demand

To use the sea_urchin functionalities within the lrc-ondemand service, follow those steps:

1. Load the precompiled environment on your terminal (connected to the hpc-cluster):

   module load python/3.7
   source activate /global/home/groups/nano/share/software/electrolyte_machine/conda_environment/elemac 
   

2. Install the IPython kernels:

   python -m ipykernel install --user --name=elemac
   

3. Connect to a Jupyter Notebook through: https://lrc-ondemand.lbl.gov/ → interactive apps → Jupyter Notebook → compute mode .....

4. Open a new notebook, make sure to select the elemac kernel.

You are ready to go! To start, check the Jupyter Notebook in sea_urchin/tutorial.

Contact

Feel free to create Merge Requests and Issues on our GitLab page: https://gitlab.com/electrolyte-machine/sea_urchin.

If you want to contact the authors, please write to D. Prendergast at [e-mail].

References

If you use this code please cite the paper:

Sea Urchin Roncoroni, F., Sanz-Matias, A., Sundararaman, S., & Prendergast, D. Unsupervised learning of representative local atomic arrangements in molecular dynamics data. Phys. Chem. Chem. Phys., 25, 13741-13754 (2023). doi:10.1039/D3CP00525A;

Additionally, if you use any of the packages the Sea Urchin relies on, please cite their work accordingly. Notably:

ASE Hjorth Larsen, A., JØrgen Mortensen, J., Blomqvist, J., Castelli, I. E., Christensen, R., Dułak, M., Friis, J., Groves, M. N., Hammer, B., Hargus, C., Hermes, E. D., Jennings, P. C., Bjerre Jensen, P., Kermode, J., Kitchin, J. R., Leonhard Kolsbjerg, E., Kubal, J., Kaasbjerg, K., Lysgaard, S., … Jacobsen, K. W. (2017). The atomic simulation environment - a Python library for working with atoms. Journal of Physics: Condensed Matter, 29(27), 273002. doi:10.1088/1361-648X/AA680E

FASTOVERLAP Griffiths, M., Niblett, S. P., & Wales, D. J. (2017). Optimal Alignment of Structures for Finite and Periodic Systems. Journal of Chemical Theory and Computation, 13(10), 4914–4931. doi:10.1021/acs.jctc.7b00543

IRA Gunde M., Salles N., Hemeryck A., Martin Samos L. IRA: A shape matching approach for recognition and comparison of generic atomic patterns. Journal of Chemical Information and Modeling (2021), doi:10.1021/acs.jcim.1c00567

Molalign J. M. Vasquez-Perez, L. A. Zarate-Hernandez, C. Z. Gomez-Castro, U. A. Nolasco-Hernandez. A Practical Algorithm to Solve the Near-Congruence Problem for Rigid Molecules and Clusters. Journal of Chemical Information and Modeling (2023), doi:10.1021/acs.jcim.2c01187