## `eigenkit.reservoir.features`

Feature extractors: map a `(B, T, 2**n)` statevector trajectory to real features for a classical readout.

The headline extractor is expectation_features(), which measures arbitrary Pauli observables / Hamiltonians given as the library's `Observable` / `PauliExpr` types or a Hamiltonian string — so you get `$\langle\psi|H|\psi\rangle$` features without hand-rolling Pauli algebra. probability_features() and amplitude_features() read out the same trajectory differently.

All extractors are pure numpy and operate on the whole `(B, T)` grid at once.

### `amplitude_features(states)`

The raw statevector as real features: its real and imaginary parts, concatenated.

`states` is a complex array of shape `(B, T, 2**n)`, and the result is a real array of shape `(B, T, 2 * 2**n)`. It exposes the full state, which only a simulator can provide; it cannot be measured on hardware.

Parameters:

| Name     | Type      | Description                                              | Default    |
| -------- | --------- | -------------------------------------------------------- | ---------- |
| `states` | `ndarray` | The trajectory of statevectors, of shape (B, T, 2\*\*n). | *required* |

Returns:

| Type      | Description                                                    |
| --------- | -------------------------------------------------------------- |
| `ndarray` | The real and imaginary parts, concatenated, for each timestep. |

### `expectation_features(states, observables)`

Expectation values `⟨ψ|H_k|ψ⟩` of each observable, over the whole trajectory.

`states` is a complex array of shape `(B, T, 2**n)`, and the result is a real array of shape `(B, T, n_obs)`. `observables` can be an `Observable`, a `PauliExpr` or a Hamiltonian string, or a sequence of these. These are the same types that the rest of the library uses, so measuring an arbitrary Hamiltonian, as QRC experiments often require, needs no manual handling of Pauli terms. A single Hamiltonian string is one observable, and gives one feature.

Parameters:

| Name          | Type                   | Description                                              | Default    |
| ------------- | ---------------------- | -------------------------------------------------------- | ---------- |
| `states`      | `ndarray`              | The trajectory of statevectors, of shape (B, T, 2\*\*n). | *required* |
| `observables` | `Sequence[Observable]` | The observables to measure.                              | *required* |

Returns:

| Type      | Description                                  |
| --------- | -------------------------------------------- |
| `ndarray` | One feature per observable and per timestep. |

### `pauli_z_features(states)`

The expectation value `⟨Z_q⟩` on each qubit, the usual default readout in QRC.

`states` has shape `(B, T, 2**n)`, and the result has shape `(B, T, n)`. The values are computed with expectation_features(), so both functions share the same tested measurement code.

Parameters:

| Name     | Type      | Description                                              | Default    |
| -------- | --------- | -------------------------------------------------------- | ---------- |
| `states` | `ndarray` | The trajectory of statevectors, of shape (B, T, 2\*\*n). | *required* |

Returns:

| Type      | Description                             |
| --------- | --------------------------------------- |
| `ndarray` | One feature per qubit and per timestep. |

### `probability_features(states)`

The measurement distribution over all `2**n` basis states, `|ψ|²`.

`states` is a complex array of shape `(B, T, 2**n)`, and the result is a real array of the same shape.

Parameters:

| Name     | Type      | Description                                              | Default    |
| -------- | --------- | -------------------------------------------------------- | ---------- |
| `states` | `ndarray` | The trajectory of statevectors, of shape (B, T, 2\*\*n). | *required* |

Returns:

| Type      | Description                                                |
| --------- | ---------------------------------------------------------- |
| `ndarray` | The distribution over the basis states, for each timestep. |