optbas_frontier_orbitals_utils Module Reference

Utilities for frontier-orbital basis optimization. More...

Data Types
type	frontier_orbitals_result_type
type	frontier_orbitals_reference_type

Functions/Subroutines
subroutine, public	print_frontier_orbital_basis_sets (unit_nr, element_symbols, reference_basis_names, initial_basis_names)
	Print reference and initial basis-set names for every fitted atom kind.
subroutine, public	frontier_orbitals_reference_init (qs_env, reference)
	Diagonalize and store the frozen reference Hamiltonian.
subroutine, public	frontier_orbitals_reference_release (reference)
	Release the stored reference eigenvalues and eigenvectors.
subroutine, public	evaluate_frontier_orbitals_objective (reference, matrix_s_candidate, matrix_s_candidate_reference, virtual_cutoff, virtual_smoothing, gap_scale, objective_result)
	Construct and diagonalize the candidate Hamiltonian and evaluate the loss function.
pure subroutine, public	compute_frontier_orbital_loss_function (orbital_overlap, eigenvalues_reference, eigenvalues_candidate, number_occupied_orbitals, virtual_cutoff, virtual_smoothing, gap_scale, objective_result)
	Compute the frontier-orbital loss function.
pure real(kind=dp) function, public	smooth_frontier_orbital_weight (energy_from_lumo, cutoff, smoothing)
	Return the smooth energy-window weight for a virtual orbital.

Detailed Description

Utilities for frontier-orbital basis optimization.

History

28.08.2026 created [Jan Wilhelm]

Author

Jan Wilhelm

Function/Subroutine Documentation

print_frontier_orbital_basis_sets()

subroutine, public optbas_frontier_orbitals_utils::print_frontier_orbital_basis_sets	(	integer, intent(in)	unit_nr,
		character(len=*), dimension(:), intent(in)	element_symbols,
		character(len=*), dimension(:), intent(in)	reference_basis_names,
		character(len=*), dimension(:), intent(in)	initial_basis_names )

Print reference and initial basis-set names for every fitted atom kind.

Parameters

unit_nr	output unit
element_symbols	fitted atom-kind symbols
reference_basis_names	reference basis-set names
initial_basis_names	initial small-basis names

Definition at line 93 of file optbas_frontier_orbitals_utils.F.

Here is the caller graph for this function:

frontier_orbitals_reference_init()

subroutine, public optbas_frontier_orbitals_utils::frontier_orbitals_reference_init	(	type(qs_environment_type), pointer	qs_env,
		type(frontier_orbitals_reference_type), intent(out)	reference )

Diagonalize and store the frozen reference Hamiltonian.

Parameters

qs_env	initialized reference Quickstep environment
reference	reference eigenvalues and eigenvectors

Definition at line 116 of file optbas_frontier_orbitals_utils.F.

Here is the call graph for this function:

Here is the caller graph for this function:

frontier_orbitals_reference_release()

subroutine, public optbas_frontier_orbitals_utils::frontier_orbitals_reference_release

(

type(frontier_orbitals_reference_type), intent(inout)

reference

)

Release the stored reference eigenvalues and eigenvectors.

Parameters

reference

reference eigenvalues and eigenvectors

Definition at line 200 of file optbas_frontier_orbitals_utils.F.

Here is the call graph for this function:

Here is the caller graph for this function:

evaluate_frontier_orbitals_objective()

subroutine, public optbas_frontier_orbitals_utils::evaluate_frontier_orbitals_objective	(	type(frontier_orbitals_reference_type), intent(in)	reference,
		type(dbcsr_type), pointer	matrix_s_candidate,
		type(dbcsr_type), pointer	matrix_s_candidate_reference,
		real(kind=dp), intent(in)	virtual_cutoff,
		real(kind=dp), intent(in)	virtual_smoothing,
		real(kind=dp), intent(in)	gap_scale,
		type(frontier_orbitals_result_type), intent(out)	objective_result )

Construct and diagonalize the candidate Hamiltonian and evaluate the loss function.

Parameters

reference	reference eigenvalues and eigenvectors C_R
matrix_s_candidate	candidate AO overlap matrix S_C
matrix_s_candidate_reference	candidate/reference AO overlap matrix S_CR
virtual_cutoff	virtual-orbital energy cutoff
virtual_smoothing	virtual-orbital energy smoothing width
gap_scale	normalization energy for the HOMO-LUMO gap loss
objective_result	loss-function terms and result information

Note

The reference Hamiltonian is transformed to the candidate AO basis using B = C_R^T S_RC H_C = B^T diag(ε_R) B The candidate orbitals are obtained from H_C C_C = S_C C_C diag(ε_C) C_C^T S_C C_C = I. The reference/candidate orbital overlap matrix is M = C_R^T S_RC C_C = B C_C.

Definition at line 274 of file optbas_frontier_orbitals_utils.F.

Here is the call graph for this function:

Here is the caller graph for this function:

compute_frontier_orbital_loss_function()

pure subroutine, public optbas_frontier_orbitals_utils::compute_frontier_orbital_loss_function	(	real(kind=dp), dimension(:, :), intent(in)	orbital_overlap,
		real(kind=dp), dimension(:), intent(in)	eigenvalues_reference,
		real(kind=dp), dimension(:), intent(in)	eigenvalues_candidate,
		integer, intent(in)	number_occupied_orbitals,
		real(kind=dp), intent(in)	virtual_cutoff,
		real(kind=dp), intent(in)	virtual_smoothing,
		real(kind=dp), intent(in)	gap_scale,
		type(frontier_orbitals_result_type), intent(out)	objective_result )

Compute the frontier-orbital loss function.

Parameters

orbital_overlap	reference/candidate orbital overlaps
eigenvalues_reference	reference eigenvalues
eigenvalues_candidate	candidate eigenvalues
number_occupied_orbitals	number of occupied spatial orbitals
virtual_cutoff	virtual-orbital energy cutoff E_cut
virtual_smoothing	virtual-orbital energy smoothing width ΔE
gap_scale	normalization energy E_scale for the gap loss
objective_result	loss-function terms and result information

Note

Let i,j denote occupied orbitals, a,b virtual orbitals, and N_occ the number of occupied orbitals. R and C label reference and candidate quantities, with M_ij = <ψ_i^R | ψ_j^C> and M_ab = <ψ_a^R | ψ_b^C>. The occupied-subspace loss is L_occ = 1 - sum_(i,j in occupied) |M_ij|^2 / N_occ.

For virtual orbitals, define the smooth energy-window weights and their norms as w_a^X = 1 / {1 + exp[(ε_a^X - ε_LUMO^X - E_cut) / ΔE]}, for X = R or C, N_X = sum_(a in virtual) (w_a^X)^2. The virtual-subspace loss is the normalized squared Frobenius distance between the energy-weighted virtual-space operators. Its expanded form is L_vir = [N_R + N_C - 2 sum_(a,b in virtual) w_a^R w_b^C |M_ab|^2] / (2 N_R).

The empty-subspace loss is L_empty = 1 - sum_(a,b in virtual) (w_a^R)^2 |M_ab|^2 / N_R.

With E_gap^X = ε_LUMO^X - ε_HOMO^X, the gap loss is L_gap = [(E_gap^C - E_gap^R) / E_scale]^2.

Definition at line 425 of file optbas_frontier_orbitals_utils.F.

Here is the call graph for this function:

Here is the caller graph for this function:

smooth_frontier_orbital_weight()

pure real(kind=dp) function, public optbas_frontier_orbitals_utils::smooth_frontier_orbital_weight	(	real(kind=dp), intent(in)	energy_from_lumo,
		real(kind=dp), intent(in)	cutoff,
		real(kind=dp), intent(in)	smoothing )

Return the smooth energy-window weight for a virtual orbital.

Parameters

energy_from_lumo	orbital energy relative to the LUMO
cutoff	outer energy of the virtual-orbital window
smoothing	smoothing width at the outer boundary

Returns

energy-window weight in the interval [0, 1]

Definition at line 527 of file optbas_frontier_orbitals_utils.F.

Here is the caller graph for this function: