ATOM LOSS Envelope matching · Beta Envelope MLE · Beta
Keep the loss.
Understand the result.
The measurement record, the decoder’s inputs, and the boundaries of the current implementation.
Two bits, different jobs
A lost atom has no measured value. Loss-visible records preserve that distinction with interleaved loss_flag,value_bit pairs.
0, value
The value bit is the measurement outcome.
1, placeholder
The value is a placeholder. Changing it must not change the decoder’s prediction.
Treating a lost value as an ordinary 0 or 1 can produce misleading detector parities.
Separate prediction from scoring
- Sample once. Export public records and private answers together; their manifests share a
dataset_id. - Decode public data. The decoder reads the circuit and loss-visible rows, without access to answers or hidden input masks.
- Score privately. Compare logical predictions with
answers.b8. Input masks are already accounted for; do not apply them again.
Choose a decoder
Envelope matching
Included in the default CLI. The tutorial uses envelope-matching.
Envelope MLE
envelope-mle requires the ilp feature or the official native archive. It solves a different objective and can take longer.
Each decoder has circuit acceptance limits. Enabling a solver does not extend support to arbitrary loss circuits.
Know the support boundary
Each envelope decoder has its own independently verified support level. Envelope matching is Beta unless publication verification succeeds for its declared Mid-SWAP scope, backed by its release evidence that is not published and verified yet. Envelope MLE is Beta unless publication verification succeeds; its declared scope is limited to four exact measured points — d=3/r=2 at loss 0.002 and d=3/r=1 at loss 0.01, each with batches 1,024 and 16,384 — backed by its separate release evidence that is not published and verified yet. It requires an ILP-capable build. The tutorial demonstrates a generated distance-3, two-round Mid-SWAP Z-memory circuit.
- There is no interpolation: every unlisted loss rate, batch size, distance, round count, and circuit family is outside the MLE Supported promise.
--shot-timeout-msbounds each MLE solve phase, not compilation or the whole batch; timeout produces diagnostics but no predictions.- Unsupported inputs can be rejected with
unsupported_circuit. A rejection is not a logical prediction. - The executable matrix and MLE scope plan record exactly which controls define each decoder’s domain; the conventional fixture is accepted by matching but excluded from MLE.
- When changing the layout, recompute logical-X support and regenerate both bundles.
- Keep failed and incomplete runs separate from successful error-rate results.
The repository also has a pinned d=5, r=15 Mid-SWAP MLE regression control; it does not widen the Supported scope. The excluded conventional circuit must fail before producing output files.
Support contract & regression commands →