In-tree GFN2-xTB calculator. More...

#include <xtb_calculator.h>

Public Types
enum class	Method { GFN2 }
	Tight-binding method. More...

Public Member Functions
	XtbCalculator (const occ::core::Molecule &mol)
	Construct from an isolated molecule (positions in Å — converted to Bohr internally).

	XtbCalculator (const occ::core::Dimer &dimer)
	Construct from a dimer; equivalent to a molecule built from the union of monomer atoms.

	XtbCalculator (const occ::crystal::Crystal &crystal)
	Construct from a 3D periodic crystal.

	XtbCalculator (XtbCalculator &&)=default

XtbCalculator &	operator= (XtbCalculator &&)=default

	XtbCalculator (const XtbCalculator &)=delete

XtbCalculator &	operator= (const XtbCalculator &)=delete

Method	method () const
	Tight-binding method enum (currently always `Method::GFN2`).

std::string	method_name () const
	Method name as a string ("GFN2"). Convenience for bindings.

std::string	backend_name () const
	Backend name as a string ("Native"). Distinguishes from `TbliteCalculator`.

bool	is_periodic () const
	True if the calculator was constructed from a `Crystal`.

int	num_atoms () const
	Number of atoms in the (central) cell.

const IVec &	atomic_numbers () const
	Atomic numbers (length = `num_atoms()`).

const Mat3N &	positions () const
	Cartesian positions in Bohr (3 × N).

Mat3	lattice () const
	Lattice vectors as columns in Bohr (periodic only — throws otherwise).

void	set_charge (double c)
	Net molecular / unit-cell charge in electrons.

double	charge () const

void	set_num_unpaired_electrons (int n)
	Number of unpaired electrons (open-shell).

int	num_unpaired_electrons () const

void	set_max_iterations (int iterations)
	Maximum SCC iterations.

int	max_iterations () const

void	set_temperature (double temp)
	Electronic temperature (K) for Fermi smearing.

double	temperature () const

void	set_mixer_damping (double damping_factor)
	SCC mixer damping factor (weight on the previous iteration; ∈ [0, 1)).

double	mixer_damping () const

void	set_include_multipoles (bool on)
	Toggle CAMM multipole AES + on-site polarization (`true` for full GFN2).

bool	include_multipoles () const

void	set_include_dispersion (bool on)
	Toggle native D4 dispersion.

bool	include_dispersion () const

void	set_kpoints (int n1, int n2, int n3)
	Monkhorst-Pack k-grid for the periodic SCC.

std::array< int, 3 >	kpoints () const
	Read back the configured k-mesh.

bool	set_solvent (const std::string &name)
	Enable an implicit-solvent model by name.

void	set_solvation_model (std::shared_ptr< XtbSolvationModel > model)
	Attach an `XtbSolvationModel` (or clear it by passing `nullptr`).

const std::shared_ptr< XtbSolvationModel > &	solvation_model () const

void	update_structure (const Mat3N &positions)
	Update Cartesian positions (Bohr).

void	update_structure (const Mat3N &positions, const Mat3 &lattice_bohr)
	Update positions and lattice vectors simultaneously (periodic only).

const XtbResult &	single_point ()
	Run an SCC at the current geometry / configuration.

double	single_point_energy ()
	Convenience wrapper around `single_point()` returning just the total energy (Hartree).

const XtbResult &	last_result () const
	Read-only access to the most recent SCC result (call after `single_point()`).

Vec	charges () const
	Per-atom Mulliken charges (xtb convention: positive = electron-deficient).

Mat	bond_orders () const
	Wiberg bond-order matrix (N × N).

double	total_energy () const
	Total energy from the most recent SCC (Hartree).

double	scc_energy () const
	Electronic + isotropic-Coulomb + (multipole AES if on) energy (Hartree).

double	repulsion_energy () const
	Closed-form repulsion energy (Hartree).

double	dispersion_energy () const
	Dispersion (D4) energy (Hartree); zero if dispersion is disabled.

Mat3N	gradient ()
	Analytical nuclear gradient (Hartree/Bohr, 3 × N).

Mat3N	gradient_numerical (double step_bohr=1e-3)
	Numerical 5-point central-difference gradient.

std::pair< double, Mat3N >	compute_energy_and_gradient (bool numerical=false, double step_bohr=1e-3)
	(energy, gradient) pair.

Mat	compute_hessian_numerical (double step_bohr=0.005)
	Numerical 3N×3N Hessian (Hartree/Bohr²) via 5-point central differences of `gradient()`.

occ::core::VibrationalModes	compute_vibrational_modes (double step_bohr=0.005, bool project_tr_rot=false)
	Convenience: build the Hessian and run a normal-mode analysis, returning frequencies (cm⁻¹), normal modes, and the mass-weighted Hessian.

occ::core::Molecule	to_molecule () const
	Snapshot the current atoms / positions as an `occ::core::Molecule` (positions returned in Å).

occ::crystal::Crystal	to_crystal () const
	Snapshot the current periodic system as an `occ::crystal::Crystal` (periodic only — throws otherwise).

occ::qm::Wavefunction	to_wavefunction () const
	Convert the converged SCC state into a `qm::Wavefunction` so the rest of occ (`.owf.json` save/load, `occ cube`, `occ isosurface`, Mulliken / Hirshfeld analysis, ESP, ...) can consume the GFN2 result.

void	print_summary () const
	Print a summary (energy decomposition, charges, HOMO/LUMO/gap) at INFO log level.

Mat3N	compute_gradient_numerical (double step_bohr=1e-3)

Mat3N	compute_gradient_analytical ()

Detailed Description

In-tree GFN2-xTB calculator.

Mirrors the public surface of TbliteCalculator so callers can swap backends. Handles isolated molecules, dimers, and 3D periodic crystals (Γ-only or k-point sampled).

Typical usage:

XtbCalculator calc(molecule);
calc.set_charge(0);
const XtbResult &r = calc.single_point();
double E = r.total_energy;
Mat3N grad = calc.gradient();

Member Enumeration Documentation

◆ Method

enum class occ::xtb::XtbCalculator::Method

strong

Tight-binding method.

Only GFN2 is implemented; the enum exists so the API can extend to GFN1 / GFN0 later without breaking callers.

Enumerator
GFN2

Constructor & Destructor Documentation

◆ XtbCalculator() [1/5]

occ::xtb::XtbCalculator::XtbCalculator ( const occ::core::Molecule & mol )

explicit

Construct from an isolated molecule (positions in Å — converted to Bohr internally).

Inherits the molecule's charge.

◆ XtbCalculator() [2/5]

occ::xtb::XtbCalculator::XtbCalculator ( const occ::core::Dimer & dimer )

explicit

Construct from a dimer; equivalent to a molecule built from the union of monomer atoms.

◆ XtbCalculator() [3/5]

occ::xtb::XtbCalculator::XtbCalculator ( const occ::crystal::Crystal & crystal )

explicit

Construct from a 3D periodic crystal.

Defaults to Γ-only sampling; call set_kpoints to enable a Monkhorst-Pack mesh.

◆ XtbCalculator() [4/5]

occ::xtb::XtbCalculator::XtbCalculator ( XtbCalculator && )

default

◆ XtbCalculator() [5/5]

occ::xtb::XtbCalculator::XtbCalculator ( const XtbCalculator & )

delete

Member Function Documentation

◆ atomic_numbers()

const IVec & occ::xtb::XtbCalculator::atomic_numbers ( ) const

inline

Atomic numbers (length = num_atoms()).

◆ backend_name()

std::string occ::xtb::XtbCalculator::backend_name ( ) const

inline

Backend name as a string ("Native"). Distinguishes from TbliteCalculator.

◆ bond_orders()

Mat occ::xtb::XtbCalculator::bond_orders ( ) const

Wiberg bond-order matrix (N × N).

◆ charge()

double occ::xtb::XtbCalculator::charge ( ) const

inline

◆ charges()

Vec occ::xtb::XtbCalculator::charges ( ) const

Per-atom Mulliken charges (xtb convention: positive = electron-deficient).

◆ compute_energy_and_gradient()

std::pair< double, Mat3N > occ::xtb::XtbCalculator::compute_energy_and_gradient	(	bool	numerical = `false`,
		double	step_bohr = `1e-3`
	)

(energy, gradient) pair.

Uses analytical by default; pass numerical = true for the FD oracle.

◆ compute_gradient_analytical()

Mat3N occ::xtb::XtbCalculator::compute_gradient_analytical ( )

inline

Deprecated:: Use gradient instead.

◆ compute_gradient_numerical()

Mat3N occ::xtb::XtbCalculator::compute_gradient_numerical ( double step_bohr = 1e-3 )

inline

Deprecated:: Use gradient_numerical instead.

◆ compute_hessian_numerical()

Mat occ::xtb::XtbCalculator::compute_hessian_numerical ( double step_bohr = 0.005 )

Numerical 3N×3N Hessian (Hartree/Bohr²) via 5-point central differences of gradient().

Costs 6N analytical-gradient evaluations (each is one multipole-on SCC + the analytical gradient assembly). The returned matrix is symmetrised. Inherits gradient()'s convention — full multipole-on (CAMM AES + on-site polarization) since Phase 5d-rest landed.

◆ compute_vibrational_modes()

occ::core::VibrationalModes occ::xtb::XtbCalculator::compute_vibrational_modes	(	double	step_bohr = `0.005`,
		bool	project_tr_rot = `false`
	)

Convenience: build the Hessian and run a normal-mode analysis, returning frequencies (cm⁻¹), normal modes, and the mass-weighted Hessian.

Calls compute_hessian_numerical then core::compute_vibrational_modes with the calculator's atomic masses

positions. Set project_tr_rot = true to project translations and rotations out of the mass-weighted Hessian (ORCA-style PROJECTTR).

◆ dispersion_energy()

double occ::xtb::XtbCalculator::dispersion_energy ( ) const

inline

Dispersion (D4) energy (Hartree); zero if dispersion is disabled.

◆ gradient()

Mat3N occ::xtb::XtbCalculator::gradient ( )

Analytical nuclear gradient (Hartree/Bohr, 3 × N).

Runs a charge-only SCC internally (no anisotropic multipole contribution to the gradient energy) so the returned (energy, gradient) pair is self-consistent; see compute_gradient_analytical body for the breakdown.

◆ gradient_numerical()

Mat3N occ::xtb::XtbCalculator::gradient_numerical ( double step_bohr = 1e-3 )

Numerical 5-point central-difference gradient.

Slow (6N SCC evals); useful as an oracle to validate the analytical version.

◆ include_dispersion()

bool occ::xtb::XtbCalculator::include_dispersion ( ) const

◆ include_multipoles()

bool occ::xtb::XtbCalculator::include_multipoles ( ) const

◆ is_periodic()

bool occ::xtb::XtbCalculator::is_periodic ( ) const

inline

True if the calculator was constructed from a Crystal.

◆ kpoints()

std::array< int, 3 > occ::xtb::XtbCalculator::kpoints ( ) const

Read back the configured k-mesh.

◆ last_result()

const XtbResult & occ::xtb::XtbCalculator::last_result ( ) const

inline

Read-only access to the most recent SCC result (call after single_point()).

◆ lattice()

Mat3 occ::xtb::XtbCalculator::lattice ( ) const

Lattice vectors as columns in Bohr (periodic only — throws otherwise).

◆ max_iterations()

int occ::xtb::XtbCalculator::max_iterations ( ) const

◆ method()

Method occ::xtb::XtbCalculator::method ( ) const

inline

Tight-binding method enum (currently always Method::GFN2).

◆ method_name()

std::string occ::xtb::XtbCalculator::method_name ( ) const

inline

Method name as a string ("GFN2"). Convenience for bindings.

◆ mixer_damping()

double occ::xtb::XtbCalculator::mixer_damping ( ) const

◆ num_atoms()

int occ::xtb::XtbCalculator::num_atoms ( ) const

inline

Number of atoms in the (central) cell.

◆ num_unpaired_electrons()

int occ::xtb::XtbCalculator::num_unpaired_electrons ( ) const

inline

◆ operator=() [1/2]

XtbCalculator & occ::xtb::XtbCalculator::operator= ( const XtbCalculator & )

delete

◆ operator=() [2/2]

XtbCalculator & occ::xtb::XtbCalculator::operator= ( XtbCalculator && )

default

◆ positions()

const Mat3N & occ::xtb::XtbCalculator::positions ( ) const

inline

Cartesian positions in Bohr (3 × N).

◆ print_summary()

void occ::xtb::XtbCalculator::print_summary ( ) const

Print a summary (energy decomposition, charges, HOMO/LUMO/gap) at INFO log level.

Useful as the post-SCF print step in occ scf.

◆ repulsion_energy()

double occ::xtb::XtbCalculator::repulsion_energy ( ) const

inline

Closed-form repulsion energy (Hartree).

◆ scc_energy()

double occ::xtb::XtbCalculator::scc_energy ( ) const

inline

Electronic + isotropic-Coulomb + (multipole AES if on) energy (Hartree).

◆ set_charge()

void occ::xtb::XtbCalculator::set_charge ( double c )

Net molecular / unit-cell charge in electrons.

◆ set_include_dispersion()

void occ::xtb::XtbCalculator::set_include_dispersion ( bool on )

Toggle native D4 dispersion.

◆ set_include_multipoles()

void occ::xtb::XtbCalculator::set_include_multipoles ( bool on )

Toggle CAMM multipole AES + on-site polarization (true for full GFN2).

For the periodic k-point path this also enables the per-k Bloch-summed multipole AO matrices.

◆ set_kpoints()

void occ::xtb::XtbCalculator::set_kpoints	(	int	n1,
		int	n2,
		int	n3
	)

Monkhorst-Pack k-grid for the periodic SCC.

(1, 1, 1) (default) uses the real-arithmetic Γ-only path; larger grids use the complex-eigensolve k-point path. No-op for molecular calculators.

◆ set_max_iterations()

void occ::xtb::XtbCalculator::set_max_iterations ( int iterations )

Maximum SCC iterations.

◆ set_mixer_damping()

void occ::xtb::XtbCalculator::set_mixer_damping ( double damping_factor )

SCC mixer damping factor (weight on the previous iteration; ∈ [0, 1)).

◆ set_num_unpaired_electrons()

void occ::xtb::XtbCalculator::set_num_unpaired_electrons ( int n )

Number of unpaired electrons (open-shell).

Only n == 0 is currently supported; non-zero values throw std::runtime_error. The setter is kept for API parity with TbliteCalculator.

◆ set_solvation_model()

void occ::xtb::XtbCalculator::set_solvation_model ( std::shared_ptr< XtbSolvationModel > model )

Attach an XtbSolvationModel (or clear it by passing nullptr).

The model is consumed by the molecular SCC each iteration — gas-phase for nullptr or a NullSolvationModel. No-op on the periodic path until Phase 7B's periodic CPCM-X lands. The calculator keeps a shared reference; the same model can be re-attached after update_structure(...) and will rebuild its cavity on the next SCC.

◆ set_solvent()

bool occ::xtb::XtbCalculator::set_solvent ( const std::string & name )

Enable an implicit-solvent model by name.

Not yet implemented in the native backend — currently always returns false. Kept for API parity with TbliteCalculator::set_solvent. Real built-in models will land in Phase 7B (CPCM-X) / 7C (SMD); until then, use set_solvation_model directly to inject a custom XtbSolvationModel.

◆ set_temperature()

void occ::xtb::XtbCalculator::set_temperature ( double temp )

Electronic temperature (K) for Fermi smearing.

◆ single_point()

const XtbResult & occ::xtb::XtbCalculator::single_point ( )

Run an SCC at the current geometry / configuration.

Returns the cached result; subsequent calls re-run.

◆ single_point_energy()

double occ::xtb::XtbCalculator::single_point_energy ( )

Convenience wrapper around single_point() returning just the total energy (Hartree).

◆ solvation_model()

const std::shared_ptr< XtbSolvationModel > & occ::xtb::XtbCalculator::solvation_model ( ) const

◆ temperature()

double occ::xtb::XtbCalculator::temperature ( ) const

◆ to_crystal()

occ::crystal::Crystal occ::xtb::XtbCalculator::to_crystal ( ) const

Snapshot the current periodic system as an occ::crystal::Crystal (periodic only — throws otherwise).

◆ to_molecule()

occ::core::Molecule occ::xtb::XtbCalculator::to_molecule ( ) const

Snapshot the current atoms / positions as an occ::core::Molecule (positions returned in Å).

◆ to_wavefunction()

occ::qm::Wavefunction occ::xtb::XtbCalculator::to_wavefunction ( ) const

Convert the converged SCC state into a qm::Wavefunction so the rest of occ (.owf.json save/load, occ cube, occ isosurface, Mulliken / Hirshfeld analysis, ESP, ...) can consume the GFN2 result.

Requires single_point() to have run.

For the periodic ctor this is a Γ-only central-cell snapshot — the orbital coefficients, density matrix, and orbital energies are the Γ-point values from XtbResult, and downstream consumers treat it as a molecular wavefunction (no Bloch sum at evaluation time). Useful for visualisation; not a substitute for a full periodic wavefunction.

◆ total_energy()

double occ::xtb::XtbCalculator::total_energy ( ) const

inline

Total energy from the most recent SCC (Hartree).

◆ update_structure() [1/2]

void occ::xtb::XtbCalculator::update_structure ( const Mat3N & positions )

Update Cartesian positions (Bohr).

Recomputes geometry-dependent caches (S, H0, γ, multipole AO blocks for periodic).

◆ update_structure() [2/2]

void occ::xtb::XtbCalculator::update_structure	(	const Mat3N &	positions,
		const Mat3 &	lattice_bohr
	)

Update positions and lattice vectors simultaneously (periodic only).

The documentation for this class was generated from the following file:

/home/runner/work/occ/occ/include/occ/xtb/xtb_calculator.h

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ Method

Constructor & Destructor Documentation

◆ XtbCalculator() [1/5]

◆ XtbCalculator() [2/5]

◆ XtbCalculator() [3/5]

◆ XtbCalculator() [4/5]

◆ XtbCalculator() [5/5]

Member Function Documentation

◆ atomic_numbers()

◆ backend_name()

◆ bond_orders()

◆ charge()

◆ charges()

◆ compute_energy_and_gradient()

◆ compute_gradient_analytical()

◆ compute_gradient_numerical()

◆ compute_hessian_numerical()

◆ compute_vibrational_modes()

◆ dispersion_energy()

◆ gradient()

◆ gradient_numerical()

◆ include_dispersion()

◆ include_multipoles()

◆ is_periodic()

◆ kpoints()

◆ last_result()

◆ lattice()

◆ max_iterations()

◆ method()

◆ method_name()

◆ mixer_damping()

◆ num_atoms()

◆ num_unpaired_electrons()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ positions()

◆ print_summary()

◆ repulsion_energy()

◆ scc_energy()

◆ set_charge()

◆ set_include_dispersion()

◆ set_include_multipoles()

◆ set_kpoints()

◆ set_max_iterations()

◆ set_mixer_damping()

◆ set_num_unpaired_electrons()

◆ set_solvation_model()

◆ set_solvent()

◆ set_temperature()

◆ single_point()

◆ single_point_energy()

◆ solvation_model()

◆ temperature()

◆ to_crystal()

◆ to_molecule()

◆ to_wavefunction()

◆ total_energy()

◆ update_structure() [1/2]

◆ update_structure() [2/2]