nvalchemi.dynamics.mep.interpolate_paths#

nvalchemi.dynamics.mep.interpolate_paths(initial, final, num_images, remove_translation_and_rotation=False, fit_mask=None)[source]#

Interpolate paired endpoint batches into grouped reaction paths.

Graph i in initial is paired with graph i in final and becomes one path. Atomic correspondence is index-based: paired graphs must contain identical atomic numbers in identical order. Periodic endpoint displacements use the minimum-image convention.

Parameters:
  • initial (Batch) – Batches containing corresponding initial and final structures.

  • final (Batch) – Batches containing corresponding initial and final structures.

  • num_images (int or sequence of int) – Total number of images per path, including both endpoints. An integer applies the same count to every path. A sequence supplies one count per paired endpoint graph. Every count must be at least three.

  • remove_translation_and_rotation (bool, optional) – Align each final structure to its paired initial structure before interpolation. For non-periodic systems, both rigid translation and rotation are removed. For periodic systems, rotation is disabled and minimum-image translation is removed. Default is False.

  • fit_mask (Tensor or None, optional) – Boolean node mask with shape (initial.num_nodes,). Selected atom pairs determine each path’s alignment. Each path must select at least one atom. Requires remove_translation_and_rotation=True. None uses all atom pairs for fitting.

Returns:

Images ordered path-by-path with a populated group layout.

Return type:

Batch

Raises:
  • TypeError – If num_images is not an integer or integer sequence, or if fit_mask is not boolean.

  • ValueError – If the endpoint batches or interpolation options are incompatible.

Notes

Only positions, atomic numbers/masses/categories, cell/PBC, charges, spin fields, and node attributes are copied from each initial graph. Neighbor data, model outputs, dynamical state, and other custom fields are discarded. Reattach any custom model inputs to the resulting path before evaluation. Unless alignment is requested, endpoint coordinates are retained exactly, even when periodic interior images follow an unwrapped minimum-image path. With alignment, terminal images use the aligned final coordinates. The input endpoint batches are never modified.