nvalchemi.models.HessianOperator#
- class nvalchemi.models.HessianOperator(context)[source]#
Matrix-free Hessian for repeated products at one geometry.
Obtain an operator through
prepare_hessian(), which runs its own energy-only forward on an independent batch snapshot, or throughfrom_energy(), which differentiates an energy the caller already computed. Itsmatvec()method computes(d^2 E / dR^2) @ vfrom a retained autograd graph. Keep model parameters, buffers, execution mode, and pipeline wiring unchanged while the operator is active. Callclose()or use a context manager to release the graph.- Parameters:
context (AbstractContextManager[_DerivativeGraph])
- close()[source]#
Release the retained derivative graph; repeated calls are harmless.
- Return type:
None
- classmethod from_energy(energy, positions)[source]#
Build an operator from an energy the caller already computed.
The energy must carry an autograd graph back to
positions, as the output of a forward pass run withpositions.requires_gradenabled does. Nothing is re-evaluated: the operator retains the caller’s graph, so products taken withcreate_graph=Truestay attached to whatever produced the energy, including the model parameters and any DDP wrapper whose forward computed it.- Parameters:
energy (torch.Tensor) – Floating tensor whose sum is differentiated, typically of shape
(num_graphs, 1).positions (torch.Tensor) – Floating tensor with
requires_gradenabled that the energy was computed from, on the same device asenergy.
- Returns:
Active operator over the supplied graph.
- Return type:
- Raises:
TypeError – If either argument is not a floating-point tensor.
ValueError – If
positionsdoes not require gradients or the tensors are on different devices.RuntimeError – If
energycarries no autograd graph, or its first position derivative is not connected topositions.
Examples
>>> import torch >>> from nvalchemi.models import HessianOperator >>> batch.positions.requires_grad_(True) >>> energy = model(batch)["energy"] >>> with HessianOperator.from_energy(energy, batch.positions) as op: ... product = op.matvec(torch.randn_like(batch.positions))
Notes
No wrapper capability check runs on this path, because no wrapper is involved: the caller vouches that the graph behind
energyis twice differentiable. An energy whose first derivative does not depend on the positions, such as one linear in them, is refused rather than given a zero Hessian, asBaseModelMixin.prepare_hessiandoes.
- matvec(vector, *, create_graph=False)[source]#
Multiply the retained Hessian by one position-space vector.
- Parameters:
vector (torch.Tensor) – Floating tensor matching the prepared positions in shape, dtype, and device.
create_graph (bool, optional) – Keep the product attached to the energy graph, and through it to the model parameters, so a loss can backpropagate through the product. Default
Falsereturns a detached product.
- Returns:
Hessian-vector product aligned with the prepared positions.
- Return type:
- Raises:
RuntimeError – If the operator has been closed.
TypeError – If the vector is not a floating-point tensor.
ValueError – If shape, dtype, or device does not match the prepared positions.