nvalchemi.dynamics.mep.hooks.PathEnergyStatsHook#

class nvalchemi.dynamics.mep.hooks.PathEnergyStatsHook[source]#

Compute reusable energy statistics for each path after model evaluation.

Register this hook before other hooks such as climbing-image selection, path-force construction, and diagnostics. It prepares persistent buffers at DynamicsStage.ON_ADMISSION and refreshes them from batch.energy at DynamicsStage.AFTER_COMPUTE.

Pass this same registered instance to downstream hooks that consume the statistics. They should call get_stats() after this hook has run for the current evaluation. In eager execution, get_stats() raises if the energy tensor has changed since the statistics were refreshed. This check is skipped during compilation because tensor mutation versions are private eager metadata, so compiled hooks must still be registered in execution order.

The hook prepares its own int32 path offsets during ON_ADMISSION so it can be used independently of path-force hooks.

get_stats(ctx)[source]#

Return statistics computed for the current energy evaluation.

Parameters:

ctx (DynamicsContext) – Context containing the energy tensor whose statistics are needed.

Returns:

Current per-path energy statistics.

Return type:

PathEnergyStats

Raises:

RuntimeError – If the hook has not prepared its buffers at ON_ADMISSION, has not refreshed them for the current energy tensor update, or cannot validate an inference tensor’s mutation version.