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 through from_energy(), which differentiates an energy the caller already computed. Its matvec() method computes (d^2 E / dR^2) @ v from a retained autograd graph. Keep model parameters, buffers, execution mode, and pipeline wiring unchanged while the operator is active. Call close() 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 with positions.requires_grad enabled does. Nothing is re-evaluated: the operator retains the caller’s graph, so products taken with create_graph=True stay 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_grad enabled that the energy was computed from, on the same device as energy.

Returns:

Active operator over the supplied graph.

Return type:

HessianOperator

Raises:
  • TypeError – If either argument is not a floating-point tensor.

  • ValueError – If positions does not require gradients or the tensors are on different devices.

  • RuntimeError – If energy carries no autograd graph, or its first position derivative is not connected to positions.

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 energy is 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, as BaseModelMixin.prepare_hessian does.

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 False returns a detached product.

Returns:

Hessian-vector product aligned with the prepared positions.

Return type:

torch.Tensor

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.