## `eigenkit.torch.layers.orthogonal_qnn`

The orthogonal quantum layer: a unary loader, a network of RBS gates, and the unary readout.

The layer loads each input vector `$x$` into the unary basis, applies an orthogonal network `$W(\theta)$` of RBS gates, and returns the probability of each wire, `$(Wx)_i^2 / \lVert x \rVert^2$`. Its circuit is the one of `eigenkit.orthogonal.to_circuit`, with trainable angles. See `eigenkit.orthogonal` for the layouts and the matrix form.

### `OrthogonalQNN`

Bases: `Module`

A quantum orthogonal layer: `$x \mapsto (Wx)^2 / \lVert x \rVert^2$` on `n_qubits` wires.

A `UnaryLoader` loads `$x / \lVert x \rVert$` with `$n - 1$` RBS gates, for `$n$` = `n_qubits`, whose angles are computed from `$x$`; an `RBSNetwork` applies the orthogonal matrix `$W(\theta)$` of `topology`; and the `Z` observable of each wire gives the probability `$p_i = (1 - \langle Z_i \rangle) / 2$`. The outputs of a row sum to 1.

The output values come from the circuit, and so does the gradient with respect to the angles. The gradient with respect to the input is the exact derivative of `$(Wx)^2 / \lVert x \rVert^2$`, with `$W$` built from the current angles: the loader angles are not differentiable where `$x$` has zeros (after a ReLU, or a one-hot input), while the output is. On a noiseless simulator the two agree; on noisy hardware the input gradient is that of the ideal circuit.

A row that is all zeros has no direction to load, so `$(Wx)^2 / \lVert x \rVert^2$` is not defined for it. Such a row, which a ReLU in front of the layer can produce, gives the uniform distribution `$1/n$` on every wire, and no gradient flows back to it. The other rows of the batch are not affected.

The circuit simulates `$2^n$` amplitudes, so the layer is practical up to about 20 qubits. The matrix form, `eigenkit.orthogonal.torch.Orthogonal`, computes the same `$W$` classically at any width.

Parameters:

| Name       | Type           | Description                                                                                                                                             | Default                                                                                                                          |
| ---------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `n_qubits` | `int`          | The number of wires, which is the number of input features and of outputs.                                                                              | *required*                                                                                                                       |
| `topology` | \`TopologyName | Topology\`                                                                                                                                              | The layout of the network: a name ("butterfly", "pyramid", "x", "diagonal") or a Topology on n_qubits wires. Default: "pyramid". |
| `loader`   | `LoaderLayout` | The layout of the loader: "diagonal" (any width, adjacent wires), "semi_diagonal" (even width) or "parallel" (power-of-two width). Default: "diagonal". | `'diagonal'`                                                                                                                     |
| `init`     | `str`          | "random" for standard normal angles, "identity" for zero angles, which make W the identity. Default: "random".                                          | `'random'`                                                                                                                       |
| `provider` | `ProviderSpec` | The backend that runs the circuit. Default: "numpy".                                                                                                    | `'numpy'`                                                                                                                        |

Example

```python
import torch
from eigenkit import OrthogonalQNN

layer = OrthogonalQNN(n_qubits=4, topology="pyramid")
out = layer(torch.randn(8, 4))  # shape (8, 4), each row sums to 1
```

#### `provider`

The backend that the circuit of this layer was compiled for.

Returns:

| Name       | Type       | Description                           |
| ---------- | ---------- | ------------------------------------- |
| `provider` | `Provider` | The backend that the circuit runs on. |

#### `forward(x)`

Run the layer.

Parameters:

| Name | Type     | Description                                                                                                                  | Default    |
| ---- | -------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `x`  | `Tensor` | One input (n_qubits,) or a batch (batch, n_qubits). A row of zeros gives the uniform distribution (see the class docstring). | *required* |

Returns:

| Name  | Type     | Description                                                             |
| ----- | -------- | ----------------------------------------------------------------------- |
| `out` | `Tensor` | The probabilities ((Wx)\_i^2 / \\lVert x \\rVert^2), of the shape of x. |

#### `reset_parameters()`

Initialise the angles again by the rule of `init`.

`init="random"` draws new standard normal angles from the global generator (`circuit.reset_parameters()`); `init="identity"` sets them to zero, so the layer starts at `W = I` again.

The estimators call `reset_parameters` on every module through `model.apply`, which resets `circuit` first and then this layer. With `init="random"` the angles are therefore drawn twice, and the second draw is kept: the result still depends only on the seed, and the generator moves on by `2 * n_angles` numbers rather than `n_angles`.
