rstim CLI reference

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.

Rust API versions Compatibility policy

All command help

Help is captured recursively from this checkout during the site build, including direct commands such as gen, render_svg and pack_samples. 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
rstim stats
rstim sample
rstim detect
rstim analyze_errors
rstim gen
rstim convert
rstim m2d
rstim explain_errors
rstim sample_dem
rstim export_json
rstim render_svg
rstim shot_viewer
rstim export_decoder_dataset
rstim pack_samples
rstim unpack_samples
rstim surface-code-ler
rstim perf
rstim circuit
rstim dataset
rstim decode
rstim capabilities
rstim perf run
rstim perf summarize
rstim perf gate
rstim perf report
rstim perf ci
rstim circuit stats
rstim circuit gen
rstim circuit sample
rstim circuit detect
rstim circuit dem
rstim circuit decode
rstim dataset export
rstim dataset import

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 and export 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> --mode <MODE> --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>
          
      --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:
  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:
  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]
      --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 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]
  -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 export

Export a public decoder dataset and private answer bundle

Usage: rstim dataset export [OPTIONS] --circuit <CIRCUIT> --shots <SHOTS> --mode <MODE> --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: detectors or measurements_blinded
      --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>
          Apply a logical-X flip on the given data qubits before export
      --logical-z-qubits <LOGICAL_Z_QUBITS>
          Apply a logical-Z flip on the given data qubits before export
      --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 subset v1)
      --error-format <ERROR_FORMAT>  Select the error channel independently of command output [possible values: human, json]
      --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

The tables come from rstim capabilities --format json. A schema identifies the structure and version of a JSON status response; artifact formats describe the separate data files.

Inspect your installed binary Open Rust API links

`rstim circuit stats`

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

Argument	Required	Accepted value	Default
`--in`	No	`path`	`stdin`
`--format`	No	`human \| json`	`human`

Structured errors

Code	Exit	Channel
`invalid_arguments`	`2`	`stderr`
`invalid_circuit`	`2`	`stderr`
`input_error`	`2`	`stderr`
`output_error`	`2`	`stderr`

`rstim circuit gen`

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

Argument	Required	Accepted value	Default
`--code`	Yes	`surface_code \| repetition_code \| color_code`	—
`--task`	Yes	`rotated_memory_z_midswap \| rotated_memory_x \| rotated_memory_z \| unrotated_memory_x \| unrotated_memory_z \| memory \| memory_xyz`	—
`--distance`	Yes	`positive_integer`	—
`--rounds`	Yes	`non_negative_integer`	—
`--after-clifford-depolarization`	No	`probability`	`0`
`--before-round-data-depolarization`	No	`probability`	`0`
`--before-round-data-loss-probability`	No	`probability`	`0`
`--before-measure-flip-probability`	No	`probability`	`0`
`--after-reset-flip-probability`	No	`probability`	`0`
`--after-clifford-loss-probability`	No	`probability`	`0`
`--operation-loss-probability`	No	`probability`	`0`
`--measurement-loss-probability`	No	`probability`	`0`
`--out`	Yes	`path`	—
`--format`	No	`human \| json`	`json`

Artifacts

Name	Flag	Format
circuit	`--out`	`stim`

Structured errors

Code	Exit	Channel
`invalid_arguments`	`2`	`stderr`
`output_error`	`2`	`stderr`

`rstim circuit sample`

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

Argument	Required	Accepted value	Default
`--shots`	Yes	`non_negative_integer`	—
`--in`	No	`path`	`stdin`
`--out`	Yes	`path`	—
`--out-format`	No	`01 \| b8 \| r8 \| hits \| ptb64`	`01`
`--seed`	No	`non_negative_integer`	—
`--skip-reference-sample`	No	`flag`	—
`--format`	No	`human \| json`	`json`

Artifacts

Name	Flag	Format
measurements	`--out`	`01\|b8\|r8\|hits\|ptb64`

Structured errors

Code	Exit	Channel
`invalid_arguments`	`2`	`stderr`
`invalid_circuit`	`2`	`stderr`
`input_error`	`2`	`stderr`
`execution_error`	`2`	`stderr`
`output_error`	`2`	`stderr`

`rstim circuit detect`

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

Argument	Required	Accepted value	Default
`--shots`	Yes	`non_negative_integer`	—
`--in`	No	`path`	`stdin`
`--out`	Yes	`path`	—
`--out-format`	No	`01 \| b8 \| r8 \| hits \| dets \| ptb64`	`01`
`--seed`	No	`non_negative_integer`	—
`--append-observables`	No	`flag`	—
`--obs-out`	No	`path`	—
`--obs-out-format`	No	`01 \| b8 \| r8 \| hits \| dets \| ptb64`	`01`
`--format`	No	`human \| json`	`json`

Artifacts

Name	Flag	Format
detection_events	`--out`	`01\|b8\|r8\|hits\|dets\|ptb64`
observable_flips	`--obs-out`	`01\|b8\|r8\|hits\|dets\|ptb64`

Structured errors

Code	Exit	Channel
`invalid_arguments`	`2`	`stderr`
`invalid_circuit`	`2`	`stderr`
`input_error`	`2`	`stderr`
`execution_error`	`2`	`stderr`
`output_error`	`2`	`stderr`

`rstim circuit dem`

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

Argument	Required	Accepted value	Default
`--in`	No	`path`	`stdin`
`--out`	Yes	`path`	—
`--approximate-disjoint-errors`	No	`flag`	—
`--allow-gauge-detectors`	No	`flag`	—
`--decompose-errors`	No	`flag`	—
`--format`	No	`human \| json`	`json`

Artifacts

Name	Flag	Format
detector_error_model	`--out`	`dem`

Structured errors

Code	Exit	Channel
`invalid_arguments`	`2`	`stderr`
`invalid_circuit`	`2`	`stderr`
`input_error`	`2`	`stderr`
`execution_error`	`2`	`stderr`
`output_error`	`2`	`stderr`

`rstim circuit decode`

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

Advertised decoders: rmatching.

Argument	Required	Accepted value	Default
`--decoder`	Yes	`rmatching`	—
`--dem`	Yes	`path`	—
`--in`	Yes	`01_detector_rows`	—
`--out`	Yes	`path`	—
`--format`	No	`human \| json`	`json`

Artifacts

Name	Flag	Format
observable_predictions	`--out`	`01`

Structured errors

Code	Exit	Channel
`invalid_arguments`	`2`	`stderr`
`invalid_dem`	`2`	`stderr`
`invalid_detector_row`	`2`	`stderr`
`input_error`	`2`	`stderr`
`output_error`	`2`	`stderr`

`rstim dataset export`

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

Argument	Required	Accepted value	Default
`--circuit`	Yes	`path`	—
`--shots`	Yes	`non_negative_integer`	—
`--mode`	Yes	`detectors \| measurements_blinded`	—
`--public-out`	Yes	`path`	—
`--private-out`	Yes	`path`	—
`--seed`	No	`non_negative_integer`	—
`--logical-x-qubits`	No	`qubit_index_list`	—
`--logical-z-qubits`	No	`qubit_index_list`	—
`--error-trace`	No	`boolean`	`false`
`--format`	No	`human \| json`	`json`

Artifacts

Name	Flag	Format
public_dataset	`--public-out`	`directory`
private_answers	`--private-out`	`directory`

Structured errors

Code	Exit	Channel
`invalid_arguments`	`2`	`stderr`
`invalid_circuit`	`2`	`stderr`
`input_error`	`2`	`stderr`
`execution_error`	`2`	`stderr`

`rstim dataset import`

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

Argument	Required	Accepted value	Default
`--circuit`	Yes	`path`	—
`--shots`	Yes	`path`	—
`--shots-format`	No	`01 \| b8`	`01`
`--out`	Yes	`path`	—
`--loss-log`	No	`path`	—
`--format`	No	`human \| json`	`json`

Artifacts

Name	Flag	Format
public_dataset	`--out`	`directory`

Structured errors

Code	Exit	Channel
`invalid_arguments`	`2`	`stderr`
`invalid_circuit`	`2`	`stderr`
`input_error`	`2`	`stderr`
`invalid_dataset`	`2`	`stderr`
`unsupported_circuit`	`2`	`stderr`
`loss_log_mismatch`	`2`	`stderr`
`output_error`	`2`	`stderr`

`rstim decode`

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

Advertised decoders: envelope-matching.

Argument	Required	Accepted value	Default
`--decoder`	Yes	`envelope-matching`	—
`--dataset`	Yes	`path`	—
`--out`	Yes	`path`	—
`--stats-out`	Yes	`path`	—
`--shot-timeout-ms`	No	`non_negative_integer`	—

Artifacts

Name	Flag	Format
predictions	`--out`	`b8`
stats	`--stats-out`	`rustqec.decode-stats.v1+json`

Structured errors

Code	Exit	Channel
`invalid_arguments`	`2`	`stderr`
`missing_dataset_file`	`2`	`stderr`
`invalid_dataset`	`2`	`stderr`
`unsupported_dataset_mode`	`2`	`stderr`
`unsupported_circuit`	`2`	`stderr`
`decode_timeout`	`3`	`stderr`
`decode_infeasible`	`3`	`stderr`
`decode_error`	`2`	`stderr`
`output_error`	`2`	`stderr`

Arguments and output contracts

Global arguments

Argument	Required	Accepted value	Default
`--error-format`	No	`human \| 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

Exit	Status	Reported codes	Channel
`0`	Success	`ok`	—
`2`	Error	`decode_error`, `execution_error`, `input_error`, `invalid_arguments`, `invalid_circuit`, `invalid_dataset`, `invalid_dem`, `invalid_detector_row`, `loss_log_mismatch`, `missing_dataset_file`, `output_error`, `unsupported_circuit`, `unsupported_dataset_mode`	`stderr`
`3`	Error	`decode_infeasible`, `decode_timeout`	`stderr`

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 the structured command interfaces and their argument values, output schema, artifact format, success code, structured errors, and available decoders. Optional features such as ilp change that document. This rendered page was generated from schema rustqec.cli.v1.

Rust APIs

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