Hamiltonian (Encodings)

Hamiltonian Module

Namespace: Encodings
Assembly: Encodings.dll

Hamiltonian construction from one-body and two-body integrals.

Assembles the second-quantized electronic Hamiltonian:

H = Σ_{pq} h_{pq} a†_p a_q + ½ Σ_{pqrs} ⟨pq|rs⟩ a†_p a†_q a_s a_r

and encodes it as a sum of Pauli strings using any provided encoding function. The builders handle one-body terms, two-body terms, coefficient combination, and zero-term dropping.

BREAKING CHANGE (0.9.0). The primary builders — computeHamiltonian, computeHamiltonianWith and the parallel / cached / skeleton variants — now consume RAW single-bar physicist integrals ⟨pq|rs⟩ keyed "p,q,r,s" (no ½, no index swap). Internally each two-body key contributes ½·⟨pq|rs⟩·a†_p a†_q a_s a_r (the ½ of the two-body term and the r↔s annihilator order are applied by the library). The Fcidump adapters likewise return raw physicist integrals, so FCIDUMP physics is unchanged.

The previously released weighted semantics (value = the full weighted prefactor of a†_i a†_j a_k a_l, applied verbatim, two-body ½ pre-folded) remain available behind the clearly named computeHamiltonianFromWeighted… migration functions and the weightedToRawFactory adapter. See the migration guide (docs/guides/migration-0.9.md) for the exact before/after mapping.

Types

Type	Description
EncoderFn	A function type that encodes a ladder operator into qubit Pauli strings.
ExchangeTerm	A two-body exchange term with indices i, j, k, l representing the operator `a†_i a†_j a_k a_l` (annihilators in the order k then l).
HamiltonianSkeleton	A precomputed encoding skeleton separating Pauli structure from integral coefficients.
HamiltonianTerm	Discriminated union representing a term in the Hamiltonian.
OverlapTerm	A one-body overlap term with indices i and j, representing h_{ij} a†_i a_j.
SkeletonEntry	A single entry in a precomputed Hamiltonian skeleton.
SkeletonTerm	A pre-computed Pauli term with its signature cached.

Functions and values

Function or value	Description
`antisymmetrizedToRawFactory antisymmetrizedFactory key` Full Usage: `antisymmetrizedToRawFactory antisymmetrizedFactory key` Parameters: antisymmetrizedFactory : `string -> Complex option` - A factory returning, for key `"p,q,r,s"`, the antisymmetrised double-bar integral `⟨pq\|\|rs⟩ = ⟨pq\|rs⟩ − ⟨pq\|sr⟩`, and, for key `"p,q"`, the one-body coefficient `h_pq`. key : `string` Returns: `Complex option` A raw factory that scales every two-body entry by ½ (one-body passes through). The double-bar Hamiltonian `¼·Σ ⟨pq\|\|rs⟩ a†_p a†_q a_s a_r` equals the single-bar `½·Σ ⟨pq\|rs⟩ a†_p a†_q a_s a_r` under fermionic anticommutation, so `½·⟨pq\|\|rs⟩` is the correct raw single-bar value for each key.	Adapt an antisymmetrised double-bar physicist tensor `⟨pq\|\|rs⟩` (¼ convention) to the raw single-bar factory consumed by the primary builders. Use for chemistry codes that hand you an already-antisymmetrised tensor. The core/nuclear energy remains a separate, caller-supplied constant. antisymmetrizedFactory : `string -> Complex option` A factory returning, for key `"p,q,r,s"`, the antisymmetrised double-bar integral `⟨pq\|\|rs⟩ = ⟨pq\|rs⟩ − ⟨pq\|sr⟩`, and, for key `"p,q"`, the one-body coefficient `h_pq`. key : `string` Returns: `Complex option` A raw factory that scales every two-body entry by ½ (one-body passes through). The double-bar Hamiltonian `¼·Σ ⟨pq\|\|rs⟩ a†_p a†_q a_s a_r` equals the single-bar `½·Σ ⟨pq\|rs⟩ a†_p a†_q a_s a_r` under fermionic anticommutation, so `½·⟨pq\|\|rs⟩` is the correct raw single-bar value for each key.
`applyCoefficients skeleton rawPhysicistFactory` Full Usage: `applyCoefficients skeleton rawPhysicistFactory` Parameters: skeleton : `HamiltonianSkeleton` - The precomputed skeleton from `computeHamiltonianSkeleton` or `computeHamiltonianSkeletonFor`. rawPhysicistFactory : `string -> Complex option` - A raw physicist factory (see `computeHamiltonianWith`): key `"p,q,r,s"` ↦ `⟨pq\|rs⟩`. The library applies the ½ and r↔s order. Returns: `PauliRegisterSequence` A PauliRegisterSequence representing the encoded Hamiltonian.	Apply raw physicist integral coefficients to a precomputed skeleton. skeleton : `HamiltonianSkeleton` The precomputed skeleton from `computeHamiltonianSkeleton` or `computeHamiltonianSkeletonFor`. rawPhysicistFactory : `string -> Complex option` A raw physicist factory (see `computeHamiltonianWith`): key `"p,q,r,s"` ↦ `⟨pq\|rs⟩`. The library applies the ½ and r↔s order. Returns: `PauliRegisterSequence` A PauliRegisterSequence representing the encoded Hamiltonian.
`applyCoefficientsFromWeighted skeleton coefficientFactory` Full Usage: `applyCoefficientsFromWeighted skeleton coefficientFactory` Parameters: skeleton : `HamiltonianSkeleton` - The precomputed skeleton from `computeHamiltonianSkeleton` or `computeHamiltonianSkeletonForFromWeighted`. coefficientFactory : `string -> Complex option` - A function returning Some(coefficient) for a given comma-separated index key, or None to skip. Same WEIGHTED contract as `computeHamiltonianFromWeightedWith` — the value is the full weighted prefactor (two-body ½ pre-folded), applied verbatim to `a†_i a†_j a_k a_l`. For the raw-physicist contract use `applyCoefficients`. Returns: `PauliRegisterSequence` A PauliRegisterSequence representing the encoded Hamiltonian.	[Legacy / migration] Apply weighted integral coefficients to a precomputed skeleton. Accumulates coefficients directly into a dictionary keyed by pre-computed Pauli signatures. No Pauli algebra, no intermediate `PauliRegister` construction, and no re-computation of signature strings. Final `PauliRegister` objects are created only for the combined result (~tens of terms, not thousands). Zero residues are dropped cancellation-aware (exact zeros, or residues from more than one contribution below a small multiple of machine epsilon times the contribution scale), matching `computeHamiltonianFromWeightedWith`; standalone tiny coefficients are preserved. Typical runtime is under 10 ms for systems up to ~20 qubits, making PES scans over hundreds of geometries essentially free after the one-time skeleton build. skeleton : `HamiltonianSkeleton` The precomputed skeleton from `computeHamiltonianSkeleton` or `computeHamiltonianSkeletonForFromWeighted`. coefficientFactory : `string -> Complex option` A function returning Some(coefficient) for a given comma-separated index key, or None to skip. Same WEIGHTED contract as `computeHamiltonianFromWeightedWith` — the value is the full weighted prefactor (two-body ½ pre-folded), applied verbatim to `a†_i a†_j a_k a_l`. For the raw-physicist contract use `applyCoefficients`. Returns: `PauliRegisterSequence` A PauliRegisterSequence representing the encoded Hamiltonian.
`computeHamiltonian rawPhysicistFactory n` Full Usage: `computeHamiltonian rawPhysicistFactory n` Parameters: rawPhysicistFactory : `string -> Complex option` - A raw physicist factory (see `computeHamiltonianWith`). n : `uint32` - The number of qubits/modes in the system. Returns: `PauliRegisterSequence`	Compute a qubit Hamiltonian from raw single-bar physicist integrals using Jordan-Wigner encoding. Primary builder (0.9.0+). rawPhysicistFactory : `string -> Complex option` A raw physicist factory (see `computeHamiltonianWith`). n : `uint32` The number of qubits/modes in the system. Returns: `PauliRegisterSequence`
`computeHamiltonianCached encode rawPhysicistFactory n` Full Usage: `computeHamiltonianCached encode rawPhysicistFactory n` Parameters: encode : `EncoderFn` - The encoding function. rawPhysicistFactory : `string -> Complex option` - A raw physicist factory (see `computeHamiltonianWith`). n : `uint32` - Number of spin-orbitals (qubits). Returns: `PauliRegisterSequence`	Cached-operator version of `computeHamiltonianWith` (raw physicist contract). encode : `EncoderFn` The encoding function. rawPhysicistFactory : `string -> Complex option` A raw physicist factory (see `computeHamiltonianWith`). n : `uint32` Number of spin-orbitals (qubits). Returns: `PauliRegisterSequence`
`computeHamiltonianFromWeighted coefficientFactory n` Full Usage: `computeHamiltonianFromWeighted coefficientFactory n` Parameters: coefficientFactory : `string -> Complex option` - A function that returns Some(coefficient) for a given comma-separated index key (e.g., "0,1" for one-body, "0,1,2,3" for two-body), or None if the term should be skipped. n : `uint32` - The number of qubits/modes in the system. Returns: `PauliRegisterSequence` A PauliRegisterSequence representing the encoded Hamiltonian.	[Legacy / migration] Compute a qubit Hamiltonian from weighted integral coefficients using Jordan-Wigner encoding. Jordan-Wigner specialisation of `computeHamiltonianFromWeightedWith`. The factory returns the FULL WEIGHTED prefactor of the corresponding operator string, applied verbatim: "i,j" → h_ij, the coefficient of a†_i a_j. "i,j,k,l" → the coefficient of a†_i a†_j a_k a_l, with the ½ of the two-body term ½·Σ g_pqrs a†_p a†_q a_r a_s already folded in. No additional ½ or index swap is applied. The nuclear/constant term is not added (callers may add E_nuc·I separately). New code should prefer the raw-physicist `computeHamiltonian` (0.9.0+). coefficientFactory : `string -> Complex option` A function that returns Some(coefficient) for a given comma-separated index key (e.g., "0,1" for one-body, "0,1,2,3" for two-body), or None if the term should be skipped. n : `uint32` The number of qubits/modes in the system. Returns: `PauliRegisterSequence` A PauliRegisterSequence representing the encoded Hamiltonian.
`computeHamiltonianFromWeightedCached encode coefficientFactory n` Full Usage: `computeHamiltonianFromWeightedCached encode coefficientFactory n` Parameters: encode : `EncoderFn` - The encoding function. coefficientFactory : `string -> Complex option` - Weighted coefficient lookup (see `computeHamiltonianFromWeightedWith`). n : `uint32` - Number of spin-orbitals (qubits). Returns: `PauliRegisterSequence`	[Legacy / migration] Optimised Hamiltonian construction with operator caching (weighted contract). Pre-computes and caches all 2n encoded ladder operators (n raises + n lowers) before assembling the Hamiltonian. This avoids redundant encoding computations when the same operator appears in many terms — each a†_i or a_j is computed once and reused across all one-body and two-body terms that reference it. For a system with n spin-orbitals and N_nz non-zero two-body integrals, this reduces encoding calls from 4·N_nz to 2n, with the multiplication cost remaining O(N_nz). Typical speedup is 5–20× for molecular systems where N_nz ≪ n⁴. Coefficient contract (same as computeHamiltonianFromWeightedWith). The factory returns the FULL WEIGHTED prefactor for each key, applied verbatim (two-body ½ pre-folded). Results are identical to the sequential builder, including the cancellation-aware removal of zero residues. encode : `EncoderFn` The encoding function. coefficientFactory : `string -> Complex option` Weighted coefficient lookup (see `computeHamiltonianFromWeightedWith`). n : `uint32` Number of spin-orbitals (qubits). Returns: `PauliRegisterSequence`
`computeHamiltonianFromWeightedParallel coefficientFactory n` Full Usage: `computeHamiltonianFromWeightedParallel coefficientFactory n` Parameters: coefficientFactory : `string -> Complex option` n : `uint32` Returns: `PauliRegisterSequence`	[Legacy / migration] Parallel version of `computeHamiltonianFromWeighted` (Jordan-Wigner, weighted contract). coefficientFactory : `string -> Complex option` n : `uint32` Returns: `PauliRegisterSequence`
`computeHamiltonianFromWeightedWith encode coefficientFactory n` Full Usage: `computeHamiltonianFromWeightedWith encode coefficientFactory n` Parameters: encode : `EncoderFn` - The encoding function to transform ladder operators to Pauli strings. coefficientFactory : `string -> Complex option` - A function that returns Some(coefficient) for a given comma-separated index key (e.g., "0,1" for one-body, "0,1,2,3" for two-body), or None if the term should be skipped. n : `uint32` - The number of qubits/modes in the system. Returns: `PauliRegisterSequence` A PauliRegisterSequence representing the encoded Hamiltonian.	[Legacy / migration] Compute a qubit Hamiltonian from weighted integral coefficients using any encoding. This preserves the previously released (≤ 0.8.0) weighted contract: the factory returns the FULL WEIGHTED prefactor of the operator string, applied verbatim — "i,j" → coefficient of `a†_i a_j`; "i,j,k,l" → coefficient of `a†_i a†_j a_k a_l`with the two-body ½ already folded in. No ½ and no index swap are applied by the library. New code should prefer the raw-physicist `computeHamiltonianWith` (0.9.0+). To reuse an existing weighted factory with the raw builders, wrap it once with `weightedToRawFactory`. Numerically-zero residues from fermionic cancellation are removed (cancellation-aware); standalone tiny coefficients are preserved. encode : `EncoderFn` The encoding function to transform ladder operators to Pauli strings. coefficientFactory : `string -> Complex option` A function that returns Some(coefficient) for a given comma-separated index key (e.g., "0,1" for one-body, "0,1,2,3" for two-body), or None if the term should be skipped. n : `uint32` The number of qubits/modes in the system. Returns: `PauliRegisterSequence` A PauliRegisterSequence representing the encoded Hamiltonian.
`computeHamiltonianFromWeightedWithParallel encode coefficientFactory n` Full Usage: `computeHamiltonianFromWeightedWithParallel encode coefficientFactory n` Parameters: encode : `EncoderFn` - The encoding function to transform ladder operators to Pauli strings. coefficientFactory : `string -> Complex option` - A weighted coefficient lookup (see `computeHamiltonianFromWeightedWith`). n : `uint32` - The number of qubits/modes in the system. Returns: `PauliRegisterSequence` A PauliRegisterSequence representing the encoded Hamiltonian.	[Legacy / migration] Parallel version of `computeHamiltonianFromWeightedWith` (weighted contract). Distributes encoding work across available CPU cores using Array.Parallel. The n² one-body and n⁴ two-body index loops are parallelised. Coefficient lookups remain sequential (cheap), while the expensive encode-and-multiply steps run across all cores. Produces results identical to the sequential `computeHamiltonianFromWeightedWith`. encode : `EncoderFn` The encoding function to transform ladder operators to Pauli strings. coefficientFactory : `string -> Complex option` A weighted coefficient lookup (see `computeHamiltonianFromWeightedWith`). n : `uint32` The number of qubits/modes in the system. Returns: `PauliRegisterSequence` A PauliRegisterSequence representing the encoded Hamiltonian.
`computeHamiltonianParallel rawPhysicistFactory n` Full Usage: `computeHamiltonianParallel rawPhysicistFactory n` Parameters: rawPhysicistFactory : `string -> Complex option` n : `uint32` Returns: `PauliRegisterSequence`	Parallel version of `computeHamiltonian` (Jordan-Wigner, raw physicist contract). rawPhysicistFactory : `string -> Complex option` n : `uint32` Returns: `PauliRegisterSequence`
`computeHamiltonianSkeleton encode n` Full Usage: `computeHamiltonianSkeleton encode n` Parameters: encode : `EncoderFn` - The encoding function. n : `uint32` - The number of qubits/modes. Returns: `HamiltonianSkeleton` A HamiltonianSkeleton containing precomputed Pauli structures for all one-body and two-body operator products.	Precompute the Pauli skeleton for a given encoding and system size. Uses `Array.Parallel.map` on the n⁴ two-body index space. Signatures and operator arrays are cached in SkeletonTerm records so that `applyCoefficients` can accumulate coefficients without any Pauli algebra or string computation. The skeleton is contract-agnostic (pure Pauli structure for each operator product `a†_i a†_j a_k a_l`): it is consumed by both the raw `applyCoefficients` and the legacy `applyCoefficientsFromWeighted`, which differ only in how they map the supplied factory onto these structures. encode : `EncoderFn` The encoding function. n : `uint32` The number of qubits/modes. Returns: `HamiltonianSkeleton` A HamiltonianSkeleton containing precomputed Pauli structures for all one-body and two-body operator products.
`computeHamiltonianSkeletonFor encode rawPhysicistFactory n` Full Usage: `computeHamiltonianSkeletonFor encode rawPhysicistFactory n` Parameters: encode : `EncoderFn` - The encoding function. rawPhysicistFactory : `string -> Complex option` - A raw physicist factory; only presence/absence matters for discovery. n : `uint32` - The number of qubits/modes. Returns: `HamiltonianSkeleton`	Precompute a sparse Pauli skeleton using a raw physicist factory to discover active keys, then apply with `applyCoefficients`. encode : `EncoderFn` The encoding function. rawPhysicistFactory : `string -> Complex option` A raw physicist factory; only presence/absence matters for discovery. n : `uint32` The number of qubits/modes. Returns: `HamiltonianSkeleton`
`computeHamiltonianSkeletonForFromWeighted encode coefficientFactory n` Full Usage: `computeHamiltonianSkeletonForFromWeighted encode coefficientFactory n` Parameters: encode : `EncoderFn` - The encoding function. coefficientFactory : `string -> Complex option` - A weighted factory that returns Some for keys to include. Only the presence/absence matters; coefficient values are ignored. n : `uint32` - The number of qubits/modes. Returns: `HamiltonianSkeleton` A HamiltonianSkeleton containing precomputed Pauli structures only for index combinations where the factory returns Some.	[Legacy / migration] Precompute a sparse Pauli skeleton using a weighted coefficient factory to discover active keys. For molecules, typically only 5–10% of possible index combinations have non-zero integrals. This variant precomputes only those entries, giving a proportional speedup over the full `computeHamiltonianSkeleton`. Use when all geometries in a scan share the same sparsity pattern (same basis set → same non-zero integral indices). The discovered keys are weighted structural keys "i,j,k,l" (operator `a†_i a†_j a_k a_l`) and must be applied with `applyCoefficientsFromWeighted`. For the raw-physicist contract use `computeHamiltonianSkeletonFor` instead. encode : `EncoderFn` The encoding function. coefficientFactory : `string -> Complex option` A weighted factory that returns Some for keys to include. Only the presence/absence matters; coefficient values are ignored. n : `uint32` The number of qubits/modes. Returns: `HamiltonianSkeleton` A HamiltonianSkeleton containing precomputed Pauli structures only for index combinations where the factory returns Some.
`computeHamiltonianWith encode rawPhysicistFactory n` Full Usage: `computeHamiltonianWith encode rawPhysicistFactory n` Parameters: encode : `EncoderFn` - The encoding function to transform ladder operators to Pauli strings. rawPhysicistFactory : `string -> Complex option` - A factory returning, for key `"p,q,r,s"`, the RAW physicist integral `⟨pq\|rs⟩` (no ½, no index swap), and for key `"p,q"` the one-body coefficient `h_pq`; None to skip. n : `uint32` - The number of qubits/modes in the system. Returns: `PauliRegisterSequence` A PauliRegisterSequence representing the encoded Hamiltonian.	Compute a qubit Hamiltonian from raw single-bar physicist integrals using any encoding. Primary builder (0.9.0+). Assembles `Σ h_pq a†_p a_q + ½ Σ ⟨pq\|rs⟩ a†_p a†_q a_s a_r`: the library applies the two-body ½ and builds the annihilators in the order `a_s a_r` (the r↔s swap) internally, so the factory supplies the raw integral unmodified. Fcidump adapters produce a conforming raw factory. To reuse an existing weighted factory, wrap it with `weightedToRawFactory`, or use the legacy `computeHamiltonianFromWeightedWith`. The nuclear/constant term is not added. Numerically-zero residues are removed (cancellation-aware) while standalone tiny coefficients are preserved. encode : `EncoderFn` The encoding function to transform ladder operators to Pauli strings. rawPhysicistFactory : `string -> Complex option` A factory returning, for key `"p,q,r,s"`, the RAW physicist integral `⟨pq\|rs⟩` (no ½, no index swap), and for key `"p,q"` the one-body coefficient `h_pq`; None to skip. n : `uint32` The number of qubits/modes in the system. Returns: `PauliRegisterSequence` A PauliRegisterSequence representing the encoded Hamiltonian.
`computeHamiltonianWithParallel encode rawPhysicistFactory n` Full Usage: `computeHamiltonianWithParallel encode rawPhysicistFactory n` Parameters: encode : `EncoderFn` - The encoding function. rawPhysicistFactory : `string -> Complex option` - A raw physicist factory (see `computeHamiltonianWith`). n : `uint32` - The number of qubits/modes. Returns: `PauliRegisterSequence`	Parallel version of `computeHamiltonianWith` (raw physicist contract). encode : `EncoderFn` The encoding function. rawPhysicistFactory : `string -> Complex option` A raw physicist factory (see `computeHamiltonianWith`). n : `uint32` The number of qubits/modes. Returns: `PauliRegisterSequence`
`weightedToRawFactory weightedFactory key` Full Usage: `weightedToRawFactory weightedFactory key` Parameters: weightedFactory : `string -> Complex option` - A factory returning the FULL WEIGHTED prefactor for key `"i,j,k,l"` (the coefficient of `a†_i a†_j a_k a_l`, two-body ½ pre-folded), and the one-body coefficient `h_pq` for key `"p,q"`. key : `string` Returns: `Complex option` A raw-physicist factory. For a two-body query `"p,q,r,s"` it returns `2·w(p,q,s,r)`, so that feeding it to a raw builder reproduces exactly the weighted physics `w(p,q,s,r)·a†_p a†_q a_s a_r`. One-body keys pass through.	Adapt a legacy weighted coefficient factory to the raw physicist contract consumed by the primary builders (0.9.0+). This is the forward migration bridge: it lets pre-adapted weighted data (or an old caller's weighted factory) drive the new raw builders — including the Optimization entry points, which have no dedicated weighted overload. It is the exact inverse of the internal raw→weighted mapping. weightedFactory : `string -> Complex option` A factory returning the FULL WEIGHTED prefactor for key `"i,j,k,l"` (the coefficient of `a†_i a†_j a_k a_l`, two-body ½ pre-folded), and the one-body coefficient `h_pq` for key `"p,q"`. key : `string` Returns: `Complex option` A raw-physicist factory. For a two-body query `"p,q,r,s"` it returns `2·w(p,q,s,r)`, so that feeding it to a raw builder reproduces exactly the weighted physics `w(p,q,s,r)·a†_p a†_q a_s a_r`. One-body keys pass through.