qarp.operators.ucc

Stateless UCC excitation-pool generators.

Each generator returns (operators, symbols) — equal-length lists of FermionOperators and sympy Symbols. Every generator is oriented as the excitation it names: symbol s_2to4 ↔ operator a†_4 a_2 (source → target, abab spin-orbital indices; spin-adapted pools use spatial indices).

Pool semantics (the excitation set is a pinned contract; the enumeration order is the documented deterministic order below, and blocks pair generators with symbols positionally before §17 canonical sorting):

  • canonical singles: occupied × virtual, spin-filtered;

  • canonical doubles: one generator per Sz-compatible {occupied pair} × {virtual pair} — the two pairings of the same four indices are the same normal-ordered monomial up to sign, so one representative is complete;

  • generalised pools replace occupied/virtual with disjoint index pairs, unordered between source and target (the antihermitized generator covers both directions); the representative has the smaller minimum as source;

  • paired doubles act on whole spatial orbitals (α and β together).

qarp.operators.ucc.adjacent_singles(n_spin_orbitals: int, *, antihermitized: bool = True) → tuple[list[FermionOperator], list[Symbol]][source]

Generate adjacent (i → i+1) singles, primarily for the Lipkin model.

Parameters:

  • n_spin_orbitals – The spin-orbital dimension; needs no reference.

  • antihermitized – If true, return T - T†; if false, plain excitation operators.

Returns:

The (operators, symbols) pair.

qarp.operators.ucc.spin_adapted_doubles(n_spatial_orbitals: int, *, antihermitized: bool = True) → tuple[list[FermionOperator], list[Symbol]][source]

Generate singlet spin-adapted paired doubles over spatial-orbital pairs.

One generator per spatial pair p < q: the pair excitation a†_{qα} a†_{qβ} a_{pβ} a_{pα}. Symbols use spatial indices: sad_0to1.

Parameters:

  • n_spatial_orbitals – Number of spatial orbitals (half the spin-orbital count).

  • antihermitized – If true, return T - T†; if false, the plain excitation.

Returns:

The (operators, symbols) pair, in itertools.combinations order.

qarp.operators.ucc.spin_adapted_singles(n_spatial_orbitals: int, *, antihermitized: bool = True) → tuple[list[FermionOperator], list[Symbol]][source]

Generate singlet spin-adapted singles over spatial-orbital pairs.

One generator per spatial pair p < q: the singlet excitation E_qp = Σ_σ a†_{qσ} a_{pσ} (reference-free — it commutes with S² regardless of occupations). Symbols use spatial indices: sas_0to1.

Parameters:

  • n_spatial_orbitals – Number of spatial orbitals (half the spin-orbital count).

  • antihermitized – If true, return E - E†; if false, the plain singlet excitation.

Returns:

The (operators, symbols) pair, in itertools.combinations order.

qarp.operators.ucc.ucc_doubles(onv: list[int] | None = None, n_spin_orbitals: int | None = None, *, spin_conserving: bool = True, generalised: bool = False, paired: bool = False, antihermitized: bool = True) → tuple[list[FermionOperator], list[Symbol]][source]

Generate UCC doubles.

Parameters:

  • onv – Reference occupation-number vector (abab list); sets the dimension.

  • n_spin_orbitals – Dimension for the reference-free generalised pool.

  • spin_conserving – If true, only include excitations which conserve Sz. Ignored for paired pools (they conserve spin by construction).

  • generalised – If true, enumerate disjoint index-pair combinations instead of occupied pairs → virtual pairs.

  • paired – If true, excite whole spatial orbitals (α and β together).

  • antihermitized – If true, return T - T†; if false, plain excitation operators.

Returns:

The (operators, symbols) pair, in enumeration order.

qarp.operators.ucc.ucc_singles(onv: list[int] | None = None, n_spin_orbitals: int | None = None, *, spin_conserving: bool = True, generalised: bool = False, antihermitized: bool = True) → tuple[list[FermionOperator], list[Symbol]][source]

Generate UCC singles.

Parameters:

  • onv – Reference occupation-number vector (abab list); sets the dimension.

  • n_spin_orbitals – Dimension for the reference-free generalised pool.

  • spin_conserving – If true, only include excitations which preserve spin.

  • generalised – If true, enumerate all index pairs instead of occupied → virtual.

  • antihermitized – If true, return T - T†; if false, plain excitation operators.

Returns:

The (operators, symbols) pair, in enumeration order.

qarp.operators.ucc.ucc_singles_and_doubles(onv: list[int] | None = None, n_spin_orbitals: int | None = None, *, spin_conserving: bool = True, generalised: bool = False, paired_doubles: bool = False, antihermitized: bool = True) → tuple[list[FermionOperator], list[Symbol]][source]

Generate UCC singles and doubles: the exact concatenation, singles first.

Parameters:

  • onv – Reference occupation-number vector (abab list); sets the dimension.

  • n_spin_orbitals – Dimension for the reference-free generalised pool.

  • spin_conserving – If true, only include excitations which preserve spin.

  • generalised – If true, pay no mind to occupations while generating.

  • paired_doubles – If true, doubles excite whole spatial orbitals.

  • antihermitized – If true, return T - T†; if false, plain excitation operators.

Returns:

The (operators, symbols) pair, singles then doubles in both lists.