VASP Interface

VaspInterface

Interface module for reading VASP/CC4S tensor files into ElemCo.

Reads YAML descriptor files (version 100) and their companion .elements files (text or IEEE binary) as produced by the VASP → CC4S pipeline.

Key tensors:

• EigenEnergies: orbital eigenvalues
• CoulombVertex: 3-index density-fitted integrals Γ[F,p,q]
• State: dimension properties (occupied/virtual partitioning)

load_vasp(dirpath::String) → VaspData

Load all VASP/CC4S tensors from a directory containing YAML descriptor files and their companion .elements files.

Required files:

• EigenEnergies.yaml + .elements
• CoulombVertex.yaml + .elements

For occupied/virtual partitioning, State.yaml is read if present. Otherwise, the user must set occupation explicitly.

setup_vasp!(EC::ECInfo, data::VaspData; ms2::Int=0)

Populate EC from loaded VASP data for use with ccdriver.

Sets up:

• EC.fd header and core Hamiltonian h₀ reconstructed from eigenvalues and Coulomb vertex
• 3-index Coulomb vertex saved as mmL to EC scratch directory
• Orbital spaces via setup_space_fd!

The core Hamiltonian is computed as: $h_{pq} = F_{pq} - \sum_i [2 J_i(p,q) - K_i(p,q)]$ where $F_{pq} = \varepsilon_p \delta_{pq}$ (canonical MOs) and $J$, $K$ are the Coulomb and exchange contributions from occupied orbitals.

decompose_vasp_vertex(Gamma::Array{T,3}, tol::Float64; sigma::Float64=0.01) where T → (B, naux_new)

ALPACA decomposition of the VASP Coulomb vertex using a matrix-free interface.

Given $\Gamma^L_{pq}$ (shape (naux, norb, norb)), the 4-index integrals in chemist notation are: $(pq|rs) = \sum_L \overline{\Gamma^L_{qp}} \Gamma^L_{rs}$

This function produces $B^J_{pq}$ (shape (norb, norb, naux_new)) such that: $(pq|rs) \approx \sum_J B^J_{pq} B^J_{rs}$

Uses the ALPACA (Amended Low-rank Principal-element Adaptive Cross Approximation) algorithm with a matrix-free interface that computes columns of the $n^2 \times n^2$ Coulomb matrix on demand via BLAS-2 operations, avoiding materialization of the full matrix. Principal elements default to the diagonal.

Arguments

• Gamma: VASP Coulomb vertex, shape (naux, norb, norb)
• tol: decomposition threshold
• sigma: span factor for ALPACA batch screening (default: 0.01)

Returns

• B: decomposed 3-index integrals, shape (norb, norb, naux_new)
• naux_new: number of decomposition vectors

determine_occupation(dirpath, norb, eigen_energies, fermi_energy, ee_meta) → (nocc, nvirt)

Determine occupied/virtual split. Uses metadata energies field if available to count states below the Fermi energy. Falls back to counting eigenvalues < fermi_energy.

read_binary_elements(path, n, effective_type, file_type, half_grid) → Vector

Read elements from an IEEE binary file. For half_grid=1: reads as Complex64 then reinterprets as Float64.

read_text_elements(path, n, scalar_type) → Vector

Read n elements from a text file, one number per line.

read_vasp_elements(elements_path::String, meta::VaspTensorMeta) → Array

Read the .elements companion file according to the tensor metadata. Returns a Julia array with proper shape and type, in column-major order.

For halfGrid=1: Complex64 data is reinterpreted as Real64 with doubled AuxiliaryField dimension (following CC4S convention).

read_vasp_yaml(filepath::String) → VaspTensorMeta

Parse a VASP tensor YAML file and return structured metadata.

VaspCoulombMatrix{T} <: AbstractALPACAMatrix

Matrix-free representation of the VASP Coulomb matrix for ALPACA decomposition.

The matrix has compound indices $I = (q-1) n + p$ (pair $(p,q)$) and $J = (s-1) n + r$ (pair $(r,s)$), with elements: $V_{IJ} = \sum_L \overline{\Gamma^L_{qp}} \, \Gamma^L_{rs} = (pq|rs)$

The matrix is complex symmetric: $V^T = V$.

VaspData{T}

Container for all tensors loaded from a VASP/CC4S directory. T is the element type of the Coulomb vertex (Float64 or ComplexF64).

VaspTensorMeta

Parsed metadata from a VASP tensor YAML file.