## `eigenkit.orthogonal.matrix`

The orthogonal matrix of a network of RBS gates, in NumPy.

On the two states `$|01\rangle$` and `$|10\rangle$` of its wires `$(i, j)$`, an RBS gate acts as the Givens rotation (Cherrat et al., Eq. 1)

```math
\mathrm{RBS}(\theta) =
\begin{pmatrix} \cos\theta & \sin\theta \\ -\sin\theta & \cos\theta \end{pmatrix}
```

Restricted to the unary basis, where exactly one wire is 1, a network of RBS gates is therefore the orthogonal matrix `$W(\theta)$` built here: the amplitude of `$e_r$` after the circuit, started in `$e_c$`, is `$W_{rc}$`.

Example

```python
import numpy as np

from eigenkit.orthogonal import butterfly, orthogonal_matrix

t = butterfly(8)
W = orthogonal_matrix(t, np.random.default_rng(0).normal(size=t.n_angles))
np.allclose(W.T @ W, np.eye(8))  # True
```

### `identity_angles(topology)`

The angles that give the identity matrix: all zeros.

Parameters:

| Name       | Type       | Description | Default    |
| ---------- | ---------- | ----------- | ---------- |
| `topology` | `Topology` | The layout. | *required* |

Returns:

| Type      | Description                                                |
| --------- | ---------------------------------------------------------- |
| `ndarray` | np.ndarray: A float64 array of shape (topology.n_angles,). |

### `orthogonal_matrix(topology, theta)`

Build the `$n \times n$` orthogonal matrix of a network of RBS gates.

Numerical contract: starting from `W = eye(n)`, each layer, in order, takes the next `k` angles (`k` = the number of pairs in the layer), with `c = cos(θ)[:, None]` and `s = sin(θ)[:, None]`, and replaces the rows `W[i] <- c*W[i] + s*W[j]` and `W[j] <- -s*W[i] + c*W[j]` for all its pairs at once, from the rows before the update. With `reflection=True` the last row is negated at the end. These are the operations, in this order, of the torch module of the same topology, so both give the same matrix.

The cost is `$O(\mathrm{depth} \cdot n^2)$`.

Parameters:

| Name       | Type           | Description                                                                                                                                             | Default    |
| ---------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `topology` | `Topology`     | The layout.                                                                                                                                             | *required* |
| `theta`    | `array - like` | The angles, of shape (topology.n_angles,), in the order of topology.pairs(). A float32 array gives a float32 matrix, and any other input a float64 one. | *required* |

Returns:

| Type      | Description                                         |
| --------- | --------------------------------------------------- |
| `ndarray` | np.ndarray: The orthogonal matrix, of shape (n, n). |

Raises:

| Type         | Description                                 |
| ------------ | ------------------------------------------- |
| `ValueError` | If theta has the wrong shape or is complex. |

### `orthogonal_matrix_jacobian(topology, theta)`

The derivative of `orthogonal_matrix` with respect to each angle.

It is exact: the derivative of one RBS gate is spliced between the product of the layers before it and the product of the layers after it. The cost is `$O(n_{\mathrm{angles}} \, n^2 + \mathrm{depth} \cdot n^3)$`.

Parameters:

| Name       | Type           | Description                                | Default    |
| ---------- | -------------- | ------------------------------------------ | ---------- |
| `topology` | `Topology`     | The layout.                                | *required* |
| `theta`    | `array - like` | The angles, of shape (topology.n_angles,). | *required* |

Returns:

| Type      | Description                                                          |
| --------- | -------------------------------------------------------------------- |
| `ndarray` | np.ndarray: A float64 array of shape (n_angles, n, n), where entry k |
| `ndarray` | is (\\partial W / \\partial \\theta_k).                              |

Raises:

| Type         | Description                                 |
| ------------ | ------------------------------------------- |
| `ValueError` | If theta has the wrong shape or is complex. |
