## `eigenkit.chemistry.mappings`

Fermion-to-qubit mappings: build a qubit `Observable` from a `FermionOperator`.

Jordan-Wigner convention (OpenFermion-compatible):

```math
a_j = \Big(\prod_{k<j} Z_k\Big)\,\frac{X_j + i Y_j}{2}
\qquad
a_j^\dagger = \Big(\prod_{k<j} Z_k\Big)\,\frac{X_j - i Y_j}{2}
```

so the number operator maps to `$a_j^\dagger a_j = (I - Z_j)/2$`, with an occupied orbital being qubit `$|1\rangle$`. The parity string `$\prod_{k<j} Z_k$` is what enforces fermionic antisymmetry.

`jordan_wigner` returns `(Observable, offset)`: the constant (identity) term is returned separately as `offset` because the Pauli backends reject identity-only terms, and a variational solver adds it back to `<H>`.

### `bravyi_kitaev(operator, n_qubits=None)`

Map a `FermionOperator` to qubits with the Bravyi-Kitaev transformation.

The transformation itself is done by OpenFermion (the `chemistry` extra), and the result is converted to an eigenkit `Observable`. The Jordan-Wigner mapping, in contrast, is implemented in eigenkit. `n_qubits` defaults to the largest mode index plus one.

Parameters:

| Name       | Type              | Description                    | Default    |
| ---------- | ----------------- | ------------------------------ | ---------- |
| `operator` | `FermionOperator` | The fermionic operator to map. | *required* |
| `n_qubits` | `int`             | The number of qubits.          | `None`     |

Returns:

| Name         | Type         | Description                                                                  |
| ------------ | ------------ | ---------------------------------------------------------------------------- |
| `observable` | `Observable` | The operator on qubits, without its identity part.                           |
| `offset`     | `float`      | The coefficient of the identity part, which the Observable does not contain. |

### `jordan_wigner(operator, *, atol=1e-10)`

Map a `FermionOperator` to qubits with the Jordan-Wigner transformation.

The operator must be Hermitian, as a Hamiltonian is. If a resulting coefficient is not real, a `ValueError` is raised.

Parameters:

| Name       | Type              | Description                                                                  | Default    |
| ---------- | ----------------- | ---------------------------------------------------------------------------- | ---------- |
| `operator` | `FermionOperator` | The fermionic operator to map.                                               | *required* |
| `atol`     | `float`           | Terms whose coefficient is smaller than this value in magnitude are dropped. | `1e-10`    |

Returns:

| Name         | Type         | Description                                                                  |
| ------------ | ------------ | ---------------------------------------------------------------------------- |
| `observable` | `Observable` | The operator on qubits, without its identity part.                           |
| `offset`     | `float`      | The coefficient of the identity part, which the Observable does not contain. |