Wavefunctions

Wavefunctions

Module for handling wavefunctions: dumping and fetching orbitals/amplitudes etc to/from TREXIO files.

close_dump(trexio::TrexioFile)

Close the opened TREXIO file.

copy_wavefunction(EC::ECInfo, tofile::AbstractString=""; start=false, state=0, reverse=false)

Copy the wavefunction dump file to tofile. If tofile is not given, copy to the current dump file for writing.

Arguments

• tofile::AbstractString="": Destination file path. If empty, copies to wf.store.

• start::Bool=false: If true, copy from wf.start file instead of wf.dump.

• state::Int=0: State number for determinant files. If 0, copies the main dump file. If >0, copies the state-specific determinant file (e.g., file_state2.h5).

• reverse::Bool=false: If true, copy from tofile to the dump file instead of the other way around.

  Note: This does not check the contents of the files.

Examples

# Copy current dump to store
copy_wavefunction(EC)

# Copy start file to a backup
copy_wavefunction(EC, "backup.h5"; start=true)

# Copy determinant file for state 2
copy_wavefunction(EC, "state2_backup.h5"; state=2)

dump_amplitudes([io::TrexioFile,] EC::ECInfo, T1, T2)

Dump closed-shell CC amplitudes to TREXIO file.

T1 is the singles amplitude matrix (nvirt × nocc). T2 is the doubles amplitude tensor (nvirt × nvirt × nocc × nocc).

dump_amplitudes([io::TrexioFile,] EC::ECInfo, T1a, T1b, T2a, T2b, T2ab)

Dump unrestricted CC amplitudes to TREXIO file.

T1a, T1b are the α and β singles amplitude matrices. T2a, T2b, T2ab are the αα, ββ, and αβ doubles amplitude tensors.

dump_determinants([io::TrexioFile,] EC::ECInfo, dets, coeffs; state=1)

Dump CIPHI determinants and CI coefficients to TREXIO file.

For multi-state calculations, each state should be stored separately using the state parameter. State 1 goes to the main file, state n goes to filename_state{n}.h5.

Arguments

• dets::Vector{<:AbstractDeterminant}: Determinants with alpha/beta occupation patterns
• coeffs::AbstractVector{Float64}: CI coefficients for this state
• state::Int=1: State number (1 = ground state)

Example

# Store ground state
dump_determinants(EC, dets, coeffs[:, 1]; state=1)
# Store excited state
dump_determinants(EC, dets, coeffs[:, 2]; state=2)

dump_determinants_multistate(EC::ECInfo, dets, coeffs_matrix)

Dump determinants and coefficients for multiple states to separate files.

Arguments

• EC::ECInfo: Electronic structure information
• dets::Vector{<:AbstractDeterminant}: Determinants (same for all states)
• coeffs_matrix::Matrix{Float64}: CI coefficients matrix (ndets × nstates)

Each state is stored in a separate file per TREXIO standard.

dump_orbitals([io::TrexioFile,] EC::ECInfo, cMO; basis=nothing, type="HF", 
              energies=nothing, occupations=nothing, MO="mo")

Dump orbitals to TREXIO file.

MO can be "mo" for molecular orbitals or "po" for positron orbitals.

dump_rotations([io::TrexioFile,] EC::ECInfo, cRot::SpinMatrix; type="Rotation", energies=nothing, occupations=nothing,
               fock=nothing, MO="mo", biorthogonal=false)

Dump orbital rotations to TREXIO file.

MO can be "mo" for molecular orbitals or "po" for positron orbitals. fock (optional) is the Fock matrix in the original MO basis (the basis the rotation is relative to); it is stored as-is (no AO reordering, since rotations carry no AO basis).

fetch_ao_fock([io::TrexioFile,] EC::ECInfo; start=false) -> Union{SpinMatrix,Nothing}

Fetch the Fock matrix stored in the trexio dump (if present). For orbital dumps it is returned in the internal (libcint) AO order; for rotation dumps it is returned in the original MO basis (as stored). Returns a restricted or unrestricted SpinMatrix, or nothing if the dump does not store a Fock matrix (e.g. dumps written before Fock persistence).

If start=true, reads from the start file (wf.start) instead of the current dump file.

fetch_determinants([io::TrexioFile,] EC::ECInfo; start=false, OPattern=UInt64, state=1)

Fetch CIPHI determinants and CI coefficients from TREXIO file.

Arguments

• start::Bool=false: If true, read from wf.start file instead of wf.dump
• OPattern::Type=UInt64: Type for orbital patterns (use UInt128 for >64 orbitals)
• state::Int=1: State number to read

Returns

• (determinants, coefficients): Tuple of determinant vector and coefficient vector

Example

dets, coeffs = fetch_determinants(EC; state=1)
# For systems with >64 orbitals:
dets, coeffs = fetch_determinants(EC; OPattern=UInt128)

fetch_orbital_classes([io::TrexioFile,] EC::ECInfo; MO="mo", start=false) -> (Vector{String}, Vector{String})

Fetch orbital classes from the trexio dump.

Returns tuples of orbital classes for alpha and beta spins. Classes can be "Core", "Inactive", "Active", "Virtual", "Deleted".

MO can be "mo" for molecular orbitals or "po" for positron orbitals. If start=true, reads from the start file (wf.start) instead of the current dump file.

fetch_orbital_data(EC::ECInfo; MO="mo") -> Union{OrbitalData, Nothing}

Fetch all orbital data from the dump file.

Returns nothing if no dump file exists (FCIDUMP-only case). This should be called BEFORE opening the store file for writing, to avoid issues when dump and store are the same file.

fetch_orbital_energies([io::TrexioFile,] EC::ECInfo, MO="mo"; start=false) -> (Vector{Float64}, Vector{Float64})

Fetch orbital energies from the trexio dump.

Returns tuples of orbital energies for alpha and beta spins.

MO can be "mo" for molecular orbitals or "po" for positron orbitals. If start=true, reads from the start file (wf.start) instead of the current dump file.

fetch_orbital_occupations([io::TrexioFile,] EC::ECInfo, MO="mo"; start=false) -> (Vector{Float64}, Vector{Float64})

Fetch orbital occupations from the trexio dump.

Returns tuples of orbital occupations for alpha and beta spins.

MO can be "mo" for molecular orbitals or "po" for positron orbitals. If start=true, reads from the start file (wf.start) instead of the current dump file.

fetch_orbitals([io::TrexioFile,] EC::ECInfo; MO="mo", start=false) -> (SpinMatrix, String, BasisSet)

Fetch the molecular orbitals from the trexio dump.

Returns a SpinMatrix of the orbitals, type::String and the basis.

If the basis information is not stored in the dump file (i.e., we have a rotation instead of orbitals), basis is returned as empty BasisSet. MO can be "mo" for molecular orbitals or "po" for positron orbitals. If start=true, reads from the start file (wf.start) instead of the current dump file.

fetch_restricted_amplitudes([io::TrexioFile,] EC::ECInfo; start=false)

Fetch restricted CC amplitudes from the trexio dump.

Returns (T1, T2) for closed-shell case. If start=true, reads from the start file (wf.start) first.

Returns empty arrays if amplitudes are not found in the dump file.

fetch_rotations([io::TrexioFile,] EC::ECInfo, MO="mo") -> (SpinMatrix, String)

Fetch the molecular orbital rotations from the trexio dump.

Returns a SpinMatrix of the rotations and type::String.

MO can be "mo" for molecular orbitals or "po" for positron orbitals.

fetch_unrestricted_amplitudes([io::TrexioFile,] EC::ECInfo; start=false)

Fetch unrestricted CC amplitudes from the trexio dump.

Returns (T1a, T1b, T2a, T2b, T2ab) for unrestricted case. If start=true, reads from the start file (wf.start) first.

Returns empty arrays if amplitudes are not found in the dump file.

has_amplitudes([io::TrexioFile,] EC::ECInfo; unrestricted=false, start=false)

Check if amplitudes are stored in the dump file. If start=true, checks the start file (wf.start) first.

Returns true if amplitudes (singles or doubles) are found.

has_determinants([io::TrexioFile,] EC::ECInfo; start=false, state=1)

Check if determinants are stored in the TREXIO file.

Arguments

• start::Bool=false: If true, check wf.start file instead of wf.dump
• state::Int=1: State number to check

Returns

true if determinants are found in the file.

has_dumpfile(EC::ECInfo; start=false)

Check if the dump file exists.

If start=true, checks for the start file (wf.start) instead. Returns true if the file exists.

is_biorthogonal(type)

Returns true if the given orbital type is a bi-orthogonal rotation.

is_rotation(type)

Returns true if the given orbital type is an orbital rotation (i.e., a unitary transformation of orbitals rather than LCAO coefficients).

load_wavefunction(EC::ECInfo, what::Vector{String}; start=false, state=1, OPattern=UInt64)

Load parts of the wavefunction from file WfOptions.dump.

what can contain any of the following strings:

• "all": load everything available (overrides other options)
• "orbitals": load orbitals (always loaded by default)
• "orbital_energies": load orbital energies
• "orbital_occupations": load orbital occupations
• "amplitudes": load CC amplitudes (restricted)
• "unrestricted_amplitudes": load CC amplitudes (unrestricted)
• "determinants": load selected CI determinants and coefficients

Arguments

• what::Vector{String}: List of wavefunction parts to load
• start::Bool=false: If true, read from wf.start file instead of wf.dump
• state::Int=1: State number for determinants (1 = ground state)
• OPattern::Type=UInt64: Orbital pattern type for determinants (use UInt128 for >64 orbitals)

Returns

A Dict{String,Any} with the requested parts of the wavefunction:

• "orbitals": SpinMatrix of molecular orbitals
• "orbital_type": Type string (e.g., "RHF", "UHF")
• "basis": BasisSet (empty if rotation)
• "orbital_energies": Tuple of (alpha, beta) energies
• "orbital_occupations": Tuple of (alpha, beta) occupations
• "T1", "T2": Restricted amplitudes
• "T1a", "T1b", "T2a", "T2b", "T2ab": Unrestricted amplitudes
• "determinants": Vector of determinants
• "ci_coefficients": Vector of CI coefficients

Example

# Load orbitals and amplitudes
wf = load_wavefunction(EC, ["orbitals", "amplitudes"])

# Load everything
wf = load_wavefunction(EC, ["all"])

# Load determinants for excited state
wf = load_wavefunction(EC, ["determinants"]; state=2)

natural_orbital_data(EC::ECInfo, rdm::SpinMatrix)

Build the orbital payload written to the natural-orbital TREXIO file from a correlated 1-RDM.

open_dump(EC::ECInfo, intent; start=false) -> TrexioFile

Open the dump file for wavefunction.

intent can be "r", "w", or "u" (read, write, or update). If start=true, opens the start file (wf.start) instead.

open_dump(f, EC::ECInfo, intent; start=false)

Open the dump file for wavefunction, execute function f with the opened TrexioFile, and close the file.

To be used as open_dump(EC, intent) do io ... end. intent can be "r", "w", or "u" (read, write, or update). If start=true, opens the start file (wf.start) instead.

Note: f is typed as a type parameter rather than ::Function to enable type inference of the return value through the closure.

rotate_orbitaldata!(orbital_data::OrbitalData, Rpq_a::Matrix{Float64}, Rpq_b::Union{Matrix{Float64}, Nothing}=nothing) -> OrbitalData

Rotate the orbitals in orbital_data using the provided rotation matrices Rpq_a and Rpq_b.

• If Rpq_b is nothing and the orbitals are restricted, only the alpha orbitals will be rotated, and the beta orbitals will follow the same rotation.
• If Rpq_b is nothing but the orbitals are unrestricted, the same rotation will be applied to both alpha and beta orbitals.
• If Rpq_b is provided and the orbitals are restricted, the beta orbitals will be rotated with Rpq_b if it is different from Rpq_a, effectively making the orbitals unrestricted.
• If Rpq_b is provided and the orbitals are already unrestricted, the beta orbitals will be rotated with Rpq_b.

save_wavefunction(EC::ECInfo, wf::AbstractDict; state=1)

Save parts of the wavefunction to file WfOptions.store or WfOptions.dump (if store is empty).

wf can contain any of the following keys:

Orbital data:

• "basis": basis set information
• "orbitals": molecular orbitals (SpinMatrix)
• "rotations": orbital rotations (SpinMatrix) - alternative to "orbitals"
• "orbital_type": type of the orbitals (e.g., "RHF", "UHF", "ROHF", "MCSCF")
• "orbital_energies": molecular orbital energies
• "orbital_occupations": molecular orbital occupations

Restricted CC amplitudes:

• "T1": singles amplitudes (nvirt × nocc)
• "T2": doubles amplitudes (nvirt × nvirt × nocc × nocc)

Unrestricted CC amplitudes:

• "T1a", "T1b": α and β singles amplitudes
• "T2a", "T2b", "T2ab": αα, ββ, and αβ doubles amplitudes

Selected CI (CIPHI) data:

• "determinants": vector of determinants
• "ci_coefficients": CI coefficients (vector for single state, matrix for multi-state)

Arguments

• wf::AbstractDict: Dictionary containing wavefunction data
• state::Int=1: State number for determinants (used when ci_coefficients is a vector)

Example

# Save orbitals and amplitudes
save_wavefunction(EC, Dict(
    "orbitals" => cMO,
    "orbital_type" => "RHF",
    "T1" => T1,
    "T2" => T2
))

# Save determinants for ground state
save_wavefunction(EC, Dict(
    "determinants" => dets,
    "ci_coefficients" => coeffs
); state=1)

# Save multi-state determinants (each column is a state)
save_wavefunction(EC, Dict(
    "determinants" => dets,
    "ci_coefficients" => coeffs_matrix  # n_dets × n_states
))

state_filename(filename::String, state::Int) -> String

Generate state-specific filename for multi-state storage. Per TREXIO standard, each state is stored in a separate file:

• State 1 (ground): filename.h5
• State 2: filename_state2.h5
• State n: filename_state{n}.h5

transfer_orbitals_to_store!(io_store::TrexioFile, EC::ECInfo, orbital_data::Union{OrbitalData, Nothing}=nothing; MO="mo")

Transfer orbitals from the dump file to an already opened store file.

Important: orbital_data must be pre-fetched before opening the store file to avoid reading from a truncated file.

This properly handles cases where frozen orbitals or geometry differ between dump and store files.

For FCIDUMP-only calculations (no dump file), stores a unity rotation matrix instead of orbitals, allowing amplitude storage and restart.

Arguments

• io_store: An already opened TrexioFile for writing
• EC: Electronic structure information object
• orbital_data: Pre-fetched orbital data, or nothing to store unity rotation
• MO: "mo" for molecular orbitals or "po" for positron orbitals

write_correlated_properties!(EC::ECInfo, rdm::SpinMatrix)

Persist the correlated 1-RDM to the standard wavefunction target and, when requested, write the corresponding natural-orbital file.

write_correlated_rdm!(EC::ECInfo, rdm::SpinMatrix)

Write the correlated 1-RDM to the standard wavefunction store target, initializing the TREXIO file with orbital data first when needed.

write_natural_orbitals!(EC::ECInfo, rdm::SpinMatrix)

Write natural orbitals and occupations to the dedicated TREXIO file selected by EC.options.wf.natorb.

OrbitalData

Container for orbital data fetched from a dump file.

dumpfile(EC::ECInfo, intent; start=false)

Get the dump file name for wavefunction.

If intent="w", the dump file for writing is returned. Otherwise, the dump file for reading is returned. If start=true and intent != "w", the start file (wf.start) is returned. For reads, an empty wf.dump falls back to the start file (wf.start), so a restart that deliberately omits a separate dump (dump="") reads orbitals/classes/amplitudes from start. Returns (filename::String, full_path_filename::String).

prepare_class_vectors(classes, orbitals::SpinMatrix)

Normalize explicit orbital classes for dumping into the (classa, classb) form expected by write_trexio_orbitals. classes is either a vector of class strings (restricted) or a tuple of (alpha, beta) vectors (unrestricted).

prepare_orb_coefficients(cMO)

Prepare orbital coefficients for dumping.

prepare_orb_vectors(input, restricted)

Prepare orbital info vectors for dumping.