Reference

Query kinds

snapshot returns amplitudes (State) or a refusal (other engines) unless options.allowWeaveState is set and the width fits, in which case the router runs State. probability returns one real number for a full bitstring or a marginal mask. shots returns counts. expectation returns one real number for a Pauli sum. reduced returns a density on the kept wires, via State partial trace or Drift partial trace. Weave serves reduced only when the open-index forecast fits.

preview=true returns the forecast and the chosen engine and does not run. It is free of shot quota and still consumes a small planning quota.

Pauli multiplication

On one wire, XI = X, IX = X, XX = I, YY = I, ZZ = I, XY = iZ, YX = −iZ, YZ = iX, ZY = −iX, ZX = iY, XZ = −iY, with phases multiplied into the string’s global phase. Across wires, letters multiply componentwise. The all-identity string on |0…0⟩ has expectation 1. Any string with an X or Y on any wire has expectation 0 on |0…0⟩. Z on a wire prepared in |0⟩ contributes +1.

CX conjugation, control c and target t: X_c stays X_c X_t, X_t stays X_t, Z_t stays Z_c Z_t, Z_c stays Z_c. Y follows from Y = iXZ up to the phase convention above. This table is the one Trace and the tests share.

Error codes

lumen.state.index_convention — bit order does not match wire 0 as the least significant bit. lumen.state.byte_ceiling — amplitude buffer exceeds the key. lumen.weave.memory_ceiling — sliced plan still too large. lumen.weave.truncated — approximate result; also returned as a status on HTTP 200 when the caller allowed truncation. lumen.drift.not_cptp — Kraus list is not trace preserving. lumen.trace.string_cap — live Pauli list exceeded the cap. lumen.trace.no_sample — shots requested from Trace. lumen.router.unpin — pinned engine cannot run. lumen.auth.quota — daily ceiling.

HTTP 200 with status exact or approximate means a result is present. HTTP 409 means a refusal with no result. HTTP 401 means the API key is missing or outside Lumen scope.

• Version field lumen.contract = 1.0 on every response.
• Unknown gate names return 400 before planning.
• Angles are radians.

Versioning

1.0 freezes the index convention, the channel families, the Pauli table, and the error codes on this page. New query kinds will arrive under a new contract version, not as silent fields. Documents on data-t.uk are the source the version names.