nvalchemi.dynamics.mep.align_batch_positions#
- nvalchemi.dynamics.mep.align_batch_positions(reference_positions, mobile_positions, batch_idx, num_atoms_per_graph, cell=None, pbc=None, fit_mask=None, *, prepared_mic=None, skip_extra_checks=False)[source]#
Align each mobile structure in a batch to its paired reference.
Both position tensors contain one or more graphs in the same flattened node layout.
batch_idxassigns each atom to a graph, and every mobile graph is aligned independently to the reference graph with the same index.Fully non-periodic graphs are independently centered and quaternion-rotated to minimize their unweighted, atom-wise Cartesian RMSD. An optional node mask can restrict the atoms used to fit each rigid transform, which is still applied to every atom. For graphs with any active periodic axis, rotation is disabled: per-atom displacements are mapped to their minimum images and the mean displacement of the selected atoms is removed. Neither
reference_positionsnormobile_positionsis modified.- Parameters:
reference_positions (Tensor) – Flattened fixed target positions for all graphs, shape
(total_atoms, 3).mobile_positions (Tensor) – Flattened positions to align using the same graph and atom ordering as
reference_positions, shape(total_atoms, 3).batch_idx (Tensor) – Integer graph membership for every atom, shaped
(total_atoms,).num_atoms_per_graph (Tensor) – Number of atoms in each graph, shaped
(num_graphs,). Every graph must contain at least one atom and the counts must agree withbatch_idx.cell (Tensor or None, optional) – Per-graph cell matrices shaped
(num_graphs, 3, 3). Required for every graph with an active periodic axis. Selected periodic cell vectors must be linearly independent; unused rows may be singular.pbc (Tensor or None, optional) – Boolean periodicity flags shaped
(num_graphs, 3).Nonemeans every graph is fully non-periodic.fit_mask (Tensor or None, optional) – Boolean node mask shaped
(total_atoms,). Selected corresponding atom pairs determine the fitted transform for each graph, while that transform is applied to every atom. Every graph must select at least one atom.Noneselects every atom.prepared_mic (PreparedMIC or None, optional) – Reusable MIC data prepared for
cellandpbc. Supplying it avoids repeating cell-dependent lattice analysis.skip_extra_checks (bool, optional) – Skip structural checks for prevalidated batch inputs. The fitting mask is always validated. Default is false.
- Returns:
Aligned flat positions, per-graph rotations shaped
(num_graphs, 3, 3), and per-graph translations shaped(num_graphs, 3). Periodic graphs have identity rotations.- Return type:
- Raises:
TypeError – If positions are not floating point, graph metadata is not integer, or periodicity flags or
fit_maskare not boolean.ValueError – If shapes, graph membership, dtypes, devices, or periodic inputs are incompatible.