nvalchemi.training.distillation.evaluation.compare_radial_distributions#

nvalchemi.training.distillation.evaluation.compare_radial_distributions(reference, candidate)[source]#

Score how far a candidate trajectory’s structure sits from a reference.

The headline number is the Jensen-Shannon divergence of the two normalized pair-distance histograms. It is symmetric, bounded in [0, 1] with a base-2 logarithm, and finite where one histogram has an empty bin. A Kullback-Leibler divergence or a chi-squared distance is not finite there on RDF data. The g(r) curves themselves are compared with an integrated absolute difference. The comparison is only as species-resolved as its curves. To gate chemical ordering, build one curve pair per species pair with the pair argument of radial_distribution().

Parameters:
  • reference (RadialDistribution) – Reference-trajectory curve.

  • candidate (RadialDistribution) – Student-trajectory curve, binned identically and resolved to the same species pair.

Returns:

The divergence and the two curve distances.

Return type:

RDFComparison

Raises:

ValueError – If the two curves do not share bin edges, if they resolve different species, or if either accumulated no pairs at all.

Examples

>>> from nvalchemi.training.distillation.evaluation import (
...     compare_radial_distributions,
...     radial_distribution,
... )
>>> match = compare_radial_distributions(
...     radial_distribution(teacher_frames),
...     radial_distribution(student_frames),
... )