pyscivr.save module

Saving and loading of trajectories and Hessians in the .npz format.

See sections II B 2 and II C of the paper for details.

Notation:

  • N: number of atoms.

  • T: number of time steps of the trajectory.

  • K: number of constraints.

  • S: number of steps at which the Hessian is evaluated.

  • m: number of active coordinates.

pyscivr.save.save_trajectory(fpath, traj, **meta)[source]

Save a trajectory.

Only the keys (posi, mome, force, potential_energy, total_energy, dt, mass) are saved. The Lagrange multipliers lam and mu are not saved, since they can be restored by load_trajectory(). Additional metadata supplied via **meta is also saved.

Parameters:
Return type:

None

pyscivr.save.restore_multipliers(coord_const, posi, mome, force, mass, dt, *, atol=1e-10)[source]

Restore the Lagrange multipliers of SHAKE/RATTLE from a trajectory.

The multipliers are obtained by solving (Eqs. (25)-(27) in the paper)

\[ \begin{align}\begin{aligned}q_{n+1} - \tilde{q}_{n+1} &= \Delta t M^{-1} \mathcal{G}(q_{n})^T \lambda_{n}, \quad \tilde{q}_{n+1} = q_n + \Delta t M^{-1} p_n + \frac{\Delta t^2}{2} M^{-1} F(q_n)\\p_{n+1} - \tilde{p}_{n+1} &= \mathcal{G}(q_{n+1})^T \mu_{n+1}, \quad \tilde{p}_{n+1} = p_n + \frac{\Delta t}{2} (F(q_n) + F(q_{n+1})) + \mathcal{G}(q_{n})^T \lambda_{n}\end{aligned}\end{align} \]

in the least-squares sense, and the residuals are checked to be small.

Parameters:

  • coord_const (InternalCoordinates) – InternalCoordinates defining the K constraints, the same as used in pyscivr.integrators.ShakeRattle.

  • posi (ArrayLike) – (T, N, 3) or (T, 3N) positions.

  • mome (ArrayLike) – (T, N, 3) or (T, 3N) momenta.

  • force (ArrayLike) – (T, N, 3) or (T, 3N) forces.

  • mass (ArrayLike) – (N,) atomic masses.

  • dt (float) – Time step.

  • atol (float) – Absolute tolerance for checking the residuals.

Returns:

(lam, mu), where

  • lam: (T, K) Lagrange multipliers for position constraints.

  • mu: (T, K) Lagrange multipliers for momentum constraints.

Raises:

AssertionError – If the residuals exceed atol, i.e., the trajectory is not consistent with SHAKE/RATTLE under coord_const.

Return type:

tuple[NDArray[np.float64], NDArray[np.float64]]

pyscivr.save.load_trajectory(fpath, coord_const=None)[source]

Load a trajectory saved by save_trajectory().

Parameters:
Returns:

Trajectory with keys of (posi, mome, force, potential_energy, total_energy, dt, mass), and additional data saved as meta. If coord_const is provided, the Lagrange multipliers lam and mu are also included.

Return type:

dict[str, Any]

pyscivr.save.save_hessian(fpath, steps, hess, posi, coord_all, active_idx, **meta)[source]

Save the Hessians or projected Hessians in a compressed form.

To reduce storage requirements, the (S, 3N, 3N) full Hessians \(K\) are saved as K A_A of shape (S, 3N, m) (see also pyscivr.hessian.eval_hess_active()). The projected Hessians \mathfrak{P}^T K \mathfrak{P} can be restored by load_hessian().

Parameters:

  • fpath (str) – Path to save the Hessians.

  • steps (ArrayLike) – (S,) indices of the steps where the Hessians are evaluated.

  • hess (ArrayLike) – (S, 3N, 3N) Hessians or projected Hessians.

  • posi (ArrayLike) – (T, N, 3) or (T, 3N) positions of the trajectory.

  • coord_all (InternalCoordinates) – InternalCoordinates for the full system. It must define 3N coordinates for coordinate transformation.

  • active_idx (ArrayLike) – (m,) row indices of the active coordinates in coord_all, in the row order after build().

  • **meta (Any) – Additional metadata to save with the Hessians.

Return type:

None

Note

The file contains the keys steps, hess and active_idx, in addition to meta.

pyscivr.save.load_hessian(fpath, coord_all, posi, n_step=None, symmetrize=True)[source]

Restore the projected Hessians saved by save_hessian().

The projected Hessians are restored as \(\mathfrak{P}^T K \mathfrak{P}\), where \(\mathfrak{P} = A_A B_A\). Since \(\mathfrak{P}\) is idempotent, the same Hessians can be restored whether the Hessians are projected or not.

Parameters:

  • fpath (str) – Path to the saved Hessians.

  • coord_all (InternalCoordinates) – InternalCoordinates for the full system. It must define 3N coordinates for coordinate transformation.

  • posi (ArrayLike) – (T, N, 3) or (T, 3N) positions of the trajectory.

  • n_step – If given, the Hessians are interpolated (cubic spline) to all steps. (0, 1, ..., n_step-1) (see pyscivr.hessian.interpolate_hessian()).

  • symmetrize – If True, the Hessians are symmetrized.

Returns:

(steps, hess), where

  • steps: (S,) indices of the steps where the Hessians are evaluated.

  • hess: (S, 3N, 3N) projected Hessians, or (n_step, 3N, 3N) if n_step is given.

Return type:

tuple[NDArray[np.int64], NDArray[np.float64]]