nvalchemi.dynamics.mep.hooks.NEBForceHook#

class nvalchemi.dynamics.mep.hooks.NEBForceHook(*, energy_stats_hook, spring=0.1, method='improved_tangent', endpoint_mode='fixed', fixed_atom_indices=None)[source]#

Configure optimizer-facing forces for nudged elastic band dynamics.

The hook prepares structural state at DynamicsStage.ON_ADMISSION and publishes the combined endpoint and user-fixed node mask for a FreezeAtomsHook. At DynamicsStage.AFTER_COMPUTE, it refreshes the spring constants and then replaces physical forces with the selected NEB force formulation. Energy extrema and image force modes come from hooks registered before this hook.

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

  • spring (float or SpringConfig, optional) – Positive constant spring value or a policy that resolves one spring constant for every adjacent image pair. Default is 0.1.

  • method (str, NEBMethod, or TorchNEBMethod, optional) – Built-in method name, custom Warp equations, or a Torch method that computes NEB effective forces for the batch of paths. Default is "improved_tangent".

  • endpoint_mode ({"fixed", "relaxed"}, optional) – Whether path endpoint images remain fixed or use their physical forces. Default is "fixed".

  • fixed_atom_indices (mapping of int to sequence of int, optional) – Image-local atom indices that must remain fixed in every image of each keyed path. Keys are zero-based path indices; omitted paths have no additional fixed atoms. All three Cartesian components of every selected atom are fixed. Atoms in fixed endpoint images are added automatically.

stage#

Primary hook stage, DynamicsStage.AFTER_COMPUTE. The hook also runs at DynamicsStage.ON_ADMISSION for batch preparation.

Type:

DynamicsStage

frequency#

Always 1. NEB forces must be refreshed after every model-force evaluation.

Type:

int

Notes

Component-level constraints, such as fixing only one Cartesian axis, are not supported.

Examples

Use the improved-tangent method with a constant spring:

energy_stats = PathEnergyStatsHook()
hook = NEBForceHook(
    energy_stats_hook=energy_stats,
    spring=0.1,
    method="improved_tangent",
    fixed_atom_indices={0: [0, 2], 1: [1]},
)

Pass a custom equation configuration directly:

method = NEBMethod(
    tangent_weights_fn=my_tangent_weights,
    effective_force_fn=my_effective_force,
    climbing_force_fn=my_climbing_force,
)
hook = NEBForceHook(energy_stats_hook=energy_stats, method=method)

Pass a Torch callable accepting (batch, *, ...) in the same way:

hook = NEBForceHook(energy_stats_hook=energy_stats, method=my_torch_method)
on_register(workflow)[source]#

Require group-aware dynamics for NEB force construction.

Parameters:

workflow (object) – Workflow on which this hook is being registered.

Raises:

ValueError – If the workflow does not enable group-aware dynamics.

Return type:

None