Weights and unitary fitting

Applicable version · ArcQML 0.1.0

On this page

Weight checkpoint file contract

save_weights writes formatted JSON with fixed format arcqml/weights. Each parameter records name, dtype, and value; records are sorted by name for stable ordering of identical states. Only Circuit Parameter objects with numel=1 and dtype F32/F64 can be written.

json

{
  "format": "arcqml/weights",
  "num_qubits": 2,
  "parameters": [
    {"name": "ry_q0_theta_0", "dtype": "f64", "value": 0.36154268969437336}
  ]
}

load_weights first validates format, qubit count, parameter-name set, duplicate names, dtype, and finite value s parsed from JSON, and prepares replacement tensors. It then writes parameters and clears gradients. It does not compare gate topology, so the caller must reconstruct the expected isomorphic Circuit.

DenseUnitary data contract

DenseUnitary stores num_qubits, dimension, and row-major C64 data. The dimension must be a power of 2; public data is indexed by output basis index first, then input index. DenseUnitary::from_tensor checks only C64, a two-dimensional square shape, length after contiguous copying, and finiteness. Public unitary_from_tensor additionally validates unitarity using these default tolerances:

\varepsilon_{\mathrm{unitary}}=10^{-10}.

unitary_from_circuit executes the Circuit on an internal batch of all computational basis initial states, then transposes to the public row-major layout. For n qubits, space complexity is:

O(4^n).

One matrix copy occupies about 16 × 4^n bytes, and internal computation needs additional buffers. This feature therefore suits small-scale circuit comparison and synthesis.

Unitary fidelity, loss, and analytical gradients

The trace overlap, full-unitary fidelity, and loss for a target unitary and the current circuit unitary are:

\begin{aligned} s&=\operatorname{Tr}\!\left(U_{\mathrm{target}}^{\dagger}U(\boldsymbol{\theta})\right),\\ F_U&=\operatorname{clamp}\!\left(\frac{\lvert s\rvert^2}{d^2},0,1\right),\\ L_U&=1-F_U. \end{aligned}

Unlike the pure-state method in State analysis and sampling (fidelity), this explicitly clamps to the interval from 0 to 1 to contain out-of-range rounding errors.

unitary_loss returns an F64 scalar compatible with the shared autograd system. Its backward pass restores the forward StateBatch in reverse order, accumulates parameter gradients from the analytical unclamped objective, and multiplies by the outer scalar upstream gradient:

\frac{\partial L_U}{\partial p} =-\frac{2}{d^2} \operatorname{Re}\!\left( s^*\frac{\partial s}{\partial p} \right).

The gradient implementation does not additionally zero gradients outside the forward clamping interval. For exact unitaries, unclamped fidelity is theoretically at most 1. Using a DenseUnitary target without validating unitarity may produce a clamped loss inconsistent with this gradient. unitary_loss itself checks only qubit-count compatibility with the circuit. Validate targets with unitary_from_tensor or explicit validate. Small rounding excursions must still be interpreted according to these implementation semantics.

Download complete Markdown manual ↓