functional_factory

Provides energy functionals.

class FunctionalFactory(*contributions: str | Module | Callable[[OFData], tuple[float, Tensor]])[source]

Class to construct energy functionals.

In the init, only contributions to the energy functional need to be passed. One instance can be used to construct multiple functionals that are specialized to multiple molecules.

__init__(*contributions: str | Module | Callable[[OFData], tuple[float, Tensor]])[source]

Initialize the energy functional with contributions that will be summed up.

Parameters:

contributions – The contributions (addends) to the energy functional. Allowed strings are either libxc functionals, torch functionals, “hartree” or “nuclear_attraction”. Can also be a torch.nn.Module or a callable.

Raises:

ValueError – If there are duplicate contributions. This is important since energies are stored in a dict, see Energies.

__str__()[source]

Return a string that contains the contribution names.

construct(mol: Mole, coulomb_matrix: Tensor, nuclear_attraction_vector: Tensor, grid: Grids | None = None, ao: Tensor | None = None, max_xc_memory: int = 4000) → Callable[[OFData], tuple[Energies, Tensor]][source]

Construct the energy functional.

Parameters:

  • mol – The molecule of the current optimization.

  • coulomb_matrix – The Coulomb matrix.

  • nuclear_attraction_vector – The nuclear attraction vector.

  • grid – The grid for the evaluation of the xc functional.

  • ao – The atomic orbital values on the grid.

  • max_xc_memory – The maximum (additional to ao memory usage) memory in MB for the evaluation of the xc functional.

Returns:

The energy functional.

evaluate_functional(sample: OFData, mol: Mole, coulomb_matrix: Tensor, nuclear_attraction_vector: Tensor, grid: Grids | None = None, grid_weights: Tensor | None = None, ao: ndarray | None = None, max_xc_memory: int = 4000) → tuple[Energies, Tensor][source]

Evaluate the energy functional for the given coefficients.

The main use of this function is to be partially called by construct().

Parameters:

  • sample – The OFData object for a torch.nn.Module. The coeffs attribute is updated.

  • mol – The molecule of the current optimization.

  • coulomb_matrix – The Coulomb matrix.

  • nuclear_attraction_vector – The nuclear attraction vector.

  • grid – The grid for the evaluation of the xc functional.

  • grid_weights – The weights of the grid points.

  • ao – The atomic orbital values on the grid.

  • max_xc_memory – The maximum (additional to ao memory usage) memory in MB for the evaluation of the xc functional.

Returns:

The energies and gradient.

classmethod from_module(module: Module, xc_functional: str = None, negative_integrated_density_penalty_weight: float = 0.0)[source]

Construct a functional from a torch.nn.Module.

Parameters:

  • module – The torch.nn.Module.

  • xc_functional – The xc functional. Can be omitted if the module learned the xc functional. Note that torch_PBE will be converted to the PBE X and PBE C functional. Other torch functionals will be used as is (but can thus only be one functional).

Returns:

The functional factory.

get_energies_label(sample: OFData, basis_info: BasisInfo) → Energies[source]

Get the energies label from OFData object.

Parameters:

sample – OFData object with the ground state energy labels.

Returns:

Energies object initialized with the energies from OFData object corresponding to the functional contributions.

classmethod get_vw_functional(xc_functional: str)[source]

Construct a functional with the von Weizsäcker kinetic energy functional.

The von Weizsäcker kinetic energy functional is exact for two-electron molecules. The remaining erroneous contribution is the exchange part of the xc functional (there should be no correlation part for two-electron molecules).

Parameters:

xc_functional – The xc functional.

class NegativeIntegratedDensity(grid_weights: Tensor, ao: Tensor, gamma: float = 1000.0)[source]

Class to compute a penalty term on the negative integrated density.

__init__(grid_weights: Tensor, ao: Tensor, gamma: float = 1000.0)[source]

Initialize the negative integrated density penalty.

Parameters:

  • grid_weights – The grid_weights.

  • ao – The atomic orbital values on the grid.

  • sample – The OFData object.

  • gamma – The penalty factor.

forward(sample: OFData) → tuple[Tensor, Tensor][source]

Compute the negative integrated density penalty.

Parameters:

sample – The OFData object.

Returns:

The energy (0.0) and gradient of the penalty term.

hartree_functional(coeffs: Tensor, coulomb_matrix: Tensor) → tuple[float, Tensor][source]

Get the Hartree energy for the given coefficients.

Parameters:

  • coulomb_matrix – Coulomb matrix of the system.

  • coeffs – The coefficients p.

Returns:

The Hartree energy and its gradient.

nuclear_attraction_functional(coeffs: Tensor, nuclear_attraction_vector: Tensor) → tuple[float, Tensor][source]

Get the nuclear attraction energy for the given coefficients.

Parameters:

  • nuclear_attraction_vector – The nuclear attraction vector.

  • coeffs – The coefficients p.

Returns:

The nuclear attraction energy and its gradient.

requires_grid(target_key: str, negative_integrated_density_penalty_weight: float | None = None) → bool[source]

Check if the functional requires a grid for the evaluation.

Returns:

True if the functional requires a grid, False otherwise.