spectral_localizer Module Reference

Dense reference spectral localizers in a nonorthogonal finite basis. More...

Data Types
interface	localizer_inertia

Functions/Subroutines
subroutine, public	localizer_3d_evaluate (h, s, r, point, energy, kappa, matrix_tol, metric_tol, gap_tol, invariant, gap, metric_ratio, status)
	Finite three-dimensional class AII localizer, using all three Cartesian moments.
subroutine, public	localizer_3d_matrix_evaluate (block, s, matrix_tol, metric_tol, gap_tol, invariant, gap, metric_ratio, status)
	Metric gap and real determinant sign of a three-dimensional AII chiral block.
subroutine, public	localizer_periodic_evaluate (h, s, cosine, sine, origin, energy, eta, aii, matrix_tol, metric_tol, gap_tol, invariant, gap, metric_ratio, status)
	Two-dimensional periodic localizer from covariant trigonometric position operators.
subroutine, public	localizer_evaluate (h, s, r, point, energy, kappa, aii, matrix_tol, metric_tol, gap_tol, invariant, gap, metric_ratio, status)
	Evaluate the 2D class A or AII localizer without projecting onto occupied states.
subroutine, public	localizer_matrix_evaluate (localizer, s, aii, matrix_tol, metric_tol, gap_tol, invariant, gap, metric_ratio, status)
	Dense reference evaluation of an assembled localizer with metric diag(S,S).
subroutine, public	localizer_aii_skew (localizer, skew, tolerance, residual, status)
	Convert the class AII localizer to a real skew matrix using Q=(I-i C)/sqrt(2).
subroutine, public	localizer_pfaffian_sign (matrix, pf_sign, status)
	Dense pivoted skew elimination, accumulating only the sign of the Pfaffian.

Detailed Description

Dense reference spectral localizers in a nonorthogonal finite basis.

Author

Thomas D. Kuehne, tkueh.nosp@m.ne@c.nosp@m.p2k.o.nosp@m.rg

Function/Subroutine Documentation

localizer_3d_evaluate()

subroutine, public spectral_localizer::localizer_3d_evaluate	(	complex(dp), dimension(:, :), intent(in)	h,
		complex(dp), dimension(:, :), intent(in)	s,
		complex(dp), dimension(:, :, :), intent(in)	r,
		real(dp), dimension(3), intent(in)	point,
		real(dp), intent(in)	energy,
		real(dp), intent(in)	kappa,
		real(dp), intent(in)	matrix_tol,
		real(dp), intent(in)	metric_tol,
		real(dp), intent(in)	gap_tol,
		integer, intent(out)	invariant,
		real(dp), intent(out)	gap,
		real(dp), intent(out)	metric_ratio,
		integer, intent(out)	status )

Finite three-dimensional class AII localizer, using all three Cartesian moments.

Parameters

h	Covariant physical-spin Hamiltonian, all up AOs followed by all down AOs
s	Positive physical-spin AO metric
r	Three covariant Hermitian position operators
point	Cartesian query coordinates
energy	Absolute energy query
kappa	Positive energy/length scale
matrix_tol	Relative matrix-structure tolerance
metric_tol	Minimum overlap eigenvalue ratio
gap_tol	Absolute unresolved-gap threshold
invariant	Strong local Z2 index, valid only for status zero
gap	Smallest metric-normalized singular value of the chiral block
metric_ratio	Smallest/largest physical metric eigenvalue
status	Same convention as localizer_evaluate

Definition at line 47 of file spectral_localizer.F.

Here is the call graph for this function:

Here is the caller graph for this function:

localizer_3d_matrix_evaluate()

subroutine, public spectral_localizer::localizer_3d_matrix_evaluate	(	complex(dp), dimension(:, :), intent(in)	block,
		complex(dp), dimension(:, :), intent(in)	s,
		real(dp), intent(in)	matrix_tol,
		real(dp), intent(in)	metric_tol,
		real(dp), intent(in)	gap_tol,
		integer, intent(out)	invariant,
		real(dp), intent(out)	gap,
		real(dp), intent(out)	metric_ratio,
		integer, intent(out)	status )

Metric gap and real determinant sign of a three-dimensional AII chiral block.

Parameters

block	Covariant A=I_aux(H-E S)-i kappa sigma.(X-x S); auxiliary index outermost
s	Positive physical-spin AO metric
matrix_tol	Relative structure tolerance
metric_tol	Minimum overlap eigenvalue ratio
gap_tol	Absolute unresolved-gap threshold
invariant	Zero for positive determinant, one for negative; valid only on success
gap	Minimum absolute generalized eigenvalue of [0,A;A^dagger,0]
metric_ratio	Smallest/largest physical metric eigenvalue
status	Same convention as localizer_evaluate

Note

A positive atomic Hamiltonian gives positive determinant in every nonsingular AO basis. Unlike the 2D Pfaffian, no basis-orientation correction is required for this determinant.

Definition at line 106 of file spectral_localizer.F.

Here is the call graph for this function:

Here is the caller graph for this function:

localizer_periodic_evaluate()

subroutine, public spectral_localizer::localizer_periodic_evaluate	(	complex(dp), dimension(:, :), intent(in)	h,
		complex(dp), dimension(:, :), intent(in)	s,
		complex(dp), dimension(:, :, :), intent(in)	cosine,
		complex(dp), dimension(:, :, :), intent(in)	sine,
		real(dp), dimension(2), intent(in)	origin,
		real(dp), intent(in)	energy,
		real(dp), intent(in)	eta,
		logical, intent(in)	aii,
		real(dp), intent(in)	matrix_tol,
		real(dp), intent(in)	metric_tol,
		real(dp), intent(in)	gap_tol,
		integer, intent(out)	invariant,
		real(dp), intent(out)	gap,
		real(dp), intent(out)	metric_ratio,
		integer, intent(out)	status )

Two-dimensional periodic localizer from covariant trigonometric position operators.

Parameters

h	Periodic Hamiltonian, including all boundary-crossing matrix elements
s	Positive definite overlap
cosine	Covariant cos(G_j.r) matrices, not cos of projected AO positions
sine	Covariant sin(G_j.r) matrices
origin	Two dimensionless phase offsets G_j.r0
energy	Absolute reference energy
eta	Positive energy scale multiplying the torus coordinates
aii	Use physical spinful time reversal
matrix_tol	Relative structure tolerance
metric_tol	Minimum overlap eigenvalue ratio
gap_tol	Absolute unresolved-gap threshold in energy units
invariant	Index in the same orientation convention as localizer_evaluate
gap	Minimum absolute generalized eigenvalue, in energy units
metric_ratio	Smallest/largest overlap eigenvalue ratio
status	Same status convention as localizer_evaluate

Note

Adapted from Doll, Loring, Schulz-Baldes (2025), Eq. (1): minus eta times their localizer, conjugated by diag(I,-I), to retain our (H,X,Y) orientation. A resolved finite-matrix signature is not a certificate of bulk convergence.

Definition at line 290 of file spectral_localizer.F.

Here is the call graph for this function:

Here is the caller graph for this function:

localizer_evaluate()

subroutine, public spectral_localizer::localizer_evaluate	(	complex(kind=dp), dimension(:, :), intent(in)	h,
		complex(kind=dp), dimension(:, :), intent(in)	s,
		complex(kind=dp), dimension(:, :, :), intent(in)	r,
		real(kind=dp), dimension(2), intent(in)	point,
		real(kind=dp), intent(in)	energy,
		real(kind=dp), intent(in)	kappa,
		logical, intent(in)	aii,
		real(kind=dp), intent(in)	matrix_tol,
		real(kind=dp), intent(in)	metric_tol,
		real(kind=dp), intent(in)	gap_tol,
		integer, intent(out)	invariant,
		real(kind=dp), intent(out)	gap,
		real(kind=dp), intent(out)	metric_ratio,
		integer, intent(out)	status )

Evaluate the 2D class A or AII localizer without projecting onto occupied states.

Parameters

h	Covariant Hamiltonian matrix
s	Positive definite AO overlap
r	Covariant Cartesian position matrices in the two oriented directions
point	Position in the same coordinates and length units as r
energy	Absolute reference energy in the units of h
kappa	Positive energy/length scale
aii	Use spinful time reversal, with all up AOs followed by all down AOs
matrix_tol	Relative Hermiticity and time-reversal tolerance
metric_tol	Minimum allowed smallest/largest overlap eigenvalue ratio
gap_tol	Absolute unresolved-gap threshold in energy units
invariant	Half-signature (A), or 0 trivial / 1 nontrivial (AII); valid only if status=0
gap	Minimum absolute generalized localizer eigenvalue
metric_ratio	Smallest/largest overlap eigenvalue ratio
status	0 resolved; 1 unresolved gap; -1 invalid data; -2 bad metric; -3 broken TR; -4 factorization failure; positive values above 1 indicate LAPACK failure

Note

This is a finite-basis diagnostic, not a certificate of basis or volume convergence.

Definition at line 362 of file spectral_localizer.F.

Here is the call graph for this function:

Here is the caller graph for this function:

localizer_matrix_evaluate()

subroutine, public spectral_localizer::localizer_matrix_evaluate	(	complex(kind=dp), dimension(:, :), intent(in)	localizer,
		complex(kind=dp), dimension(:, :), intent(in)	s,
		logical, intent(in)	aii,
		real(kind=dp), intent(in)	matrix_tol,
		real(kind=dp), intent(in)	metric_tol,
		real(kind=dp), intent(in)	gap_tol,
		integer, intent(out)	invariant,
		real(kind=dp), intent(out)	gap,
		real(kind=dp), intent(out)	metric_ratio,
		integer, intent(out)	status )

Dense reference evaluation of an assembled localizer with metric diag(S,S).

Parameters

localizer	Covariant Hermitian localizer
s	Positive definite physical AO/spinor overlap
aii	Whether to use the physical spinful time-reversal structure
matrix_tol	Relative structure tolerance
metric_tol	Minimum overlap eigenvalue ratio
gap_tol	Absolute unresolved-gap tolerance
invariant	Resolved class A or AII index
gap	Minimum absolute generalized eigenvalue
metric_ratio	Smallest/largest overlap eigenvalue ratio
status	Same status convention as localizer_evaluate

Definition at line 421 of file spectral_localizer.F.

Here is the call graph for this function:

Here is the caller graph for this function:

localizer_aii_skew()

subroutine, public spectral_localizer::localizer_aii_skew	(	complex(kind=dp), dimension(:, :), intent(in)	localizer,
		real(kind=dp), dimension(:, :), intent(out)	skew,
		real(kind=dp), intent(in)	tolerance,
		real(kind=dp), intent(out)	residual,
		integer, intent(out)	status )

Convert the class AII localizer to a real skew matrix using Q=(I-i C)/sqrt(2).

Parameters

localizer	Hermitian localizer; auxiliary index outside physical up/down index
skew	Real part of i Q^dagger L Q
tolerance	Relative imaginary/skew residual tolerance
residual	Entrywise bound for the discarded real and symmetric components
status	Zero on success; negative if the AII structure is violated

Definition at line 731 of file spectral_localizer.F.

Here is the call graph for this function:

Here is the caller graph for this function:

localizer_pfaffian_sign()

subroutine, public spectral_localizer::localizer_pfaffian_sign	(	real(kind=dp), dimension(:, :), intent(in)	matrix,
		integer, intent(out)	pf_sign,
		integer, intent(out)	status )

Dense pivoted skew elimination, accumulating only the sign of the Pfaffian.

Parameters

matrix	Real skew-symmetric matrix; input is not modified
pf_sign	Sign, or zero if singular/unresolved
status	Zero on success, -1 invalid data, -2 numerically singular factorization

Note

Each simultaneous row/column interchange changes the Pfaffian sign, not its square.

Definition at line 798 of file spectral_localizer.F.

Here is the caller graph for this function: