nonlocal_overlap_matrix_oct_m Module Reference

Exact inverse of the ultrasoft/PAW generalized overlap operator for overlapping spheres. More...

Detailed Description

Exact inverse of the ultrasoft/PAW generalized overlap operator for overlapping spheres.

The overlap operator is S = 1 + sum_I |beta^I> q^I <beta^I|. The per-atom Woodbury inverse (T^I = q^I (1 + M^I q^I)^{-1} with the single-atom Gram M^I) is exact only when projector spheres of different atoms / periodic images never share grid points. When they do overlap (close atoms, small cells), the exact inverse needs the full projector Gram including the inter-atomic and periodic-image cross blocks. Because that Gram couples only projector matrices whose spheres share points, (1 + M Q) is block diagonal across the connected components (clusters) of the overlap graph, and so is its inverse T. This module assembles and applies that exact cross-block inverse per cluster; singletons reduce to the per-atom inverse, which the caller keeps as a bit-identical fast path when no sphere overlap is present.

Data Types
type	overlap_cluster_t
	One connected component of the projector-overlap graph. More...
type	overlap_matrix_t
	The exact inverse-overlap operator, grouped into overlap clusters. More...

Functions/Subroutines
subroutine	overlap_matrix_detect (this, nmat, projector_matrices, projector_to_atom, epot, space, self_overlap)
	Detect distinct-atom projector overlap and group the projector matrices into the connected components (clusters) of the overlap graph. Sets use_global_coupling and fills clusters when at least one cluster spans more than one matrix or a sphere overlaps its own periodic images; otherwise the per-atom (block-diagonal) inverse is exact and nothing is grouped. More...
recursive integer function	uf_find (parent, ii)
	Union-find "find" with path compression (roots of the projector-overlap graph). More...
subroutine	uf_union (parent, ii, jj)
	Union-find "union" of two projector matrices into one cluster. More...
subroutine	overlap_matrix_build (this, projector_matrices, projector_phases, mesh, kstart, kend)
	Assemble the exact inverse-overlap coupling -T for each overlap cluster. More...
subroutine	overlap_matrix_end (this)
	Release the exact inverse-overlap cluster data. More...
subroutine	doverlap_matrix_apply (this, projector_matrices, proj, nst_linear, ik)
	Apply the exact inverse-overlap coupling p` = -T p (mix = -T stored per cluster), dense within each overlap cluster, to the already domain-reduced projection vector, in place. Replaces the per-matrix block-diagonal coupling; the caller`s subsequent scatter reads the coupled slices. proj is the projection vector (nst_linear, full_projection_size); its per-matrix slice starts at thisproj_offset(im). More...
subroutine	zoverlap_matrix_apply (this, projector_matrices, proj, nst_linear, ik)
	Apply the exact inverse-overlap coupling p` = -T p (mix = -T stored per cluster), dense within each overlap cluster, to the already domain-reduced projection vector, in place. Replaces the per-matrix block-diagonal coupling; the caller`s subsequent scatter reads the coupled slices. proj is the projection vector (nst_linear, full_projection_size); its per-matrix slice starts at thisproj_offset(im). More...

Variables
logical	uspp_gpu_approx_warned = .false.
	Emit the "exact inverse overlap is CPU-only" warning at most once per run. More...

Function/Subroutine Documentation

overlap_matrix_detect()

subroutine nonlocal_overlap_matrix_oct_m::overlap_matrix_detect ( class(overlap_matrix_t), intent(inout)  this, integer, intent(in)  nmat, type(projector_matrix_t), dimension(:), intent(in)  projector_matrices, integer, dimension(:), intent(in)  projector_to_atom, type(epot_t), intent(in)  epot, class(space_t), intent(in)  space, logical, intent(in)  self_overlap  )

private

Detect distinct-atom projector overlap and group the projector matrices into the connected components (clusters) of the overlap graph. Sets use_global_coupling and fills clusters when at least one cluster spans more than one matrix or a sphere overlaps its own periodic images; otherwise the per-atom (block-diagonal) inverse is exact and nothing is grouped.

Parameters

[in]

self_overlap

some sphere overlaps its own images

Definition at line 190 of file nonlocal_overlap_matrix.F90.

uf_find()

recursive integer function nonlocal_overlap_matrix_oct_m::uf_find ( integer, dimension(:), intent(inout)  parent, integer, intent(in)  ii  )

private

Union-find "find" with path compression (roots of the projector-overlap graph).

Definition at line 306 of file nonlocal_overlap_matrix.F90.

uf_union()

subroutine nonlocal_overlap_matrix_oct_m::uf_union ( integer, dimension(:), intent(inout)  parent, integer, intent(in)  ii, integer, intent(in)  jj  )

private

Union-find "union" of two projector matrices into one cluster.

Definition at line 316 of file nonlocal_overlap_matrix.F90.

overlap_matrix_build()

subroutine nonlocal_overlap_matrix_oct_m::overlap_matrix_build ( class(overlap_matrix_t), intent(inout), target  this, type(projector_matrix_t), dimension(:), intent(in)  projector_matrices, complex(real64), dimension(:, :, :, :), intent(in), allocatable  projector_phases, class(mesh_t), intent(in)  mesh, integer, intent(in)  kstart, integer, intent(in)  kend  )

private

Assemble the exact inverse-overlap coupling -T for each overlap cluster.

For each connected cluster of overlapping projector matrices this builds the full projector Gram M (including the inter-atomic and periodic-image cross blocks, carrying the k-dependent Bloch projector phases), forms A = 1 + M Q with the block-diagonal augmentation charges Q, and stores mix = -T = -Q A^{-1} (SVD pseudo-inverse) exactly as the per-atom build does, but at the cluster dimension. T is k-dependent whenever the phases are, so it must be rebuilt whenever the phases are (re)built: every SCF geometry update, and every TD step with a time-dependent vector potential. Without phases (finite systems / Gamma without a field) T is k-independent and the (single) local k slot is filled once.

Only projector_phases enter M, not the grid phase P = diag(exp(i k.x)): P is applied to the wavefunction on the grid and undone by the caller, and being unitary and diagonal it cancels in S^{-1} = P^{-1} S_grid^{-1} P. M is therefore built from the same bra (beta* . phase) / ket (beta . conjg(phase)) convention used by the apply.

Definition at line 343 of file nonlocal_overlap_matrix.F90.

overlap_matrix_end()

subroutine nonlocal_overlap_matrix_oct_m::overlap_matrix_end ( class(overlap_matrix_t), intent(inout)  this )

private

Release the exact inverse-overlap cluster data.

Definition at line 546 of file nonlocal_overlap_matrix.F90.

doverlap_matrix_apply()

subroutine nonlocal_overlap_matrix_oct_m::doverlap_matrix_apply ( class(overlap_matrix_t), intent(in), target  this, type(projector_matrix_t), dimension(:), intent(in)  projector_matrices, real(real64), dimension(:, :), intent(inout)  proj, integer, intent(in)  nst_linear, integer, intent(in)  ik  )

private

Apply the exact inverse-overlap coupling p` = -T p (mix = -T stored per cluster), dense within each overlap cluster, to the already domain-reduced projection vector, in place. Replaces the per-matrix block-diagonal coupling; the caller`s subsequent scatter reads the coupled slices. proj is the projection vector (nst_linear, full_projection_size); its per-matrix slice starts at thisproj_offset(im).

Definition at line 643 of file nonlocal_overlap_matrix.F90.

zoverlap_matrix_apply()

subroutine nonlocal_overlap_matrix_oct_m::zoverlap_matrix_apply ( class(overlap_matrix_t), intent(in), target  this, type(projector_matrix_t), dimension(:), intent(in)  projector_matrices, complex(real64), dimension(:, :), intent(inout)  proj, integer, intent(in)  nst_linear, integer, intent(in)  ik  )

private

Apply the exact inverse-overlap coupling p` = -T p (mix = -T stored per cluster), dense within each overlap cluster, to the already domain-reduced projection vector, in place. Replaces the per-matrix block-diagonal coupling; the caller`s subsequent scatter reads the coupled slices. proj is the projection vector (nst_linear, full_projection_size); its per-matrix slice starts at thisproj_offset(im).

Definition at line 770 of file nonlocal_overlap_matrix.F90.

Variable Documentation

uspp_gpu_approx_warned

logical nonlocal_overlap_matrix_oct_m::uspp_gpu_approx_warned = .false.

private

Emit the "exact inverse overlap is CPU-only" warning at most once per run.

Definition at line 181 of file nonlocal_overlap_matrix.F90.