octp-pp

Post-processing toolkit for OCTP (Order-n Transport Properties) output files from LAMMPS molecular dynamics simulations.

The computationally intensive work — file parsing, MSD fitting, and all physical-property models — is compiled to native code via a PyO3/maturin Rust extension. Interactive visualisations use Plotly.

Features

• Rust core — parsing, diffusivity fitting, Laliberte density/viscosity, Dewane and Gilliam conductivity models, and concentration conversions all run natively; the Brent–Dekker molarity→molality inversion is ~570× faster than an equivalent scipy.fsolve loop
• Automatic run averaging — pass a list of parallel-run folders; means and standard deviations are computed automatically
• Biased Random Walk (BRW) correction — built-in correction for proton-hopping contributions (OH⁻ / H₃O⁺) matched against experimental conductivity
• Configurable constants — ion charges, molecular weights, hop distance, etc. live in a JSONL file and can be overridden at runtime without touching code

Installation

pip install octp-pp

From source

git clone https://github.com/JelleLagerweij/octp-pp
cd octp-pp
pip install maturin
maturin develop            # debug build  (fast compile, slower runtime)
maturin develop --release  # release build (slow compile, fast runtime)

maturin build (and pip install .) always use the release profile. maturin develop defaults to debug — ideal during active development.

Quick start

import octp_pp as octp
import octp_pp.helpers as hf

# Five parallel NVT runs stored under data/run_1 … data/run_5
mixture = octp.PP_OCTP(
    "data",
    [f"run_{i}" for i in range(1, 6)],
    groups=["wat", "Na", "OH", "SCN"],
    dt=2,           # timestep in fs
    plotting=True,  # interactive Plotly figures
)

# Configure non-default file names (if needed)
mixture.filenames(Diff_Onsag="diffonsag.dat", Diff_self="diffself.dat")
mixture.changefit(Minc=7, Mmax=45, er_max=0.05)

# State properties
mixture.density()
mixture.molality("OH",  "wat", hf.MOLECULAR_WEIGHTS["WAT"])
mixture.molality("SCN", "wat", hf.MOLECULAR_WEIGHTS["WAT"])

# Transport properties
mixture.viscosity()
mixture.self_diffusivity(YH_correction=True)
mixture.onsager_coeff()

# Structural properties with new features
mixture.coord_number(solvent="wat", interpolate_spline=3)  # RDF with interpolation
mixture.bond_angles(smoothing_width=5.0)  # Angular smoothing in degrees

# Conductivity
mixture.electrical_conductivity(ion_names=["Na", "OH", "SCN"], ion_charges=[1, -1, -1], method="nernst-einstein")
mixture.electrical_conductivity(ion_names=["Na", "OH", "SCN"], ion_charges=[1, -1, -1], method="direct")

# BRW correction (requires experimental Excel file)
octp.biassed_random_walk(mixture, "Experiments_total.xlsx")

mixture.store()   # writes postprocessed.csv next to the data folder

Physical-property helpers (octp_pp.helpers)

All functions are vectorised and delegate to the Rust core.

Fit parameters are stored in a user-provided JSON file (see test/fits_laliberte.json for the expected structure).

Global constants

Loaded from octp_pp/constants.jsonl at import time. Override at runtime without editing any file:

# Add a custom salt for this session
hf.load_constants(updates={"MOLECULAR_WEIGHTS": {"MYMAT": 123.45}})

# Inspect what is loaded
print(hf.MOLECULAR_WEIGHTS)
print(hf.DELTA_HOP)

API reference

PP_OCTP class

All optional methods call mandatory_properties() automatically if it has not yet been run.

Time-based Filtering

Several methods support filter_time parameter for exponential weighted moving average filtering of time-series data. The filter window is specified in femtoseconds (fs) and is automatically converted to the appropriate number of data points based on the actual time spacing in the data:

# Apply 500 fs moving average filter to pressure data
mixture.pressure(filter_time=500)

# Filter thermodynamic property data
mixture.read_thermoprop('v_TotEn', 'nvt', filter_time=5000)

# Filter energy data
mixture.tot_energy(filter_time=1000)
mixture.pot_energy(filter_time=1000)

Filtering is applied only to plotted data, not to the computed averages stored in results.

RDF Interpolation

The coord_number method supports Akima1DInterpolator-based interpolation for smoother RDF analysis:

# No interpolation (default)
mixture.coord_number(solvent="wat")

# Interpolate with 3 subdivisions per interval (4x denser grid)
mixture.coord_number(solvent="wat", interpolate_spline=3)

# High-density interpolation (50x denser grid)
mixture.coord_number(solvent="wat", interpolate_spline=50)

• interpolate_spline=None, 0, or 1: No interpolation
• interpolate_spline>1: Interpolate with that many subdivisions per original interval

Module-level functions

License

MIT