Skip to content

types

Core data types for the tsim compilation and sampling pipeline.

This module defines immutable data structures that represent the different stages of circuit compilation:

  1. SamplingGraph: Result of parsing and reducing a circuit graph
  2. CompiledComponent: A single compiled connected component
  3. CompiledProgram: The full compiled circuit ready for sampling

CompiledComponent

Bases: Module


              flowchart TD
              tsim.core.types.CompiledComponent[CompiledComponent]

              

              click tsim.core.types.CompiledComponent href "" "tsim.core.types.CompiledComponent"

A single compiled connected component of a circuit.

Each component is independent and can be sampled separately. The results are then combined according to output_indices.

Attributes:

Name Type Description
output_indices tuple[int, ...]

Which global output indices this component owns. Used to reassemble component outputs into the final result.
f_selection Array

Indices into the global f_params array to select this component's required f-parameters. Shape: (num_f_for_component,)
compiled_scalar_graphs tuple[CompiledScalarGraphs, ...]

Compiled circuits for sampling. For sequential mode: - compiled_scalar_graphs[0]: Normalization (no outputs plugged) - compiled_scalar_graphs[i]: First i outputs plugged For joint mode: - compiled_scalar_graphs[0]: Normalization - compiled_scalar_graphs[1]: All outputs plugged

CompiledProgram dataclass 

CompiledProgram(
    components: tuple[CompiledComponent, ...],
    direct_f_indices: Array,
    direct_flips: Array,
    output_order: Array,
    output_reindex: Array | None,
    num_outputs: int,
    num_detectors: int,
)

A fully compiled circuit program ready for sampling.

This is the result of compiling a SamplingGraph and contains everything needed to sample from the circuit.

Attributes:

Name Type Description
components tuple[CompiledComponent, ...]

The compiled components, sorted by number of outputs.
direct_f_indices Array

Precomputed f-parameter indices for direct components.
direct_flips Array

Precomputed flip flags for direct components.
output_order Array

Maps concatenated position to original output index. The first len(direct_f_indices) entries correspond to direct components; the remainder to compiled components.
output_reindex Array | None

Precomputed argsort(output_order) permutation, or None when the outputs are already in order.
num_outputs int

Total number of outputs across all components.
num_detectors int

Number of detector outputs (for detector sampling).

SamplingGraph dataclass 

SamplingGraph(
    graph: BaseGraph,
    error_transform: ndarray,
    channel_probs: list[ndarray],
    num_outputs: int,
    num_detectors: int,
)

Result of the graph preparation phase for sampling.

Contains all data structures needed for sampling. This represents a circuit that has been: 1. Parsed from stim format 2. Converted to a ZX graph 3. Doubled (composed with adjoint) 4. Reduced via zx.full_reduce 5. Had its error basis transformed (Gaussian elimination: e → f)

Attributes:

Name Type Description
graph BaseGraph

The prepared ZX graph with f-parameters on vertices.
error_transform ndarray

Binary matrix of shape (num_f, num_e) where entry [i, j] = 1 means f_i depends on e_j (i.e., f_i = XOR of e_j where matrix[i,j] = 1).
channel_probs list[ndarray]

List of probability arrays for error channels.
num_outputs int

Number of output vertices (measurements or detectors).
num_detectors int

Number of detector vertices.