## `eigenkit.chemistry.ansatz`

Ansatz building blocks for chemistry circuits: Hartree-Fock reference-state preparation and the UCCSD ansatz.

### `apply_hartree_fock(circuit, n_electrons)`

Prepare the Hartree-Fock reference state on an existing builder.

It applies an `X` gate to each of the lowest `n_electrons` spin-orbitals, which marks them as occupied (`|1⟩`).

The convention is the one of the Jordan-Wigner mapping: mode `j` is qubit `j`, and the spin-orbitals are ordered so that the lowest `n_electrons` of them are occupied in the reference state, for example `|1…1 0…0⟩`.

Parameters:

| Name          | Type             | Description                                                           | Default    |
| ------------- | ---------------- | --------------------------------------------------------------------- | ---------- |
| `circuit`     | `CircuitBuilder` | The builder to add the gates to.                                      | *required* |
| `n_electrons` | `int`            | The number of electrons, which sets the Hartree-Fock reference state. | *required* |

Returns:

| Type             | Description                                     |
| ---------------- | ----------------------------------------------- |
| `CircuitBuilder` | The same builder, so that calls can be chained. |

### `hartree_fock_state(n_qubits, n_electrons)`

A circuit that prepares the Hartree-Fock reference state.

The state is `|1…1 0…0⟩` on `n_qubits` qubits, with `n_electrons` occupied spin-orbitals.

Parameters:

| Name          | Type  | Description                                                           | Default    |
| ------------- | ----- | --------------------------------------------------------------------- | ---------- |
| `n_qubits`    | `int` | The number of qubits.                                                 | *required* |
| `n_electrons` | `int` | The number of electrons, which sets the Hartree-Fock reference state. | *required* |

Returns:

| Type          | Description                                              |
| ------------- | -------------------------------------------------------- |
| `CircuitSpec` | The circuit, as a CircuitSpec with no trainable weights. |

### `uccsd_ansatz(n_qubits, n_electrons, reps=1)`

The UCCSD ansatz on the Hartree-Fock reference, with a Trotter approximation.

UCCSD is the unitary coupled-cluster ansatz with single and double excitations. The circuit prepares `(∏_k exp(θ_k (T_k − T_k†)))^reps |HF⟩`, where `|HF⟩` is the Hartree-Fock state.

Each generator `G = T − T†` is anti-Hermitian. The Jordan-Wigner mapping turns `H = −iG` into a Hermitian qubit operator, and `exp(θG) = exp(iθH)` is then a product of `pauli_exponential` gates. The Pauli terms of one generator commute, so that product is exact. The product over different generators is a first-order Trotter approximation. `reps` repeats the whole sequence with independent weights, which reduces the Trotter error: more repetitions bring the circuit closer to the exact UCCSD unitary. The ansatz has `reps * n_excitations` weights in total.

Parameters:

| Name          | Type  | Description                                                                                  | Default    |
| ------------- | ----- | -------------------------------------------------------------------------------------------- | ---------- |
| `n_qubits`    | `int` | The number of qubits, one per spin-orbital.                                                  | *required* |
| `n_electrons` | `int` | The number of electrons, which sets the Hartree-Fock reference and the possible excitations. | *required* |
| `reps`        | `int` | The number of Trotter repetitions of the product of excitations. The default is 1.           | `1`        |

Returns:

| Type          | Description                                                                             |
| ------------- | --------------------------------------------------------------------------------------- |
| `CircuitSpec` | The ansatz as a CircuitSpec, with one trainable angle per generator and per repetition. |

### `uccsd_excitation_generators(n_qubits, n_electrons)`

The excitation generators `T - T†` of the UCCSD ansatz.

UCCSD is the unitary coupled-cluster ansatz with single and double excitations. The excitations go from the occupied spin-orbitals (the lowest `n_electrons`) to the unoccupied ones. Single and double excitations are taken over all choices of occupied and unoccupied indices, with no restriction from spin symmetry, which keeps the construction simple and correct. A variant restricted by spin symmetry, which would have fewer parameters, is not implemented.

Parameters:

| Name          | Type  | Description                                                           | Default    |
| ------------- | ----- | --------------------------------------------------------------------- | ---------- |
| `n_qubits`    | `int` | The number of qubits.                                                 | *required* |
| `n_electrons` | `int` | The number of electrons, which sets the Hartree-Fock reference state. | *required* |

Returns:

| Type                    | Description                                           |
| ----------------------- | ----------------------------------------------------- |
| `list[FermionOperator]` | The generators, as a list of FermionOperator objects. |