nvalchemi.dynamics.mep.hooks.PathDiagnosticsHook#

class nvalchemi.dynamics.mep.hooks.PathDiagnosticsHook(*, energy_stats_hook, frequency=1)[source]#

Compute and cache one diagnostics record per reaction path.

A reaction path is represented by one contiguous group of graphs in batch.group_layout. Each graph is one path image, ordered from the initial endpoint to the final endpoint. Custom reaction-path methods can use this hook without subclassing it by satisfying the input and registration contracts below.

Parameters:
  • energy_stats_hook (PathEnergyStatsHook) – Shared path-energy statistics hook registered before this hook.

  • frequency (int, optional) – Refresh diagnostics every frequency workflow steps. Default is 1.

  • fields (Required batch)

  • ---------------------

  • batch.group_idx – One group index per image, shape (num_images,). Call batch.set_group_layout(...) before running the workflow. Images belonging to one path must be contiguous and ordered along that path.

  • batch.energy – Potential energy for every image. This must be current before the shared PathEnergyStatsHook runs.

  • batch.forces – Effective optimization force for every atom, shape (num_atoms, 3). This is the force whose norm contributes to the reported path fmax; it need not be the model’s unmodified physical force.

  • batch.forward_link_length –

    Distance from each image to the next image in the same path, shape (num_images,). Values must use the same floating-point dtype and device as batch.positions. The final image of every path has no successor and must therefore have a link length of zero.

    A method-specific force hook must create this field before this hook runs at ON_ADMISSION and refresh it before this hook runs at AFTER_COMPUTE.

  • ordering (Hook)

  • -------------

  • AFTER_COMPUTE (At)

  • order (hooks must be registered in this)

:param 1. PathEnergyStatsHook: :param 2. The method-specific effective-force and link-length hook: :param 3. PathDiagnosticsHook: :param This hook reduces image- and atom-cardinality inputs to one value per path.: :param Downstream consumers should be registered after it and retrieve the current: :param values with get_diagnostics().: :param Active-path behavior: :param ——————–: :param Activity must be consistent across every image in a path. Diagnostics for: :param inactive paths retain their last valid values. Newly admitted paths contain: :param NaN floating-point diagnostics and a highest-interior-image index of -1 until: :param their first active evaluation.:

get_diagnostics()[source]#

Return diagnostics refreshed for the current path evaluation.

Raises:

RuntimeError – If the hook has not prepared its buffers at ON_ADMISSION.

Return type:

PathDiagnostics

on_register(workflow)[source]#

Require group-aware dynamics for per-path reductions.

Parameters:

workflow (object)

Return type:

None