Circuit definitions 0.1

Status: complete working draft for prototyping and collaborator review. Version 1 is reserved for the first reviewed public release.

This document defines the human meaning of schemas/circuit/0.1.schema.json. One record is one exact sampling circuit, its exact generated detector error model (DEM), the complete generation parameters, and the metadata needed to interpret both.

Revision identity and descriptions

There is no separate circuit-family record. A root revision has no predecessor; its ID is the lineage identity. Each later revision names its direct predecessor and histories are linear and acyclic. id always identifies one exact revision.

The root has a general description; a later revision may replace it or leave it null. A lineage page walks back from the current leaf to the newest non-null general description and shows it with the leaf's mandatory revision_description. The latter says what this exact revision introduced or changed.

Changing the circuit, DEM, realised priors, DEM-generation parameters, scientific tags, distance bounds, or noise model creates a new revision.

Noise model and exact priors

noise_model_id names the exact compact registry entry describing the noise construction. Whether that construction randomises priors is read from the noise-model record and is not copied here.

The numerical probabilities or weights actually used by this revision are the ones frozen in its sampling-circuit and DEM files. The noise-model entry is not a substitute for those bytes.

Code and experiment tags

code_tags classify the code construction represented by the revision. experiment_tags classify the circuit's scientific purpose or protocol. Both arrays contain stable slugs from their corresponding tag namespaces, are non-exclusive, and are non-empty on publication. Tag membership supports discovery; it does not select a result metric.

CSS and detector-basis classification

is_css says whether the represented circuit uses a CSS construction. dem_x_detectors_only says every detector represented in the DEM is classified as X-type; dem_z_detectors_only says every detector is classified as Z-type. Either detector-only claim implies is_css. For a non-empty detector set, both detector-only booleans cannot be true.

These values classify the exact represented circuit/DEM. They are not inferred from its name or code tag.

Distance bounds, rounds, and derived counts

code_distance_upper_bound and circuit_distance_upper_bound are explicitly upper bounds. They must not be presented or interpreted as exact distances. Null means no bound is declared. rounds is the declared round count where that quantity is meaningful and is otherwise null.

num_detectors, num_errors, and num_observables are respectively the detector count, the Stim DEM error-instruction count, and the logical-observable count. They are derived and verified from the frozen files rather than trusted as independent contributor claims.

Detector-error-model generation

stim_version is the exact Stim version used. The generation method is fixed to stim.Circuit.detector_error_model. Every supported argument to that method is stored explicitly, including when its default value was used:

• dem_decompose_errors;
• dem_flatten_loops;
• dem_allow_gauge_detectors;
• dem_approximate_disjoint_errors, a boolean;
• dem_ignore_decomposition_failures; and
• dem_block_decomposition_from_introducing_remnant_edges.

Together these fields identify how the uploaded DEM was made. A reader must not assume the defaults of their currently installed Stim version.

Frozen files and manifest

sampling_circuit_artifact contains the exact Stim sampling circuit. detector_error_model_artifact contains the exact generated DEM, including its realised priors. manifest_artifact is the canonical manifest naming the schema release, file hashes, noise-model ID, tags, generation parameters, distance bounds, and derived counts.

Each file descriptor identifies immutable content-addressed bytes by SHA-256, byte count, media type, and download URL. Stored bytes are never overwritten in place. The manifest and server verification must agree with the public record before publication.

Credits, links, and infrastructure

Credits are ordered and non-empty. A credit is either a display-name string or a registered account; equal strings on different records do not assert the same person. The uploader is separate from the credits. Links are optional classified provenance pointers and do not identify a frozen file.

schema, IDs, slug, lifecycle state, uploader, and timestamps are identity and infrastructure fields. There is deliberately no license field in this contract. Withdrawal preserves the immutable published revision and its audit trail.