estimate.jl

NoiseError

Noise estimate error data structure containing normalised root-mean-square errors (NRMSE) for a NoiseEstimate.

Fields

• gls_nrmse::Float64: Generalised least squares normalised root-mean-square error.
• gls_proj_nrmse::Float64: Generalised least squares projected normalised root-mean-square error.
• gls_marginal_nrmse::Float64: Generalised least squares marginal normalised root-mean-square error.
• gls_proj_marginal_nrmse::Float64: Generalised least squares projected marginal normalised root-mean-square error.
• gls_relative_nrmse::Float64: Generalised least squares relative normalised root-mean-square error.
• gls_proj_relative_nrmse::Float64: Generalised least squares projected relative normalised root-mean-square error.
• wls_nrmse::Float64: Weighted least squares normalised root-mean-square error.
• wls_proj_nrmse::Float64: Weighted least squares projected normalised root-mean-square error.
• wls_marginal_nrmse::Float64: Weighted least squares marginal normalised root-mean-square error.
• wls_proj_marginal_nrmse::Float64: Weighted least squares projected marginal normalised root-mean-square error.
• wls_relative_nrmse::Float64: Weighted least squares relative normalised root-mean-square error.
• wls_proj_relative_nrmse::Float64: Weighted least squares projected relative normalised root-mean-square error.
• ols_nrmse::Float64: Ordinary least squares normalised root-mean-square error.
• ols_proj_nrmse::Float64: Ordinary least squares projected normalised root-mean-square error.
• ols_marginal_nrmse::Float64: Ordinary least squares marginal normalised root-mean-square error.
• ols_proj_marginal_nrmse::Float64: Ordinary least squares projected marginal normalised root-mean-square error.
• ols_relative_nrmse::Float64: Ordinary least squares relative normalised root-mean-square error.
• ols_proj_relative_nrmse::Float64: Ordinary least squares projected relative normalised root-mean-square error.

NoiseEstimate

Noise estimate data structure.

Fields

• eigenvalues_experiment_ensemble::Vector{Vector{Vector{Float64}}}: Circuit eigenvalue estimates for each tuple and circuit eigenvalue.
• covariance_experiment_ensemble::Vector{Vector{Vector{Float64}}}: Covariance circuit eigenvalue estimates for each tuple and covariance circuit eigenvalue.
• shot_budget::Int: Shot budget for the (potentially randomised) experimental ensemble.
• gls_unproj_gate_eigenvalues::Vector{Float64}: Generalised least squares unprojected gate eigenvalues.
• gls_gate_eigenvalues::Vector{Float64}: Generalised least squares projected gate eigenvalues.
• gls_unproj_gate_probabilities::Dict{Gate, Vector{Float64}}: Generalised least squares unprojected gate error probabilities.
• gls_gate_probabilities::Dict{Gate, Vector{Float64}}: Generalised least squares projected gate error probabilities.
• gls_unproj_marginal_gate_eigenvalues::Vector{Float64}: Generalised least squares unprojected marginal gate eigenvalues.
• gls_marginal_gate_eigenvalues::Vector{Float64}: Generalised least squares projected marginal gate eigenvalues.
• gls_unproj_marginal_gate_probabilities::Dict{Gate, Vector{Float64}}: Generalised least squares unprojected marginal gate error probabilities.
• gls_marginal_gate_probabilities::Dict{Gate, Vector{Float64}}: Generalised least squares projected marginal gate error probabilities.
• gls_unproj_relative_gate_eigenvalues::Vector{Float64}: Generalised least squares unprojected relative gate eigenvalues.
• gls_relative_gate_eigenvalues::Vector{Float64}: Generalised least squares projected relative gate eigenvalues.
• wls_unproj_gate_eigenvalues::Vector{Float64}: Weighted least squares unprojected gate eigenvalues.
• wls_gate_eigenvalues::Vector{Float64}: Weighted least squares projected gate eigenvalues.
• wls_unproj_gate_probabilities::Dict{Gate, Vector{Float64}}: Weighted least squares unprojected gate error probabilities.
• wls_gate_probabilities::Dict{Gate, Vector{Float64}}: Weighted least squares projected gate error probabilities.
• wls_unproj_marginal_gate_eigenvalues::Vector{Float64}: Weighted least squares unprojected marginal gate eigenvalues.
• wls_marginal_gate_eigenvalues::Vector{Float64}: Weighted least squares projected marginal gate eigenvalues.
• wls_unproj_marginal_gate_probabilities::Dict{Gate, Vector{Float64}}: Weighted least squares unprojected marginal gate error probabilities.
• wls_marginal_gate_probabilities::Dict{Gate, Vector{Float64}}: Weighted least squares projected marginal gate error probabilities.
• wls_unproj_relative_gate_eigenvalues::Vector{Float64}: Weighted least squares unprojected relative gate eigenvalues.
• wls_relative_gate_eigenvalues::Vector{Float64}: Weighted least squares projected relative gate eigenvalues.
• ols_unproj_gate_eigenvalues::Vector{Float64}: Ordinary least squares unprojected gate eigenvalues.
• ols_gate_eigenvalues::Vector{Float64}: Ordinary least squares projected gate eigenvalues.
• ols_unproj_gate_probabilities::Dict{Gate, Vector{Float64}}: Ordinary least squares unprojected gate error probabilities.
• ols_gate_probabilities::Dict{Gate, Vector{Float64}}: Ordinary least squares projected gate error probabilities.
• ols_unproj_marginal_gate_eigenvalues::Vector{Float64}: Ordinary least squares unprojected marginal gate eigenvalues.
• ols_marginal_gate_eigenvalues::Vector{Float64}: Ordinary least squares projected marginal gate eigenvalues.
• ols_unproj_marginal_gate_probabilities::Dict{Gate, Vector{Float64}}: Ordinary least squares unprojected marginal gate error probabilities.
• ols_marginal_gate_probabilities::Dict{Gate, Vector{Float64}}: Ordinary least squares projected marginal gate error probabilities.
• ols_unproj_relative_gate_eigenvalues::Vector{Float64}: Ordinary least squares unprojected relative gate eigenvalues.
• ols_relative_gate_eigenvalues::Vector{Float64}: Ordinary least squares projected relative gate eigenvalues.

NoiseScore

Noise estimate error z-score data structure, containing the z-scores for a NoiseError with respect to some predicted Merit.

Fields

• gls_z_score::Float64: Generalised least squares z-score.
• gls_proj_z_score::Float64: Generalised least squares projected z-score.
• gls_marginal_z_score::Float64: Generalised least squares marginal z-score.
• gls_proj_marginal_z_score::Float64: Generalised least squares projected marginal z-score.
• gls_relative_z_score::Float64: Generalised least squares relative z-score.
• gls_proj_relative_z_score::Float64: Generalised least squares projected relative z-score.
• wls_z_score::Float64: Weighted least squares z-score.
• wls_proj_z_score::Float64: Weighted least squares projected z-score.
• wls_marginal_z_score::Float64: Weighted least squares marginal z-score.
• wls_proj_marginal_z_score::Float64: Weighted least squares projected marginal z-score.
• wls_relative_z_score::Float64: Weighted least squares relative z-score.
• wls_proj_relative_z_score::Float64: Weighted least squares projected relative z-score.
• ols_z_score::Float64: Ordinary least squares z-score.
• ols_proj_z_score::Float64: Ordinary least squares projected z-score.
• ols_marginal_z_score::Float64: Ordinary least squares marginal z-score.
• ols_proj_marginal_z_score::Float64: Ordinary least squares projected marginal z-score.
• ols_relative_z_score::Float64: Ordinary least squares relative z-score.
• ols_proj_relative_z_score::Float64: Ordinary least squares projected relative z-score.

calc_covariance(d::Design, noise_est::NoiseEstimate; weight_time::Bool = false)
calc_covariance(d_rand::RandDesign, noise_est::NoiseEstimate; weight_time::Bool = false)

Returns the estimated covariance matrix for a noise estimate noise_est associated with the design d or randomised design d_rand, weighting the shot budget by the time factor if weight_time is true.

estimate_gate_noise(d::Design, noise_est::NoiseEstimate; kwargs...)
estimate_gate_noise(d_rand::RandDesign, noise_est::NoiseEstimate; kwargs...)
estimate_gate_noise(d::Design, est_eigenvalues_experiment_ensemble::Vector{Vector{Vector{Float64}}}, est_covariance_experiment_ensemble::Vector{Vector{Vector{Float64}}}, shot_budget::Int; kwargs...)
estimate_gate_noise(d_rand::RandDesign, est_eigenvalues_experiment_ensemble::Vector{Vector{Vector{Float64}}}, est_covariance_experiment_ensemble::Vector{Vector{Vector{Float64}}}; kwargs...)

Returns a NoiseEstimate of the gate noise for the design d or randomised design d_rand derived from estimated circuit eigenvalues, either already contained in a noise estimate noise_est, or as estimated circuit eigenvalues est_eigenvalues_experiment_ensemble and covariance circuit eigenvalues est_covariance_experiment_ensemble, with shot budget shot_budget.

Arguments

• d::Design: Experimental design.
• d_rand::RandDesign: Randomised experimental design.
• noise_est::NoiseEstimate: Noise estimate.
• est_eigenvalues_experiment_ensemble::Vector{Vector{Vector{Float64}}}: Estimated ensemble of circuit eigenvalues.
• est_covariance_experiment_ensemble::Vector{Vector{Vector{Float64}}}: Estimated ensemble of covariance circuit eigenvalues.
• shot_budget::Int: Noise estimate shot budget.

Keword arguments

• min_eigenvalue::Float64 = 0.1: The minimum eigenvalue threshold for clipping.
• clip_warning::Bool = true: Whether to warn if eigenvalues are clipped.
• N_warn_split::Integer = 5 * 10^3: The number of gate eigenvalues above which to warn about splitting.
• split::Bool = (d.c.gate_data.N < N_warn_split ? false : true): Whether to split the gate eigenvalue projection across gates or simultaneously project all gate eigenvalues.
• split_warning::Bool = true: Whether to warn if the gate eigenvalue projection is not split.
• precision::Real = 1e-8: The solver precision for the gate eigenvalue projection.

get_aic(d::Design, noise_est::NoiseEstimate; projected::Bool = false)
get_aic(d_rand::RandDesign, noise_est::NoiseEstimate; projected::Bool = false)

Returns the Akaike information criterion (AIC) corresponding to the noise estimate noise_est, given the design d or alternatively the randomised design d_rand, calculating with the projected gate eigenvalues if projected is true.

get_bic(d::Design, noise_est::NoiseEstimate; projected::Bool = false)
get_bic(d_rand::RandDesign, noise_est::NoiseEstimate; projected::Bool = false)

Returns the Bayesian information criterion (BIC) corresponding to the noise estimate noise_est, given the design d or alternatively the randomised design d_rand, calculating with the projected gate eigenvalues if projected is true.

get_eigenvalues(noise_est::NoiseEstimate)

Returns the estimated circuit eigenvalues of noise estimate noise_est.

get_model_violation(d::Design, noise_est::NoiseEstimate; projected::Bool = false)
get_model_violation(d_rand::RandDesign, noise_est::NoiseEstimate; projected::Bool = false)
get_model_violation(d::Design, noise_est_vector::Vector{NoiseEstimate}; projected::Bool = false)
get_model_violation(d::Design, noise_est_matrix::Matrix{NoiseEstimate}; projected::Bool = false)

Returns the noise model violation z-score for the generalised residual sum of squares corresponding to the noise estimate noise_est, given the design d or alternatively the randomised design d_rand, calculating with the projected gate eigenvalues if projected is true.

get_noise_error(d::Design, noise_est::NoiseEstimate)
get_noise_error(d_rand::RandDesign, noise_est::NoiseEstimate)

Returns a NoiseError object containing the normalised root-mean-square errors (NRMSEs) for the gate noise estimates in noise_est and the true gate eigenvalues for the design d, or alternatively the randomised design d_rand.

get_noise_score(noise_error::NoiseError, merit::Merit)
get_noise_score(noise_error_vector::Vector{NoiseError}, merit::Merit)
get_noise_score(noise_error_matrix::Matrix{NoiseError}, merit::Merit)

Returns a NoiseScore object containing the z-scores for the supplied normalised root-mean-square error (NRMSE) data in noise_error given the merit merit.

get_rss(d::Design, noise_est::NoiseEstimate; projected::Bool = false)
get_rss(d_rand::RandDesign, noise_est::NoiseEstimate; projected::Bool = false)

Returns the generalised residual sum of squares corresponding to the noise estimate noise_est, given the design d or alternatively the randomised design d_rand, calculating with the projected gate eigenvalues if projected is true.

is_score_expected(noise_score::NoiseScore, z_score_cutoff::Real)
is_score_expected(noise_score::NoiseScore, z_score_cutoff_lower::Real, z_score_cutoff_upper::Real)

Returns a Boolean indicating whether the z-scores in noise_score are within the specified cutoffs, and projection improves the z-scores as expected.

estimate_experiment(counts::Union{Matrix{UInt8}, Dict{String, Int}}, experiment_meas_indices::Vector{Vector{Int}}, experiment_pauli_signs::Vector{Bool}, shots_value::Integer)

Returns the sample average estimator contributions estimated from the counts counts for the circuit eigenvalues measured at experiment_meas_indices whose Pauli mappings have signs experiment_pauli_signs, across shots_value samples.

estimate_gate_eigenvalues(design_matrix::SparseMatrixCSC{Float64, Int}, est_covariance_log_inv_factor::SparseMatrixCSC{Float64, Int}, est_eigenvalues::Vector{Float64}; constrain::Bool = false)
estimate_gate_eigenvalues(design_matrix::SparseMatrixCSC{Float64, Int}, est_eigenvalues::Vector{Float64}; constrain::Bool = false)

Returns the gate eigenvalues estimated from the estimated circuit eigenvalues est_eigenvalues by least squares inversion with the design matrix design_matrix, both weighted by the factor est_covariance_log_inv_factor if appropriate, constraining the gate eigenvalues to be at most 1 if constrain is true.

full_project_gate_eigenvalues(est_unproj_gate_eigenvalues::Vector{Float64}, est_precision_matrix::SparseMatrixCSC{Float64, Int64}, gate_data::GateData; precision::Real = 1e-8, diagnostics::Bool = false)

Returns the projection into the probability simplex of the gate eigenvalues est_unproj_gate_eigenvalues and the corresponding gate probabilities, projecting in the Mahalanobis distance using the precision matrix est_precision_matrix, with corresponding gate data gate_data. The solver precision is controlled by precision, and solver diagnostics are printed if diagnostics is true.

get_clipped_indices(est_eigenvalues::Vector{Float64}; min_eigenvalue::Real = 0.1, warning::Bool = true)

Returns clipped indices for the estimated circuit eigenvalues est_eigenvalues that not less than min_eigenvalue, warning if eigenvalues are clipped and warning is true.

get_clipped_mapping_lengths(mapping_lengths::Vector{Int}, clipped_indices::Vector{Int})

Returns updated mapping_lengths given the clipped indices clipped_indices.

get_covariance_experiment_data(d::Design, covariance_keys_ensemble::Vector{Vector{CartesianIndex{2}}}, covariance_key_indices_ensemble::Vector{Dict{CartesianIndex{2}, Int}}; qiskit_qubit_map::Union{Vector{Int}, Nothing} = nothing)

Returns the covariance experiment data for the design d, including the covariance experiment ensemble, covariance measurement indices ensemble, and covariance Pauli sign ensemble.

get_experiment_data(d::Design; qiskit_qubit_map::Union{Vector{Int}, Nothing} = nothing)

Returns the experiment data for the design d, including the experiment ensemble, measurement indices ensemble, and Pauli sign ensemble.

pauli_estimate(stim_counts::Matrix{UInt8}, pauli_meas_indices::Vector{Int}, shots_value::Integer)
pauli_estimate(qiskit_counts::Dict{String,Int}, pauli_meas_indices::Vector{Int}, shots_value::Integer)

Returns the sample average from the counts stim_counts or qiskit_counts of the Pauli operator measured at the indices pauli_meas_indices across shots_value samples.

Note that parse_qiskit_dict parses Qiskit formatted counts into Stim formatted counts.

simple_project_gate_eigenvalues(est_unproj_gate_eigenvalues::Vector{Float64}, gate_data::GateData)

Returns the projection into the probability simplex of the gate eigenvalues est_unproj_gate_eigenvalues and the corresponding gate probabilities, projecting in the Euclidean distance with corresponding gate data gate_data.

split_project_gate_eigenvalues(est_unproj_gate_eigenvalues::Vector{Float64}, est_precision_matrix::SparseMatrixCSC{Float64, Int64}, gate_data::GateData; precision::Real = 1e-8, diagnostics::Bool = false)

Returns the projection into the probability simplex of the gate eigenvalues est_unproj_gate_eigenvalues and the corresponding gate probabilities, projecting separately for each gate in the Mahalanobis distance using the relevant slice of the precision matrix est_precision_matrix, with corresponding gate data gate_data. The solver precision is controlled by precision, and solver diagnostics are printed if diagnostics is true.