Compute¶

Trajectory and structure analyses. Import with from molpy.compute import....

Numerical kernels live in the high-performance backend. The public types are identity-style for a stable Python import path — there is no second science implementation in molpy. Compose raw Computes with Fits (and an optional SI scale) the same way the Rust API does.

Like freud’s API modules, each molpy.compute module has its own page under Compute with an overview table and full signatures. This page is the index plus the shared base / result types.

Analysis units (LAMMPS real)

Length Å, charge e, time fs, volume Å³, temperature K. Vibrational spectra take dt_fs in femtoseconds and report cm⁻¹. GROMACS trajectories are nm-native — scale lengths ×10 before analysis. MSD / Einstein routes need unwrapped coordinates.

Architecture: raw Compute → Fit → scale¶

Layer	Role	Examples
Raw Compute	Correlation / MSD / ACF curve only	`EinsteinConductivity`, `GreenKuboConductivity`, `DebyeRelaxation`, `MSD`
Fit	Integrate or slope-fit the curve	`CumulativeTrapezoid`, `LinearFit`, `DebyeFit`, `EinsteinHelfandSpectrum`, `GreenKuboSpectrum`
Scale	MD → SI prefactor in your script	\(1/(6 V k_B T)\), \(1/(3 V k_B T)\), \(1/d\)

There is no all-in-one IonicConductivity / DielectricSusceptibility recipe class. Historical tame names remain as aliases of the public types:

Alias (deprecated name)	Canonical type
`JACF`	`GreenKuboConductivity`
`PMSDCompute`	`EinsteinConductivity`

Self-diffusion uses MSD (Einstein) and Acf / signal.acf_fft (Green–Kubo); see the MSD and VACF guides.

Module index¶

Module	Primary exports	Guide
`neighborlist`	`NeighborList`	NeighborList
`rdf`	`RDF`	RDF
`density`	`LocalDensity`, `GaussianDensity`	Density
`diffraction`	`StaticStructureFactorDebye`	Diffraction
`pmft`	`PMFTXY`	PMFT
`distribution`	distance / angle / dihedral / combined DF	Distribution
`spatial`	`SpatialDistribution`	Spatial
`order`	Steinhardt family	Order
`environment`	`BondOrder`	Environment
`shape`	COM, gyration, inertia, \(R_g\)	Shape
`cluster`	`Cluster`, `ClusterCenters`, `ClusterProperties`	Cluster
`decomposition`	`DescriptorRow`, `Pca`, `KMeans`	Decomposition
`hbond`	`HBonds`, `HBondCriterion`	HBond
`voronoi`	radical Voronoi tessellation	Voronoi
`msd`	`MSD`	MSD
`pmsd`	`EinsteinConductivity`	PMSD
`jacf`	`GreenKuboConductivity`	JACF
`onsager`	`Onsager`	Onsager
`persist`	`Persist`	Persist
`van_hove`	`VanHove`	Van Hove
`reorientation`	`LegendreReorientation`	Reorientation
`dielectric`	dielectric raw/fit helpers	Dielectric
`spectra`	VDOS / IR / Raman / VCD / ROA	Spectra
`signal`	`acf_fft`, windows, frequency grid	Signal
`workflow`	`Workflow`	Workflow

Shared base types¶

Base¶

base ¶

Base class for compute operations.

A :class:Compute is a configurable callable. Construction parameters go to __init__ (stored for serialization via :meth:Compute.dump); data inputs go to __call__. Operators take one or more data inputs directly — there is no single-input restriction:

>>> rdf = RDF(n_bins=100, r_max=10.0)
>>> result = rdf(frames, neighbors)      # two data inputs

Compute ¶

Compute(**config)

Bases: ABC

Abstract base class for compute operations.

Subclasses implement :meth:__call__ with a concrete, fully typed signature (one positional parameter per data input) and pass their construction parameters to super().__init__(**config) so that :meth:dump can round-trip the configuration.

Examples:

>>> class MyCompute(Compute):
...     def __init__(self, scale: float):
...         super().__init__(scale=scale)
...         self.scale = scale
...
...     def __call__(self, frames: Sequence[Frame]) -> MyResult:
...         return MyResult(value=42 * self.scale)
>>>
>>> compute = MyCompute(scale=2.0)
>>> result = compute(frames)
>>> compute.dump()
{'scale': 2.0}

Store construction parameters for serialization.

Parameters:

Name	Type	Description	Default
`**config`	`Any`	Configuration parameters, returned verbatim by :meth:`dump`.	`{}`

dump ¶

dump()

Serialize construction configuration to a dictionary.

Returns:

Type	Description
`dict[str, Any]`	The configuration parameters passed to `__init__`.

Result types¶

result ¶

Result classes for compute operations.

This module defines result types returned by compute operations.

ACFResult `dataclass` ¶

ACFResult(
    meta=dict(),
    time=(lambda: np.array([]))(),
    acf=(lambda: np.array([]))(),
    n_lags=0,
)

Bases: TimeSeriesResult

Autocorrelation function result.

Attributes:

Name	Type	Description
`time`	`NDArray[float64]`	Time lag values (in ps)
`acf`	`NDArray[float64]`	Autocorrelation values at each time lag, shape (n_lags,)
`n_lags`	`int`	Number of time lags

ConductivityResult `dataclass` ¶

ConductivityResult(
    meta=dict(),
    time=(lambda: np.array([]))(),
    msd=(lambda: np.array([]))(),
    sigma=float("nan"),
    slope=float("nan"),
    fit_start=0,
    fit_end=0,
)

Bases: TimeSeriesResult

Einstein-Helfand ionic-conductivity result.

Attributes:

Name	Type	Description
`time`	`NDArray[float64]`	MSD lag times tau (ps), shape (n_lags,).
`msd`	`NDArray[float64]`	Collective MSD <\|M_J(t+tau) - M_J(t)\|^2> of the ionic translational dipole, (e*A)^2, shape (n_lags,).
`sigma`	`float`	Static ionic conductivity sigma (S/m).
`slope`	`float`	Fitted MSD slope over the diffusive window, (e*A)^2/ps.
`fit_start`	`int`	First lag index used in the linear fit (inclusive).
`fit_end`	`int`	Last lag index used in the linear fit (exclusive).

DebyeSpectrumFit `dataclass` ¶

DebyeSpectrumFit(
    tau=float("nan"),
    delta_eps=float("nan"),
    eps_inf=1.0,
    eps_static=float("nan"),
    omega_peak=float("nan"),
)

Single-Debye parameters fitted from a frequency-domain spectrum.

Distinct from :class:molrs.compute.transport.DebyeFit, which fits the time-domain normalized ACF Φ(t). Prefer that Fit for compose pipelines.

Attributes:

Name	Type	Description
`tau`	`float`	Relaxation time (same time base as the spectrum).
`delta_eps`	`float`	Relaxation strength epsilon(0) - epsilon_inf (dimensionless).
`eps_inf`	`float`	High-frequency permittivity used in the fit.
`eps_static`	`float`	Static permittivity epsilon(0) (dimensionless).
`omega_peak`	`float`	Angular frequency of the dielectric-loss peak.

epsilon ¶

epsilon(omega)

Evaluate the fitted Debye model at angular frequencies omega.

Returns:

Type	Description
`NDArray`	`(epsilon_real, epsilon_imag)` under the positive-loss convention
`NDArray`	`epsilon* = epsilon' - i epsilon''`.

DielectricResult `dataclass` ¶

DielectricResult(
    meta=dict(),
    frequency=(lambda: np.array([]))(),
    epsilon_real=(lambda: np.array([]))(),
    epsilon_imag=(lambda: np.array([]))(),
    epsilon_static=float("nan"),
    epsilon_inf=1.0,
    route="",
    component="",
    conductivity=None,
)

Bases: Result

Single-route dielectric susceptibility result.

Attributes:

Name	Type	Description
`frequency`	`NDArray[float64]`	Angular frequency grid omega, shape (n_freq,), units rad/ps. Bin 0 is DC; bin 1 is Delta-omega = 2 * pi / (n_pad * dt).
`epsilon_real`	`NDArray[float64]`	Real part epsilon'(omega), shape (n_freq,), dimensionless.
`epsilon_imag`	`NDArray[float64]`	Loss spectrum epsilon''(omega), shape (n_freq,), dimensionless, positive sign convention.
`epsilon_static`	`float`	Static dielectric constant epsilon(0), dimensionless. May be `nan` if the route does not provide a static estimate.
`epsilon_inf`	`float`	High-frequency dielectric constant.
`route`	`str`	Computation route ("einstein-helfand" or "green-kubo").
`component`	`str`	System component ("full", "water", "ion").
`conductivity`	`NDArray[float64] \| None`	Optional conductivity spectrum sigma(omega), shape (n_freq,).

fit_debye ¶

fit_debye()

Fit a single Debye relaxation to this spectrum (NumPy only).

Uses the exact single-Debye identity epsilon''(omega) / (epsilon'(omega) - epsilon_inf) = omega * tau: tau is the least-squares slope through the origin of that ratio versus omega over the low-frequency rising branch (up to the loss peak), with a loss-peak fallback tau = 1 / omega_peak. The relaxation strength is the static limit delta_eps = epsilon(0) - epsilon_inf.

No SciPy: the estimator is closed-form linear regression. For broadened or skewed (Cole-Cole / Havriliak-Negami) line shapes do a nonlinear fit in your analysis script using :meth:DebyeSpectrumFit.epsilon as the model.

Returns:

Type	Description
`'DebyeSpectrumFit'`	DebyeSpectrumFit with tau, delta_eps, eps_inf, eps_static, omega_peak.

DielectricSusceptibilityResult `dataclass` ¶

DielectricSusceptibilityResult(
    meta=dict(), results=dict(), metadata=dict()
)

Bases: Result

Aggregate dielectric susceptibility result.

Attributes:

Name	Type	Description
`results`	`dict[str, DielectricResult]`	Mapping from route-component key to DielectricResult
`metadata`	`dict[str, Any]`	Trajectory parameters and computation info

to_dict ¶

to_dict()

Serialize with nested DielectricResult recursion.

JACFResult `dataclass` ¶

JACFResult(
    meta=dict(),
    time=(lambda: np.array([]))(),
    jacf=(lambda: np.array([]))(),
    sigma_running=(lambda: np.array([]))(),
    sigma=float("nan"),
)

Bases: TimeSeriesResult

Results from a Green-Kubo current-autocorrelation conductivity.

Attributes:

Name	Type	Description
`time`	`NDArray[float64]`	Time lag values (in ps), shape (n_time_lags,).
`jacf`	`NDArray[float64]`	Current autocorrelation `C(tau) = <J(0).J(tau)>`, (e*A/ps)^2, shape (n_time_lags,).
`sigma_running`	`NDArray[float64]`	Running Green-Kubo conductivity integral `sigma(tau) = 1/(3 V kB T) integral_0^tau C(t) dt` (S/m), shape (n_time_lags,).
`sigma`	`float`	DC ionic conductivity (S/m) — `sigma_running` at the final lag.

OnsagerResult `dataclass` ¶

OnsagerResult(
    meta=dict(),
    time=(lambda: np.array([]))(),
    correlations=dict(),
)

Bases: TimeSeriesResult

Results from an Onsager collective-displacement cross-correlation.

Attributes:

Name	Type	Description
`time`	`NDArray[float64]`	Time lag values (in ps), shape (n_time_lags,).
`correlations`	`dict[str, NDArray[float64]]`	Mapping from tag `"i,j"` to the cross-correlation `L_ij(tau) = <DP_i(tau).DP_j(tau)>` of the collective (summed) species displacements, shape (n_time_lags,), units A^2. The diagonal `"i,i"` is the collective MSD of species `i`.

PMSDResult `dataclass` ¶

PMSDResult(
    meta=dict(),
    time=(lambda: np.array([]))(),
    pmsd=(lambda: np.array([]))(),
)

Bases: TimeSeriesResult

Results from Polarization Mean Square Displacement calculation.

Attributes:

Name	Type	Description
`time`	`NDArray[float64]`	Time lag values (in ps)
`pmsd`	`NDArray[float64]`	Polarization MSD values at each time lag, shape (n_time_lags,)

PersistResult `dataclass` ¶

PersistResult(
    meta=dict(),
    time=(lambda: np.array([]))(),
    correlations=dict(),
)

Bases: TimeSeriesResult

Results from a pair-survival (persistence) correlation.

Attributes:

Name	Type	Description
`time`	`NDArray[float64]`	Time lag values (in ps), shape (n_time_lags,).
`correlations`	`dict[str, NDArray[float64]]`	Mapping from tag `"i,j:method:r0[,r1]"` to the persistence correlation `C(tau)` (mean surviving partners per reference particle), shape (n_time_lags,). `C(0)` is the mean coordination number.

Result `dataclass` ¶

Result(meta=dict())

Base class for computation results.

Subclasses should define specific fields for their result data.

to_dict ¶

to_dict()

Convert result to dictionary representation.

SpectralResult `dataclass` ¶

SpectralResult(
    meta=dict(),
    frequency=(lambda: np.array([]))(),
    spectrum=(lambda: np.array([]))(),
)

Bases: Result

Frequency-domain spectrum result.

Attributes:

Name	Type	Description
`frequency`	`NDArray[float64]`	Angular frequency grid omega, shape (n_freq,), units rad/ps.
`spectrum`	`NDArray[float64]`	Spectral density at each frequency, shape (n_freq,).

TimeSeriesResult `dataclass` ¶

TimeSeriesResult(
    meta=dict(), time=(lambda: np.array([]))()
)

Bases: Result

Base class for time-series analysis results.

Attributes:

Name	Type	Description
`time`	`NDArray[float64]`	Time points for the analysis (in ps or frames)

Compute¶

Architecture: raw Compute → Fit → scale¶

Module index¶

Shared base types¶

Base¶

base ¶

Compute ¶

dump ¶

Result types¶

result ¶

ACFResult dataclass ¶

ConductivityResult dataclass ¶

DebyeSpectrumFit dataclass ¶

epsilon ¶

DielectricResult dataclass ¶

fit_debye ¶

DielectricSusceptibilityResult dataclass ¶

to_dict ¶

JACFResult dataclass ¶

OnsagerResult dataclass ¶

PMSDResult dataclass ¶

PersistResult dataclass ¶

Result dataclass ¶

to_dict ¶

SpectralResult dataclass ¶

TimeSeriesResult dataclass ¶

ACFResult `dataclass` ¶

ConductivityResult `dataclass` ¶

DebyeSpectrumFit `dataclass` ¶

DielectricResult `dataclass` ¶

DielectricSusceptibilityResult `dataclass` ¶

JACFResult `dataclass` ¶

OnsagerResult `dataclass` ¶

PMSDResult `dataclass` ¶

PersistResult `dataclass` ¶

Result `dataclass` ¶

SpectralResult `dataclass` ¶

TimeSeriesResult `dataclass` ¶