Skip to content

About

Universal tool for quantifying various transport mechanisms in ion conducting medium

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

OnsagerDecomposer logo

OnsagerDecomposer

Which microscopic events carry the ions, how often they happen, and how effective each one is —
an exact, additive decomposition of transport coefficients from molecular dynamics.

tests MIT license Python 3.9+ arXiv:2602.16636


OnsagerDecomposer splits the self-diffusion coefficient, the Nernst–Einstein conductivity and the full Onsager matrix of an MD trajectory into contributions of physically defined events — vehicular motion, solvent or anion exchange, intra- and interchain hops, single-ion and concerted hops, or transitions between solvation states such as SSIP, CIP and AGG. The contributions sum exactly to the conventional Einstein / Green–Kubo values, and scanning the window length Δt shows on which timescales each mechanism emerges and dominates.

It works for liquid, polymer and crystalline ion conductors.

How it works

Step What happens API
1. Shells First coordination shell of every cation in every frame (convex hull, distance cutoff, or crystal sites) compute_shells, crystal.compute_site_shells
2. Events Every window [t, t+Δt] of every cation gets exactly one event label liquid_events, polymer_events, crystal.crystal_events, transitions
3. Decomposition Each cation is split into one virtual particle per event; event-resolved self and distinct correlations from FFTs decompose
4. Transport D_self, σ_NE, share and effectiveness (D^m / p_m) of every event self_diffusion_table, per_macrostate

System requirements

  • Operating system: Linux or macOS (both tested); pure Python, nothing to compile, so other platforms with Python 3.9 or later should also work.
  • Dependencies: numpy, scipy, pandas. Crystals also need ase and networkx; the tests need pytest.
  • Tested on:
    • Ubuntu (GitHub Actions ubuntu-latest) with Python 3.9 and 3.12, using the latest dependency releases for each Python version, on every push.
    • macOS 27 (Apple M3 Max), Python 3.10.18 with numpy 1.26.4 and 2.2.6, scipy 1.14.1, pandas 2.2.2 and 2.3.3, ase 3.25.0, networkx 3.4.2.
  • Hardware: no special hardware (no GPU). The demo needs under 1 GB of memory. A full analysis of a 500 ns polymer run (50,000 frames, 288 Li) needs about 5 GB. Computing shells from a long trajectory runs in parallel over frames (n_workers), so more CPU cores make it faster.

Installation

git clone https://github.com/learningmatter-mit/OnsagerDecomposer.git
cd OnsagerDecomposer
pip install -e .              # liquids and polymers
pip install -e ".[crystal]"   # + crystals (ase, networkx)
pip install -e ".[test]" && pytest -q   # optional: run the tests (about 3 s)

Typical install time is under a minute on a normal desktop computer (10 s in a fresh virtual environment on the test machine above, including downloading numpy, scipy and pandas).

Demo

examples/data/ holds excerpts of the paper's FAN/LiFSI (liquid) and PPM/LiTFSI (polymer) runs: 10 frames of input files, plus precomputed coordination shells (details in examples/data/README.md). After installing:

python examples/quickstart.py

Run time: a few seconds on a normal desktop computer (3.5 s on the test machine; the very first run takes up to about 20 s while Python compiles the imports).

Expected output: seven tables, printed as text:

  1. A one-line summary of the shells computed from the 10 input frames: 10 frames of 11610 atoms -> 9612 shell rows (6.8 coordinating atoms per Li).
  2. FAN/LiFSI events at Δt = 2, 10 and 20 ps, then the SSIP/CIP/AGG macrostates at Δt = 10 ps. Each event table lists, per event, its probability, D_self (cm²/s), σ_NE (mS/cm), share of the total, and effectiveness. The total Li D_self is 1.85, 1.88 and 1.91 × 10⁻⁶ cm²/s at the three Δt.
  3. PPM/LiTFSI events at Δt = 0.5, 1 and 2 ns. The total Li D_self is 7.6 × 10⁻⁸ cm²/s, as in the paper.

The first table looks like this:

2. FAN/LiFSI, dt = 2 ps
                        probability     D_self  sigma_NE  share  effective_D_self  effective_sigma_NE
event
vehicular                     0.503  6.844e-07     3.161  0.370         1.359e-06               6.278
solvent_exchange              0.274  8.820e-07     4.073  0.477         3.222e-06              14.879
anion_exchange                0.150  1.397e-07     0.645  0.076         9.299e-07               4.295
solvent_anion_exchange        0.073  1.432e-07     0.661  0.077         1.974e-06               9.116
total                         1.000  1.849e-06     8.540  1.000         1.849e-06               8.540
anion                           NaN  1.672e-06       NaN    NaN               NaN                 NaN

Use on your own data

The sections below show how to run each step on your own trajectories.

Quick start: liquid or polymer electrolyte

Input is a HiTPoly analysis folder with atom_names_rdf_all.txt (element, type, residue id per atom), xyz_unwrapped_rdf_all.txt (unwrapped coordinates) and box_len.txt.

import onsagerdecomposer as od

folder = "path/to/simulation"
top = od.read_hitpoly_topology(folder)
frames = od.iter_hitpoly_frames(folder, top, stride=1)        # unwrapped, solvent-COM frame
shells = od.compute_shells(top, frames, timestep=2.0,           # ps between frames
                           anion_center="N", n_workers=8)       # N for TFSI/FSI, P for PF6
shells.save("shells.npz")                                       # compute once, reuse for every Δt

s = shells.subsample(10)                                        # Δt = 10 frames = 20 ps
events = od.liquid_events(s)                                    # or od.polymer_events(s)
corr = od.decompose(s.cation_displacements(), events.labels, events.names, s.anion_displacements())
table = od.self_diffusion_table(corr, events, s.timestep, volume=top.box**3, temperature=298,
                                fit_range=(0.05, 0.10))
print(table)   # probability, D_self, sigma_NE, share, effective_D_self, effective_sigma_NE per event

SSIP / CIP / AGG macrostates:

states, names = od.solvation_states(s)
tr = od.transitions(states, names)                              # SSIP->SSIP, SSIP->CIP, ...
corr = od.decompose(s.cation_displacements(), tr.labels, tr.names, s.anion_displacements())
print(od.per_macrostate(od.self_diffusion_table(corr, tr, s.timestep, top.box**3, 298), names))

examples/decompose_hitpoly.py runs the full Δt scan from the command line.

Quick start: crystalline conductor

Input is an ASE trajectory and a network of crystallographic sites (a networkx graph whose nodes carry the framework-anion indices of each site polyhedron, e.g. the 6b/18e/36f sites of NASICON).

from onsagerdecomposer import crystal, decompose, self_diffusion_table

elements, cell = crystal.read_ase_topology("latp_800K.traj")
network = crystal.load_site_network("supercell_network_wyckoff.gpickle")
frames = crystal.iter_ase_frames("latp_800K.traj", stride=10)
shells = crystal.compute_site_shells(elements, cell, frames, network, timestep=1.0, n_workers=8)

events = crystal.crystal_events(shells)    # vibration, single-ion hop, aligned / unaligned concerted hop
states, names = crystal.activated_states(shells)   # activated (A) / non-activated macrostates

Fitting window

D_self is the slope of each event's displacement correlation versus lag time, divided by 6 and by the number of cations. The slope is fitted over a window given as a fraction of the available lag range (fit_range), so the same fraction corresponds to different absolute times for different trajectory lengths. The windows used in the paper:

System Frame interval Shell definition fit_range
LATP (crystal) 0.1 ps crystal sites; Li neighbours ≤ 4 Å and ≤ 2 site edges (0.08, 0.10)
PEO / PPM + LiTFSI (polymer) 10 ps convex hull; O, N, F coordinators (0.06, 0.12)
EC / LiPF6, FAN / LiFSI (liquid) 2 ps convex hull; O, N, F coordinators (0.05, 0.10)

Check that the correlations are linear inside the window before trusting a decomposed coefficient; rare events converge last.

Defining your own events

An event rule is any function that gives every cation window exactly one label. Helpers report, for each window, whether a residue (solvent molecule, chain, anion) or a coordinating atom entered or left the shell:

import numpy as np
import onsagerdecomposer as od

def anion_gain_or_loss(shells):
    entered, left = od.residue_entries_exits(shells, "anion")
    labels = np.select([entered & left, entered, left], [3, 1, 2], default=0)
    return od.Events(labels, ["no_change", "anion_gained", "anion_lost", "anion_swapped"])

A macrostate rule returns one state per cation and frame; od.transitions(states, names) turns it into X→Y events that are decomposed the same way.

Validation

pytest runs the unit tests. The package was validated against the original research code on the paper's PPM/LiTFSI, FAN/LiFSI and LATP trajectories: coordination shells and event labels are identical, and correlation matrices and transport coefficients agree to better than 1e-9 relative. Pair sums are replaced by per-event collective sums, so the full self + distinct decomposition takes seconds rather than cluster-days.

Reproducing the paper

The polymer example (examples/data/ppm_litfsi_shells.npz) reproduces the paper's PPM/LiTFSI event table at Δt = 0.5, 1 and 2 ns: identical event labels and probabilities, and D_self within 2 × 10⁻⁷ relative (tests/test_example_data.py). Reproducing every figure needs the full MD trajectories (tens of GB), which are available from the corresponding author on reasonable request. With a trajectory folder, the quick-start code above (paper settings in the fitting window table) gives the paper's numbers.

Citation

If you use OnsagerDecomposer, please cite:

K. Jun, P. A. Leon, J. Ruža, J. Nam, B. D. McCloskey, R. Gómez-Bombarelli, Environment-mediated transport as a general principle of fast ion conduction, arXiv:2602.16636 (2026). https://arxiv.org/abs/2602.16636

@article{jun2026environment,
  title   = {Environment-mediated transport as a general principle of fast ion conduction},
  author  = {Jun, KyuJung and Leon, Pablo A. and Ru{\v{z}}a, Jur{\c{g}}is and Nam, Juno and
             McCloskey, Bryan D. and G{\'o}mez-Bombarelli, Rafael},
  journal = {arXiv preprint arXiv:2602.16636},
  year    = {2026},
  url     = {https://arxiv.org/abs/2602.16636}
}

Contact

KyuJung Jun — School of Mechanical Engineering, Korea University (kyujung@korea.ac.kr, kyujung@mit.edu). Questions, bug reports and new event definitions are also welcome as GitHub issues.

License

MIT — see LICENSE.

About

Universal tool for quantifying various transport mechanisms in ion conducting medium

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages