## `eigenkit.chemistry.molecule`

Real-molecule Hamiltonians via PySCF + OpenFermion (the `chemistry` extra).

We use OpenFermion + openfermion-pyscf for the *classical* chemistry — molecular integrals and the fermionic Hamiltonian — and keep the quantum mapping ours: the returned `Molecule.fermion_operator` is our `FermionOperator`, ready for `jordan_wigner` (or `bravyi_kitaev`). The constant (nuclear repulsion + core energy) is included as the identity term, so `jordan_wigner`'s `offset` is the full energy shift and `min<H> + offset` is the total molecular energy.

Optional deps are imported lazily; install with `pip install eigenkit[chemistry]`.

### `Molecule`

A molecular Hamiltonian in second quantisation.

`fermion_operator` already includes the constant term (the nuclear repulsion), so `jordan_wigner(fermion_operator)` returns it as the offset. `hf_energy` and `fci_energy`, when computed, are the reference energies from PySCF, which are useful targets for the Variational Quantum Eigensolver (VQE).

Attributes:

| Name                | Type              | Description                                                                                                                                                         |
| ------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fermion_operator`  | `FermionOperator` | The Hamiltonian in second quantisation, including the constant term.                                                                                                |
| `n_qubits`          | `int`             | The number of qubits needed after the mapping, one per spin-orbital with Jordan-Wigner.                                                                             |
| `n_electrons`       | `int`             | The number of electrons, which sets the Hartree-Fock reference state and the excitations that a unitary coupled-cluster singles and doubles (UCCSD) ansatz can use. |
| `nuclear_repulsion` | `float`           | The constant nuclear term, in Hartree. It is already included in fermion_operator, and it is kept separately so that it can be reported.                            |
| `hf_energy`         | `float`           | The Hartree-Fock energy from PySCF, in Hartree. A VQE run should reach a lower energy.                                                                              |
| `fci_energy`        | \`float           | None\`                                                                                                                                                              |

### `hydrogen_molecule(bond_length=0.7414, *, basis='sto-3g', run_fci=False)`

The hydrogen molecule `H₂` at the given bond length, in angstroms.

In the minimal STO-3G basis set, this is the standard 4-qubit benchmark for VQE. Its FCI ground-state energy is about `-1.137` Hartree at equilibrium.

Parameters:

| Name          | Type    | Description                                                                                   | Default    |
| ------------- | ------- | --------------------------------------------------------------------------------------------- | ---------- |
| `bond_length` | `float` | The distance between the nuclei, in angstroms. The default, 0.7414, is close to equilibrium.  | `0.7414`   |
| `basis`       | `str`   | The name of the PySCF basis set.                                                              | `'sto-3g'` |
| `run_fci`     | `bool`  | Whether to also compute the exact FCI energy, the target against which a VQE run is measured. | `False`    |

Returns:

| Type       | Description                                                |
| ---------- | ---------------------------------------------------------- |
| `Molecule` | The molecule, with its Hamiltonian and reference energies. |

### `molecular_hamiltonian(geometry, *, basis='sto-3g', charge=0, multiplicity=1, run_fci=False)`

Build a `Molecule` from a geometry, with PySCF and OpenFermion.

Parameters:

| Name           | Type                                           | Description                                                                                                                                                                        | Default    |
| -------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `geometry`     | `list[tuple[str, tuple[float, float, float]]]` | A list of (element, (x, y, z)) entries, with the coordinates in angstroms.                                                                                                         | *required* |
| `basis`        | `str`                                          | The name of the PySCF basis set. The default is the minimal basis set "sto-3g".                                                                                                    | `'sto-3g'` |
| `charge`       | `int`                                          | The total charge of the molecule.                                                                                                                                                  | `0`        |
| `multiplicity` | `int`                                          | The spin multiplicity, 2S + 1.                                                                                                                                                     | `1`        |
| `run_fci`      | `bool`                                         | Whether to also compute the FCI energy, which is exact in this basis set and a useful target for VQE. It needs an exact diagonalisation, so it is only possible for small systems. | `False`    |

Returns:

| Type       | Description                                                |
| ---------- | ---------------------------------------------------------- |
| `Molecule` | The Molecule, with its Hamiltonian and reference energies. |