merit.jl

Merit

Merit parameters for an experimental design.

Fields

• circuit_param::AbstractCircuitParameters: Circuit parameters.
• noise_param::AbstractNoiseParameters: Noise parameters.
• tuple_set_data::TupleSetData: TupleSetData object that generates the tuple set.
• tuple_times::Vector{Float64}: Time taken to implement the circuit corresponding to each tuple, normalised according to the basic tuple set.
• shot_weights::Vector{Float64}: Shot weights for each tuple in the set, which add to 1.
• experiment_numbers::Vector{Int}: Number of experiments for each tuple in the set.
• experiment_number::Int: Total number of experiments.
• N::Int: Number of gate eigenvalues.
• N_marginal::Int: Number of marginal gate eigenvalues.
• N_relative::Int: Number of relative precision marginal gate eigenvalues.
• G::Int: Total number of gates.
• gls_expectation::Float64: Expected normalised RMS error for the generalised least squares (GLS) gate eigenvalue estimator vector.
• gls_variance::Float64: Normalised RMS error variance for the GLS gate eigenvalue estimator vector.
• gls_cov_eigenvalues::Vector{Float64}: Eigenvalues of the GLS gate eigenvalue estimator covariance matrix.
• gls_marginal_expectation::Float64: Expected normalised RMS error for the marginal GLS gate eigenvalue estimator vector.
• gls_marginal_variance::Float64: Normalised RMS error variance for the marginal GLS gate eigenvalue estimator vector.
• gls_marginal_cov_eigenvalues::Vector{Float64}: Eigenvalues of the marginal GLS gate eigenvalue estimator covariance matrix.
• gls_relative_expectation::Float64: Expected normalised RMS error for the relative precision marginal GLS gate eigenvalue estimator vector.
• gls_relative_variance::Float64: Normalised RMS error variance for the relative precision marginal GLS gate eigenvalue estimator vector.
• gls_relative_cov_eigenvalues::Vector{Float64}: Eigenvalues of the relative precision marginal GLS gate eigenvalue estimator covariance matrix.
• wls_expectation::Float64: Expected normalised RMS error for the weighted least squares (WLS) gate eigenvalue estimator vector.
• wls_variance::Float64: Normalised RMS error variance for the WLS gate eigenvalue estimator vector.
• wls_cov_eigenvalues::Vector{Float64}: Eigenvalues of the WLS gate eigenvalue estimator covariance matrix.
• wls_marginal_expectation::Float64: Expected normalised RMS error for the marginal WLS gate eigenvalue estimator vector.
• wls_marginal_variance::Float64: Normalised RMS error variance for the marginal WLS gate eigenvalue estimator vector.
• wls_marginal_cov_eigenvalues::Vector{Float64}: Eigenvalues of the marginal WLS gate eigenvalue estimator covariance matrix.
• wls_relative_expectation::Float64: Expected normalised RMS error for the relative precision marginal WLS gate eigenvalue estimator vector.
• wls_relative_variance::Float64: Normalised RMS error variance for the relative precision marginal WLS gate eigenvalue estimator vector.
• wls_relative_cov_eigenvalues::Vector{Float64}: Eigenvalues of the relative precision marginal WLS gate eigenvalue estimator covariance matrix.
• ols_expectation::Float64: Expected normalised RMS error for the ordinary least squares (OLS) gate eigenvalue estimator vector.
• ols_variance::Float64: Normalised RMS error variance for the OLS gate eigenvalue estimator vector.
• ols_cov_eigenvalues::Vector{Float64}: Eigenvalues of the OLS gate eigenvalue estimator covariance matrix.
• ols_marginal_expectation::Float64: Expected normalised RMS error for the marginal OLS gate eigenvalue estimator vector.
• ols_marginal_variance::Float64: Normalised RMS error variance for the marginal OLS gate eigenvalue estimator vector.
• ols_marginal_cov_eigenvalues::Vector{Float64}: Eigenvalues of the marginal OLS gate eigenvalue estimator covariance matrix.
• ols_relative_expectation::Float64: Expected normalised RMS error for the relative precision marginal OLS gate eigenvalue estimator vector.
• ols_relative_variance::Float64: Normalised RMS error variance for the relative precision marginal OLS gate eigenvalue estimator vector.
• ols_relative_cov_eigenvalues::Vector{Float64}: Eigenvalues of the relative precision marginal OLS gate eigenvalue estimator covariance matrix.
• cond_num::Float64: Condition number of the design matrix, the ratio of the largest and smallest singular values.
• pinv_norm::Float64: Pseudoinverse norm of the design matrix, the inverse of the smallest singular value.

calc_covariance(d::Design; epsilon::Real = 1e-10, weight_time::Bool = true, warning::Bool = true)
calc_covariance(d::Design, gate_eigenvalues::Vector{Float64}; epsilon::Real = 1e-10, weight_time::Bool = true, warning::Bool = true)
calc_covariance(d::Design, eigenvalues_ensemble::Vector{Vector{Float64}}, covariance_ensemble::Vector{Vector{Float64}}; epsilon::Real = 1e-10, weight_time::Bool = true, warning::Bool = true)
calc_covariance(d::Design, eigenvalues_experiment_ensemble::Vector{Vector{Vector{Float64}}}, covariance_experiment_ensemble::Vector{Vector{Vector{Float64}}}; epsilon::Real = 1e-10, weight_time::Bool = true, warning::Bool = true)

Returns the circuit eigenvalue estimator covariance matrix for the design d with gate eigenvalues gate_eigenvalues, eigenvalue ensemble eigenvalues_ensemble, and covariance eigenvalue ensemble covariance_ensemble. Eigenvalue variances are set to a minimum value epsilon and the covariance matrix is adjusted by the times factor if weight_time is true, and if warning is true, warns that if d.full_covariance is false this will only generate the diagonal of the covariance matrix.

calc_covariance_log(covariance::SparseMatrixCSC{Float64, Int}, eigenvalues::Vector{Float64})
calc_covariance_log(d::Design; warning::Bool = true)

Returns the covariance matrix of the circuit log-eigenvalues corresponding to the circuit eigenvalues eigenvalues with covariance matrix covariance, using values generated from the design d and, if warning is true, warns that if d.full_covariance is false then this will only generate the diagonal of the covariance matrix.

calc_gate_probabilities_covariance(d::Design; ls_type::Symbol = :gls, est_type::Symbol = :ordinary, unpad::Bool = false)
calc_gate_probabilities_covariance(d::Design, covariance_log::SparseMatrixCSC{Float64, Int}; ls_type::Symbol = :gls, est_type::Symbol = :ordinary, unpad::Bool = false)

Returns the padded gate error probabilities estimator covariance matrix for the least squares estimator specified by ls_type (:gls, :wls, or :ols) corresponding to the design d with circuit log-eigenvalue estimator covariance matrix covariance_log, with estimator type est_type (:ordinary, :marginal, or :relative). Instead returns the unpadded gate error probabilities estimator covariance matrix if unpad is true, which is stripped of the covariance with the identity error probabilities.

calc_gls_covariance(d::Design)
calc_gls_covariance(d::Design, covariance_log::SparseMatrixCSC{Float64, Int})

Returns the gate eigenvalue estimator covariance matrix for the generalised least squares (GLS) estimator corresponding to the design d with circuit log-eigenvalue estimator covariance matrix covariance_log.

calc_gls_moments(d::Design; est_type::Symbol = :ordinary)
calc_gls_moments(d::Design, covariance_log::SparseMatrixCSC{Float64, Int}; est_type::Symbol = :ordinary)

Returns the expectation and variance of the normalised RMS error for the generalised least squares (GLS) estimator corresponding to the design d with circuit log-eigenvalue estimator covariance matrix covariance_log, with estimator type est_type (:ordinary, :marginal, or :relative).

calc_ls_covariance(d::Design; ls_type::Symbol = :gls, est_type::Symbol = :ordinary)
calc_ls_covariance(d::Design, covariance_log::SparseMatrixCSC{Float64, Int}; ls_type::Symbol = :gls, est_type::Symbol = :ordinary)

Returns the gate eigenvalue estimator covariance matrix for the least squares estimator specified by ls_type (:gls, :wls, or :ols) corresponding to the design d with circuit log-eigenvalue estimator covariance matrix covariance_log, with estimator type est_type (:ordinary, :marginal, or :relative).

calc_ls_moments(d::Design; ls_type::Symbol = :gls, est_type::Symbol = :ordinary, est_weight::Float64 = 0.5)
calc_ls_moments(d::Design, covariance_log::SparseMatrixCSC{Float64, Int}; ls_type::Symbol = :gls, est_type::Symbol = :ordinary, est_weight::Float64 = 0.5)

Returns the expectation and variance of the normalised RMS error for the least squares estimator specified by ls_type (:gls, :wls, or :ols) corresponding to the design d with circuit log-eigenvalue estimator covariance matrix covariance_log, with estimator type est_type (:ordinary, :marginal, or :relative). If est_type is instead set to :sum or :prod, computes the arithmetic or geometric mean of the ordinary and relative precision moments, weighted by est_weight, the weighting allocated to the ordinary precision moments.

calc_merit(d::Design; warning::Bool = true)
calc_merit(d_rand::RandDesign; warning::Bool = true)

Returns a Merit object corresponding to the design d or randomised design d_rand, displaying a warning if the design does not have full covariance matrix data and warning is true.

calc_ols_covariance(d::Design)
calc_ols_covariance(d::Design, covariance_log::SparseMatrixCSC{Float64, Int})

Returns the gate eigenvalue estimator covariance matrix for the ordinary least squares (OLS) estimator corresponding to the design d with circuit log-eigenvalue estimator covariance matrix covariance_log.

calc_ols_moments(d::Design; est_type::Symbol = :ordinary)
calc_ols_moments(d::Design, covariance_log::SparseMatrixCSC{Float64, Int}; est_type::Symbol = :ordinary)

Returns the expectation and variance of the normalised RMS error for the ordinary least squares (OLS) estimator corresponding to the design d with circuit log-eigenvalue estimator covariance matrix covariance_log, with estimator type est_type (:ordinary, :marginal, or :relative).

calc_precision_matrix(design_matrix::SparseMatrixCSC{Float64, Int}, gate_eigenvalues::Vector{Float64}, covariance_log_inv::SparseMatrixCSC{Float64, Int})
calc_precision_matrix(d::Design, gate_eigenvalues::Vector{Float64}; diagonal::Bool = false)
calc_precision_matrix(d::Design; diagonal::Bool = false)

Returns the precision matrix, namely the inverse of the generalised least squares gate eigenvalue estimator covariance matrix, corresponding to the design d with design matrix design_matrix, gate eigenvalues gate_eigenvalues and circuit log-eigenvalue estimator covariance matrix inverse covariance_log_inv. Ordinarily this yields the precision matrix for generalise least squares, but if diagonal is true it calculates the inverse of the diagonal of the covariance matrix, rather than the inverse of the full matrix, yielding the precision matrix for both generalised and weighted least squares if the circuit eigenvalue estimators were uncorrelated.

calc_wls_covariance(d::Design)
calc_wls_covariance(d::Design, covariance_log::SparseMatrixCSC{Float64, Int})

Returns the gate eigenvalue estimator covariance matrix for the weighted least squares (WLS) estimator corresponding to the design d with circuit log-eigenvalue estimator covariance matrix covariance_log.

calc_wls_moments(d::Design; est_type::Symbol = :ordinary)
calc_wls_moments(d::Design, covariance_log::SparseMatrixCSC{Float64, Int}; est_type::Symbol = :ordinary)

Returns the expectation and variance of the normalised RMS error for the weighted least squares (WLS) estimator corresponding to the design d with circuit log-eigenvalue estimator covariance matrix covariance_log, with estimator type est_type (:ordinary, :marginal, or :relative).

get_marginal_gate_covariance(d::Design, gate_eigenvalues_cov::Symmetric{Float64, Matrix{Float64}})

Returns the marginal gate eigenvalue estimator covariance matrix corresponding to the gate eigenvalue estimator covariance matrix gate_eigenvalues_cov for the design d.

get_pad_transform(d::Design, est_type::Symbol; probabilities::Bool = false)

Returns a transform matrix that pads gate eigenvalues, or gate error probabilities if probabilities is true, whose type depends on the estimator type est_type (:ordinary, :marginal, or :relative), with identity eigenvaleus or error probabilities, respectively, calculated using the gate data of the design d.

get_relative_gate_covariance(d::Design, gate_eigenvalues_cov::Symmetric{Float64, Matrix{Float64}})

Returns the relative gate eigenvalue estimator covariance matrix corresponding to the gate eigenvalue estimator covariance matrix gate_eigenvalues_cov for the design d.

get_transform(d::Design, est_type::Symbol)

Returns a transform matrix that maps gate eigenvalues to gate eigenvalues of type depending on the estimator type est_type (:ordinary, :marginal, or :relative), calculated using the gate data of the design d.

get_wht_transform(d::Design, est_type::Symbol; inverse::Bool = false)

Returns a transform matrix that maps padded gate error probabilities to padded gate eigenvalues, or the inverse transform if inverse is true, whose type depends on the estimator type est_type (:ordinary, :marginal, or:relative), calculated using the gate data of the designd`.

nrmse_pdf(cov_eigenvalues::Vector{Float64}, nrmse_values::Vector{Float64}; epsilon::Real = 1e-5)

Returns the probability density function (PDF) for the normalised RMS error (NRMSE) of the gate eigenvalue estimator vector, which follows a generalised chi-squared distribution and whose covariance matrix has eigenvalues cov_eigenvalues, at the coordinates specified by nrmse_values. Does not calculate values when the normal approximation to the PDF is less than a factor of epsilon of its maximum value.

Calculation follows Eq. 3.2 of Computing the distribution of quadratic forms in normal variables by J. P. Imhof (1961).

sparse_covariance_inv(covariance_log::SparseMatrixCSC{Float64, Int}, mapping_lengths::Vector{Int}; epsilon::Real = 1e-12, warning::Bool = true)

Returns the inverse of the sparse block diagonal circuit log-eigenvalue estimator covariance matrix covariance_log, where the block sizes are specified by mapping_lengths, ensuring a smallest eigenvalue epsilon if the Cholesky factorisation fails, and warning if warning is true.

calc_covariance_eigenvalues(d::Design)
calc_covariance_eigenvalues(d::Design, gate_eigenvalues::Vector{Float64})

Returns the covariance matrix eigenvalue ensemble for the design d with gate eigenvalues gate_eigenvalues.

get_covariance_mapping_data(d::Design)

Returns covariance matrix mapping index data for the design d.

nrmse_moments(gate_eigenvalues_cov::Symmetric{Float64, Matrix{Float64}})    
nrmse_moments(gate_eigenvalues_cov_eigenvalues::Vector{Float64})

Returns the expectation and variance of the normalised RMS error, as determined either by the gate eigenvalue estimator covariance matrix gate_eigenvalues_cov or its eigenvalues gate_eigenvalues_cov_eigenvalues.

nrmse_pdf_integrand(u::Float64, x::Float64, norm_cov_eigenvalues::Vector{Float64})

Returns the integrand of the Imhof method CDF for the distribution of the NRMSE.

Calculation follows Eq. 3.2 of Computing the distribution of quadratic forms in normal variables by J. P. Imhof (1961).

sparse_covariance_inv_factor(covariance_log::SparseMatrixCSC{Float64, Int}, mapping_lengths::Vector{Int}; epsilon::Real = 1e-12, warning::Bool = true)

Returns the inverse of the lower Cholesky factor of the sparse block diagonal circuit log-eigenvalue estimator covariance matrix covariance_log, where the block sizes are specified by mapping_lengths, ensuring a smallest eigenvalue epsilon if the Cholesky factorisation fails, and warning if warning is true.