Fcidump (Encodings)

Fcidump Module

Namespace: Encodings
Assembly: Encodings.dll

FCIDUMP file parser and coefficient factory builder.

Reads molecular integrals in the standard FCIDUMP format (Knowles & Handy, 1989) used by MOLPRO, PySCF, Psi4, and other quantum chemistry packages. Produces a coefficientFactory function compatible with computeHamiltonianWith.

Index convention: FCIDUMP files use 1-based indices with zero as a sentinel. Two-electron integrals are stored in chemist's notation (ij|kl). The parser converts to 0-based indices internally.

Integral notation: The chemist's integral (ij|kl) relates to the physicist's integral ⟨pq|rs⟩ by ⟨pq|rs⟩ = (pr|qs). Since 0.9.0 the factory returns the RAW single-bar physicist integral⟨pq|rs⟩ for key "p,q,r,s" (no ½, no index swap); the Hamiltonian builders apply the two-body ½ and the r↔s annihilator order, so the assembled physics is unchanged from earlier releases.

Types

Type	Description
FcidumpData	Parsed FCIDUMP data containing molecular integrals and metadata.

Functions and values

Function or value	Description
`parse content` Full Usage: `parse content` Parameters: content : `string` - The full text content of an FCIDUMP file. Returns: `FcidumpData` A FcidumpData record with parsed integrals and metadata.	Parse an FCIDUMP file from its text content. Handles both `&END` and `/` header terminators. Indices are converted from 1-based (FCIDUMP) to 0-based internally. Two-electron integrals are fully symmetrized (8-fold permutation symmetry). One-electron integrals are symmetrized: h[i,j] = h[j,i]. content : `string` The full text content of an FCIDUMP file. Returns: `FcidumpData` A FcidumpData record with parsed integrals and metadata.
`parseToFactory content` Full Usage: `parseToFactory content` Parameters: content : `string` - The full text content of an FCIDUMP file. Returns: `(string -> Complex option) * float * int` A tuple of (coefficientFactory, coreEnergy, norb) where norb is the number of spatial orbitals (use as the `n` parameter to `computeHamiltonianWith`).	Parse an FCIDUMP file and return a ready-to-use coefficient factory. content : `string` The full text content of an FCIDUMP file. Returns: `(string -> Complex option) * float * int` A tuple of (coefficientFactory, coreEnergy, norb) where norb is the number of spatial orbitals (use as the `n` parameter to `computeHamiltonianWith`).
`parseToSpinOrbitalFactory content` Full Usage: `parseToSpinOrbitalFactory content` Parameters: content : `string` - FCIDUMP file content (spatial orbitals). Returns: `(string -> Complex option) * float * int` A tuple of (factory, coreEnergy, numSpinOrbitals). Use numSpinOrbitals as the `n` parameter to `computeHamiltonianWith`.	Parse a spatial-orbital FCIDUMP and return a spin-orbital coefficient factory. content : `string` FCIDUMP file content (spatial orbitals). Returns: `(string -> Complex option) * float * int` A tuple of (factory, coreEnergy, numSpinOrbitals). Use numSpinOrbitals as the `n` parameter to `computeHamiltonianWith`.
`toCoefficientFactory data` Full Usage: `toCoefficientFactory data` Parameters: data : `FcidumpData` - Parsed FCIDUMP data. Returns: `string -> Complex option` A coefficient factory function `string → Complex option`.	Build a coefficient factory from parsed FCIDUMP data. The returned function is compatible with the raw-physicist `computeHamiltonianWith` and the Skeleton API (0.9.0+). Convention mapping: The Hamiltonian module assembles `H₂ = ½ Σ ⟨pq\|rs⟩ a†_p a†_q a_s a_r`, applying the ½ and the r↔s annihilator order itself. This factory therefore returns the RAW single-bar physicist integral for key `"p,q,r,s"`: `⟨pq\|rs⟩ = (pr\|qs)` in chemist's notation (no ½, no swap). The assembled physics is identical to earlier releases. The nuclear repulsion energy is not included in the factory output. Add it separately as an identity-weighted term if needed. data : `FcidumpData` Parsed FCIDUMP data. Returns: `string -> Complex option` A coefficient factory function `string → Complex option`.
`toSpinOrbitalFactory data` Full Usage: `toSpinOrbitalFactory data` Parameters: data : `FcidumpData` - Parsed spatial-orbital FCIDUMP data. Returns: `(string -> Complex option) * int` A coefficient factory for spin-orbital indices, and the number of spin-orbitals.	Build a spin-orbital coefficient factory from spatial-orbital FCIDUMP data. Standard FCIDUMP files from RHF/ROHF calculations contain spatial-orbital integrals. Fermion-to-qubit encodings operate on spin-orbitals, where each spatial orbital p maps to spin-orbitals 2p (α) and 2p+1 (β). Spin-orbital mapping: One-electron: h_{2p+σ, 2q+τ} = δ_{σ,τ} · h_{p,q} Two-electron (chemist): (2p+σ, 2q+τ \| 2r+σ', 2s+τ') = δ_{σ,τ} · δ_{σ',τ'} · (pq\|rs) The returned factory is indexed by spin-orbital indices and should be used with `n = 2 * NORB` (number of spin-orbitals). Since 0.9.0 it returns the RAW single-bar physicist integral for a two-body key `"P,Q,R,S"`: `⟨PQ\|RS⟩ = chemist_spinorb(P,R,Q,S)` (no ½, no swap); the Hamiltonian builder applies the ½ and r↔s order. data : `FcidumpData` Parsed spatial-orbital FCIDUMP data. Returns: `(string -> Complex option) * int` A coefficient factory for spin-orbital indices, and the number of spin-orbitals.