SAPPHIRE

Sapphire is a post-processing environment for the structural characterisation of metallic nanoparticles and nanoalloys from molecular-dynamics trajectories. It turns frames into physics: pair-distance distributions and per-frame nearest-neighbour cutoffs, adjacency and coordination, atop generalised coordination numbers (aGCN) and the GCN-based oxygen-reduction mass-activity model, common-neighbour-analysis (CNA) signatures and patterns with an SVM structure classifier, chemical ordering in alloys (mixing parameter, LAE, per-species neighbour counts), shape and shell-by-shell morphology, and the distribution divergences and change-point statistics that locate melting and other transitions along a run.

It reads anything ASE can read and writes per-frame results any tool can consume — plain text for series, sparse npz for adjacency matrices. Documentation, rendered tutorials and the full API reference live at https://jonesrobm.github.io/Sapphire/.

Citing Sapphire

If Sapphire contributes to your work, please cite the method paper:

R. M. Jones, K. Rossi, C. Zeni, M. Vanzan, I. Vasiljevic, A. Santana-Bonilla and F. Baletto, Structural characterisation of nanoalloys for (photo)catalytic applications with the Sapphire library, Faraday Discussions, 2023, 242, 326–352. doi:10.1039/D2FD00097K

@article{Jones2023Sapphire,
  author  = {Jones, Robert M. and Rossi, Kevin and Zeni, Claudio and Vanzan, Mirko and
             Vasiljevic, Igor and Santana-Bonilla, Alejandro and Baletto, Francesca},
  title   = {Structural characterisation of nanoalloys for (photo)catalytic applications
             with the Sapphire library},
  journal = {Faraday Discussions},
  year    = {2023},
  volume  = {242},
  pages   = {326--352},
  doi     = {10.1039/D2FD00097K},
}

To cite the software itself (a specific archived version), use the Zenodo DOI: 10.5281/zenodo.22211283 resolves to the latest release; v1.1.0 is 10.5281/zenodo.22211284. GitHub's "Cite this repository" button (from CITATION.cff) gives both formats.

The GCN-based mass-activity model implemented in Post_Process.Mass_Activity follows Rossi, Asara & Baletto, ChemPhysChem 2019, 20, 3037 (doi:10.1002/cphc.201900564), building on Rück, Bandarenka, Calle-Vallejo & Gagliardi, J. Phys. Chem. Lett. 2018, 9, 4463.

Installation

Sapphire supports Python 3.10+.

python -m venv .venv && source .venv/bin/activate
pip install -e ".[plot,changepoint]"      # core + plotting + change-point analysis

Extras: ml (CNA structure classifier), mlpot (MACE foundation-model potentials; pulls in PyTorch), light (pyGDM2 optics), quote, notebooks, docs, dev, all. Verify with python -c "import Sapphire; print(Sapphire.__version__)" and, with the dev extra, pytest.

Quick start

from Sapphire.api import run
from Sapphire.Tutorials import data

xyz = data.sample("AuPt", "work/")            # bundled Au80Pt20 melting trajectory (70 frames)
r = run(xyz, "work/out/", quantities=["pdf", "adj", "nn", "agcn", "cna_sigs"],
        frames=(0, 70, 7), statistics={"JSD": ["pdf"]})
r.load("agcn")                                 # (frames, atoms) atop generalised coordination numbers

Or from a shell, which is the same analysis driven by a TOML config:

sapphire run movie.xyz -o out/ -q pdf,adj,nn,agcn,cna_sigs --frames 0:1000:10 -j 8

-j analyses frames across processes for identical output; missing prerequisites are filled in and reported, and a run that could not produce what was asked exits non-zero. See the command line reference.

Results are per-frame text files, with adjacency matrices stored sparse (see the file contract) readable with Sapphire.IO.Reader or any other tool. The classic two-dictionary interface to Sapphire.Process is unchanged (examples/run_analysis.py); examples/from_lammps.py ingests a LAMMPS dump.

Tutorials

Nine executable notebooks in main/Sapphire/Tutorials/, run in CI and rendered on the documentation site:

The bundled samples are down-sampled from four 14 ns bimetallic MD data sets published as a GitHub release; fetch the full trajectories with Sapphire.Tutorials.data.fetch(...).

Repository layout

Authors and acknowledgements

Sapphire was written in the Baletto group at King's College London.

• Robert M. Jones — lead author and maintainer (Robert.M.Jones@kcl.ac.uk)
• Francesca Baletto — principal investigator
• Claudio Zeni, Kevin Rossi, Mirko Vanzan, Igor Vasiljevic, Alejandro Santana-Bonilla — co-authors of the Sapphire paper
• Matteo Tibberi, Armand Aquier — contributors to early versions of the CNA-pattern pipeline and morphology tools (their originals are preserved under legacy/)

The library builds on ASE, numpy/scipy, and optionally ruptures, scikit-learn, pyGDM2 and MACE.

Sapphire is research software in active development: if something looks wrong, please open an issue with whatever you can share — trajectories, logs, or just the surprise.

Licence

GPL-3.0 (see LICENSE).