nvalchemi.training.distillation.evaluation.radial_distribution#

nvalchemi.training.distillation.evaluation.radial_distribution(frames, *, r_max=6.0, num_bins=60, pair=None)[source]#

Accumulate the radial distribution function of a trajectory.

Every graph is one frame, so a trajectory that SnapshotHook captured into a DataSink can be passed straight from sink.read(). Pairs are collected with the framework’s own neighbor build at r_max on a copy of each frame, so the caller’s neighbor state is left as it was. By default every pair goes into one histogram: the number-weighted total g(r) = \sum_{ab} x_a x_b g_{ab}(r), which cannot see chemical ordering. Pass pair to resolve one species pair and gate a multi-species student on its partial curves. The normalization is g(r) = n(r) / (N \rho V_{shell}), generalized over frames. Each pair is apportioned between the two bins whose centers bracket its distance, and the neighbor list is built one bin past r_max. The histogram is therefore continuous in the positions rather than stepping when a shell crosses a bin edge.

Parameters:
  • frames (Iterable[Batch] | Batch) – Periodic frames to accumulate.

  • r_max (float, optional) – Largest pair distance binned, in A. It may exceed the cell vectors, because the neighbor build enumerates as many periodic images as the cutoff needs. Default 6.0.

  • num_bins (int, optional) – Uniform bins between 0 and r_max. Default 60.

  • pair (Sequence[int] | None, optional) – Two atomic numbers (a, b). Only pairs whose first atom has atomic number a and whose second atom has b are counted. Default None (every pair, pooled into the species-blind total).

Returns:

Curve, raw counts, and the sizes they were accumulated over.

Return type:

RadialDistribution

Raises:

ValueError – If r_max or num_bins is not positive. If pair is not two atomic numbers, or names a species the frames do not carry. If a frame is not periodic or its cell encloses no volume, or if no frame was supplied.

Examples

>>> from nvalchemi.training.distillation.evaluation import radial_distribution
>>> student_rdf = radial_distribution(sink.read(), r_max=6.0)
>>> na_cl = radial_distribution(sink.read(), pair=(11, 17))