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_ADMISSIONand publishes the combined endpoint and user-fixed node mask for aFreezeAtomsHook. AtDynamicsStage.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 atDynamicsStage.ON_ADMISSIONfor batch preparation.- Type:
- 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)