RustQEC 0.3 · Development

Reference boundary

Use rstim capabilities --format json to inspect your installed commands and optional decoders. If your binary differs from this documentation, its command help and capabilities describe the available interfaces.

The generated reference includes the optional qasm feature. Enable it in a development build for circuit import-qasm, circuit export-qasm and semantic-document sampling. See the OpenQASM 2.0 guide for examples and supported-profile limits.

All command help

The structured circuit and dataset interfaces use hyphenated options; direct interfaces may use underscores. Use the spelling listed for the command you run. Optional features can change available decoder choices.

rstim
Circuit simulation and quantum error correction tools

Usage: rstim [OPTIONS] [COMMAND]

Commands:
  stats                   Summarize circuit structure and counts
  sample                  Sample measurement results from a circuit
  detect                  Sample detection events and observable flips from a circuit
  analyze_errors          Convert a circuit into a detector error model
  gen                     Generate a common QEC circuit
  convert                 Convert shot data between output formats
  m2d                     Convert measurement results to detection events
  explain_errors          Explain which errors could have caused observed detection events
  sample_dem              Sample detection events from a detector error model
  export_json             Export a circuit as QP101 JSON
  render_svg              Render a circuit as SVG through QP101
  shot_viewer             Open the interactive local-file shot viewer on loopback
  export_decoder_dataset  Export a public decoder dataset and private answer bundle
  pack_samples            Pack measurement samples into an RSMP archive
  unpack_samples          Unpack an RSMP archive into result sample streams
  surface-code-ler        Sample, decode, and plot a surface-code logical error rate curve
  perf                    Run performance evidence workflows
  help                    Print this message or the help of the given subcommand(s)

Options:
      --benchmark-telemetry-json <BENCHMARK_TELEMETRY_JSON>  
  -h, --help                                                 Print help
  -V, --version                                              Print version

Additional command groups:
  circuit       Structured circuit operations
  dataset       Import, export and score decoder datasets
  decode        Decode a detector dataset
  capabilities  Print the machine-readable CLI contract
rstim stats
Summarize circuit structure and counts

Usage: rstim stats [OPTIONS]

Options:
      --benchmark-telemetry-json <BENCHMARK_TELEMETRY_JSON>  
      --in <IN>                                              
      --out <OUT>                                            
      --json                                                 
  -h, --help                                                 Print help
rstim sample
Sample measurement results from a circuit

Usage: rstim sample [OPTIONS]

Options:
      --benchmark-telemetry-json <BENCHMARK_TELEMETRY_JSON>  
      --shots <SHOTS>                                        
      --out_format <OUT_FORMAT>                              [default: 01]
      --in <IN>                                              
      --out <OUT>                                            
      --seed <SEED>                                          
      --skip_reference_sample                                
  -h, --help                                                 Print help
rstim detect
Sample detection events and observable flips from a circuit

Usage: rstim detect [OPTIONS]

Options:
      --benchmark-telemetry-json <BENCHMARK_TELEMETRY_JSON>
          
      --shots <SHOTS>
          
      --out_format <OUT_FORMAT>
          [default: 01]
      --in <IN>
          
      --out <OUT>
          
      --seed <SEED>
          
      --append_observables
          
      --obs_out <OBS_OUT>
          
      --obs_out_format <OBS_OUT_FORMAT>
          [default: 01]
      --trace_out <TRACE_OUT>
          Write a versioned manifest and one detailed JSON record per shot
  -h, --help
          Print help
rstim analyze_errors
Convert a circuit into a detector error model

Usage: rstim analyze_errors [OPTIONS]

Options:
      --benchmark-telemetry-json <BENCHMARK_TELEMETRY_JSON>  
      --in <IN>                                              
      --out <OUT>                                            
      --approximate_disjoint_errors                          
      --allow_gauge_detectors                                
      --decompose_errors                                     
  -h, --help                                                 Print help
rstim gen
Generate a common QEC circuit

Usage: rstim gen [OPTIONS] --code <CODE> --task <TASK> --rounds <ROUNDS>

Options:
      --benchmark-telemetry-json <BENCHMARK_TELEMETRY_JSON>
          
      --code <CODE>
          
      --task <TASK>
          
      --distance <DISTANCE>
          
      --rounds <ROUNDS>
          
      --after_clifford_depolarization <NOISE>
          [default: 0]
      --before_round_data_depolarization <BEFORE_ROUND_DATA_DEPOLARIZATION>
          Depolarization applied to data qubits at the start of each round [default: 0]
      --before_round_data_loss_probability <BEFORE_ROUND_DATA_LOSS_PROBABILITY>
          Atom loss applied to data qubits at the start of each Mid-SWAP round [default: 0] [alias: --before_round_data_loss]
      --before_measure_flip_probability <BEFORE_MEASURE_FLIP_PROBABILITY>
          Bit-flip probability applied immediately before each measurement [default: 0]
      --after_reset_flip_probability <AFTER_RESET_FLIP_PROBABILITY>
          Bit-flip probability applied immediately after each reset [default: 0]
      --after_clifford_loss_probability <AFTER_CLIFFORD_LOSS_PROBABILITY>
          [default: 0]
      --operation_loss_probability <OPERATION_LOSS_PROBABILITY>
          Operation-loss probability for gates and resets in Mid-SWAP circuits [default: 0]
      --measurement_loss_probability <MEASUREMENT_LOSS_PROBABILITY>
          Atom-loss probability immediately before a Mid-SWAP measurement [default: 0]
      --hx <HX>
          
      --hz <HZ>
          
      --basis <BASIS>
          
      --schedule <SCHEDULE>
          [default: greedy]
      --observables <OBSERVABLES>
          
      --out <OUT>
          
  -h, --help
          Print help
rstim convert
Convert shot data between output formats

Usage: rstim convert [OPTIONS]

Options:
      --benchmark-telemetry-json <BENCHMARK_TELEMETRY_JSON>  
      --in_format <IN_FORMAT>                                [default: 01]
      --out_format <OUT_FORMAT>                              [default: 01]
      --bits <BITS>                                          
      --circuit <CIRCUIT>                                    
      --in <IN>                                              
      --out <OUT>                                            
      --shots <SHOTS>                                        
  -h, --help                                                 Print help
rstim m2d
Convert measurement results to detection events

Usage: rstim m2d [OPTIONS]

Options:
      --benchmark-telemetry-json <BENCHMARK_TELEMETRY_JSON>  
      --in_format <IN_FORMAT>                                [default: 01]
      --out_format <OUT_FORMAT>                              [default: dets]
      --circuit <CIRCUIT>                                    
      --in <IN>                                              
      --out <OUT>                                            
      --append_observables                                   
      --skip_reference_sample                                
      --sweep <SWEEP>                                        
      --sweep_format <SWEEP_FORMAT>                          [default: 01]
      --ran_without_feedback                                 
      --shots <SHOTS>                                        
  -h, --help                                                 Print help
rstim explain_errors
Explain which errors could have caused observed detection events

Usage: rstim explain_errors [OPTIONS]

Options:
      --benchmark-telemetry-json <BENCHMARK_TELEMETRY_JSON>  
      --in <IN>                                              
      --in_format <IN_FORMAT>                                [default: dets]
      --circuit <CIRCUIT>                                    
      --dem <DEM>                                            
      --out <OUT>                                            
  -h, --help                                                 Print help
rstim sample_dem
Sample detection events from a detector error model

Usage: rstim sample_dem [OPTIONS]

Options:
      --benchmark-telemetry-json <BENCHMARK_TELEMETRY_JSON>  
      --shots <SHOTS>                                        
      --out_format <OUT_FORMAT>                              [default: 01]
      --in <IN>                                              
      --out <OUT>                                            
      --seed <SEED>                                          
      --obs_out <OBS_OUT>                                    
      --obs_out_format <OBS_OUT_FORMAT>                      [default: 01]
  -h, --help                                                 Print help
rstim export_json
Export a circuit as QP101 JSON

Usage: rstim export_json [OPTIONS]

Options:
      --benchmark-telemetry-json <BENCHMARK_TELEMETRY_JSON>  
      --in <IN>                                              
      --out <OUT>                                            
      --format <FORMAT>                                      [default: pretty]
      --highlight_dem_error <HIGHLIGHT_DEM_ERROR>            
      --sample_shot                                          
      --seed <SEED>                                          
  -h, --help                                                 Print help
rstim render_svg
Render a circuit as SVG through QP101

Usage: rstim render_svg [OPTIONS]

Options:
      --benchmark-telemetry-json <BENCHMARK_TELEMETRY_JSON>  
      --in <IN>                                              
      --out <OUT>                                            
      --highlight_dem_error <HIGHLIGHT_DEM_ERROR>            
      --sample_shot                                          
      --seed <SEED>                                          
  -h, --help                                                 Print help
rstim shot_viewer
Open the interactive local-file shot viewer on loopback

Usage: rstim shot_viewer [OPTIONS]

Options:
      --benchmark-telemetry-json <BENCHMARK_TELEMETRY_JSON>  
      --port <PORT>                                          [default: 0]
      --no_open                                              
  -h, --help                                                 Print help
rstim export_decoder_dataset
Export a public decoder dataset and private answer bundle

Usage: rstim export_decoder_dataset [OPTIONS] --circuit <CIRCUIT> --shots <SHOTS> --public_out <PUBLIC_OUT> --private_out <PRIVATE_OUT>

Options:
      --benchmark-telemetry-json <BENCHMARK_TELEMETRY_JSON>
          
      --circuit <CIRCUIT>
          
      --shots <SHOTS>
          
      --batch_shots <BATCH_SHOTS>
          [default: 10000]
      --mode <MODE>
          Auto selects blinded measurements when logical-input metadata is available [default: auto]
      --logical_x_qubits <LOGICAL_X_QUBITS>
          
      --logical_z_qubits <LOGICAL_Z_QUBITS>
          
      --public_out <PUBLIC_OUT>
          
      --private_out <PRIVATE_OUT>
          
      --seed <SEED>
          
      --error_trace
          Also write a per-shot rstim.error-trace.v1 trace.jsonl into the private bundle
  -h, --help
          Print help
rstim pack_samples
Pack measurement samples into an RSMP archive

Usage: rstim pack_samples [OPTIONS] --circuit <CIRCUIT> --shots <SHOTS> --in <IN> --out <OUT>

Options:
      --benchmark-telemetry-json <BENCHMARK_TELEMETRY_JSON>  
      --circuit <CIRCUIT>                                    
      --shots <SHOTS>                                        
      --in <IN>                                              
      --in_format <IN_FORMAT>                                [default: b8]
      --out <OUT>                                            
  -h, --help                                                 Print help
rstim unpack_samples
Unpack an RSMP archive into result sample streams

Usage: rstim unpack_samples [OPTIONS] --circuit <CIRCUIT> --in <IN>

Options:
      --benchmark-telemetry-json <BENCHMARK_TELEMETRY_JSON>  
      --circuit <CIRCUIT>                                    
      --in <IN>                                              
      --measurements_out <MEASUREMENTS_OUT>                  
      --measurements_out_format <MEASUREMENTS_OUT_FORMAT>    [default: b8]
      --detectors_out <DETECTORS_OUT>                        
      --detectors_out_format <DETECTORS_OUT_FORMAT>          [default: b8]
      --obs_out <OBS_OUT>                                    
      --obs_out_format <OBS_OUT_FORMAT>                      [default: b8]
      --verify_only                                          
  -h, --help                                                 Print help
rstim surface-code-ler
Sample, decode, and plot a surface-code logical error rate curve

Usage: rstim surface-code-ler [OPTIONS] --distances <DISTANCES> --rounds <ROUNDS> --physical-error-rates <PHYSICAL_ERROR_RATES>

Options:
      --benchmark-telemetry-json <BENCHMARK_TELEMETRY_JSON>
          
      --distances <DISTANCES>
          Increasing code distances, comma-separated
      --rounds <ROUNDS>
          Measurement rounds paired with distances, comma-separated
      --physical-error-rates <PHYSICAL_ERROR_RATES>
          Increasing physical error probabilities, comma-separated
      --shots <SHOTS>
          [default: 2000]
      --seed <SEED>
          [default: 86]
      --out-dir <OUT_DIR>
          [default: .]
  -h, --help
          Print help
rstim perf
Run performance evidence workflows

Usage: rstim perf [OPTIONS] <COMMAND>

Commands:
  run        Emit raw benchmark JSONL
  summarize  Aggregate raw JSONL into summary JSON
  gate       Evaluate summary JSON and return non-zero on gate failure
  report     Render summary JSON as Markdown
  ci         Run the full perf pipeline and write raw / summary / report artifacts
  help       Print this message or the help of the given subcommand(s)

Options:
      --benchmark-telemetry-json <BENCHMARK_TELEMETRY_JSON>  
  -h, --help                                                 Print help
rstim circuit
Inspect and operate on Stim-like circuits

Usage: rstim circuit [OPTIONS] <COMMAND>

Commands:
  import-qasm  Import checked OpenQASM 2.0 into a semantic document or Stim projection
  export-qasm  Export supported native or semantic circuits as OpenQASM 2.0
  stats        Summarize circuit structure and counts
  gen          Generate a built-in QEC circuit (common families and Mid-SWAP)
  sample       Sample measurement results from a circuit
  detect       Sample detection events and observable flips from a circuit
  dem          Convert a circuit into a detector error model
  decode       Decode detector rows from a DEM with a selected decoder
  help         Print this message or the help of the given subcommand(s)

Options:
      --error-format <ERROR_FORMAT>  Select the error channel independently of command output [possible values: human, json]
  -h, --help                         Print help
rstim dataset
Produce decoder-ready datasets

Usage: rstim dataset [OPTIONS] <COMMAND>

Commands:
  score   Score observable predictions against the private answer bundle
  export  Export a public decoder dataset and private answer bundle
  import  Package a third-party circuit and shot payload into a public dataset
  help    Print this message or the help of the given subcommand(s)

Options:
      --error-format <ERROR_FORMAT>  Select the error channel independently of command output [possible values: human, json]
  -h, --help                         Print help
rstim decode
Decode a public loss-visible decoder dataset

Usage: rstim decode [OPTIONS] --decoder <DECODER> --dataset <DATASET> --out <OUT> --stats-out <STATS_OUT>

Options:
      --decoder <DECODER>
          Loss-aware decoder implementation [possible values: envelope-matching]
      --error-format <ERROR_FORMAT>
          Select the error channel independently of command output [possible values: human, json]
      --circuit-subset <CIRCUIT_SUBSET>
          Versioned loss-visible circuit subset [default: v1] [possible values: v1, v2]
      --dataset <DATASET>
          Directory containing manifest.json, circuit.stim, and shots.b8
      --out <OUT>
          Destination bit-packed observable predictions
      --stats-out <STATS_OUT>
          Destination structured decode statistics
      --shot-timeout-ms <SHOT_TIMEOUT_MS>
          Per-shot Envelope-MLE time limit
  -h, --help
          Print help
rstim capabilities
Discover the commands and contracts implemented by this binary

Usage: rstim capabilities [OPTIONS] --format <FORMAT>

Options:
      --error-format <ERROR_FORMAT>  Select the error channel independently of command output [possible values: human, json]
      --format <FORMAT>              [possible values: json]
  -h, --help                         Print help
rstim perf run
Emit raw benchmark JSONL

Usage: rstim perf run [OPTIONS]

Options:
      --benchmark-telemetry-json <BENCHMARK_TELEMETRY_JSON>  
      --out <OUT>                                            
      --case <CASE>                                          
      --warmup-rounds <WARMUP_ROUNDS>                        [default: 1]
      --measure-rounds <MEASURE_ROUNDS>                      [default: 5]
  -h, --help                                                 Print help
rstim perf summarize
Aggregate raw JSONL into summary JSON

Usage: rstim perf summarize [OPTIONS]

Options:
      --benchmark-telemetry-json <BENCHMARK_TELEMETRY_JSON>  
      --case <CASE>                                          
      --in <IN>                                              
      --out <OUT>                                            
  -h, --help                                                 Print help
rstim perf gate
Evaluate summary JSON and return non-zero on gate failure

Usage: rstim perf gate [OPTIONS]

Options:
      --benchmark-telemetry-json <BENCHMARK_TELEMETRY_JSON>  
      --in <IN>                                              
      --sampler-threshold <SAMPLER_THRESHOLD>                [default: 1.1]
      --analyzer-threshold <ANALYZER_THRESHOLD>              [default: 1.1]
  -h, --help                                                 Print help
rstim perf report
Render summary JSON as Markdown

Usage: rstim perf report [OPTIONS]

Options:
      --benchmark-telemetry-json <BENCHMARK_TELEMETRY_JSON>  
      --in <IN>                                              
      --out <OUT>                                            
  -h, --help                                                 Print help
rstim perf ci
Run the full perf pipeline and write raw / summary / report artifacts

Usage: rstim perf ci [OPTIONS] --out-dir <OUT_DIR>

Options:
      --benchmark-telemetry-json <BENCHMARK_TELEMETRY_JSON>  
      --out-dir <OUT_DIR>                                    
      --case <CASE>                                          
      --warmup-rounds <WARMUP_ROUNDS>                        [default: 1]
      --measure-rounds <MEASURE_ROUNDS>                      [default: 5]
  -h, --help                                                 Print help
rstim circuit import-qasm
Import checked OpenQASM 2.0 into a semantic document or Stim projection

Usage: rstim circuit import-qasm [OPTIONS] --out <OUT>

Options:
      --error-format <ERROR_FORMAT>  Select the error channel independently of command output [possible values: human, json]
      --in <INPUT>                   
      --out <OUT>                    
      --out-format <OUT_FORMAT>      [default: qasm2-json] [possible values: qasm2-json, stim]
      --backend <BACKEND>            [default: stabilizer] [possible values: stabilizer, near-clifford]
      --include-dir <INCLUDE_DIRS>   
      --format <FORMAT>              [default: json] [possible values: human, json]
  -h, --help                         Print help
rstim circuit export-qasm
Export supported native or semantic circuits as OpenQASM 2.0

Usage: rstim circuit export-qasm [OPTIONS] --out <OUT>

Options:
      --error-format <ERROR_FORMAT>  Select the error channel independently of command output [possible values: human, json]
      --in <INPUT>                   
      --out <OUT>                    
      --in-format <IN_FORMAT>        [default: stim] [possible values: stim, qasm2-json]
      --omit-annotations             
      --format <FORMAT>              [default: json] [possible values: human, json]
  -h, --help                         Print help
rstim circuit stats
Summarize circuit structure and counts

Usage: rstim circuit stats [OPTIONS]

Options:
      --error-format <ERROR_FORMAT>  Select the error channel independently of command output [possible values: human, json]
      --in <INPUT>                   Read the circuit from a file instead of stdin
      --format <FORMAT>              Select human-readable or versioned JSON output [default: human] [possible values: human, json]
  -h, --help                         Print help
rstim circuit gen
Generate a built-in QEC circuit (common families and Mid-SWAP)

Usage: rstim circuit gen [OPTIONS] --code <CODE> --task <TASK> --distance <DISTANCE> --rounds <ROUNDS> --out <OUT>

Options:
      --code <CODE>
          Code family, e.g. surface_code
      --error-format <ERROR_FORMAT>
          Select the error channel independently of command output [possible values: human, json]
      --task <TASK>
          Task within the family, e.g. rotated_memory_z_midswap
      --distance <DISTANCE>
          Code distance
      --rounds <ROUNDS>
          Number of syndrome-extraction rounds
      --after-clifford-depolarization <AFTER_CLIFFORD_DEPOLARIZATION>
          After-Clifford depolarization probability [default: 0] [alias: --after_clifford_depolarization]
      --before-round-data-depolarization <BEFORE_ROUND_DATA_DEPOLARIZATION>
          Depolarization applied to data qubits at the start of each round [default: 0]
      --before-round-data-loss-probability <BEFORE_ROUND_DATA_LOSS_PROBABILITY>
          Atom loss applied to data qubits at the start of each Mid-SWAP round [default: 0] [alias: --before-round-data-loss]
      --before-measure-flip-probability <BEFORE_MEASURE_FLIP_PROBABILITY>
          Bit-flip probability applied immediately before each measurement [default: 0]
      --after-reset-flip-probability <AFTER_RESET_FLIP_PROBABILITY>
          Bit-flip probability applied immediately after each reset [default: 0]
      --after-clifford-loss-probability <AFTER_CLIFFORD_LOSS_PROBABILITY>
          Loss probability after Clifford gates (non-Mid-SWAP families) [default: 0]
      --operation-loss-probability <OPERATION_LOSS_PROBABILITY>
          Operation-loss probability for gates and resets (Mid-SWAP and loss-visible rotated_memory_z) [default: 0]
      --measurement-loss-probability <MEASUREMENT_LOSS_PROBABILITY>
          Measurement-loss probability (Mid-SWAP and loss-visible rotated_memory_z) [default: 0]
      --out <OUT>
          Destination circuit file
      --format <FORMAT>
          Select human-readable or versioned JSON output [default: json] [possible values: human, json]
  -h, --help
          Print help
rstim circuit sample
Sample measurement results from a circuit

Usage: rstim circuit sample [OPTIONS] --shots <SHOTS> --out <OUT>

Options:
      --error-format <ERROR_FORMAT>
          Select the error channel independently of command output [possible values: human, json]
      --shots <SHOTS>
          Number of shots
      --in <INPUT>
          Read the circuit from a file instead of stdin
      --out <OUT>
          Destination shot file
      --out-format <OUT_FORMAT>
          Shot output format: 01, b8, r8, hits, ptb64 [default: 01]
      --seed <SEED>
          Sampling seed
      --skip-reference-sample
          Skip the reference noiseless sample (requires a noiseless circuit)
      --format <FORMAT>
          Select human-readable or versioned JSON output [default: json] [possible values: human, json]
      --in-format <IN_FORMAT>
          Input circuit format; ordinary Stim remains the default [default: stim] [possible values: stim, qasm2-json]
      --backend <BACKEND>
          Explicit execution backend; no fallback is performed [default: stabilizer] [possible values: stabilizer, near-clifford]
      --result-view <RESULT_VIEW>
          Return all measurement events or final declared classical bits [default: measurement-record] [possible values: measurement-record, classical]
      --max-active-rank <MAX_ACTIVE_RANK>
          Near-Clifford active rank budget [default: 16]
  -h, --help
          Print help
rstim circuit detect
Sample detection events and observable flips from a circuit

Usage: rstim circuit detect [OPTIONS] --shots <SHOTS> --out <OUT>

Options:
      --error-format <ERROR_FORMAT>
          Select the error channel independently of command output [possible values: human, json]
      --shots <SHOTS>
          Number of shots
      --in <INPUT>
          Read the circuit from a file instead of stdin
      --out <OUT>
          Destination detection-event file
      --out-format <OUT_FORMAT>
          Detection output format: 01, b8, r8, hits, dets, ptb64 [default: 01]
      --seed <SEED>
          Sampling seed
      --append-observables
          Append observable flips after the detection events
      --obs-out <OBS_OUT>
          Write observable flips to a separate file
      --obs-out-format <OBS_OUT_FORMAT>
          Observable output format when --obs-out is set [default: 01]
      --format <FORMAT>
          Select human-readable or versioned JSON output [default: json] [possible values: human, json]
  -h, --help
          Print help
rstim circuit dem
Convert a circuit into a detector error model

Usage: rstim circuit dem [OPTIONS] --out <OUT>

Options:
      --error-format <ERROR_FORMAT>  Select the error channel independently of command output [possible values: human, json]
      --in <INPUT>                   Read the circuit from a file instead of stdin
      --out <OUT>                    Destination detector error model file
      --approximate-disjoint-errors  Allow statistical approximation of disjoint errors
      --allow-gauge-detectors        Allow gauge detectors with ambiguous observables
      --decompose-errors             Decompose errors into graphlike components
      --format <FORMAT>              Select human-readable or versioned JSON output [default: json] [possible values: human, json]
  -h, --help                         Print help
rstim circuit decode
Decode detector rows from a DEM with a selected decoder

Usage: rstim circuit decode [OPTIONS] --decoder <DECODER> --dem <DEM> --in <INPUT> --out <OUT>

Options:
      --decoder <DECODER>            Decoder to use; rmatching requires a graphlike DEM and rejects hyperedges [possible values: rmatching]
      --error-format <ERROR_FORMAT>  Select the error channel independently of command output [possible values: human, json]
      --dem <DEM>                    Detector error model file
      --in <INPUT>                   Input 01 file containing detector bits only, one shot per line
      --out <OUT>                    Destination 01 file containing observable predictions
      --format <FORMAT>              Select human-readable or versioned JSON output [default: json] [possible values: human, json]
  -h, --help                         Print help
rstim dataset score
Score observable predictions against the private answer bundle

Usage: rstim dataset score [OPTIONS] --dataset <DATASET> --private <PRIVATE> --predictions <PREDICTIONS>

Options:
      --dataset <DATASET>            Public dataset directory used for decoding
      --error-format <ERROR_FORMAT>  Select the error channel independently of command output [possible values: human, json]
      --private <PRIVATE>            Matching private answer bundle (read only during scoring)
      --predictions <PREDICTIONS>    Bit-packed observable predictions in lsb_first b8 format
      --decode-stats <DECODE_STATS>  Optional decode statistics to verify successful completion
      --format <FORMAT>              Select human-readable or versioned JSON output [default: human] [possible values: human, json]
  -h, --help                         Print help
rstim dataset export
Export a public decoder dataset and private answer bundle

Usage: rstim dataset export [OPTIONS] --circuit <CIRCUIT> --shots <SHOTS> --public-out <PUBLIC_OUT> --private-out <PRIVATE_OUT>

Options:
      --circuit <CIRCUIT>
          Circuit file to sample (loss-visible circuits supported)
      --error-format <ERROR_FORMAT>
          Select the error channel independently of command output [possible values: human, json]
      --shots <SHOTS>
          Number of shots to sample into the dataset
      --mode <MODE>
          Dataset mode; auto uses circuit logical-input metadata or explicit support [default: auto]
      --public-out <PUBLIC_OUT>
          Destination directory for the public dataset bundle
      --private-out <PRIVATE_OUT>
          Destination directory for the private answer bundle
      --seed <SEED>
          Sampling seed for reproducible datasets
      --logical-x-qubits <LOGICAL_X_QUBITS>
          Override the circuit's logical-input operator with X on these qubits
      --logical-z-qubits <LOGICAL_Z_QUBITS>
          Override the circuit's logical-input operator with Z on these qubits
      --error-trace
          Also write a per-shot rstim.error-trace.v1 trace.jsonl into the private bundle
      --format <FORMAT>
          Select human-readable or versioned JSON output [default: json] [possible values: human, json]
  -h, --help
          Print help
rstim dataset import
Package a third-party circuit and shot payload into a public dataset

Usage: rstim dataset import [OPTIONS] --circuit <CIRCUIT> --shots <SHOTS> --out <OUT>

Options:
      --circuit <CIRCUIT>
          Loss-visible circuit file (must satisfy the selected subset)
      --error-format <ERROR_FORMAT>
          Select the error channel independently of command output [possible values: human, json]
      --circuit-subset <CIRCUIT_SUBSET>
          Versioned loss-visible circuit subset [default: v1] [possible values: v1, v2]
      --shots <SHOTS>
          Shot payload file produced by an external sampler
      --shots-format <SHOTS_FORMAT>
          Shot payload encoding: 01 (text rows) or b8 (packed binary) [default: 01]
      --out <OUT>
          Destination directory for the public dataset bundle
      --loss-log <LOSS_LOG>
          Optional rustqec.loss-log.v1 sidecar to cross-check flag bits
      --format <FORMAT>
          Select human-readable or versioned JSON output [default: json] [possible values: human, json]
  -h, --help
          Print help

rstim commands

A schema identifies the structure and version of a JSON status response; artifact formats describe the separate data files.

rstim circuit stats

Inputs: stdin, file. Status formats: human, json. Output schema: rustqec.cli.v1. Success exit: 0.

ArgumentRequiredAccepted valueDefault
--inNopathstdin
--formatNohuman | jsonhuman

Structured errors

CodeExitChannel
invalid_arguments2stderr
invalid_circuit2stderr
input_error2stderr
output_error2stderr

rstim circuit gen

Inputs: built_in_generators. Status formats: human, json. Output schema: rustqec.cli.v1. Success exit: 0.

ArgumentRequiredAccepted valueDefault
--codeYessurface_code | repetition_code | color_code—
--taskYesrotated_memory_z_midswap | rotated_memory_x | rotated_memory_z | unrotated_memory_x | unrotated_memory_z | memory | memory_xyz—
--distanceYespositive_integer—
--roundsYesnon_negative_integer—
--after-clifford-depolarizationNoprobability0
--before-round-data-depolarizationNoprobability0
--before-round-data-loss-probabilityNoprobability0
--before-measure-flip-probabilityNoprobability0
--after-reset-flip-probabilityNoprobability0
--after-clifford-loss-probabilityNoprobability0
--operation-loss-probabilityNoprobability0
--measurement-loss-probabilityNoprobability0
--outYespath—
--formatNohuman | jsonjson

Artifacts

NameFlagFormat
circuit--outstim

Structured errors

CodeExitChannel
invalid_arguments2stderr
output_error2stderr

rstim circuit sample

Inputs: stdin, file. Status formats: human, json. Output schema: rustqec.cli.v1. Success exit: 0.

ArgumentRequiredAccepted valueDefault
--shotsYesnon_negative_integer—
--inNopathstdin
--outYespath—
--out-formatNo01 | b8 | r8 | hits | ptb6401
--seedNonon_negative_integer—
--skip-reference-sampleNoflag—
--formatNohuman | jsonjson
--in-formatNostim | qasm2-jsonstim
--backendNostabilizer | near-cliffordstabilizer
--result-viewNomeasurement-record | classicalmeasurement-record
--max-active-rankNonon_negative_integer16

Artifacts

NameFlagFormat
measurements--out01|b8|r8|hits|ptb64

Structured errors

CodeExitChannel
invalid_arguments2stderr
invalid_circuit2stderr
input_error2stderr
execution_error2stderr
output_error2stderr
qasm_parse_error2stderr
qasm_type_error2stderr
qasm_unsupported_construct2stderr
qasm_backend_unsupported2stderr
qasm_unrepresentable_export2stderr
qasm_missing_layout2stderr
qasm_limit_exceeded2stderr
qasm_io_error2stderr
qasm_invalid_document2stderr

rstim circuit detect

Inputs: stdin, file. Status formats: human, json. Output schema: rustqec.cli.v1. Success exit: 0.

ArgumentRequiredAccepted valueDefault
--shotsYesnon_negative_integer—
--inNopathstdin
--outYespath—
--out-formatNo01 | b8 | r8 | hits | dets | ptb6401
--seedNonon_negative_integer—
--append-observablesNoflag—
--obs-outNopath—
--obs-out-formatNo01 | b8 | r8 | hits | dets | ptb6401
--formatNohuman | jsonjson

Artifacts

NameFlagFormat
detection_events--out01|b8|r8|hits|dets|ptb64
observable_flips--obs-out01|b8|r8|hits|dets|ptb64

Structured errors

CodeExitChannel
invalid_arguments2stderr
invalid_circuit2stderr
input_error2stderr
execution_error2stderr
output_error2stderr

rstim circuit dem

Inputs: stdin, file. Status formats: human, json. Output schema: rustqec.cli.v1. Success exit: 0.

ArgumentRequiredAccepted valueDefault
--inNopathstdin
--outYespath—
--approximate-disjoint-errorsNoflag—
--allow-gauge-detectorsNoflag—
--decompose-errorsNoflag—
--formatNohuman | jsonjson

Artifacts

NameFlagFormat
detector_error_model--outdem

Structured errors

CodeExitChannel
invalid_arguments2stderr
invalid_circuit2stderr
input_error2stderr
execution_error2stderr
output_error2stderr

rstim circuit decode

Inputs: file. Status formats: human, json. Output schema: rustqec.cli.v1. Success exit: 0.

Advertised decoders: rmatching.

ArgumentRequiredAccepted valueDefault
--decoderYesrmatching—
--demYespath—
--inYes01_detector_rows—
--outYespath—
--formatNohuman | jsonjson

Artifacts

NameFlagFormat
observable_predictions--out01

Structured errors

CodeExitChannel
invalid_arguments2stderr
invalid_dem2stderr
invalid_detector_row2stderr
input_error2stderr
output_error2stderr

rstim dataset export

Inputs: file. Status formats: human, json. Output schema: rustqec.cli.v1. Success exit: 0.

ArgumentRequiredAccepted valueDefault
--circuitYespath—
--shotsYesnon_negative_integer—
--modeNoauto | detectors | measurements_blindedauto
--public-outYespath—
--private-outYespath—
--seedNonon_negative_integer—
--logical-x-qubitsNoqubit_index_list—
--logical-z-qubitsNoqubit_index_list—
--error-traceNobooleanfalse
--formatNohuman | jsonjson

Artifacts

NameFlagFormat
public_dataset--public-outdirectory
private_answers--private-outdirectory

Structured errors

CodeExitChannel
invalid_arguments2stderr
invalid_circuit2stderr
input_error2stderr
execution_error2stderr

rstim dataset import

Inputs: file. Status formats: human, json. Output schema: rustqec.cli.v1. Success exit: 0.

ArgumentRequiredAccepted valueDefault
--circuit-subsetNov1 | v2v1
--circuitYespath—
--shotsYespath—
--shots-formatNo01 | b801
--outYespath—
--loss-logNopath—
--formatNohuman | jsonjson

Artifacts

NameFlagFormat
public_dataset--outdirectory

Structured errors

CodeExitChannel
invalid_arguments2stderr
invalid_circuit2stderr
input_error2stderr
invalid_dataset2stderr
unsupported_circuit2stderr
loss_log_mismatch2stderr
output_error2stderr

rstim dataset score

Inputs: public_decoder_dataset_directory, private_answer_bundle, b8_predictions. Status formats: human, json. Output schema: rustqec.cli.v1. Success exit: 0.

ArgumentRequiredAccepted valueDefault
--datasetYespath—
--privateYespath—
--predictionsYespath—
--decode-statsNopath—
--formatNohuman | jsonhuman

Structured errors

CodeExitChannel
invalid_arguments2stderr
input_error2stderr
missing_dataset_file2stderr
invalid_dataset2stderr
unsupported_dataset_mode2stderr
invalid_predictions2stderr
invalid_decode_stats2stderr
output_error2stderr

rstim decode

Inputs: public_decoder_dataset_directory. Status formats: b8, json. Output schema: rustqec.decode-stats.v1. Success exit: 0.

Advertised decoders: envelope-matching.

ArgumentRequiredAccepted valueDefault
--circuit-subsetNov1 | v2v1
--decoderYesenvelope-matching—
--datasetYespath—
--outYespath—
--stats-outYespath—
--shot-timeout-msNonon_negative_integer—

Artifacts

NameFlagFormat
predictions--outb8
stats--stats-outrustqec.decode-stats.v1+json

Structured errors

CodeExitChannel
invalid_arguments2stderr
missing_dataset_file2stderr
invalid_dataset2stderr
unsupported_dataset_mode2stderr
unsupported_circuit2stderr
decode_timeout3stderr
decode_infeasible3stderr
decode_error2stderr
output_error2stderr

rstim circuit import-qasm

Inputs: stdin, file. Status formats: human, json. Output schema: rustqec.cli.v1. Success exit: 0.

ArgumentRequiredAccepted valueDefault
--inNopathstdin
--outYespath—
--formatNohuman | jsonjson
--out-formatNoqasm2-json | stimqasm2-json
--backendNostabilizer | near-cliffordstabilizer
--include-dirNopath—

Artifacts

NameFlagFormat
circuit--outrstim.qasm2-program.v1+json|stim

Structured errors

CodeExitChannel
qasm_parse_error2stderr
qasm_type_error2stderr
qasm_unsupported_construct2stderr
qasm_backend_unsupported2stderr
qasm_unrepresentable_export2stderr
qasm_missing_layout2stderr
qasm_limit_exceeded2stderr
qasm_io_error2stderr
qasm_invalid_document2stderr
invalid_arguments2stderr
invalid_circuit2stderr
input_error2stderr
output_error2stderr

rstim circuit export-qasm

Inputs: stdin, file. Status formats: human, json. Output schema: rustqec.cli.v1. Success exit: 0.

ArgumentRequiredAccepted valueDefault
--inNopathstdin
--outYespath—
--formatNohuman | jsonjson
--in-formatNostim | qasm2-jsonstim
--omit-annotationsNoflag—

Artifacts

NameFlagFormat
circuit--outopenqasm-2.0

Structured errors

CodeExitChannel
qasm_parse_error2stderr
qasm_type_error2stderr
qasm_unsupported_construct2stderr
qasm_backend_unsupported2stderr
qasm_unrepresentable_export2stderr
qasm_missing_layout2stderr
qasm_limit_exceeded2stderr
qasm_io_error2stderr
qasm_invalid_document2stderr
invalid_arguments2stderr
invalid_circuit2stderr
input_error2stderr
output_error2stderr

Arguments and output contracts

Global arguments

ArgumentRequiredAccepted valueDefault
--error-formatNohuman | json—

Input

Commands that accept --in read stdin when the flag is omitted. Dataset commands use directories with a manifest and fixed artifact names.

Output

--format human|json controls command status output where offered. Artifact flags such as --out and --stats-out name separate files.

Errors

Global error formatting and each command’s structured error channel are listed from the executable contract above.

rstim --error-format json circuit stats --in missing.stim
{
  "schema_version": "rustqec.cli.v1",
  "status": "error",
  "command": "circuit.stats",
  "error": {"code": "input_error", "message": "..."}
}

Exit codes and structured errors

ExitStatusReported codesChannel
0Successok—
2Errordecode_error, execution_error, input_error, invalid_arguments, invalid_circuit, invalid_dataset, invalid_decode_stats, invalid_dem, invalid_detector_row, invalid_predictions, loss_log_mismatch, missing_dataset_file, output_error, qasm_backend_unsupported, qasm_invalid_document, qasm_io_error, qasm_limit_exceeded, qasm_missing_layout, qasm_parse_error, qasm_type_error, qasm_unrepresentable_export, qasm_unsupported_construct, unsupported_circuit, unsupported_dataset_modestderr
3Errordecode_infeasible, decode_timeoutstderr

Use the error code for automation. Human messages add context but are not the compatibility key.

Inspect the installed binary

rstim capabilities --format json > capabilities.json
rstim --version

The capabilities document lists command arguments, output schemas, artifact formats, exit codes, structured errors and available decoders. Optional features such as ilp change that document.

Dataset scoring

rstim dataset score compares observable predictions with the matching private answers. It checks dataset identity, file hashes, complete rows and zero padding bits. When --decode-stats is supplied, the statistics must match the circuit and shot count and describe a complete run without timeouts or infeasible shots. Each shot with any wrong observable counts as one logical error.

Rust APIs

Open the versioned Rust API index, or run a complete experiment in Rust.