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_ADMISSIONand refreshes them frombatch.energyatDynamicsStage.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_ADMISSIONso 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:
- 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.