Sapphire
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:
| # | Topic |
|---|---|
| 01 | Build a cluster; CN/GCN; surface–core peeling (Morphology) |
| 02 | Pair-distance KDE, RDF, deriving the cutoff |
| 03 | Adjacency, aGCN and the ORR mass-activity volcano |
| 04 | CNA signatures, patterns, structure classifier |
| 05 | Bimetallic trajectory with Process, Reader, Graphing |
| 06 | Divergences, collectivity, change-point detection |
| 07 | Shape: inertia, radii of gyration, radial density |
| 08 | Ensemble averaging over runs |
| 09 | MD with a MACE foundation-model potential |
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
| Path | Contents |
|---|---|
main/Sapphire/ |
the package (api, Process, Post_Process, CNA, IO, Graphing, Potentials, Light, Utilities, Tutorials) |
examples/ |
driver-script templates |
tests/ |
pytest suite (import sweep, numerics, end-to-end runs on bundled data) |
docs/ |
mkdocs site: guides, file contract, API reference, changelog (mkdocs serve) |
legacy/ |
earlier code kept for reference; not installed |
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).