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)

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).

  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::SpinMatrix; 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, 
               MO="mo", biorthogonal=false)

Dump orbital rotations to TREXIO file.

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

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") -> (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.

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)

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.

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.

If orbital_data is provided, uses it directly. Otherwise fetches from dump file.

Important: When dump and store files are the same, 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 fetch from dump
• MO: "mo" for molecular orbitals or "po" for positron orbitals

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. Returns (filename::String, full_path_filename::String).

prepare_orb_vectors(input, restricted)

Prepare orbital info vectors for dumping.