stim.jl

MemoryData

Stim memory simulation results.

Fields

• circuit_param::AbstractCircuitParameters: Circuit parameters.
• noise_param::AbstractNoiseParameters: Noise parameters.
• rounds::Int: Number of memory circuit rounds.
• shots::Int: Number of sampled shots.
• seed::UInt64: Seed for Stim simulation.
• reset_type::Symbol: Reset type, which is :meas_reset by default but can be set to :meas.
• decoder_type::Symbol: Decoder type, which is :pymatching by default but can be set to :beliefmatching.
• decoder_gate_probabilities::Vector{Dict{Gate, Vector{Float64}}}: Vector of gate probabilities used to inform the decoder.
• decoder_labels::Vector{String}: Labels for the gate probabilities in decoder_gate_probabilities.
• memory_x_observable::Vector{Bool}: X memory experiment observable across each of the shots.
• memory_z_observable::Vector{Bool}: Z memory experiment observable across each of the shots.
• decoder_x_predictions::Matrix{Bool}: X memory experiment decoder predictions across each of the shots and decoders in decoder_gate_probabilities.
• decoder_z_predictions::Matrix{Bool}: Z memory experiment decoder predictions across each of the shots and decoders in decoder_gate_probabilities.

MemorySummary

Stim memory simulation summary results.

Fields

• circuit_param::AbstractCircuitParameters: Circuit parameters.
• noise_param::AbstractNoiseParameters: Noise parameters.
• rounds::Int: Number of memory circuit rounds.
• shots::Int: Number of sampled shots.
• seed::UInt64: Seed for Stim simulation.
• reset_type::Symbol: Reset type, which is :meas_reset by default but can be set to :meas.
• decoder_type::Symbol: Decoder type, which is :pymatching by default but can be set to :beliefmatching.
• decoder_labels::Vector{String}: Labels for the decoder gate probabilities.
• memory_x_errors::Vector{Float64}: X memory experiment error rate.
• memory_z_errors::Vector{Float64}: Z memory experiment error rate.
• memory_x_errors_cov::Matrix{Float64}: X memory experiment error rate covariance.
• memory_z_errors_cov::Matrix{Float64}: Z memory experiment error rate covariance.
• change_x_errors::Matrix{Float64}: X memory experiment change in error rate across different gate probabilities.
• change_z_errors::Matrix{Float64}: Z memory experiment change in error rate across different gate probabilities.
• change_x_errors_sem::Matrix{Float64}: X memory experiment change in error rate across different gate probabilities standard error of the mean.
• change_z_errors_sem::Matrix{Float64}: Z memory experiment change in error rate across different gate probabilities standard error of the mean.
• decoder_x_confusion::Matrix{Int}: X memory experiment decoder confusion matrix.
• decoder_z_confusion::Matrix{Int}: Z memory experiment decoder confusion matrix.

calc_memory_distances(c::AbstractCircuit; reset_type::Symbol = :meas_reset, max_event_set_size::Integer = 4, max_edge_degree::Integer = 2, explore_increasing_degree::Bool = false)

Calculates the logical Z and X error distances corresponding to the X and Z memory circuits corresponding to the syndrome extraction circuit c, which are conventionally the vertical and horizontal distances, respectively. Reset types are specified by reset_type and can be :meas_reset or :meas. Search parameters used by Stim are max_event_set_size, max_edge_degree, and explore_increasing_degree.

dist_linear_model(dist, params)

Linear model as a function of the distance dist with parameters params.

fit_dist_error(dist_set::Vector{Int}, dist_memory_errors::Vector{Float64}, dist_memory_errors_sem::Vector{Float64}; return_cov::Bool = false)

Returns parameters for dist_linear_model fitted with weighted least squares from the memory errors dist_memory_errors and their standard errors of the mean dist_memory_errors_sem across the distances in dist_set. Note that the fitting is performed in log space: to fit the original parameters, exponentiate the output of dist_linear_model.

fit_round_error(rounds_set::Vector{Int}, rounds_memory_errors::Vector{Float64}, rounds_memory_errors_sem::Vector{Float64}; return_cov::Bool = false)

Returns parameters for round_exponential_model fitted with weighted least squares from the memory errors rounds_memory_errors and their standard errors of the mean rounds_memory_errors_sem across the rounds in rounds_set.

get_dist_error(dist_params::Vector{Float64})
get_dist_error(dist_params::Vector{Float64}, dist_params_cov::Matrix{Float64})

Returns the error suppression factor, the change in error rate in a code as the distance is increased by 2, determined from dist_params, and its standard error if its covariance matrix dist_params_cov is supplied.

get_memory_summary(memory_data::MemoryData)

Returns memory summary data as a MemorySummary object from the memory data memory_data.

get_round_error(round_params::Vector{Float64})
get_round_error(round_params::Vector{Float64}, round_params_cov::Matrix{Float64})

Returns the error per round determined from round_params, and its standard error if its covariance matrix round_params_cov is supplied.

get_stim_circuit(circuit::Vector{Layer}, gate_probabilities::Dict{Gate, Vector{Float64}}, noisy_prep::Bool, noisy_meas::Bool; extra_fields::Dict{Symbol, Any} = Dict{Symbol, Any}(), meas_and_reset::Bool = false)

Returns a Stim string representation of the circuit circuit alongside error probabilities specified by gate_probabilities, as well as noisy preparations if noisy_prep is true and noisy measurements if noisy_meas is true. Qubit coordinates are specified by extra_fields if it contains a CodeParameters object. Reset types are specified by reset_type and can be :reset, :meas, or :meas_reset.

Stim orders one-qubit Paulis as: X, Y, Z. We order one-qubit Paulis as: X, Z, Y. The indexing to transform between these orderings is: 1, 3, 2.

Stim orders two-qubit Paulis as: IX, IY, IZ, XI, XX, XY, XZ, YI, YX, YY, YZ, ZI, ZX, ZY, ZZ. We order two-qubit Paulis as: XI, IX, XX, ZI, YI, ZX, YX, IZ, XZ, IY, XY, ZZ, YZ, ZY, YY. The indexing to transform from the Stim ordering to ours is: 4, 1, 5, 12, 8, 13, 9, 3, 7, 2, 6, 15, 11, 14, 10. The indexing to transform from our ordering to the Stim ordering is: 2, 10, 8, 1, 3, 11, 9, 5, 7, 15, 13, 4, 6, 14, 12.

get_stim_memory_circuit(c::AbstractCircuit, gate_probabilities::Dict{Gate, Vector{Float64}}, memory_type::Symbol, rounds::Integer; reset_type::Symbol = :meas_reset)
get_stim_memory_circuit(c::AbstractCircuit, memory_type::Symbol, rounds::Integer; reset_type::Symbol = :meas_reset)

Returns a Stim string representation of the memory circuit corresponding to the syndrome extraction circuit c, optionally using the gate error probabilities gate_probabilities, memory type memory_type, which can be either :x or :z, number of rounds rounds, and reset type reset_type, which can be either :meas_reset or :meas.

If you want to add support for custom syndrome extraction circuits c which do not store their code parameters in the CodeParameters object, you will need to define new methods for get_stim_qubits, get_stim_initialise, get_stim_detectors, and get_stim_measure_detectors to make this function work.

round_exponential_model(rounds, params)

Exponential decay model as a function of the number of rounds rounds with parameters params.

simulate_memory(c::AbstractCircuit, rounds::Integer, shots::Integer; kwargs...)

Returns the memory and decoding simulation results for a memory experiment conducted with the given syndrome extraction circuit.

WARNING: Seeding has the same features as in Stim. The behaviour of the same random seed will differ across different versions of Stim. Also, when measurement shots are sampled in batches, which occurs when max_samples is exceeded, the results will differ from when all shots are sampled at once.

Arguments

• c::AbstractCircuit: Syndrome extraction circuit.
• rounds::Integer: Number of memory circuit rounds, which must be at least 0.
• shots::Integer: Number of shots, which must be at least 1.

Keyword arguments

• seed::Union{UInt64, Nothing} = nothing: Seed to use for random number generation.
• reset_type::Symbol = :meas_reset: Reset type, which can be either :meas_reset or :meas.
• decoder_type::Symbol = :pymatching: Decoder type, which can be either :pymatching or :beliefmatching.
• decoder_gate_probabilities::Vector{Dict{Gate, Vector{Float64}}} = [c.gate_probabilities]: Gate probabilities used for decoding, the first of which must be the gate probabilities of the supplied circuit c.
• decoder_labels::Vector{String} = [string(idx) for idx in 1:length(decoder_gate_probabilities)]: Labels for the decoder gate probabilities.
• max_samples::Integer = 10^9: Maximum number of Stim detector samples collected in a single simulation.
• diagnostics::Bool = false: Whether to print diagnostics.

batch_simulate_memory(c::AbstractCircuit, memory_type::Symbol, rounds::Integer, shots::Integer; kwargs...)

Returns the memory and decoding simulation results for a memory experiment conducted with the given syndrome extraction circuit.

WARNING: Seeding has the same features as in Stim. The behaviour of the same random seed will differ across different versions of Stim. Also, when measurement shots are sampled in batches, which occurs when max_samples is exceeded, the results will differ from when all shots are sampled at once.

Arguments

• c::AbstractCircuit: Syndrome extraction circuit.
• memory_type::Symbol: Memory type, which can be either :x or :z.
• rounds::Integer: Number of memory circuit rounds, which must be at least 0.
• shots::Integer: Number of shots, which must be at least 1.

Keyword arguments

• seed::Union{UInt64, Nothing} = nothing: Seed to use for random number generation.
• reset_type::Symbol = :meas_reset: Reset type, which can be either :meas_reset or :meas.
• decoder_type::Symbol = :pymatching: Decoder type, which can be either :pymatching or :beliefmatching.
• decoder_gate_probabilities::Vector{Dict{Gate, Vector{Float64}}} = [c.gate_probabilities]: Gate probabilities used for decoding, the first of which must be the gate probabilities of the supplied circuit c.
• max_samples::Integer = 10^9: Maximum number of Stim detector samples collected in a single simulation.
• diagnostics::Bool = false: Whether to print diagnostics.

get_stim_detectors(code_param::CodeParameters, memory_type::Symbol; previous_compare::Integer = 0, include_data::Bool = false)
get_stim_detectors(code_param::CodeParameters, previous_compare::Integer)

Returns a Stim string representation of the detectors for the code parameters code_param corresponding to the Pauli type specified by memory_type, which can be either :x or :z, comparing the detectors against those from previous_compare rounds ago. If include_data is true, the detector checks the relevant data qubits and is included only if it checks a nonzero number of data qubits.

If no memory type is specified, this generates detectors for both X and Z memory types but requires previous_compare to be specified.

get_stim_initialise(code_param::CodeParameters, memory_type::Symbol, gate_probabilities::Dict{Gate, Vector{Float64}}, noisy_prep::Bool)

Returns a Stim string representation of the initialisation for the code parameters code_param corresponding to the Pauli type specified by memory_type, which can be either :x or :z, using the gate error probabilities gate_probabilities if noisy_prep is true.

get_stim_measure_detectors(code_param::CodeParameters, gate_probabilities::Dict{Gate, Vector{Float64}}, noisy_meas::Bool; reset_type::Symbol = :meas_reset, do_rounds::Bool = true)

Returns a Stim string representation of the measurement and detectors for the code parameters code_param corresponding to the Pauli type specified by memory_type, which can be either :x or :z, using the gate error probabilities gate_probabilities if noisy_meas is true, for the reset type reset_type, which can be either :meas_reset or :meas. Set do_rounds to false when no rounds of the memory circuit are performed and reset_type is :meas to avoid breaking the measurement detectors.

get_stim_qubits(qubits::Vector{Tuple{Int, Int}})
get_stim_qubits(code_param::CodeParameters)
get_stim_qubits(empty_code_param::EmptyCodeParameters)

Returns a Stim string representation of the qubit coordinates described by qubits, which may be a field of code_param.

process_memory_data(memory_observable::Vector{Bool}, decoder_predictions::Matrix{Bool})

Returns summary data for the memory observables memory_observable and decoder predictions decoder_predictions.