Python toolkit for proton transport and polyanion dynamics in CsH2PO4 and CsHSO4, with a six-part tutorial and figure-reproduction workflows for
M. Wang, J. Ding, G. Xiong, N. Zhan, C. Owen, A. Musaelian, Y. Xie, N. Molinari, R. Adams, B. Kozinsky, S. Haile. Revealing the Proton Slingshot Mechanism in Solid Acid Electrolytes through Machine-Learning Molecular Dynamics. Journal of the American Chemical Society 148 (40), 42913–42927 (2026). DOI: 10.1021/jacs.5c21965.
Open the six-part tutorial in Google Colab and choose Runtime → Run all. The first cell installs the dependencies and downloads the example data. Everything runs in Colab's CPU runtime; no local installation or GPU is needed.
The notebook teaches the paper's core analysis methods using the bundled 75 ps CDP and CHS trajectories for short demonstrations, rather than reproducing the published results.
- Distinguish rattling, rotation and productive rotation; examine CHS pointing before hopping.
- Classify productive/nonproductive rotations and estimate residence-time rates.
- Relate bound-proton coordination to rotational dynamics.
- Measure spatial–temporal event correlations and temporal overlaps.
- Measure rotation displacement and O–H reorientation underlying the slingshot.
- Map orientation probability landscapes and vector autocorrelation.
To run the same notebook locally, follow the installation instructions, then:
jupyter lab notebooks/superproton-tutorial.ipynbTo recalculate the paper's results from trajectories, download the matching full production trajectories and follow the figure map with the original analysis settings.
Use superproton.workflow.Analysis for the same analyses in Python. For other
compatible solid-acid trajectories, supply an explicit AtomMapping; the paper
CLI provides CDP and CHS presets. The notebook includes input requirements,
atom mappings and examples for your own trajectories.
For local use, install uv, then:
git clone https://github.com/mir-group/super_proton.git
cd super_proton
uv venv --python 3.11 --managed-python
source .venv/bin/activate
uv pip install -e ".[tutorial]"This creates a separate Python environment with the scientific dependencies,
OVITO, Jupyter and the local package. Run local commands from the repository
root with this environment activated. Conda users can use
environment.yml instead.
Redraw from reference data. The numerical inputs in data/reference/ are
included in the repository; no trajectory download is needed.
python figures/plot_residence_time.py # Figures 4a and 7a
python figures/plot_msd.py # Figure 2 MSD panels
for f in figures/plot_*.py; do python "$f"; done # all plottersPlots are written to figures/output/. See the figure map
for scripts, inputs and reproduction commands.
Recalculate from production trajectories. Download the matching full trajectory
from Zenodo following the data guide.
For example, with CDP_525K_4ns.trj decompressed in data/zenodo/:
python scripts/run_analysis.py --analysis residence xoh \
--dump data/zenodo/CDP_525K_4ns.trj --material CDP --temperature 525 --compareResults are written to results/; --compare prints available paper values
alongside them. Run python scripts/run_analysis.py --help for other analyses
and options. These command-line scripts run from the checkout.
Reproducing a panel requires its matching trajectory, temperature, window and settings. This repository covers post-MD analysis and plotting; force-field training, DFT calculations and MD simulations are outside its scope.
The agent skill provides instructions for AI agents to use Superproton and interpret analysis results.
uv pip install -e ".[tutorial,dev]"
pytestProduction-trajectory tests are skipped unless their input paths are configured. To enable them, set the paths to the matching 4 ns trajectories:
export SUPERPROTON_CDP_525K_TRJ=/path/to/CDP_525K_4ns.trj
export SUPERPROTON_CHS_450K_TRJ=/path/to/CHS_450K_4ns.trj
pytest tests/test_reference.pyIf you use these analysis methods, cite the JACS paper above and record the software version or commit and analysis settings. CITATION.cff provides the preferred citation. Cite the Zenodo dataset separately when using the supplied trajectories or DFT data.
The software is licensed under MIT; see LICENSE.