From cfb4337740c39180d22b297c3bf584eb47082374 Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Thu, 3 Sep 2026 10:28:14 -0400 Subject: [PATCH 01/15] add pkg name and box link --- scripts/config/api-html-artifacts.json | 3 +++ scripts/js/lib/api/Pkg.ts | 10 ++++++++++ 2 files changed, 13 insertions(+) diff --git a/scripts/config/api-html-artifacts.json b/scripts/config/api-html-artifacts.json index 2ab461d8eb8e..cea0fcc878c5 100644 --- a/scripts/config/api-html-artifacts.json +++ b/scripts/config/api-html-artifacts.json @@ -136,6 +136,9 @@ "qiskit-addon-slc": { "0.1": "https://ibm.box.com/shared/static/87gic8sr1vc85y4g6g1h0x6gk1eb1sqw.zip" }, + "qiskit-noise-learning": { + "0.1": "https://ibm.box.com/shared/static/pv4b1gvfivkbsceup6kkveov15k0naqi.zip" + }, "qiskit-addon-utils": { "0.4": "https://ibm.box.com/shared/static/j9qms9f2wfzo7fdfwnm2ns8rdjrhje7h.zip", "0.3": "https://ibm.box.com/shared/static/921yb7b7162e20a9b7ojgzhc1erxhgzd.zip", diff --git a/scripts/js/lib/api/Pkg.ts b/scripts/js/lib/api/Pkg.ts index 06c2ec7ec703..b0c9ea76f32a 100644 --- a/scripts/js/lib/api/Pkg.ts +++ b/scripts/js/lib/api/Pkg.ts @@ -74,6 +74,7 @@ export class Pkg { "qiskit-fermions-c", "pauli-prop", "qiskit-addon-slc", + "qiskit-noise-learning", ]; static VALID_NAMES = [ @@ -290,6 +291,15 @@ export class Pkg { language: "Python", }); } + if (name === "qiskit-noise-learning") { + return new Pkg({ + ...args, + title: "Qiskit noise liearning", + githubSlug: "Qiskit/qiskit-noise-learning", + kebabCaseAndShortenUrls: true, + language: "Python", + }); + } if (name === "qiskit-c") { return new Pkg({ From 630147c4ec7412bda43cce17157d3498ddcdfb83 Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Thu, 3 Sep 2026 10:31:06 -0400 Subject: [PATCH 02/15] npm run gen-api -- -p qiskit-noise-learning -v 0.1.0 --- docs/api/qiskit-noise-learning/_package.json | 4 + docs/api/qiskit-noise-learning/_toc.json | 71 ++++++++++++++++++ .../qiskit-noise-learning/aer-executor.mdx | 31 ++++++++ docs/api/qiskit-noise-learning/analysis.mdx | 38 ++++++++++ .../circuit-generator.mdx | 25 ++++++ docs/api/qiskit-noise-learning/data.mdx | 28 +++++++ .../experiment-builder.mdx | 39 ++++++++++ docs/api/qiskit-noise-learning/gate-sets.mdx | 29 +++++++ docs/api/qiskit-noise-learning/index.mdx | 19 +++++ docs/api/qiskit-noise-learning/math.mdx | 29 +++++++ docs/api/qiskit-noise-learning/models.mdx | 46 ++++++++++++ .../qiskit-noise-learning/noise-learner.mdx | 29 +++++++ docs/api/qiskit-noise-learning/sequences.mdx | 36 +++++++++ .../qiskit-noise-learning/visualizations.mdx | 26 +++++++ .../api/qiskit-noise-learning/objects.inv | Bin 0 -> 6206 bytes .../config/historical-pages-to-latest.json | 4 +- 16 files changed, 453 insertions(+), 1 deletion(-) create mode 100644 docs/api/qiskit-noise-learning/_package.json create mode 100644 docs/api/qiskit-noise-learning/_toc.json create mode 100644 docs/api/qiskit-noise-learning/aer-executor.mdx create mode 100644 docs/api/qiskit-noise-learning/analysis.mdx create mode 100644 docs/api/qiskit-noise-learning/circuit-generator.mdx create mode 100644 docs/api/qiskit-noise-learning/data.mdx create mode 100644 docs/api/qiskit-noise-learning/experiment-builder.mdx create mode 100644 docs/api/qiskit-noise-learning/gate-sets.mdx create mode 100644 docs/api/qiskit-noise-learning/index.mdx create mode 100644 docs/api/qiskit-noise-learning/math.mdx create mode 100644 docs/api/qiskit-noise-learning/models.mdx create mode 100644 docs/api/qiskit-noise-learning/noise-learner.mdx create mode 100644 docs/api/qiskit-noise-learning/sequences.mdx create mode 100644 docs/api/qiskit-noise-learning/visualizations.mdx create mode 100644 public/docs/api/qiskit-noise-learning/objects.inv diff --git a/docs/api/qiskit-noise-learning/_package.json b/docs/api/qiskit-noise-learning/_package.json new file mode 100644 index 000000000000..f4ee5149b7ba --- /dev/null +++ b/docs/api/qiskit-noise-learning/_package.json @@ -0,0 +1,4 @@ +{ + "name": "qiskit-noise-learning", + "version": "0.1.0" +} diff --git a/docs/api/qiskit-noise-learning/_toc.json b/docs/api/qiskit-noise-learning/_toc.json new file mode 100644 index 000000000000..74b66d53397e --- /dev/null +++ b/docs/api/qiskit-noise-learning/_toc.json @@ -0,0 +1,71 @@ +{ + "title": "Qiskit noise liearning", + "children": [ + { + "title": "API index", + "url": "/docs/api/qiskit-noise-learning" + }, + { + "title": "Release notes", + "useDivider": true, + "url": "/docs/api/qiskit-noise-learning/release-notes" + }, + { + "title": "qiskit_noise_learning.aer_executor", + "url": "/docs/api/qiskit-noise-learning/aer-executor", + "untranslatable": true + }, + { + "title": "qiskit_noise_learning.analysis", + "url": "/docs/api/qiskit-noise-learning/analysis", + "untranslatable": true + }, + { + "title": "qiskit_noise_learning.circuit_generator", + "url": "/docs/api/qiskit-noise-learning/circuit-generator", + "untranslatable": true + }, + { + "title": "qiskit_noise_learning.data", + "url": "/docs/api/qiskit-noise-learning/data", + "untranslatable": true + }, + { + "title": "qiskit_noise_learning.experiment_builder", + "url": "/docs/api/qiskit-noise-learning/experiment-builder", + "untranslatable": true + }, + { + "title": "qiskit_noise_learning.gate_sets", + "url": "/docs/api/qiskit-noise-learning/gate-sets", + "untranslatable": true + }, + { + "title": "qiskit_noise_learning.math", + "url": "/docs/api/qiskit-noise-learning/math", + "untranslatable": true + }, + { + "title": "qiskit_noise_learning.models", + "url": "/docs/api/qiskit-noise-learning/models", + "untranslatable": true + }, + { + "title": "qiskit_noise_learning.noise_learner", + "url": "/docs/api/qiskit-noise-learning/noise-learner", + "untranslatable": true + }, + { + "title": "qiskit_noise_learning.sequences", + "url": "/docs/api/qiskit-noise-learning/sequences", + "untranslatable": true + }, + { + "title": "qiskit_noise_learning.visualizations", + "url": "/docs/api/qiskit-noise-learning/visualizations", + "untranslatable": true + } + ], + "collapsed": true, + "untranslatable": true +} diff --git a/docs/api/qiskit-noise-learning/aer-executor.mdx b/docs/api/qiskit-noise-learning/aer-executor.mdx new file mode 100644 index 000000000000..b9922a704770 --- /dev/null +++ b/docs/api/qiskit-noise-learning/aer-executor.mdx @@ -0,0 +1,31 @@ +--- +title: aer_executor (latest version) +description: API reference for qiskit_noise_learning.aer_executor in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 2 +python_api_type: module +python_api_name: qiskit_noise_learning.aer_executor +--- + + + + + +# Aer executor + +`qiskit_noise_learning.aer_executor` + +Aer-based local executor for QuantumProgram objects. + +## Classes + +| | | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| [`AerExecutor`](generated/aer-executor-aer-executor#qiskit_noise_learning.aer_executor.AerExecutor "qiskit_noise_learning.aer_executor.AerExecutor") | Local Aer-based executor mimicking the IBM Runtime executor interface. | +| [`AerRuntimeJob`](generated/aer-executor-aer-runtime-job#qiskit_noise_learning.aer_executor.AerRuntimeJob "qiskit_noise_learning.aer_executor.AerRuntimeJob") | Job object returned by [`AerExecutor.run()`](generated/aer-executor-aer-executor#qiskit_noise_learning.aer_executor.AerExecutor.run "qiskit_noise_learning.aer_executor.AerExecutor.run"). | + +## Functions + +| | | +| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | +| [`inline_samplexes`](generated/aer-executor-inline-samplexes#qiskit_noise_learning.aer_executor.inline_samplexes "qiskit_noise_learning.aer_executor.inline_samplexes")(program\[, omit, rng]) | Return a new `QuantumProgram` with `SamplexItem`s resolved in-place. | + diff --git a/docs/api/qiskit-noise-learning/analysis.mdx b/docs/api/qiskit-noise-learning/analysis.mdx new file mode 100644 index 000000000000..e07a2294e0bb --- /dev/null +++ b/docs/api/qiskit-noise-learning/analysis.mdx @@ -0,0 +1,38 @@ +--- +title: analysis (latest version) +description: API reference for qiskit_noise_learning.analysis in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 2 +python_api_type: module +python_api_name: qiskit_noise_learning.analysis +--- + + + + + +# Analysis + +`qiskit_noise_learning.analysis` + +Data analysis. + +## Classes + +| | | +| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`AnalysisPipeline`](generated/analysis-analysis-pipeline#qiskit_noise_learning.analysis.AnalysisPipeline "qiskit_noise_learning.analysis.AnalysisPipeline") | A composite [`AnalysisStage`](generated/analysis-analysis-stage#qiskit_noise_learning.analysis.AnalysisStage "qiskit_noise_learning.analysis.AnalysisStage") that chains stages sequentially. | +| [`AnalysisStage`](generated/analysis-analysis-stage#qiskit_noise_learning.analysis.AnalysisStage "qiskit_noise_learning.analysis.AnalysisStage") | Abstract base for a stage in the analysis pipeline. | +| [`AverageObservables`](generated/analysis-average-observables#qiskit_noise_learning.analysis.AverageObservables "qiskit_noise_learning.analysis.AverageObservables") | Average observables over randomizations for each unbound path and fragment depth pair. | +| [`ComputeObservables`](generated/analysis-compute-observables#qiskit_noise_learning.analysis.ComputeObservables "qiskit_noise_learning.analysis.ComputeObservables") | Compute observable data from raw data. | +| [`CurveFitObservables`](generated/analysis-curve-fit-observables#qiskit_noise_learning.analysis.CurveFitObservables "qiskit_noise_learning.analysis.CurveFitObservables") | Fit observable data to exponential decays of the form `a * f**fragment_depth`, and average any remaining observables over randomizations. | +| [`Fit`](generated/analysis-fit#qiskit_noise_learning.analysis.Fit "qiskit_noise_learning.analysis.Fit") | Container for data at each level of the analysis hierarchy. | +| [`FlipPostSelect`](generated/analysis-flip-post-select#qiskit_noise_learning.analysis.FlipPostSelect "qiskit_noise_learning.analysis.FlipPostSelect") | Apply a mask to raw data based on bit flips across measurement outcomes. | +| [`LegacySolve`](generated/analysis-legacy-solve#qiskit_noise_learning.analysis.LegacySolve "qiskit_noise_learning.analysis.LegacySolve") | Solves for the [`ModelData`](generated/data-model-data#qiskit_noise_learning.data.ModelData "qiskit_noise_learning.data.ModelData") using the legacy pair-fidelity method. | +| [`LinearSystemData`](generated/analysis-linear-system-data#qiskit_noise_learning.analysis.LinearSystemData "qiskit_noise_learning.analysis.LinearSystemData") | The linear system to solve and metadata in raw format. | +| [`LSQLinearSolve`](generated/analysis-lsq-linear-solve#qiskit_noise_learning.analysis.LSQLinearSolve "qiskit_noise_learning.analysis.LSQLinearSolve") | Solves for the [`ModelData`](generated/data-model-data#qiskit_noise_learning.data.ModelData "qiskit_noise_learning.data.ModelData") using SciPy's linear least squares solver. | +| [`NNLSSolve`](generated/analysis-nnls-solve#qiskit_noise_learning.analysis.NNLSSolve "qiskit_noise_learning.analysis.NNLSSolve") | Solves for the [`ModelData`](generated/data-model-data#qiskit_noise_learning.data.ModelData "qiskit_noise_learning.data.ModelData") using SciPy's non-negative least squares solver. | +| [`PositivityMinSolve`](generated/analysis-positivity-min-solve#qiskit_noise_learning.analysis.PositivityMinSolve "qiskit_noise_learning.analysis.PositivityMinSolve") | Solves for the [`ModelData`](generated/data-model-data#qiskit_noise_learning.data.ModelData "qiskit_noise_learning.data.ModelData") while minimizing Pauli-Lindblad rate positivity. | +| [`SymmetrizeFidelities`](generated/analysis-symmetrize-fidelities#qiskit_noise_learning.analysis.SymmetrizeFidelities "qiskit_noise_learning.analysis.SymmetrizeFidelities") | Project generator rates into the fidelity-symmetry null space, gate by gate. | +| [`SymmetrizeGenerators`](generated/analysis-symmetrize-generators#qiskit_noise_learning.analysis.SymmetrizeGenerators "qiskit_noise_learning.analysis.SymmetrizeGenerators") | Project generator rates to satisfy conjugation symmetry, gate by gate. | +| [`ZeroPostSelect`](generated/analysis-zero-post-select#qiskit_noise_learning.analysis.ZeroPostSelect "qiskit_noise_learning.analysis.ZeroPostSelect") | Apply a mask to raw data based on whether bit values are all False. | + diff --git a/docs/api/qiskit-noise-learning/circuit-generator.mdx b/docs/api/qiskit-noise-learning/circuit-generator.mdx new file mode 100644 index 000000000000..d5eaeb2fbeae --- /dev/null +++ b/docs/api/qiskit-noise-learning/circuit-generator.mdx @@ -0,0 +1,25 @@ +--- +title: circuit_generator (latest version) +description: API reference for qiskit_noise_learning.circuit_generator in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 2 +python_api_type: module +python_api_name: qiskit_noise_learning.circuit_generator +--- + + + + + +# Circuit generator + +`qiskit_noise_learning.circuit_generator` + +Executor circuit generator. + +## Classes + +| | | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | +| [`ExecutorCircuitGenerator`](generated/circuit-generator-executor-circuit-generator#qiskit_noise_learning.circuit_generator.ExecutorCircuitGenerator "qiskit_noise_learning.circuit_generator.ExecutorCircuitGenerator") | A circuit generator that converts sequences of Qiskit gates into a samplex items. | +| [`ExecutorDataMapper`](generated/circuit-generator-executor-data-mapper#qiskit_noise_learning.circuit_generator.ExecutorDataMapper "qiskit_noise_learning.circuit_generator.ExecutorDataMapper") | Map executor results into standard results. | + diff --git a/docs/api/qiskit-noise-learning/data.mdx b/docs/api/qiskit-noise-learning/data.mdx new file mode 100644 index 000000000000..076ef67e7be9 --- /dev/null +++ b/docs/api/qiskit-noise-learning/data.mdx @@ -0,0 +1,28 @@ +--- +title: data (latest version) +description: API reference for qiskit_noise_learning.data in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 2 +python_api_type: module +python_api_name: qiskit_noise_learning.data +--- + + + + + +# Data + +`qiskit_noise_learning.data` + +Data containers. + +## Classes + +| | | +| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| [`AggregatedObservableData`](generated/data-aggregated-observable-data#qiskit_noise_learning.data.AggregatedObservableData "qiskit_noise_learning.data.AggregatedObservableData") | Per-path estimates obtained by aggregating [`ObservableData`](generated/data-observable-data#qiskit_noise_learning.data.ObservableData "qiskit_noise_learning.data.ObservableData"). | +| [`LeveledData`](generated/data-leveled-data#qiskit_noise_learning.data.LeveledData "qiskit_noise_learning.data.LeveledData") | Marker base class for data at a specific level of the analysis hierarchy. | +| [`ModelData`](generated/data-model-data#qiskit_noise_learning.data.ModelData "qiskit_noise_learning.data.ModelData") | Results from fitting, backed by an xarray Dataset. | +| [`ObservableData`](generated/data-observable-data#qiskit_noise_learning.data.ObservableData "qiskit_noise_learning.data.ObservableData") | A collection of calculated expectation values. | +| [`RawData`](generated/data-raw-data#qiskit_noise_learning.data.RawData "qiskit_noise_learning.data.RawData") | Raw experimental outcome data associated with instruction sequences and classical registers. | + diff --git a/docs/api/qiskit-noise-learning/experiment-builder.mdx b/docs/api/qiskit-noise-learning/experiment-builder.mdx new file mode 100644 index 000000000000..93f4139ec758 --- /dev/null +++ b/docs/api/qiskit-noise-learning/experiment-builder.mdx @@ -0,0 +1,39 @@ +--- +title: experiment_builder (latest version) +description: API reference for qiskit_noise_learning.experiment_builder in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 2 +python_api_type: module +python_api_name: qiskit_noise_learning.experiment_builder +--- + + + + + +# Experiment builder + +`qiskit_noise_learning.experiment_builder` + +Experiment builder. + +## Classes + +| | | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`Experiment`](generated/experiment-builder-experiment#qiskit_noise_learning.experiment_builder.Experiment "qiskit_noise_learning.experiment_builder.Experiment") | A learning experiment specification. | +| [`ExperimentBuilder`](generated/experiment-builder-experiment-builder#qiskit_noise_learning.experiment_builder.ExperimentBuilder "qiskit_noise_learning.experiment_builder.ExperimentBuilder") | A composite [`ExperimentBuilderStage`](generated/experiment-builder-experiment-builder-stage#qiskit_noise_learning.experiment_builder.ExperimentBuilderStage "qiskit_noise_learning.experiment_builder.ExperimentBuilderStage") that chains stages sequentially. | +| [`ExperimentBuilderStage`](generated/experiment-builder-experiment-builder-stage#qiskit_noise_learning.experiment_builder.ExperimentBuilderStage "qiskit_noise_learning.experiment_builder.ExperimentBuilderStage") | Abstract base for a stage in the experiment-building pipeline. | +| [`AddInstructionSequences`](generated/experiment-builder-add-instruction-sequences#qiskit_noise_learning.experiment_builder.AddInstructionSequences "qiskit_noise_learning.experiment_builder.AddInstructionSequences") | Add instruction sequences to an experiment. | +| [`AddPaths`](generated/experiment-builder-add-paths#qiskit_noise_learning.experiment_builder.AddPaths "qiskit_noise_learning.experiment_builder.AddPaths") | Add paths to an experiment. | +| [`BindFragmentDepths`](generated/experiment-builder-bind-fragment-depths#qiskit_noise_learning.experiment_builder.BindFragmentDepths "qiskit_noise_learning.experiment_builder.BindFragmentDepths") | Expand unbound instruction sequences at the given fragment depths. | +| [`CompleteSequences`](generated/experiment-builder-complete-sequences#qiskit_noise_learning.experiment_builder.CompleteSequences "qiskit_noise_learning.experiment_builder.CompleteSequences") | Complete all instruction sequences. | +| [`Depth1Paths`](generated/experiment-builder-depth-1-paths#qiskit_noise_learning.experiment_builder.Depth1Paths "qiskit_noise_learning.experiment_builder.Depth1Paths") | Generate depth-1 paths for each target gate. | +| [`EvenDepthPaths`](generated/experiment-builder-even-depth-paths#qiskit_noise_learning.experiment_builder.EvenDepthPaths "qiskit_noise_learning.experiment_builder.EvenDepthPaths") | Generate unbound paths with repetitions of two applications of each target gate. | +| [`EvenDepthVanillaPaths`](generated/experiment-builder-even-depth-vanilla-paths#qiskit_noise_learning.experiment_builder.EvenDepthVanillaPaths "qiskit_noise_learning.experiment_builder.EvenDepthVanillaPaths") | Generate unbound vanilla paths with repetitions of two gate applications. | +| [`GenerateInstructionSequences`](generated/experiment-builder-generate-instruction-sequences#qiskit_noise_learning.experiment_builder.GenerateInstructionSequences "qiskit_noise_learning.experiment_builder.GenerateInstructionSequences") | Generate one instruction sequence per path via [`to_instruction_sequence()`](generated/sequences-path#qiskit_noise_learning.sequences.Path.to_instruction_sequence "qiskit_noise_learning.sequences.Path.to_instruction_sequence"). | +| [`IdentifyRelations`](generated/experiment-builder-identify-relations#qiskit_noise_learning.experiment_builder.IdentifyRelations "qiskit_noise_learning.experiment_builder.IdentifyRelations") | Identify new relations amongst existing paths and instruction sequences. | +| [`MergeInstructionSequences`](generated/experiment-builder-merge-instruction-sequences#qiskit_noise_learning.experiment_builder.MergeInstructionSequences "qiskit_noise_learning.experiment_builder.MergeInstructionSequences") | Merge instruction sequences into a smaller set. | +| [`RankReducePaths`](generated/experiment-builder-rank-reduce-paths#qiskit_noise_learning.experiment_builder.RankReducePaths "qiskit_noise_learning.experiment_builder.RankReducePaths") | Reduce the paths to a maximal linearly independent set. | +| [`SPAMPaths`](generated/experiment-builder-spam-paths#qiskit_noise_learning.experiment_builder.SPAMPaths "qiskit_noise_learning.experiment_builder.SPAMPaths") | Generate depth-0 paths. | +| [`VanillaInstructionSequences`](generated/experiment-builder-vanilla-instruction-sequences#qiskit_noise_learning.experiment_builder.VanillaInstructionSequences "qiskit_noise_learning.experiment_builder.VanillaInstructionSequences") | Generate vanilla instruction sequences for each target gate. | + diff --git a/docs/api/qiskit-noise-learning/gate-sets.mdx b/docs/api/qiskit-noise-learning/gate-sets.mdx new file mode 100644 index 000000000000..62937f8c7624 --- /dev/null +++ b/docs/api/qiskit-noise-learning/gate-sets.mdx @@ -0,0 +1,29 @@ +--- +title: gate_sets (latest version) +description: API reference for qiskit_noise_learning.gate_sets in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 2 +python_api_type: module +python_api_name: qiskit_noise_learning.gate_sets +--- + + + + + +# Gate sets + +`qiskit_noise_learning.gate_sets` + +Gate sets. + +## Classes + +| | | +| ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`Gate`](generated/gate-sets-gate#qiskit_noise_learning.gate_sets.Gate "qiskit_noise_learning.gate_sets.Gate") | Represents qubit metadata for a single gate in a gate set. | +| [`GateSet`](generated/gate-sets-gate-set#qiskit_noise_learning.gate_sets.GateSet "qiskit_noise_learning.gate_sets.GateSet") | A mapping of names to gates with qubit metadata. | +| [`ModelGate`](generated/gate-sets-model-gate#qiskit_noise_learning.gate_sets.ModelGate "qiskit_noise_learning.gate_sets.ModelGate") | A model for a gate of the form Clifford - MCM - reset. | +| [`ModelGateSet`](generated/gate-sets-model-gate-set#qiskit_noise_learning.gate_sets.ModelGateSet "qiskit_noise_learning.gate_sets.ModelGateSet") | A set of Clifford - MCM - reset gates represented as [`ModelGate`](generated/gate-sets-model-gate#qiskit_noise_learning.gate_sets.ModelGate "qiskit_noise_learning.gate_sets.ModelGate") instances. | +| [`QiskitGate`](generated/gate-sets-qiskit-gate#qiskit_noise_learning.gate_sets.QiskitGate "qiskit_noise_learning.gate_sets.QiskitGate") | Represents a single gate in a [`QiskitGateSet`](generated/gate-sets-qiskit-gate-set#qiskit_noise_learning.gate_sets.QiskitGateSet "qiskit_noise_learning.gate_sets.QiskitGateSet"). | +| [`QiskitGateSet`](generated/gate-sets-qiskit-gate-set#qiskit_noise_learning.gate_sets.QiskitGateSet "qiskit_noise_learning.gate_sets.QiskitGateSet") | A gate set whose noise is to be learned and that is specified using Qiskit objects. | + diff --git a/docs/api/qiskit-noise-learning/index.mdx b/docs/api/qiskit-noise-learning/index.mdx new file mode 100644 index 000000000000..ce65fb433184 --- /dev/null +++ b/docs/api/qiskit-noise-learning/index.mdx @@ -0,0 +1,19 @@ +--- +title: Qiskit noise liearning API documentation (latest version) +description: Index of all the modules in the latest version of qiskit-noise-learning. +--- + +# API reference + +* [Aer executor (`qiskit_noise_learning.aer_executor`)](aer-executor) +* [Analysis (`qiskit_noise_learning.analysis`)](analysis) +* [Circuit generator (`qiskit_noise_learning.circuit_generator`)](circuit-generator) +* [Data (`qiskit_noise_learning.data`)](data) +* [Experiment builder (`qiskit_noise_learning.experiment_builder`)](experiment-builder) +* [Gate sets (`qiskit_noise_learning.gate_sets`)](gate-sets) +* [Math (`qiskit_noise_learning.math`)](math) +* [Models (`qiskit_noise_learning.models`)](models) +* [Noise learner (`qiskit_noise_learning.noise_learner`)](noise-learner) +* [Sequences (`qiskit_noise_learning.sequences`)](sequences) +* [Visualizations (`qiskit_noise_learning.visualizations`)](visualizations) + diff --git a/docs/api/qiskit-noise-learning/math.mdx b/docs/api/qiskit-noise-learning/math.mdx new file mode 100644 index 000000000000..95e0b4b1ed09 --- /dev/null +++ b/docs/api/qiskit-noise-learning/math.mdx @@ -0,0 +1,29 @@ +--- +title: math (latest version) +description: API reference for qiskit_noise_learning.math in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 2 +python_api_type: module +python_api_name: qiskit_noise_learning.math +--- + + + + + +# Math + +`qiskit_noise_learning.math` + +General mathematical objects. + +## Classes + +| | | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | +| [`IndexedMatrix`](generated/math-indexed-matrix#qiskit_noise_learning.math.IndexedMatrix "qiskit_noise_learning.math.IndexedMatrix") | A matrix with float entries and arbitrary row and column index data. | +| [`EnumeratedIndexedSpace`](generated/math-enumerated-indexed-space#qiskit_noise_learning.math.EnumeratedIndexedSpace "qiskit_noise_learning.math.EnumeratedIndexedSpace") | An indexed space backed by an explicit finite collection of indices. | +| [`IndexedSpace`](generated/math-indexed-space#qiskit_noise_learning.math.IndexedSpace "qiskit_noise_learning.math.IndexedSpace") | Abstract description of a vector space with arbitrary basis index types. | +| [`IndexedVector`](generated/math-indexed-vector#qiskit_noise_learning.math.IndexedVector "qiskit_noise_learning.math.IndexedVector") | A vector of floats with arbitrary index, or axis label, data. | +| [`ComposedLinearMap`](generated/math-composed-linear-map#qiskit_noise_learning.math.ComposedLinearMap "qiskit_noise_learning.math.ComposedLinearMap") | A linear map formed by composing a chain of maps. | +| [`LinearMap`](generated/math-linear-map#qiskit_noise_learning.math.LinearMap "qiskit_noise_learning.math.LinearMap") | An implicit linear map between two indexed spaces. | + diff --git a/docs/api/qiskit-noise-learning/models.mdx b/docs/api/qiskit-noise-learning/models.mdx new file mode 100644 index 000000000000..c1c685300210 --- /dev/null +++ b/docs/api/qiskit-noise-learning/models.mdx @@ -0,0 +1,46 @@ +--- +title: models (latest version) +description: API reference for qiskit_noise_learning.models in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 2 +python_api_type: module +python_api_name: qiskit_noise_learning.models +--- + + + + + +# Models + +`qiskit_noise_learning.models` + +Gate set noise models. + +## Classes + +| | | +| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`IdentityFidelityModel`](generated/models-identity-fidelity-model#qiskit_noise_learning.models.IdentityFidelityModel "qiskit_noise_learning.models.IdentityFidelityModel") | A fidelity model whose parameters are the log fidelities themselves. | +| [`LogFidelitySpace`](generated/models-log-fidelity-space#qiskit_noise_learning.models.LogFidelitySpace "qiskit_noise_learning.models.LogFidelitySpace") | The space of log fidelities of a gate set. | +| [`GeneratorIndex`](generated/models-generator-index#qiskit_noise_learning.models.GeneratorIndex "qiskit_noise_learning.models.GeneratorIndex") | | +| [`PauliLindbladModel`](generated/models-pauli-lindblad-model#qiskit_noise_learning.models.PauliLindbladModel "qiskit_noise_learning.models.PauliLindbladModel") | A linear mapping from Pauli-Lindblad generator rates to log fidelities. | +| [`RateSpace`](generated/models-rate-space#qiskit_noise_learning.models.RateSpace "qiskit_noise_learning.models.RateSpace") | Space of Pauli-Lindblad generator rates, indexed by [`GeneratorIndex`](generated/models-generator-index#qiskit_noise_learning.models.GeneratorIndex "qiskit_noise_learning.models.GeneratorIndex"). | +| [`PauliLindbladSplit`](generated/models-pauli-lindblad-split#qiskit_noise_learning.models.PauliLindbladSplit "qiskit_noise_learning.models.PauliLindbladSplit") | The decomposition of a map around its underlying [`PauliLindbladModel`](generated/models-pauli-lindblad-model#qiskit_noise_learning.models.PauliLindbladModel "qiskit_noise_learning.models.PauliLindbladModel"). | + +## Functions + +| | | +| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| [`contains_pauli_lindblad_model`](generated/models-contains-pauli-lindblad-model#qiskit_noise_learning.models.contains_pauli_lindblad_model "qiskit_noise_learning.models.contains_pauli_lindblad_model")(model) | Whether a map is, or contains, a [`PauliLindbladModel`](generated/models-pauli-lindblad-model#qiskit_noise_learning.models.PauliLindbladModel "qiskit_noise_learning.models.PauliLindbladModel"). | +| [`get_noise_site`](generated/models-get-noise-site#qiskit_noise_learning.models.get_noise_site "qiskit_noise_learning.models.get_noise_site")(model) | The noise-site mapping of the map's [`PauliLindbladModel`](generated/models-pauli-lindblad-model#qiskit_noise_learning.models.PauliLindbladModel "qiskit_noise_learning.models.PauliLindbladModel"), if it has exactly one. | +| [`is_fidelity_model`](generated/models-is-fidelity-model#qiskit_noise_learning.models.is_fidelity_model "qiskit_noise_learning.models.is_fidelity_model")(model) | Whether an object is a [`LinearMap`](generated/math-linear-map#qiskit_noise_learning.math.LinearMap "qiskit_noise_learning.math.LinearMap") with a [`LogFidelitySpace`](generated/models-log-fidelity-space#qiskit_noise_learning.models.LogFidelitySpace "qiskit_noise_learning.models.LogFidelitySpace") output space. | +| [`split_pauli_lindblad_model`](generated/models-split-pauli-lindblad-model#qiskit_noise_learning.models.split_pauli_lindblad_model "qiskit_noise_learning.models.split_pauli_lindblad_model")(model) | Split a map around its underlying [`PauliLindbladModel`](generated/models-pauli-lindblad-model#qiskit_noise_learning.models.PauliLindbladModel "qiskit_noise_learning.models.PauliLindbladModel"). | + +## Type aliases + +### qiskit\_noise\_learning.models.FidelityModel + + + alias of [`LinearMap`](generated/math-linear-map#qiskit_noise_learning.math.LinearMap "qiskit_noise_learning.math.linear_map.LinearMap")\[[`Hashable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Hashable), [`FidelityIndex`](generated/sequences-fidelity-index#qiskit_noise_learning.sequences.FidelityIndex "qiskit_noise_learning.sequences.fidelity_index.FidelityIndex")] + + diff --git a/docs/api/qiskit-noise-learning/noise-learner.mdx b/docs/api/qiskit-noise-learning/noise-learner.mdx new file mode 100644 index 000000000000..00ef4b1a0082 --- /dev/null +++ b/docs/api/qiskit-noise-learning/noise-learner.mdx @@ -0,0 +1,29 @@ +--- +title: noise_learner (latest version) +description: API reference for qiskit_noise_learning.noise_learner in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 2 +python_api_type: module +python_api_name: qiskit_noise_learning.noise_learner +--- + + + + + +# Noise learner + +`qiskit_noise_learning.noise_learner` + +Noise learner. + +## Classes + +| | | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`LearningOptions`](generated/noise-learner-learning-options#qiskit_noise_learning.noise_learner.LearningOptions "qiskit_noise_learning.noise_learner.LearningOptions") | Options for the noise learner. | +| [`NoiseLearner`](generated/noise-learner-noise-learner#qiskit_noise_learning.noise_learner.NoiseLearner "qiskit_noise_learning.noise_learner.NoiseLearner") | A noise learner. | +| [`NoiseLearnerJob`](generated/noise-learner-noise-learner-job#qiskit_noise_learning.noise_learner.NoiseLearnerJob "qiskit_noise_learning.noise_learner.NoiseLearnerJob") | A noise learner job. | +| [`NoiseLearnerResult`](generated/noise-learner-noise-learner-result#qiskit_noise_learning.noise_learner.NoiseLearnerResult "qiskit_noise_learning.noise_learner.NoiseLearnerResult") | Result of noise learning. | +| [`ProgramExecutor`](generated/noise-learner-program-executor#qiskit_noise_learning.noise_learner.ProgramExecutor "qiskit_noise_learning.noise_learner.ProgramExecutor") | The executor role that [`NoiseLearner`](generated/noise-learner-noise-learner#qiskit_noise_learning.noise_learner.NoiseLearner "qiskit_noise_learning.noise_learner.NoiseLearner") submits programs to. | +| [`ProgramJob`](generated/noise-learner-program-job#qiskit_noise_learning.noise_learner.ProgramJob "qiskit_noise_learning.noise_learner.ProgramJob") | The job role that [`NoiseLearnerJob`](generated/noise-learner-noise-learner-job#qiskit_noise_learning.noise_learner.NoiseLearnerJob "qiskit_noise_learning.noise_learner.NoiseLearnerJob") wraps. | + diff --git a/docs/api/qiskit-noise-learning/sequences.mdx b/docs/api/qiskit-noise-learning/sequences.mdx new file mode 100644 index 000000000000..9e4c394f53d6 --- /dev/null +++ b/docs/api/qiskit-noise-learning/sequences.mdx @@ -0,0 +1,36 @@ +--- +title: sequences (latest version) +description: API reference for qiskit_noise_learning.sequences in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 2 +python_api_type: module +python_api_name: qiskit_noise_learning.sequences +--- + + + + + +# Sequences + +`qiskit_noise_learning.sequences` + +Path and instruction sequences. + +## Classes + +| | | +| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | +| [`ApplyGate`](generated/sequences-apply-gate#qiskit_noise_learning.sequences.ApplyGate "qiskit_noise_learning.sequences.ApplyGate") | An instruction that applies a fixed gate. | +| [`FidelityIndex`](generated/sequences-fidelity-index#qiskit_noise_learning.sequences.FidelityIndex "qiskit_noise_learning.sequences.FidelityIndex") | Index data for a fidelity in a Pauli-MCM-reset gate set. | +| [`InstructionSequence`](generated/sequences-instruction-sequence#qiskit_noise_learning.sequences.InstructionSequence "qiskit_noise_learning.sequences.InstructionSequence") | A sequence of instructions. | +| [`LogPathMap`](generated/sequences-log-path-map#qiskit_noise_learning.sequences.LogPathMap "qiskit_noise_learning.sequences.LogPathMap") | The linear map from a space of log fidelities to its associated log path space. | +| [`LogPathSpace`](generated/sequences-log-path-space#qiskit_noise_learning.sequences.LogPathSpace "qiskit_noise_learning.sequences.LogPathSpace") | The (infinite-dimensional) space of log path-fidelities. | +| [`PartialPauliPermutation`](generated/sequences-partial-pauli-permutation#qiskit_noise_learning.sequences.PartialPauliPermutation "qiskit_noise_learning.sequences.PartialPauliPermutation") | Partially-specified permutations of the single-qubit phaseless Paulis on `n` qubits. | +| [`Path`](generated/sequences-path#qiskit_noise_learning.sequences.Path "qiskit_noise_learning.sequences.Path") | A sequence of fidelity indices. | + +## Functions + +| | | +| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | +| [`group_mergeable_instruction_sequences`](generated/sequences-group-mergeable-instruction-sequences#qiskit_noise_learning.sequences.group_mergeable_instruction_sequences "qiskit_noise_learning.sequences.group_mergeable_instruction_sequences") | Group the positions of instruction sequences that can be merged with each other. | + diff --git a/docs/api/qiskit-noise-learning/visualizations.mdx b/docs/api/qiskit-noise-learning/visualizations.mdx new file mode 100644 index 000000000000..38a23ebe333e --- /dev/null +++ b/docs/api/qiskit-noise-learning/visualizations.mdx @@ -0,0 +1,26 @@ +--- +title: visualizations (latest version) +description: API reference for qiskit_noise_learning.visualizations in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 2 +python_api_type: module +python_api_name: qiskit_noise_learning.visualizations +--- + + + + + +# Visualizations + +`qiskit_noise_learning.visualizations` + +Visualization utilities. + +## Functions + +| | | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | +| [`fidelity_index_math_label`](generated/visualizations-fidelity-index-math-label#qiskit_noise_learning.visualizations.fidelity_index_math_label "qiskit_noise_learning.visualizations.fidelity_index_math_label")(gate\_set, ...\[, ...]) | Return a math-mode LaTeX label for a fidelity index. | +| [`path_math_label`](generated/visualizations-path-math-label#qiskit_noise_learning.visualizations.path_math_label "qiskit_noise_learning.visualizations.path_math_label")(gate\_set, path\[, style, ...]) | Return a math-mode LaTeX label for a path. | +| [`gate_set_topology`](generated/visualizations-gate-set-topology#qiskit_noise_learning.visualizations.gate_set_topology "qiskit_noise_learning.visualizations.gate_set_topology")(gate\_set) | Draw the device topology with per-gate coloring. | + diff --git a/public/docs/api/qiskit-noise-learning/objects.inv b/public/docs/api/qiskit-noise-learning/objects.inv new file mode 100644 index 0000000000000000000000000000000000000000..b485feca048462f5568088f650b9c43d3c36326f GIT binary patch literal 6206 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 Date: Thu, 3 Sep 2026 10:39:57 -0400 Subject: [PATCH 03/15] fix from Bob --- scripts/js/lib/api/htmlToMd.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/js/lib/api/htmlToMd.ts b/scripts/js/lib/api/htmlToMd.ts index df6f15289d03..e0ffb05f20d2 100644 --- a/scripts/js/lib/api/htmlToMd.ts +++ b/scripts/js/lib/api/htmlToMd.ts @@ -264,7 +264,7 @@ function buildAdmonition( { type: "mdxJsxAttribute", name: "title", - value: toText(titleNode), + value: titleNode ? toText(titleNode) : "", }, { type: "mdxJsxAttribute", From 69712ca61e2c28a521b12ec6dc34452e2c1c595a Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Thu, 3 Sep 2026 10:41:04 -0400 Subject: [PATCH 04/15] npm run gen-addon -- -p qiskit-noise-learning -v 0.1.0 --- docs/addons/qiskit-noise-learning/_toc.json | 13 ++ .../qiskit-noise-learning/formalism/index.mdx | 184 ++++++++++++++++++ docs/addons/qiskit-noise-learning/index.mdx | 39 ++++ docs/addons/qiskit-noise-learning/prf-prf.mdx | 15 ++ 4 files changed, 251 insertions(+) create mode 100644 docs/addons/qiskit-noise-learning/_toc.json create mode 100644 docs/addons/qiskit-noise-learning/formalism/index.mdx create mode 100644 docs/addons/qiskit-noise-learning/index.mdx create mode 100644 docs/addons/qiskit-noise-learning/prf-prf.mdx diff --git a/docs/addons/qiskit-noise-learning/_toc.json b/docs/addons/qiskit-noise-learning/_toc.json new file mode 100644 index 000000000000..2df22fb1a871 --- /dev/null +++ b/docs/addons/qiskit-noise-learning/_toc.json @@ -0,0 +1,13 @@ +{ + "parentUrl": "/docs/guides/addons", + "parentLabel": "Documentation", + "title": "Qiskit noise liearning 0.1", + "collapsed": true, + "children": [ + { + "title": "", + "children": [], + "collapsible": false + } + ] +} diff --git a/docs/addons/qiskit-noise-learning/formalism/index.mdx b/docs/addons/qiskit-noise-learning/formalism/index.mdx new file mode 100644 index 000000000000..e6c1a3583c91 --- /dev/null +++ b/docs/addons/qiskit-noise-learning/formalism/index.mdx @@ -0,0 +1,184 @@ +--- +title: "Mathematical formalism" +description: "Mathematical formalism for the latest version of Qiskit noise liearning" +--- + +# Mathematical formalism + +Given the task of learning Pauli noise for a set of Clifford gates, a common analysis technique is to track how individual Pauli operators are transformed through a sequence of gate applications (under the assumption that the gates are Clifford and the noise is a Pauli channel, a single Pauli will always be mapped to another Pauli up to a scalar that is a function of the noise). Obviously, the evolution of *any* state under such a sequence can be captured by a linear combination of such trajectories, but under the assumption that we always prepare the state in a Pauli eigenstate, and always measure and post-process the results to compute the expectation value of a Pauli operator, the relationship between the expectation value and the noise model parameters will *always* depend on only a single such trajectory. This follows from the simple fact that the initial state is a linear combination of Pauli operators, each gate and noise model maps Paulis to Paulis and preserves their orthogonality, and the final expectation value “selects” only one of the Paulis in the final decomposition before measurement. + +This type of reasoning appears in many parallel research tracks in noise learning, including in the Pauli gate-set learning literature \[[CCF+26](#id20 "Edward H. Chen, Senrui Chen, Laurin E. Fischer, Andrew Eddins, Luke C. G. Govia, Brad Mitchell, Andre He, Youngseok Kim, Liang Jiang, and Alireza Seif. Disambiguating pauli noise in quantum computers. PRX Quantum, pages, 2026. doi:10.1103/69wc-gzl6."), [CZJF26](#id17 "Senrui Chen, Zhihan Zhang, Liang Jiang, and Steven T. Flammia. Efficient Self-Consistent Learning of Gate Set Pauli Noise. PRX Quantum, 7(1):010305, 2026. URL: https://link.aps.org/doi/10.1103/1pnv-t9px, doi:10.1103/1pnv-t9px.")], the ACES literature \[[Fla22](#id15 "Steven T. Flammia. Averaged Circuit Eigenvalue Sampling. In 17th Conference on the Theory of Quantum Computation, Communication and Cryptography (TQC 2022), volume 232 of Leibniz International Proceedings in Informatics (LIPIcs), 4:1–4:10. Dagstuhl, Germany, 2022. Schloss Dagstuhl – Leibniz-Zentrum für Informatik. doi:10.4230/LIPIcs.TQC.2022.4.")], and the cycle benchmarking literature \[[EWP+19](#id14 "Alexander Erhard, Joel J. Wallman, Lukas Postler, Michael Meth, Roman Stricker, Esteban A. Martinez, Philipp Schindler, Thomas Monz, Joseph Emerson, and Rainer Blatt. Characterizing large-scale quantum computers via cycle benchmarking. Nature Communications, 10(1):5347, 2019. doi:10.1038/s41467-019-13068-7.")]. This reasoning was further generalized in \[[ZCLJ25](#id16 "Zhihan Zhang, Senrui Chen, Yunchao Liu, and Liang Jiang. Generalized Cycle Benchmarking Algorithm for Characterizing Midcircuit Measurements. PRX Quantum, 6(1):010310, 2025. URL: https://link.aps.org/doi/10.1103/PRXQuantum.6.010310, doi:10.1103/PRXQuantum.6.010310.")] to include Clifford-MCM gates (a Clifford gate followed by a projective mid-circuit measurement). This package most closely follows \[[CZJF26](#id17 "Senrui Chen, Zhihan Zhang, Liang Jiang, and Steven T. Flammia. Efficient Self-Consistent Learning of Gate Set Pauli Noise. PRX Quantum, 7(1):010305, 2026. URL: https://link.aps.org/doi/10.1103/1pnv-t9px, doi:10.1103/1pnv-t9px."), [ZCLJ25](#id16 "Zhihan Zhang, Senrui Chen, Yunchao Liu, and Liang Jiang. Generalized Cycle Benchmarking Algorithm for Characterizing Midcircuit Measurements. PRX Quantum, 6(1):010310, 2025. URL: https://link.aps.org/doi/10.1103/PRXQuantum.6.010310, doi:10.1103/PRXQuantum.6.010310.")]. While not explicitly named, we adopt the *Pattern Transfer Graph* (PTG) formalism for describing how Pauli operators evolve through learning circuits, providing a direct data representation of *paths* through the graph. + +The following is a review of some core mathematical concepts from the literature. It is primarily meant to consolidate notation, and to serve as a conceptual documentation reference for the rest of the package. + + + +## 1. Background + + + +### 1 .1 Notation + +For $K \in \mathbb{N}$, let $[K] = \{0, 1, \dots, K - 1\}$. For a finite set $S \subset \mathbb{N}$ of qubit indices, let $\P^S$ denote the set of *unphased* Pauli operators acting on those qubits. Note that we think of elements of $\P^S$ as functions mapping $S \rightarrow \{I, X, Y, Z\}$, so that for any $P \in \P^S$ and $T \subseteq S$, $P|_T$ denotes the restriction of $P$ to the qubit subset $T$. Along these lines, for disjoint sets $S, T$, and $P \in \P^S$ and $Q \in \P^T$, $P \otimes Q$ denotes the element of $\P^{S \cup T}$ such that $P \otimes Q |_S = P$ and $P \otimes Q |_T = Q$. This notation is helpful to avoid explicitly dealing with subsystem orderings, and to make it easy to describe restrictions. + +For finite subsets $M \subset \mathbb{N}$, we denote $\Z_2^M$ as the set of the bit strings whose elements are indexed by $M$. Similarly to the above, we think of elements as functions mapping $M \rightarrow \Z_2$, so that we may easily describe substrings in terms of restrictions of the index set. + +Lastly, for a matrix $X$, we use $\opket{X}$ to denote its vectorization. Based on the limited way in which we use this notation, it is not actually necessary to choose a specific vectorization convention. For a classical bit string $m$, we use the shorthand $\opket{m} = \opket{\ket{m}\bra{m}}$. + + + +### 1.2 Quantum instruments + +A quantum operation producing classical bits $m \in \Z_2^M$ (for example, the result of measurement) is generally modeled as a linear map of the form: + +$$ + \rho \mapsto \sum_{m \in \Z_2^M} \E_m(\rho) \otimes \ket{m}\bra{m}, +$$ + +where the set $\{\E_m: m \in \Z_2^M\}$ are completely positive, and $\sum_m \E_m$ is trace-preserving. A set of completely positive maps $\{\E_m\}$ satisfying these properties is called a *quantum instrument*. A unitary gate is a special case of an instrument with only one element that is a unitary operation. + + + +## 2. Noisy Clifford-MCM-reset gates + +The formalism utilized in this package assumes every gate in the gate set to be characterized consists of the following sequence of operations on $K$ qubits: + +1. A Clifford operation on all qubits. +2. A mid-circuit projective measurement along $Z$ on some subset of qubits $M \subseteq [K]$. +3. A mid-circuit reset to the $Z$ ground state on some subset of qubits $R \subseteq [K]$. + +This is a general class of operations that includes unitary Clifford gates, measurement, state preparation, and any combination of the above. Note that we assume measurement and reset are always along the $Z$-axis for each qubit. While this is not strictly required, it is a common feature of many quantum computing modalities, and enables simplified representations and analysis. + +As outlined in \[[BW23](#id18 "Stefanie J. Beale and Joel J. Wallman. Randomized compiling for subsystem measurements. 2023. URL: http://arxiv.org/abs/2304.06599, doi:10.48550/arXiv.2304.06599."), [ZCLJ25](#id16 "Zhihan Zhang, Senrui Chen, Yunchao Liu, and Liang Jiang. Generalized Cycle Benchmarking Algorithm for Characterizing Midcircuit Measurements. PRX Quantum, 6(1):010310, 2025. URL: https://link.aps.org/doi/10.1103/PRXQuantum.6.010310, doi:10.1103/PRXQuantum.6.010310.")] for the no-reset case, if a specific twirling strategy is applied to a noisy instance of such a gate, then the action of the resulting operation can be modeled mathematically as a *uniform Pauli instrument*. That is, within the quantum instrument notation, $\E_m = \U_mG$, where $G$ is the Clifford unitary, and: + +$$ + \U_m = \sum_{a,b \in \Z_2^M} \Lambda_{a,b} \otimes \opket{m + a}\opbra{m + b}, +$$ + +where each $\Lambda_{a,b}$ is a sub-normalized Pauli channel on the unmeasured qubits $N = [K] \setminus M$. It is implied by this being a quantum instrument that $\sum_{a,b} \Lambda_{a,b}$ is also trace-preserving. Some notes: + +* The initial untwirled noise is modeled to include both “quantum” and “classical” errors: erroneous operations on the quantum registers, as well as mistakes in the measurement value reporting. +* The noise map $\Lambda_{a,b}$ is *independent* of the measurement outcome $m$. + +In words, a single term in the above sum represents observing a measurement outcome of $m$ when the measured state was $\ket{m + b}$ (a misclassification if $b \neq 0$), and when the output state on the measurement register is $\ket{m + a}$ (the “wrong” state when $a \neq 0$). The map $\Lambda_{a,b}$ simultaneously encodes the action on the unmeasured qubits (conditioned on the measurement behavior) and the *probability* of the specific measurement behavior (through the normalization). + +Note that we are not concerned here with the specifics of the twirling strategy: that such a strategy exists to put the channel into the above form is enough. Note that “finer” twirling strategies exist which can further restrict the form of the Pauli channels \[[BW24](#id19 "Ewout van den Berg and Pawel Wocjan. Techniques for learning sparse Pauli-Lindblad noise models. Quantum, 8:1556, 2024. URL: https://quantum-journal.org/papers/q-2024-12-10-1556/, doi:10.22331/q-2024-12-10-1556.")]; however, we take the above form as the most general mathematical representation under consideration. + +In Lemma 1 of \[[ZCLJ25](#id16 "Zhihan Zhang, Senrui Chen, Yunchao Liu, and Liang Jiang. Generalized Cycle Benchmarking Algorithm for Characterizing Midcircuit Measurements. PRX Quantum, 6(1):010310, 2025. URL: https://link.aps.org/doi/10.1103/PRXQuantum.6.010310, doi:10.1103/PRXQuantum.6.010310.")], it is shown that $\E_m = \U_mG$ can be rewritten as: + +$$ + \E_m = \frac{1}{2^{2|M| + |N|}}\sum_{x, y \in \Z_2^M, Q \in \P^N} (-1)^{m \cdot (x + y)} +\lambda^Q_{x, y}\opket{Q \otimes Z^y}\opbra{G^\dagger(Q \otimes Z^x)}. +$$ + +for some real numbers $\lambda_{x,y}^Q$, which are called the *fidelities* of the instrument. + +Adding reset to this picture is relatively straightforward. A noisy reset operation on qubits $R \subset [K]$ can be modeled according to the decomposition: + +$$ + \frac{1}{2^{|R|}}\sum_{r \in \Z_2^{R}} \lambda_r \opket{Z^r}\opbra{I_R}. +$$ + +The above form explicitly utilizes the assumption that the reset is along the $Z$-axis for each qubit. Noise in the operation is encoded in the reset fidelities $\lambda_r$, which are simply indexed by qubit subsets. + +An analog to Equation [(1)](#equation-clifford-mcm-form) that includes a reset operation at the end can be attained by simply composing it with Equation [(2)](#equation-reset-form). This composition, after some simplification, yields: + +$$ +\begin{split} \frac{1}{2^{2|M|+|N|}} \sum_{\substack{x \in \Z_2^M, y \in \Z_2^{M \cup R} \\ Q \in +\P^{N\setminus R}}} (-1)^{m \cdot (x + y|_M)} \lambda^Q_{x,y} \opket{Q \otimes +Z^y}\opbra{G^\dagger(Q \otimes I_{N \cap R} \otimes Z^x)}. \end{split} +$$ + +This decomposition indicates that the number of fidelities $\lambda^Q_{x, y}$ is + +$$ +4^{|N \setminus R|} 2^{|M|}2^{|M \cup R|} = 4^{K}2^{|M|}2^{-|M \cup R|} = 4^K 2^{-|R \setminus M|}. +$$ + +Consider limiting cases: (1) For no measurement or reset, $M = R = \emptyset$, and the expression yields $4^K$, the number of phase-less Pauli operators on $K$ qubits. (2) For $M = \emptyset$ and $R=[K]$, this yields $2^K$, which is the number of subsets of $[K]$. Lastly, (3) for $M = [K]$ and $R = \emptyset$, this yields $4^K$. Note that this may initially seem surprising: for standard learning, measurement and reset are typically considered to have the same number of fidelities: $2^K$. However, here the all-measurement gate in this context is understood not as a *terminal* measurement, but as an MCM, and as such fidelities corresponding to non-identity *outputs* of the measurement are also included (such as $y \neq 0$ in Equation [(3)](#equation-clifford-mcm-reset-form)). + +Finally, it is important to note that any twirling strategy yielding the form in Equation [(1)](#equation-clifford-mcm-form) in the non-reset case still applies equally well to the non-trivial reset case with a simple modification. The potential problem is that such a twirling strategy may require operations on measured qubits *after* the measurement. Therefore, if a qubit is measured *and* reset, implementing the strategy seemingly requires inserting operations *within* the gate between the measurement and reset. However, given the nature of reset, any such operations have no effect, and can simply be skipped while still yielding the same desired structure. + + + +## 3. Path formalism + +As described in the introduction, all learning algorithms for Pauli-type noise on Clifford gates are based around tracking how individual Paulis evolve through a circuit, picking up noise fidelity factors along the way. The expectation values of a circuit composed of such gates are therefore related simply to products of the underlying fidelities of the individual gates, and in this way model parameters can be inferred by *inverting* whatever sparse parameter-to-fidelity mapping is being assumed. + +In \[[CZJF26](#id17 "Senrui Chen, Zhihan Zhang, Liang Jiang, and Steven T. Flammia. Efficient Self-Consistent Learning of Gate Set Pauli Noise. PRX Quantum, 7(1):010305, 2026. URL: https://link.aps.org/doi/10.1103/1pnv-t9px, doi:10.1103/1pnv-t9px.")], in the context of unitary gate sets, this is formalized into the *Pattern Transfer Graph* (PTG): a directed graph describing all possible experiments consisting of elements of the gate set and layers of single-qubit Clifford gates (assumed to be perfect, or “free”, operations). This was generalized in \[[ZCLJ25](#id16 "Zhihan Zhang, Senrui Chen, Yunchao Liu, and Liang Jiang. Generalized Cycle Benchmarking Algorithm for Characterizing Midcircuit Measurements. PRX Quantum, 6(1):010310, 2025. URL: https://link.aps.org/doi/10.1103/PRXQuantum.6.010310, doi:10.1103/PRXQuantum.6.010310.")] to include gate sets with mid-circuit measurements. In both cases, each experiment is described by tracking a single Pauli operator through the circuit, under the assumption of a particular observable being computed at each measurement site. Here we do not directly review the graph or path constructions; however, we present the required facts for justifying them within our own notation and with resets included. + +While the tracking of a single Pauli operator through the circuit may be intuitive in the unitary gate set case, it does not so obviously hold in the more general Clifford-MCM-reset case, due to the non-deterministic nature of measurement. The following proposition recovers this picture even in the more general case \[[ZCLJ25](#id16 "Zhihan Zhang, Senrui Chen, Yunchao Liu, and Liang Jiang. Generalized Cycle Benchmarking Algorithm for Characterizing Midcircuit Measurements. PRX Quantum, 6(1):010310, 2025. URL: https://link.aps.org/doi/10.1103/PRXQuantum.6.010310, doi:10.1103/PRXQuantum.6.010310.")]: + + + + + For any $x \in \Z_2^M$, $y \in \Z_2^{M \cup R}$, and $Q\in \P^{N \setminus R}$, it holds that: + +$$ + +\opbra{Q \otimes Z^y}\otimes \opbra{Z^{x + y|_M}}_M \left(\sum_{m\in \Z_2^M} \E_m \otimes \opket{m}\right) += \lambda_{x,y}^Q\opbra{G^\dagger(Q \otimes I_{N \cap R} \otimes Z^x)} + +$$ + + +In other words, if we compute the expectation value $Z^{x + y|_M}$ on the classical register output by the MCM, then the “Heisenberg picture” evolution of an observable through the Clifford-MCM-reset gate maps $Q \otimes Z^y \rightarrow Q \otimes I_{N \cap R} \otimes Z^x$. This fact alone enables recovery of PTG-like analysis beyond the unitary gate set case: with a particular post-processing of the measurement results, even gates with measurements and resets can be viewed as deterministically mapping one Pauli operator to another. + +Before proving this, we write Equation [(3)](#equation-clifford-mcm-reset-form) in a more suggestive way. Note that for $x, y \in \Z_2^M$, it holds that $Z^{x+y} = \sum_{m \in \Z_2^M} (-1)^{m \cdot (x + y)}\ket{m}\bra{m}$, and as such (in super operator notation) we have: + +$$ +\begin{split} \begin{aligned} \sum_{m \in \Z_2^M} \E_m \otimes \opket{m}_M = \frac{1}{2^{2|M|+|N|}}\sum_{\substack{x \in +\Z_2^M, y \in \Z_2^{M \cup R} \\ Q \in \P^{N\setminus R}}} \lambda^Q_{x,y} \opket{Q \otimes Z^y} +\opbra{G^\dagger(Q \otimes I_{N \cap R} \otimes Z^x)} \otimes \opket{Z^{x + y|_M}}_M, \end{aligned} \end{split} +$$ + +where we have applied Equation [(3)](#equation-clifford-mcm-reset-form) and collected terms, and we use the subscript $M$ to indicate the classical measurement result register, which we treat above in a similar notation to the quantum registers. + + + Proof. It holds that: + +$$ +\begin{split} +\begin{aligned} +&\opbra{Q \otimes Z^y} \otimes \opbra{Z^{x + y|_M}} \left(\sum_{m\in \Z_2^M} \E_m \otimes \opket{m}\right)\\ +&= \opbra{Q \otimes Z^y} \otimes \opbra{Z^{x + y|_M}} \left( \frac{1}{2^{2|M|+|N|}} \sum_{\substack{a \in \Z_2^M, b \in \Z_2^{M \cup R} \\ P \in \P^{N\setminus R}}} \lambda^P_{a,b} \opket{P \otimes Z^b}\opbra{G^\dagger(P \otimes I_{N \cap R} \otimes Z^a)} \otimes \opket{Z^{a + b|_M}} \right) \\ +&=\frac{1}{2^{2|M| + |N|}}\sum_{\substack{a \in \Z_2^M, b \in \Z_2^{M \cup R} \\ P \in \P^{N \setminus R}}} \lambda^P_{a, b}\underbrace{\ip{Q \otimes Z^y}{P \otimes Z^b}}_{2^{|M| + |N|} \delta_{P, Q}\delta_{y,b}} \underbrace{\ip{Z^{x + y|_M}}{Z^{a + b|_M}}}_{2^{|M|}\delta_{x+y|_M,a+b|_M}}\opbra{G^\dagger(P \otimes I_{N \cap R} \otimes Z^a)} +\end{aligned} +\end{split} +$$ + + Lastly, observe that $\delta_{y,b}\delta_{x+y|_M,a+b|_M} = \delta_{y,b}\delta_{x,a}$, and hence the final term above collapses down to the single term $\lambda^Q_{x,y} \opbra{G^\dagger(Q \otimes I_{N \cap R} \otimes Z^x)}$, yielding the desired result. + + +See \[[ZCLJ25](#id16 "Zhihan Zhang, Senrui Chen, Yunchao Liu, and Liang Jiang. Generalized Cycle Benchmarking Algorithm for Characterizing Midcircuit Measurements. PRX Quantum, 6(1):010310, 2025. URL: https://link.aps.org/doi/10.1103/PRXQuantum.6.010310, doi:10.1103/PRXQuantum.6.010310.")] for development beyond this point: the definition of the PTG, paths through the PTG, and the proof that any properly-defined path corresponds to an experiment. + +## References + +\[[BW23](#id6)] + +Stefanie J. Beale and Joel J. Wallman. Randomized compiling for subsystem measurements. 2023. URL: [http://arxiv.org/abs/2304.06599](http://arxiv.org/abs/2304.06599), [doi:10.48550/arXiv.2304.06599](https://doi.org/10.48550/arXiv.2304.06599). + +\[[BW24](#id7)] + +Ewout van den Berg and Pawel Wocjan. Techniques for learning sparse Pauli-Lindblad noise models. *Quantum*, 8:1556, 2024. URL: [https://quantum-journal.org/papers/q-2024-12-10-1556/](https://quantum-journal.org/papers/q-2024-12-10-1556/), [doi:10.22331/q-2024-12-10-1556](https://doi.org/10.22331/q-2024-12-10-1556). + +\[[CCF+26](#id1)] + +Edward H. Chen, Senrui Chen, Laurin E. Fischer, Andrew Eddins, Luke C. G. Govia, Brad Mitchell, Andre He, Youngseok Kim, Liang Jiang, and Alireza Seif. Disambiguating pauli noise in quantum computers. *PRX Quantum*, pages, 2026. [doi:10.1103/69wc-gzl6](https://doi.org/10.1103/69wc-gzl6). + +\[CZJF26] ([1](#id1),[2](#id5),[3](#id9)) + +Senrui Chen, Zhihan Zhang, Liang Jiang, and Steven T. Flammia. Efficient Self-Consistent Learning of Gate Set Pauli Noise. *PRX Quantum*, 7(1):010305, 2026. URL: [https://link.aps.org/doi/10.1103/1pnv-t9px](https://link.aps.org/doi/10.1103/1pnv-t9px), [doi:10.1103/1pnv-t9px](https://doi.org/10.1103/1pnv-t9px). + +\[[EWP+19](#id3)] + +Alexander Erhard, Joel J. Wallman, Lukas Postler, Michael Meth, Roman Stricker, Esteban A. Martinez, Philipp Schindler, Thomas Monz, Joseph Emerson, and Rainer Blatt. Characterizing large-scale quantum computers via cycle benchmarking. *Nature Communications*, 10(1):5347, 2019. [doi:10.1038/s41467-019-13068-7](https://doi.org/10.1038/s41467-019-13068-7). + +\[[Fla22](#id2)] + +Steven T. Flammia. Averaged Circuit Eigenvalue Sampling. In *17th Conference on the Theory of Quantum Computation, Communication and Cryptography (TQC 2022)*, volume 232 of Leibniz International Proceedings in Informatics (LIPIcs), 4:1–4:10. Dagstuhl, Germany, 2022. Schloss Dagstuhl – Leibniz-Zentrum für Informatik. [doi:10.4230/LIPIcs.TQC.2022.4](https://doi.org/10.4230/LIPIcs.TQC.2022.4). + +\[ZCLJ25] ([1](#id4),[2](#id5),[3](#id6),[4](#id8),[5](#id10),[6](#id11),[7](#id12)) + +Zhihan Zhang, Senrui Chen, Yunchao Liu, and Liang Jiang. Generalized Cycle Benchmarking Algorithm for Characterizing Midcircuit Measurements. *PRX Quantum*, 6(1):010310, 2025. URL: [https://link.aps.org/doi/10.1103/PRXQuantum.6.010310](https://link.aps.org/doi/10.1103/PRXQuantum.6.010310), [doi:10.1103/PRXQuantum.6.010310](https://doi.org/10.1103/PRXQuantum.6.010310). + diff --git a/docs/addons/qiskit-noise-learning/index.mdx b/docs/addons/qiskit-noise-learning/index.mdx new file mode 100644 index 000000000000..5e85451b0f07 --- /dev/null +++ b/docs/addons/qiskit-noise-learning/index.mdx @@ -0,0 +1,39 @@ +--- +title: "Qiskit Noise Learning" +description: "Documentation for the latest version of Qiskit noise liearning" +--- + +# Qiskit Noise Learning + +* [Tutorials](tutorials/index) + + * [Learn the noise model of a gate with NoiseLearner](tutorials/noise-learner) + * [Build a learning experiment](tutorials/workflow) + +* [Mathematical formalism](formalism/index) + + * [1. Background](formalism/index#background) + * [2. Noisy Clifford-MCM-reset gates](formalism/index#noisy-clifford-mcm-reset-gates) + * [3. Path formalism](formalism/index#path-formalism) + * [References](formalism/index#references) + +* [API reference](/docs/api/qiskit-noise-learning/index) + + * [Aer executor (`qiskit_noise_learning.aer_executor`)](/docs/api/qiskit-noise-learning/aer-executor) + * [Analysis (`qiskit_noise_learning.analysis`)](/docs/api/qiskit-noise-learning/analysis) + * [Circuit generator (`qiskit_noise_learning.circuit_generator`)](/docs/api/qiskit-noise-learning/circuit-generator) + * [Data (`qiskit_noise_learning.data`)](/docs/api/qiskit-noise-learning/data) + * [Experiment builder (`qiskit_noise_learning.experiment_builder`)](/docs/api/qiskit-noise-learning/experiment-builder) + * [Gate sets (`qiskit_noise_learning.gate_sets`)](/docs/api/qiskit-noise-learning/gate-sets) + * [Math (`qiskit_noise_learning.math`)](/docs/api/qiskit-noise-learning/math) + * [Models (`qiskit_noise_learning.models`)](/docs/api/qiskit-noise-learning/models) + * [Noise learner (`qiskit_noise_learning.noise_learner`)](/docs/api/qiskit-noise-learning/noise-learner) + * [Sequences (`qiskit_noise_learning.sequences`)](/docs/api/qiskit-noise-learning/sequences) + * [Visualizations (`qiskit_noise_learning.visualizations`)](/docs/api/qiskit-noise-learning/visualizations) + +## Indices and tables + +* [Index](genindex) +* [Module Index](py-modindex) +* [Search Page](search) + diff --git a/docs/addons/qiskit-noise-learning/prf-prf.mdx b/docs/addons/qiskit-noise-learning/prf-prf.mdx new file mode 100644 index 000000000000..e6e00a83e214 --- /dev/null +++ b/docs/addons/qiskit-noise-learning/prf-prf.mdx @@ -0,0 +1,15 @@ +--- +title: "Proof Index" +description: "Proof Index for the latest version of Qiskit noise liearning" +--- + +# Proof Index + +[**prop-mcm-evolution**](#cap-prop-mcm-evolution) + +| | | | +| - | ------------------------------------------------------------------------------ | ------------- | +| |   | | +| | **prop-mcm-evolution** | | +| | [`prop-mcm-evolution`](formalism/index#prop-mcm-evolution) *(formalism/index)* | *proposition* | + From 8d192052df28721b37f64ab7fb905f1a89c0fd26 Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Thu, 3 Sep 2026 10:44:08 -0400 Subject: [PATCH 05/15] typo! --- docs/addons/qiskit-noise-learning/_toc.json | 2 +- docs/addons/qiskit-noise-learning/formalism/index.mdx | 2 +- docs/addons/qiskit-noise-learning/index.mdx | 2 +- docs/addons/qiskit-noise-learning/prf-prf.mdx | 2 +- scripts/js/lib/api/Pkg.ts | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/addons/qiskit-noise-learning/_toc.json b/docs/addons/qiskit-noise-learning/_toc.json index 2df22fb1a871..86b894972a55 100644 --- a/docs/addons/qiskit-noise-learning/_toc.json +++ b/docs/addons/qiskit-noise-learning/_toc.json @@ -1,7 +1,7 @@ { "parentUrl": "/docs/guides/addons", "parentLabel": "Documentation", - "title": "Qiskit noise liearning 0.1", + "title": "Qiskit noise learning 0.1", "collapsed": true, "children": [ { diff --git a/docs/addons/qiskit-noise-learning/formalism/index.mdx b/docs/addons/qiskit-noise-learning/formalism/index.mdx index e6c1a3583c91..a7014c9521d7 100644 --- a/docs/addons/qiskit-noise-learning/formalism/index.mdx +++ b/docs/addons/qiskit-noise-learning/formalism/index.mdx @@ -1,6 +1,6 @@ --- title: "Mathematical formalism" -description: "Mathematical formalism for the latest version of Qiskit noise liearning" +description: "Mathematical formalism for the latest version of Qiskit noise learning" --- # Mathematical formalism diff --git a/docs/addons/qiskit-noise-learning/index.mdx b/docs/addons/qiskit-noise-learning/index.mdx index 5e85451b0f07..9aa6f9096bc6 100644 --- a/docs/addons/qiskit-noise-learning/index.mdx +++ b/docs/addons/qiskit-noise-learning/index.mdx @@ -1,6 +1,6 @@ --- title: "Qiskit Noise Learning" -description: "Documentation for the latest version of Qiskit noise liearning" +description: "Documentation for the latest version of Qiskit noise learning" --- # Qiskit Noise Learning diff --git a/docs/addons/qiskit-noise-learning/prf-prf.mdx b/docs/addons/qiskit-noise-learning/prf-prf.mdx index e6e00a83e214..0b2272c9312f 100644 --- a/docs/addons/qiskit-noise-learning/prf-prf.mdx +++ b/docs/addons/qiskit-noise-learning/prf-prf.mdx @@ -1,6 +1,6 @@ --- title: "Proof Index" -description: "Proof Index for the latest version of Qiskit noise liearning" +description: "Proof Index for the latest version of Qiskit noise learning" --- # Proof Index diff --git a/scripts/js/lib/api/Pkg.ts b/scripts/js/lib/api/Pkg.ts index b0c9ea76f32a..76918c2490d8 100644 --- a/scripts/js/lib/api/Pkg.ts +++ b/scripts/js/lib/api/Pkg.ts @@ -294,7 +294,7 @@ export class Pkg { if (name === "qiskit-noise-learning") { return new Pkg({ ...args, - title: "Qiskit noise liearning", + title: "Qiskit noise learning", githubSlug: "Qiskit/qiskit-noise-learning", kebabCaseAndShortenUrls: true, language: "Python", From 7a39346b83b68f85385dda69487e31b9680eb83e Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Thu, 3 Sep 2026 10:45:25 -0400 Subject: [PATCH 06/15] typo --- docs/api/qiskit-noise-learning/_toc.json | 2 +- docs/api/qiskit-noise-learning/index.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/api/qiskit-noise-learning/_toc.json b/docs/api/qiskit-noise-learning/_toc.json index 74b66d53397e..b3bd4911c027 100644 --- a/docs/api/qiskit-noise-learning/_toc.json +++ b/docs/api/qiskit-noise-learning/_toc.json @@ -1,5 +1,5 @@ { - "title": "Qiskit noise liearning", + "title": "Qiskit noise learning", "children": [ { "title": "API index", diff --git a/docs/api/qiskit-noise-learning/index.mdx b/docs/api/qiskit-noise-learning/index.mdx index ce65fb433184..54bb421dc0a3 100644 --- a/docs/api/qiskit-noise-learning/index.mdx +++ b/docs/api/qiskit-noise-learning/index.mdx @@ -1,5 +1,5 @@ --- -title: Qiskit noise liearning API documentation (latest version) +title: Qiskit noise learning API documentation (latest version) description: Index of all the modules in the latest version of qiskit-noise-learning. --- From 295b455877b9c78c045b8fa7e19751d6e5985c96 Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Thu, 3 Sep 2026 16:31:21 -0400 Subject: [PATCH 07/15] run gen-api and gen-addon --- .../index.mdx => guides/formalism.mdx} | 46 +-- .../qiskit-noise-learning/guides/index.mdx | 7 + .../guides/noise-learner.mdx | 170 ++++++++++ .../qiskit-noise-learning/guides/workflow.mdx | 294 ++++++++++++++++++ docs/addons/qiskit-noise-learning/index.mdx | 38 +-- docs/addons/qiskit-noise-learning/install.mdx | 21 ++ docs/addons/qiskit-noise-learning/prf-prf.mdx | 10 +- .../api/qiskit-noise-learning/objects.inv | Bin 6206 -> 6303 bytes ...0665f8a0513450d76bfc5ab63e24f40c6b8f6.avif | Bin 0 -> 105531 bytes 9 files changed, 520 insertions(+), 66 deletions(-) rename docs/addons/qiskit-noise-learning/{formalism/index.mdx => guides/formalism.mdx} (59%) create mode 100644 docs/addons/qiskit-noise-learning/guides/index.mdx create mode 100644 docs/addons/qiskit-noise-learning/guides/noise-learner.mdx create mode 100644 docs/addons/qiskit-noise-learning/guides/workflow.mdx create mode 100644 docs/addons/qiskit-noise-learning/install.mdx create mode 100644 public/docs/images/addons/qiskit-noise-learning/cbfeb7989573772757ac81e9b3a0665f8a0513450d76bfc5ab63e24f40c6b8f6.avif diff --git a/docs/addons/qiskit-noise-learning/formalism/index.mdx b/docs/addons/qiskit-noise-learning/guides/formalism.mdx similarity index 59% rename from docs/addons/qiskit-noise-learning/formalism/index.mdx rename to docs/addons/qiskit-noise-learning/guides/formalism.mdx index a7014c9521d7..eb8ba2243943 100644 --- a/docs/addons/qiskit-noise-learning/formalism/index.mdx +++ b/docs/addons/qiskit-noise-learning/guides/formalism.mdx @@ -7,7 +7,7 @@ description: "Mathematical formalism for the latest version of Qiskit noise lear Given the task of learning Pauli noise for a set of Clifford gates, a common analysis technique is to track how individual Pauli operators are transformed through a sequence of gate applications (under the assumption that the gates are Clifford and the noise is a Pauli channel, a single Pauli will always be mapped to another Pauli up to a scalar that is a function of the noise). Obviously, the evolution of *any* state under such a sequence can be captured by a linear combination of such trajectories, but under the assumption that we always prepare the state in a Pauli eigenstate, and always measure and post-process the results to compute the expectation value of a Pauli operator, the relationship between the expectation value and the noise model parameters will *always* depend on only a single such trajectory. This follows from the simple fact that the initial state is a linear combination of Pauli operators, each gate and noise model maps Paulis to Paulis and preserves their orthogonality, and the final expectation value “selects” only one of the Paulis in the final decomposition before measurement. -This type of reasoning appears in many parallel research tracks in noise learning, including in the Pauli gate-set learning literature \[[CCF+26](#id20 "Edward H. Chen, Senrui Chen, Laurin E. Fischer, Andrew Eddins, Luke C. G. Govia, Brad Mitchell, Andre He, Youngseok Kim, Liang Jiang, and Alireza Seif. Disambiguating pauli noise in quantum computers. PRX Quantum, pages, 2026. doi:10.1103/69wc-gzl6."), [CZJF26](#id17 "Senrui Chen, Zhihan Zhang, Liang Jiang, and Steven T. Flammia. Efficient Self-Consistent Learning of Gate Set Pauli Noise. PRX Quantum, 7(1):010305, 2026. URL: https://link.aps.org/doi/10.1103/1pnv-t9px, doi:10.1103/1pnv-t9px.")], the ACES literature \[[Fla22](#id15 "Steven T. Flammia. Averaged Circuit Eigenvalue Sampling. In 17th Conference on the Theory of Quantum Computation, Communication and Cryptography (TQC 2022), volume 232 of Leibniz International Proceedings in Informatics (LIPIcs), 4:1–4:10. Dagstuhl, Germany, 2022. Schloss Dagstuhl – Leibniz-Zentrum für Informatik. doi:10.4230/LIPIcs.TQC.2022.4.")], and the cycle benchmarking literature \[[EWP+19](#id14 "Alexander Erhard, Joel J. Wallman, Lukas Postler, Michael Meth, Roman Stricker, Esteban A. Martinez, Philipp Schindler, Thomas Monz, Joseph Emerson, and Rainer Blatt. Characterizing large-scale quantum computers via cycle benchmarking. Nature Communications, 10(1):5347, 2019. doi:10.1038/s41467-019-13068-7.")]. This reasoning was further generalized in \[[ZCLJ25](#id16 "Zhihan Zhang, Senrui Chen, Yunchao Liu, and Liang Jiang. Generalized Cycle Benchmarking Algorithm for Characterizing Midcircuit Measurements. PRX Quantum, 6(1):010310, 2025. URL: https://link.aps.org/doi/10.1103/PRXQuantum.6.010310, doi:10.1103/PRXQuantum.6.010310.")] to include Clifford-MCM gates (a Clifford gate followed by a projective mid-circuit measurement). This package most closely follows \[[CZJF26](#id17 "Senrui Chen, Zhihan Zhang, Liang Jiang, and Steven T. Flammia. Efficient Self-Consistent Learning of Gate Set Pauli Noise. PRX Quantum, 7(1):010305, 2026. URL: https://link.aps.org/doi/10.1103/1pnv-t9px, doi:10.1103/1pnv-t9px."), [ZCLJ25](#id16 "Zhihan Zhang, Senrui Chen, Yunchao Liu, and Liang Jiang. Generalized Cycle Benchmarking Algorithm for Characterizing Midcircuit Measurements. PRX Quantum, 6(1):010310, 2025. URL: https://link.aps.org/doi/10.1103/PRXQuantum.6.010310, doi:10.1103/PRXQuantum.6.010310.")]. While not explicitly named, we adopt the *Pattern Transfer Graph* (PTG) formalism for describing how Pauli operators evolve through learning circuits, providing a direct data representation of *paths* through the graph. +This type of reasoning appears in many parallel research tracks in noise learning, including in the Pauli gate-set learning literature [\[3\]](#references), [\[4\]](#references), the ACES literature [\[6\]](#references), and the cycle benchmarking literature [\[5\]](#references). This reasoning was further generalized in [\[7\]](#references) to include Clifford-MCM gates (a Clifford gate followed by a projective mid-circuit measurement). This package most closely follows [\[4\]](#references), [\[7\]](#references). While not explicitly named, we adopt the *Pattern Transfer Graph* (PTG) formalism for describing how Pauli operators evolve through learning circuits, providing a direct data representation of *paths* through the graph. The following is a review of some core mathematical concepts from the literature. It is primarily meant to consolidate notation, and to serve as a conceptual documentation reference for the rest of the package. @@ -17,7 +17,7 @@ The following is a review of some core mathematical concepts from the literature -### 1 .1 Notation +### 1.1 Notation For $K \in \mathbb{N}$, let $[K] = \{0, 1, \dots, K - 1\}$. For a finite set $S \subset \mathbb{N}$ of qubit indices, let $\P^S$ denote the set of *unphased* Pauli operators acting on those qubits. Note that we think of elements of $\P^S$ as functions mapping $S \rightarrow \{I, X, Y, Z\}$, so that for any $P \in \P^S$ and $T \subseteq S$, $P|_T$ denotes the restriction of $P$ to the qubit subset $T$. Along these lines, for disjoint sets $S, T$, and $P \in \P^S$ and $Q \in \P^T$, $P \otimes Q$ denotes the element of $\P^{S \cup T}$ such that $P \otimes Q |_S = P$ and $P \otimes Q |_T = Q$. This notation is helpful to avoid explicitly dealing with subsystem orderings, and to make it easy to describe restrictions. @@ -49,7 +49,7 @@ The formalism utilized in this package assumes every gate in the gate set to be This is a general class of operations that includes unitary Clifford gates, measurement, state preparation, and any combination of the above. Note that we assume measurement and reset are always along the $Z$-axis for each qubit. While this is not strictly required, it is a common feature of many quantum computing modalities, and enables simplified representations and analysis. -As outlined in \[[BW23](#id18 "Stefanie J. Beale and Joel J. Wallman. Randomized compiling for subsystem measurements. 2023. URL: http://arxiv.org/abs/2304.06599, doi:10.48550/arXiv.2304.06599."), [ZCLJ25](#id16 "Zhihan Zhang, Senrui Chen, Yunchao Liu, and Liang Jiang. Generalized Cycle Benchmarking Algorithm for Characterizing Midcircuit Measurements. PRX Quantum, 6(1):010310, 2025. URL: https://link.aps.org/doi/10.1103/PRXQuantum.6.010310, doi:10.1103/PRXQuantum.6.010310.")] for the no-reset case, if a specific twirling strategy is applied to a noisy instance of such a gate, then the action of the resulting operation can be modeled mathematically as a *uniform Pauli instrument*. That is, within the quantum instrument notation, $\E_m = \U_mG$, where $G$ is the Clifford unitary, and: +As outlined in [\[1\]](#references), [\[7\]](#references) for the no-reset case, if a specific twirling strategy is applied to a noisy instance of such a gate, then the action of the resulting operation can be modeled mathematically as a *uniform Pauli instrument*. That is, within the quantum instrument notation, $\E_m = \U_mG$, where $G$ is the Clifford unitary, and: $$ \U_m = \sum_{a,b \in \Z_2^M} \Lambda_{a,b} \otimes \opket{m + a}\opbra{m + b}, @@ -62,9 +62,9 @@ where each $\Lambda_{a,b}$ is a sub-normalized Pauli channel on the unmeasured q In words, a single term in the above sum represents observing a measurement outcome of $m$ when the measured state was $\ket{m + b}$ (a misclassification if $b \neq 0$), and when the output state on the measurement register is $\ket{m + a}$ (the “wrong” state when $a \neq 0$). The map $\Lambda_{a,b}$ simultaneously encodes the action on the unmeasured qubits (conditioned on the measurement behavior) and the *probability* of the specific measurement behavior (through the normalization). -Note that we are not concerned here with the specifics of the twirling strategy: that such a strategy exists to put the channel into the above form is enough. Note that “finer” twirling strategies exist which can further restrict the form of the Pauli channels \[[BW24](#id19 "Ewout van den Berg and Pawel Wocjan. Techniques for learning sparse Pauli-Lindblad noise models. Quantum, 8:1556, 2024. URL: https://quantum-journal.org/papers/q-2024-12-10-1556/, doi:10.22331/q-2024-12-10-1556.")]; however, we take the above form as the most general mathematical representation under consideration. +Note that we are not concerned here with the specifics of the twirling strategy: that such a strategy exists to put the channel into the above form is enough. Note that “finer” twirling strategies exist which can further restrict the form of the Pauli channels [\[2\]](#references); however, we take the above form as the most general mathematical representation under consideration. -In Lemma 1 of \[[ZCLJ25](#id16 "Zhihan Zhang, Senrui Chen, Yunchao Liu, and Liang Jiang. Generalized Cycle Benchmarking Algorithm for Characterizing Midcircuit Measurements. PRX Quantum, 6(1):010310, 2025. URL: https://link.aps.org/doi/10.1103/PRXQuantum.6.010310, doi:10.1103/PRXQuantum.6.010310.")], it is shown that $\E_m = \U_mG$ can be rewritten as: +In Lemma 1 of [\[7\]](#references), it is shown that $\E_m = \U_mG$ can be rewritten as: $$ \E_m = \frac{1}{2^{2|M| + |N|}}\sum_{x, y \in \Z_2^M, Q \in \P^N} (-1)^{m \cdot (x + y)} @@ -105,9 +105,9 @@ Finally, it is important to note that any twirling strategy yielding the form in As described in the introduction, all learning algorithms for Pauli-type noise on Clifford gates are based around tracking how individual Paulis evolve through a circuit, picking up noise fidelity factors along the way. The expectation values of a circuit composed of such gates are therefore related simply to products of the underlying fidelities of the individual gates, and in this way model parameters can be inferred by *inverting* whatever sparse parameter-to-fidelity mapping is being assumed. -In \[[CZJF26](#id17 "Senrui Chen, Zhihan Zhang, Liang Jiang, and Steven T. Flammia. Efficient Self-Consistent Learning of Gate Set Pauli Noise. PRX Quantum, 7(1):010305, 2026. URL: https://link.aps.org/doi/10.1103/1pnv-t9px, doi:10.1103/1pnv-t9px.")], in the context of unitary gate sets, this is formalized into the *Pattern Transfer Graph* (PTG): a directed graph describing all possible experiments consisting of elements of the gate set and layers of single-qubit Clifford gates (assumed to be perfect, or “free”, operations). This was generalized in \[[ZCLJ25](#id16 "Zhihan Zhang, Senrui Chen, Yunchao Liu, and Liang Jiang. Generalized Cycle Benchmarking Algorithm for Characterizing Midcircuit Measurements. PRX Quantum, 6(1):010310, 2025. URL: https://link.aps.org/doi/10.1103/PRXQuantum.6.010310, doi:10.1103/PRXQuantum.6.010310.")] to include gate sets with mid-circuit measurements. In both cases, each experiment is described by tracking a single Pauli operator through the circuit, under the assumption of a particular observable being computed at each measurement site. Here we do not directly review the graph or path constructions; however, we present the required facts for justifying them within our own notation and with resets included. +In [\[4\]](#references), in the context of unitary gate sets, this is formalized into the *Pattern Transfer Graph* (PTG): a directed graph describing all possible experiments consisting of elements of the gate set and layers of single-qubit Clifford gates (assumed to be perfect, or “free”, operations). This was generalized in [\[7\]](#references) to include gate sets with mid-circuit measurements. In both cases, each experiment is described by tracking a single Pauli operator through the circuit, under the assumption of a particular observable being computed at each measurement site. Here we do not directly review the graph or path constructions; however, we present the required facts for justifying them within our own notation and with resets included. -While the tracking of a single Pauli operator through the circuit may be intuitive in the unitary gate set case, it does not so obviously hold in the more general Clifford-MCM-reset case, due to the non-deterministic nature of measurement. The following proposition recovers this picture even in the more general case \[[ZCLJ25](#id16 "Zhihan Zhang, Senrui Chen, Yunchao Liu, and Liang Jiang. Generalized Cycle Benchmarking Algorithm for Characterizing Midcircuit Measurements. PRX Quantum, 6(1):010310, 2025. URL: https://link.aps.org/doi/10.1103/PRXQuantum.6.010310, doi:10.1103/PRXQuantum.6.010310.")]: +While the tracking of a single Pauli operator through the circuit may be intuitive in the unitary gate set case, it does not so obviously hold in the more general Clifford-MCM-reset case, due to the non-deterministic nature of measurement. The following proposition recovers this picture even in the more general case [\[7\]](#references): @@ -150,35 +150,23 @@ $$ Lastly, observe that $\delta_{y,b}\delta_{x+y|_M,a+b|_M} = \delta_{y,b}\delta_{x,a}$, and hence the final term above collapses down to the single term $\lambda^Q_{x,y} \opbra{G^\dagger(Q \otimes I_{N \cap R} \otimes Z^x)}$, yielding the desired result. -See \[[ZCLJ25](#id16 "Zhihan Zhang, Senrui Chen, Yunchao Liu, and Liang Jiang. Generalized Cycle Benchmarking Algorithm for Characterizing Midcircuit Measurements. PRX Quantum, 6(1):010310, 2025. URL: https://link.aps.org/doi/10.1103/PRXQuantum.6.010310, doi:10.1103/PRXQuantum.6.010310.")] for development beyond this point: the definition of the PTG, paths through the PTG, and the proof that any properly-defined path corresponds to an experiment. +See [\[7\]](#references) for development beyond this point: the definition of the PTG, paths through the PTG, and the proof that any properly-defined path corresponds to an experiment. -## References - -\[[BW23](#id6)] - -Stefanie J. Beale and Joel J. Wallman. Randomized compiling for subsystem measurements. 2023. URL: [http://arxiv.org/abs/2304.06599](http://arxiv.org/abs/2304.06599), [doi:10.48550/arXiv.2304.06599](https://doi.org/10.48550/arXiv.2304.06599). - -\[[BW24](#id7)] + -Ewout van den Berg and Pawel Wocjan. Techniques for learning sparse Pauli-Lindblad noise models. *Quantum*, 8:1556, 2024. URL: [https://quantum-journal.org/papers/q-2024-12-10-1556/](https://quantum-journal.org/papers/q-2024-12-10-1556/), [doi:10.22331/q-2024-12-10-1556](https://doi.org/10.22331/q-2024-12-10-1556). - -\[[CCF+26](#id1)] - -Edward H. Chen, Senrui Chen, Laurin E. Fischer, Andrew Eddins, Luke C. G. Govia, Brad Mitchell, Andre He, Youngseok Kim, Liang Jiang, and Alireza Seif. Disambiguating pauli noise in quantum computers. *PRX Quantum*, pages, 2026. [doi:10.1103/69wc-gzl6](https://doi.org/10.1103/69wc-gzl6). - -\[CZJF26] ([1](#id1),[2](#id5),[3](#id9)) +## References -Senrui Chen, Zhihan Zhang, Liang Jiang, and Steven T. Flammia. Efficient Self-Consistent Learning of Gate Set Pauli Noise. *PRX Quantum*, 7(1):010305, 2026. URL: [https://link.aps.org/doi/10.1103/1pnv-t9px](https://link.aps.org/doi/10.1103/1pnv-t9px), [doi:10.1103/1pnv-t9px](https://doi.org/10.1103/1pnv-t9px). +\[1] Stefanie J. Beale and Joel J. Wallman. Randomized compiling for subsystem measurements. 2023. URL: [http://arxiv.org/abs/2304.06599](http://arxiv.org/abs/2304.06599), doi:10.48550/arXiv.2304.06599. -\[[EWP+19](#id3)] +\[2] Ewout van den Berg and Pawel Wocjan. Techniques for learning sparse Pauli-Lindblad noise models. *Quantum*, 8:1556, 2024. URL: [https://quantum-journal.org/papers/q-2024-12-10-1556/](https://quantum-journal.org/papers/q-2024-12-10-1556/), doi:10.22331/q-2024-12-10-1556. -Alexander Erhard, Joel J. Wallman, Lukas Postler, Michael Meth, Roman Stricker, Esteban A. Martinez, Philipp Schindler, Thomas Monz, Joseph Emerson, and Rainer Blatt. Characterizing large-scale quantum computers via cycle benchmarking. *Nature Communications*, 10(1):5347, 2019. [doi:10.1038/s41467-019-13068-7](https://doi.org/10.1038/s41467-019-13068-7). +\[3] Edward H. Chen, Senrui Chen, Laurin E. Fischer, Andrew Eddins, Luke C. G. Govia, Brad Mitchell, Andre He, Youngseok Kim, Liang Jiang, and Alireza Seif. Disambiguating pauli noise in quantum computers. *PRX Quantum*, pages, 2026. doi:10.1103/69wc-gzl6. -\[[Fla22](#id2)] +\[4] Senrui Chen, Zhihan Zhang, Liang Jiang, and Steven T. Flammia. Efficient Self-Consistent Learning of Gate Set Pauli Noise. *PRX Quantum*, 7(1):010305, 2026. URL: [https://link.aps.org/doi/10.1103/1pnv-t9px](https://link.aps.org/doi/10.1103/1pnv-t9px), doi:10.1103/1pnv-t9px. -Steven T. Flammia. Averaged Circuit Eigenvalue Sampling. In *17th Conference on the Theory of Quantum Computation, Communication and Cryptography (TQC 2022)*, volume 232 of Leibniz International Proceedings in Informatics (LIPIcs), 4:1–4:10. Dagstuhl, Germany, 2022. Schloss Dagstuhl – Leibniz-Zentrum für Informatik. [doi:10.4230/LIPIcs.TQC.2022.4](https://doi.org/10.4230/LIPIcs.TQC.2022.4). +\[5] Alexander Erhard, Joel J. Wallman, Lukas Postler, Michael Meth, Roman Stricker, Esteban A. Martinez, Philipp Schindler, Thomas Monz, Joseph Emerson, and Rainer Blatt. Characterizing large-scale quantum computers via cycle benchmarking. *Nature Communications*, 10(1):5347, 2019. doi:10.1038/s41467-019-13068-7. -\[ZCLJ25] ([1](#id4),[2](#id5),[3](#id6),[4](#id8),[5](#id10),[6](#id11),[7](#id12)) +\[6] Steven T. Flammia. Averaged Circuit Eigenvalue Sampling. In 17th Conference on the Theory of Quantum Computation, Communication and Cryptography (TQC 2022), volume 232 of *Leibniz International Proceedings in Informatics* (LIPIcs), 4:1–4:10. Dagstuhl, Germany, 2022. Schloss Dagstuhl – Leibniz-Zentrum für Informatik. doi:10.4230/LIPIcs.TQC.2022.4. -Zhihan Zhang, Senrui Chen, Yunchao Liu, and Liang Jiang. Generalized Cycle Benchmarking Algorithm for Characterizing Midcircuit Measurements. *PRX Quantum*, 6(1):010310, 2025. URL: [https://link.aps.org/doi/10.1103/PRXQuantum.6.010310](https://link.aps.org/doi/10.1103/PRXQuantum.6.010310), [doi:10.1103/PRXQuantum.6.010310](https://doi.org/10.1103/PRXQuantum.6.010310). +\[7] Zhihan Zhang, Senrui Chen, Yunchao Liu, and Liang Jiang. Generalized Cycle Benchmarking Algorithm for Characterizing Midcircuit Measurements. *PRX Quantum*, 6(1):010310, 2025. URL: [https://link.aps.org/doi/10.1103/PRXQuantum.6.010310](https://link.aps.org/doi/10.1103/PRXQuantum.6.010310), doi:10.1103/PRXQuantum.6.010310. diff --git a/docs/addons/qiskit-noise-learning/guides/index.mdx b/docs/addons/qiskit-noise-learning/guides/index.mdx new file mode 100644 index 000000000000..77480609e7f0 --- /dev/null +++ b/docs/addons/qiskit-noise-learning/guides/index.mdx @@ -0,0 +1,7 @@ +--- +title: "Guides" +description: "Guides for the latest version of Qiskit noise learning" +--- + +# Guides + diff --git a/docs/addons/qiskit-noise-learning/guides/noise-learner.mdx b/docs/addons/qiskit-noise-learning/guides/noise-learner.mdx new file mode 100644 index 000000000000..24e8e7edb794 --- /dev/null +++ b/docs/addons/qiskit-noise-learning/guides/noise-learner.mdx @@ -0,0 +1,170 @@ +--- +title: "Learn the noise model of a gate with NoiseLearner" +description: "Learn the noise model of a gate with NoiseLearner for the latest version of Qiskit noise learning" +--- + +# Learn the noise model of a gate with NoiseLearner + +This guide demonstrates using [`NoiseLearner`](/docs/api/qiskit-noise-learning/generated-noise-learner-noise-learner#qiskit_noise_learning.noise_learner.NoiseLearner "qiskit_noise_learning.noise_learner.NoiseLearner") to learn a noise model for a unitary gate. + +1. Define the gate +2. Set up local simulation +3. Run the learner +4. Read the results + + + The circuits below are simulated locally, so this walkthrough needs no IBM Quantum® credentials. Two changes take it to a real device, each flagged again where it applies: + + * **Step 1**: replace [`FakeMarrakesh`](/docs/api/qiskit-ibm-runtime/fake-provider-fake-marrakesh "(in Qiskit Runtime IBM Client)") with a real backend. + * **Step 2**: skip it, and drop the `executor` argument in step 3. + + + + +## 1. Define the gate + +The gate whose noise we will learn is a [`BoxOp`](/docs/api/qiskit/qiskit.circuit.BoxOp) holding a layer of six disjoint `CZ` gates, with two Samplomatic annotations: `Twirl()` marks the box for Pauli twirling, and `InjectNoise("cz_gate")` names it. That name is the key under which the learned noise map is reported — and, because this guide simulates the gate, also the key under which noise is injected. + +```python +from qiskit.circuit import QuantumCircuit +from qiskit_ibm_runtime.fake_provider import FakeMarrakesh +from samplomatic import InjectNoise, Twirl + +backend = FakeMarrakesh() + +cz_pairs = [(91, 92), (93, 94), (95, 99), (98, 111), (112, 113), (114, 115)] + +circuit = QuantumCircuit(backend.num_qubits) +with circuit.box([Twirl(), InjectNoise("cz_gate")]): + for pair in cz_pairs: + circuit.cz(*pair) +``` + + + ```python + from qiskit_ibm_runtime import QiskitRuntimeService + + backend = QiskitRuntimeService().backend("ibm_marrakesh") + ``` + + + + +## 2. Set up local simulation + +An [`AerExecutor`](/docs/api/qiskit-noise-learning/generated-aer-executor-aer-executor#qiskit_noise_learning.aer_executor.AerExecutor "qiskit_noise_learning.aer_executor.AerExecutor") runs a program on a local Aer simulator, injecting Pauli-Lindblad noise at the barriers Samplomatic places around each twirled gate. + +The Pauli indices inside each map are local to the gate, in ascending physical-qubit order: + +```python +cz_qubits = sorted({qubit for pair in cz_pairs for qubit in pair}) +local = {qubit: index for index, qubit in enumerate(cz_qubits)} +local +``` + +```myst +{91: 0, + 92: 1, + 93: 2, + 94: 3, + 95: 4, + 98: 5, + 99: 6, + 111: 7, + 112: 8, + 113: 9, + 114: 10, + 115: 11} +``` + +The gate gets a correlated `ZZ` term and a weaker `XX` term on each `CZ` pair, plus a single-qubit `Z` term everywhere; preparation and measurement each get a bit-flip term per qubit. + +```python +from qiskit.quantum_info import PauliLindbladMap + +num_qubits = len(cz_qubits) + +cz_noise = PauliLindbladMap.from_sparse_list( + [("ZZ", [local[a], local[b]], 8e-4) for a, b in cz_pairs] + + [("XX", [local[a], local[b]], 4e-4) for a, b in cz_pairs] + + [("Z", [index], 3e-4) for index in range(num_qubits)], + num_qubits=num_qubits, +) + +spam_noise = PauliLindbladMap.from_sparse_list( + [("X", [index], 5e-3) for index in range(num_qubits)], num_qubits=num_qubits +) + +noise_dict = {"cz_gate": cz_noise, "P": spam_noise, "M": spam_noise} +``` + +Instantiate [`AerExecutor`](/docs/api/qiskit-noise-learning/generated-aer-executor-aer-executor#qiskit_noise_learning.aer_executor.AerExecutor "qiskit_noise_learning.aer_executor.AerExecutor") with the stabilizer method. Set `root_seed` to make the simulated data reproducible. + +```python +from qiskit_aer import AerSimulator + +from qiskit_noise_learning.aer_executor import AerExecutor + +executor = AerExecutor( + AerSimulator(method="stabilizer"), noise_dict=noise_dict, root_seed=1234 +) +``` + + + Skip this step entirely. + + + + +## 3. Run the learner + +[`LearningOptions`](/docs/api/qiskit-noise-learning/generated-noise-learner-learning-options#qiskit_noise_learning.noise_learner.LearningOptions "qiskit_noise_learning.noise_learner.LearningOptions") controls the shape of the experiment: how deep the twirled gate is repeated, and how many randomizations and shots are spent at each depth. Passing `executor` diverts the generated program to the simulator; leave it out and [`NoiseLearner`](/docs/api/qiskit-noise-learning/generated-noise-learner-noise-learner#qiskit_noise_learning.noise_learner.NoiseLearner "qiskit_noise_learning.noise_learner.NoiseLearner") submits to `backend` through IBM Quantum instead. + +```python +from qiskit_noise_learning.noise_learner import LearningOptions, NoiseLearner + +options = LearningOptions( + fragment_depths=[2, 16, 64, 128], + num_randomizations=50, + shots_per_randomizations=20, +) + +learner = NoiseLearner(backend, options=options, executor=executor) + +job = learner.run([circuit[0]]) +result = job.result() +``` + + + ```python + learner = NoiseLearner(backend, options=options) + ``` + + + + +## 4. Read the results + +Everything the analysis pipeline produced is reachable through [`fit`](/docs/api/qiskit-noise-learning/generated-noise-learner-noise-learner-result#qiskit_noise_learning.noise_learner.NoiseLearnerResult.fit "qiskit_noise_learning.noise_learner.NoiseLearnerResult.fit"). Use the fit to plot per-qubit-pair fidelity decays: both the data and the exponential fit. + +```python +result.fit.plot_qubit_pair_decays( + pairs=cz_pairs, + observable_type="means", + exponential_fit=True, +) +``` + +Extract the learned noise from [`to_dict()`](/docs/api/qiskit-noise-learning/generated-noise-learner-noise-learner-result#qiskit_noise_learning.noise_learner.NoiseLearnerResult.to_dict "qiskit_noise_learning.noise_learner.NoiseLearnerResult.to_dict"): one [`PauliLindbladMap`](/docs/api/qiskit/qiskit.quantum_info.PauliLindbladMap) per learned gate, keyed by the name from the `InjectNoise` annotation, and expressed in the backend’s own qubit indexing rather than that of the gate. + +```python +learned = result.to_dict()["cz_gate"] +learned.num_terms +``` + +```myst +144 +``` + +By default [`NoiseLearner`](/docs/api/qiskit-noise-learning/generated-noise-learner-noise-learner#qiskit_noise_learning.noise_learner.NoiseLearner "qiskit_noise_learning.noise_learner.NoiseLearner") fits a 2-local model, so the map carries a term for every Pauli supported on a connected pair of the gate’s qubits — 144 of them, of which only 24 were given a nonzero rate in step 2. + diff --git a/docs/addons/qiskit-noise-learning/guides/workflow.mdx b/docs/addons/qiskit-noise-learning/guides/workflow.mdx new file mode 100644 index 000000000000..b33a3377dc5a --- /dev/null +++ b/docs/addons/qiskit-noise-learning/guides/workflow.mdx @@ -0,0 +1,294 @@ +--- +title: "Build a learning experiment" +description: "Build a learning experiment for the latest version of Qiskit noise learning" +--- + +# Build a learning experiment + +This guide demonstrates how to build a standard learning experiment from scratch, and use it to learn a model from simulated noisy data. + +1. Define a gate set on a ring of qubits +2. Choose a 2-local Pauli-Lindblad model +3. Build the learning experiment +4. Generate circuits +5. Set up local simulation +6. Run the program +7. Analyze the data + + + The circuits below are simulated locally, so this walkthrough needs no IBM Quantum® credentials. Three changes take it to a real device, each flagged again where it applies: + + * **Step 1**: replace [`FakeMarrakesh`](/docs/api/qiskit-ibm-runtime/fake-provider-fake-marrakesh "(in Qiskit Runtime IBM Client)") with a real backend. + * **Step 5**: skip it. + * **Step 6**: submit through [`Executor`](/docs/api/qiskit-ibm-runtime/executor "(in Qiskit Runtime IBM Client)"). + + + + +## 1. Define a gate set on a ring of qubits + +Build a [`QiskitGateSet`](/docs/api/qiskit-noise-learning/generated-gate-sets-qiskit-gate-set#qiskit_noise_learning.gate_sets.QiskitGateSet "qiskit_noise_learning.gate_sets.QiskitGateSet") from a backend [`Target`](/docs/api/qiskit/qiskit.transpiler.Target) and a subset of its qubits — here a twelve-qubit ring of [`FakeMarrakesh`](/docs/api/qiskit-ibm-runtime/fake-provider-fake-marrakesh "(in Qiskit Runtime IBM Client)") — then add one gate to it: a layer of six `CZ` gates covering that ring. By default the gate set is initialized with a preparation gate `P` and a measurement gate `M`. + +```python +from qiskit_ibm_runtime.fake_provider import FakeMarrakesh + +from qiskit_noise_learning.gate_sets import QiskitGateSet + +backend = FakeMarrakesh() + +qubit_subset = [*range(25, 30), *range(37, 39), *range(45, 50)] +cz_pairs = [(25, 26), (27, 28), (29, 38), (37, 45), (46, 47), (48, 49)] + +gate_set = QiskitGateSet(backend.num_qubits, target=backend.target, qubit_subset=qubit_subset) + +with gate_set.build_new_gate("cz_gate", latex_str=r"\mathrm{CZ}") as builder: + for pair in cz_pairs: + builder.circuit.cz(*pair) + +list(gate_set) +``` + +```myst +['M', 'P', 'cz_gate'] +``` + + + ```python + from qiskit_ibm_runtime import QiskitRuntimeService + + backend = QiskitRuntimeService().backend("ibm_marrakesh") + ``` + + +Call [`draw()`](/docs/api/qiskit-noise-learning/generated-gate-sets-gate-set#qiskit_noise_learning.gate_sets.GateSet.draw "qiskit_noise_learning.gate_sets.GateSet.draw") to see the gate on the device topology: the ring of qubits in the gate set, and which pairs of them the gate entangles. + +```python +gate_set.draw() +``` + + + +## 2. Choose a 2-local Pauli-Lindblad model + +Decide which Pauli-Lindblad generators the noise is allowed to have with a [`PauliLindbladModel`](/docs/api/qiskit-noise-learning/generated-models-pauli-lindblad-model#qiskit_noise_learning.models.PauliLindbladModel "qiskit_noise_learning.models.PauliLindbladModel"). Build that generator set from the gate set’s connectivity with [`k_local()`](/docs/api/qiskit-noise-learning/generated-models-pauli-lindblad-model#qiskit_noise_learning.models.PauliLindbladModel.k_local "qiskit_noise_learning.models.PauliLindbladModel.k_local") — here every 2-local Pauli on connected qubit pairs of the unitary gate, and single-qubit Paulis for preparation and measurement. + +```python +from qiskit_noise_learning.models import PauliLindbladModel + +model = PauliLindbladModel.k_local(gate_set, gate_k={"cz_gate": 2, "M": 1, "P": 1}) +``` + +Display the unknown parameter count for the noise model of each gate. + +```python +{name: len(generators) for name, generators in model.generators.items()} +``` + +```myst +{'M': 12, 'P': 12, 'cz_gate': 144} +``` + + + +## 3. Build the learning experiment + +Assemble an [`Experiment`](/docs/api/qiskit-noise-learning/generated-experiment-builder-experiment#qiskit_noise_learning.experiment_builder.Experiment "qiskit_noise_learning.experiment_builder.Experiment") by composing builder stages. Each stage reads what earlier stages wrote, so order matters: + +```python +from qiskit_noise_learning.experiment_builder import ( + BindFragmentDepths, + CompleteSequences, + EvenDepthVanillaPaths, + Experiment, + GenerateInstructionSequences, + IdentifyRelations, + MergeInstructionSequences, + SPAMPaths, + VanillaInstructionSequences, +) + +experiment_builder = ( + # Add standard vanilla learning paths and instruction sequences, and identify relations + EvenDepthVanillaPaths() + + VanillaInstructionSequences() + + IdentifyRelations() + # Add paths for learning SPAM, then generate and merge instruction sequences for measuring them + + SPAMPaths() + + GenerateInstructionSequences() + + MergeInstructionSequences() + # Finalize by completing the instruction sequences and setting experiment depths + + CompleteSequences() + + BindFragmentDepths([2, 16, 32, 64]) +) + +experiment = experiment_builder.run( + Experiment(fidelity_model=model, shots=20, randomizations=50) +) + +print(f"Number of paths: {len(experiment.paths)}") +print(f"Number of instruction sequences: {len(experiment.instruction_sequences)}") +``` + +```myst +Number of paths: 156 +Number of instruction sequences: 37 +``` + +Observe design matrix rank: + +```python +print(f"Design matrix rank: {experiment.design_matrix.rank}") +``` + +```myst +Design matrix rank: 120 +``` + + + +## 4. Generate circuits + +Compile the experiment with an [`ExecutorCircuitGenerator`](/docs/api/qiskit-noise-learning/generated-circuit-generator-executor-circuit-generator#qiskit_noise_learning.circuit_generator.ExecutorCircuitGenerator "qiskit_noise_learning.circuit_generator.ExecutorCircuitGenerator"), generating a [`QuantumProgram`](/docs/api/qiskit-ibm-runtime/quantum-program-quantum-program "(in Qiskit Runtime IBM Client)") — one parameterized template circuit per fragment depth — together with a data mapper that records how to interpret results. + +```python +from qiskit_noise_learning.circuit_generator import ExecutorCircuitGenerator + +circuit_generator = ExecutorCircuitGenerator(gate_set) +quantum_program, data_mapper = circuit_generator.generate(experiment) + +print(f"Number of template circuits: {len(quantum_program.items)}") +``` + +```myst +Number of template circuits: 5 +``` + +Draw a template circuit to inspect. + +```python +quantum_program.items[0].circuit.draw("mpl", idle_wires=False, fold=False) +``` + +![../\_images/cbfeb7989573772757ac81e9b3a0665f8a0513450d76bfc5ab63e24f40c6b8f6.png](/docs/images/addons/qiskit-noise-learning/cbfeb7989573772757ac81e9b3a0665f8a0513450d76bfc5ab63e24f40c6b8f6.avif) + + + +## 5. Set up local simulation + +An [`AerExecutor`](/docs/api/qiskit-noise-learning/generated-aer-executor-aer-executor#qiskit_noise_learning.aer_executor.AerExecutor "qiskit_noise_learning.aer_executor.AerExecutor") runs a program on a local Aer simulator, injecting Pauli-Lindblad noise at the barriers Samplomatic places around each twirled gate. + +Unlike the hand-picked noise of the [`NoiseLearner`](/docs/api/qiskit-noise-learning/generated-noise-learner-noise-learner#qiskit_noise_learning.noise_learner.NoiseLearner "qiskit_noise_learning.noise_learner.NoiseLearner") guide, give *every one* of the model’s 168 generators an independent random rate. The model’s generators are already exactly the Paulis to put in a [`PauliLindbladMap`](/docs/api/qiskit/qiskit.quantum_info.PauliLindbladMap), so pair each one with a rate and build the map per gate directly: + +```python +import numpy as np +from qiskit.quantum_info import PauliLindbladMap + +rng = np.random.default_rng(1234) + +true_maps = { + name: PauliLindbladMap.from_terms( + [ + PauliLindbladMap.GeneratorTerm(rate, generator) + for generator, rate in zip(generators, rng.uniform(2e-4, 1.5e-3, len(generators))) + ] + ) + for name, generators in model.generators.items() +} +{name: noise_map.num_qubits for name, noise_map in true_maps.items()} +``` + +```myst +{'M': 156, 'P': 156, 'cz_gate': 156} +``` + +Those maps are as wide as the device, since the model is expressed in `backend`’s qubit indexing, but [`AerExecutor`](/docs/api/qiskit-noise-learning/generated-aer-executor-aer-executor#qiskit_noise_learning.aer_executor.AerExecutor "qiskit_noise_learning.aer_executor.AerExecutor") wants each map to be as wide as the gate it applies to, with Pauli indices running over the gate’s qubits in ascending physical order. Narrow them with [`keep_qubits()`](/docs/api/qiskit/qiskit.quantum_info.PauliLindbladMap#keep_qubits), which traces out everything off the ring: + +```python +noise_dict = { + name: noise_map.keep_qubits(qubit_subset) for name, noise_map in true_maps.items() +} +{name: noise_map.num_qubits for name, noise_map in noise_dict.items()} +``` + +```myst +{'M': 12, 'P': 12, 'cz_gate': 12} +``` + +Instantiate [`AerExecutor`](/docs/api/qiskit-noise-learning/generated-aer-executor-aer-executor#qiskit_noise_learning.aer_executor.AerExecutor "qiskit_noise_learning.aer_executor.AerExecutor") with the stabilizer method. Set `root_seed` to make the simulated data reproducible. + +```python +from qiskit_aer import AerSimulator + +from qiskit_noise_learning.aer_executor import AerExecutor + +executor = AerExecutor( + AerSimulator(method="stabilizer"), noise_dict=noise_dict, root_seed=42 +) +``` + + + Skip this step entirely. + + + + +## 6. Run the program + +Run the program, then pair the returned bitstrings with the data mapper using [`collect()`](/docs/api/qiskit-noise-learning/generated-circuit-generator-executor-circuit-generator#qiskit_noise_learning.circuit_generator.ExecutorCircuitGenerator.collect "qiskit_noise_learning.circuit_generator.ExecutorCircuitGenerator.collect"), which produces a [`Fit`](/docs/api/qiskit-noise-learning/generated-analysis-fit#qiskit_noise_learning.analysis.Fit "qiskit_noise_learning.analysis.Fit") — the container the analysis stages read from and write to. + +```python +job = executor.run(quantum_program) +fit = circuit_generator.collect(job.result(), data_mapper) +``` + + + ```python + from qiskit_ibm_runtime import Executor + + executor = Executor(mode=backend) + ``` + + + + +## 7. Analyze the data + +Build an analysis pipeline around nonnegative least squares fitting of the model. + +```python +from qiskit_noise_learning.analysis import ( + ComputeObservables, # computes observables from raw data + CurveFitObservables, # performs exponential fitting + NNLSSolve, # solves model with nonnegative least squares +) + +analyzer = ComputeObservables() + CurveFitObservables() + NNLSSolve() + +fit = analyzer.run(fit) +``` + +```myst +/opt/hostedtoolcache/Python/3.12.14/x64/lib/python3.12/site-packages/qiskit_noise_learning/analysis/model_solve.py:244: UserWarning: 3 of 156 row(s) of the linear system have a non-positive or non-finite uncertainty, so they carry no usable statistical weight. Positions in LinearSystemData.row_labels: 145, 146, 147. + system = LinearSystemData.from_fit(fit) +``` + +Plot the measured observable means against their fitted exponentials, one subplot per `CZ` pair, to see whether the decays being fitted are exponential at all. + +```python +fit.plot_qubit_pair_decays( + pairs=cz_pairs, + observable_type="means", + exponential_fit=True, +) +``` + +Swap `exponential_fit` for `model_prediction` to compare the same data against the decays implied by the rates that came out of the non-negative least squares solve. + +```python +fit.plot_qubit_pair_decays( + pairs=cz_pairs, + observable_type="means", + model_prediction=True, +) +``` + diff --git a/docs/addons/qiskit-noise-learning/index.mdx b/docs/addons/qiskit-noise-learning/index.mdx index 9aa6f9096bc6..204184c3e929 100644 --- a/docs/addons/qiskit-noise-learning/index.mdx +++ b/docs/addons/qiskit-noise-learning/index.mdx @@ -1,39 +1,13 @@ --- -title: "Qiskit Noise Learning" +title: "Qiskit noise learning" description: "Documentation for the latest version of Qiskit noise learning" --- -# Qiskit Noise Learning +# Qiskit noise learning -* [Tutorials](tutorials/index) +A Python toolkit for randomization-based quantum noise characterization. - * [Learn the noise model of a gate with NoiseLearner](tutorials/noise-learner) - * [Build a learning experiment](tutorials/workflow) - -* [Mathematical formalism](formalism/index) - - * [1. Background](formalism/index#background) - * [2. Noisy Clifford-MCM-reset gates](formalism/index#noisy-clifford-mcm-reset-gates) - * [3. Path formalism](formalism/index#path-formalism) - * [References](formalism/index#references) - -* [API reference](/docs/api/qiskit-noise-learning/index) - - * [Aer executor (`qiskit_noise_learning.aer_executor`)](/docs/api/qiskit-noise-learning/aer-executor) - * [Analysis (`qiskit_noise_learning.analysis`)](/docs/api/qiskit-noise-learning/analysis) - * [Circuit generator (`qiskit_noise_learning.circuit_generator`)](/docs/api/qiskit-noise-learning/circuit-generator) - * [Data (`qiskit_noise_learning.data`)](/docs/api/qiskit-noise-learning/data) - * [Experiment builder (`qiskit_noise_learning.experiment_builder`)](/docs/api/qiskit-noise-learning/experiment-builder) - * [Gate sets (`qiskit_noise_learning.gate_sets`)](/docs/api/qiskit-noise-learning/gate-sets) - * [Math (`qiskit_noise_learning.math`)](/docs/api/qiskit-noise-learning/math) - * [Models (`qiskit_noise_learning.models`)](/docs/api/qiskit-noise-learning/models) - * [Noise learner (`qiskit_noise_learning.noise_learner`)](/docs/api/qiskit-noise-learning/noise-learner) - * [Sequences (`qiskit_noise_learning.sequences`)](/docs/api/qiskit-noise-learning/sequences) - * [Visualizations (`qiskit_noise_learning.visualizations`)](/docs/api/qiskit-noise-learning/visualizations) - -## Indices and tables - -* [Index](genindex) -* [Module Index](py-modindex) -* [Search Page](search) + + This library is in the 0.x stage of development and under active development. No part of the public interface is yet stable: while the major version is 0, expect breaking changes between releases and pin your dependency accordingly (for example, qiskit-noise-learning==0.1.\*). We do not currently issue deprecation warnings, but all changes are recorded in the changelog. See the \[deprecation policy]\(DEPRECATION.md) for details. All feedback is appreciated. + diff --git a/docs/addons/qiskit-noise-learning/install.mdx b/docs/addons/qiskit-noise-learning/install.mdx new file mode 100644 index 000000000000..6e6a4a913401 --- /dev/null +++ b/docs/addons/qiskit-noise-learning/install.mdx @@ -0,0 +1,21 @@ +--- +title: "Installation" +description: "Installation for the latest version of Qiskit noise learning" +--- + +# Installation + +You can install `qiskit-noise-learning` via pip from the GitHub repository (`main` branch): + +```bash +pip install "git+https://github.com/Qiskit/qiskit-noise-learning@main" +``` + +For visualization support, include the visualization dependencies: + +```bash +pip install "qiskit-noise-learning[vis] @ git+https://github.com/Qiskit/qiskit-noise-learning@main" +``` + +See the [contribution guidelines](https://github.com/Qiskit/qiskit-noise-learning/blob/main/CONTRIBUTING.md) for developer dependencies and editable installations. + diff --git a/docs/addons/qiskit-noise-learning/prf-prf.mdx b/docs/addons/qiskit-noise-learning/prf-prf.mdx index 0b2272c9312f..68be72144511 100644 --- a/docs/addons/qiskit-noise-learning/prf-prf.mdx +++ b/docs/addons/qiskit-noise-learning/prf-prf.mdx @@ -7,9 +7,9 @@ description: "Proof Index for the latest version of Qiskit noise learning" [**prop-mcm-evolution**](#cap-prop-mcm-evolution) -| | | | -| - | ------------------------------------------------------------------------------ | ------------- | -| |   | | -| | **prop-mcm-evolution** | | -| | [`prop-mcm-evolution`](formalism/index#prop-mcm-evolution) *(formalism/index)* | *proposition* | +| | | | +| - | -------------------------------------------------------------------------------- | ------------- | +| |   | | +| | **prop-mcm-evolution** | | +| | [`prop-mcm-evolution`](guides/formalism#prop-mcm-evolution) *(guides/formalism)* | *proposition* | diff --git a/public/docs/api/qiskit-noise-learning/objects.inv b/public/docs/api/qiskit-noise-learning/objects.inv index b485feca048462f5568088f650b9c43d3c36326f..00d276ad5255a67072a4d64e016d4276fdc4f1ef 100644 GIT binary patch delta 6121 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
!W2YP>t7g| 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 bQj4ScylsW#UD7{%5><6fj8*b~oRUu-PuRb} diff --git a/public/docs/images/addons/qiskit-noise-learning/cbfeb7989573772757ac81e9b3a0665f8a0513450d76bfc5ab63e24f40c6b8f6.avif b/public/docs/images/addons/qiskit-noise-learning/cbfeb7989573772757ac81e9b3a0665f8a0513450d76bfc5ab63e24f40c6b8f6.avif new file mode 100644 index 0000000000000000000000000000000000000000..8075ff8a30fcc6c1e50bb42d85466d21930edc69 GIT binary patch literal 105531 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

e%Q8q?N zzZQqyIH=ZJ=&iOJAxs=bAkcJib$8CULKex`vRT59k|A_?H6#tT;|NOdHYxxl_|`JL zHC}FE+jw!ZBYu!a+Ps8Z5Zcvfv4{I%E3{*r=*sXgNt6H$bagDL7o3>RvE?+1E?+{o zq=L^8JB75tPOtLzb-3Rdah$dNd=)H9@t^YKS~8BGw~o2E-M9-Ir`cYi)?6jU2nU#k z|E?%zC~;?gO;9)1loxX_y(uFEapNjy`wjl=&_zv=bQ2!g0iv5ptk=Mjvyeh( z=PPzD!&1$*{Ch<6m=@4zJ-HX}4EbX(<$9VgGc+_DsoV7U|2lLzDrE69e8wV$1@&WII1J(&Hj~cA9|B+oT`ZC)vGT+HVBCFBF1jUms~2m-;4 z2BcH+6GT=iQgr65n~?1JWf(SvwjRarew^%6nh#^wOs8`Ll*-WeBqAIhL_?ZIyNm@p z;3VO5UE_OQs59&c4t7P>2>MW_a444Pn}BOmXxnYl%jIAudNPE-O~z+p68Z+a17GGjU+egf}o~ zXztr`r6RJ8VY`idqGMzHtguqY}aO&o;o;*rvG8Rb=b5f%a%7d*X?_UG!* z$}EgBv(yZ|sf#=kRwX2k+vcOs_LK*hs;NL+(~4<1{UO)(-yJ&Fu@Txh>9Y8)kC;!` zuJM(+qSg}ZWb~yi9?QG_h23p^ohy2FV|H|VPSlSpZyeewG(Q;3&OVQ2OP=csRy1QW zw4V!wo{4?`S`-()Df$1u;4s$7+*q!iv} zNa_KnM~*O>)zvpA6-w75we%g+=#x)7;93+2dPF;Uip|9jFuU7_Sv`keFZIpmBB}qf zs7LHU=a%7>z0?aGfh`>?HvMzswvkas8fHFJ%$VI$LGstq;OfVU)B`ZyUy-1i54*|H zG0#;Iq>Uq1R4+8-!XH&1f)ede({x3HH>MD^xWFv8=c`W%oJ^(+ByV#hs`OO{bfRy? z_}qX|DVGQA%}k$V5Y~%y*CT6r;zKnDxQL~LDkt2ubsC+aual*Z{xQ9t4N!M8sOJM) zA*MW-ap5ftHyx;C0&8Ti)y0;}lQI*=X=hq&* zs+BLM+>bUxG(KXJ9TbeXyfcR`~#ZJ&5e(uW#!Gg=ioJFo<2`NWbx@sEE{y|o7-JqP@!m4zMv ztDOVdn(cd$(-u`u#*)J6Q_BWSuj^0z(%cw8@NS^YKJP}IJl9qDE!?w+sd8pFy%xUY z#A_Dl*&`nJU+8H5)yxp21_4n|X{Q$lm44(?kqI9MuAMi@QZ{iBfMVhKjqR3x)rN8W6N}Vh zGD_8Z01KG%hiWu0ub9=8zUsd@Q zxl=iQJ`YwvZ?#69G-^r$}U2&;U4rJ2m^}dB`-L)#ZGf5(x+U>jHgq6Ci}9hjih_yO|s2pa4y$ zm>F&es00LKm7zNwUy{^tVZwWAtF>CFZj=A0ml3?_Aq406MA{Eh(;pQ_GEuKJ)^mrx z1h6zp_Wx_H9H~ang()qfwnr-?ThvNy(wN|y)TI&qmFDu41NJj;fI``dbU_o$mUVZD zYTI3hkDshqYJYI~4=z@%qMkjOOf*=<3n;e%iSm2&S13O0=jHK7EMdRU;o5J(x+RPa*a5q;QuaN>y0Y{;UruMSpn8Gah6qP zE8n@%;@c!8>aZmhh%fEpiaNf!pOoB$a`zSgQNkP}z7`8~GWDYJY8lFx5G_h6U-sKZ z(^fHjSdEXI9qgJ4^gR!TlmS@FxX6s>-+++OOvw=AnBZ) zP!Np-C#BVN5(d3TB|`31&57z(`(1*1F+Ew#DPvz8Fo@5k{kxwnlHG91*~|FVas4I{ z_N0Q7u1duJoP_@H!kom62jAQ`ZxVsEk(eVq zK%|Cxf_A+^(PW9p;#Cz_nJGaA9?zknM#!Bizr@rCy5>lE8Up2cvohc4=OW| zVe#7g?6;}XNb)Vw&hUJltb80G2KfsQ`u)Y9^PqUzC^%dMjhtj9irczhoJ=`DYsf(E zegXb)R@poiqCiKnl8`b5-!mj(IC(`&095lSzuY9(6(knYj)6rwQpv@oeEc`px%2Q$ zQ3#6Tr2j=_CXQRs<&{G+DEY8 z=;hTIawy2;2q$N(rhf9--GQCAn>{GAQ9{`zNC1LHE|0oC#y6VInfaCU?}%nRnPuS^ zYgM--^%$IbZKff!6p{?Ry1CIVLdTGlvF#t~qS>ocX4mMWtRYJ=jY*^q4mO>4)wTlg zxj3IWi*HLOu>^iyNu*{Tqs*`Tt=(lf*kf^1Q;iV2(M6w_;$|J+I_BT>O!BRFNOJMp zS6J8~8O0xRw%=^>A}0C&?W>QT4m2W_T1So%u@U`L0#o2JF-$3xILeZVi(lLP5(fjw ziqLv4Y19KEDnNQTW1IE&**$SOuQbp*ZKSQo5Xe%NrJm^QacoW%fe#GX)Z#Vs={y!* zE4z>{FFC~y{uW8>J?4){G~0liUF<7)&g-|i$RB9E=YW-+61rV5MWWV}8h-H%VuT8B z#^GTgS`Iny3Dr@u4!frf!3Of2Y+~JSf9H%aOt=aZ${ zpnO8RrXC4qrg@Fh^V@CnsFNS*B@HQUOY;rX;cJZ8^L@UCBnq_>*QCaA44=E-{xa+q zb7VfI9tHSl1-|-xn40ugxkr5l5t9o)VKUehuL%<*1wp;aU*lykAMe|}V0pmP%PL^x zt8%>}wS%o0p#$PvWQnaU+H46X_+=K~2G+_br&hlL1n_MJJ?%L_~c zim3rjU1r?Jz2`o%R)|WOr6?&X$9+qSSzho-lsS0TJ2y*xGfDJTj|n#mK4Zng^`DrW zO}eNskJPXAoV$kj%Z!RJ#al@fwR}gK8g#XC*EpXHj?ZgjEO~G)cX6|L#(-^;aSR1)@ zMWaQ$xac*1sL*3sZ7D-!oW#sTpJ*cz+Hqe?L;y(1-KW(i#)r~8)_mIDtZV6gggx)j zZGjQzw{Ff&Fa7k0`1zz*kY1d{7>eFpcnj7eB&Lv{-;%(i6ZBP(Ml#{cUQQM<9$2cmBHazyPc(g(+A*0sR1m1OW&n9Y*zAA3X67!jcm|MQB zwCO9vB{Q750gKf1ghP5#fE_o&J~w91h11Tup!`Tp3HD?I*isHzz@ZHaGa~NohYR}r zRI0CC?6Dte3b!r7zzj=tK!lnK+G=vM{=GIhsQhcKohb)mtw|erWHXUET`0aCdidB- z(7Zw)qfEb~_uA>jN>|OpS_MXW&wTBP)kmK#knW#>dN^b1T^s;3rCfPe8S zUvS`=u?N%UYyc)gJ)7io2IDCfa_%&x53E#P*4MIz?2=7MCw=__d)hk3%Xp(AGu0Q( z_AH4(;#bP(;o0}flyrT+vi1^k)~Sd~psUYIMrqNP6HXw>te@rZt zrx8SNSdbm`OG}P*u!i+!Aivzhqc#avH$h89_^pUcZDr>J$I2)+HxQ$9+8oAiluIY= zs5)g~T}{qvZ%t;7n!2cIQt3yBh{vMHOt>cfH~qvY7CCP?bpwoxg28-Tfe}d1gM35E zTgqxMRN#p+SEah*LeeI{`hF4VJ*8=Q()0!Jo+-Fk-vwQ%Uv-M!#E2 z9KAsLJSa(>eaWY?Ys=xP+9mXFSXp&5E=pJ_GdF!2JUQdd>rsSCS?#Zj(`YIo?T)Z~ z^i;+^&tlm^d@3Ss1C81Dx(3@ZROV9}0x(6iHy7KB zMyP&q6h-#mX=@?O0WmmbjDM8L%(PeI;)X%!8)|Wm_3P?=Ju8bDS#&okgg(}WvRen> zYquI<8~;Hv)Htq&7`v8j5l{>#^APv52vYXlToOina&{H+G!QOUDh3Ati>}r{41Uou zj(S5#;-?VmwWN^zS0iiFGGAK+9VACm zO|a1PzGyYToygS#sMB5XPge1Y9+iTVX+*qh)-OK`GR6y&SIbwh2SR(s66J_WVr4@8 zZqbX10=`qHTF{bu{-HI2=0K=IN0lt8Pc6n{zhZ&=uIm^Ka{|E8k4-BG0%5>F?RE{K{VhF?Ummw${`BEdVuX)d_qwM z%do{|12h-oUp?$CkrEIQLbXo8>Z1C5G!DOzq&4vZ@< z9IW*&%c?F^kmH6|`DFY>f?7x2ZU&Eitv>L<92w%t+)QfR*h{14iMTz{g@Z^rIqNty zpKcJ*&W7??%!#JgxW1cD1vB^9I#eb0bQWYpLFE#XsWsbzZc$&Mee;%dkSPo9$$xVm z*gWlAEN1W?N)MCbbJfarf53N9=$hL`fdly;?q~AJ%MgTPaMtcJ%6*I?Q@M*~yGQY4 zbHEy=p(~;14z6v?3oU}yYkneYy3gRmVTv??O+XWZm4gtksXIxYBz=ps=R$}&H6Cz{ z?%reC_wZi&2K|=?v`P~LK5uCOLPqyp6Y7$t^NX1dC7tPe%v`b+8S^5*(mzr= zK&1qr22aRhnQ~*6h>ugKR*LWRLVl6C*0{p<*kNV7n7}Gg{TJmkng%n0$GsqgPZR+C zY3JQ^LAZ-4hTdc=0q=|3kqMZTGxGTw`My_&A+~UR!1*KfkQ*#AY6_6q`_15zM|10A z>PCy;6Dwv@_R9($hM^F5tQ-A@LQ~vX@AcEQMZ$2_J28wwLYKn57RPoH_AM@yj?KiF z7l`J<{(K=ztE;a0nDS5DLR6Y6JTaP>HprtKR(lMXp3ZaQ>9?qD%pd=6P?2yPLb2 zqx}s=I7X=?5C&?p_%1xqu$9z>g!Uu>w0J;2T+3J ztMbBhfLbpCov_2A87T*G3Uq(!bmUge54h<;FI6wUV*)}&u~K|(IP4x#R9)k~E4`#O zg6I@1r~}Y5xN%ynYhN3 zb&lF4Gt8Ti;dBtrZ7};mS~V|KC4)v0fHBt3f*+b=ofNN3{M~p}yTpO*Uwwfh7#sJ3 zbGEIA0onsxR`#C_7>Y7YT4P7#xQ(D!7ROtgY)Vtu?8a;!~@RVxpD{@aEJP|k-^g2 zxyHru9u7e$J^OW3X_jt3xn&gFhtnF9mX03HpQ;Wy1X2`DnF(dVy|&H+Y61R#{xDJst_Q5!N! zwK51Ls=PRJ)`!Ktft1!(R#R?%o_fvvqmYVNbmHMflq5ObS7#pZdim)Sy4#g<5i7cG zj!7XpkSg?|?9bF(`gLRauZdc!cN;o@s+#ZFNac^TAm5*C2nw)iCj=>hadc$3>x}Pb z6r>M;@Z|Q*9BK_fN`_b%0Wj)rNJXa_%htep4|`K0O1 zexxbfZjuO{E}dM2*s}cPqiR;(aLt%pn!*vO9zc9=Mz5K#AHu2Z`fqEj=yxUjP(`qj z|873QXG_6tkDV+@0N&C%mC&uDBxguLxA0buH7Er6c?917-wgwvCPPLSju=_uSkJ5s z1<6ZREqN7A$u;rbwWTA7>P>WM{T#0*RwTzvQ>>t5({Qx8@bA8ikl}Kh%d;~fCzNWL zsu*Z~0kzF|h0BWd7)>g%#>RmAQ?vj<|bu+B7eNpmcse_|52NE@a|U0}vpQMD@fmY@Z=^HfhV_ z9Eu70a(pjj9Bj%epXxXM{1)%v#lUHcPI<8a*k$oL^bVPd!vn(wUTp^m=}M#MNh{C(cQ?vcHy51$hvz*A|r(?rPIM;3**-qwYs#9?H4i%}z+yvjWS%Y{A!1Nhc!TX{@X^r{mijGm0^ zuayk_#{+F`=a*AeKfC{naB&2o0NF@?uG|4@_sL<&6$CX#aZRWjLvDY_7rk7{0}*&W zKEmsAd8PnkrZg5q39kDp=C}xIT%=brA>MT@5kIk>@!qE35T&6ElD8Gc4iH69ywIi! zpZ>*Z zafw8d*^^HklP2r#>`vYiI4+dP*;*FqN5jm5e4}=2#AnLQ176~+L^jIUL>^@RLU~St zbmdqTfSH*Lg#@X63K6;S^h5F>tY*Z|bqug@@J6(F;5@!n0@i~Blnn%0` z11k1tbx9d6%9t$VKYq3#YvK|>Art8nvkbFT-S&MvM-1b9J~@$Pggi+FAo3>cWMH{} z+J5Oj^6|GEo^64)-zw5z;^K+i%FZm0rM;6#@@Sov=N73Yq&W-RdczR)+|Ig}*+P6) z`;&XP45+ON7Ch*GMO3%GZ#8i(U2KcI-%XvdU)ec<=aUwUa^>psC}Ixj4onKYxHTuB z#Ke0QFKZe$m4$?jR>IE%T>%Y}bO(FWH@seOoq$M`f}Y_FRAhQxpG#1s%Cpy@%N5vA zIbBZMsn}*nqIstB-_;tB4dOTCfu;WuN^-4gW%%CCdxtl`orL7(#y|H`I> z4oO?>N*zQEG4Y6a#a8Wn>3u5Dh){DOC~c2Z9P7)>g%xNU*^PTHfl?2xm4$7l37{wX zTXF=~AtZKSK#Wwf#6jUt4v+51ilEKU{HASLyZw)-1EjHnw%Nu?5^Cx*PW`Z9VfZ*9 zL;oNt31&-8MZF3#>s#xo;;LgcD6xp`5qFDS?hfbEPm-We&qG03e+ z8(zwAg70ewFeL_1k1N)=y8G3z1M z3QgTJBa;&OGlqZL$@S{()x8?s&zE?e(f-aB@&#$$RF+ii@T+N3`5rsA0V$Z%b4Uh_ zPILDxaj6cjP^K|Zo$_tk&|t)BS&|5V%6!2u=qbQ0Ff-fl)7Fx+W^C<^lsH zj)q%%E!$9fKz&8T%P_QgzaspRbzN5kICGwzJDIgfF#)Fdl! ziYdrHH@jAYPsOvAMwCA7G^X*-IUseBCp`V-=&P1@@ySKAz$&r7%c-dq< z`1r96$~m~Q?7QZe+;lLyrTYYLUeAbm+(F5;Rifkux*B_d&T_-}MOb(=HZnNS_p{Hb z?Af1E#C9*}7tP1KAX4s{r_l1o&t`NN-LmnUiu%osMj!l2RuDL^=0IYSQ3_81GqgV> zP5tj%qF})xIL|)ZEh`Lj5x<>NUjhWGbj063C+k$M_U?m!%itcTIRUHDez$Poj*^@R zc;mY;H#wdrvf|$uo{0*-=O#??)hw(zUmrr#;F~jkrjRe`z83P>ED-Z#`Zk^^+7PnW zqJbqQ85m>yjd+Y!D3o% zB1w*BEJ&48574!pm9d@?d-*Bhmt28(D7VwJ`o=!{aYl7N;eD5&ZiBdiosm&7`XcT; zG&PmpT1`U%NtR&2LU;Yz*eWdE^~9>Vl?xUMUPc-y60)eaae_|JZGz3zP2+}F;7bRQ zQ{-hR$^UAGX7fsqYb6@0<{3m`%zPa0_v&|GEnTO5#JRz!ekPmVGhn^>Rq=+E?vh%| zNT4Z;IgkQ^kH`(eZ)_Ur#>YqZgiA2F6WKWH$>s86*iouFJ^%pIq`MJ;f(g->d1f@t z`ZU*Wodt`xm$?(Kx+cfo+_A!jz6pfAa43A=CNcOgW`3yh-3DH18~|Xgt4^6astNMB z$>}GZa%V&>wp8vvMH%>hzF)pgZ>?Eyk)@x)QzmUytE+?D8Z z8ayGYrzRM-XbjIgZVAl9#-RK+q#z0og`33ia(P~75Hm8h$LqaHjFiY?o`)&lnnqiIPG8H0a z&E&+|F+aplhHM3&*Bp}I6&$aoIH3*O-gd7p2aD0Fic`zpNWvmGsxIry4Mbl3yuMW{ zA40JHVa;l3W>~OH3Ol`#JJj)cQuGD1+Jzo*n+`l8T{CS3B_9k_67!1;&S;L(foo?v z5qzTj`8kYoUa*D!1$HhAVTSz3M6`T_%9p}48~QvAF(94n?R{+!+7qRlAZ#i@`>t$e zA7Qd6sPH|)%Y>z`JH4J|*ndTNFQE{*8JX%dhO}meKg@$wmGvY(n~p_hECLW@hW%&H zcY<2#jGc$R^2tFxLqFWvqkT|l>BYeo(3`bIHVJw!^|V!QOoq&1MX~5GY3P_ot9b#)z#5gX8lVf)&Whb~W|03UiLP6G1XZf1rzLb{p?Ct2j_k#{DI zfB`PAbLo z1z$E*L0~kE?zLuMH6)Z*_pADa2$pT@bcv5UY;*oqpE(Wj+rH1V#V%?D%(t)Y-&_Jt z37WCH5fDJll1lw>(i9WTN&qLQ%1M^vo6K|{wLr4nTU9Y77xzb=+l;S7D!k_ad(mQY z55-lT=ozWxTocQH;B#odZb07f86t`{M|%i^aNq;NCEx<%Z44gnSM;l;gYBKu#~z)y zD_dEOLmP<&ye3)pxpvIFVrlAeaFYismKT#bTJl;;=(+i;C_T``yq+5;i}dlGh2*U8 zE_*NO#;D-#@-R1tz;j8?Zm@4$@kAyvjCLG#hY5Nf5P|hEqsH%wTn1U*-$aqzf-T9) zX8!W=9ZV7cEU8*;1@~!3e$>akdT}0HO&T;n=Q&z}!8qY`sBOdv1JZHUsBHx(K<|*! z#bC`et}{9WYO;l^j$v-QZ>Xj@>Y5MafHFJT71iVjV3%yGGO^cpcD{ zAp(_O)Ma|E62*(1@R7&?t*xQFFiZ#&Kt;30{%I9R;q&jN){B}o2lHy3*?KWuxDS0& zL0^3u^D`__oL?WD!*O04!-Q$F(nnWq|3hGtKe`n#IpkRzi5($4*4pg~_F95MgJe{u zBM+TH6wR~RY!f&RHPDNOiN4yz%6%(OWW81fR9dHnJ-d$v7Q z7XEEv4GG9$^0D7Y*(!q48P%aXds~TN$WDR~`cp(_e!P>5-yp0w7WzjL>Kb$(OTdlG z*9MC3+2)~bf*oj>3tJYY3IxrZiA=J_F7F2u3dAeoS8cfv4_mW0TSOvsXCpeOD0TYD z15hW`rQE7(u5szN*_lLTAMgoSJ`eVkwC1xvhp_u>S-JtV!LP$3=sc?Q*v<2{G2(DI z%ZjVs!du*!XQV}TIpFIp#n&mH1ph=)Y2^t*L+4EwKupk}Nx3%&yD7`s<1}}**LT1v z>)BeR#EEuMXVWBu>Ov`j2}pudYof=!9F>rNBV%^|>rL33>}0)_{TaX0;5`;EPstP_ z5_MF>TiFZhq9a7nrUtD7Yv@$E_Mc8#_M4}Yue?15oZOEupEo0JOt-yV1_}(;)1}w%_|`EgPBT|Yms|>p%4zP zd{K8GHU{Q?>*B;V*%k7`3fEgaYx}rZT~L+iunVTn(*v>GC(!@l`!#U*$vS&_Bt-*< zWmYJ$IKukk=4)(hrW!Z=VE&r`Yn*E!+5aL{Ga?TqgCmNs$-5pHvL33h54Z=AlqkM2 z<`-BrWfwy2lf^Z|hT-(5{+Tz4)Cfxa-6=QIwRvUXI=l&dJCivPV*ZSZHmorGk0dmB zFF%q++h;v^+kF^Nu8u0-lt;DKTVS_9Bxj|QBWd87U_V&$0MSMt>-qL$&BDsAp3JHB zyt*D9rwgGdshMkNs=E)VV%|b-S**!G@0cI{p2Mbeq)?>%P}-dkK!l+#K% z6dsT9ds&xmXg&L?U2%))ZkAw!nw9tE(H3MmO&e7Dd;%xjcfz52uHSO!=E(nv{P+7K zP7zd_6tEnKU4@7DG-m(gnEL>+5!DDs-_YIHPs(+kjDXmbZB$Ci%tX~{U7j2v6=C+2 zG#g9tNeXBjyuM}a(ebw&dP`a&e7kCt2Q@GFnk1SCY#Jt^&vIWEsf&g{MLs~3uln&$ zI(cMS8%=t3JfjpCK^;oUy%|pm1zol5E&VR}D@M)z9>!(1M<+4N`(SQe0``}~5^<@rcM0b{q-fY+b7IG;DUzDybQH~Y_{P1M^eO z<|-2aXTFn7fFyRhJS7lN7jrxd`cL=Y0higyGOR zQRT)?f!mdOgf^ygvF)z7dtfuX;WWlJV{)4c2vuDn2d85f+N*aEXZDcUm4dGr44$CE zyf7c3u-DjEdz}MAdLr2JnpHjN_XC*nIC1GV)uBl#V7dLL= zgH$9FoCT`@J1|*&R5PHg5&;#OshLQ4VM-BwWCH^0bI(-~0s%teNW0zIy8mn=9QluE zM%MU(0}40@^J+Z{S}&6wjN(raVXwE2Gp8GUO3n;Ia(TNQ;9@(o-Pw`b=EtZ1lc?ZV z6BS+y9ca(+LjNI$hGQr*Vg*8HzeBfNT>Nf?PxO&G8skvXkH1G)89L8D3)iYV2>TV| z&S0BX`(}ABn87O^)~4S2Y3Q-=B$a#50cU*`Z&0Z93OLp5F)?4%S11fwxhPw4L>Q~y ze4AGm(8n3c;|bEN#{|LEreywg8e?*tK|2=dSkf=gEc!DESYrpI5va`~+Ltu*@p_u1ZcDz9BhtTDYlp0B}X+ zm%`HmZRt|?_`v`%$Df|8-|0d`lk|;dh$>|0vx~h=^A*k;K)%V3=Y0P!@_f@02vhfd zmGP%)kA^^MamDxk9ot339I^}s};QX8r5{4kVF1wE`S^# z(Q?>vBF<%HZ2DIp-1Vu$(;e*(H>xsmDDq=s8k#+Yqx>SseK+NKi8=H?A7!cuZo~#XIr$oOCn>mv8nP_+Lts7jWn8hH(ExaI!rixOmkKKKXANcAulcoj9$nHam z2SW-MRdm>pECP^x^LN~SHr#V~K@styu2xarygPC;Xh>0gwdL>WDj8d%nU7OgBDMt; zu?)Spc-3*0@<&i%n|<~E2|h5BX%3=9?MJ|E!niD!`ctmZ2m`~s-UxV%Lm$zU&&h$i zKIDB#@)mct<7(j=>VSRa_2g*atCWfBGmg6i+RC3V2v%C(5}Pzicj&w^7^AD>&oEAO zoIf%GM{L3XDM3zbL)Y;sKNTat-LY{L2rUgzViL^+>~{mnqeUq>p~fSV>ta}2d`g_C zngmGJ1bKC)es6JO;)yW1H++uSl8(PJo`G&H8!j!$j?c1B?v*7aABSu5YCJ=fHkR=VqZ&rB5^z#up`#7cVKDJ)~ET-55O31wEF?0*&yj2EjN(vNplT!G^jkJhv96a^p>vuc*np0ajNHO zW?^W={9^{UXsUC1dR;-GsE^nNIuUnagU$G?4q0}Vp}gkX>WR)yh>mTmiwT9IgIcqO4RI}L-fHeygVT_GeZWVJ@N-26BTd)>g$(;eSert?mB)W%urjZ*-ZIT?A z*oaO{%z^}GB#oPKxsOqZ0<=~S7~L&yU5ii^hd*~i;Y?qj6J1hc@g?t3&hGbMu{Cz! zLP!uZglJQhVjU1ugulsu5nZpR(OAWGpZX_Q?H&FL37Q`~nNi*f;7u%^_OQ%j-1pqb zMqPZw6C=#?zZv%oqZgf`&mwd+VC@;|3k)iq>7i|8MuGxNa=bL8y+^y@LVybO=TE;W zU*qNsz;ced8DCb~{S&4;p4kSn@I^>yd9@sB^+?jjtga`xWxoCIMhnb8fT7RyclNa}7D?tc&b4jl^4%0ap_v4;3O)DhOk+Ga56 z&)H$Gyy}4i)@lIwS+pu?Z9p_wH1qNp^HiEfKY=ZUleCGfbS+1`bzZJnywGd4X(uW2fQVx)K^58}Dq~>+{w^|>COY&y(J+(N{|3i8 zs1D_)Xl2a)m5m;TQ4vk!V^zYkVY)BWVnho2ZZtM6zHvRFy-- zfguzb*Z?PFrnwf*q4A+o1#vPfgD@qUwju{!8N`4*IOB^N46jj%7e@VxZ)*L4c_o$~T< z<$T|XUuB68Iy9wvvCc+gO+#gbM(izW+%&>5dw)yeEg&q7#B`vu{R$~yzP};D zH*==?X+p~IcNXw8$(T8aKC_)D<&9P(rSlCxlV%d z?#|}UnCr=w#$di53qZRZv$xmBIE{xPZ#ueg2CA1rQR@wMgzq@Dz~k@q#Zl=zh%GgM z(foBFZMfar>4-Wd4Q0gDJYE;lu1kZkLY4gVV@Rq|+t}yL1pT*&SM|LTc>%IDRl0uT zdxsk~^(4&M4rhxj3`T|ZJL9X{C{-ncz7!=i;n7DiH5rLGC65C<1Y57Zh>xr?HjXZU*kWj!%0^A<=}`)3XD7xL0<0>w`_o%#KMFGZ}4q>97YNSF*rbH5J<{gdQkHoO+6>h^JRynrb? zoX7Ik67ej>m0IETZ7R$mWE|sL36tLt1+{!jdFrYvgvHa&y%P@P@Z@7&IleuR)(2sH zNrJq%pz$bncCeQ@+wMl0etPdbGNoB7 z@`Lm29uE5Ww+N?&jJ|zyJ!<~C>;Hylc;NH~1dJR2U8bjf^h+#&cKBq)Y6J}kH3>nd z`FzwzvKyjwx5}P2#tO$ch#3UoY1HL5tOW*_DWj4thkr!D8?I0NcX5}0Ibh}Zd=tmb zIg4e33Y;b$VvlnZWf2ShJHw>2w75aj)}X}g5Ft9)x` zbd&3xw~5w@vQns?VmbAW_}DXFiQo?fzEM{|avcGv=oI9`idrKmN>K_M5U}!AR{{jd zhA79i%TxF$dAYhIke`M{d8Wj8Ii2F&6|rce($c7ko9xaAvh|ohNwlv`Ri+;MkY|ow zPZ>g-xGFH?d~gg7?1EFK7kW15ya^UwtYC1x3YmkGJ3M&59B-NaY)>@7GhAEun~v@%q8@gh!yh<04_uy4D<;$@LUe_8>OIZBoe?$ zp=aAdXn{Cr+N4F_v5BcE8CprTXlmKf&GMaFxKZ*Gt?*ZIx@#J@fGWSX#opx1wO8Gs zCaTD;=Q|NMBa-rg%Il~oPh>iiKQh?$53*Bxa;FzS8cXW~>HB;8r~`B$@;&???jB^6 zM!bwoB9UtlGXQWv3Fc=YQZOEaj$@A-h|C7W!&54%)AZaMMM`zh2RkUT>Rn+G z&AUlb84~1=N<47${WAVc>@o^7sr+PMrVr7IHMshmTHOXKeo4^(1wrg=JP&J_=`g>* zW6ST>*shcAGoD;$^Tb>=O;UJ2?!0wuXlC1iekJH1K zWlaObWDor_~>dZ}5KI{LHw%EHe$;Z;G>f3zAg zDN*G3iG6O_z9)H6kDf37p5TFOGM}ekkpc#Dj$k^~NK{Gw80H?64UIr; zst}{!FImAtSaK=s6u|IHOizx_Eg1`f5}lr>#XZ`*ny_bZ585PjSo^A%?_px+U-eJE z4C4-OxJQPE#=2(A@I}eg?N-`I$T4&C}n|@1WdA5AEx`|I0UgP zC+R11X2AH&?LPReA^L3d*DiFf{LLJR0o|nW61m6f-pLEczD^+pcV5AM4{*)zApd$U z>7Mj|H^XeOSxOz~AEk)jh9aI@g-X4%kBi~yF1mZXIm3X{0_iU8048u=$FIe`cW3m> z${*phul3@>xty9f8iBC0elQJb|FyZ#@c3U)9OQ{JG?&`5@1joaSsdZ#6o?E`ygLvI zkiCao-!v(xeiLk5N_G1Yk*4?%W3r>(i_38a#ocYVJKsZ_q^ZVxn;ee!dIj8gb6X^T zpL1Hz4o-sG&AJx^v8$~>0%*_w4E`y|j8d)g^YgRzWHx0lS>Y1=r8>b)GL*>>ZHM)D z_vOUZaP~s08Nj#!qVp{|!*FX-Bh+$@0bk#0+c>BE{>?PmONbZb z{ylYfRnlLxT8}8T91r*%AcCNECYiYvl3fWUuBTG1_Lxer>Zo5^4p;nOVF{aMei>`3 zQG1nl38OAycGFp>=BTX!fa|}$o)26!gu++*O#6w^k8-NHuw-JsQs66`cn^^J1~&CG znd$;R3|7>WV4Xy-8*bkhniTw)w$7pFdH}QG=?q83VoI@Y=PR>1-yTvF)@5X99Yb# zIRra$0am@8OyRu0g|8^>?C<~0je&MeI&gP51aGoYQ56^4?lG9Ir4=Iv2ZuaW`#Yq5 zubAU@hIy#yNR6eVdvrvHb9oq~k)Uh!$wwLzvO|RwJGbCL6^n*?MT;-sNL2kt3j+y0 zaYT5At*j{#*ivmHoiTo51%N(7LdmXcUbvqiXjT&OA5C9c+h1?x!@T+hk6lhE=d_J1 ze-T@z;&wZgU4z{t4Ux#(#ADP#@V4w?HmSinv)K|}9bbc4wy`D@2?j44QjEl-!mIoD ztnAME%xk&k-@-*b)q9Dz>}z>RHg5I4xWC8>j=*a$q~s{f%#IV&0MAxdK)Ha8)_pRl z{wz6lM*3qJkqUsSs z(*{N`)-v86OTojp$x6DAv0Lp@8$q~0aO)*$rr6bJfUa278OyASD+yRT`y;a@JkH~J zWXS&2Y$}5p@=%YmTuCBtfLKuDeelcdmiLB)xx6H4pbBMaA4WBHx-Z)+D9FlCLO%b` zwXiL%t#ITl{lx?TZ#*+ce+Vi*0CdiaI}IjoWN{+NlIAg0{}Nlw29R|kWwGnV$Vo9l zFs;C!xMwRoFncsPxkp30(aS0`Xgm9LghJ$3puIzCoVS0<-?d5dtRy<=xnB+4u(V9^ z{DYhhTXsfA^z!!Z>YW zvPPCE9wNlGfb)XE95GO3EP;K^>uFqXHs92T_|RJbu(ftK-33~Q;)oM#RIt1g<(no!SPmpnKp zO2MM3%rJrPO-a(!*3&#cx#?`s6nSUqNG(KLULPk2Uhi<;*Xr9Pzb83tJ)6I1wQdEU?JyUV+L|!jJiR@qi=s0B_-+Netu_!t@{K> zVQy;)qP2laNbEkua5Zp{eLXFSf2tern4G+V+aW$}+3=V!z}tVFG_9xlFeJV%0Fd$1%J zY|A6qGaXee_d+BWlLX#t{;M^@aZ@j!iH$Vz5N@~pfy4|K?N*&h65B^t9Vcg0@#qi2 zeFbbGL9_C{u2%R}?uUbLoS{bsf}_dSwpY2okjisWuSLUHWu4fKF>0kC#fR6T(yuZ0 zG7{WYL+tvt1*gIJW=-9_>SscpIdLvNI_)OagDUPL!!i3i0$sWu(r}OZk{>Ench9l` z)JV`A1vKt<{R9e_U7+Jx&f@fz?a!XMaqK_u&=Ad_l+Tb8o5T(B`(ZdQQDS|yxNe3S z5T4Uif`4IeH`^|5LlYQbEv;hW5BNIG^x&8y2oMQWN`ccALgzbey60NCM3K;h3{H zngh9~M2xcKP+U~KmB5_Cr)FZ@#4;hI(VpwKJ?NnpL(3?o*Mw&Z2zfiavX4;`;t4+* z?m$+1TGDW!WyLD-7H)bT@49i)e`Ro+aXOLG>UYR~p9D@n$+ZAjO#@n47qX|L&ettz zFyEdU_~=yfb5_zn{o))YpprTLNE4U>GAsk3Qs~byixEy3t5Z^O464iv$NBDDuHY1j zS>mxF5syP7^`MC_9vMnoi%wNNj8fdZb9}+X#Kk9Hj<4JC!U4bR-8KsR=4R``o|*|s zgkyWzzmO+1+#Kf*1eQD=xe$mJI^BpGB+z!M{H!pp7I?h4Q_yjKq(;un6XjKx0I|I3 z{8=6%9dYpu^jz`3V;Sd!SwcquOq1?pE!3$lf_T{7_>`!m(H@U7(<|UVU?)6NU7T4O zT;cH{uKx>E(xWyO$S!x@>C2bc5`t@iuQgB{f&+v~Y53*TU`9<-ePTU!ry#apsQ-XNFl415pu}l9o>3 zOuOAG>g~d>1pV+kJ#95B9}SL|<8X~dgC!^yQY`DO4VWTqm->ib0Uyy2Egi4%}q2_5XS`WK!JZVRK?=)Uc4_s z{S#)V9iSHkK>T3OndEOzD0UP6 zd?(6g(Hy;&#w@Cb)}#bLL>$7@O}}Geg9)0Ey9ca5*t9COG25cdbA|YL{^O?zIL6lv z@2y+)u+B z9XhRs$X$<(gSEyPF9E5zCFHxLUFhR-Dx_MECW*QU>32zRfB2d>A~V+h7T8%r>F1uN zgaN?CEoXyACzB=p&)|W)+VAN;vB6^DXrN1hv5xG~b`JG9|CNl z!*XT3708_srWrBBfXtKZw6UvJYo=}Kg{ZeAgC|MeWY!fPITa_&hzBF zIc2VaWl+~_HCOq;7Cniv$WmBzR|ViU2qu`b4W|qJ9oP9r->&{#cT_o~M~ZL2IGg&% zKlmjLu`q13E8OSt;DF0<^?h*FC;0HYRB`&AM?8SLb`C zWpC5G+P>{*>O3PwWY?$xHJ2kw$OiJGNefmn=Lu5e76_p=q-fo0=+$D@Ev{9z+aI@8 zmEKQqfL0986ORu;z!cCi8Sr!Hn#%}3?io5c<=-|mQg9%3(^T_ zQU20Z2BeG%1rj>^@l!HSu!mglt7-KTDbVntwwMBSgGz8T9>C%BH! z*jWjddeETiACe7P7=Hf>X3r-Qquo0;^vmWuD{qYN8oO6ZgGcP2>nK|qi2?<3M z-)8&&tHzbZa61(2$$GC=0|wL}UAMITZYJ4D+wRfT2u>3zPaJgI2vr?=$VZ$jcoTc&CSn zPi|JTrK%fk+Lo2QE1&kd^R?jbXfx#CNa>9oc z{@ixx^UFdsP{O-}vy_Vh>IvqDDm7~9uJ3af++(9ip(bz=Oy!GlWHYpFEYwHdZ83&t z&>JG7;}m3EkHW%JM%w_e17r%u%U7hcmL@`}04R8F4|l(j+Juu5ZDNY*o6N&JT?2F1 z&p?l_7^C+)YA33{fgc$q&V(C9ocPOYd3I7~wrGHqIkWtq@WUkQce<7+b-IU!;s9KG zrngRCHaQSNrp1G3wSqzTRy$UvpSSNmUHZfVSABpQ`%ot|TiK`pT>4??RRzV9#cN+! zc>8m&$qCG3NchwyCt7t-L*Ua_q)2&z@vCBBDnB({*p7oEL2EUxzNF9jp}7-@`(B~U zlkO`@mEeui0<;<(G!2=v&n4ww*Fs;Qxd9O{Q+6sEJAjHZpWm)Hy}-EltS4Cj zI%XEU(^e9MHZ3gk@Ck%FG+6_NS9|0NT3|dv93&Jj+EB?8hhbU0%XS>%Q9}Oegrh!x z(yZWOd$M~A>9(%B*76yx=R$IHntXOhB!b#2D|u~9{EOu|#i~Avy+RlxLJ?T2B6Dqq zEDVUAh<)Xcz106?IEa$CSi%%@E(h0NbfRdDa;B}G&|@?&4}X^hV+_2DCQ~~aS?3yG>o=>@GT{$mcfUL zd3E+xNvwcvO5*u%t=6(N^j>BYjXokkLh4v&VJmmXAY3|PjJ|mZmkSU`(F;a*j_ z@Xh9=m!09$u1ox^-3kLo2@6hTq8SB*Ja?_TZoj)OH-(oB!OrZcE+%OK(emf8vnvK+?f9@+l$fZAA58C=0B(A;1~7Lq!QM61^%eW4bld- zhSuNz=a;mX`5m=(mi*$(rE`I)E$bq`iGowi2T2VsUQQr5vmLxBrCLTL=%y%Q}911~Xz*YZF} zaP~I$aCTGnVvo^ZU0cM>`@hzQ|S0iTttGji7~qS>1IZwxlo4V5xz z-ieA=MR0bxpzI{mSOeGKm6*{t#Klc=xf8{BFw(G5T$<;}Z&EOLfrFAdyyq(FV0Y%n z57EXI|lJ~^0m4Koniu}7$RyAn1<+-)q zKV9l>B9ducA>~P25W~7c0tl8(y_KwX+IkXI_eC;1c>`tr|5x3aOA;9 z9qiqx&Ko6?a(vi+f=UhLpoZ0qn?kUm>R!Aj*1wCCO*^tVg^}U~&3e>A+UXsMOtzWs0J& zZu!eOF|f$O*aPJ`EXwjtw#x$dbs~q!Zbh&SGplOsjUZrY!{sT_J0vN%9yyvq=SPl1 zkTip7%}IAG=@i?oDBfT}e`;z7jH=TdA9s&P>+rO5ZSvX?#pjjW;cFO}j^nxNQKNP; zFdml$NoJcStkI#2v7i$IVEvk8jL_NhnK$-E&~f;KL;-o-n}}lhXT} zA!XFBj$N3(saw9@+4Y+(*GCND%vns1W=-8zWwaH@8SoC8qZsJ7>dM5_6Z>!I)A4t`A}jKtr=fNT+9-&%57Kp*ZLl z#U6U)t|a*=>TCok#0}lCp8#(b;YCW(A8=0*?X_~s_pVMyLgUFn05}f?gvoj~{MsA1 zO8_-M%DEgdgOdjp2 zleg}wCDk!zX`ld`F{2Nx+1-o`=+$A$uAVj?y-xjsfYRpT92$uxNOmhm!0+tQ zfY(?CL}-K73lu5BRR$&x0b>#$0X8M1QoWRb6c7U8br`qv91lC^0{H>g>izbdOW zA>{(58_g>Oyvy{pJgr$}FLA{jRV$cIcx56J$Y5nuxW~$JraHG4sqS^eI}pgIW7`+c zQEnCqul6Oiiidkv2a_O4ae-_yV?ug=Uj0&KZyFe3rDz1Rl%#$)`PgFX9dtrv#fj#& z3D5nf92IOwcHsm8$*9TvQVFxc?XYy|d4i5zP3c~hv`~&ko zU;(j*gmi~F){X|Ur?wmDe@X?C>(fWW;b#@x?xRL5O?4Xmd1~o=C{Rzkb$C8^9jx2iBa&squ(o zN5I}yT@iIjr==I^`=Obc)MLGbRT3sb#pSZ}XDh|vkH0*y*93d}5izXSZ8$9VWdD6A z@p+IiqUuXfqXvpHXk05${P-pHsgBbqR=YiBjpP)*5 z>9vl*Mh8Tfsw4-gTUjClDLgx}O;C?$(bpkpudBUVtudTj*3Ob&5^+5PS#O_=$4hYa zZT?613mRP44~Il(WI1vuL)%BwV4ULbtG#)cX+_ZZ1fOLaEdEu&NJMsU0XPFWm>;C! zr{^L!-R9n=MluN5bIf2MfC48c!0ZQSp9ruRg*lv`-YZ`^t_*uFEzBbOtFX3$Hlw1r zPQJT-e)pfVK4AbuZ`7Si_@60N0*c%DZP2^3QCc>@7Qeg3f@Zl+yj?~f403?sn6}uE zloRu5_LfZFCgt~%nk)s3i;qE5Wl&Pc4B5Ed2*`8+?ors1a&9GtJOM`uQ8hwb*-~Awg5{DOWlPe;e#N z?9h6Z^st981sk!ma!(^c-txF?B$uAcp3M#;I|iWx7J=Ik?5ZPazcd+I_;dq9a4gR$ zqond&%f&3quq(?Ab~R*XrErv8$9S#BkDj%NIVy(6-T4)b*XWYdr4A14K>NpzcYccIq&IC)WstqSLfcq5vZas zZLW!Gl8L?_?L%$enciT#R!%7Zs2Uja>Sy+9c$ZPjF>s~~-l8C)iQMC%*79-_Dq;3b)F+c$$tB4;+-685Bk4DrLI znD)%6bNp46@%*N{?iqQ9K+`*$zm86_hxds;@te(C@ z%p_d9P^;@OP`(_QTqH;;g6x!2hX=2$VkM0g$#E16z4McbHW77cqAmKDg4FY|U{`Sw17zhL9|CM< zvMI+rEeH>Bsvq&GX5fa0hC;~)wnZ3*CvJhfckKM?uXXs#7m2)sJtjZr$QQ^&3#+>B zX1?gdG-eVp1sRhG%~*Bw*xHV#un%`t^2)so&5JT}rM}H*%q^+n2L2JOO}*i$5rWQb zP;Yt4Z7ZfN57t42+Pd{pG#wM~p*QFIOplgqH&hCD_B&vFsljrNo{?N+3lV(yL<5pq zx}+qYORYC*HcMgEI9ZwVAd#QkD>dyF^Wr#a^M)*5W5A7jQAA}e_s|{s0UDF-bB_7) zlCvtNO=l+Yl<)Z!2Ke^byy~92bv|IbMYxC4z>N)QI~7Z zC?ff9s)l5jfU|C$-8nOr&OGk5EhI54;c{V=?j6c+WT`5>cljyPGBrVzaIX;0QFjmL zcI-V>JiELH#qZN^NBosun{IdkdyNkOUp@CtNYew<*nXD!@m<&y>S8 zk8P~u#Q#~+e!tL{Zkfhv=3#J7G6UZm7vp>;FL{oP+;~TU23`C z?Vc{HE}|yy{7OUFhYOmHXj@o5f+`u4>%u>bQJK`VjoKnRJ|pkydnZifO&n%`_z-rJ zsxL)Q>QQ=5!`}MqqDKA((Ypk>K-f#Q*Z1tCx%p~hkrmnA>EaF>*WF97MjVz}IbTJ2~ z(9rtbaYYt@Ja9;L1BjtaMZh9;9aG-Cb#b`*2#B7MAjU7G363>IPGr5cl#8sw6;PA7 z+CQO1=jk^kgTb22BO1l8&q~37pm_pwdw1y)7FyrUT=s5|c(rGxe2Y;@8m%x>$gPA3 z956_B$Qv*NS#%J&FQKIol`1B#lWlS;DdRvmp&?HwHYJ5%gY-f9ern@&9V zC9~8SA3{mkOY81_hM&LE(8T4%qo?LM5D{@KzFr&TN&2#q5xU~qLO1kV42jeRRAN)g z$537uCT;mQ3aaalk3?M7L;Ic+4nkw2p5||W*1lj`q$?%0i?+*jOcLY>A3)Z|@tf;| zSTu|n!}AgXWo9|68EZ1+(zAPAl%wU}3{6lNMV_Gh!0qckAbh@>oqf?6t|bz)w_jYs zsN=OStnA=?X|W1s0qJSE(CTRcdKY_ZvveE&B0v`W0JRsvts@`(lV9a@eAcqkForNMVWqS8&{@ioM$yKH?D zN83CXok(Tfx-8amL)*^EXm**wDI0}#7DVCy_5y2W8J!*R@5i$sI*<9*|1QyC$~O7F>7h#>j`o+h+z zmjP3*=2RsV$Hi$E0j1Y2;hD34Wj(TITZ(6<%r9DzSz^dq?c?$GVa$nSAj7Ye7`kj+Uei?>zwL48xGNB`iOqKhNxe}OSU z0KMFsGB)&VMsV1W<_ntAmHsJNSy0l_;d5nR>X@c0u{qDBVbH7B%Y2nkUNy)=V2gV8YSAl7-%a_obh#il`Op%mFR3auL%PDLAIQbAV>!)5SMIravquUuBHyB*}4r zjaSsx7%{3Xu_M^BNaUtnAU#{KJRkNItN~uua@W==JDXmAl3zHX42P5IseDZxX?~Qo zL>0dpGX6pT$KG{3tnSPk)67gV6?IiLlW9)m-YLX&35Qw>G@+?-LyW8U_UPm2iC=R_ zIyQ}jL>jY81+JO#lt1a9oHY)URVkC3sx`BC|Ni2qZR~&nlKBg$(cFB5_$S|W`+jn2 zd$Q}o|LBvc0GO4iOCS4jcuvmTUx(|B=RHEOKASo{DBUqR2c-U{!M+3(T%Z%l`VlPpOypH`pEK(Wffs4G@#1c`4)&JSrQI5V~a&x6R*W}LEWOvfD8~Eu z1-xYG_9>Bso1K*351o=}lvi@iK{Qp%a7kK03VrH!ZlhMtsx0k7waZ*X<ewCdO zLq`h_HMjy8zf_xl=pB@aR&i!iUuW&u;9nL7O@(rtj z4>GGJtHip|DA-vkCcVOtB%+tkwIh}&MegKw4jRnfbWk8fx zhs&OJmCR#YR=O%vy*qS2~NcP|Tw!nu3UkFkxp;#D5 zbYTcys>?v%R(*g0U1wI91SY>SDeU(k(@k;#+F92Ze{+D6f=0;)*4jifC)a+o(>m2} zX5tIk!$~*ETNkLq#^2m5LHB@Zi#hv4&hUsi5>I;Q>IAow4K7kMZJV=sZPH+c9)50{ z)~--gvPpq>4t>4~Yp-0yNxH`9>2Hzy5K)rbhB;DqrbfKQ(7yD_QqQ_?Ct(s3)u z5zcDy#PVg9-^+!9kM$`Gy&j@ZcKM<4cQgEKRZuM zys7;|iP-tLp9?Z{74_Z^+T)Trnvf=&4fF8RN-E@J#S;ZzG@mTG_75@v|bzCbH*spYk28!`0a}ZNxQ;^nu73_{aJnP|$>m ziFs{+0m{FERWlcaG=BVx4u|gj#g(Wfn~aL*+2-y5i+;9Tv_n;9tI9WlO~cwexXdgoA)hM^Pylh<2zD>>4Gkx%Z|{9MbI!I5gpCr-G1`O&Pu5f(n*Y2gBLRRfBg#fJciI7#Q+2UPHP1o*mOiA8Cgo_&&6=e}{t@8vwxtV~*D)l?FA!z>5WC4hO9^E){M~-8N+^P-Txc ztLR$36dDzsK$?g)OpJQf`>3@&UE;ZR_@i)z&kZv@6oolyV&-1m&)e)W2&+q$v7Ja@ zPM1%{n6-TsQcN3|nOwF6bQVpChtU>MMV1w+uvdO2=-H<|-Z%xx)M$N%+BV9OG6kgv znf5=EvU;Nm#A!34tmSpZqxj>9pc?QFKd-I=JczS zxjXLtLvMY!p+v#qky7(uqalDaBqk5UTReuBT&o#{WO?&gg%k-1l!0FDDVO@!VSloI zk_e`JYO%72G*bn9Z5bN)H{%knDBuvERpfi5HKttp z6O}BF4Td9Nmi$-*5DkI{^n>i&N|oMfrlYo0UUcg90Br3>geZx1)61QN^5JZ|Eoznr zSGW$smA^vYiu*de$|6TECyPl)c62EPWXz8JdAd$NX`A2D=kGdo2KaW_=T!Rhz)Rt)N(CzW$<(P!!p4 zzUbGH$xW6D9sPvJ@ltX7qQ(A`br`ljo3=JulVm)htADTqpJL8{3lz=XD@WlH1~ITf zVQ?Y`!*nnhG2S5#a53(D^+JE%R>l1j5MuT^rdky=K z$YWqY#s`r1s9H=CgXrg#Yv8N^3ye5~PNemZQ=z&uJ2j_su-SbBSfb}o^1Piom#eZ4 z0R{|{=70}s#gs1SS4*YH9VZT2wE)py@Q@aT9F#Us-oKacA}4jN(NSHu4LuJdOw0|* zIp%?Cw~zFAKqlTFQ02c?$2wVck+;-xcg?gH!p1>}f^uH-;2E3WM=A2nWdR=>0RDA( z6X989d&+WX5QQ=>QWSH`H^xcmrasqtN`q|!ksQ9>*@^`(I$zmu7ci42RH7=r_!Xk^ z)WV!UBI8%=&h?v|c*JMquzWIpzId1ifKJ2jc@!s%N2@Z4udb`Rpil)W!LC{3OQ zJTSA)jD}BIM*Jd3+ses@+66z3?x1(fu+G9eV>AvYk@V6PQoNhV0YDyWzY7U-+l2Xp z`&BJ^1bNpb4vl0{*U>-<$cw@a>T9GTP9ZliK;s;Ti4tqg@po zE`%XeV@M0&H;Igl;Yr(o$=%)XGYS%pf>1GKoDnV*ueDUQ zuDAxdCU(7b14#yxrPk&66^(iOK~TqcjVW3{%P8~(0*ZUrD2DL?$;|m!Kj5PufJhJ+ zh{QZT$#~>Y+d~N!tTs2&f%qg3If*Z-So-l*{8N_4#yE+?<*?bo)%oz=!%ZkOp=kCk z1N@wb?Y39)FI5;Gf^kx>vG!=bL#ce2aOd}%+WKowAT+gt2?j@lAM0b{MAg**0)gvQ zw)0dWGLRoO`2BccTO&lh>GqvEJ_~t0aXWej_)N!xL9Z+5shtK#79>TplzHe zYEIoObA&skhx-B&Np-rTLUTno+3EujLF$ucUA{u3ommFgF+o@e#RgK-LM2bBM`%H+z49@Bd zz$OrWO6bDgr=dENP8dqSPFeUV8w<@Bdpjn(=8Ym?D?zv3)_cz`I_N#Xf{^b!MK4h= zQVsVapG0f#I#jZ4p{ht$Q|9jOpu{Nd>Rc$APrWlX(yzYRt#g6A_|NVyw)R)$jrov4 zm&0c6N~dr$uQ=ouUzen(fs9Sth#6|?unY2R-tCc_n4hzlSJ~%M<8ziujFln_Y{DEv zbOw-V)+?(&9!+UaOSj%tq^{(O{mxdXXu-#qs~%}uJD>PP&zVLVdlog73FEGfLaaww zFNXc_(aB`$5`6bMjr*Z(=+})Af{;!=4dKR$iHGs{v1Ck8lq=9xoj`BUR-rre#)38F zmJ9YSDxoF?NW$I!lB0HE&2;vIqK69Byd%s+@kc_f2F#9YJ&sQr(-Erknj~#fM}BKs zGt{nDlNe%zOl8$FfB;1xo(G@3nkZE{kK%HX`-@t4Bj3a4pl*4vh zKLTEi@g-QGMPmrJAaP!auTM^Bg1QsS%Y0@6gNZZsy^rGnOOh=LuVQ8n^8?S34SJrW zgzL;Bn2%T)?SR;C`RgTXrt`0;<#fFU+;ce*!}zEN0HNbY@H0=J~vRPK)J7uys%?2 zYyF0)cltrTv?Rs8Z3%j0-(K|n^(WL%&+DBeh_M&={NDVDR3|B`iJGEDIPjWC!4$?< zavk?FP7WaY+J*dQU_6=BcffJ3`X~(+#(Zw=79@#GSc{RQ5$2JS^aC!;D~fgK(B~_$ zgX#rXqI{9;dlbM)5|l<0Mg7s2G^l!C2DX`+@m7!%1f`-t%%d@nn#KH-I`{*rF${if zA9xlmRwMJUKK9@NOE5vJVftN0<5ZWghrRX^^QD1sMT*ThOmq`R>0og4RA`8}T4u@T z(J5@>)0^c<+%eG)k=?_Zbvi#l=hJxP_8!xR1vsogdRb$jl?LoG zL>KYe-%zblFb_}4>)FkqWFV-}_}}c2P|%td9=v?{4W^lOSd+9emfc25aNFC{Q2gu{ z`u+_B5(5zdpPknUs zHU$vjCrrP^#13S}xdRL9Xz`h?N1{2}VtcfAm66VJWYb;`^azVw{myI;=f=>a+K!-S zdF>DHrLF^_79PnDOSM&S7`PA?la+ zhUKeAC;ADy@ImHg?jVzTjX%{yX3|-BXVoo}RRHQxHps+)ZKoul$e+AQ8`1`P#67_siWYJwn9zmmb=en{gs6!PX`aS-I@7EKZ@ADL;Z>x!>ZmLa7(0ov|5C1r7x%y_Oh1F3eWUOL$7*9NpX zn(!1N>*8kd1k4s$>JHOq9v7rQASYV1C8h5?$5aH6*VV2&_^GFIR1IDb{d)gx&kr3B zT+2+j2q{yt2N)L`SS&A040$TBr0M~ic>SmOX zudntt<8CZwk=nX9nb;0dpY@S-NH;Xhg1`im{bL_2s+Y3bEn6nDzHXbgTf&7i)hv%= z^sw^&!}sD{ZWS0PsZ#jktL^)sN@8EhgXDCbXc_M1*k-5_+gPdLdVPM+lzjEk4#Ljl zb~EO~i#8t`z9>s^!1}&OS6NuhY&Y_4f@%*Y5cdNv(VGHjVoo(dpi%`$8JXzI_Bg7a z0Awx1A$*)p+ikA2`V?^il4+5AX&@!I*L9A}=|c`rxXc;-a~sndHy~Nr_e-hrG~>JM zSnJLr7Z5F311>zsbkIg|&#gF9(}gc3R=pZciU&3i^Ajp)LX|9< z&vEtKt2ZwDtXe{`JBOnVl`(UaU5oV~RNm{SU<+D^Lo%S|1du6>T1sarwv!NXQxU28 z;tiuf<}b9FHoeatq-jC6i7em-NaM@uv?CR?cjs?6lQ;(hbjmBrkM}mm-)@q1r03`g z^fGPj_>Cp(gS{(mNY9=D+>pux2hfmB1T_blx;2$<+XUc7JO$!VaT_U@SUUKjX+)k{ zo^@vVW`M?D~5A@h0K^z+i|xa_Tp%N%JDP)(Z)Nj)*v_BK^M_RSa$RCkm!T>tKm}5iJ6{5Hgumc) zXmrT^l#BlyH)^5sfy$lZf)9wBOZJc(08}6*uRd;v;8oPR#_8mXjpk}??6~)G!a*!~ z>Y>1C9WTN6T7<0JEFd$F_WWchNEKV=**MFKU$0~CB(I^H2SUwWl{gu)Xm^GISx?=w zZl2D=_SCb=@V>$H+lC9zOH|+UhR{v7)>qxO9F59@V|dD2yE?N>G}mDCOj-$^M7cI8 zz}9LIXi0}!(B5Dq4>vn);1*exHdYHM$c@8te{B9*UbaFILI~L%p+_lt`VaiU zcCG?OPkfk?{X+qs`fNZAiAntvZ=6orV5Irw?lRGC;2{$gpuaL90TD!vE#nQ#ddvtQ zw*wvO0OJ1XwyQK{|1LC@f6jis+m77{1b&%ddwn|RP`1oA5AfwvZiB4@;;w1?*ev-~ z0Pk%pg3e9C6~6e-+$}G+DJ4}ds)nGH6}ql;O(;mF%mO!BJN9-J_Sa=iqfLy44k;)J zF&y<%_A^W*TS=A87k|OPMSNe)M6osm>CkV)6p+_HKl=(PL|+yGRX2ZThO04m(x&8dBzLYhp*mqmeTx z(+UbcnG>-k0H*A>s$NCv9^CaqC^62A^zsDe?00Tda85MFgu#0Hz@Z9nopDc4kY=&9 z-F_eopwih;nd4uTnxcwn3x`w6)x$~l8>68=-HGFKF7lHV6c*j-3#=K^9%9TLz51iQ z2gnx>ENi$}b~*hB%9oKoxia;v$t>!nE1W)lsqBygxo&RqLXC?q(a z6Cx9x<1x~Ti(I|)R0cBLEIxTu=tJq`h)ovKu$)(rt{BmMzbWx%|_5URAS$8niHkM4v)t zpRq9=q(&&!Xy-^UkiUA%vWCR95Hf{Xf?PKkLjxo(F;}SpU#63^vc9BsJ0tl4Qr{2G z*@D!%zN@@CSTtdKy}sQhTTpshHS_iKVw>J=TW?|qH2R*v)Gukr?jPF%^b``KA`ltjpG_J|0X z>|czI*=P?@CqRP2WOvn=@}bGd$IA;;D~Lokq4%HekMNkzoF6I)i}^d-wZg$6FIzU) z9@U(i7%luEdvV*m7i&0F=~@h9h5gf*o(Fpn@14drCkj^EQrxl6kg5`NI$L1q6#70Q zrvqM@QT#k{mlx8ZMa#MnP>+jWzJ8`JgnO|X(xjmJr_9zlM9LapA^P!Oh3;f!$W&2_ zxgwwK3&ROH*U^CniJ4U!3qB%BVw?xkPrQQy1&iah-I9g0pw)k090Slefb=ezNG}c;8W=<{Ipz133NO zdY!k!SeH<-2@Xr(?W2J0(s|Q|Y}0w(zdLkUD@S?2K2zzfjJtppQ~ZhbjuR|$FC>a7 zM$=b$Ds&V91aP#5lb(Yp-aS>IRjq1?2~pO#V)c8IL=Jr6RVXCB;-?QtRsn2zmO+9rukVF)I)pjXAf!NgeCceHDr>krM$Vxre;815 z@~jzj$TPXFl@64tq@ezM^YgY>qphiW2Wvl^p{t4~sVdDBJL2wYz^IdRP1svI2w0B5*kXEYx$lG_{ zYuZ~KxK<%>YFER_6s8t{Tpp$b8KEr>JtswR}eW<%Mi_JC)clVl?l01$|{5 zBd%%#u(klV5gHT-~OtS;8n&ji`rxK2@axvF5%uaVR?HuMhd za`;mqJlmCKaAnRxDn1_RS}EV`dir%jzv79(COd(%z6CQ&=7hid!c{D0bMIQmoHQ99 z$-NVoO*cfi*ty~f7HBBf81}4!udB5~E8`^syzVoXZw5+VSY<|6$cBP>CIRy)KnR+V zlg8cdoiES)V%iz_eu;so=CmVy)=5P_GsO>#^6!@9A1~rqow@ft8*nfPW^I(`d0|6X zDLr-riJvlT^o6~C$tm0;j`&jOy`3R|m>K$H1QrI}D{e*X~8wRlw!DQ8r* zMtMOElpEsqm%LCA)3*^)5=cUciGyn*j`(evbip=@cI&#zin2#l$(`ojmVh+n}}f$eLnW6Ho>f*URAZF_Tn>50OX1Uht#*xuXcC{_s$=-`E4;D zJ1#@%ioNwk^&Gpo#G#Mg!Ra75J8^cQXLLtK2isQ91g`rjhiJ-OFq6z>rJa(^eyp5k zw~%D^66Bs{_mc@Ipbn*nh=5xuc_ay@ulIk4y#xB^Z0crtppp5tf0sAGXY_Y>KSse1 zgp_C?;LenR%dtpJ=8!xg;KBMu?_{|P^F8=Z1F*4wO})E%E!O>3^|VjOgR-k3qC@k< zz4ZtP(PJQ)||cL*xr73fe)D*10`MNg%t^n(rG<0djJ% z;|eWHdf0-rWoeZISq!4g%GT^7`S@}o^=!><+_Tyw;#R?ntpxKhUl{gg_ji-X(a86#$)WfoUc0*W=(3^+rjO-1ZT< z)#!R?d-#cu;3wAhA~;XPsZ^rak9=3h(bmXx?u%nqrKf6q<7_*+MeaD|3$!Oni&Tbj z_9AaG#a|lUVDmfB9FpfPJc`gW4vaMmw?pvAq>T~vm*oV?+{H7tK6E6IN5-EJT#deX zU3fXL!D2LRfrUv2Zw0U+CDhNBIrVbl}GU;m(Q`@Y~4Y>;d`d+E48y`Bq$)bNHgF6ko4D+2`F?N+p=Ep?auD-7= zYitQeX*9goHN|!o+eJ18WT8hg^53yp6v8}IiIlQm?YD80>v*!kTZGl8sGr%{Mx_F| zmdb}BfihWDG8yZ3hxab`=n2OMr{XVx#qnyx{+Ivzll^63KRCAbV z_0)wGejYy6PaiI8+5PLoO81QFeYpFTRYIr@(l9Dm>;OqZwPzE2;v365iHuG)q5xSi=>Yxtu@E)@nCPelmPqmL`si()rRi(VmCayFNjBV(;HkFXoOVl7M;u> z)Je^xX5uI7{`=_oB=l{}s0 z&-we_gp>XL}GLN{+v@6j~J@6Y?ot(M$S_W5nidU8@uDpXm z8XKy*Q|)uoG%N&I6i}X0?|Ki|h-z&lKWKnL>3;Jh$D7miE|{ZsPA~4tV3=B)!hVIi zbNl9vR~<&Ylrk_Thkov0PU>5DxZWTIYBDY~<3 zq_8h8Ou70~xF|p&3Cbroq9DJ`-V$VPzO*O(MUiJ#m;ix5@r(RP< z(W?L}rifX5nge^hBm&8b3dNNz_ULzH1E!02sML$3PyO#6y-`0scsXJZB-tI$?ZvDQ ztrZ2uEoyTLNdRIcz_&O_s3g{H^?1GtamWU3%!Q>}ElO%GCKAp8y`~dOa(2A?2oMSj8s$V?tqGzr#(>0}&zI@luQbw_ zbbaNh#pu9`s;Kq(vXyb4rfv7b+m>_-UWaTt~X*D>UQo z0a66U8Cxo$=Na``Vn?IdQI}y<7e{h^nwAf|ti=9qwdKqT50x8jehOh-iUmPuQa zbUe_(>)(H7|26|ct%;AXY38v&J7Tn0;`UdRf9V%GicHz&j+H`%Sdlu#`~2@LX-y#= z=|Ol}@YY*&lFEI)CT^_U2Y{h?CrD*xJ@e1yRGJ4d*PvKg!%pY!i=nuuk4&2e)=L{3 zhUv(c{mz7g2r{%TiHYW^0q0qWdt z^pHCa5=ceJq=X_qT#8ThUz7G%CObC6(mLBY1oobIS|WT4w|T*G2J-4;y#A>(^-8@m z2wQUmZz2Dg6z=mPREmqa9p#SJr|SM+kA{OAyh!qG`9*Vh zg@FM+eB^*_r66sxu4E?1bI?XoRzy&Ij8(Q|yie8erP0OMBr^dO{vVSC)DE1h8X?qwUOwx91@> z5e%2AtG#xd7L0C>AE0Bj}~X?w}=i{HD3dteGNhsMm>hiAQTcx z*^u8nvhFUB1JhpRZ-d8iCZ3}{U#3y=jD1pfWSj}7%ltdCOXu#J8i!V07UkNCY8PuY ztYxF(md4UlLaufLey9&uc`oOKRC)Y0F*I<@rS!B6gAs z5Mz%!ZW{=wz*c83lOFHPzYvoqDfg~|x%XRBZxgG+8om1_pwUwO^#Sj3}b@+lu-_&%AVWBd_&h3QO?e(ADOQtB8ZN-h)fblA0HW+c=_ESJiTi>c3Zu(61Le87il#+*8cifUj< zU=kp6x~qLAL_OCrVSQnXTmxqz$3#~#YZdjohMUp&^k*%(vieeInd8};srI0v-KZ)D z?e0cMCBO81_B@a_xz;VYzL-LTj6MO^X0IPM9!LsX9X~ng1w2C|JeliKF-ZS4aczQh z>gSi^M~oAb4x|WVA503=k2{J>yBoWUMDDZY$$HMsT(50_>iUuIToq>vw?xy5mn`?g z)tQIP|M-`czCC%vffU%T^gLpu^{3V19WPnFUcsGX9al7YqR8rQ$pu&TK;Kf5?V&#m z;IfQ1K-|p+!cMRwd<%Zcd(HploiDB0>lh-qr$uLM+1>K%`&heS$amlGK@&3auJ5~i zRx>gY;h#`fEJ>|-Sg4LB69s`%skf;7{SE&RN}vRe_TyTv!n_rlU$Fq&7C5htp zGrxL?swu|Zj1syGjLDnPsB4itK2+(d#YE(Atk=S$$ zb%OFql=ve^|9@0MdI;Z0bzqIM!r4m-Ei zs7^E3*Opi#0Z@~86E;#G1sgN*i0jSEXfCvKIIwV0yqUy>_}3~c*nmA^pD|uUh?pZp zZF3{f(0=jeaIhZLaFb1w+cCVDn#Q7&o1lpmywb%#Ko*TskN(EXHzC;JMCh%#_()uR z0UCZ#+D2IY_*oUzTWBx!@QjoSezFB!DLD)F?EEe`J6FPV^aYY!>tvr_YvZVEI-nN` ztk@1;{Y4Kk@Oezlwx5%T=dmt|78n6-Gb35But<`dpV(kmLF|I@fD-lM1K82_L{u1= z(Hu1P&;~cbfQut4bSdF$vGHa9o{Y}oa-#szt1>| z)?ntnb!`E{7>Vc2Kdy>~++p7EU``VI3QQgu{zJGm#`*6ndH`tLV(~Sv0YrOHczm~` z)T=@M69Qk(%ajF(z9@TEOo(lfvLSW>_w2K8*;_A#s?qPnIYTD}6={{I%Bm)O7_Xq> zFX+V$KcW|1d8vnfPJLh)wt7_Z{S;dTS|!DK;|BgMZp zXFaC`ne2KUVcN6ah&wDGTNktvy=!zQ#Z8v>2w~L!pZDIuKfpCkS+~O$h!~e@`Lx%e z0)}huES3k~la#Z`OaOXI`PlgH^=b4b>SN?#(xQVaYD%2tc)Vk4V$|lUeJOg1iR2)L zqyLSL9Dedl#DvrSN8k~kqTQI8TK9kTj8#N`f}5Fk!2bS<#DE`u+q< z?HGf>ozjRe^zkq4M^wTDI?lv=<#C^-?UuGv@ZJ&@S=--7_?0@{^~5m0i7jS8rq~Tf zcBD%fdr5g+F>1{XtpF}?KG4G5l|O*~5(XJT6hDsgjNQ`L{Bl&Zrmi@BQc?C|q5rhk zIho$PAk{$`RO)s&R8-KbJucjSNyUM3Y1SSUE7Z@R@vvF?(c%uazfrSGZJ{UxoY9Hf zW`AQZyO%zJ0kW6YVCZ2#+0xjT-CR8QIs2Ft*j9z1TEF)+t0eHriWWQAA~;sz>&l6| zS44u+NPtD`sv$<&iia3-eWN0=6@^9nT;cp$XL7A~oP7D&!RiD=Z? z2@Y|yvuBAf({Zp3oQ?KFIo%AjAf8RBH=SfsHI0M5)0y`)EaMAI;$wq;t|>8nd7rt1 zO{#7kuV}qWFf?4oB;TSxeN6s7FTt4P;_^BhrG!imt&$WDNN~d0z$i8Cqdl_LbLLTF zjxk+QumO#s!d6P19xJM8%^OTxoMPF0^Rh31B!aGbie(C)piMr`CE_aH0cWfNTyO0n zf(ep9W~%WXKu=ss>y-rZ1-XHJJ>mNHM=@=v_JKWvGbS;XzH|rN8_H(A+O_WKs}>Sy zVsZ8DiqHh{RueP~YI}FmmYUk1g)_n4k2HW5@>>FN_4jJCzO`-0WYo5(DWrBQnEEN6 z;;JM5cP#9;oKcTkqj{9^Wzm;qhS$M3+V@d^9$_N?l!_6LGf?Cv1e90c$Rs_}z=C4E z0|ukM6t<6HVg?4&5--CnAbQ<#ciiun%+$Aulx^upO@et6bngiPtj6ULB%o z_q=P#JAg(i9!xLeHaB8o`P976m!Xf`c?egLwd|~M>-upPBxSVu2;>zgPzPg8LMjX# z=~Eg1dL8Y&BZoi$Q9!Q0ou2u79XW|u`NM)v_z{xTmIqjSVNZ@}ENQWIc#I_D03AisL z&?3%}eRu_kvZd*!dmEnvKC5LnB0rFMf3euFbBI|rqZOWa?azKvRpwn6`d+xIHqX1S zBwcWFh`#oaX*)0<9*VuD?HN&{{9L=PRX&JTCR=3Wep9t zM-)pfl{15OlhKw>Aq2I*WE4|-~V)`SdLUSWt zdG0yIRHE-`LSA#@5bZ$vu1dj3{*{a&+C4v!cyZ_`Qw%3{9L2581^UU+VU*JURA7z! zpiZ?W>*NG7xa!0D91#OfS0AiWVLVl_XB9T=%?(aSUJR8N~rG2v=TgH_F`*&?XC?&P}hK zm%0aD^vrbsWVrrowIJGuEo4EWX&Q_#ysJ{2%OW|INi{roEBMq9`-hfBrc{kJr}A0E zj)Y|{Huv_InJzuG?OpKenmHd~2poJIf*Vy_4*LTaOC*jRS=BJ>?Pd+3t*UUCjeBmQr`lYQ2jDiim&ttOtdp z*({(B0KJGWPN}YTl39x%=vVm!FlAj4sPz*9`b`-|1E4VJ4!0cpsC9`+pDIDvHEf|v z=uj?LYx}olU7no^t+a$&=;((jio{1pJeSeR;I^UZCtLW5&wOKziccbBOh|O+%$~uS z*2Gh(N;|EYBZF)`dw$$L_{mU(h`XAaNc_Y{S^klKRsi7mI|CnBEUxToF>*t7PQR5vl zbm&^p(xqVj%4#L5wW&vhl6m>1$O7_nc+nyCb+r@+}SX^Khno4W{N`V(e5X=^?<@_Bn~!M1Qw?7p_KQ~FFa zu=bhkUu;7!vK-X-0ukfg?qrclCcHjX5V3w%i7zyww-M7UkATk5L`|tf7sHt8nlOPdCGB%Fx1GEovqG@y7-bh>eo%p6uT3h+f zz#0eNescOPet9*JKb|7Q8&vQuuQs1enDrWt zKubzx+cCIXRx*NLJO1dVtyH_DQ|p6^LyBAPeKc5aGA9Ro{7K+h)UvJ>bkr5Qe@yPv zbYs+epZQ3dV*5HY4zkskkLeB!@7BCcc^IJ!i>Ht#pITK%hV=Y}Uz|%8`%1D7MsJDw zt4UB4ANlC!*hBK_N`lb>F>m!MvDvy&N6eY2Z;GJh>T8@gr3sPc==X23grC1WC&1X^#MQ4<^j61rYXG2QiZF`TX@;Xxj+B^LYOE9 zgdT4VRq3MIdM9sbjAYCkw9J?v0WKBD#mzX{Qo0fH4dC;JxZ!E?Ix@PJHjFw^1HjW zVsq~9-Um}buNvI#DCZC{Fn7!p92J0N-LH9d&yqN;51!po%1KVxS*wK4+pk5xL~KHC z`HagVm~X2sU%73Vm=%=`**%lP9)^2a31v$cBlNq6q(;hDV-#xShxBYk7M?vKY#)i* z%RXg=wg7QsGDRmcS15_3Df*rfZWgzYrn}ySbpdI+X;WU_v&sfzy99<)2bU zoG$BxWIoya@6JyfnkNTod5_V#Oo*rm!h*z;%M)elQMw_G&TebNh=3&)E^LD2rCk=o zESS-EIPJDh=@Q$dx%DHHG*O171wV(PgCe6%;yvRV@{m0nqcR+zm)fCn4*gH>gebNt z_?L5yv-NnceEwk6(mlhm7?;< z85t=uJ`H=~6d}NMNF?6h1A^>H!{Sd!|Zy~5pUp#S=Kr(2}vhR00y!R11fs{*o+ zHHZT2{{glf!HH8_BmqSv*@qu*_DJ=I*al65r!a&qvEw}9{B zQo#G$>MB%R%UvdsUkz^q;pyCH9PyJp+_)=zN>hW8Dt^sxL0op;3eW4>+sQ zqX-zgNo%#ARK*Bk>KBPYq+T1Q6Db;wRDG@t7r#vk+D5w zLx1WjcNm3pdipvcUcSPBT-ZOv0qp4=Tr*0o7O1h1yHREL zv~m(q&cW z&`0yEGlMzcKQFBMR)iW(I%YL`NBjd)Z?~pL=If8gi??edcCR39rg|#KGPhpE_ z$tUDay29V#4uM@F8a&s7+Bg)F(}H$bj*zLQf569mjd{rD;mAB3+xX|-3+ILHFxFL) z^#YlXa1eh-Iedw+TGvNZS#;&R8(J*~%C*_DNK>eBqVj#P+N#%~T~w7qjfu zR0H+^)bvnkZYJfq_&ekDjs6cYi{ZqJ?DN#zKMFTA$nxX;S9yGd9|w&xx| z;xsR#$dPic?#ZYTnqp!EFAZdY0?`z}gTQ62kHRQ?Tl_ZHzCj^Igct1n z>~e08vMTCkV-p7RpSC3ak|x`wbn5aj=IG6!A1K`H7Yj)-_a$JVw<>kF^1PyW7&0flQmRLER`|cryF>)_w5e+R-NMbHA+XS+mi8YT=iwtT3Y^rvPJbn9t z)wr#ZNa-vElYpeRxPS+L5{&oR1i0ilZ#h2&FX6SmsH9>A4dc>U znix7cj0iW`*dLeFI(L;orrADO@7+hO#-$$<4Q_Fe$A(7yPfMHgm+tC)BuVt>u!`A0zYej#4n6 z@oYQ&zd8`!-iGFPqCS<8q+FRLp@!=J?c7`@h5mEatW4~+Mrrp=kWj_FGjSO|{c1P- z_657|U8hTKomH_k0u2lxDNB{!jH8p!XK$08=NE7z< z3gFtd8I5Kvg9P{%tz?LUpCQbYRIiJ7R|jH*B93Vn)%vL;?O2ykn0>S2Oj}>Q*@46k z1w0V_hH~tAI4g%S>*D^)DHz14W<~KDXKqZs5jZVb$3dnl%Al5quQuGj?GWNk{!$iR zytR9RzbkalM9nVn5AhtfA6febIMpq_zo%1~Q^pTbZ~Q~M=x!Uu6|KIj()Snh43S{= zr0Z>uQMz_)P66KMaE|WLQ&)O}`{nQmPT6xPH0|_q2qt)Tb7=;JD@G}$bTUAdv_8$e z$6LvTCgN_p9}>EYYY}k~k@653+ACt$YIm$m@#+9@q6c ztqXKcq91*u;jqh5yLygZr%fUrH`5Lp>traGjqY|f4d6eIGH6FZuiw3eM4HD+NK8bn{6w>+&j}2bIL44QQcV6Z%C&kAv#ejKF0plikhw1%gON&_^0>x@v zpJ)qL`DC^n$>0aPMkUtkO^m**eS71{YoX<}(oQYo-#>g*m*qU|o;Fo@gc49%ZIL+LcdR%)gHl+qq&Vl5m4GcW!)4C)l z6b^Cvb{VmOebWZ>d)y{>1L`Q0Yv?tp;zS?sDQHs$d6)XgSVNKI6B?+D_2rKlF;kRF5)FQ?i21b0VA+aHkSi|HDw4!yIVxD`}(U-39dM;b0W6P(- z0jBdWKkoMZNd;IaA3bTQQ*v%o+=(toS4a|re{#&97guNHy50tbSqmwXy|i6WENDx# zV&c>YO0yl6HzS-Q?|0LRY9P-KwHEK)4K~)xGi&%SGNJ?j*R1e`1*|<_5ONdDuu0E7 z1OKFzmgR0mDU;{`L%ivZw^jGG6$uscddX8-h?=>$zocY6BZ+E$Ts5$K=UVeQXIDCQ ztPn;?eOfN>ti`L_>m@S)4KyTt_tQnrJcyjkq!Rgx`A!*yLARnk@V2#bb*%go{IziV z{*vvL|7`-(MMO}@k}s?OXN6ut6JA#7ZE%C1wY;b^F3%;G1WadT6=%QKH5Mg8V_t-J z7LQL5*qPw)|AI88KH9ac_@Q1DQC&u@N^3XHf`k{>>eG=@l=KR!D|(eYF_I@NYv9se zTJ$F^%SX-NAapH#DS97wJsI?WP^*p74_swpP5ZwUyfeH_JP{@Jc{)n%?WlJajn#NsA5%YpHn2Ag7x++6(Vz6`2cA2gmPqN#w+#?gw3%h~*rE zy5Y*7jFo?D6nW}FBhh?N$RN&TX1!jl*RRCe01L$%Mh3Lmsn$_}>uns%j}~HTuuc&g zaUY{5%hGrXh~suz!pRxDM???eqfytMLuI2TinjgE?`yW@_n~sGd!_voa+2}f4_$TU>l{N}q-|S{WPS~qV44Mix zx{d!NfXQb%zNIxZ^Om_cYI{KLrg}z3$eQ3S3{NYo?-ua`5~~@Nyf?Naj!@Iih~EUp zd{6)2R00|`3@Y$OhqpF(XeJH9oWZcijv?Nue*-V2S+$AbMW8L!2&!e#Ne^!J^%hIq z4}$^NGmuRv4pZ>FtJOv!sblAA)XWCLm>ako$*OJ>*tY4DGEfc3&GKJetL`NAGtE^x zZ<4Z|m@$bW(^ypA4v_?_6Y{7tL!|Zf5AGah*4i@YPG#e@+}i>t(+(X@ph-(lN_e~O zPc>IZ%NeU7kTq(OdC`e3P+W(Uba?iXw^O)r4BWAnD@^NEHE~`*VNX1+3U_BmfXW0G z8L3JP(D8dmWu+Tj8@QS&d$z2P(NTP4s2bB^C{vqv;!7qoPtgyE;8@+aILU6d#0|yK zlcQpru(QH|T|piJR@~KH;uyOV;MIn;pEVi#PP`>R{PBUqJ@qCgoi($zcY_HodW1T)beK z4W+`eAj>D4Haq0@(ewqI&1`&uBw7>Mh&*BR7Pt)8o^11 z3#`dO2cp~L2b+&MwKUN_9tQXg!pGT&$AlGe1Gls+Mc0}wVy-fq(6tLVJ|CuPT-YN? zjWoZ4nslFwOU|vU@fel2{+Z*fKH6R+9#e8)NlQ{`&5?MgF%a$JPJZ29HQ& z71SM+@oH-7C+%ta-_6f1&RC2IPAp7tssSF5-0O{WQQXf7!aRxAkbHEjZw#dkPdP-Q zz}AR9O`o?djPQy239THAZMfruti{lg{KcM6HC$m4F0E*jRU0pD82k%iC{2`9J44Zr zti!h;(r;Q~EkEUEhoLig>Gu8? zA(Q?CKJYWX6;g%CSBH_gabx59mpqs5m)217KaZkVGt5Gih3~1Ny?9#Hn%N zha#%RxBEt$d}T)~5d|{wnYSENA zSkHDkpzQS$!1@tiCnq7Bdsu^y<4&GaFJENBjfAbFJkhOSPS;AIs3oY~yN5FiQ@hfT znRl;D3@{vLVH;4*oKsexm8_O|>I^L$>ri;_wYai3^S?Iu&NIBuhGJ0R*`&as>7cq9 z_YI%uQKe&z(?P3gxY~&a@jVaVUPwj^e&4t7wMeop0#m$YYF4Q!Evp~=CJQxQXL}=s z3r+qbNyLBS!viSUU7y|xXLsk`>IHTPU9EHPfE}FCQWp%L!jWR&FV;zPoqtA+0SyK( zKyUtI{t<*bL&)}7$X-15@;^B=;Y>(*%m_IL!|ofWK-&A%k;}5>h_++P@ygXZxSVt! zqWDMw$&rx<9LR#J3%Nby1 zxA1&)V9R0d{$NolQ=w9t7Qzpuy1-AB8mo(1(DP=YJXI6w+mZtfL3vfA^#D0I0`c0J zphL?3)t)hkvrC>9xQNV9eVp3AF={|IyWiEnt*CuKpubE$1@&)+Hc<#CMVq6e<=J`w z3;5o$zUn-uVVI$iGHUgBw}f0uK@zcoOr}2XQFg|sG^y~=-|}9Q+STUlf?A^^5>-a9GE#t4MelH$0 zJlchEyNw2`GpJi#HWw;7(2eGYeOE0^0e8Fs-qh53>8{e`2^M5vaB&i#l=+cD@i&17 zgvgmGw}sJ4rTHJoz~va@KXva|EijvN@jMh@{B|3~fNN<28(fV@^_XF#!P}n1@wF6SfDMFDC*y?Du26`M{(4C*)JAIQ`n@cbw4MzkbT{ze8Rn7W8v~uU$ zrJ??esKjf??lAy|oY{gBMy&yU+7ER2e9Q=bik*EuH!AOU-rbEYG_YO081s4}ou~xq zU=}ylL5>s4s=Ws`3_n0R)?7&KkU}~gZlk^;>gGB0m1kiDYK(;CgK|6y#nEmHmKm)* z8X;!f;>q0cYu7aY!^rY2v3Bg~0S@OswdtMzpL@u9Hf(+>EnUTM5&NI`oO>Y))2+#0 zgM-{v1gN<~e%^kI<_@^o^1FZJJ#5=!jX~>~C>_pLDf60xCk$}q0zpkf9RZnk$9f7@ zbVQA$v1!3e`2+g)Tvcy(@rV`C3>p&aSgVrXOPMhLu(roHbQ)o=H3#6h zD^srh@aO<737c)iRV=PVx<&fqR(`6nDb0LzgVcVm;nc3rKg`buZu{0x>>roOmmf4<4c2-{e*bB{sDi%J1R{K{N2OA3T%9tsfwq@q3CYy6`V0yI-dXpecQQB7 zS!I-8L6vmEw%9Lv*)HSpX$J{`+hmfjm-+ue?DY7!FE^g%B0!Y)6qYxK%1HXyH*q52 zpaytCYao4;0zZ~$Q-h(EKf4jl)A!MG>vfnMa|*8<;XO3{rc8h&PA*ORXRpNrkMNrm zHkBE&*ACW1V_DO$t!?Mpd+Hp2In{W?fn0*JGEG4sBr`&eGr%}M=vV^3YOl~^Ecro* z==&}w5cB~k3SQL$5#jWoi_cEgu4|z`VC`&y$gy&i(OKrFz)#x}4DzZ4u>(jgP@n(xNh4$#IH|))u{-ce8XHu{w^iPQy?+)mhoE!J^7{+43;o5eB5Q*7d!y^xAxzYDUd@MXulun6^cA zSUgD!G3uN)*m+QD3ly`a7+&_gwTlxc7Qi;lGgzkAAlVeJgNUDKglIP>?t6*g2sqZ}wO*KCHAnU&$-^YEL`vY-88EXu_A8*$2N zjC{X+PCtDRhPgvYH%?ev2l4VRkbeoRLD^A{+wzV=7e#ie#zYz7QHo1snxsTm){lex z1^a>cZyE<2dRHaa<)ooT=i%uUEE}UCib(CiXwa1`bei+s@a`JFL4cic0q} z8_L0_PkV%<_!%v!^0&7jAw$Mkr0E}&pYg==J78O9RwTl`8DA*~D-<=4?Vur3n=y;8 zBJuB4;X|sveKay*aU&Kc6V(SE* z?aEr=QYm6~+k&RM`zw(vHh6vgP|%D;QO9E;+f$PXSmH}0jLaJ3XbSXoAa)=Mekwlj_vR7{7vvWAEepAXE zXPoEsv@7UoSlI?x&)|)l8WpIdss>RaY-xy3gmiQ^%vNP`7SE9FSD2B`~q>oVC;W?YgAvZGkkBDfIRC- z)rfLot%IbFlwH!|Q(u4M3#Tr3K;;{gh8z>|kAmsPcy7$XBhaYR*EuD*u&@p0;wfWt z^a>v_wRT9WSDi6w+md}^kjwP@oN6R%M*lziLA1u2oGqc;DVSLRS$B+*qMDSTpD{E^ zBoew50E+LxavEy@+CId}N})k1^{i7o=QJ`hd6 zbU1q@q9r(?p<4r$dAQ@cwDvA0aaB7Z;E+K=>IV@Tf6cHp{`K;Mhe)+|Pmw}I91?Dc zoR`J^7`#ZPq+gqV)@(|T$4A(ccLD+hlvgCcVef>;=xYYGxo|U#w)SCYfAdHff0$6! zGl|4?OwZOA4%m+@&(aP(K_KZg3nc_75_*%@1a9;#RaLdm+w5*M`?;-=t;9f#M>dM< z=}7FRe3;~AgkpTr(~mNoZ(6z&R{z5L{aAiD^vdX-`O=IBxH%!4W870o$-dUOo0uKf z$2+p$a|KPBoF`vgVy|ic5+hk<yv8Mb#o&#{;F5^Ud(m)?SB zW6k@p{v%*+HpRn){&!j`VM3ialAV{u0&Ka^hQf;^LgD%v}`!_MuqZv)ntR+fGTp)9L5yEIj z61xj4j4bg)CHY;a8MIlvY_3JCpO?$@$U@m@J|TVu--PUyT4hV2j$kFkQ%AUWa0u$g zo8uUfM3EBg^6!>{W-`I6`i>PIs0TDdV-&AsBeF{OvcIQ9uEs7)#})WJzdLGi;2SsJ zHI0sCv#u(~{kTZo9|o++CPq$LyZ3S5heQvw9Zhg2H@mbSV_g-+-GI(E%xmo7{0CW) zvw()aKLkEq0PLSl(TSzhf@*zZiIsX7HFpukfqi}UYP*PxpX1qrgbw9Rakp9Hd(Y*R zVNjfK5J$t;KQYpr^GOum;g+ul?-H-0?>*F_gzr$t8bn34W-|ipMEMo5hsLSx%r3LCzazXeacrY_s+Dv}{VnM^VfP7=cT*MrTLL+&@=eDZsY*mb)r*LwV*faW*NBK~UHglKyL@ zK0M2-Oi8vGMIn&lNZRGhG&xDDqNSnp);d)$4yVq0%=kTIYGhRGK?q`QF1+w@P}A@o zjx=p*UOVXZgbtcjUpwIHMF^NL(lT{<&{imwcCZc+Ty&5%5DvWX30~rbUYgn?(0ob z#J!#ok=@3PbV<$N2x2iNDYv*yqNp>sPBhlQqu_0Kh&ya;8A17{AGDU9GXvkYCo>{0 z^qYL{qUHO9;sNZ92P3$mP0hg1 zQu|12_OcVe(%=PagO)p>Oh;S}l<7Xz0GhRUr1%zLw!|F}f4x*x(M}9h+YsI;h~|&q zEtF2`0(m;B_}`mh-y4$6kfSI9bqPdF|i%gQ{}eAqPTvS!7Ef? zm)G$z`kmjnrm<$J<+eDfo6KjMUr;8o(T4baW7@E6HfuZvQXBfFPIzN6_1qq%+8y0WcNF=cy^nCg)?%m~&A7@`X_)b?C zeCDjByT*cy1UFS=;w02yIAyGvGF%Nr* z$qK(q^w!lgATcJ6t3`dg5H!h3tcK*HwyEy%fGvJQ=h(P{6Fl8fyXDK05fwIe&Wzv5 zygOCQyvVG$77NMA>5ulgu$*NhLO2Gq-x0HO6)IxzTgWVsI^NR_|u+h9sth<c{=<5-Q1G%Bf9lm(7R3M zmBNS|DLNFq3|K}YMoj<#4`%SJby8#|iyv&I=t8brEs2Gjydcff(7+s9Db>+lbPtyW zqNOa(AshSMiIHXxz1*a%uf^v*wmDyxz@y-))lm?@X>i!E!|*(0)`IqVP|uho-nsu< z8V{AQh!3H}_gM8g|om~#=%O1MdK{vkkuYl`9T zE_)pljW(k9gP3ijXz|RKc0UWE)U>>rg#E;O3y{}>T6pAT8dc!Pn2D%KYc^Dw5AHBh zU$$EMbUg2m^H|0Fj`zi!_FlmjX7*~DPr2BVKpjgk&nz8p^9+Du{aN`=R#*eB`{gNQ zSqq*FG>t*zEMPGEHW-@_bTDfReoeK&Tnk(ie%U6z^0O`Am?*40$DQXyL{>lU(5X$Q zcGo|~Ol;;-ABX{Jga@IPI#lG*O>&v_;3-?7w)pfQ_pFkkCWLyYGK6GosXo+y(oiHx zM3v6i{apN>lrPK(1jcSwuuZxcIew>x+Pn(83mq*kCrr^`)m1Sy9Vbu5L*yH|ZOXA6 z3yW}Dz0pI+`@R%5=GSUkYOp(ocTe#^!6%i=`F;PnK3KZMx%^_jPdePluG>U%ZuDC5 zmaNS6?0U>ejaYLB%7fd^+^PwtD2tG78pTmrE9|j?nE9gGGxSG4mvmg=7xaI7|5R@w zkcUK3G(BEnwNM7^eiPr*ua)EIvgc8@XeDU!u`HJ7YFSwMoI|SxJBAqoeh|Nt-5Y! zV{CfLrzzbhXgLL}ZlozXKP+0;Q8D}usQ$5yd;9Lg3Wb~rOaa)yoU(8_WoV2T@Ovoh zcV20n@+P1D&!yy30R3d#sd{ZTvl@7A`wm+6BppeuOTf;0%xB!&=hp5rTwe|@aHqSwqQW5#W>(7X}q<(AnoB@xKr*On2yT271>Z?f?24ap{bE7Kbe-_H%o~yAn>}$|} zCqQPdFK!BFmsyBt)ITePDDug0`5%xNp6lmTtuBrqMBRMlCj9WsW-h^ zG6PdgvS2vRKF$id=@H-|kb8xhc;{=&^LT$SpmtLuSKkN}=CSOvLRO7z8^)?u!sx2HLqE!EBj3rEa_m}f-s0@G84!zrUOjp-@ z*d!2{T)e9BLTeat0X#hkB$9AL7)#Tx9O^hBSf8?0&p2R1M4e zF9*&KeE}`Ng?@nqHa-ra!CSyE9(;#j~HBzkP zNP*OmjGzl0z=VN$44owzX)7{BSVvhlL_#|>1qf2rR+P|rvd`@8(A#zP76k z+8{Z?86lq9?^JWVqRXOv)5mTCiYUqcJ{%xxA8>|G{K)=SXT8*l# z&dEleG<#HkwH(;k!isUp2P5K@lt4j82jTezg{53;rt|OQL5C}a&GR~~>}gUicLMrM z_Umy|>*Z?vA&-`DEo;6&xLI~}EwBA@?DD62JW`19i48h%OG8;HK;?T1I8iTh{R$hb z4N|F-!66KaJ=h(}| z0*-U$0mN)Og{FuV4@aBD2*|e5sKff}jBj20Ph?D9Yq6&e-s1ln&kQ09!*|#Ojh*!0 zj>NP0*S~`?E>^Et5=xBm(ey+#ES(L`+vVM}yIOvV>a5`-p1e8(i|9#4A%;-mu|M&) zk1(i!JfGg|l#txM5q~XsP{Army&_xCE*#tyJSx#UIc^iTL6|R6w%?-t0zK+5u39^t+06dgb0XUI}}`m$eM3Pk9^X1yoQ^#dRmN}v%%a2qBWt>61SAX$c}&bg&` zE<=B95%w&7!q|RR_#|+Efw{FV5ayfJNTCRBi@JgYlQ>lP-tMTy9g;Or@(awg#+`825KC&>*tUD<%NHoL9NCDQYL00ctSpIBmv@{c3O5 zbF$4njAw}bxy+bcytb%zRuczG>y(PwQ!$3I=q=7ijzV0@5$4CQIn$Q@n?XAG+kFTA zF4?Z6RiFs0TWt__`fV#0HCkeh)n(1AV4UJj0eOyudK;3w(P+i*O`5Z(eTz8!1NuO2 zIylXKuyT5ASjMZj8SC(4MN)7brciN?oMb8eGch+SZmLVzIwQ!u9;f#RZF+4$K++df ztC-^poA^|Srm{;4{A@yTvqJi@6+WC_p=DX21=XoWrrRYtr$+EGgaB^c2x}A+Ic#uU zF{1EdK3A1~n8s(DNe>JTyDGXY#3CW#7(1w;otFCP1j_*x;TTrh)i~yyuO#hAvKTYn zkjuC{~Gd~zP7ftiks z5d(Pt9$G-{kO&qu<#BEx=pFFXN{e`Q18|SyaB;>NWW@$r%K$;N)PAcO(0#QCKcnVi zXD8>juJK4Q!A%zprfr1*}KuueQPKVi0n{rJ{CL! zTLpUSy*C{az7rhs4WxH%&vX4FM8w&%ADY5+LwEUnuE&PqTLM0}kgX7}fZvNI9M?%8 zdJ0r!NEyMT^96FiMFx<8PV%5` z@lhgI=p!zw9|4s+60x<>KDaqhm+e`WrnX69@1`PmH>m|tcT@~i9NG}HxxAJ@j!J6WqZdGDc zzCcSl>a$n7H!9y<1WX9E&~Hm&WPuZ!)W$%si}`v#*e|=U+F|L>y+2LXbNc^nuIC|j z-l&U=(WCn&0@`CcsNlWHE)*fckE-Z`jbm{{RuX+d1+(loa>L@7zvYC+w$Q_)228c9 zY8zw@+PQ=Vz6K`DpMuEo><4&ARBWqcZmtRU4vY{MxH>-@)Y-NQI2tTg=r!;Ie)7Y> z9C^SKa%!3>n*{}yEar8Q)raHrM_e>Ok?UAMtCVh3{N)V&e^J$T8>D=*w`ol(3#BF~ zk{={eAz`>aJnaL0H^9I;zGRbd?M!54w?Mmep$CR#92{;?a!7yAqL1sKnN_biZ@=K< zcP8}{K>%G)juCE33PHX`(cgZqz%Zhb!zM{Caq`;Y;szoJ`~nGne^i9lYa;@*Je$MW zu{$})<^zr_=R+UbqigQl$ou~`E&o@hiyN%U#?AnlSo0UphmSpnBy3Ip-CuMjoF>>N zU`1no!=;{ShFLG7VXCn42F~~0x!Y5)_dNDWAR}7R+6D{)-WCM`yL&;2JRv=td zsW|K-6V!wp&;}}d?V|W05>}J5=o#OUk3{FN=D~x89l9r%qA>k<1V;Q3u!FdXEjG=byUE) z;z-@tEUhW}KUXtJo`*AS7j{?w2vwDBZdOf;Gm^0@zGoEr3N|djG#`Uie^B16G*Hr@^z&K%CHfp zpABz3fK*P>nD>GTf~-QHQhRiEu^R+&wG}uxID7W`<-*SI;M|N<&H6&ZEk%uL@KxLg z=Fa$1+YU}v!yoFoY;@&>#miTTI*w1nE=2%vP@~8}-637Qzdu}4TAG<6OIR16g;w9S zg*gqWb5VLg96LB(tZ4~ig>r6_{{Px{xwNoP6Mw|SA#QtV>5^CF`cwEBHWi0tuc3`) zrcsM9-c8tq5JsF;WLdBc(Qeun@&C$_*(mrz6?6nMR%%t%YLz9W7avcsG9F9G2UMHZ zde9pw6^p=){y2C75xykwMlH$O1CeG&V1kR8Z_h2!W;JQzzPXERf*K5lEidL6P#(hqqB+5pOB{ZQ}T<)}_`+iw2)S)b{2Jk|n zZelecDq_;k?UL}77Ra;xCPio!M=?x*nNg{mQ0_#*pu;KPzg+DDa5CW}Fm*ggNud*H zykGVaho3OO-J$!gL+POE6BnL2|FU(74x@9&IUvNJXPB*K9?Cj;ulDAjXT`U@`aW!C z@&L?%CP;^vx>~_|MNdR4wU>}ul8+f#+>iBWxo= zcl+x+i$&bu#(265>$|2he3!yshCcjXG7B%le>R2uk1>jRarB63i-A5$+Xb3qWF>24 zBs4DZ&Augs5j3w*0hKRsqt7axBSLcekVYmr0-#Ly-A#OQv(mfVs;j`tex1iO>Kzto z_FP=bB78$`IN=+rQ$*;pg9lZvE{PG(fSi(8LBX1?xo|bEe#LC(#6@Y52$aSu8jf~< zFszjqbnhX!#3)1n2Tlc?FRbcOF0_Ug_&taZu^(?*)dOtV;)x zW5Fe+O59dEOXezE2y3PLyf50zOj4(nTm~@)ERgu4O_i4KQG~Ebg;0c_CG`stiH&r5AV=N=WZs+>9X0UK?6S_+?eh(vq@^^lTrP% zx>R@&4}25;3dY4bCobTII&0-3x8XIe2IStdk<(Cmh`MmH+R4=@l7L z_ACW!4@Q*}oLdFSN5>Ius?WM>Ntaa7PN&%7NSF1byy6cA8M_-J1{9oj4Wr}Y? z{unmB;|ioVc(x$wv})6#KN=r{NSuT~K$bmlJK&CpjMmw!YHU9PbrS3JJaO6zod7{o z6TO1yy#ym?0gfz-{{G+->bNbynO7CPS+MP~1e%Q7BpOYsJ`AVS0tuu;{KyncVaUl+ zCpsMD3N2Golk$NkE&ZOQGi2NmWnC#@)1bu(^>a%ymxqCfTUzvN<5d7T`Li)WLtRbp zV`3rquY;iQHtgtphq~$-X3NPC#JO^QJznlgqa_Blr_r^=#!jjy@=aiOz2W6VF|>V< zj!Ft-U$0`bps_O2GJQuoQLVYU$sOcr{flJLOfTE_@U^?k?elyBKv+q2_iBv@rB2Y5 ziLqTj3p3X><*ev3r7!xunJJ@Q49G2EE+1q!#`1+rfwMgmBj(v0Ud=|CQZQ!zg6Aa&&aj=O@ zD*=ut)Wp(DoQv?06xr$X6E7$_zo!B0FZl&Ph(#wd2q>TuHyoA1jnDN0t@tKIyX==^|& zbP&Tk(@=zHLUU`_eYUgI90ltrQ}n&ExgEC|T{DA)a0zGmM2U|619I4JHd!pq`Du_v zfwgiqbu`%!rPe{NS)49VD%cX3l zmBgmWG%W5%uNZAi2FnFPTz}Iz#oBpi6Zm4+99%SZdIyG#jBblh*+%~Qp4Chabe0W2 zO6)XQ^*dn0mhkXUwW`qj={_x)C>gc##pcJY@~dpPsH=39Q8o5DK|rH0Fu&pDolVVc zI4IlGsyop6OiTNAt@9%0LEC}zOwO>oW_Svt$ISgu?k?MicQCLaMJz$*uUC%76W@*M zZozZa4!~eSQgA|5L`|77y@sUI|E^^l6+lJ~jW=M100{K-F6pUg%-JekbJ_I6bScIq z!twW$bl=5(t~-7m|2cZY4;z<;$|(n(Jn`zxV{j>=Cr0cBR z{!?9aGbPyr6Z11ODqF&ogp$6#%?GP&w_tTCRIFm6TzPzZ7i|fw2Bk`&=G64Vvo52M zPuMQ0Mxhs$K*GT%+!xEnUGjUtpqu?~_J_(-lIm-NBMMpn2M(BQftw=uEscbOFoZko z8Wo+h@h{OtG6_UxI!zkUPLge#dT?PfijL32?n*#&zIhe}ATIDEaDyq$$Kg)mw+Tk;^I0+?sid|J0QR9d% ztTAVK%#GMy_;~;{uGz6q=%5U7CgC2l7mP?2`>%i7C!$T|))toh%sPH3DCQ{Vst-kE zna~+CgHjhv2<2gSFa{4cL?a}T?D7XeJE2jQMLiTJO#jlAJ(lD8J_|6NN?bhHw0&ij zv}>%SoYLSeXll_w2YtJYV7k`68hRV)Rc)P}9zHR-X#uE)L= z&Pe>xSkUD21_r%SRpxSRW+#7mqfBde;~m%+YzbwpA!-U?IfjS-1)Q`Rxai zMs%W)(@+E@DMsFt$OG3(q2&noYq4O(f=BW9HIBO z;9>E$5aRR@yI(y3>UoK^I%2B~egFmt)gA%fL~7*vrOowUu@mfZW7E5v1iUZnwnM%C z{7Rb`(Usm6cy{NI3TDTWc@KmdQvVd86)%?<~J|G%6C)#=0^PXD&a zzbz;m_h!-&T%oS z2mGb16D9S_&mUCem0W0t`KcJp{vYNmGqt(DsKU3}6YH(i(o=CDzd_FRMPb_K-VbYk z4!aZnqXm~Y#;dbm1qvBwEHTL4bR?BAD9GYfDWZk$30soFunV!3etMNfbvgCMnd(a4 z&W^ueooV zT;SA5_OspX^NF+Bncz9G1yY;9+YR4hx@Y)8-DivAdl=4*?p~mq>KU1n;Of$3jaV?a zR`NU!TY`&!-!Ud82znn82_P82r-N+{GJ29v{RVk6<+6ck z0TWa72GK+nO2w)tH~GjwrLj8!*<9Yd1DL=TfYl&KGnEr?edr6xviENOIM<`0`WO#Q z6!Ry1g`Aqdm`{aSHFrs{s41z|PiRvW#9MOcV z+B+~_e_~v~JR^%gxs*7+oEG3AzvnaR=QhDhXU=}V+r~QZr`O{WuMBo??RTK0YKNYG z9nQ@bZ7$kh{m(nhh6CVj4(DEo>sCx2Lm*HoEH+h||L~LIaz}d_r@J)7%P|sJxoWlU z2nQcVJomK|*YxJD%2}6BFT}-B^rVPoNC2Z{@Km=No)4AyM24xdGg26$1QE$kX1KAO zNYa+>(FJ^mR-F|c=!xV9?0fc!yT2ByJiSAZgq zIs^9gPoZQ5^$c$E&Pw!0MdTLOS9S7bO0w`g9RMkI?*W40ChK5V4y`vn#G!J1HNGHM z*lKz2&Ka;$jUUC2v`b2)C0sc}yS?Jmr3F3VZVzQ`0h76i{eSY61>Yt8xasBdeQ2lC zTMLJAbzsR8vo(O`p|Oki%kb+`G3|I;^%-!%<&X}R@1jRko$bz<8cX~8N-guv$h}RD z+u3jKVdlK^4wMc^gN2Mo!^udGfN#NJSriF`h?z5R9;+%dr_-Ux|2Je=GXv$CDGXXj zTZjvNyco%ZOqUSb=7U{h-!hNG!T-zdg_Rj4V0k{`>O23D_FCNrtWe5a%i@;TlXB?` zh>dqMD7u?~QeAKM?W-Q6u|?OMr3VI0nlNLadR*)i8$fbMebh^)J~F6!%PxF}#`$x4 zTKuiOX)BkghKDk#ZhaGL)VaeGik(y`?&#rDPAG!Q=x=)57d+nG&>8qmc`2W;KODyN&Fw0@LRxeCK)-+E7lah2W|44IoC!iQZwTxQ~<-hX9mGFO7fjo z0oVyWq&7oR5WH@rId9D`+Qz^}bl2HyKwrI+pRoGe)`(xOlRjxcjWaklwoh6VR!qV& zfAyxh%nMRA^00j1m3w|9w{U@wXm+JwJtYp(JiNjD%!&(!vev{a@w5qf!gobwnt<_y{xqW25 zHqr^>?7=)vy`m()oYkh6?JM=7EG(bJ@lKw3^`}<l6ssDe5~HbJof1s9NSgOAF&H_$VpX(V;~ic4cb0PlsHm^r910^E zq0cD>Lpm3wr@=mp@$ROfPlK*J$(-vtZXR%%*_`j(l3L``jG%_Kg$z&8ZXUt5<#KAp zOUBx+g}If$l6A-fXS<`gMhs3x()okxg6e`PiF>Erf1sb8{s1yzy>V{0?4W8hhta?8 zd}CKTSgiDzE&DU9fl5nJj&Zxz$0O3y!);~z;KF0KWRHmX6x7v6h&dS*!AxmxvZ&XL z^O>;cMktqKU{MoI<_J^!D9hS~MqU5+R~j{k?$szKN-7&64;I&|vZ9&Zk8K!&6!;5q zFT>NO+?=6qgwH4H{6oo@z1Kc)TF%1Ntz%PfjK+SO#*qS&;tus$Ik9*w!NLMEBoH3O zU+)9bEEGWhsn1wwpf4QcU-MXKjWUo?iyix+wW`! zG$&=OvS5<*6+IB$=b#|RPT*qf^^{EVpL;#ZFA0QRd1qaK12XHV@z^UVU?lz+0W-O9V`~bi_JtD$*y1Be4r^;;5U+z z{nSRz(t-gbVOoHi_hXkQ0{pch68))zD>&yl_y3l*EgrDH**dF%NQ)&zj9tHB`Z9i) z!C&mYPyJ<+>dy2@4>nHPh?G!~?bZWo^!6i*p4?9xztGKi>q_+P#`kzEk5

yYL4A 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 Fjlf+~Jn#Sj literal 0 HcmV?d00001 From 101775b5ea4766b094fca295e384a7adf1adc406 Mon Sep 17 00:00:00 2001 From: Kaelyn Ferris <43348706+kaelynj@users.noreply.github.com> Date: Thu, 10 Sep 2026 12:11:48 -0400 Subject: [PATCH 08/15] Fix latex rendering and toc --- docs/addons/qiskit-noise-learning/_toc.json | 42 ++++++++++++++- .../guides/formalism.mdx | 54 +++++++++---------- docs/addons/qiskit-noise-learning/prf-prf.mdx | 15 ------ 3 files changed, 68 insertions(+), 43 deletions(-) delete mode 100644 docs/addons/qiskit-noise-learning/prf-prf.mdx diff --git a/docs/addons/qiskit-noise-learning/_toc.json b/docs/addons/qiskit-noise-learning/_toc.json index 86b894972a55..37e71f5b9c83 100644 --- a/docs/addons/qiskit-noise-learning/_toc.json +++ b/docs/addons/qiskit-noise-learning/_toc.json @@ -6,8 +6,48 @@ "children": [ { "title": "", - "children": [], + "children": [ + { + "title": "Documentation home", + "url": "/docs/addons/qiskit-noise-learning" + }, + { + "title": "Installation instructions", + "url": "/docs/addons/qiskit-noise-learning/install" + }, + { + "title": "Guides", + "children": [ + { + "title": "Mathematical formalism", + "url": "/docs/addons/qiskit-noise-learning/guides/formalism" + }, + { + "title": "Build a learning experiment", + "url": "/docs/addons/qiskit-noise-learning/guides/workflow" + }, + { + "title": "Learn the noise model of a gate with NoiseLearner", + "url": "/docs/addons/qiskit-noise-learning/guides/noise-learner" + } + ] + }, + { + "title": "GitHub", + "url": "https://github.com/Qiskit/qiskit-noise-learning" + } + ], "collapsible": false + }, + { + "title": "API reference", + "collapsible": false, + "children": [ + { + "title": "Python API reference", + "url": "/docs/api/qiskit-noise-learning" + } + ] } ] } diff --git a/docs/addons/qiskit-noise-learning/guides/formalism.mdx b/docs/addons/qiskit-noise-learning/guides/formalism.mdx index eb8ba2243943..96a57b1a12d6 100644 --- a/docs/addons/qiskit-noise-learning/guides/formalism.mdx +++ b/docs/addons/qiskit-noise-learning/guides/formalism.mdx @@ -19,23 +19,23 @@ The following is a review of some core mathematical concepts from the literature ### 1.1 Notation -For $K \in \mathbb{N}$, let $[K] = \{0, 1, \dots, K - 1\}$. For a finite set $S \subset \mathbb{N}$ of qubit indices, let $\P^S$ denote the set of *unphased* Pauli operators acting on those qubits. Note that we think of elements of $\P^S$ as functions mapping $S \rightarrow \{I, X, Y, Z\}$, so that for any $P \in \P^S$ and $T \subseteq S$, $P|_T$ denotes the restriction of $P$ to the qubit subset $T$. Along these lines, for disjoint sets $S, T$, and $P \in \P^S$ and $Q \in \P^T$, $P \otimes Q$ denotes the element of $\P^{S \cup T}$ such that $P \otimes Q |_S = P$ and $P \otimes Q |_T = Q$. This notation is helpful to avoid explicitly dealing with subsystem orderings, and to make it easy to describe restrictions. +For $K \in \mathbb{N}$, let $[K] = \{0, 1, \dots, K - 1\}$. For a finite set $S \subset \mathbb{N}$ of qubit indices, let $\mathcal{P}^S$ denote the set of *unphased* Pauli operators acting on those qubits. Note that we think of elements of $\mathcal{P}^S$ as functions mapping $S \rightarrow \{I, X, Y, Z\}$, so that for any $P \in \mathcal{P}^S$ and $T \subseteq S$, $P|_T$ denotes the restriction of $P$ to the qubit subset $T$. Along these lines, for disjoint sets $S, T$, and $P \in \mathcal{P}^S$ and $Q \in \mathcal{P}^T$, $P \otimes Q$ denotes the element of $\mathcal{P}^{S \cup T}$ such that $P \otimes Q |_S = P$ and $P \otimes Q |_T = Q$. This notation is helpful to avoid explicitly dealing with subsystem orderings, and to make it easy to describe restrictions. -For finite subsets $M \subset \mathbb{N}$, we denote $\Z_2^M$ as the set of the bit strings whose elements are indexed by $M$. Similarly to the above, we think of elements as functions mapping $M \rightarrow \Z_2$, so that we may easily describe substrings in terms of restrictions of the index set. +For finite subsets $M \subset \mathbb{N}$, we denote $\mathbb{Z}_2^M$ as the set of the bit strings whose elements are indexed by $M$. Similarly to the above, we think of elements as functions mapping $M \rightarrow \mathbb{Z}_2$, so that we may easily describe substrings in terms of restrictions of the index set. -Lastly, for a matrix $X$, we use $\opket{X}$ to denote its vectorization. Based on the limited way in which we use this notation, it is not actually necessary to choose a specific vectorization convention. For a classical bit string $m$, we use the shorthand $\opket{m} = \opket{\ket{m}\bra{m}}$. +Lastly, for a matrix $X$, we use $| X \rangle\!\rangle$ to denote its vectorization. Based on the limited way in which we use this notation, it is not actually necessary to choose a specific vectorization convention. For a classical bit string $m$, we use the shorthand $| m \rangle\!\rangle = | | m \rangle\langle m | \rangle\!\rangle$. ### 1.2 Quantum instruments -A quantum operation producing classical bits $m \in \Z_2^M$ (for example, the result of measurement) is generally modeled as a linear map of the form: +A quantum operation producing classical bits $m \in \mathbb{Z}_2^M$ (for example, the result of measurement) is generally modeled as a linear map of the form: $$ - \rho \mapsto \sum_{m \in \Z_2^M} \E_m(\rho) \otimes \ket{m}\bra{m}, + \rho \mapsto \sum_{m \in \mathbb{Z}_2^M} \mathcal{E}_m(\rho) \otimes | m \rangle\langle m |, $$ -where the set $\{\E_m: m \in \Z_2^M\}$ are completely positive, and $\sum_m \E_m$ is trace-preserving. A set of completely positive maps $\{\E_m\}$ satisfying these properties is called a *quantum instrument*. A unitary gate is a special case of an instrument with only one element that is a unitary operation. +where the set $\{\mathcal{E}_m: m \in \mathbb{Z}_2^M\}$ are completely positive, and $\sum_m \mathcal{E}_m$ is trace-preserving. A set of completely positive maps $\{\mathcal{E}_m\}$ satisfying these properties is called a *quantum instrument*. A unitary gate is a special case of an instrument with only one element that is a unitary operation. @@ -49,10 +49,10 @@ The formalism utilized in this package assumes every gate in the gate set to be This is a general class of operations that includes unitary Clifford gates, measurement, state preparation, and any combination of the above. Note that we assume measurement and reset are always along the $Z$-axis for each qubit. While this is not strictly required, it is a common feature of many quantum computing modalities, and enables simplified representations and analysis. -As outlined in [\[1\]](#references), [\[7\]](#references) for the no-reset case, if a specific twirling strategy is applied to a noisy instance of such a gate, then the action of the resulting operation can be modeled mathematically as a *uniform Pauli instrument*. That is, within the quantum instrument notation, $\E_m = \U_mG$, where $G$ is the Clifford unitary, and: +As outlined in [\[1\]](#references), [\[7\]](#references) for the no-reset case, if a specific twirling strategy is applied to a noisy instance of such a gate, then the action of the resulting operation can be modeled mathematically as a *uniform Pauli instrument*. That is, within the quantum instrument notation, $\mathcal{E}_m = \mathcal{U}_mG$, where $G$ is the Clifford unitary, and: $$ - \U_m = \sum_{a,b \in \Z_2^M} \Lambda_{a,b} \otimes \opket{m + a}\opbra{m + b}, + \mathcal{U}_m = \sum_{a,b \in \mathbb{Z}_2^M} \Lambda_{a,b} \otimes | m + a \rangle\!\rangle \langle\!\langle m + b |, $$ where each $\Lambda_{a,b}$ is a sub-normalized Pauli channel on the unmeasured qubits $N = [K] \setminus M$. It is implied by this being a quantum instrument that $\sum_{a,b} \Lambda_{a,b}$ is also trace-preserving. Some notes: @@ -60,15 +60,15 @@ where each $\Lambda_{a,b}$ is a sub-normalized Pauli channel on the unmeasured q * The initial untwirled noise is modeled to include both “quantum” and “classical” errors: erroneous operations on the quantum registers, as well as mistakes in the measurement value reporting. * The noise map $\Lambda_{a,b}$ is *independent* of the measurement outcome $m$. -In words, a single term in the above sum represents observing a measurement outcome of $m$ when the measured state was $\ket{m + b}$ (a misclassification if $b \neq 0$), and when the output state on the measurement register is $\ket{m + a}$ (the “wrong” state when $a \neq 0$). The map $\Lambda_{a,b}$ simultaneously encodes the action on the unmeasured qubits (conditioned on the measurement behavior) and the *probability* of the specific measurement behavior (through the normalization). +In words, a single term in the above sum represents observing a measurement outcome of $m$ when the measured state was $| m + b \rangle$ (a misclassification if $b \neq 0$), and when the output state on the measurement register is $| m + a \rangle$ (the “wrong” state when $a \neq 0$). The map $\Lambda_{a,b}$ simultaneously encodes the action on the unmeasured qubits (conditioned on the measurement behavior) and the *probability* of the specific measurement behavior (through the normalization). Note that we are not concerned here with the specifics of the twirling strategy: that such a strategy exists to put the channel into the above form is enough. Note that “finer” twirling strategies exist which can further restrict the form of the Pauli channels [\[2\]](#references); however, we take the above form as the most general mathematical representation under consideration. -In Lemma 1 of [\[7\]](#references), it is shown that $\E_m = \U_mG$ can be rewritten as: +In Lemma 1 of [\[7\]](#references), it is shown that $\mathcal{E}_m = \mathcal{U}_mG$ can be rewritten as: $$ - \E_m = \frac{1}{2^{2|M| + |N|}}\sum_{x, y \in \Z_2^M, Q \in \P^N} (-1)^{m \cdot (x + y)} -\lambda^Q_{x, y}\opket{Q \otimes Z^y}\opbra{G^\dagger(Q \otimes Z^x)}. + \mathcal{E}_m = \frac{1}{2^{2|M| + |N|}}\sum_{x, y \in \mathbb{Z}_2^M, Q \in \mathcal{P}^N} (-1)^{m \cdot (x + y)} +\lambda^Q_{x, y}| Q \otimes Z^y \rangle\!\rangle \langle\!\langle G^\dagger(Q \otimes Z^x) |. $$ for some real numbers $\lambda_{x,y}^Q$, which are called the *fidelities* of the instrument. @@ -76,7 +76,7 @@ for some real numbers $\lambda_{x,y}^Q$, which are called the *fidelities* of th Adding reset to this picture is relatively straightforward. A noisy reset operation on qubits $R \subset [K]$ can be modeled according to the decomposition: $$ - \frac{1}{2^{|R|}}\sum_{r \in \Z_2^{R}} \lambda_r \opket{Z^r}\opbra{I_R}. + \frac{1}{2^{|R|}}\sum_{r \in \mathbb{Z}_2^{R}} \lambda_r | Z^r \rangle\!\rangle \langle\!\langle I_R |. $$ The above form explicitly utilizes the assumption that the reset is along the $Z$-axis for each qubit. Noise in the operation is encoded in the reset fidelities $\lambda_r$, which are simply indexed by qubit subsets. @@ -84,9 +84,9 @@ The above form explicitly utilizes the assumption that the reset is along the $Z An analog to Equation [(1)](#equation-clifford-mcm-form) that includes a reset operation at the end can be attained by simply composing it with Equation [(2)](#equation-reset-form). This composition, after some simplification, yields: $$ -\begin{split} \frac{1}{2^{2|M|+|N|}} \sum_{\substack{x \in \Z_2^M, y \in \Z_2^{M \cup R} \\ Q \in -\P^{N\setminus R}}} (-1)^{m \cdot (x + y|_M)} \lambda^Q_{x,y} \opket{Q \otimes -Z^y}\opbra{G^\dagger(Q \otimes I_{N \cap R} \otimes Z^x)}. \end{split} +\begin{split} \frac{1}{2^{2|M|+|N|}} \sum_{\substack{x \in \mathbb{Z}_2^M, y \in \mathbb{Z}_2^{M \cup R} \\ Q \in +\mathcal{P}^{N\setminus R}}} (-1)^{m \cdot (x + y|_M)} \lambda^Q_{x,y} | Q \otimes +Z^y \rangle\!\rangle \langle\!\langle G^\dagger(Q \otimes I_{N \cap R} \otimes Z^x) |. \end{split} $$ This decomposition indicates that the number of fidelities $\lambda^Q_{x, y}$ is @@ -112,24 +112,24 @@ While the tracking of a single Pauli operator through the circuit may be intuiti - For any $x \in \Z_2^M$, $y \in \Z_2^{M \cup R}$, and $Q\in \P^{N \setminus R}$, it holds that: + For any $x \in \mathbb{Z}_2^M$, $y \in \mathbb{Z}_2^{M \cup R}$, and $Q\in \mathcal{P}^{N \setminus R}$, it holds that: $$ -\opbra{Q \otimes Z^y}\otimes \opbra{Z^{x + y|_M}}_M \left(\sum_{m\in \Z_2^M} \E_m \otimes \opket{m}\right) -= \lambda_{x,y}^Q\opbra{G^\dagger(Q \otimes I_{N \cap R} \otimes Z^x)} +\langle\!\langle Q \otimes Z^y |\otimes \langle\!\langle Z^{x + y|_M} |_M \left(\sum_{m\in \mathbb{Z}_2^M} \mathcal{E}_m \otimes | m \rangle\!\rangle\right) += \lambda_{x,y}^Q\langle\!\langle G^\dagger(Q \otimes I_{N \cap R} \otimes Z^x) | $$ In other words, if we compute the expectation value $Z^{x + y|_M}$ on the classical register output by the MCM, then the “Heisenberg picture” evolution of an observable through the Clifford-MCM-reset gate maps $Q \otimes Z^y \rightarrow Q \otimes I_{N \cap R} \otimes Z^x$. This fact alone enables recovery of PTG-like analysis beyond the unitary gate set case: with a particular post-processing of the measurement results, even gates with measurements and resets can be viewed as deterministically mapping one Pauli operator to another. -Before proving this, we write Equation [(3)](#equation-clifford-mcm-reset-form) in a more suggestive way. Note that for $x, y \in \Z_2^M$, it holds that $Z^{x+y} = \sum_{m \in \Z_2^M} (-1)^{m \cdot (x + y)}\ket{m}\bra{m}$, and as such (in super operator notation) we have: +Before proving this, we write Equation [(3)](#equation-clifford-mcm-reset-form) in a more suggestive way. Note that for $x, y \in \mathbb{Z}_2^M$, it holds that $Z^{x+y} = \sum_{m \in \mathbb{Z}_2^M} (-1)^{m \cdot (x + y)} | m \rangle\langle m |$, and as such (in super operator notation) we have: $$ -\begin{split} \begin{aligned} \sum_{m \in \Z_2^M} \E_m \otimes \opket{m}_M = \frac{1}{2^{2|M|+|N|}}\sum_{\substack{x \in -\Z_2^M, y \in \Z_2^{M \cup R} \\ Q \in \P^{N\setminus R}}} \lambda^Q_{x,y} \opket{Q \otimes Z^y} -\opbra{G^\dagger(Q \otimes I_{N \cap R} \otimes Z^x)} \otimes \opket{Z^{x + y|_M}}_M, \end{aligned} \end{split} +\begin{split} \begin{aligned} \sum_{m \in \mathbb{Z}_2^M} \mathcal{E}_m \otimes | m \rangle\!\rangle_M = \frac{1}{2^{2|M|+|N|}}\sum_{\substack{x \in +\mathbb{Z}_2^M, y \in \mathbb{Z}_2^{M \cup R} \\ Q \in \mathcal{P}^{N\setminus R}}} \lambda^Q_{x,y} | Q \otimes Z^y \rangle\!\rangle +\langle\!\langle G^\dagger(Q \otimes I_{N \cap R} \otimes Z^x) | \otimes | Z^{x + y|_M} \rangle\!\rangle_M, \end{aligned} \end{split} $$ where we have applied Equation [(3)](#equation-clifford-mcm-reset-form) and collected terms, and we use the subscript $M$ to indicate the classical measurement result register, which we treat above in a similar notation to the quantum registers. @@ -140,14 +140,14 @@ where we have applied Equation [(3)](#equation-clifford-mcm-reset-form) and coll $$ \begin{split} \begin{aligned} -&\opbra{Q \otimes Z^y} \otimes \opbra{Z^{x + y|_M}} \left(\sum_{m\in \Z_2^M} \E_m \otimes \opket{m}\right)\\ -&= \opbra{Q \otimes Z^y} \otimes \opbra{Z^{x + y|_M}} \left( \frac{1}{2^{2|M|+|N|}} \sum_{\substack{a \in \Z_2^M, b \in \Z_2^{M \cup R} \\ P \in \P^{N\setminus R}}} \lambda^P_{a,b} \opket{P \otimes Z^b}\opbra{G^\dagger(P \otimes I_{N \cap R} \otimes Z^a)} \otimes \opket{Z^{a + b|_M}} \right) \\ -&=\frac{1}{2^{2|M| + |N|}}\sum_{\substack{a \in \Z_2^M, b \in \Z_2^{M \cup R} \\ P \in \P^{N \setminus R}}} \lambda^P_{a, b}\underbrace{\ip{Q \otimes Z^y}{P \otimes Z^b}}_{2^{|M| + |N|} \delta_{P, Q}\delta_{y,b}} \underbrace{\ip{Z^{x + y|_M}}{Z^{a + b|_M}}}_{2^{|M|}\delta_{x+y|_M,a+b|_M}}\opbra{G^\dagger(P \otimes I_{N \cap R} \otimes Z^a)} +&\langle\!\langle Q \otimes Z^y | \otimes \langle\!\langle Z^{x + y|_M} | \left(\sum_{m\in \mathbb{Z}_2^M} \mathcal{E}_m \otimes | m \rangle\!\rangle\right)\\ +&= \langle\!\langle Q \otimes Z^y | \otimes \langle\!\langle Z^{x + y|_M} | \left( \frac{1}{2^{2|M|+|N|}} \sum_{\substack{a \in \mathbb{Z}_2^M, b \in \mathbb{Z}_2^{M \cup R} \\ P \in \mathcal{P}^{N\setminus R}}} \lambda^P_{a,b} | P \otimes Z^b \rangle\!\rangle \langle\!\langle G^\dagger(P \otimes I_{N \cap R} \otimes Z^a) | \otimes | Z^{a + b|_M} \rangle\!\rangle \right) \\ +&=\frac{1}{2^{2|M| + |N|}}\sum_{\substack{a \in \mathbb{Z}_2^M, b \in \mathbb{Z}_2^{M \cup R} \\ P \in \mathcal{P}^{N \setminus R}}} \lambda^P_{a, b}\underbrace{\langle Q \otimes Z^y, P \otimes Z^b \rangle}_{2^{|M| + |N|} \delta_{P, Q}\delta_{y,b}} \underbrace{\langle Z^{x + y|_M}, Z^{a + b|_M} \rangle}_{2^{|M|}\delta_{x+y|_M,a+b|_M}}\langle\!\langle G^\dagger(P \otimes I_{N \cap R} \otimes Z^a) | \end{aligned} \end{split} $$ - Lastly, observe that $\delta_{y,b}\delta_{x+y|_M,a+b|_M} = \delta_{y,b}\delta_{x,a}$, and hence the final term above collapses down to the single term $\lambda^Q_{x,y} \opbra{G^\dagger(Q \otimes I_{N \cap R} \otimes Z^x)}$, yielding the desired result. + Lastly, observe that $\delta_{y,b}\delta_{x+y|_M,a+b|_M} = \delta_{y,b}\delta_{x,a}$, and hence the final term above collapses down to the single term $\lambda^Q_{x,y} \langle\!\langle G^\dagger(Q \otimes I_{N \cap R} \otimes Z^x) |$, yielding the desired result. See [\[7\]](#references) for development beyond this point: the definition of the PTG, paths through the PTG, and the proof that any properly-defined path corresponds to an experiment. diff --git a/docs/addons/qiskit-noise-learning/prf-prf.mdx b/docs/addons/qiskit-noise-learning/prf-prf.mdx deleted file mode 100644 index 68be72144511..000000000000 --- a/docs/addons/qiskit-noise-learning/prf-prf.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: "Proof Index" -description: "Proof Index for the latest version of Qiskit noise learning" ---- - -# Proof Index - -[**prop-mcm-evolution**](#cap-prop-mcm-evolution) - -| | | | -| - | -------------------------------------------------------------------------------- | ------------- | -| |   | | -| | **prop-mcm-evolution** | | -| | [`prop-mcm-evolution`](guides/formalism#prop-mcm-evolution) *(guides/formalism)* | *proposition* | - From 6038f525a3e3667b047c0fe0d022d162b1585f1b Mon Sep 17 00:00:00 2001 From: Kaelyn Ferris <43348706+kaelynj@users.noreply.github.com> Date: Thu, 10 Sep 2026 12:17:42 -0400 Subject: [PATCH 09/15] Fix API ref generation by looking for nested refs in sphinx --- scripts/js/lib/api/apiDocsPipeline.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/scripts/js/lib/api/apiDocsPipeline.ts b/scripts/js/lib/api/apiDocsPipeline.ts index 7538fcd04a44..8b5c26aee11a 100644 --- a/scripts/js/lib/api/apiDocsPipeline.ts +++ b/scripts/js/lib/api/apiDocsPipeline.ts @@ -85,8 +85,8 @@ async function determineFilePaths( : ObjectsInv.fromFile(htmlPath, pkg.language)); const extraFiles = pkg.isCApi() - ? [`${C_API_BASE_PATH}/**.html`, "apidocs/**.html"] - : ["apidocs/**.html", "apidoc/**.html", "stubs/**.html", "pydoc/**.html"]; + ? [`${C_API_BASE_PATH}/**.html`, "apidocs/**/**.html"] + : ["apidocs/**/**.html", "apidoc/**/**.html", "stubs/**/**.html", "pydoc/**/**.html"]; const files = await globby( [...extraFiles, "release_notes.html", "release-notes.html"], { From 0bf8215ac3ba7c73b0b9d668591222c3a489d03e Mon Sep 17 00:00:00 2001 From: Kaelyn Ferris <43348706+kaelynj@users.noreply.github.com> Date: Thu, 10 Sep 2026 12:18:57 -0400 Subject: [PATCH 10/15] Regenerate API docs --- docs/api/qiskit-noise-learning/_toc.json | 499 +++++++++++++++++- .../qiskit-noise-learning/aer-executor.mdx | 14 +- docs/api/qiskit-noise-learning/analysis.mdx | 34 +- .../circuit-generator.mdx | 8 +- docs/api/qiskit-noise-learning/data.mdx | 14 +- .../experiment-builder.mdx | 36 +- docs/api/qiskit-noise-learning/gate-sets.mdx | 16 +- .../generated/aer-executor-aer-executor.mdx | 81 +++ .../aer-executor-aer-runtime-job.mdx | 71 +++ .../aer-executor-inline-samplexes.mdx | 28 + .../generated/analysis-analysis-pipeline.mdx | 69 +++ .../generated/analysis-analysis-stage.mdx | 75 +++ .../analysis-average-observables.mdx | 48 ++ .../analysis-compute-observables.mdx | 50 ++ .../analysis-curve-fit-observables.mdx | 56 ++ .../generated/analysis-fit.mdx | 183 +++++++ .../generated/analysis-flip-post-select.mdx | 60 +++ .../generated/analysis-legacy-solve.mdx | 45 ++ .../generated/analysis-linear-system-data.mdx | 89 ++++ .../generated/analysis-lsq-linear-solve.mdx | 42 ++ .../generated/analysis-nnls-solve.mdx | 42 ++ .../analysis-positivity-min-solve.mdx | 111 ++++ .../analysis-symmetrize-fidelities.mdx | 43 ++ .../analysis-symmetrize-generators.mdx | 43 ++ .../generated/analysis-zero-post-select.mdx | 63 +++ ...t-generator-executor-circuit-generator.mdx | 102 ++++ ...circuit-generator-executor-data-mapper.mdx | 120 +++++ .../data-aggregated-observable-data.mdx | 109 ++++ .../generated/data-leveled-data.mdx | 28 + .../generated/data-model-data.mdx | 82 +++ .../generated/data-observable-data.mdx | 124 +++++ .../generated/data-raw-data.mdx | 121 +++++ ...ment-builder-add-instruction-sequences.mdx | 45 ++ .../experiment-builder-add-paths.mdx | 44 ++ ...xperiment-builder-bind-fragment-depths.mdx | 42 ++ .../experiment-builder-complete-sequences.mdx | 38 ++ .../experiment-builder-depth-1-paths.mdx | 55 ++ .../experiment-builder-even-depth-paths.mdx | 58 ++ ...iment-builder-even-depth-vanilla-paths.mdx | 57 ++ ...iment-builder-experiment-builder-stage.mdx | 65 +++ .../experiment-builder-experiment-builder.mdx | 67 +++ .../experiment-builder-experiment.mdx | 168 ++++++ ...builder-generate-instruction-sequences.mdx | 44 ++ .../experiment-builder-identify-relations.mdx | 42 ++ ...nt-builder-merge-instruction-sequences.mdx | 42 ++ .../experiment-builder-rank-reduce-paths.mdx | 42 ++ .../experiment-builder-spam-paths.mdx | 42 ++ ...-builder-vanilla-instruction-sequences.mdx | 58 ++ .../generated/gate-sets-gate-set.mdx | 150 ++++++ .../generated/gate-sets-gate.mdx | 171 ++++++ .../generated/gate-sets-model-gate-set.mdx | 72 +++ .../generated/gate-sets-model-gate.mdx | 124 +++++ .../generated/gate-sets-qiskit-gate-set.mdx | 256 +++++++++ .../generated/gate-sets-qiskit-gate.mdx | 131 +++++ .../generated/math-composed-linear-map.mdx | 81 +++ .../math-enumerated-indexed-space.mdx | 48 ++ .../generated/math-indexed-matrix.mdx | 160 ++++++ .../generated/math-indexed-space.mdx | 44 ++ .../generated/math-indexed-vector.mdx | 53 ++ .../generated/math-linear-map.mdx | 122 +++++ .../models-contains-pauli-lindblad-model.mdx | 24 + .../generated/models-generator-index.mdx | 30 ++ .../generated/models-get-noise-site.mdx | 24 + .../models-identity-fidelity-model.mdx | 71 +++ .../generated/models-is-fidelity-model.mdx | 24 + .../generated/models-log-fidelity-space.mdx | 59 +++ .../generated/models-pauli-lindblad-model.mdx | 194 +++++++ .../generated/models-pauli-lindblad-split.mdx | 70 +++ .../generated/models-rate-space.mdx | 57 ++ .../models-split-pauli-lindblad-model.mdx | 28 + .../noise-learner-learning-options.mdx | 133 +++++ .../noise-learner-noise-learner-job.mdx | 59 +++ .../noise-learner-noise-learner-result.mdx | 55 ++ .../generated/noise-learner-noise-learner.mdx | 80 +++ .../noise-learner-program-executor.mdx | 49 ++ .../generated/noise-learner-program-job.mdx | 41 ++ .../generated/sequences-apply-gate.mdx | 105 ++++ .../generated/sequences-fidelity-index.mdx | 178 +++++++ ...-group-mergeable-instruction-sequences.mdx | 47 ++ .../sequences-instruction-sequence.mdx | 134 +++++ .../generated/sequences-log-path-map.mdx | 60 +++ .../generated/sequences-log-path-space.mdx | 66 +++ .../sequences-partial-pauli-permutation.mdx | 264 +++++++++ .../generated/sequences-path.mdx | 155 ++++++ ...sualizations-fidelity-index-math-label.mdx | 32 ++ .../visualizations-gate-set-topology.mdx | 35 ++ .../visualizations-path-math-label.mdx | 29 + docs/api/qiskit-noise-learning/math.mdx | 16 +- docs/api/qiskit-noise-learning/models.mdx | 30 +- .../qiskit-noise-learning/noise-learner.mdx | 16 +- docs/api/qiskit-noise-learning/sequences.mdx | 24 +- .../qiskit-noise-learning/visualizations.mdx | 10 +- .../api/qiskit-noise-learning/objects.inv | Bin 6303 -> 7116 bytes 93 files changed, 6895 insertions(+), 131 deletions(-) create mode 100644 docs/api/qiskit-noise-learning/generated/aer-executor-aer-executor.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/aer-executor-aer-runtime-job.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/aer-executor-inline-samplexes.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/analysis-analysis-pipeline.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/analysis-analysis-stage.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/analysis-average-observables.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/analysis-compute-observables.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/analysis-curve-fit-observables.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/analysis-fit.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/analysis-flip-post-select.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/analysis-legacy-solve.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/analysis-linear-system-data.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/analysis-lsq-linear-solve.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/analysis-nnls-solve.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/analysis-positivity-min-solve.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/analysis-symmetrize-fidelities.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/analysis-symmetrize-generators.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/analysis-zero-post-select.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/circuit-generator-executor-circuit-generator.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/circuit-generator-executor-data-mapper.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/data-aggregated-observable-data.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/data-leveled-data.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/data-model-data.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/data-observable-data.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/data-raw-data.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/experiment-builder-add-instruction-sequences.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/experiment-builder-add-paths.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/experiment-builder-bind-fragment-depths.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/experiment-builder-complete-sequences.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/experiment-builder-depth-1-paths.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/experiment-builder-even-depth-paths.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/experiment-builder-even-depth-vanilla-paths.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/experiment-builder-experiment-builder-stage.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/experiment-builder-experiment-builder.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/experiment-builder-experiment.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/experiment-builder-generate-instruction-sequences.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/experiment-builder-identify-relations.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/experiment-builder-merge-instruction-sequences.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/experiment-builder-rank-reduce-paths.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/experiment-builder-spam-paths.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/experiment-builder-vanilla-instruction-sequences.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/gate-sets-gate-set.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/gate-sets-gate.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/gate-sets-model-gate-set.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/gate-sets-model-gate.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/gate-sets-qiskit-gate-set.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/gate-sets-qiskit-gate.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/math-composed-linear-map.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/math-enumerated-indexed-space.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/math-indexed-matrix.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/math-indexed-space.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/math-indexed-vector.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/math-linear-map.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/models-contains-pauli-lindblad-model.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/models-generator-index.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/models-get-noise-site.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/models-identity-fidelity-model.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/models-is-fidelity-model.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/models-log-fidelity-space.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/models-pauli-lindblad-model.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/models-pauli-lindblad-split.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/models-rate-space.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/models-split-pauli-lindblad-model.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/noise-learner-learning-options.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/noise-learner-noise-learner-job.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/noise-learner-noise-learner-result.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/noise-learner-noise-learner.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/noise-learner-program-executor.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/noise-learner-program-job.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/sequences-apply-gate.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/sequences-fidelity-index.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/sequences-group-mergeable-instruction-sequences.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/sequences-instruction-sequence.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/sequences-log-path-map.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/sequences-log-path-space.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/sequences-partial-pauli-permutation.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/sequences-path.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/visualizations-fidelity-index-math-label.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/visualizations-gate-set-topology.mdx create mode 100644 docs/api/qiskit-noise-learning/generated/visualizations-path-math-label.mdx diff --git a/docs/api/qiskit-noise-learning/_toc.json b/docs/api/qiskit-noise-learning/_toc.json index b3bd4911c027..31ec4363280a 100644 --- a/docs/api/qiskit-noise-learning/_toc.json +++ b/docs/api/qiskit-noise-learning/_toc.json @@ -12,58 +12,513 @@ }, { "title": "qiskit_noise_learning.aer_executor", - "url": "/docs/api/qiskit-noise-learning/aer-executor", - "untranslatable": true + "untranslatable": true, + "children": [ + { + "title": "Module overview", + "url": "/docs/api/qiskit-noise-learning/aer-executor" + }, + { + "title": "AerExecutor", + "url": "/docs/api/qiskit-noise-learning/generated/aer-executor-aer-executor", + "untranslatable": true + }, + { + "title": "AerRuntimeJob", + "url": "/docs/api/qiskit-noise-learning/generated/aer-executor-aer-runtime-job", + "untranslatable": true + }, + { + "title": "inline_samplexes", + "url": "/docs/api/qiskit-noise-learning/generated/aer-executor-inline-samplexes", + "untranslatable": true + } + ] }, { "title": "qiskit_noise_learning.analysis", - "url": "/docs/api/qiskit-noise-learning/analysis", - "untranslatable": true + "untranslatable": true, + "children": [ + { + "title": "Module overview", + "url": "/docs/api/qiskit-noise-learning/analysis" + }, + { + "title": "AnalysisPipeline", + "url": "/docs/api/qiskit-noise-learning/generated/analysis-analysis-pipeline", + "untranslatable": true + }, + { + "title": "AnalysisStage", + "url": "/docs/api/qiskit-noise-learning/generated/analysis-analysis-stage", + "untranslatable": true + }, + { + "title": "AverageObservables", + "url": "/docs/api/qiskit-noise-learning/generated/analysis-average-observables", + "untranslatable": true + }, + { + "title": "ComputeObservables", + "url": "/docs/api/qiskit-noise-learning/generated/analysis-compute-observables", + "untranslatable": true + }, + { + "title": "CurveFitObservables", + "url": "/docs/api/qiskit-noise-learning/generated/analysis-curve-fit-observables", + "untranslatable": true + }, + { + "title": "Fit", + "url": "/docs/api/qiskit-noise-learning/generated/analysis-fit", + "untranslatable": true + }, + { + "title": "FlipPostSelect", + "url": "/docs/api/qiskit-noise-learning/generated/analysis-flip-post-select", + "untranslatable": true + }, + { + "title": "LegacySolve", + "url": "/docs/api/qiskit-noise-learning/generated/analysis-legacy-solve", + "untranslatable": true + }, + { + "title": "LinearSystemData", + "url": "/docs/api/qiskit-noise-learning/generated/analysis-linear-system-data", + "untranslatable": true + }, + { + "title": "LSQLinearSolve", + "url": "/docs/api/qiskit-noise-learning/generated/analysis-lsq-linear-solve", + "untranslatable": true + }, + { + "title": "NNLSSolve", + "url": "/docs/api/qiskit-noise-learning/generated/analysis-nnls-solve", + "untranslatable": true + }, + { + "title": "PositivityMinSolve", + "url": "/docs/api/qiskit-noise-learning/generated/analysis-positivity-min-solve", + "untranslatable": true + }, + { + "title": "SymmetrizeFidelities", + "url": "/docs/api/qiskit-noise-learning/generated/analysis-symmetrize-fidelities", + "untranslatable": true + }, + { + "title": "SymmetrizeGenerators", + "url": "/docs/api/qiskit-noise-learning/generated/analysis-symmetrize-generators", + "untranslatable": true + }, + { + "title": "ZeroPostSelect", + "url": "/docs/api/qiskit-noise-learning/generated/analysis-zero-post-select", + "untranslatable": true + } + ] }, { "title": "qiskit_noise_learning.circuit_generator", - "url": "/docs/api/qiskit-noise-learning/circuit-generator", - "untranslatable": true + "untranslatable": true, + "children": [ + { + "title": "Module overview", + "url": "/docs/api/qiskit-noise-learning/circuit-generator" + }, + { + "title": "ExecutorCircuitGenerator", + "url": "/docs/api/qiskit-noise-learning/generated/circuit-generator-executor-circuit-generator", + "untranslatable": true + }, + { + "title": "ExecutorDataMapper", + "url": "/docs/api/qiskit-noise-learning/generated/circuit-generator-executor-data-mapper", + "untranslatable": true + } + ] }, { "title": "qiskit_noise_learning.data", - "url": "/docs/api/qiskit-noise-learning/data", - "untranslatable": true + "untranslatable": true, + "children": [ + { + "title": "Module overview", + "url": "/docs/api/qiskit-noise-learning/data" + }, + { + "title": "AggregatedObservableData", + "url": "/docs/api/qiskit-noise-learning/generated/data-aggregated-observable-data", + "untranslatable": true + }, + { + "title": "LeveledData", + "url": "/docs/api/qiskit-noise-learning/generated/data-leveled-data", + "untranslatable": true + }, + { + "title": "ModelData", + "url": "/docs/api/qiskit-noise-learning/generated/data-model-data", + "untranslatable": true + }, + { + "title": "ObservableData", + "url": "/docs/api/qiskit-noise-learning/generated/data-observable-data", + "untranslatable": true + }, + { + "title": "RawData", + "url": "/docs/api/qiskit-noise-learning/generated/data-raw-data", + "untranslatable": true + } + ] }, { "title": "qiskit_noise_learning.experiment_builder", - "url": "/docs/api/qiskit-noise-learning/experiment-builder", - "untranslatable": true + "untranslatable": true, + "children": [ + { + "title": "Module overview", + "url": "/docs/api/qiskit-noise-learning/experiment-builder" + }, + { + "title": "AddInstructionSequences", + "url": "/docs/api/qiskit-noise-learning/generated/experiment-builder-add-instruction-sequences", + "untranslatable": true + }, + { + "title": "AddPaths", + "url": "/docs/api/qiskit-noise-learning/generated/experiment-builder-add-paths", + "untranslatable": true + }, + { + "title": "BindFragmentDepths", + "url": "/docs/api/qiskit-noise-learning/generated/experiment-builder-bind-fragment-depths", + "untranslatable": true + }, + { + "title": "CompleteSequences", + "url": "/docs/api/qiskit-noise-learning/generated/experiment-builder-complete-sequences", + "untranslatable": true + }, + { + "title": "Depth1Paths", + "url": "/docs/api/qiskit-noise-learning/generated/experiment-builder-depth-1-paths", + "untranslatable": true + }, + { + "title": "EvenDepthPaths", + "url": "/docs/api/qiskit-noise-learning/generated/experiment-builder-even-depth-paths", + "untranslatable": true + }, + { + "title": "EvenDepthVanillaPaths", + "url": "/docs/api/qiskit-noise-learning/generated/experiment-builder-even-depth-vanilla-paths", + "untranslatable": true + }, + { + "title": "Experiment", + "url": "/docs/api/qiskit-noise-learning/generated/experiment-builder-experiment", + "untranslatable": true + }, + { + "title": "ExperimentBuilder", + "url": "/docs/api/qiskit-noise-learning/generated/experiment-builder-experiment-builder", + "untranslatable": true + }, + { + "title": "ExperimentBuilderStage", + "url": "/docs/api/qiskit-noise-learning/generated/experiment-builder-experiment-builder-stage", + "untranslatable": true + }, + { + "title": "GenerateInstructionSequences", + "url": "/docs/api/qiskit-noise-learning/generated/experiment-builder-generate-instruction-sequences", + "untranslatable": true + }, + { + "title": "IdentifyRelations", + "url": "/docs/api/qiskit-noise-learning/generated/experiment-builder-identify-relations", + "untranslatable": true + }, + { + "title": "MergeInstructionSequences", + "url": "/docs/api/qiskit-noise-learning/generated/experiment-builder-merge-instruction-sequences", + "untranslatable": true + }, + { + "title": "RankReducePaths", + "url": "/docs/api/qiskit-noise-learning/generated/experiment-builder-rank-reduce-paths", + "untranslatable": true + }, + { + "title": "SPAMPaths", + "url": "/docs/api/qiskit-noise-learning/generated/experiment-builder-spam-paths", + "untranslatable": true + }, + { + "title": "VanillaInstructionSequences", + "url": "/docs/api/qiskit-noise-learning/generated/experiment-builder-vanilla-instruction-sequences", + "untranslatable": true + } + ] }, { "title": "qiskit_noise_learning.gate_sets", - "url": "/docs/api/qiskit-noise-learning/gate-sets", - "untranslatable": true + "untranslatable": true, + "children": [ + { + "title": "Module overview", + "url": "/docs/api/qiskit-noise-learning/gate-sets" + }, + { + "title": "Gate", + "url": "/docs/api/qiskit-noise-learning/generated/gate-sets-gate", + "untranslatable": true + }, + { + "title": "GateSet", + "url": "/docs/api/qiskit-noise-learning/generated/gate-sets-gate-set", + "untranslatable": true + }, + { + "title": "ModelGate", + "url": "/docs/api/qiskit-noise-learning/generated/gate-sets-model-gate", + "untranslatable": true + }, + { + "title": "ModelGateSet", + "url": "/docs/api/qiskit-noise-learning/generated/gate-sets-model-gate-set", + "untranslatable": true + }, + { + "title": "QiskitGate", + "url": "/docs/api/qiskit-noise-learning/generated/gate-sets-qiskit-gate", + "untranslatable": true + }, + { + "title": "QiskitGateSet", + "url": "/docs/api/qiskit-noise-learning/generated/gate-sets-qiskit-gate-set", + "untranslatable": true + } + ] }, { "title": "qiskit_noise_learning.math", - "url": "/docs/api/qiskit-noise-learning/math", - "untranslatable": true + "untranslatable": true, + "children": [ + { + "title": "Module overview", + "url": "/docs/api/qiskit-noise-learning/math" + }, + { + "title": "ComposedLinearMap", + "url": "/docs/api/qiskit-noise-learning/generated/math-composed-linear-map", + "untranslatable": true + }, + { + "title": "EnumeratedIndexedSpace", + "url": "/docs/api/qiskit-noise-learning/generated/math-enumerated-indexed-space", + "untranslatable": true + }, + { + "title": "IndexedMatrix", + "url": "/docs/api/qiskit-noise-learning/generated/math-indexed-matrix", + "untranslatable": true + }, + { + "title": "IndexedSpace", + "url": "/docs/api/qiskit-noise-learning/generated/math-indexed-space", + "untranslatable": true + }, + { + "title": "IndexedVector", + "url": "/docs/api/qiskit-noise-learning/generated/math-indexed-vector", + "untranslatable": true + }, + { + "title": "LinearMap", + "url": "/docs/api/qiskit-noise-learning/generated/math-linear-map", + "untranslatable": true + } + ] }, { "title": "qiskit_noise_learning.models", - "url": "/docs/api/qiskit-noise-learning/models", - "untranslatable": true + "untranslatable": true, + "children": [ + { + "title": "Module overview", + "url": "/docs/api/qiskit-noise-learning/models" + }, + { + "title": "contains_pauli_lindblad_model", + "url": "/docs/api/qiskit-noise-learning/generated/models-contains-pauli-lindblad-model", + "untranslatable": true + }, + { + "title": "GeneratorIndex", + "url": "/docs/api/qiskit-noise-learning/generated/models-generator-index", + "untranslatable": true + }, + { + "title": "get_noise_site", + "url": "/docs/api/qiskit-noise-learning/generated/models-get-noise-site", + "untranslatable": true + }, + { + "title": "IdentityFidelityModel", + "url": "/docs/api/qiskit-noise-learning/generated/models-identity-fidelity-model", + "untranslatable": true + }, + { + "title": "is_fidelity_model", + "url": "/docs/api/qiskit-noise-learning/generated/models-is-fidelity-model", + "untranslatable": true + }, + { + "title": "LogFidelitySpace", + "url": "/docs/api/qiskit-noise-learning/generated/models-log-fidelity-space", + "untranslatable": true + }, + { + "title": "PauliLindbladModel", + "url": "/docs/api/qiskit-noise-learning/generated/models-pauli-lindblad-model", + "untranslatable": true + }, + { + "title": "PauliLindbladSplit", + "url": "/docs/api/qiskit-noise-learning/generated/models-pauli-lindblad-split", + "untranslatable": true + }, + { + "title": "RateSpace", + "url": "/docs/api/qiskit-noise-learning/generated/models-rate-space", + "untranslatable": true + }, + { + "title": "split_pauli_lindblad_model", + "url": "/docs/api/qiskit-noise-learning/generated/models-split-pauli-lindblad-model", + "untranslatable": true + } + ] }, { "title": "qiskit_noise_learning.noise_learner", - "url": "/docs/api/qiskit-noise-learning/noise-learner", - "untranslatable": true + "untranslatable": true, + "children": [ + { + "title": "Module overview", + "url": "/docs/api/qiskit-noise-learning/noise-learner" + }, + { + "title": "LearningOptions", + "url": "/docs/api/qiskit-noise-learning/generated/noise-learner-learning-options", + "untranslatable": true + }, + { + "title": "NoiseLearner", + "url": "/docs/api/qiskit-noise-learning/generated/noise-learner-noise-learner", + "untranslatable": true + }, + { + "title": "NoiseLearnerJob", + "url": "/docs/api/qiskit-noise-learning/generated/noise-learner-noise-learner-job", + "untranslatable": true + }, + { + "title": "NoiseLearnerResult", + "url": "/docs/api/qiskit-noise-learning/generated/noise-learner-noise-learner-result", + "untranslatable": true + }, + { + "title": "ProgramExecutor", + "url": "/docs/api/qiskit-noise-learning/generated/noise-learner-program-executor", + "untranslatable": true + }, + { + "title": "ProgramJob", + "url": "/docs/api/qiskit-noise-learning/generated/noise-learner-program-job", + "untranslatable": true + } + ] }, { "title": "qiskit_noise_learning.sequences", - "url": "/docs/api/qiskit-noise-learning/sequences", - "untranslatable": true + "untranslatable": true, + "children": [ + { + "title": "Module overview", + "url": "/docs/api/qiskit-noise-learning/sequences" + }, + { + "title": "ApplyGate", + "url": "/docs/api/qiskit-noise-learning/generated/sequences-apply-gate", + "untranslatable": true + }, + { + "title": "FidelityIndex", + "url": "/docs/api/qiskit-noise-learning/generated/sequences-fidelity-index", + "untranslatable": true + }, + { + "title": "group_mergeable_instruction_sequences", + "url": "/docs/api/qiskit-noise-learning/generated/sequences-group-mergeable-instruction-sequences", + "untranslatable": true + }, + { + "title": "InstructionSequence", + "url": "/docs/api/qiskit-noise-learning/generated/sequences-instruction-sequence", + "untranslatable": true + }, + { + "title": "LogPathMap", + "url": "/docs/api/qiskit-noise-learning/generated/sequences-log-path-map", + "untranslatable": true + }, + { + "title": "LogPathSpace", + "url": "/docs/api/qiskit-noise-learning/generated/sequences-log-path-space", + "untranslatable": true + }, + { + "title": "PartialPauliPermutation", + "url": "/docs/api/qiskit-noise-learning/generated/sequences-partial-pauli-permutation", + "untranslatable": true + }, + { + "title": "Path", + "url": "/docs/api/qiskit-noise-learning/generated/sequences-path", + "untranslatable": true + } + ] }, { "title": "qiskit_noise_learning.visualizations", - "url": "/docs/api/qiskit-noise-learning/visualizations", - "untranslatable": true + "untranslatable": true, + "children": [ + { + "title": "Module overview", + "url": "/docs/api/qiskit-noise-learning/visualizations" + }, + { + "title": "fidelity_index_math_label", + "url": "/docs/api/qiskit-noise-learning/generated/visualizations-fidelity-index-math-label", + "untranslatable": true + }, + { + "title": "gate_set_topology", + "url": "/docs/api/qiskit-noise-learning/generated/visualizations-gate-set-topology", + "untranslatable": true + }, + { + "title": "path_math_label", + "url": "/docs/api/qiskit-noise-learning/generated/visualizations-path-math-label", + "untranslatable": true + } + ] } ], "collapsed": true, diff --git a/docs/api/qiskit-noise-learning/aer-executor.mdx b/docs/api/qiskit-noise-learning/aer-executor.mdx index b9922a704770..53df914e0c9b 100644 --- a/docs/api/qiskit-noise-learning/aer-executor.mdx +++ b/docs/api/qiskit-noise-learning/aer-executor.mdx @@ -18,14 +18,14 @@ Aer-based local executor for QuantumProgram objects. ## Classes -| | | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| [`AerExecutor`](generated/aer-executor-aer-executor#qiskit_noise_learning.aer_executor.AerExecutor "qiskit_noise_learning.aer_executor.AerExecutor") | Local Aer-based executor mimicking the IBM Runtime executor interface. | -| [`AerRuntimeJob`](generated/aer-executor-aer-runtime-job#qiskit_noise_learning.aer_executor.AerRuntimeJob "qiskit_noise_learning.aer_executor.AerRuntimeJob") | Job object returned by [`AerExecutor.run()`](generated/aer-executor-aer-executor#qiskit_noise_learning.aer_executor.AerExecutor.run "qiskit_noise_learning.aer_executor.AerExecutor.run"). | +| | | +| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | +| [`AerExecutor`](generated/aer-executor-aer-executor "qiskit_noise_learning.aer_executor.AerExecutor") | Local Aer-based executor mimicking the IBM Runtime executor interface. | +| [`AerRuntimeJob`](generated/aer-executor-aer-runtime-job "qiskit_noise_learning.aer_executor.AerRuntimeJob") | Job object returned by [`AerExecutor.run()`](generated/aer-executor-aer-executor#run "qiskit_noise_learning.aer_executor.AerExecutor.run"). | ## Functions -| | | -| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | -| [`inline_samplexes`](generated/aer-executor-inline-samplexes#qiskit_noise_learning.aer_executor.inline_samplexes "qiskit_noise_learning.aer_executor.inline_samplexes")(program\[, omit, rng]) | Return a new `QuantumProgram` with `SamplexItem`s resolved in-place. | +| | | +| ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| [`inline_samplexes`](generated/aer-executor-inline-samplexes "qiskit_noise_learning.aer_executor.inline_samplexes")(program\[, omit, rng]) | Return a new `QuantumProgram` with `SamplexItem`s resolved in-place. | diff --git a/docs/api/qiskit-noise-learning/analysis.mdx b/docs/api/qiskit-noise-learning/analysis.mdx index e07a2294e0bb..48b5a6425b34 100644 --- a/docs/api/qiskit-noise-learning/analysis.mdx +++ b/docs/api/qiskit-noise-learning/analysis.mdx @@ -18,21 +18,21 @@ Data analysis. ## Classes -| | | -| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`AnalysisPipeline`](generated/analysis-analysis-pipeline#qiskit_noise_learning.analysis.AnalysisPipeline "qiskit_noise_learning.analysis.AnalysisPipeline") | A composite [`AnalysisStage`](generated/analysis-analysis-stage#qiskit_noise_learning.analysis.AnalysisStage "qiskit_noise_learning.analysis.AnalysisStage") that chains stages sequentially. | -| [`AnalysisStage`](generated/analysis-analysis-stage#qiskit_noise_learning.analysis.AnalysisStage "qiskit_noise_learning.analysis.AnalysisStage") | Abstract base for a stage in the analysis pipeline. | -| [`AverageObservables`](generated/analysis-average-observables#qiskit_noise_learning.analysis.AverageObservables "qiskit_noise_learning.analysis.AverageObservables") | Average observables over randomizations for each unbound path and fragment depth pair. | -| [`ComputeObservables`](generated/analysis-compute-observables#qiskit_noise_learning.analysis.ComputeObservables "qiskit_noise_learning.analysis.ComputeObservables") | Compute observable data from raw data. | -| [`CurveFitObservables`](generated/analysis-curve-fit-observables#qiskit_noise_learning.analysis.CurveFitObservables "qiskit_noise_learning.analysis.CurveFitObservables") | Fit observable data to exponential decays of the form `a * f**fragment_depth`, and average any remaining observables over randomizations. | -| [`Fit`](generated/analysis-fit#qiskit_noise_learning.analysis.Fit "qiskit_noise_learning.analysis.Fit") | Container for data at each level of the analysis hierarchy. | -| [`FlipPostSelect`](generated/analysis-flip-post-select#qiskit_noise_learning.analysis.FlipPostSelect "qiskit_noise_learning.analysis.FlipPostSelect") | Apply a mask to raw data based on bit flips across measurement outcomes. | -| [`LegacySolve`](generated/analysis-legacy-solve#qiskit_noise_learning.analysis.LegacySolve "qiskit_noise_learning.analysis.LegacySolve") | Solves for the [`ModelData`](generated/data-model-data#qiskit_noise_learning.data.ModelData "qiskit_noise_learning.data.ModelData") using the legacy pair-fidelity method. | -| [`LinearSystemData`](generated/analysis-linear-system-data#qiskit_noise_learning.analysis.LinearSystemData "qiskit_noise_learning.analysis.LinearSystemData") | The linear system to solve and metadata in raw format. | -| [`LSQLinearSolve`](generated/analysis-lsq-linear-solve#qiskit_noise_learning.analysis.LSQLinearSolve "qiskit_noise_learning.analysis.LSQLinearSolve") | Solves for the [`ModelData`](generated/data-model-data#qiskit_noise_learning.data.ModelData "qiskit_noise_learning.data.ModelData") using SciPy's linear least squares solver. | -| [`NNLSSolve`](generated/analysis-nnls-solve#qiskit_noise_learning.analysis.NNLSSolve "qiskit_noise_learning.analysis.NNLSSolve") | Solves for the [`ModelData`](generated/data-model-data#qiskit_noise_learning.data.ModelData "qiskit_noise_learning.data.ModelData") using SciPy's non-negative least squares solver. | -| [`PositivityMinSolve`](generated/analysis-positivity-min-solve#qiskit_noise_learning.analysis.PositivityMinSolve "qiskit_noise_learning.analysis.PositivityMinSolve") | Solves for the [`ModelData`](generated/data-model-data#qiskit_noise_learning.data.ModelData "qiskit_noise_learning.data.ModelData") while minimizing Pauli-Lindblad rate positivity. | -| [`SymmetrizeFidelities`](generated/analysis-symmetrize-fidelities#qiskit_noise_learning.analysis.SymmetrizeFidelities "qiskit_noise_learning.analysis.SymmetrizeFidelities") | Project generator rates into the fidelity-symmetry null space, gate by gate. | -| [`SymmetrizeGenerators`](generated/analysis-symmetrize-generators#qiskit_noise_learning.analysis.SymmetrizeGenerators "qiskit_noise_learning.analysis.SymmetrizeGenerators") | Project generator rates to satisfy conjugation symmetry, gate by gate. | -| [`ZeroPostSelect`](generated/analysis-zero-post-select#qiskit_noise_learning.analysis.ZeroPostSelect "qiskit_noise_learning.analysis.ZeroPostSelect") | Apply a mask to raw data based on whether bit values are all False. | +| | | +| ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| [`AnalysisPipeline`](generated/analysis-analysis-pipeline "qiskit_noise_learning.analysis.AnalysisPipeline") | A composite [`AnalysisStage`](generated/analysis-analysis-stage "qiskit_noise_learning.analysis.AnalysisStage") that chains stages sequentially. | +| [`AnalysisStage`](generated/analysis-analysis-stage "qiskit_noise_learning.analysis.AnalysisStage") | Abstract base for a stage in the analysis pipeline. | +| [`AverageObservables`](generated/analysis-average-observables "qiskit_noise_learning.analysis.AverageObservables") | Average observables over randomizations for each unbound path and fragment depth pair. | +| [`ComputeObservables`](generated/analysis-compute-observables "qiskit_noise_learning.analysis.ComputeObservables") | Compute observable data from raw data. | +| [`CurveFitObservables`](generated/analysis-curve-fit-observables "qiskit_noise_learning.analysis.CurveFitObservables") | Fit observable data to exponential decays of the form `a * f**fragment_depth`, and average any remaining observables over randomizations. | +| [`Fit`](generated/analysis-fit "qiskit_noise_learning.analysis.Fit") | Container for data at each level of the analysis hierarchy. | +| [`FlipPostSelect`](generated/analysis-flip-post-select "qiskit_noise_learning.analysis.FlipPostSelect") | Apply a mask to raw data based on bit flips across measurement outcomes. | +| [`LegacySolve`](generated/analysis-legacy-solve "qiskit_noise_learning.analysis.LegacySolve") | Solves for the [`ModelData`](generated/data-model-data "qiskit_noise_learning.data.ModelData") using the legacy pair-fidelity method. | +| [`LinearSystemData`](generated/analysis-linear-system-data "qiskit_noise_learning.analysis.LinearSystemData") | The linear system to solve and metadata in raw format. | +| [`LSQLinearSolve`](generated/analysis-lsq-linear-solve "qiskit_noise_learning.analysis.LSQLinearSolve") | Solves for the [`ModelData`](generated/data-model-data "qiskit_noise_learning.data.ModelData") using SciPy's linear least squares solver. | +| [`NNLSSolve`](generated/analysis-nnls-solve "qiskit_noise_learning.analysis.NNLSSolve") | Solves for the [`ModelData`](generated/data-model-data "qiskit_noise_learning.data.ModelData") using SciPy's non-negative least squares solver. | +| [`PositivityMinSolve`](generated/analysis-positivity-min-solve "qiskit_noise_learning.analysis.PositivityMinSolve") | Solves for the [`ModelData`](generated/data-model-data "qiskit_noise_learning.data.ModelData") while minimizing Pauli-Lindblad rate positivity. | +| [`SymmetrizeFidelities`](generated/analysis-symmetrize-fidelities "qiskit_noise_learning.analysis.SymmetrizeFidelities") | Project generator rates into the fidelity-symmetry null space, gate by gate. | +| [`SymmetrizeGenerators`](generated/analysis-symmetrize-generators "qiskit_noise_learning.analysis.SymmetrizeGenerators") | Project generator rates to satisfy conjugation symmetry, gate by gate. | +| [`ZeroPostSelect`](generated/analysis-zero-post-select "qiskit_noise_learning.analysis.ZeroPostSelect") | Apply a mask to raw data based on whether bit values are all False. | diff --git a/docs/api/qiskit-noise-learning/circuit-generator.mdx b/docs/api/qiskit-noise-learning/circuit-generator.mdx index d5eaeb2fbeae..46184694a498 100644 --- a/docs/api/qiskit-noise-learning/circuit-generator.mdx +++ b/docs/api/qiskit-noise-learning/circuit-generator.mdx @@ -18,8 +18,8 @@ Executor circuit generator. ## Classes -| | | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | -| [`ExecutorCircuitGenerator`](generated/circuit-generator-executor-circuit-generator#qiskit_noise_learning.circuit_generator.ExecutorCircuitGenerator "qiskit_noise_learning.circuit_generator.ExecutorCircuitGenerator") | A circuit generator that converts sequences of Qiskit gates into a samplex items. | -| [`ExecutorDataMapper`](generated/circuit-generator-executor-data-mapper#qiskit_noise_learning.circuit_generator.ExecutorDataMapper "qiskit_noise_learning.circuit_generator.ExecutorDataMapper") | Map executor results into standard results. | +| | | +| ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | +| [`ExecutorCircuitGenerator`](generated/circuit-generator-executor-circuit-generator "qiskit_noise_learning.circuit_generator.ExecutorCircuitGenerator") | A circuit generator that converts sequences of Qiskit gates into a samplex items. | +| [`ExecutorDataMapper`](generated/circuit-generator-executor-data-mapper "qiskit_noise_learning.circuit_generator.ExecutorDataMapper") | Map executor results into standard results. | diff --git a/docs/api/qiskit-noise-learning/data.mdx b/docs/api/qiskit-noise-learning/data.mdx index 076ef67e7be9..a9e9789f0d2c 100644 --- a/docs/api/qiskit-noise-learning/data.mdx +++ b/docs/api/qiskit-noise-learning/data.mdx @@ -18,11 +18,11 @@ Data containers. ## Classes -| | | -| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| [`AggregatedObservableData`](generated/data-aggregated-observable-data#qiskit_noise_learning.data.AggregatedObservableData "qiskit_noise_learning.data.AggregatedObservableData") | Per-path estimates obtained by aggregating [`ObservableData`](generated/data-observable-data#qiskit_noise_learning.data.ObservableData "qiskit_noise_learning.data.ObservableData"). | -| [`LeveledData`](generated/data-leveled-data#qiskit_noise_learning.data.LeveledData "qiskit_noise_learning.data.LeveledData") | Marker base class for data at a specific level of the analysis hierarchy. | -| [`ModelData`](generated/data-model-data#qiskit_noise_learning.data.ModelData "qiskit_noise_learning.data.ModelData") | Results from fitting, backed by an xarray Dataset. | -| [`ObservableData`](generated/data-observable-data#qiskit_noise_learning.data.ObservableData "qiskit_noise_learning.data.ObservableData") | A collection of calculated expectation values. | -| [`RawData`](generated/data-raw-data#qiskit_noise_learning.data.RawData "qiskit_noise_learning.data.RawData") | Raw experimental outcome data associated with instruction sequences and classical registers. | +| | | +| ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| [`AggregatedObservableData`](generated/data-aggregated-observable-data "qiskit_noise_learning.data.AggregatedObservableData") | Per-path estimates obtained by aggregating [`ObservableData`](generated/data-observable-data "qiskit_noise_learning.data.ObservableData"). | +| [`LeveledData`](generated/data-leveled-data "qiskit_noise_learning.data.LeveledData") | Marker base class for data at a specific level of the analysis hierarchy. | +| [`ModelData`](generated/data-model-data "qiskit_noise_learning.data.ModelData") | Results from fitting, backed by an xarray Dataset. | +| [`ObservableData`](generated/data-observable-data "qiskit_noise_learning.data.ObservableData") | A collection of calculated expectation values. | +| [`RawData`](generated/data-raw-data "qiskit_noise_learning.data.RawData") | Raw experimental outcome data associated with instruction sequences and classical registers. | diff --git a/docs/api/qiskit-noise-learning/experiment-builder.mdx b/docs/api/qiskit-noise-learning/experiment-builder.mdx index 93f4139ec758..d5a91788627f 100644 --- a/docs/api/qiskit-noise-learning/experiment-builder.mdx +++ b/docs/api/qiskit-noise-learning/experiment-builder.mdx @@ -18,22 +18,22 @@ Experiment builder. ## Classes -| | | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`Experiment`](generated/experiment-builder-experiment#qiskit_noise_learning.experiment_builder.Experiment "qiskit_noise_learning.experiment_builder.Experiment") | A learning experiment specification. | -| [`ExperimentBuilder`](generated/experiment-builder-experiment-builder#qiskit_noise_learning.experiment_builder.ExperimentBuilder "qiskit_noise_learning.experiment_builder.ExperimentBuilder") | A composite [`ExperimentBuilderStage`](generated/experiment-builder-experiment-builder-stage#qiskit_noise_learning.experiment_builder.ExperimentBuilderStage "qiskit_noise_learning.experiment_builder.ExperimentBuilderStage") that chains stages sequentially. | -| [`ExperimentBuilderStage`](generated/experiment-builder-experiment-builder-stage#qiskit_noise_learning.experiment_builder.ExperimentBuilderStage "qiskit_noise_learning.experiment_builder.ExperimentBuilderStage") | Abstract base for a stage in the experiment-building pipeline. | -| [`AddInstructionSequences`](generated/experiment-builder-add-instruction-sequences#qiskit_noise_learning.experiment_builder.AddInstructionSequences "qiskit_noise_learning.experiment_builder.AddInstructionSequences") | Add instruction sequences to an experiment. | -| [`AddPaths`](generated/experiment-builder-add-paths#qiskit_noise_learning.experiment_builder.AddPaths "qiskit_noise_learning.experiment_builder.AddPaths") | Add paths to an experiment. | -| [`BindFragmentDepths`](generated/experiment-builder-bind-fragment-depths#qiskit_noise_learning.experiment_builder.BindFragmentDepths "qiskit_noise_learning.experiment_builder.BindFragmentDepths") | Expand unbound instruction sequences at the given fragment depths. | -| [`CompleteSequences`](generated/experiment-builder-complete-sequences#qiskit_noise_learning.experiment_builder.CompleteSequences "qiskit_noise_learning.experiment_builder.CompleteSequences") | Complete all instruction sequences. | -| [`Depth1Paths`](generated/experiment-builder-depth-1-paths#qiskit_noise_learning.experiment_builder.Depth1Paths "qiskit_noise_learning.experiment_builder.Depth1Paths") | Generate depth-1 paths for each target gate. | -| [`EvenDepthPaths`](generated/experiment-builder-even-depth-paths#qiskit_noise_learning.experiment_builder.EvenDepthPaths "qiskit_noise_learning.experiment_builder.EvenDepthPaths") | Generate unbound paths with repetitions of two applications of each target gate. | -| [`EvenDepthVanillaPaths`](generated/experiment-builder-even-depth-vanilla-paths#qiskit_noise_learning.experiment_builder.EvenDepthVanillaPaths "qiskit_noise_learning.experiment_builder.EvenDepthVanillaPaths") | Generate unbound vanilla paths with repetitions of two gate applications. | -| [`GenerateInstructionSequences`](generated/experiment-builder-generate-instruction-sequences#qiskit_noise_learning.experiment_builder.GenerateInstructionSequences "qiskit_noise_learning.experiment_builder.GenerateInstructionSequences") | Generate one instruction sequence per path via [`to_instruction_sequence()`](generated/sequences-path#qiskit_noise_learning.sequences.Path.to_instruction_sequence "qiskit_noise_learning.sequences.Path.to_instruction_sequence"). | -| [`IdentifyRelations`](generated/experiment-builder-identify-relations#qiskit_noise_learning.experiment_builder.IdentifyRelations "qiskit_noise_learning.experiment_builder.IdentifyRelations") | Identify new relations amongst existing paths and instruction sequences. | -| [`MergeInstructionSequences`](generated/experiment-builder-merge-instruction-sequences#qiskit_noise_learning.experiment_builder.MergeInstructionSequences "qiskit_noise_learning.experiment_builder.MergeInstructionSequences") | Merge instruction sequences into a smaller set. | -| [`RankReducePaths`](generated/experiment-builder-rank-reduce-paths#qiskit_noise_learning.experiment_builder.RankReducePaths "qiskit_noise_learning.experiment_builder.RankReducePaths") | Reduce the paths to a maximal linearly independent set. | -| [`SPAMPaths`](generated/experiment-builder-spam-paths#qiskit_noise_learning.experiment_builder.SPAMPaths "qiskit_noise_learning.experiment_builder.SPAMPaths") | Generate depth-0 paths. | -| [`VanillaInstructionSequences`](generated/experiment-builder-vanilla-instruction-sequences#qiskit_noise_learning.experiment_builder.VanillaInstructionSequences "qiskit_noise_learning.experiment_builder.VanillaInstructionSequences") | Generate vanilla instruction sequences for each target gate. | +| | | +| --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| [`Experiment`](generated/experiment-builder-experiment "qiskit_noise_learning.experiment_builder.Experiment") | A learning experiment specification. | +| [`ExperimentBuilder`](generated/experiment-builder-experiment-builder "qiskit_noise_learning.experiment_builder.ExperimentBuilder") | A composite [`ExperimentBuilderStage`](generated/experiment-builder-experiment-builder-stage "qiskit_noise_learning.experiment_builder.ExperimentBuilderStage") that chains stages sequentially. | +| [`ExperimentBuilderStage`](generated/experiment-builder-experiment-builder-stage "qiskit_noise_learning.experiment_builder.ExperimentBuilderStage") | Abstract base for a stage in the experiment-building pipeline. | +| [`AddInstructionSequences`](generated/experiment-builder-add-instruction-sequences "qiskit_noise_learning.experiment_builder.AddInstructionSequences") | Add instruction sequences to an experiment. | +| [`AddPaths`](generated/experiment-builder-add-paths "qiskit_noise_learning.experiment_builder.AddPaths") | Add paths to an experiment. | +| [`BindFragmentDepths`](generated/experiment-builder-bind-fragment-depths "qiskit_noise_learning.experiment_builder.BindFragmentDepths") | Expand unbound instruction sequences at the given fragment depths. | +| [`CompleteSequences`](generated/experiment-builder-complete-sequences "qiskit_noise_learning.experiment_builder.CompleteSequences") | Complete all instruction sequences. | +| [`Depth1Paths`](generated/experiment-builder-depth-1-paths "qiskit_noise_learning.experiment_builder.Depth1Paths") | Generate depth-1 paths for each target gate. | +| [`EvenDepthPaths`](generated/experiment-builder-even-depth-paths "qiskit_noise_learning.experiment_builder.EvenDepthPaths") | Generate unbound paths with repetitions of two applications of each target gate. | +| [`EvenDepthVanillaPaths`](generated/experiment-builder-even-depth-vanilla-paths "qiskit_noise_learning.experiment_builder.EvenDepthVanillaPaths") | Generate unbound vanilla paths with repetitions of two gate applications. | +| [`GenerateInstructionSequences`](generated/experiment-builder-generate-instruction-sequences "qiskit_noise_learning.experiment_builder.GenerateInstructionSequences") | Generate one instruction sequence per path via [`to_instruction_sequence()`](generated/sequences-path#to_instruction_sequence "qiskit_noise_learning.sequences.Path.to_instruction_sequence"). | +| [`IdentifyRelations`](generated/experiment-builder-identify-relations "qiskit_noise_learning.experiment_builder.IdentifyRelations") | Identify new relations amongst existing paths and instruction sequences. | +| [`MergeInstructionSequences`](generated/experiment-builder-merge-instruction-sequences "qiskit_noise_learning.experiment_builder.MergeInstructionSequences") | Merge instruction sequences into a smaller set. | +| [`RankReducePaths`](generated/experiment-builder-rank-reduce-paths "qiskit_noise_learning.experiment_builder.RankReducePaths") | Reduce the paths to a maximal linearly independent set. | +| [`SPAMPaths`](generated/experiment-builder-spam-paths "qiskit_noise_learning.experiment_builder.SPAMPaths") | Generate depth-0 paths. | +| [`VanillaInstructionSequences`](generated/experiment-builder-vanilla-instruction-sequences "qiskit_noise_learning.experiment_builder.VanillaInstructionSequences") | Generate vanilla instruction sequences for each target gate. | diff --git a/docs/api/qiskit-noise-learning/gate-sets.mdx b/docs/api/qiskit-noise-learning/gate-sets.mdx index 62937f8c7624..346e36ab1ef1 100644 --- a/docs/api/qiskit-noise-learning/gate-sets.mdx +++ b/docs/api/qiskit-noise-learning/gate-sets.mdx @@ -18,12 +18,12 @@ Gate sets. ## Classes -| | | -| ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`Gate`](generated/gate-sets-gate#qiskit_noise_learning.gate_sets.Gate "qiskit_noise_learning.gate_sets.Gate") | Represents qubit metadata for a single gate in a gate set. | -| [`GateSet`](generated/gate-sets-gate-set#qiskit_noise_learning.gate_sets.GateSet "qiskit_noise_learning.gate_sets.GateSet") | A mapping of names to gates with qubit metadata. | -| [`ModelGate`](generated/gate-sets-model-gate#qiskit_noise_learning.gate_sets.ModelGate "qiskit_noise_learning.gate_sets.ModelGate") | A model for a gate of the form Clifford - MCM - reset. | -| [`ModelGateSet`](generated/gate-sets-model-gate-set#qiskit_noise_learning.gate_sets.ModelGateSet "qiskit_noise_learning.gate_sets.ModelGateSet") | A set of Clifford - MCM - reset gates represented as [`ModelGate`](generated/gate-sets-model-gate#qiskit_noise_learning.gate_sets.ModelGate "qiskit_noise_learning.gate_sets.ModelGate") instances. | -| [`QiskitGate`](generated/gate-sets-qiskit-gate#qiskit_noise_learning.gate_sets.QiskitGate "qiskit_noise_learning.gate_sets.QiskitGate") | Represents a single gate in a [`QiskitGateSet`](generated/gate-sets-qiskit-gate-set#qiskit_noise_learning.gate_sets.QiskitGateSet "qiskit_noise_learning.gate_sets.QiskitGateSet"). | -| [`QiskitGateSet`](generated/gate-sets-qiskit-gate-set#qiskit_noise_learning.gate_sets.QiskitGateSet "qiskit_noise_learning.gate_sets.QiskitGateSet") | A gate set whose noise is to be learned and that is specified using Qiskit objects. | +| | | +| ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`Gate`](generated/gate-sets-gate "qiskit_noise_learning.gate_sets.Gate") | Represents qubit metadata for a single gate in a gate set. | +| [`GateSet`](generated/gate-sets-gate-set "qiskit_noise_learning.gate_sets.GateSet") | A mapping of names to gates with qubit metadata. | +| [`ModelGate`](generated/gate-sets-model-gate "qiskit_noise_learning.gate_sets.ModelGate") | A model for a gate of the form Clifford - MCM - reset. | +| [`ModelGateSet`](generated/gate-sets-model-gate-set "qiskit_noise_learning.gate_sets.ModelGateSet") | A set of Clifford - MCM - reset gates represented as [`ModelGate`](generated/gate-sets-model-gate "qiskit_noise_learning.gate_sets.ModelGate") instances. | +| [`QiskitGate`](generated/gate-sets-qiskit-gate "qiskit_noise_learning.gate_sets.QiskitGate") | Represents a single gate in a [`QiskitGateSet`](generated/gate-sets-qiskit-gate-set "qiskit_noise_learning.gate_sets.QiskitGateSet"). | +| [`QiskitGateSet`](generated/gate-sets-qiskit-gate-set "qiskit_noise_learning.gate_sets.QiskitGateSet") | A gate set whose noise is to be learned and that is specified using Qiskit objects. | diff --git a/docs/api/qiskit-noise-learning/generated/aer-executor-aer-executor.mdx b/docs/api/qiskit-noise-learning/generated/aer-executor-aer-executor.mdx new file mode 100644 index 000000000000..3d313b6200d1 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/aer-executor-aer-executor.mdx @@ -0,0 +1,81 @@ +--- +title: AerExecutor (latest version) +description: API reference for qiskit_noise_learning.aer_executor.AerExecutor in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.aer_executor.AerExecutor +--- + + + +# qiskit\_noise\_learning.aer\_executor.AerExecutor + + + Bases: [`object`](https://docs.python.org/3/library/functions.html#object) + + Local Aer-based executor mimicking the IBM Runtime executor interface. + + Runs a `QuantumProgram` eagerly on construction of the returned job — the result is available immediately when [`AerRuntimeJob.result()`](aer-executor-aer-runtime-job#result "qiskit_noise_learning.aer_executor.AerRuntimeJob.result") is called. + + **Noise injection** + + When `noise_dict` is provided, Pauli-Lindblad noise is injected into circuits at tagged barriers via `InsertNoisePass`. Samplomatic inserts three barriers around each boxed gate — left (`L`), middle (`M`), and right (`R`) — with labels of the form `@tag=` (e.g. `R0@tag=r0`). By default, noise is injected at the `R` (right) barriers, i.e. *after* the gate. Use `noise_after=False` on `InsertNoisePass` to target `M` barriers instead (noise *before* the gate). + + The `noise_dict` format is: + + * **Keys** — layer name tags (strings, e.g. `"r0"`, `"my_tag"`). Each key must match the `ref` of a `Tag` annotation used when building the `QuantumProgram`. A warning is emitted (if `warn_absent=True`) when a tagged barrier’s tag is absent from the dict; the barrier is left as-is (no noise inserted for that layer). + * **Values** — [`PauliLindbladMap`](/docs/api/qiskit/qiskit.quantum_info.PauliLindbladMap) instances describing the Pauli-Lindblad noise channel for that gate. The map’s `num_qubits` must equal the number of qubits on the corresponding barrier in the circuit. + * **Qubit indexing** — indices inside the map are *local* to the barrier’s qubit set, independent of global circuit qubit numbering. Local index `i` refers to the `i`-th qubit of the barrier in *ascending physical-qubit order*, so a device-wide map can be converted with [`PauliLindbladMap.keep_qubits(sorted(qubits))`](/docs/api/qiskit/qiskit.quantum_info.PauliLindbladMap#keep_qubits). + + **Parameters** + + * **qasm\_simulator** – The Aer simulator to run programs on. + * **noise\_dict** – A map from barrier label refs to Pauli-Lindblad noise maps. Pass `None` (default) to run without noise injection. + * **angle\_decimals** – Gate angles are rounded to the nearest multiple of π/2 at this decimal precision before simulation. This prevents floating-point drift from preventing Clifford-method simulation when angles are nominally Clifford. + * **warn\_absent** – If `True` (default), emit a warning when a tagged barrier’s tag is not found in `noise_dict`. Set to `False` when partial coverage of tags is intentional. + * **root\_seed** – Root seed for random number generation, covering both the sampling of shots and the sampling of twirls. Rather than being used directly, it seeds a sequence that each call to [`run()`](#qiskit_noise_learning.aer_executor.AerExecutor.run "qiskit_noise_learning.aer_executor.AerExecutor.run") draws the next seed from, so that runs are independently random. With the default of `None` a root seed is drawn nondeterministically; it is available as [`root_seed`](#qiskit_noise_learning.aer_executor.AerExecutor.root_seed "qiskit_noise_learning.aer_executor.AerExecutor.root_seed") either way. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | + | [`__init__`](#qiskit_noise_learning.aer_executor.AerExecutor.__init__ "qiskit_noise_learning.aer_executor.AerExecutor.__init__")(qasm\_simulator\[, noise\_dict, ...]) | | + | [`run`](#qiskit_noise_learning.aer_executor.AerExecutor.run "qiskit_noise_learning.aer_executor.AerExecutor.run")(program) | Run a quantum program and return a completed job. | + + ## Attributes + + | | | + | ----------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | + | [`root_seed`](#qiskit_noise_learning.aer_executor.AerExecutor.root_seed "qiskit_noise_learning.aer_executor.AerExecutor.root_seed") | The root seed each run's randomness is derived from. | + + ### root\_seed + + + Type: [`int`](https://docs.python.org/3/library/functions.html#int) + + The root seed each run’s randomness is derived from. + + Passing this to a new executor reproduces this executor’s whole sequence of runs. It is not the seed of any individual run: to reproduce a single run, use the seed of the job that produced it, [`AerRuntimeJob.seed`](aer-executor-aer-runtime-job#seed "qiskit_noise_learning.aer_executor.AerRuntimeJob.seed"). + + + ### run + + + Run a quantum program and return a completed job. + + Each call draws a fresh seed from the executor’s root seed, so successive runs are independently random even when the executor is seeded. + + **Parameters** + + **program** – The quantum program to execute. + + **Returns** + + A job whose result is immediately available. + + + diff --git a/docs/api/qiskit-noise-learning/generated/aer-executor-aer-runtime-job.mdx b/docs/api/qiskit-noise-learning/generated/aer-executor-aer-runtime-job.mdx new file mode 100644 index 000000000000..467a66c66620 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/aer-executor-aer-runtime-job.mdx @@ -0,0 +1,71 @@ +--- +title: AerRuntimeJob (latest version) +description: API reference for qiskit_noise_learning.aer_executor.AerRuntimeJob in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.aer_executor.AerRuntimeJob +--- + + + +# qiskit\_noise\_learning.aer\_executor.AerRuntimeJob + + + Bases: [`object`](https://docs.python.org/3/library/functions.html#object) + + Job object returned by [`AerExecutor.run()`](aer-executor-aer-executor#run "qiskit_noise_learning.aer_executor.AerExecutor.run"). + + The program is executed eagerly on construction; the result is available immediately when [`result()`](#qiskit_noise_learning.aer_executor.AerRuntimeJob.result "qiskit_noise_learning.aer_executor.AerRuntimeJob.result") is called. + + **Parameters** + + * **qasm\_simulator** – The Aer simulator to run on. + * **program** – The quantum program to execute. + * **noise\_dict** – A map from barrier label refs to Pauli-Lindblad noise maps. + * **angle\_decimals** – Rounding precision for gate angles (in units of π/2). + * **warn\_absent** – If `True` (default), warn when a tagged barrier has no entry in `noise_dict`. + * **seed** – Root seed for this job’s randomness. If `None`, one is drawn nondeterministically; either way the value used is available as [`seed`](#qiskit_noise_learning.aer_executor.AerRuntimeJob.seed "qiskit_noise_learning.aer_executor.AerRuntimeJob.seed"). + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | + | [`__init__`](#qiskit_noise_learning.aer_executor.AerRuntimeJob.__init__ "qiskit_noise_learning.aer_executor.AerRuntimeJob.__init__")(qasm\_simulator, program\[, ...]) | | + | [`job_id`](#qiskit_noise_learning.aer_executor.AerRuntimeJob.job_id "qiskit_noise_learning.aer_executor.AerRuntimeJob.job_id")() | Return the unique job ID. | + | [`result`](#qiskit_noise_learning.aer_executor.AerRuntimeJob.result "qiskit_noise_learning.aer_executor.AerRuntimeJob.result")(\*\_, \*\*\_\_) | Return the result of the program execution. | + + ## Attributes + + | | | + | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------- | + | [`seed`](#qiskit_noise_learning.aer_executor.AerRuntimeJob.seed "qiskit_noise_learning.aer_executor.AerRuntimeJob.seed") | The root seed this job's randomness was derived from. | + + ### job\_id + + + Return the unique job ID. + + + ### seed + + + Type: [`int`](https://docs.python.org/3/library/functions.html#int) + + The root seed this job’s randomness was derived from. + + Constructing another job with this seed and the same program reproduces this job’s result, including when the job itself was created without a seed. + + For a job created by [`AerExecutor.run()`](aer-executor-aer-executor#run "qiskit_noise_learning.aer_executor.AerExecutor.run") this is the seed that the executor drew for this particular run, which is not its [`AerExecutor.root_seed`](aer-executor-aer-executor#root_seed "qiskit_noise_learning.aer_executor.AerExecutor.root_seed") — the two are not interchangeable. + + + ### result + + + Return the result of the program execution. + + + diff --git a/docs/api/qiskit-noise-learning/generated/aer-executor-inline-samplexes.mdx b/docs/api/qiskit-noise-learning/generated/aer-executor-inline-samplexes.mdx new file mode 100644 index 000000000000..4480e5ffafac --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/aer-executor-inline-samplexes.mdx @@ -0,0 +1,28 @@ +--- +title: inline_samplexes (latest version) +description: API reference for qiskit_noise_learning.aer_executor.inline_samplexes in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit_noise_learning.aer_executor.inline_samplexes +--- + + + +# qiskit\_noise\_learning.aer\_executor.inline\_samplexes + + + Return a new `QuantumProgram` with `SamplexItem`s resolved in-place. + + Each `SamplexItem` whose index is not in `omit` is replaced by a `CircuitItem` via `inline_samplex_item()`. The passthrough data produced by sampling (e.g. `measurement_flips.*` arrays) is stored in the returned program’s `passthrough_data` under the key `"inlined"`, keyed by the original item index (as a string). Any existing `passthrough_data` on the input program is preserved alongside the new `"inlined"` entry. + + **Parameters** + + * **program** – The quantum program to process. + * **omit** – Indices of items to leave as `SamplexItem`s. All other `SamplexItem`s are inlined. `CircuitItem`s are always left unchanged regardless of this list. + * **rng** – Random number generator passed to `inline_samplex_item()`. If `None`, `np.random.default_rng()` is used. + + **Returns** + + A new `QuantumProgram` with the same shots, noise maps, and measurement level as the input, but with the selected `SamplexItem`s replaced by `CircuitItem`s. + + diff --git a/docs/api/qiskit-noise-learning/generated/analysis-analysis-pipeline.mdx b/docs/api/qiskit-noise-learning/generated/analysis-analysis-pipeline.mdx new file mode 100644 index 000000000000..981130c93c6b --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/analysis-analysis-pipeline.mdx @@ -0,0 +1,69 @@ +--- +title: AnalysisPipeline (latest version) +description: API reference for qiskit_noise_learning.analysis.AnalysisPipeline in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.analysis.AnalysisPipeline +--- + + + +# qiskit\_noise\_learning.analysis.AnalysisPipeline + + + Bases: [`AnalysisStage`](analysis-analysis-stage "qiskit_noise_learning.analysis.analysis_pipeline.AnalysisStage") + + A composite [`AnalysisStage`](analysis-analysis-stage "qiskit_noise_learning.analysis.AnalysisStage") that chains stages sequentially. + + Because [`AnalysisPipeline`](#qiskit_noise_learning.analysis.AnalysisPipeline "qiskit_noise_learning.analysis.AnalysisPipeline") is itself an [`AnalysisStage`](analysis-analysis-stage "qiskit_noise_learning.analysis.AnalysisStage"), pipelines can be nested and used anywhere a single stage is expected. + + Consecutive stages must connect: the [`output_level`](analysis-analysis-stage#output_level "qiskit_noise_learning.analysis.AnalysisStage.output_level") of each stage must equal the [`input_level`](analysis-analysis-stage#input_level "qiskit_noise_learning.analysis.AnalysisStage.input_level") of the next. + + **Parameters** + + **stages** – The analysis stages to use in this pipeline in sequential order. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | -------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | + | [`__init__`](#qiskit_noise_learning.analysis.AnalysisPipeline.__init__ "qiskit_noise_learning.analysis.AnalysisPipeline.__init__")(\*stages) | | + | `run`(fit) | Run this stage, returning a new [`Fit`](analysis-fit "qiskit_noise_learning.analysis.Fit") with the output level populated. | + + ## Attributes + + | | | + | ---------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | + | [`input_level`](#qiskit_noise_learning.analysis.AnalysisPipeline.input_level "qiskit_noise_learning.analysis.AnalysisPipeline.input_level") | The data level this stage reads. | + | [`output_level`](#qiskit_noise_learning.analysis.AnalysisPipeline.output_level "qiskit_noise_learning.analysis.AnalysisPipeline.output_level") | The data level this stage writes. | + | [`stages`](#qiskit_noise_learning.analysis.AnalysisPipeline.stages "qiskit_noise_learning.analysis.AnalysisPipeline.stages") | The stages in this pipeline. | + + ### input\_level + + + Type: [`type`](https://docs.python.org/3/library/functions.html#type)\[[`LeveledData`](data-leveled-data "qiskit_noise_learning.data.leveled_data.LeveledData")] + + The data level this stage reads. + + + ### output\_level + + + Type: [`type`](https://docs.python.org/3/library/functions.html#type)\[[`LeveledData`](data-leveled-data "qiskit_noise_learning.data.leveled_data.LeveledData")] + + The data level this stage writes. + + + ### stages + + + Type: [`tuple`](https://docs.python.org/3/library/stdtypes.html#tuple)\[[`AnalysisStage`](analysis-analysis-stage "qiskit_noise_learning.analysis.analysis_pipeline.AnalysisStage"), ...] + + The stages in this pipeline. + + + diff --git a/docs/api/qiskit-noise-learning/generated/analysis-analysis-stage.mdx b/docs/api/qiskit-noise-learning/generated/analysis-analysis-stage.mdx new file mode 100644 index 000000000000..4588691fa6da --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/analysis-analysis-stage.mdx @@ -0,0 +1,75 @@ +--- +title: AnalysisStage (latest version) +description: API reference for qiskit_noise_learning.analysis.AnalysisStage in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.analysis.AnalysisStage +--- + + + +# qiskit\_noise\_learning.analysis.AnalysisStage + + + Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC) + + Abstract base for a stage in the analysis pipeline. + + Each stage declares the data level it consumes ([`input_level`](#qiskit_noise_learning.analysis.AnalysisStage.input_level "qiskit_noise_learning.analysis.AnalysisStage.input_level")) and produces ([`output_level`](#qiskit_noise_learning.analysis.AnalysisStage.output_level "qiskit_noise_learning.analysis.AnalysisStage.output_level")). Stages may skip intermediate levels, e.g. going directly from `RawData` to `DecayData`. + + To implement a stage, subclass this and override `_run()`. The public [`run()`](#qiskit_noise_learning.analysis.AnalysisStage.run "qiskit_noise_learning.analysis.AnalysisStage.run") method handles shallow-copying the [`Fit`](analysis-fit "qiskit_noise_learning.analysis.Fit") container and marking skipped levels; `_run()` receives the copy and may mutate it in place. + + [`input_level`](#qiskit_noise_learning.analysis.AnalysisStage.input_level "qiskit_noise_learning.analysis.AnalysisStage.input_level") and [`output_level`](#qiskit_noise_learning.analysis.AnalysisStage.output_level "qiskit_noise_learning.analysis.AnalysisStage.output_level") can be declared as class attributes: + + ```python + class MyStage(AnalysisStage): + input_level = RawData + output_level = ObservableData + + def _run(self, fit): + fit[ObservableData] = compute(fit[RawData]) + ``` + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- | + | [`__init__`](#qiskit_noise_learning.analysis.AnalysisStage.__init__ "qiskit_noise_learning.analysis.AnalysisStage.__init__")() | | + | [`run`](#qiskit_noise_learning.analysis.AnalysisStage.run "qiskit_noise_learning.analysis.AnalysisStage.run")(fit) | Run this stage, returning a new [`Fit`](analysis-fit "qiskit_noise_learning.analysis.Fit") with the output level populated. | + + ## Attributes + + | | | + | ---------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | + | [`input_level`](#qiskit_noise_learning.analysis.AnalysisStage.input_level "qiskit_noise_learning.analysis.AnalysisStage.input_level") | The data level this stage reads. | + | [`output_level`](#qiskit_noise_learning.analysis.AnalysisStage.output_level "qiskit_noise_learning.analysis.AnalysisStage.output_level") | The data level this stage writes. | + + ### input\_level + + + Type: [`type`](https://docs.python.org/3/library/functions.html#type)\[[`LeveledData`](data-leveled-data "qiskit_noise_learning.data.leveled_data.LeveledData")] + + The data level this stage reads. + + + ### output\_level + + + Type: [`type`](https://docs.python.org/3/library/functions.html#type)\[[`LeveledData`](data-leveled-data "qiskit_noise_learning.data.leveled_data.LeveledData")] + + The data level this stage writes. + + + ### run + + + Run this stage, returning a new [`Fit`](analysis-fit "qiskit_noise_learning.analysis.Fit") with the output level populated. + + Shallow-copies `fit`, marks any `Absent` intermediate levels as `Skipped`, calls `_run()` on the copy, and returns it. The original `fit` is not modified. + + + diff --git a/docs/api/qiskit-noise-learning/generated/analysis-average-observables.mdx b/docs/api/qiskit-noise-learning/generated/analysis-average-observables.mdx new file mode 100644 index 000000000000..7324e046d5d8 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/analysis-average-observables.mdx @@ -0,0 +1,48 @@ +--- +title: AverageObservables (latest version) +description: API reference for qiskit_noise_learning.analysis.AverageObservables in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.analysis.AverageObservables +--- + + + +# qiskit\_noise\_learning.analysis.AverageObservables + + + Bases: [`AnalysisStage`](analysis-analysis-stage "qiskit_noise_learning.analysis.analysis_pipeline.AnalysisStage") + + Average observables over randomizations for each unbound path and fragment depth pair. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ---------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | + | [`__init__`](#qiskit_noise_learning.analysis.AverageObservables.__init__ "qiskit_noise_learning.analysis.AverageObservables.__init__")() | | + | `run`(fit) | Run this stage, returning a new [`Fit`](analysis-fit "qiskit_noise_learning.analysis.Fit") with the output level populated. | + + ## Attributes + + | | | + | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | + | [`input_level`](#qiskit_noise_learning.analysis.AverageObservables.input_level "qiskit_noise_learning.analysis.AverageObservables.input_level") | The data level this stage reads. | + | [`output_level`](#qiskit_noise_learning.analysis.AverageObservables.output_level "qiskit_noise_learning.analysis.AverageObservables.output_level") | The data level this stage writes. | + + ### input\_level + + + The data level this stage reads. + + + ### output\_level + + + The data level this stage writes. + + + diff --git a/docs/api/qiskit-noise-learning/generated/analysis-compute-observables.mdx b/docs/api/qiskit-noise-learning/generated/analysis-compute-observables.mdx new file mode 100644 index 000000000000..f7606d553c31 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/analysis-compute-observables.mdx @@ -0,0 +1,50 @@ +--- +title: ComputeObservables (latest version) +description: API reference for qiskit_noise_learning.analysis.ComputeObservables in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.analysis.ComputeObservables +--- + + + +# qiskit\_noise\_learning.analysis.ComputeObservables + + + Bases: [`AnalysisStage`](analysis-analysis-stage "qiskit_noise_learning.analysis.analysis_pipeline.AnalysisStage") + + Compute observable data from raw data. + + This analysis stage utilizes existing relations between paths and instruction sequences in the [`Fit`](analysis-fit "qiskit_noise_learning.analysis.Fit") to determine how to compute observables. If relations are not specified, they are greedily constructed by exhaustively comparing paths in `fit.paths` and the instruction sequences in `fit.raw_data`. Note that in this latter case, `fit.paths` is not updated and will therefore remain `None`. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ---------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | + | [`__init__`](#qiskit_noise_learning.analysis.ComputeObservables.__init__ "qiskit_noise_learning.analysis.ComputeObservables.__init__")() | | + | `run`(fit) | Run this stage, returning a new [`Fit`](analysis-fit "qiskit_noise_learning.analysis.Fit") with the output level populated. | + + ## Attributes + + | | | + | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | + | [`input_level`](#qiskit_noise_learning.analysis.ComputeObservables.input_level "qiskit_noise_learning.analysis.ComputeObservables.input_level") | The data level this stage reads. | + | [`output_level`](#qiskit_noise_learning.analysis.ComputeObservables.output_level "qiskit_noise_learning.analysis.ComputeObservables.output_level") | The data level this stage writes. | + + ### input\_level + + + The data level this stage reads. + + + ### output\_level + + + The data level this stage writes. + + + diff --git a/docs/api/qiskit-noise-learning/generated/analysis-curve-fit-observables.mdx b/docs/api/qiskit-noise-learning/generated/analysis-curve-fit-observables.mdx new file mode 100644 index 000000000000..2428170174c6 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/analysis-curve-fit-observables.mdx @@ -0,0 +1,56 @@ +--- +title: CurveFitObservables (latest version) +description: API reference for qiskit_noise_learning.analysis.CurveFitObservables in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.analysis.CurveFitObservables +--- + + + +# qiskit\_noise\_learning.analysis.CurveFitObservables + + + Bases: [`AnalysisStage`](analysis-analysis-stage "qiskit_noise_learning.analysis.analysis_pipeline.AnalysisStage") + + Fit observable data to exponential decays of the form `a * f**fragment_depth`, and average any remaining observables over randomizations. + + This stage will curve fit data for any unbound paths in `fit.paths`. If `fit.paths is None`, any path in the data with multiple fragment depths will be curve fit. In both cases, any remaining paths will be averaged. + + Each curve-fit row carries the following per-row metadata, which the averaged rows do not have: + + * `"spam_fidelity"`, `"spam_fidelity_std"`: the fitted prefactor $a$ and its `1`-sigma uncertainty. + * `"chi_squared"`: the raw chi-squared of the fit. + * `"reduced_chi_squared"`: the raw chi-squared divided by the degrees of freedom, that is the number of fragment depths minus the two fit parameters, or `nan` if there are none. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- | + | [`__init__`](#qiskit_noise_learning.analysis.CurveFitObservables.__init__ "qiskit_noise_learning.analysis.CurveFitObservables.__init__")() | | + | `run`(fit) | Run this stage, returning a new [`Fit`](analysis-fit "qiskit_noise_learning.analysis.Fit") with the output level populated. | + + ## Attributes + + | | | + | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | + | [`input_level`](#qiskit_noise_learning.analysis.CurveFitObservables.input_level "qiskit_noise_learning.analysis.CurveFitObservables.input_level") | The data level this stage reads. | + | [`output_level`](#qiskit_noise_learning.analysis.CurveFitObservables.output_level "qiskit_noise_learning.analysis.CurveFitObservables.output_level") | The data level this stage writes. | + + ### input\_level + + + The data level this stage reads. + + + ### output\_level + + + The data level this stage writes. + + + diff --git a/docs/api/qiskit-noise-learning/generated/analysis-fit.mdx b/docs/api/qiskit-noise-learning/generated/analysis-fit.mdx new file mode 100644 index 000000000000..219690589ab5 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/analysis-fit.mdx @@ -0,0 +1,183 @@ +--- +title: Fit (latest version) +description: API reference for qiskit_noise_learning.analysis.Fit in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.analysis.Fit +--- + + + +# qiskit\_noise\_learning.analysis.Fit + + + Bases: [`object`](https://docs.python.org/3/library/functions.html#object) + + Container for data at each level of the analysis hierarchy. + + The `LEVELS` represent different stages of processed data. In order, they are: + + * `RawData` corresponding to bit counts of executed instruction sequences. + * `ObservableData` corresponding to observables of randomizations of paths that traverse the instruction sequences. + * `AggregatedObservableData` corresponding to a combination of observables aggregated across randomizations. + * `ModelData` corresponding to model fit parameters. + + Each level holds a history of all values written to it; the current value is always the most recent. New levels start as `Absent`. Levels bypassed by a stage are marked `Skipped`. + + Example: + + ```python + result = my_stage.run(my_raw_data) + result.raw_data # current RawData + result.history.raw_data # full write history at the RawData level + ``` + + **Parameters** + + * **model** – The model to fit. If given, it must be a fidelity model, i.e. a [`LinearMap`](math-linear-map "qiskit_noise_learning.math.LinearMap") whose output space is a [`LogFidelitySpace`](models-log-fidelity-space "qiskit_noise_learning.models.LogFidelitySpace") (see [`is_fidelity_model()`](models-is-fidelity-model "qiskit_noise_learning.models.is_fidelity_model")). + * **paths** – The paths to analyze. + * **instruction\_sequences** – The instruction sequences used in the experiment. + * **relations** – A pre-computed set of `(path_idx, sequence_idx)` tuples indicating which paths are traversed by which instruction sequences. + + **Raises** + + [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError) – If `model` is not `None` and is not a fidelity model. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | + | [`__init__`](#qiskit_noise_learning.analysis.Fit.__init__ "qiskit_noise_learning.analysis.Fit.__init__")(\*\[, model, paths, ...]) | | + | [`copy`](#qiskit_noise_learning.analysis.Fit.copy "qiskit_noise_learning.analysis.Fit.copy")() | Return a copy preserving the full history at each level. | + | [`plot_qubit_pair_decays`](#qiskit_noise_learning.analysis.Fit.plot_qubit_pair_decays "qiskit_noise_learning.analysis.Fit.plot_qubit_pair_decays")(pairs, \*\[, ...]) | Plot a grid of fidelity decays over qubit pairs, drawn from this fit's data. | + + ## Attributes + + | | | + | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | + | [`aggregated_observable_data`](#qiskit_noise_learning.analysis.Fit.aggregated_observable_data "qiskit_noise_learning.analysis.Fit.aggregated_observable_data") | Current data at the `AggregatedObservableData` level. | + | [`history`](#qiskit_noise_learning.analysis.Fit.history "qiskit_noise_learning.analysis.Fit.history") | The full write history for each level. | + | [`instruction_sequences`](#qiskit_noise_learning.analysis.Fit.instruction_sequences "qiskit_noise_learning.analysis.Fit.instruction_sequences") | The instruction sequences used in the experiment, or `None` if not set. | + | [`model`](#qiskit_noise_learning.analysis.Fit.model "qiskit_noise_learning.analysis.Fit.model") | The fidelity model used for design matrix construction. | + | [`model_data`](#qiskit_noise_learning.analysis.Fit.model_data "qiskit_noise_learning.analysis.Fit.model_data") | Current data at the `ModelData` level. | + | [`observable_data`](#qiskit_noise_learning.analysis.Fit.observable_data "qiskit_noise_learning.analysis.Fit.observable_data") | Current data at the `ObservableData` level. | + | [`paths`](#qiskit_noise_learning.analysis.Fit.paths "qiskit_noise_learning.analysis.Fit.paths") | The paths to compute observables for. | + | [`raw_data`](#qiskit_noise_learning.analysis.Fit.raw_data "qiskit_noise_learning.analysis.Fit.raw_data") | Current data at the `RawData` level. | + | [`relations`](#qiskit_noise_learning.analysis.Fit.relations "qiskit_noise_learning.analysis.Fit.relations") | Path-to-sequence relations, or `None` if not set. | + + ### copy + + + Return a copy preserving the full history at each level. + + + ### history + + + Type: `FitHistory` + + The full write history for each level. + + + ### model + + + Type: [`LinearMap`](math-linear-map "qiskit_noise_learning.math.linear_map.LinearMap")\[[`Hashable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Hashable), [`FidelityIndex`](sequences-fidelity-index "qiskit_noise_learning.sequences.fidelity_index.FidelityIndex")] | [`None`](https://docs.python.org/3/library/constants.html#None) + + The fidelity model used for design matrix construction. + + + ### raw\_data + + + Type: [`RawData`](data-raw-data "qiskit_noise_learning.data.raw_data.RawData") | `AbsentType` | `SkippedType` + + Current data at the `RawData` level. + + + ### observable\_data + + + Type: [`ObservableData`](data-observable-data "qiskit_noise_learning.data.observable_data.ObservableData") | `AbsentType` | `SkippedType` + + Current data at the `ObservableData` level. + + + ### aggregated\_observable\_data + + + Type: [`AggregatedObservableData`](data-aggregated-observable-data "qiskit_noise_learning.data.aggregated_observable_data.AggregatedObservableData") | `AbsentType` | `SkippedType` + + Current data at the `AggregatedObservableData` level. + + + ### model\_data + + + Type: [`ModelData`](data-model-data "qiskit_noise_learning.data.model_data.ModelData") | `AbsentType` | `SkippedType` + + Current data at the `ModelData` level. + + + ### paths + + + Type: [`list`](https://docs.python.org/3/library/stdtypes.html#list)\[[`Path`](sequences-path "qiskit_noise_learning.sequences.path.Path")] + + The paths to compute observables for. + + + ### instruction\_sequences + + + Type: [`list`](https://docs.python.org/3/library/stdtypes.html#list)\[[`InstructionSequence`](sequences-instruction-sequence "qiskit_noise_learning.sequences.instruction_sequence.InstructionSequence")] | [`None`](https://docs.python.org/3/library/constants.html#None) + + The instruction sequences used in the experiment, or `None` if not set. + + + ### relations + + + Type: [`set`](https://docs.python.org/3/library/stdtypes.html#set)\[[`tuple`](https://docs.python.org/3/library/stdtypes.html#tuple)\[[`int`](https://docs.python.org/3/library/functions.html#int), [`int`](https://docs.python.org/3/library/functions.html#int)]] | [`None`](https://docs.python.org/3/library/constants.html#None) + + Path-to-sequence relations, or `None` if not set. + + + ### plot\_qubit\_pair\_decays + + + Plot a grid of fidelity decays over qubit pairs, drawn from this fit’s data. + + One subplot per pair, sharing labels/colors across pairs. Which decays are drawn is controlled by the toggles below; all default to off, so enable the ones you want. A requested decay whose data has not been computed on this fit yet is skipped with a warning. + + **Parameters** + + * **pairs** – The qubit pairs to plot, one subplot each. A pair is unordered – `(1, 0)` names the same subplot as `(0, 1)` – so no pair may be repeated. + * **observable\_type** – How to draw the empirical observable data: `"raw"` (raw per-randomization scatter), `"means"` (per-fragment-depth means with error bars), `"both"`, or `None` (the default) to omit the empirical points. Uses this fit’s [`ObservableData`](data-observable-data "qiskit_noise_learning.data.ObservableData"). + * **exponential\_fit** – Whether to draw the fitted exponential decay curve, from this fit’s [`AggregatedObservableData`](data-aggregated-observable-data "qiskit_noise_learning.data.AggregatedObservableData") (its `fragment_depth == -1` fitted parameters). Defaults to `False`. + * **model\_prediction** – Whether to draw the model-predicted decay curve, from this fit’s model and [`ModelData`](data-model-data "qiskit_noise_learning.data.ModelData"). Defaults to `False`. + * **observable\_marker\_kwargs** – Optional `marker` overrides for the raw observable points. + * **means\_marker\_kwargs** – Optional `marker` overrides for the observable-means points. + * **exponential\_fit\_line\_kwargs** – Optional `line` overrides for the exponential-fit curve. + * **model\_line\_kwargs** – Optional `line` overrides for the model curve. + * **num\_cols** – The number of subplot columns; rows are derived from the pair count. + * **noise\_site** – An optional noise-site mapping forwarded to the label formatter (with the default `"formula"` label style this yields the compact `f^{gate}_{pauli}` label). Defaults to the noise site of the fit’s model when it is, or contains, a single [`PauliLindbladModel`](models-pauli-lindblad-model "qiskit_noise_learning.models.PauliLindbladModel"). + * **paths** – The paths to draw across all layers. Defaults to the decay paths found in this fit’s observable/aggregated observable data, falling back to the fit’s own `paths` when no such data is present. Supply this to draw model-prediction curves for a fit that carries only a model (no observable or aggregated observable data to derive the paths from). + * **fragment\_depths** – The fragment-depth range for the curves. Defaults to `0` through the largest fragment depth in the empirical data present, or `0`–`10` when there is none. + * **title** – An optional figure title. + + **Returns** + + The figure with interactive legends. + + **Raises** + + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – If the fit has no model (and hence no gate set) to build labels from, or if `pairs` names the same pair twice. + * [**ImportError**](https://docs.python.org/3/library/exceptions.html#ImportError) – If `matplotlib` is not installed. + + + diff --git a/docs/api/qiskit-noise-learning/generated/analysis-flip-post-select.mdx b/docs/api/qiskit-noise-learning/generated/analysis-flip-post-select.mdx new file mode 100644 index 000000000000..5c819a1c37a0 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/analysis-flip-post-select.mdx @@ -0,0 +1,60 @@ +--- +title: FlipPostSelect (latest version) +description: API reference for qiskit_noise_learning.analysis.FlipPostSelect in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.analysis.FlipPostSelect +--- + + + +# qiskit\_noise\_learning.analysis.FlipPostSelect + + + Bases: [`AnalysisStage`](analysis-analysis-stage "qiskit_noise_learning.analysis.analysis_pipeline.AnalysisStage") + + Apply a mask to raw data based on bit flips across measurement outcomes. + + This post selection stage is based on identifying successful bit flips on the same qubit(s) between two measurements. It can be configured to operate in one of two modes: + + * `"node"`: Shots are discarded if at least one bit failed to flip. + * `"edge"`: Shots are discarded if there exists a pair of neighbouring qubits in the measurement for which both bits failed to flip. + + **Parameters** + + * **creg\_pair\_identifier** – A callable that, given a list of present creg names, returns an iterator over pairs of creg names for which to do the flip-based post selection on. Defaults to returning pairs of cregs with names of the form `"*"` and `"*_ps"`. + * **mode** – Post-selection mode; either `"node"` or `"edge"`. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | + | [`__init__`](#qiskit_noise_learning.analysis.FlipPostSelect.__init__ "qiskit_noise_learning.analysis.FlipPostSelect.__init__")(\[creg\_pair\_identifier, mode]) | | + | `run`(fit) | Run this stage, returning a new [`Fit`](analysis-fit "qiskit_noise_learning.analysis.Fit") with the output level populated. | + + ## Attributes + + | | | + | ------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------- | + | `creg_pair_identifier` | | + | [`input_level`](#qiskit_noise_learning.analysis.FlipPostSelect.input_level "qiskit_noise_learning.analysis.FlipPostSelect.input_level") | The data level this stage reads. | + | `mode` | | + | [`output_level`](#qiskit_noise_learning.analysis.FlipPostSelect.output_level "qiskit_noise_learning.analysis.FlipPostSelect.output_level") | The data level this stage writes. | + + ### input\_level + + + The data level this stage reads. + + + ### output\_level + + + The data level this stage writes. + + + diff --git a/docs/api/qiskit-noise-learning/generated/analysis-legacy-solve.mdx b/docs/api/qiskit-noise-learning/generated/analysis-legacy-solve.mdx new file mode 100644 index 000000000000..df363ad611d6 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/analysis-legacy-solve.mdx @@ -0,0 +1,45 @@ +--- +title: LegacySolve (latest version) +description: API reference for qiskit_noise_learning.analysis.LegacySolve in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.analysis.LegacySolve +--- + + + +# qiskit\_noise\_learning.analysis.LegacySolve + + + Bases: [`AnalysisStage`](analysis-analysis-stage "qiskit_noise_learning.analysis.analysis_pipeline.AnalysisStage") + + Solves for the [`ModelData`](data-model-data "qiskit_noise_learning.data.ModelData") using the legacy pair-fidelity method. + + This solver assumes that the gate set only has a single unitary gate, and that the paths are of a vanilla-learning type (i.e. even depth with no single-qubit Cliffords required). + + Delegates to `fit_noise_model_legacy()` with `noise_assumption="symmetric_fidelities"`, `optimizer_name="nnls"`, and `constrained=True`. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | + | [`__init__`](#qiskit_noise_learning.analysis.LegacySolve.__init__ "qiskit_noise_learning.analysis.LegacySolve.__init__")() | | + | `run`(fit) | Run this stage, returning a new [`Fit`](analysis-fit "qiskit_noise_learning.analysis.Fit") with the output level populated. | + + ### input\_level + + + alias of [`AggregatedObservableData`](data-aggregated-observable-data "qiskit_noise_learning.data.aggregated_observable_data.AggregatedObservableData") + + + ### output\_level + + + alias of [`ModelData`](data-model-data "qiskit_noise_learning.data.model_data.ModelData") + + + diff --git a/docs/api/qiskit-noise-learning/generated/analysis-linear-system-data.mdx b/docs/api/qiskit-noise-learning/generated/analysis-linear-system-data.mdx new file mode 100644 index 000000000000..3da6c278676c --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/analysis-linear-system-data.mdx @@ -0,0 +1,89 @@ +--- +title: LinearSystemData (latest version) +description: API reference for qiskit_noise_learning.analysis.LinearSystemData in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.analysis.LinearSystemData +--- + + + +# qiskit\_noise\_learning.analysis.LinearSystemData + + + Bases: [`Generic`](https://docs.python.org/3/library/typing.html#typing.Generic)\[`RowIndex`, `ColumnIndex`] + + The linear system to solve and metadata in raw format. + + A linear system `A @ x = b` with axis labels and metadata. + + The row and column labels are of arbitrary hashable types: this class carries no assumptions about what a row or column denotes. In the systems built by [`from_fit()`](#qiskit_noise_learning.analysis.LinearSystemData.from_fit "qiskit_noise_learning.analysis.LinearSystemData.from_fit") the rows are [`Path`](sequences-path "qiskit_noise_learning.sequences.Path") objects and the columns are the fidelity model’s parameter labels. + + The index maps are the authoritative record of how labels correspond to positions in `A`. Anything that needs to align a label-keyed quantity with the arrays should index through `row_index_map` or `column_index_map` rather than rebuilding the correspondence from [`row_labels`](#qiskit_noise_learning.analysis.LinearSystemData.row_labels "qiskit_noise_learning.analysis.LinearSystemData.row_labels") or [`column_labels`](#qiskit_noise_learning.analysis.LinearSystemData.column_labels "qiskit_noise_learning.analysis.LinearSystemData.column_labels"). + + **Parameters** + + * **A** – The matrix with shape `(m, n)`. + * **b** – The target vector length `m`. + * **sigma\_b** – Statistical `1`-sigma uncertainty on `b` per row, with length `m`. + * **row\_diagnostics** – Named per-row quantities recorded by the stages that produced `b`, each an array of length `m` holding `nan` for rows the quantity is undefined for. Keys are the metadata names used upstream; see [`from_fit()`](#qiskit_noise_learning.analysis.LinearSystemData.from_fit "qiskit_noise_learning.analysis.LinearSystemData.from_fit"). + * **row\_index\_map** – A mapping from row labels to their integer row position in `A`. + * **column\_index\_map** – A mapping from column labels to their integer column position in `A`. + * **time\_lb** – Earliest time bound across the rows. + * **time\_ub** – Latest time bound across the rows. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | + | [`__init__`](#qiskit_noise_learning.analysis.LinearSystemData.__init__ "qiskit_noise_learning.analysis.LinearSystemData.__init__")(A, b, sigma\_b, row\_diagnostics, ...) | | + | [`from_fit`](#qiskit_noise_learning.analysis.LinearSystemData.from_fit "qiskit_noise_learning.analysis.LinearSystemData.from_fit")(fit) | Build the linear system arrays from a [`Fit`](analysis-fit "qiskit_noise_learning.analysis.Fit"). | + + ## Attributes + + | | | + | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | + | [`column_labels`](#qiskit_noise_learning.analysis.LinearSystemData.column_labels "qiskit_noise_learning.analysis.LinearSystemData.column_labels") | Column labels, ordered by their column position in `A`. | + | [`row_labels`](#qiskit_noise_learning.analysis.LinearSystemData.row_labels "qiskit_noise_learning.analysis.LinearSystemData.row_labels") | Row labels, ordered by their row position in `A`. | + | `A` | | + | `b` | | + | `sigma_b` | | + | `row_diagnostics` | | + | `row_index_map` | | + | `column_index_map` | | + | `time_lb` | | + | `time_ub` | | + + ### row\_labels + + + Type: [`list`](https://docs.python.org/3/library/stdtypes.html#list)\[`RowIndex`] + + Row labels, ordered by their row position in `A`. + + + ### column\_labels + + + Type: [`list`](https://docs.python.org/3/library/stdtypes.html#list)\[`ColumnIndex`] + + Column labels, ordered by their column position in `A`. + + + ### from\_fit + + + Build the linear system arrays from a [`Fit`](analysis-fit "qiskit_noise_learning.analysis.Fit"). + + Rows are the [`Path`](sequences-path "qiskit_noise_learning.sequences.Path") objects of the [`AggregatedObservableData`](data-aggregated-observable-data "qiskit_noise_learning.data.AggregatedObservableData"), columns are the fidelity model’s parameter labels, and `row_diagnostics` holds every real-valued per-observable metadata entry under the name the producing stage used — for instance `"reduced_chi_squared"` from [`CurveFitObservables`](analysis-curve-fit-observables "qiskit_noise_learning.analysis.CurveFitObservables"). + + **Warns** + + **UserWarning** – If any row’s uncertainty is non-positive or non-finite, giving those rows’ positions in [`row_labels`](#qiskit_noise_learning.analysis.LinearSystemData.row_labels "qiskit_noise_learning.analysis.LinearSystemData.row_labels"). Such a row carries no usable statistical weight, and how it is treated is up to the solver. + + + diff --git a/docs/api/qiskit-noise-learning/generated/analysis-lsq-linear-solve.mdx b/docs/api/qiskit-noise-learning/generated/analysis-lsq-linear-solve.mdx new file mode 100644 index 000000000000..59b58f792d54 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/analysis-lsq-linear-solve.mdx @@ -0,0 +1,42 @@ +--- +title: LSQLinearSolve (latest version) +description: API reference for qiskit_noise_learning.analysis.LSQLinearSolve in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.analysis.LSQLinearSolve +--- + + + +# qiskit\_noise\_learning.analysis.LSQLinearSolve + + + Bases: `ModelSolve` + + Solves for the [`ModelData`](data-model-data "qiskit_noise_learning.data.ModelData") using SciPy’s linear least squares solver. + + See SciPy’s [documentation](https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.lsq_linear.html) for details on the method. See `ModelSolve` for more details about the general responsibility of a model solver in this library. + + **Parameters** + + **\*\*lsq\_linear\_opts** – The options passed on to the SciPy solver. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | + | [`__init__`](#qiskit_noise_learning.analysis.LSQLinearSolve.__init__ "qiskit_noise_learning.analysis.LSQLinearSolve.__init__")(\*\*lsq\_linear\_opts) | | + | `run`(fit) | Run this stage, returning a new [`Fit`](analysis-fit "qiskit_noise_learning.analysis.Fit") with the output level populated. | + + ## Attributes + + | | | + | -------------- | --------------------------------- | + | `input_level` | The data level this stage reads. | + | `output_level` | The data level this stage writes. | + + diff --git a/docs/api/qiskit-noise-learning/generated/analysis-nnls-solve.mdx b/docs/api/qiskit-noise-learning/generated/analysis-nnls-solve.mdx new file mode 100644 index 000000000000..d9b0a04294eb --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/analysis-nnls-solve.mdx @@ -0,0 +1,42 @@ +--- +title: NNLSSolve (latest version) +description: API reference for qiskit_noise_learning.analysis.NNLSSolve in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.analysis.NNLSSolve +--- + + + +# qiskit\_noise\_learning.analysis.NNLSSolve + + + Bases: `ModelSolve` + + Solves for the [`ModelData`](data-model-data "qiskit_noise_learning.data.ModelData") using SciPy’s non-negative least squares solver. + + See SciPy’s [documentation](https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.nnls.html) for details on the method. See `ModelSolve` for more details about the general responsibility of a model solver in this library. + + **Parameters** + + **\*\*nnls\_opts** – The options passed on to the SciPy solver. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- | + | [`__init__`](#qiskit_noise_learning.analysis.NNLSSolve.__init__ "qiskit_noise_learning.analysis.NNLSSolve.__init__")(\*\*nnls\_opts) | | + | `run`(fit) | Run this stage, returning a new [`Fit`](analysis-fit "qiskit_noise_learning.analysis.Fit") with the output level populated. | + + ## Attributes + + | | | + | -------------- | --------------------------------- | + | `input_level` | The data level this stage reads. | + | `output_level` | The data level this stage writes. | + + diff --git a/docs/api/qiskit-noise-learning/generated/analysis-positivity-min-solve.mdx b/docs/api/qiskit-noise-learning/generated/analysis-positivity-min-solve.mdx new file mode 100644 index 000000000000..d5a2940d24d6 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/analysis-positivity-min-solve.mdx @@ -0,0 +1,111 @@ +--- +title: PositivityMinSolve (latest version) +description: API reference for qiskit_noise_learning.analysis.PositivityMinSolve in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.analysis.PositivityMinSolve +--- + + + +# qiskit\_noise\_learning.analysis.PositivityMinSolve + + + Bases: `ModelSolve` + + Solves for the [`ModelData`](data-model-data "qiskit_noise_learning.data.ModelData") while minimizing Pauli-Lindblad rate positivity. + + Requires that the [`Fit`](analysis-fit "qiskit_noise_learning.analysis.Fit") uses a [`PauliLindbladModel`](models-pauli-lindblad-model "qiskit_noise_learning.models.PauliLindbladModel"). + + For a gate set $\mathcal{G}$, let $\{r_{G, P}\}$ denote the Pauli-Lindblad rates over gate-dependent generator sets $\mathcal{K}(G)$, $A$ the design matrix and $b$ the observed data. For the user-specified algorithm parameters: + + * Gate coefficients $\{c_G \in \mathbb{R} : G \in \mathcal{G}\}$, + * Global fit bound $\epsilon > 0$, and + * Local fit bounds $\delta_P$ for each path $P$ measured in the design matrix, + + this class solves the convex optimization problem: + +$$ +\min \sum_{G \in \mathcal{G}} c_G \sum_{P \in \mathcal{K}(G)} \max(0, r_{P, G}) +$$ + + subject to: + + * $\|W (A r - b)\|_2 \leq \epsilon$ + * $|(Ar - b)_i| \leq \delta_i$ for each row $i$ + * $r \geq 0$ (optional) + + See `ModelSolve` for more details about the general responsibility of a model solver in this library. + + The constraint bounds are specified as **policies**: callables that receive the solve-time [`LinearSystemData`](analysis-linear-system-data "qiskit_noise_learning.analysis.LinearSystemData") and return the corresponding bound. + + **Parameters** + + * **coefficients** – Per-gate coefficients for the objective function, as a mapping from gate name to float. + * **epsilon** – Policy returning the tolerance for the overall weighted L2 norm constraint. At least one of `epsilon` or `deltas` must be provided. + * **deltas** – Policy returning per-row tolerances as a mapping from [`Path`](sequences-path "qiskit_noise_learning.sequences.Path") to float. It must cover every row of the linear system, since a row absent from the mapping would be left unconstrained. At least one of `epsilon` or `deltas` must be provided. + * **weights** – Policy returning the weight matrix `W` for the L2 constraint as an [`IndexedMatrix`](math-indexed-matrix "qiskit_noise_learning.math.IndexedMatrix") whose row and column indices are [`Path`](sequences-path "qiskit_noise_learning.sequences.Path") objects. Defaults to identity. A row or column of the linear system absent from `W` is weighted zero, which drops its residual from the norm. Only used when `epsilon` is provided. + * **non\_negative** – Whether to enforce `x >= 0`. + + **Raises** + + * [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError) – If `epsilon`, `deltas` or `weights` is given as a fixed value rather than a policy. Use [`from_constants()`](#qiskit_noise_learning.analysis.PositivityMinSolve.from_constants "qiskit_noise_learning.analysis.PositivityMinSolve.from_constants") for fixed values. + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – At solve time, if the `deltas` or `weights` policy produces a label that is not a row of the linear system, or if `deltas` omits one. + * [**RuntimeError**](https://docs.python.org/3/library/exceptions.html#RuntimeError) – At solve time, if the convex solver does not return a solution, for instance because the constraints are infeasible. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | + | [`__init__`](#qiskit_noise_learning.analysis.PositivityMinSolve.__init__ "qiskit_noise_learning.analysis.PositivityMinSolve.__init__")(coefficients\[, epsilon, deltas, ...]) | | + | [`from_constants`](#qiskit_noise_learning.analysis.PositivityMinSolve.from_constants "qiskit_noise_learning.analysis.PositivityMinSolve.from_constants")(coefficients\[, epsilon, ...]) | Construct from fixed constant bounds instead of data-driven policies. | + | [`from_data_scaled_deltas`](#qiskit_noise_learning.analysis.PositivityMinSolve.from_data_scaled_deltas "qiskit_noise_learning.analysis.PositivityMinSolve.from_data_scaled_deltas")(coefficients\[, ...]) | Build with a delta-only policy based on statistical uncertainty of observables. | + | `run`(fit) | Run this stage, returning a new [`Fit`](analysis-fit "qiskit_noise_learning.analysis.Fit") with the output level populated. | + + ## Attributes + + | | | + | -------------- | --------------------------------- | + | `input_level` | The data level this stage reads. | + | `output_level` | The data level this stage writes. | + + ### from\_constants + + + Construct from fixed constant bounds instead of data-driven policies. + + Each supplied constant is wrapped in a policy that ignores the data and returns it. See the class docstring for the meaning of each argument; here they are fixed values rather than callables. + + + ### from\_data\_scaled\_deltas + + + Build with a delta-only policy based on statistical uncertainty of observables. + + Each row’s tolerance is set from that row’s own statistical uncertainty and its exponential-fit goodness-of-fit. For row $i$, with statistical `1`-sigma `sigma_b` and the reduced chi-squared `chi2_red` read from the `"reduced_chi_squared"` entry of `row_diagnostics`: + +$$ +\begin{split}\mathrm{inflation}_i &= \max(1, \sqrt{\mathrm{chi2\_red}_i}) \\ +\delta_i &= \mathrm{scale} \cdot \mathrm{inflation}_i \cdot \sigma_{b, i}\end{split} +$$ + + Setting `delta_i` proportional to `sigma` follows the Morozov discrepancy principle (allow about `scale` standard deviations of slack). Because `curve_fit` reports `sigma_b` with `absolute_sigma=True`, it is blind to model mismatch; the `sqrt(chi2_red)` factor loosens rows whose exponential fit is poor, and the `max(1, .)` clamp means mismatch can only loosen a row, never tighten it below its statistical uncertainty. Rows with an undefined `chi2_red` (`nan`, e.g. averaged rows), and every row when the system carries no `"reduced_chi_squared"` diagnostic at all, get no inflation. If the model cannot be fit within the resulting tolerances the solve reports an infeasible problem, and `scale` is the knob that loosens every row at once. + + A row whose uncertainty is non-positive or non-finite carries no statistical information to scale by, so rather than being treated as an extremely precise row it is assigned the median tolerance of the rows that do have a usable uncertainty. This keeps such a row in the fit at a typical scale without letting it constrain the solution as a near-equality, and no row’s tolerance ever depends on another row’s uncertainty except through this substitution. + + **Parameters** + + * **coefficients** – Per-gate coefficients for the objective function, as a mapping from gate name to float. + * **scale** – Multiplier on the per-row tolerance, in units of (inflated) standard deviations. + * **non\_negative** – Whether to enforce `x >= 0`. + + **Raises** + + [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – At solve time, if no row of the linear system has a positive, finite uncertainty, leaving nothing to derive tolerances from. + + + diff --git a/docs/api/qiskit-noise-learning/generated/analysis-symmetrize-fidelities.mdx b/docs/api/qiskit-noise-learning/generated/analysis-symmetrize-fidelities.mdx new file mode 100644 index 000000000000..e27c9b175741 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/analysis-symmetrize-fidelities.mdx @@ -0,0 +1,43 @@ +--- +title: SymmetrizeFidelities (latest version) +description: API reference for qiskit_noise_learning.analysis.SymmetrizeFidelities in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.analysis.SymmetrizeFidelities +--- + + + +# qiskit\_noise\_learning.analysis.SymmetrizeFidelities + + + Bases: [`AnalysisStage`](analysis-analysis-stage "qiskit_noise_learning.analysis.analysis_pipeline.AnalysisStage") + + Project generator rates into the fidelity-symmetry null space, gate by gate. + + For each gate, builds commutation matrices of generators against generators and conjugated generators against generators, then projects rates into the null space of their difference. Covariance is zeroed (the iterative projection with clipping is non-linear). + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | -------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | + | [`__init__`](#qiskit_noise_learning.analysis.SymmetrizeFidelities.__init__ "qiskit_noise_learning.analysis.SymmetrizeFidelities.__init__")() | | + | `run`(fit) | Run this stage, returning a new [`Fit`](analysis-fit "qiskit_noise_learning.analysis.Fit") with the output level populated. | + + ### input\_level + + + alias of [`ModelData`](data-model-data "qiskit_noise_learning.data.model_data.ModelData") + + + ### output\_level + + + alias of [`ModelData`](data-model-data "qiskit_noise_learning.data.model_data.ModelData") + + + diff --git a/docs/api/qiskit-noise-learning/generated/analysis-symmetrize-generators.mdx b/docs/api/qiskit-noise-learning/generated/analysis-symmetrize-generators.mdx new file mode 100644 index 000000000000..069bb7ca7d47 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/analysis-symmetrize-generators.mdx @@ -0,0 +1,43 @@ +--- +title: SymmetrizeGenerators (latest version) +description: API reference for qiskit_noise_learning.analysis.SymmetrizeGenerators in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.analysis.SymmetrizeGenerators +--- + + + +# qiskit\_noise\_learning.analysis.SymmetrizeGenerators + + + Bases: [`AnalysisStage`](analysis-analysis-stage "qiskit_noise_learning.analysis.analysis_pipeline.AnalysisStage") + + Project generator rates to satisfy conjugation symmetry, gate by gate. + + For each gate, finds the pairs of generators that map to each under its conjugate action. The covariance is propagated through averaging. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | -------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | + | [`__init__`](#qiskit_noise_learning.analysis.SymmetrizeGenerators.__init__ "qiskit_noise_learning.analysis.SymmetrizeGenerators.__init__")() | | + | `run`(fit) | Run this stage, returning a new [`Fit`](analysis-fit "qiskit_noise_learning.analysis.Fit") with the output level populated. | + + ### input\_level + + + alias of [`ModelData`](data-model-data "qiskit_noise_learning.data.model_data.ModelData") + + + ### output\_level + + + alias of [`ModelData`](data-model-data "qiskit_noise_learning.data.model_data.ModelData") + + + diff --git a/docs/api/qiskit-noise-learning/generated/analysis-zero-post-select.mdx b/docs/api/qiskit-noise-learning/generated/analysis-zero-post-select.mdx new file mode 100644 index 000000000000..316afe3d3a20 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/analysis-zero-post-select.mdx @@ -0,0 +1,63 @@ +--- +title: ZeroPostSelect (latest version) +description: API reference for qiskit_noise_learning.analysis.ZeroPostSelect in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.analysis.ZeroPostSelect +--- + + + +# qiskit\_noise\_learning.analysis.ZeroPostSelect + + + Bases: [`AnalysisStage`](analysis-analysis-stage "qiskit_noise_learning.analysis.analysis_pipeline.AnalysisStage") + + Apply a mask to raw data based on whether bit values are all False. + + This post-selection stage identifies cregs and masks shots whose bit patterns indicate failure. It can be configured to operate in one of two modes: + + * `"node"`: Shots are discarded if any bit in the identified creg is True. + + * **`"edge"`: Shots are discarded if there exists a pair of neighbouring qubits in the** + + coupling map for which both bits are True. + + **Parameters** + + * **creg\_identifier** – A callable that, given a list of present creg names, returns an iterator over creg names to post-select on. Defaults to identifying cregs with naming pattern `"*_ps"`. + * **mode** – Post-selection mode; either `"node"` or `"edge"`. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | --------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | + | [`__init__`](#qiskit_noise_learning.analysis.ZeroPostSelect.__init__ "qiskit_noise_learning.analysis.ZeroPostSelect.__init__")(\[creg\_identifier, mode]) | | + | `run`(fit) | Run this stage, returning a new [`Fit`](analysis-fit "qiskit_noise_learning.analysis.Fit") with the output level populated. | + + ## Attributes + + | | | + | ------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------- | + | `creg_identifier` | | + | [`input_level`](#qiskit_noise_learning.analysis.ZeroPostSelect.input_level "qiskit_noise_learning.analysis.ZeroPostSelect.input_level") | The data level this stage reads. | + | `mode` | | + | [`output_level`](#qiskit_noise_learning.analysis.ZeroPostSelect.output_level "qiskit_noise_learning.analysis.ZeroPostSelect.output_level") | The data level this stage writes. | + + ### input\_level + + + The data level this stage reads. + + + ### output\_level + + + The data level this stage writes. + + + diff --git a/docs/api/qiskit-noise-learning/generated/circuit-generator-executor-circuit-generator.mdx b/docs/api/qiskit-noise-learning/generated/circuit-generator-executor-circuit-generator.mdx new file mode 100644 index 000000000000..786fbc51c39e --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/circuit-generator-executor-circuit-generator.mdx @@ -0,0 +1,102 @@ +--- +title: ExecutorCircuitGenerator (latest version) +description: API reference for qiskit_noise_learning.circuit_generator.ExecutorCircuitGenerator in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.circuit_generator.ExecutorCircuitGenerator +--- + + + +# qiskit\_noise\_learning.circuit\_generator.ExecutorCircuitGenerator + + + Bases: `CircuitGenerator`\[[`QuantumProgram`](/docs/api/qiskit-ibm-runtime/quantum-program-quantum-program "(in Qiskit Runtime IBM Client)"), [`ExecutorDataMapper`](circuit-generator-executor-data-mapper "qiskit_noise_learning.circuit_generator.executor_data_mapper.ExecutorDataMapper"), [`QuantumProgramResult`](/docs/api/qiskit-ibm-runtime/results-quantum-program-result "(in Qiskit Runtime IBM Client)")] + + A circuit generator that converts sequences of Qiskit gates into a samplex items. + + **Parameters** + + * **gate\_set** – The Qiskit gate set that this generator constructs against. + * **creg\_prefix** – The prefix assigned to all creg names used in instruction sequence measurements. Defaults to `"meas"`. + * **local\_clifford\_ref\_prefix** – The prefix assigned to all local Clifford parameter references in template circuits. Defaults to `"c"`. + * **pass\_manager** – An optional `PassManager` to apply to all template circuits produced by [`ExecutorCircuitGenerator.generate()`](#qiskit_noise_learning.circuit_generator.ExecutorCircuitGenerator.generate "qiskit_noise_learning.circuit_generator.ExecutorCircuitGenerator.generate"). + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | + | [`__init__`](#qiskit_noise_learning.circuit_generator.ExecutorCircuitGenerator.__init__ "qiskit_noise_learning.circuit_generator.ExecutorCircuitGenerator.__init__")(gate\_set\[, creg\_prefix, ...]) | | + | [`collect`](#qiskit_noise_learning.circuit_generator.ExecutorCircuitGenerator.collect "qiskit_noise_learning.circuit_generator.ExecutorCircuitGenerator.collect")(result, data\_mapper) | Coerce data from a specific execution framework into a canonical form. | + | [`generate`](#qiskit_noise_learning.circuit_generator.ExecutorCircuitGenerator.generate "qiskit_noise_learning.circuit_generator.ExecutorCircuitGenerator.generate")(experiment) | Generate a new experimental task from the provided experiment. | + | [`generate_samplex_item`](#qiskit_noise_learning.circuit_generator.ExecutorCircuitGenerator.generate_samplex_item "qiskit_noise_learning.circuit_generator.ExecutorCircuitGenerator.generate_samplex_item")(instruction\_sequences, ...) | Generate a samplex item from instruction sequences with the same structure. | + | [`generate_samplex_items`](#qiskit_noise_learning.circuit_generator.ExecutorCircuitGenerator.generate_samplex_items "qiskit_noise_learning.circuit_generator.ExecutorCircuitGenerator.generate_samplex_items")(...) | Generate samplex items from instruction sequences. | + | `partition`(sequences) | Partition the positions of instruction sequences that can share a generation output. | + + ## Attributes + + | | | + | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | + | [`gate_set`](#qiskit_noise_learning.circuit_generator.ExecutorCircuitGenerator.gate_set "qiskit_noise_learning.circuit_generator.ExecutorCircuitGenerator.gate_set") | The gate set this generator constructs against. | + + ### gate\_set + + + Type: [`QiskitGateSet`](gate-sets-qiskit-gate-set "qiskit_noise_learning.gate_sets.qiskit_gate_set.QiskitGateSet") + + The gate set this generator constructs against. + + + ### collect + + + Coerce data from a specific execution framework into a canonical form. + + + ### generate + + + Generate a new experimental task from the provided experiment. + + + ### generate\_samplex\_items + + + Generate samplex items from instruction sequences. + + **Parameters** + + * **instruction\_sequences** – The instruction sequences to generate circuits for. + * **num\_randomizations** – The number of randomizations per sequence. + + **Returns** + + A tuple of samplex items and a data mapper. + + + ### generate\_samplex\_item + + + Generate a samplex item from instruction sequences with the same structure. + + **Parameters** + + * **instruction\_sequences** – The similar instruction sequences to generate. + * **num\_randomizations** – The number of randomizations per sequence. + + **Returns** + + A samplex item where the order of the arguments correspond to the order of `instruction_sequences`, an ordered list of creg names, and a dictionary mapping creg names to the ordered list of qubit indices they measure. + + **Raises** + + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – If `instruction_sequences` is empty. + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – If any of the instruction sequences is not complete. + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – If any of the instruction sequences have different structure. + + + diff --git a/docs/api/qiskit-noise-learning/generated/circuit-generator-executor-data-mapper.mdx b/docs/api/qiskit-noise-learning/generated/circuit-generator-executor-data-mapper.mdx new file mode 100644 index 000000000000..1b9c3c5ec55f --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/circuit-generator-executor-data-mapper.mdx @@ -0,0 +1,120 @@ +--- +title: ExecutorDataMapper (latest version) +description: API reference for qiskit_noise_learning.circuit_generator.ExecutorDataMapper in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.circuit_generator.ExecutorDataMapper +--- + + + +# qiskit\_noise\_learning.circuit\_generator.ExecutorDataMapper + + + Bases: [`object`](https://docs.python.org/3/library/functions.html#object) + + Map executor results into standard results. + + As instruction sequences with similar structure are generated together with a single template circuit and different samplex arguments, the order of input sequences to [`ExecutorCircuitGenerator.generate()`](circuit-generator-executor-circuit-generator#generate "qiskit_noise_learning.circuit_generator.ExecutorCircuitGenerator.generate") is not preserved during execution. This class contains properties to format the results of a [`qiskit_ibm_runtime.results.QuantumProgramResult`](/docs/api/qiskit-ibm-runtime/results-quantum-program-result "(in Qiskit Runtime IBM Client)") to the order of the input sequences. + + **Parameters** + + * **item\_sequence\_indices** – For each program item, an ordered list of instruction sequence indices. Position in the list corresponds to the configuration index within the result item. + * **creg\_names** – The name of classical registers in each program item. + * **measurement\_maps** – For each program item, a dictionary from creg names to an ordered array of measured qubit indices. + * **instruction\_sequences** – The instruction sequences associated with the data. + * **num\_randomizations** – The number of randomizations used per experiment. + * **fidelity\_model** – The fidelity model used in the experiment. + * **paths** – The analysis paths. + * **relations** – Path-to-sequence relations. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | + | [`__init__`](#qiskit_noise_learning.circuit_generator.ExecutorDataMapper.__init__ "qiskit_noise_learning.circuit_generator.ExecutorDataMapper.__init__")(item\_sequence\_indices, creg\_names, ...) | | + + ## Attributes + + | | | + | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | + | [`creg_names`](#qiskit_noise_learning.circuit_generator.ExecutorDataMapper.creg_names "qiskit_noise_learning.circuit_generator.ExecutorDataMapper.creg_names") | List of names of the classical registers contained in the results. | + | [`fidelity_model`](#qiskit_noise_learning.circuit_generator.ExecutorDataMapper.fidelity_model "qiskit_noise_learning.circuit_generator.ExecutorDataMapper.fidelity_model") | The fidelity model used in the experiment. | + | [`instruction_sequences`](#qiskit_noise_learning.circuit_generator.ExecutorDataMapper.instruction_sequences "qiskit_noise_learning.circuit_generator.ExecutorDataMapper.instruction_sequences") | The instruction sequences corresponding to the sequence indices in the sequence map. | + | [`item_sequence_indices`](#qiskit_noise_learning.circuit_generator.ExecutorDataMapper.item_sequence_indices "qiskit_noise_learning.circuit_generator.ExecutorDataMapper.item_sequence_indices") | Per program item, the instruction sequence indices corresponding to each config. | + | [`measurement_maps`](#qiskit_noise_learning.circuit_generator.ExecutorDataMapper.measurement_maps "qiskit_noise_learning.circuit_generator.ExecutorDataMapper.measurement_maps") | A per-program-item map from creg name to an ordered array of measured qubit indices. | + | [`num_randomizations`](#qiskit_noise_learning.circuit_generator.ExecutorDataMapper.num_randomizations "qiskit_noise_learning.circuit_generator.ExecutorDataMapper.num_randomizations") | The number of randomizations used per experiment. | + | [`paths`](#qiskit_noise_learning.circuit_generator.ExecutorDataMapper.paths "qiskit_noise_learning.circuit_generator.ExecutorDataMapper.paths") | The analysis paths. | + | [`relations`](#qiskit_noise_learning.circuit_generator.ExecutorDataMapper.relations "qiskit_noise_learning.circuit_generator.ExecutorDataMapper.relations") | Path-to-sequence relations. | + + ### item\_sequence\_indices + + + Type: [`list`](https://docs.python.org/3/library/stdtypes.html#list)\[[`list`](https://docs.python.org/3/library/stdtypes.html#list)\[[`int`](https://docs.python.org/3/library/functions.html#int)]] + + Per program item, the instruction sequence indices corresponding to each config. + + + ### creg\_names + + + Type: [`list`](https://docs.python.org/3/library/stdtypes.html#list)\[[`list`](https://docs.python.org/3/library/stdtypes.html#list)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str)]] + + List of names of the classical registers contained in the results. + + The list at a given index corresponds to names expected in the data of the [`qiskit_ibm_runtime.results.QuantumProgramResult`](/docs/api/qiskit-ibm-runtime/results-quantum-program-result "(in Qiskit Runtime IBM Client)") at the same index. + + + ### measurement\_maps + + + Type: [`list`](https://docs.python.org/3/library/stdtypes.html#list)\[[`dict`](https://docs.python.org/3/library/stdtypes.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`ndarray`](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray)\[[`int`](https://docs.python.org/3/library/functions.html#int)]]] + + A per-program-item map from creg name to an ordered array of measured qubit indices. + + + ### instruction\_sequences + + + Type: [`list`](https://docs.python.org/3/library/stdtypes.html#list) + + The instruction sequences corresponding to the sequence indices in the sequence map. + + + ### num\_randomizations + + + Type: [`int`](https://docs.python.org/3/library/functions.html#int) + + The number of randomizations used per experiment. + + + ### fidelity\_model + + + Type: [`LinearMap`](math-linear-map "qiskit_noise_learning.math.linear_map.LinearMap")\[[`Hashable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Hashable), [`FidelityIndex`](sequences-fidelity-index "qiskit_noise_learning.sequences.fidelity_index.FidelityIndex")] | [`None`](https://docs.python.org/3/library/constants.html#None) + + The fidelity model used in the experiment. + + + ### paths + + + Type: [`list`](https://docs.python.org/3/library/stdtypes.html#list)\[[`Path`](sequences-path "qiskit_noise_learning.sequences.path.Path")] | [`None`](https://docs.python.org/3/library/constants.html#None) + + The analysis paths. + + + ### relations + + + Type: [`set`](https://docs.python.org/3/library/stdtypes.html#set)\[[`tuple`](https://docs.python.org/3/library/stdtypes.html#tuple)\[[`int`](https://docs.python.org/3/library/functions.html#int), [`int`](https://docs.python.org/3/library/functions.html#int)]] | [`None`](https://docs.python.org/3/library/constants.html#None) + + Path-to-sequence relations. + + + diff --git a/docs/api/qiskit-noise-learning/generated/data-aggregated-observable-data.mdx b/docs/api/qiskit-noise-learning/generated/data-aggregated-observable-data.mdx new file mode 100644 index 000000000000..b421ee99d142 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/data-aggregated-observable-data.mdx @@ -0,0 +1,109 @@ +--- +title: AggregatedObservableData (latest version) +description: API reference for qiskit_noise_learning.data.AggregatedObservableData in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.data.AggregatedObservableData +--- + + + +# qiskit\_noise\_learning.data.AggregatedObservableData + + + Bases: [`LeveledData`](data-leveled-data "qiskit_noise_learning.data.leveled_data.LeveledData") + + Per-path estimates obtained by aggregating [`ObservableData`](data-observable-data "qiskit_noise_learning.data.ObservableData"). + + This class holds a single estimate per observable, obtained by collapsing the per-randomization structure of [`ObservableData`](data-observable-data "qiskit_noise_learning.data.ObservableData"). Each observable estimate is labelled by an unbound path and a corresponding fragment depth. A non-negative fragment depth corresponds to labelling by a bound path with that depth, and a fragment depth of `-1` signals that the estimate corresponds to a genuinely unbound path. For a non-negative fragment depth, the estimate value corresponds to the product of all fidelities in the path, and the estimate for a fragment depth of `-1` corresponds to the product of the fidelities in the repeatable fragment. + + * Data variables: + + > * `estimate_values`: A 1d float array of per-observable estimates, with dimensions `("observable",)`. + > * `estimate_std`: A 1d array of standard deviations for the estimates, with dimensions `("observable",)`. + > * `time_lbs`: A lower bound on the data collection for each observable, with dimensions `("observable",)`. + > * `time_ubs`: An upper bound on the data collection for each observable, with dimensions `("observable",)`. + > * `metadata`: A 1d object array of any additional per-observable data, with dimensions `("observable",)`. + + * Coordinates: + + > * `unbound_path`: A 1d array of unbound [`Path`](sequences-path "qiskit_noise_learning.sequences.Path") instances labelling each observable, with dimensions `("observable",)`. + > * `fragment_depth`: A 1d array of type `int` specifying the fragment depth associated to the observable. A value of `-1` indicates an estimate of only the `repeatable_fragment` of the path. + + **Parameters** + + **dataset** – A `Dataset` with the above formatting. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- | + | [`__init__`](#qiskit_noise_learning.data.AggregatedObservableData.__init__ "qiskit_noise_learning.data.AggregatedObservableData.__init__")(dataset) | | + | [`filter_time`](#qiskit_noise_learning.data.AggregatedObservableData.filter_time "qiskit_noise_learning.data.AggregatedObservableData.filter_time")(lb, ub) | Filter to data gathered within the time bounds. | + | [`from_arrays`](#qiskit_noise_learning.data.AggregatedObservableData.from_arrays "qiskit_noise_learning.data.AggregatedObservableData.from_arrays")(unbound\_paths, fragment\_depths, ...) | Instantiate from data specified as arrays in standard containers. | + | [`merge`](#qiskit_noise_learning.data.AggregatedObservableData.merge "qiskit_noise_learning.data.AggregatedObservableData.merge")(other) | Merge the data from self and other into a single instance. | + + ## Attributes + + | | | + | --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | + | [`dataset`](#qiskit_noise_learning.data.AggregatedObservableData.dataset "qiskit_noise_learning.data.AggregatedObservableData.dataset") | The aggregated observable data set. | + + ### dataset + + + Type: `Dataset` + + The aggregated observable data set. + + + ### from\_arrays + + + Instantiate from data specified as arrays in standard containers. + + **Parameters** + + * **unbound\_paths** – A list of unbound paths (with `fragment_depth=None`). + * **fragment\_depths** – A list of fragment depths, with `-1` indicating the corresponding estimate is in reference to only the repeatable fragment of the corresponding path. + * **estimate\_values** – A 1d array of per-observable estimates. + * **estimate\_std** – A 1d array of standard deviations. + * **time\_lbs** – A 1d array of time lower bounds. + * **time\_ubs** – A 1d array of time upper bounds. + * **metadata** – Any additional data associated with a given observable. + + + ### merge + + + Merge the data from self and other into a single instance. + + **Parameters** + + **other** – The other data. + + **Returns** + + A new instance containing both data sets. + + + ### filter\_time + + + Filter to data gathered within the time bounds. + + **Parameters** + + * **lb** – The time lower bound (inclusive). + * **ub** – The time upper bound (inclusive). + + **Returns** + + The time filtered version of self. + + + diff --git a/docs/api/qiskit-noise-learning/generated/data-leveled-data.mdx b/docs/api/qiskit-noise-learning/generated/data-leveled-data.mdx new file mode 100644 index 000000000000..151ed435dc56 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/data-leveled-data.mdx @@ -0,0 +1,28 @@ +--- +title: LeveledData (latest version) +description: API reference for qiskit_noise_learning.data.LeveledData in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.data.LeveledData +--- + + + +# qiskit\_noise\_learning.data.LeveledData + + + Bases: [`object`](https://docs.python.org/3/library/functions.html#object) + + Marker base class for data at a specific level of the analysis hierarchy. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ------------------------------------------------------------------------------------------------------------------ | - | + | [`__init__`](#qiskit_noise_learning.data.LeveledData.__init__ "qiskit_noise_learning.data.LeveledData.__init__")() | | + + diff --git a/docs/api/qiskit-noise-learning/generated/data-model-data.mdx b/docs/api/qiskit-noise-learning/generated/data-model-data.mdx new file mode 100644 index 000000000000..7b9f281ac5da --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/data-model-data.mdx @@ -0,0 +1,82 @@ +--- +title: ModelData (latest version) +description: API reference for qiskit_noise_learning.data.ModelData in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.data.ModelData +--- + + + +# qiskit\_noise\_learning.data.ModelData + + + Bases: [`LeveledData`](data-leveled-data "qiskit_noise_learning.data.leveled_data.LeveledData"), [`Generic`](https://docs.python.org/3/library/typing.html#typing.Generic)\[`ParameterIndex`] + + Results from fitting, backed by an xarray Dataset. + + The dataset has data variables: + + * `parameter_values`: 1D array with dimension `parameter_index`. + * `covariance`: 2D array with dimensions `(parameter_row_index, parameter_col_index)`. + + The `parameter_index`, `parameter_row_index`, and `parameter_col_index` coordinates all share the same parameter labels. Additional fit metadata is stored in dataset attrs. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | + | [`__init__`](#qiskit_noise_learning.data.ModelData.__init__ "qiskit_noise_learning.data.ModelData.__init__")(dataset) | | + | [`filter_time`](#qiskit_noise_learning.data.ModelData.filter_time "qiskit_noise_learning.data.ModelData.filter_time")(lb, ub) | Filter to data gathered within the time bounds. | + | [`from_arrays`](#qiskit_noise_learning.data.ModelData.from_arrays "qiskit_noise_learning.data.ModelData.from_arrays")(parameter\_indices, ...\[, metadata]) | Instantiate from data specified as arrays in standard containers. | + + ## Attributes + + | | | + | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------- | + | `dataset` | | + | [`metadata`](#qiskit_noise_learning.data.ModelData.metadata "qiskit_noise_learning.data.ModelData.metadata") | Metadata describing the model parameter fit. | + + ### from\_arrays + + + Instantiate from data specified as arrays in standard containers. + + **Parameters** + + * **parameter\_indices** – A list of `ParameterIndex` instances. + * **parameter\_values** – A 1d array of floats indicating parameter values. + * **covariance** – A 2d array of floats indicating the covariances of the parameter values. + * **time\_lbs** – A 1d array of data acquisition time lower bounds for each parameter estimate. + * **time\_ubs** – A 1d array of data acquisition time upper bounds for each parameter estimate. + * **metadata** – Any metadata to attach to the dataset. + + + ### metadata + + + Type: [`dict`](https://docs.python.org/3/library/stdtypes.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] + + Metadata describing the model parameter fit. + + + ### filter\_time + + + Filter to data gathered within the time bounds. + + **Parameters** + + * **lb** – The time lower bound (inclusive). + * **ub** – The time upper bound (inclusive). + + **Returns** + + The time filtered version of self. + + + diff --git a/docs/api/qiskit-noise-learning/generated/data-observable-data.mdx b/docs/api/qiskit-noise-learning/generated/data-observable-data.mdx new file mode 100644 index 000000000000..728b8af2e6f9 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/data-observable-data.mdx @@ -0,0 +1,124 @@ +--- +title: ObservableData (latest version) +description: API reference for qiskit_noise_learning.data.ObservableData in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.data.ObservableData +--- + + + +# qiskit\_noise\_learning.data.ObservableData + + + Bases: [`LeveledData`](data-leveled-data "qiskit_noise_learning.data.leveled_data.LeveledData") + + A collection of calculated expectation values. + + This class is a wrapper around an XArray `Dataset`, containing the following data: + + * Data variables: + + > * `observable_values`: Observables computed from single `InstructionSequence` and `Path` pairs at a given fragment depth, separated by randomizations. Has dimensions `("observable", "randomization")`. `np.nan` values are assumed to be due to raggedness of the `"randomization"` dimension for different observables. + > * `time_lbs`: Lower bound on data acquisition times, with dimensions `("observable", "randomization")`, and of type `"datetime64[us]"`. + > * `time_ubs`: Upper bound on data acquisition times, with dimensions `("observable", "randomization")`, and of type `"datetime64[us]"`. + + * Coordinates: + + > * `unbound_path`: The unbound path (with `fragment_depth=None`) for each observable, along dimension `("observable",)`, of type `Path`. + > * `fragment_depth`: Integer array of fragment depths along dimension `("observable",)`. + + **Parameters** + + **dataset** – A dataset with the above formatting. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | + | [`__init__`](#qiskit_noise_learning.data.ObservableData.__init__ "qiskit_noise_learning.data.ObservableData.__init__")(dataset) | | + | [`filter_time`](#qiskit_noise_learning.data.ObservableData.filter_time "qiskit_noise_learning.data.ObservableData.filter_time")(lb, ub) | Filter to data gathered within the time bounds. | + | [`from_arrays`](#qiskit_noise_learning.data.ObservableData.from_arrays "qiskit_noise_learning.data.ObservableData.from_arrays")(unbound\_paths, fragment\_depths, ...) | Instantiate from data specified as arrays. | + | [`merge`](#qiskit_noise_learning.data.ObservableData.merge "qiskit_noise_learning.data.ObservableData.merge")(other) | Merge observable data into a single instance. | + + ## Attributes + + | | | + | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | + | `dataset` | | + | [`observable_values`](#qiskit_noise_learning.data.ObservableData.observable_values "qiskit_noise_learning.data.ObservableData.observable_values") | Observables data array. | + | [`time_lbs`](#qiskit_noise_learning.data.ObservableData.time_lbs "qiskit_noise_learning.data.ObservableData.time_lbs") | Time lower bounds data array. | + | [`time_ubs`](#qiskit_noise_learning.data.ObservableData.time_ubs "qiskit_noise_learning.data.ObservableData.time_ubs") | Time upper bounds data array. | + + ### from\_arrays + + + Instantiate from data specified as arrays. + + **Parameters** + + * **unbound\_paths** – The unbound paths corresponding to the observables. + * **fragment\_depths** – The fragment depths for each observable. + * **observable\_values** – A 2d numpy array of `floats` with axes `("observable", "randomization")`. + * **time\_lbs** – A lower bound on the data collection time for each observable and randomization. Has axes `("observable", "randomization")`. + * **time\_ubs** – Upper bounds on the data collection time for each observable and randomization. Has axes `("observable", "randomization")`. + + + ### observable\_values + + + Type: `DataArray` + + Observables data array. + + + ### time\_lbs + + + Type: `DataArray` + + Time lower bounds data array. + + + ### time\_ubs + + + Type: `DataArray` + + Time upper bounds data array. + + + ### merge + + + Merge observable data into a single instance. + + **Parameters** + + **other** – The other observable data set. + + **Returns** + + The merged data. + + + ### filter\_time + + + Filter to data gathered within the time bounds. + + **Parameters** + + * **lb** – The time lower bound (inclusive). + * **ub** – The time upper bound (inclusive). + + **Returns** + + The time filtered version of self. + + + diff --git a/docs/api/qiskit-noise-learning/generated/data-raw-data.mdx b/docs/api/qiskit-noise-learning/generated/data-raw-data.mdx new file mode 100644 index 000000000000..3b047bc00fa3 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/data-raw-data.mdx @@ -0,0 +1,121 @@ +--- +title: RawData (latest version) +description: API reference for qiskit_noise_learning.data.RawData in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.data.RawData +--- + + + +# qiskit\_noise\_learning.data.RawData + + + Bases: [`LeveledData`](data-leveled-data "qiskit_noise_learning.data.leveled_data.LeveledData") + + Raw experimental outcome data associated with instruction sequences and classical registers. + + This class is a wrapper around a 1-layer deep XArray `DataTree` with arbitrary string keys. Each leaf dataset contains: + + * Data variables: + + > * `data`: The raw boolean data with dimensions `("randomization", "shot", "bit")`. + > * `data_mask`: A boolean mask with dimensions `("randomization", "shot")`. Handles potential raggedness in the `"shot"` dimension across different randomizations. + > * `measurement_flips`: A boolean array of measurement flips with dimensions `("randomization", "bit")`. + > * `time_lbs`: Lower bound on data acquisition times, with dimensions `("randomization",)`, of type `"datetime64[us]"`. + > * `time_ubs`: Upper bound on data acquisition times, with dimensions `("randomization",)`, of type `"datetime64[us]"`. + + * Coordinates: + + > * `unbound_instruction_sequence`: The unbound instruction sequence for the data, along dimension `("randomization",)`, of type `InstructionSequence`. + > * `fragment_depth`: Integer array of fragment depths along dimension `("randomization",)`. + + * Attrs: + + > * `creg_names`: Ordered list of classical register names. + > * `measurement_map`: Dictionary mapping creg names to arrays of measured qubit indices. + > * `creg_bit_boundaries`: Dictionary mapping creg names to `(start_idx, end_idx)` tuples indicating the slice of the `"bit"` dimension for that register. + + Datasets are grouped by creg metadata: two datasets with the same `creg_names` and `measurement_map` are merged along the `"randomization"` dimension. + + **Parameters** + + **datatree** – A datatree in the above format. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | + | [`__init__`](#qiskit_noise_learning.data.RawData.__init__ "qiskit_noise_learning.data.RawData.__init__")(datatree) | | + | [`filter_time`](#qiskit_noise_learning.data.RawData.filter_time "qiskit_noise_learning.data.RawData.filter_time")(lb, ub) | Filter to data gathered within the time bounds. | + | [`from_arrays`](#qiskit_noise_learning.data.RawData.from_arrays "qiskit_noise_learning.data.RawData.from_arrays")(creg\_names, measurement\_map, ...) | Instantiate from data specified as arrays. | + | [`merge`](#qiskit_noise_learning.data.RawData.merge "qiskit_noise_learning.data.RawData.merge")(other) | Merge with another raw data set. | + + ## Attributes + + | | | + | -------------------------------------------------------------------------------------------------------- | -------------- | + | [`datatree`](#qiskit_noise_learning.data.RawData.datatree "qiskit_noise_learning.data.RawData.datatree") | The data tree. | + + ### datatree + + + Type: `DataTree` + + The data tree. + + + ### from\_arrays + + + Instantiate from data specified as arrays. + + All instruction sequences must share the same creg structure (same `creg_names` and `measurement_map`). The resulting `RawData` contains a single-leaf datatree. + + **Parameters** + + * **creg\_names** – Ordered list of classical register names. + * **measurement\_map** – Dictionary mapping creg names to arrays of measured physical qubit indices. + * **instruction\_sequences** – The list of instruction sequences used to generate the experiments. + * **data** – A list of outcome data for each instruction sequence for all classical registers. The data has dimensions `("randomization", "shot", "bit")`. Bits are ordered according to `creg_names` order, with each creg’s bits contiguous. + * **measurement\_flips** – A list of measurement flips to be applied to the data for each instruction sequence. Dimensions are `("randomization", "bit")`. + * **time\_lbs** – A lower bound on the data collection time for each randomization for a given instruction sequence. The dimensions are `("randomization",)`. + * **time\_ubs** – An upper bound on the data collection time for each randomization for a given instruction sequence. The dimensions are `("randomization",)`. + + + ### merge + + + Merge with another raw data set. + + Datasets with matching creg metadata (`creg_names` and `measurement_map`) are concatenated along the `"randomization"` dimension. Potential raggedness of the `"shot"` dimension is handled via the `"data_mask"` data variable. + + **Parameters** + + **other** – The other raw dataset. + + **Returns** + + The merged data. + + + ### filter\_time + + + Filter to data gathered within the time bounds. + + **Parameters** + + * **lb** – The time lower bound (inclusive). + * **ub** – The time upper bound (inclusive). + + **Returns** + + The time filtered version of self. + + + diff --git a/docs/api/qiskit-noise-learning/generated/experiment-builder-add-instruction-sequences.mdx b/docs/api/qiskit-noise-learning/generated/experiment-builder-add-instruction-sequences.mdx new file mode 100644 index 000000000000..a063a1e22ea6 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/experiment-builder-add-instruction-sequences.mdx @@ -0,0 +1,45 @@ +--- +title: AddInstructionSequences (latest version) +description: API reference for qiskit_noise_learning.experiment_builder.AddInstructionSequences in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.experiment_builder.AddInstructionSequences +--- + + + +# qiskit\_noise\_learning.experiment\_builder.AddInstructionSequences + + + Bases: [`ExperimentBuilderStage`](experiment-builder-experiment-builder-stage "qiskit_noise_learning.experiment_builder.experiment_builder_stage.ExperimentBuilderStage") + + Add instruction sequences to an experiment. + + This is both a concrete stage (pass sequences directly) and the base class for sequence-generator stages that compute sequences from the experiment at runtime. + + Subclasses should override `_generate_sequences()` to return sequences and multipliers computed from the experiment’s data. + + **Parameters** + + * **instruction\_sequences** – The instruction sequences to add. + * **randomization\_multipliers** – Per-sequence randomization multipliers. If `None`, defaults to all ones. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | + | [`__init__`](#qiskit_noise_learning.experiment_builder.AddInstructionSequences.__init__ "qiskit_noise_learning.experiment_builder.AddInstructionSequences.__init__")(instruction\_sequences\[, ...]) | | + | `run`(experiment) | Validate required fields, then apply this stage. | + + ## Attributes + + | | | + | ------------------ | - | + | `populates_fields` | | + | `required_fields` | | + + diff --git a/docs/api/qiskit-noise-learning/generated/experiment-builder-add-paths.mdx b/docs/api/qiskit-noise-learning/generated/experiment-builder-add-paths.mdx new file mode 100644 index 000000000000..356da1a29b7e --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/experiment-builder-add-paths.mdx @@ -0,0 +1,44 @@ +--- +title: AddPaths (latest version) +description: API reference for qiskit_noise_learning.experiment_builder.AddPaths in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.experiment_builder.AddPaths +--- + + + +# qiskit\_noise\_learning.experiment\_builder.AddPaths + + + Bases: [`ExperimentBuilderStage`](experiment-builder-experiment-builder-stage "qiskit_noise_learning.experiment_builder.experiment_builder_stage.ExperimentBuilderStage") + + Add paths to an experiment. + + This is both a concrete stage (pass path iterators directly) and the base class for path-generator stages that compute paths from the experiment at runtime. + + Subclasses should override `_generate_paths()` to yield paths computed from the experiment’s fidelity model or other data. + + **Parameters** + + **path\_iterators** – One or more iterators of [`Path`](sequences-path "qiskit_noise_learning.sequences.Path") instances. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | + | [`__init__`](#qiskit_noise_learning.experiment_builder.AddPaths.__init__ "qiskit_noise_learning.experiment_builder.AddPaths.__init__")(\*path\_iterators) | | + | `run`(experiment) | Validate required fields, then apply this stage. | + + ## Attributes + + | | | + | ------------------ | - | + | `populates_fields` | | + | `required_fields` | | + + diff --git a/docs/api/qiskit-noise-learning/generated/experiment-builder-bind-fragment-depths.mdx b/docs/api/qiskit-noise-learning/generated/experiment-builder-bind-fragment-depths.mdx new file mode 100644 index 000000000000..0897b59f094a --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/experiment-builder-bind-fragment-depths.mdx @@ -0,0 +1,42 @@ +--- +title: BindFragmentDepths (latest version) +description: API reference for qiskit_noise_learning.experiment_builder.BindFragmentDepths in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.experiment_builder.BindFragmentDepths +--- + + + +# qiskit\_noise\_learning.experiment\_builder.BindFragmentDepths + + + Bases: [`ExperimentBuilderStage`](experiment-builder-experiment-builder-stage "qiskit_noise_learning.experiment_builder.experiment_builder_stage.ExperimentBuilderStage") + + Expand unbound instruction sequences at the given fragment depths. + + Each unbound instruction sequence is replaced by a bound copy at each fragment depth. Bound sequences are kept as-is. The `randomization_multipliers` and `relations` are updated accordingly: the multiplier of an unbound sequence is propagated to all its bound expansions, and any relation pointing to an unbound sequence is fanned out to all the resulting bound sequences. + + **Parameters** + + **fragment\_depths** – The fragment depths at which to bind unbound sequences. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | + | [`__init__`](#qiskit_noise_learning.experiment_builder.BindFragmentDepths.__init__ "qiskit_noise_learning.experiment_builder.BindFragmentDepths.__init__")(fragment\_depths) | | + | `run`(experiment) | Validate required fields, then apply this stage. | + + ## Attributes + + | | | + | ------------------ | - | + | `populates_fields` | | + | `required_fields` | | + + diff --git a/docs/api/qiskit-noise-learning/generated/experiment-builder-complete-sequences.mdx b/docs/api/qiskit-noise-learning/generated/experiment-builder-complete-sequences.mdx new file mode 100644 index 000000000000..486a20418445 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/experiment-builder-complete-sequences.mdx @@ -0,0 +1,38 @@ +--- +title: CompleteSequences (latest version) +description: API reference for qiskit_noise_learning.experiment_builder.CompleteSequences in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.experiment_builder.CompleteSequences +--- + + + +# qiskit\_noise\_learning.experiment\_builder.CompleteSequences + + + Bases: [`ExperimentBuilderStage`](experiment-builder-experiment-builder-stage "qiskit_noise_learning.experiment_builder.experiment_builder_stage.ExperimentBuilderStage") + + Complete all instruction sequences. + + Calls [`complete()`](sequences-instruction-sequence#complete "qiskit_noise_learning.sequences.InstructionSequence.complete") on each instruction sequence to finalize any [`PartialPauliPermutation`](sequences-partial-pauli-permutation "qiskit_noise_learning.sequences.PartialPauliPermutation") instances. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | + | [`__init__`](#qiskit_noise_learning.experiment_builder.CompleteSequences.__init__ "qiskit_noise_learning.experiment_builder.CompleteSequences.__init__")() | | + | `run`(experiment) | Validate required fields, then apply this stage. | + + ## Attributes + + | | | + | ------------------ | - | + | `populates_fields` | | + | `required_fields` | | + + diff --git a/docs/api/qiskit-noise-learning/generated/experiment-builder-depth-1-paths.mdx b/docs/api/qiskit-noise-learning/generated/experiment-builder-depth-1-paths.mdx new file mode 100644 index 000000000000..5f643a3a755d --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/experiment-builder-depth-1-paths.mdx @@ -0,0 +1,55 @@ +--- +title: Depth1Paths (latest version) +description: API reference for qiskit_noise_learning.experiment_builder.Depth1Paths in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.experiment_builder.Depth1Paths +--- + + + +# qiskit\_noise\_learning.experiment\_builder.Depth1Paths + + + Bases: [`AddPaths`](experiment-builder-add-paths "qiskit_noise_learning.experiment_builder.stages.path_generators.add_paths.AddPaths") + + Generate depth-1 paths for each target gate. + + **Parameters** + + * **prep\_gate** – The preparation gate. If `None`, defaults to the gate named `"P"`. + * **meas\_gate** – The measurement gate. If `None`, defaults to the gate named `"M"`. + * **gates** – Gates to generate paths for; these must be unitary (no preparation or measurement component). If `None`, defaults to all unitary (non-SPAM) gates. + * **input\_paulis** – Optional mapping from gate name to input Paulis. If not specified, defaults to the gate generators if the fidelity model contains a [`PauliLindbladModel`](models-pauli-lindblad-model "qiskit_noise_learning.models.PauliLindbladModel"), otherwise a `ValueError` is raised. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | + | [`__init__`](#qiskit_noise_learning.experiment_builder.Depth1Paths.__init__ "qiskit_noise_learning.experiment_builder.Depth1Paths.__init__")(\*\[, prep\_gate, meas\_gate, gates, ...]) | | + | `run`(experiment) | Validate required fields, then apply this stage. | + + ## Attributes + + | | | + | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | + | `populates_fields` | | + | [`required_fields`](#qiskit_noise_learning.experiment_builder.Depth1Paths.required_fields "qiskit_noise_learning.experiment_builder.Depth1Paths.required_fields") | Built-in immutable sequence. | + + ### required\_fields + + + Type: [`tuple`](https://docs.python.org/3/library/stdtypes.html#tuple)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), ...] + + Built-in immutable sequence. + + If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items. + + If the argument is a tuple, the return value is the same object. + + + diff --git a/docs/api/qiskit-noise-learning/generated/experiment-builder-even-depth-paths.mdx b/docs/api/qiskit-noise-learning/generated/experiment-builder-even-depth-paths.mdx new file mode 100644 index 000000000000..28769c4cffa8 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/experiment-builder-even-depth-paths.mdx @@ -0,0 +1,58 @@ +--- +title: EvenDepthPaths (latest version) +description: API reference for qiskit_noise_learning.experiment_builder.EvenDepthPaths in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.experiment_builder.EvenDepthPaths +--- + + + +# qiskit\_noise\_learning.experiment\_builder.EvenDepthPaths + + + Bases: [`AddPaths`](experiment-builder-add-paths "qiskit_noise_learning.experiment_builder.stages.path_generators.add_paths.AddPaths") + + Generate unbound paths with repetitions of two applications of each target gate. + + For each target gate, generates all well-defined paths where the repeatable fragment consists of two applications of the gate with intermediate single-qubit Cliffords. + + **Parameters** + + * **prep\_gate** – The preparation gate. If `None`, defaults to the gate named `"P"`. + * **meas\_gate** – The measurement gate. If `None`, defaults to the gate named `"M"`. + * **gates** – Gates to generate paths for; these must be unitary (no preparation or measurement component). If `None`, defaults to all unitary gates. + * **input\_paulis** – Optional mapping from gate name to input Paulis. If not specified, defaults to the gate generators if the fidelity model contains a [`PauliLindbladModel`](models-pauli-lindblad-model "qiskit_noise_learning.models.PauliLindbladModel"), otherwise a `ValueError` is raised. + * **output\_paulis** – Optional mapping from gate name to output Paulis. Defaults to input. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | + | [`__init__`](#qiskit_noise_learning.experiment_builder.EvenDepthPaths.__init__ "qiskit_noise_learning.experiment_builder.EvenDepthPaths.__init__")(\*\[, prep\_gate, meas\_gate, gates, ...]) | | + | `run`(experiment) | Validate required fields, then apply this stage. | + + ## Attributes + + | | | + | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | + | `populates_fields` | | + | [`required_fields`](#qiskit_noise_learning.experiment_builder.EvenDepthPaths.required_fields "qiskit_noise_learning.experiment_builder.EvenDepthPaths.required_fields") | Built-in immutable sequence. | + + ### required\_fields + + + Type: [`tuple`](https://docs.python.org/3/library/stdtypes.html#tuple)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), ...] + + Built-in immutable sequence. + + If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items. + + If the argument is a tuple, the return value is the same object. + + + diff --git a/docs/api/qiskit-noise-learning/generated/experiment-builder-even-depth-vanilla-paths.mdx b/docs/api/qiskit-noise-learning/generated/experiment-builder-even-depth-vanilla-paths.mdx new file mode 100644 index 000000000000..4e7e9f5faddb --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/experiment-builder-even-depth-vanilla-paths.mdx @@ -0,0 +1,57 @@ +--- +title: EvenDepthVanillaPaths (latest version) +description: API reference for qiskit_noise_learning.experiment_builder.EvenDepthVanillaPaths in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.experiment_builder.EvenDepthVanillaPaths +--- + + + +# qiskit\_noise\_learning.experiment\_builder.EvenDepthVanillaPaths + + + Bases: [`AddPaths`](experiment-builder-add-paths "qiskit_noise_learning.experiment_builder.stages.path_generators.add_paths.AddPaths") + + Generate unbound vanilla paths with repetitions of two gate applications. + + For each target gate, generates paths where the repeatable fragment consists of two applications of the gate. + + **Parameters** + + * **prep\_gate** – The preparation gate. If `None`, defaults to the gate named `"P"`. + * **meas\_gate** – The measurement gate. If `None`, defaults to the gate named `"M"`. + * **gates** – Gates to generate paths for; these must be unitary (no preparation or measurement component). If `None`, defaults to all unitary gates in the gate set. + * **input\_paulis** – Optional mapping from gate name to the Paulis to use. If not specified, defaults to the gate generators if the fidelity model contains a [`PauliLindbladModel`](models-pauli-lindblad-model "qiskit_noise_learning.models.PauliLindbladModel"), otherwise a `ValueError` is raised. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | + | [`__init__`](#qiskit_noise_learning.experiment_builder.EvenDepthVanillaPaths.__init__ "qiskit_noise_learning.experiment_builder.EvenDepthVanillaPaths.__init__")(\*\[, prep\_gate, meas\_gate, gates, ...]) | | + | `run`(experiment) | Validate required fields, then apply this stage. | + + ## Attributes + + | | | + | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | + | `populates_fields` | | + | [`required_fields`](#qiskit_noise_learning.experiment_builder.EvenDepthVanillaPaths.required_fields "qiskit_noise_learning.experiment_builder.EvenDepthVanillaPaths.required_fields") | Built-in immutable sequence. | + + ### required\_fields + + + Type: [`tuple`](https://docs.python.org/3/library/stdtypes.html#tuple)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), ...] + + Built-in immutable sequence. + + If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items. + + If the argument is a tuple, the return value is the same object. + + + diff --git a/docs/api/qiskit-noise-learning/generated/experiment-builder-experiment-builder-stage.mdx b/docs/api/qiskit-noise-learning/generated/experiment-builder-experiment-builder-stage.mdx new file mode 100644 index 000000000000..a073c42eb43c --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/experiment-builder-experiment-builder-stage.mdx @@ -0,0 +1,65 @@ +--- +title: ExperimentBuilderStage (latest version) +description: API reference for qiskit_noise_learning.experiment_builder.ExperimentBuilderStage in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.experiment_builder.ExperimentBuilderStage +--- + + + +# qiskit\_noise\_learning.experiment\_builder.ExperimentBuilderStage + + + Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC) + + Abstract base for a stage in the experiment-building pipeline. + + Each stage takes an [`Experiment`](experiment-builder-experiment "qiskit_noise_learning.experiment_builder.Experiment") and returns a new [`Experiment`](experiment-builder-experiment "qiskit_noise_learning.experiment_builder.Experiment") with additional fields populated or existing fields transformed. + + Subclasses declare which [`Experiment`](experiment-builder-experiment "qiskit_noise_learning.experiment_builder.Experiment") fields they require via the `required_fields` class attribute, and which fields they populate (can take form `None` to a non-`None` value) via `populates_fields`. The public [`run()`](#qiskit_noise_learning.experiment_builder.ExperimentBuilderStage.run "qiskit_noise_learning.experiment_builder.ExperimentBuilderStage.run") method validates that the required fields are not `None` before dispatching to `_run()`. + + [`ExperimentBuilder`](experiment-builder-experiment-builder "qiskit_noise_learning.experiment_builder.ExperimentBuilder") uses `populates_fields` to compute its aggregate `required_fields`: a stage’s requirement is satisfied if a preceding stage populates that field. + + **Parameters** + + * **required\_fields** – Tuple of [`Experiment`](experiment-builder-experiment "qiskit_noise_learning.experiment_builder.Experiment") property names that must be non-`None` before this stage can execute. + * **populates\_fields** – Tuple of [`Experiment`](experiment-builder-experiment "qiskit_noise_learning.experiment_builder.Experiment") property names that this stage populates on the returned [`Experiment`](experiment-builder-experiment "qiskit_noise_learning.experiment_builder.Experiment"). + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | + | [`__init__`](#qiskit_noise_learning.experiment_builder.ExperimentBuilderStage.__init__ "qiskit_noise_learning.experiment_builder.ExperimentBuilderStage.__init__")() | | + | [`run`](#qiskit_noise_learning.experiment_builder.ExperimentBuilderStage.run "qiskit_noise_learning.experiment_builder.ExperimentBuilderStage.run")(experiment) | Validate required fields, then apply this stage. | + + ## Attributes + + | | | + | ------------------ | - | + | `populates_fields` | | + | `required_fields` | | + + ### run + + + Validate required fields, then apply this stage. + + **Parameters** + + **experiment** – The input experiment. + + **Returns** + + A new [`Experiment`](experiment-builder-experiment "qiskit_noise_learning.experiment_builder.Experiment") with this stage’s transformations applied. + + **Raises** + + [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – If any field listed in `required_fields` is `None`. + + + diff --git a/docs/api/qiskit-noise-learning/generated/experiment-builder-experiment-builder.mdx b/docs/api/qiskit-noise-learning/generated/experiment-builder-experiment-builder.mdx new file mode 100644 index 000000000000..0173ea4cde37 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/experiment-builder-experiment-builder.mdx @@ -0,0 +1,67 @@ +--- +title: ExperimentBuilder (latest version) +description: API reference for qiskit_noise_learning.experiment_builder.ExperimentBuilder in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.experiment_builder.ExperimentBuilder +--- + + + +# qiskit\_noise\_learning.experiment\_builder.ExperimentBuilder + + + Bases: [`ExperimentBuilderStage`](experiment-builder-experiment-builder-stage "qiskit_noise_learning.experiment_builder.experiment_builder_stage.ExperimentBuilderStage") + + A composite [`ExperimentBuilderStage`](experiment-builder-experiment-builder-stage "qiskit_noise_learning.experiment_builder.ExperimentBuilderStage") that chains stages sequentially. + + Because [`ExperimentBuilder`](#qiskit_noise_learning.experiment_builder.ExperimentBuilder "qiskit_noise_learning.experiment_builder.ExperimentBuilder") is itself an [`ExperimentBuilderStage`](experiment-builder-experiment-builder-stage "qiskit_noise_learning.experiment_builder.ExperimentBuilderStage"), builders can be nested and used anywhere a single stage is expected. + + **Parameters** + + **stages** – The stages to chain in sequential order. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ | + | [`__init__`](#qiskit_noise_learning.experiment_builder.ExperimentBuilder.__init__ "qiskit_noise_learning.experiment_builder.ExperimentBuilder.__init__")(\*stages) | | + | `run`(experiment) | Validate required fields, then apply this stage. | + + ## Attributes + + | | | + | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | + | [`populates_fields`](#qiskit_noise_learning.experiment_builder.ExperimentBuilder.populates_fields "qiskit_noise_learning.experiment_builder.ExperimentBuilder.populates_fields") | The union of all fields populated by stages in this pipeline. | + | [`required_fields`](#qiskit_noise_learning.experiment_builder.ExperimentBuilder.required_fields "qiskit_noise_learning.experiment_builder.ExperimentBuilder.required_fields") | The fields required by this pipeline that no internal stage populates. | + | [`stages`](#qiskit_noise_learning.experiment_builder.ExperimentBuilder.stages "qiskit_noise_learning.experiment_builder.ExperimentBuilder.stages") | The stages in this builder. | + + ### stages + + + Type: [`tuple`](https://docs.python.org/3/library/stdtypes.html#tuple)\[[`ExperimentBuilderStage`](experiment-builder-experiment-builder-stage "qiskit_noise_learning.experiment_builder.experiment_builder_stage.ExperimentBuilderStage"), ...] + + The stages in this builder. + + + ### required\_fields + + + Type: [`tuple`](https://docs.python.org/3/library/stdtypes.html#tuple)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), ...] + + The fields required by this pipeline that no internal stage populates. + + + ### populates\_fields + + + Type: [`tuple`](https://docs.python.org/3/library/stdtypes.html#tuple)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), ...] + + The union of all fields populated by stages in this pipeline. + + + diff --git a/docs/api/qiskit-noise-learning/generated/experiment-builder-experiment.mdx b/docs/api/qiskit-noise-learning/generated/experiment-builder-experiment.mdx new file mode 100644 index 000000000000..fa52c0c8acfc --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/experiment-builder-experiment.mdx @@ -0,0 +1,168 @@ +--- +title: Experiment (latest version) +description: API reference for qiskit_noise_learning.experiment_builder.Experiment in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.experiment_builder.Experiment +--- + + + +# qiskit\_noise\_learning.experiment\_builder.Experiment + + + Bases: [`object`](https://docs.python.org/3/library/functions.html#object) + + A learning experiment specification. + + An [`Experiment`](#qiskit_noise_learning.experiment_builder.Experiment "qiskit_noise_learning.experiment_builder.Experiment") collects all the data needed to define a noise-learning experiment: a fidelity model, analysis paths, instruction sequences, their relations, and execution parameters (shots and randomizations). + + All fields are optional and may be progressively populated via [`ExperimentBuilderStage`](experiment-builder-experiment-builder-stage "qiskit_noise_learning.experiment_builder.ExperimentBuilderStage") instances. + + **Parameters** + + * **fidelity\_model** – A fidelity model or a model gate set (which is wrapped in an [`IdentityFidelityModel`](models-identity-fidelity-model "qiskit_noise_learning.models.IdentityFidelityModel")). + * **paths** – Paths to analyze. + * **instruction\_sequences** – Instruction sequences (may include both bound and unbound). + * **relations** – Set of `(path_idx, sequence_idx)` tuples indicating which paths are traversed by which instruction sequences. + * **shots** – Global number of shots (default 20). + * **randomizations** – Global number of randomizations (default 50). + * **randomization\_multipliers** – Per-sequence randomization multiplier (parallel to instruction\_sequences). + * **validate** – If `True` (default), enforce the same validation checks as [`replace()`](#qiskit_noise_learning.experiment_builder.Experiment.replace "qiskit_noise_learning.experiment_builder.Experiment.replace") (co-replacement, length consistency, relations bounds). + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- | + | [`__init__`](#qiskit_noise_learning.experiment_builder.Experiment.__init__ "qiskit_noise_learning.experiment_builder.Experiment.__init__")(\*\[, fidelity\_model, paths, ...]) | | + | [`replace`](#qiskit_noise_learning.experiment_builder.Experiment.replace "qiskit_noise_learning.experiment_builder.Experiment.replace")(\*\[, validate]) | Return a shallow copy with the given fields overridden. | + + ## Attributes + + | | | + | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | + | [`design_matrix`](#qiskit_noise_learning.experiment_builder.Experiment.design_matrix "qiskit_noise_learning.experiment_builder.Experiment.design_matrix") | The design matrix, lazily computed from the fidelity model and paths. | + | [`fidelity_model`](#qiskit_noise_learning.experiment_builder.Experiment.fidelity_model "qiskit_noise_learning.experiment_builder.Experiment.fidelity_model") | The fidelity model. | + | [`gate_set`](#qiskit_noise_learning.experiment_builder.Experiment.gate_set "qiskit_noise_learning.experiment_builder.Experiment.gate_set") | The model gate set. | + | [`instruction_sequences`](#qiskit_noise_learning.experiment_builder.Experiment.instruction_sequences "qiskit_noise_learning.experiment_builder.Experiment.instruction_sequences") | The instruction sequences. | + | [`is_executable`](#qiskit_noise_learning.experiment_builder.Experiment.is_executable "qiskit_noise_learning.experiment_builder.Experiment.is_executable") | Whether this experiment has all the information required to be run. | + | [`paths`](#qiskit_noise_learning.experiment_builder.Experiment.paths "qiskit_noise_learning.experiment_builder.Experiment.paths") | The analysis paths. | + | [`randomization_multipliers`](#qiskit_noise_learning.experiment_builder.Experiment.randomization_multipliers "qiskit_noise_learning.experiment_builder.Experiment.randomization_multipliers") | Per-sequence randomization multipliers. | + | [`randomizations`](#qiskit_noise_learning.experiment_builder.Experiment.randomizations "qiskit_noise_learning.experiment_builder.Experiment.randomizations") | Global number of randomizations. | + | [`relations`](#qiskit_noise_learning.experiment_builder.Experiment.relations "qiskit_noise_learning.experiment_builder.Experiment.relations") | The set of path and sequence relations. | + | [`shots`](#qiskit_noise_learning.experiment_builder.Experiment.shots "qiskit_noise_learning.experiment_builder.Experiment.shots") | Global number of shots. | + + ### fidelity\_model + + + Type: [`LinearMap`](math-linear-map "qiskit_noise_learning.math.linear_map.LinearMap")\[[`Hashable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Hashable), [`FidelityIndex`](sequences-fidelity-index "qiskit_noise_learning.sequences.fidelity_index.FidelityIndex")] | [`None`](https://docs.python.org/3/library/constants.html#None) + + The fidelity model. + + + ### gate\_set + + + Type: [`ModelGateSet`](gate-sets-model-gate-set "qiskit_noise_learning.gate_sets.model_gate_set.ModelGateSet") | [`None`](https://docs.python.org/3/library/constants.html#None) + + The model gate set. + + + ### paths + + + Type: [`list`](https://docs.python.org/3/library/stdtypes.html#list)\[[`Path`](sequences-path "qiskit_noise_learning.sequences.path.Path")] | [`None`](https://docs.python.org/3/library/constants.html#None) + + The analysis paths. + + + ### instruction\_sequences + + + Type: [`list`](https://docs.python.org/3/library/stdtypes.html#list)\[[`InstructionSequence`](sequences-instruction-sequence "qiskit_noise_learning.sequences.instruction_sequence.InstructionSequence")] | [`None`](https://docs.python.org/3/library/constants.html#None) + + The instruction sequences. + + + ### relations + + + Type: [`set`](https://docs.python.org/3/library/stdtypes.html#set)\[[`tuple`](https://docs.python.org/3/library/stdtypes.html#tuple)\[[`int`](https://docs.python.org/3/library/functions.html#int), [`int`](https://docs.python.org/3/library/functions.html#int)]] | [`None`](https://docs.python.org/3/library/constants.html#None) + + The set of path and sequence relations. + + + ### shots + + + Type: [`int`](https://docs.python.org/3/library/functions.html#int) + + Global number of shots. + + + ### randomizations + + + Type: [`int`](https://docs.python.org/3/library/functions.html#int) + + Global number of randomizations. + + + ### randomization\_multipliers + + + Type: [`list`](https://docs.python.org/3/library/stdtypes.html#list)\[[`int`](https://docs.python.org/3/library/functions.html#int)] | [`None`](https://docs.python.org/3/library/constants.html#None) + + Per-sequence randomization multipliers. + + + ### design\_matrix + + + Type: [`IndexedMatrix`](math-indexed-matrix "qiskit_noise_learning.math.indexed_matrix.IndexedMatrix") + + The design matrix, lazily computed from the fidelity model and paths. + + **Raises** + + [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – If `fidelity_model` or `paths` is `None`. + + + ### is\_executable + + + Type: [`bool`](https://docs.python.org/3/library/functions.html#bool) + + Whether this experiment has all the information required to be run. + + Requires: `instruction_sequences` is set, all sequences are bound and complete, and `randomization_multipliers` is set. + + + ### replace + + + Return a shallow copy with the given fields overridden. + + When `validate=True` (default), the following checks are enforced: + + * **Co-replacement**: `instruction_sequences` and `randomization_multipliers` must always both be `None` or both be non-`None`. Replacing one without the other is only allowed if it preserves this invariant. + * **Length consistency**: `randomization_multipliers` must have the same length as `instruction_sequences`. + * **Relations bounds**: Setting `relations` requires `paths` and `instruction_sequences` to be present, and all indices must be in bounds. + * **Soft invalidation**: Replacing `paths` or `instruction_sequences` without providing new `relations` will set `relations` to `None` with a warning. + + **Parameters** + + * **validate** – If `True`, enforce the above checks. If `False`, fields are set as-is with no validation. + * **\*\*kwargs** – Field names and their new values. + + **Raises** + + * [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError) – If an unrecognized field name is given. + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – If a validation constraint is violated. + + + diff --git a/docs/api/qiskit-noise-learning/generated/experiment-builder-generate-instruction-sequences.mdx b/docs/api/qiskit-noise-learning/generated/experiment-builder-generate-instruction-sequences.mdx new file mode 100644 index 000000000000..0487d7347d6f --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/experiment-builder-generate-instruction-sequences.mdx @@ -0,0 +1,44 @@ +--- +title: GenerateInstructionSequences (latest version) +description: API reference for qiskit_noise_learning.experiment_builder.GenerateInstructionSequences in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.experiment_builder.GenerateInstructionSequences +--- + + + +# qiskit\_noise\_learning.experiment\_builder.GenerateInstructionSequences + + + Bases: [`AddInstructionSequences`](experiment-builder-add-instruction-sequences "qiskit_noise_learning.experiment_builder.stages.sequence_generators.add_instruction_sequences.AddInstructionSequences") + + Generate one instruction sequence per path via [`to_instruction_sequence()`](sequences-path#to_instruction_sequence "qiskit_noise_learning.sequences.Path.to_instruction_sequence"). + + For each path (optionally skipping paths already referenced by a relation), generates a corresponding instruction sequence and adds it along with a new relation entry. + + **Parameters** + + * **bound\_multiplier** – Randomization multiplier for bound sequences. + * **unbound\_multiplier** – Randomization multiplier for unbound sequences. + * **skip\_related\_paths** – If `True` (default), paths that already appear in a relation are not used to generate new sequences. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | + | [`__init__`](#qiskit_noise_learning.experiment_builder.GenerateInstructionSequences.__init__ "qiskit_noise_learning.experiment_builder.GenerateInstructionSequences.__init__")(\*\[, bound\_multiplier, ...]) | | + | `run`(experiment) | Validate required fields, then apply this stage. | + + ## Attributes + + | | | + | ------------------ | - | + | `populates_fields` | | + | `required_fields` | | + + diff --git a/docs/api/qiskit-noise-learning/generated/experiment-builder-identify-relations.mdx b/docs/api/qiskit-noise-learning/generated/experiment-builder-identify-relations.mdx new file mode 100644 index 000000000000..fbbb85807e69 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/experiment-builder-identify-relations.mdx @@ -0,0 +1,42 @@ +--- +title: IdentifyRelations (latest version) +description: API reference for qiskit_noise_learning.experiment_builder.IdentifyRelations in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.experiment_builder.IdentifyRelations +--- + + + +# qiskit\_noise\_learning.experiment\_builder.IdentifyRelations + + + Bases: [`ExperimentBuilderStage`](experiment-builder-experiment-builder-stage "qiskit_noise_learning.experiment_builder.experiment_builder_stage.ExperimentBuilderStage") + + Identify new relations amongst existing paths and instruction sequences. + + Iterates over all path/sequence pairs and identifies which sequences traverse which paths. Optionally extends instruction sequence permutations to enable new traversals. + + **Parameters** + + **attempt\_instruction\_extension** – Whether to extend instruction sequence permutations to traverse new paths. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | + | [`__init__`](#qiskit_noise_learning.experiment_builder.IdentifyRelations.__init__ "qiskit_noise_learning.experiment_builder.IdentifyRelations.__init__")(\[attempt\_instruction\_extension]) | | + | `run`(experiment) | Validate required fields, then apply this stage. | + + ## Attributes + + | | | + | ------------------ | - | + | `populates_fields` | | + | `required_fields` | | + + diff --git a/docs/api/qiskit-noise-learning/generated/experiment-builder-merge-instruction-sequences.mdx b/docs/api/qiskit-noise-learning/generated/experiment-builder-merge-instruction-sequences.mdx new file mode 100644 index 000000000000..a0eb81fe5e50 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/experiment-builder-merge-instruction-sequences.mdx @@ -0,0 +1,42 @@ +--- +title: MergeInstructionSequences (latest version) +description: API reference for qiskit_noise_learning.experiment_builder.MergeInstructionSequences in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.experiment_builder.MergeInstructionSequences +--- + + + +# qiskit\_noise\_learning.experiment\_builder.MergeInstructionSequences + + + Bases: [`ExperimentBuilderStage`](experiment-builder-experiment-builder-stage "qiskit_noise_learning.experiment_builder.experiment_builder_stage.ExperimentBuilderStage") + + Merge instruction sequences into a smaller set. + + The sequences that can be merged with each other are grouped together by [`group_mergeable_instruction_sequences()`](sequences-group-mergeable-instruction-sequences "qiskit_noise_learning.sequences.group_mergeable_instruction_sequences"), and every group is merged into a single sequence. + + **Parameters** + + **grouping\_strategies** – The grouping strategies to take the fewest groups found by any of, as documented in [`group_mergeable_instruction_sequences()`](sequences-group-mergeable-instruction-sequences "qiskit_noise_learning.sequences.group_mergeable_instruction_sequences"). If `None`, an empirically determined default set of strategies is used. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | + | [`__init__`](#qiskit_noise_learning.experiment_builder.MergeInstructionSequences.__init__ "qiskit_noise_learning.experiment_builder.MergeInstructionSequences.__init__")(\[grouping\_strategies]) | | + | `run`(experiment) | Validate required fields, then apply this stage. | + + ## Attributes + + | | | + | ------------------ | - | + | `populates_fields` | | + | `required_fields` | | + + diff --git a/docs/api/qiskit-noise-learning/generated/experiment-builder-rank-reduce-paths.mdx b/docs/api/qiskit-noise-learning/generated/experiment-builder-rank-reduce-paths.mdx new file mode 100644 index 000000000000..2cdba6b0ef9f --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/experiment-builder-rank-reduce-paths.mdx @@ -0,0 +1,42 @@ +--- +title: RankReducePaths (latest version) +description: API reference for qiskit_noise_learning.experiment_builder.RankReducePaths in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.experiment_builder.RankReducePaths +--- + + + +# qiskit\_noise\_learning.experiment\_builder.RankReducePaths + + + Bases: [`ExperimentBuilderStage`](experiment-builder-experiment-builder-stage "qiskit_noise_learning.experiment_builder.experiment_builder_stage.ExperimentBuilderStage") + + Reduce the paths to a maximal linearly independent set. + + Removes linearly dependent paths from the experiment’s design matrix, updates relations accordingly, and removes any instruction sequences no longer referenced. + + **Parameters** + + **tol** – Tolerance for determining linear independence. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ | + | [`__init__`](#qiskit_noise_learning.experiment_builder.RankReducePaths.__init__ "qiskit_noise_learning.experiment_builder.RankReducePaths.__init__")(\[tol]) | | + | `run`(experiment) | Validate required fields, then apply this stage. | + + ## Attributes + + | | | + | ------------------ | - | + | `populates_fields` | | + | `required_fields` | | + + diff --git a/docs/api/qiskit-noise-learning/generated/experiment-builder-spam-paths.mdx b/docs/api/qiskit-noise-learning/generated/experiment-builder-spam-paths.mdx new file mode 100644 index 000000000000..21d4840f2066 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/experiment-builder-spam-paths.mdx @@ -0,0 +1,42 @@ +--- +title: SPAMPaths (latest version) +description: API reference for qiskit_noise_learning.experiment_builder.SPAMPaths in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.experiment_builder.SPAMPaths +--- + + + +# qiskit\_noise\_learning.experiment\_builder.SPAMPaths + + + Bases: [`AddPaths`](experiment-builder-add-paths "qiskit_noise_learning.experiment_builder.stages.path_generators.add_paths.AddPaths") + + Generate depth-0 paths. + + **Parameters** + + * **prep\_gate** – The preparation gate. If `None`, defaults to the gate named `"P"`. + * **meas\_gate** – The measurement gate. If `None`, defaults to the gate named `"M"`. + * **indices\_list** – An iterable of qubit index lists. If `None`, generates single-qubit paths for every qubit. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | + | [`__init__`](#qiskit_noise_learning.experiment_builder.SPAMPaths.__init__ "qiskit_noise_learning.experiment_builder.SPAMPaths.__init__")(\*\[, prep\_gate, meas\_gate, indices\_list]) | | + | `run`(experiment) | Validate required fields, then apply this stage. | + + ## Attributes + + | | | + | ------------------ | - | + | `populates_fields` | | + | `required_fields` | | + + diff --git a/docs/api/qiskit-noise-learning/generated/experiment-builder-vanilla-instruction-sequences.mdx b/docs/api/qiskit-noise-learning/generated/experiment-builder-vanilla-instruction-sequences.mdx new file mode 100644 index 000000000000..fdb871936526 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/experiment-builder-vanilla-instruction-sequences.mdx @@ -0,0 +1,58 @@ +--- +title: VanillaInstructionSequences (latest version) +description: API reference for qiskit_noise_learning.experiment_builder.VanillaInstructionSequences in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.experiment_builder.VanillaInstructionSequences +--- + + + +# qiskit\_noise\_learning.experiment\_builder.VanillaInstructionSequences + + + Bases: [`AddInstructionSequences`](experiment-builder-add-instruction-sequences "qiskit_noise_learning.experiment_builder.stages.sequence_generators.add_instruction_sequences.AddInstructionSequences") + + Generate vanilla instruction sequences for each target gate. + + For each gate, generates 9 instruction sequences sufficient to measure any single- and two-qubit Pauli fidelity on a triangle-free coupling map. + + **Parameters** + + * **prep\_gate** – The preparation gate. If `None`, defaults to the gate named `"P"`. + * **meas\_gate** – The measurement gate. If `None`, defaults to the gate named `"M"`. + * **gates** – Gates to generate sequences for. If `None`, defaults to all non-SPAM gates. + * **coupling\_map** – The coupling map. If `None`, defaults to the gate set’s coupling map. + * **randomization\_multiplier** – Randomization multiplier applied to all generated sequences. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | + | [`__init__`](#qiskit_noise_learning.experiment_builder.VanillaInstructionSequences.__init__ "qiskit_noise_learning.experiment_builder.VanillaInstructionSequences.__init__")(\*\[, prep\_gate, meas\_gate, gates, ...]) | | + | `run`(experiment) | Validate required fields, then apply this stage. | + + ## Attributes + + | | | + | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | + | `populates_fields` | | + | [`required_fields`](#qiskit_noise_learning.experiment_builder.VanillaInstructionSequences.required_fields "qiskit_noise_learning.experiment_builder.VanillaInstructionSequences.required_fields") | Built-in immutable sequence. | + + ### required\_fields + + + Type: [`tuple`](https://docs.python.org/3/library/stdtypes.html#tuple)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), ...] + + Built-in immutable sequence. + + If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items. + + If the argument is a tuple, the return value is the same object. + + + diff --git a/docs/api/qiskit-noise-learning/generated/gate-sets-gate-set.mdx b/docs/api/qiskit-noise-learning/generated/gate-sets-gate-set.mdx new file mode 100644 index 000000000000..9315e604629e --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/gate-sets-gate-set.mdx @@ -0,0 +1,150 @@ +--- +title: GateSet (latest version) +description: API reference for qiskit_noise_learning.gate_sets.GateSet in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.gate_sets.GateSet +--- + + + +# qiskit\_noise\_learning.gate\_sets.GateSet + + + Bases: [`Mapping`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), `GateType`] + + A mapping of names to gates with qubit metadata. + + **Parameters** + + * **num\_qubits** – How many qubits the QPU of interest has. + * **qubit\_subset** – A subset of `range(num_qubits)` specifying the region of interest of the QPU. All gates added must act within this subset. By default, contains all qubits. + * **target** – An optional `Target` against which operations will be validated whenever gates are added to the gate set. Its number of qubits must match `num_qubits` if both are present. + * **name** – Name for this gate set. If `None`, [`name`](#qiskit_noise_learning.gate_sets.GateSet.name "qiskit_noise_learning.gate_sets.GateSet.name") falls back to the class name. + * **latex\_str** – An optional LaTeX string for rendering this gate set. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | + | [`__init__`](#qiskit_noise_learning.gate_sets.GateSet.__init__ "qiskit_noise_learning.gate_sets.GateSet.__init__")(num\_qubits\[, qubit\_subset, target, ...]) | | + | [`add_gate`](#qiskit_noise_learning.gate_sets.GateSet.add_gate "qiskit_noise_learning.gate_sets.GateSet.add_gate")(gate) | Add a gate to the gate set. | + | [`draw`](#qiskit_noise_learning.gate_sets.GateSet.draw "qiskit_noise_learning.gate_sets.GateSet.draw")() | Draw the device topology with per-gate coloring. | + | `get`(k\[,d]) | | + | `items`() | | + | `keys`() | | + | `values`() | | + + ## Attributes + + | | | + | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | + | [`label`](#qiskit_noise_learning.gate_sets.GateSet.label "qiskit_noise_learning.gate_sets.GateSet.label") | A string label for use in plotter legends. | + | [`latex_str`](#qiskit_noise_learning.gate_sets.GateSet.latex_str "qiskit_noise_learning.gate_sets.GateSet.latex_str") | A LaTeX string for this gate set. | + | [`math_label`](#qiskit_noise_learning.gate_sets.GateSet.math_label "qiskit_noise_learning.gate_sets.GateSet.math_label") | A string label for use within latex math mode. | + | [`model_gate_set`](#qiskit_noise_learning.gate_sets.GateSet.model_gate_set "qiskit_noise_learning.gate_sets.GateSet.model_gate_set") | Return a [`ModelGateSet`](gate-sets-model-gate-set "qiskit_noise_learning.gate_sets.ModelGateSet") representing this gate set. | + | [`name`](#qiskit_noise_learning.gate_sets.GateSet.name "qiskit_noise_learning.gate_sets.GateSet.name") | Name for this gate set, defaulting to the class name. | + | [`num_qubits`](#qiskit_noise_learning.gate_sets.GateSet.num_qubits "qiskit_noise_learning.gate_sets.GateSet.num_qubits") | The total number of qubits of the device this gateset acts on. | + | [`qubit_subset`](#qiskit_noise_learning.gate_sets.GateSet.qubit_subset "qiskit_noise_learning.gate_sets.GateSet.qubit_subset") | The indices of the subset of device qubits that all gates act on. | + | [`target`](#qiskit_noise_learning.gate_sets.GateSet.target "qiskit_noise_learning.gate_sets.GateSet.target") | The target of this gateset, if one exists. | + + ### model\_gate\_set + + + Type: [`ModelGateSet`](gate-sets-model-gate-set "qiskit_noise_learning.gate_sets.ModelGateSet") + + Return a [`ModelGateSet`](gate-sets-model-gate-set "qiskit_noise_learning.gate_sets.ModelGateSet") representing this gate set. + + + ### name + + + Type: [`str`](https://docs.python.org/3/library/stdtypes.html#str) + + Name for this gate set, defaulting to the class name. + + + ### latex\_str + + + Type: [`str`](https://docs.python.org/3/library/stdtypes.html#str) + + A LaTeX string for this gate set. + + + ### label + + + Type: [`str`](https://docs.python.org/3/library/stdtypes.html#str) + + A string label for use in plotter legends. + + + ### math\_label + + + Type: [`str`](https://docs.python.org/3/library/stdtypes.html#str) + + A string label for use within latex math mode. + + + ### num\_qubits + + + Type: [`int`](https://docs.python.org/3/library/functions.html#int) + + The total number of qubits of the device this gateset acts on. + + + ### qubit\_subset + + + Type: [`frozenset`](https://docs.python.org/3/library/stdtypes.html#frozenset)\[[`int`](https://docs.python.org/3/library/functions.html#int)] + + The indices of the subset of device qubits that all gates act on. + + + ### target + + + Type: [`Target`](/docs/api/qiskit/qiskit.transpiler.Target) | [`None`](https://docs.python.org/3/library/constants.html#None) + + The target of this gateset, if one exists. + + + ### add\_gate + + + Add a gate to the gate set. + + **Parameters** + + **gate** – The gate to add. + + **Raises** + + [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – If the gate acts on some qubits outside of the valid range, or if the gate name is already used in the gate set. + + + ### draw + + + Draw the device topology with per-gate coloring. + + Each gate’s 2-qubit interactions are drawn as colored edges on the device coupling graph. Gates that act only on single qubits (such as preparation and measurement) are shown as shaped markers on the relevant nodes. + + **Returns** + + The figure, with toggleable legends. + + **Raises** + + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – If [`target`](#qiskit_noise_learning.gate_sets.GateSet.target "qiskit_noise_learning.gate_sets.GateSet.target") is `None`. + * [**ImportError**](https://docs.python.org/3/library/exceptions.html#ImportError) – If `matplotlib` is not installed. + + + diff --git a/docs/api/qiskit-noise-learning/generated/gate-sets-gate.mdx b/docs/api/qiskit-noise-learning/generated/gate-sets-gate.mdx new file mode 100644 index 000000000000..1c3cefc241ba --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/gate-sets-gate.mdx @@ -0,0 +1,171 @@ +--- +title: Gate (latest version) +description: API reference for qiskit_noise_learning.gate_sets.Gate in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.gate_sets.Gate +--- + + + +# qiskit\_noise\_learning.gate\_sets.Gate + + + Bases: [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC) + + Represents qubit metadata for a single gate in a gate set. + + Typically serves as a base class for types that implement non-trivial gates. + + **Parameters** + + * **name** – The gate name. + * **qubit\_idxs** – The physical qubit indices that the gate acts on. + * **prep\_idxs** – The physical qubit indices that this gate prepares, or resets to the 0 state. + * **meas\_idxs** – The physical qubit indices that this gate measures. + * **latex\_str** – An optional LaTeX string for rendering this gate. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | --------------------------------------------------------------------------------------------------------------------------------------------------- | - | + | [`__init__`](#qiskit_noise_learning.gate_sets.Gate.__init__ "qiskit_noise_learning.gate_sets.Gate.__init__")(name, qubit\_idxs\[, prep\_idxs, ...]) | | + + ## Attributes + + | | | + | --------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | + | [`constituent_gate_idxs`](#qiskit_noise_learning.gate_sets.Gate.constituent_gate_idxs "qiskit_noise_learning.gate_sets.Gate.constituent_gate_idxs") | Iterator over tuples of physical indices that specify where constituent gates act. | + | [`gate_idxs`](#qiskit_noise_learning.gate_sets.Gate.gate_idxs "qiskit_noise_learning.gate_sets.Gate.gate_idxs") | The physical indices where this gate undergoes unitary action. | + | [`idling_idxs`](#qiskit_noise_learning.gate_sets.Gate.idling_idxs "qiskit_noise_learning.gate_sets.Gate.idling_idxs") | The physical qubit indices that this gate is idling on. | + | [`label`](#qiskit_noise_learning.gate_sets.Gate.label "qiskit_noise_learning.gate_sets.Gate.label") | A string label for use in plotter legends. | + | [`latex_str`](#qiskit_noise_learning.gate_sets.Gate.latex_str "qiskit_noise_learning.gate_sets.Gate.latex_str") | A LaTeX string for this gate. | + | [`math_label`](#qiskit_noise_learning.gate_sets.Gate.math_label "qiskit_noise_learning.gate_sets.Gate.math_label") | A string label for use within latex math mode. | + | [`meas_idxs`](#qiskit_noise_learning.gate_sets.Gate.meas_idxs "qiskit_noise_learning.gate_sets.Gate.meas_idxs") | The physical qubit indices that this gate measures. | + | [`model_gate`](#qiskit_noise_learning.gate_sets.Gate.model_gate "qiskit_noise_learning.gate_sets.Gate.model_gate") | Return a [`ModelGate`](gate-sets-model-gate "qiskit_noise_learning.gate_sets.ModelGate") representing this gate. | + | [`name`](#qiskit_noise_learning.gate_sets.Gate.name "qiskit_noise_learning.gate_sets.Gate.name") | The gate name. | + | [`num_qubits`](#qiskit_noise_learning.gate_sets.Gate.num_qubits "qiskit_noise_learning.gate_sets.Gate.num_qubits") | The number of qubits this gate acts on. | + | [`prep_idxs`](#qiskit_noise_learning.gate_sets.Gate.prep_idxs "qiskit_noise_learning.gate_sets.Gate.prep_idxs") | The physical qubit indices that this gate prepares (or resets). | + | [`qubit_idxs`](#qiskit_noise_learning.gate_sets.Gate.qubit_idxs "qiskit_noise_learning.gate_sets.Gate.qubit_idxs") | The physical qubit indices this gate acts on. | + | [`sorted_meas_idxs`](#qiskit_noise_learning.gate_sets.Gate.sorted_meas_idxs "qiskit_noise_learning.gate_sets.Gate.sorted_meas_idxs") | The indices of the measured qubits in increasing order. | + | [`sorted_prep_idxs`](#qiskit_noise_learning.gate_sets.Gate.sorted_prep_idxs "qiskit_noise_learning.gate_sets.Gate.sorted_prep_idxs") | The indices of the reset qubits in increasing order. | + + ### model\_gate + + + Type: [`ModelGate`](gate-sets-model-gate "qiskit_noise_learning.gate_sets.ModelGate") + + Return a [`ModelGate`](gate-sets-model-gate "qiskit_noise_learning.gate_sets.ModelGate") representing this gate. + + + ### name + + + Type: [`str`](https://docs.python.org/3/library/stdtypes.html#str) + + The gate name. + + + ### latex\_str + + + Type: [`str`](https://docs.python.org/3/library/stdtypes.html#str) + + A LaTeX string for this gate. + + + ### label + + + Type: [`str`](https://docs.python.org/3/library/stdtypes.html#str) + + A string label for use in plotter legends. + + + ### math\_label + + + Type: [`str`](https://docs.python.org/3/library/stdtypes.html#str) + + A string label for use within latex math mode. + + + ### num\_qubits + + + Type: [`int`](https://docs.python.org/3/library/functions.html#int) + + The number of qubits this gate acts on. + + + ### qubit\_idxs + + + Type: [`tuple`](https://docs.python.org/3/library/stdtypes.html#tuple)\[[`int`](https://docs.python.org/3/library/functions.html#int), ...] + + The physical qubit indices this gate acts on. + + + ### meas\_idxs + + + Type: [`frozenset`](https://docs.python.org/3/library/stdtypes.html#frozenset)\[[`int`](https://docs.python.org/3/library/functions.html#int)] + + The physical qubit indices that this gate measures. + + + ### sorted\_meas\_idxs + + + Type: [`list`](https://docs.python.org/3/library/stdtypes.html#list)\[[`int`](https://docs.python.org/3/library/functions.html#int)] + + The indices of the measured qubits in increasing order. + + + ### prep\_idxs + + + Type: [`frozenset`](https://docs.python.org/3/library/stdtypes.html#frozenset)\[[`int`](https://docs.python.org/3/library/functions.html#int)] + + The physical qubit indices that this gate prepares (or resets). + + + ### sorted\_prep\_idxs + + + Type: [`list`](https://docs.python.org/3/library/stdtypes.html#list)\[[`int`](https://docs.python.org/3/library/functions.html#int)] + + The indices of the reset qubits in increasing order. + + + ### idling\_idxs + + + Type: [`set`](https://docs.python.org/3/library/stdtypes.html#set)\[[`int`](https://docs.python.org/3/library/functions.html#int)] + + The physical qubit indices that this gate is idling on. + + + ### gate\_idxs + + + Type: [`frozenset`](https://docs.python.org/3/library/stdtypes.html#frozenset)\[[`int`](https://docs.python.org/3/library/functions.html#int)] + + The physical indices where this gate undergoes unitary action. + + + ### constituent\_gate\_idxs + + + Type: [`Iterator`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterator)\[[`tuple`](https://docs.python.org/3/library/stdtypes.html#tuple)\[[`int`](https://docs.python.org/3/library/functions.html#int), ...]] + + Iterator over tuples of physical indices that specify where constituent gates act. + + Some subclasses may not have a meaningful notion of what a “constituent gate” is, because they don’t choose to represent unitary action by some seperable representation. The only contract they need to obey is that the union of all yielded integers is equal to [`gate_idxs`](#qiskit_noise_learning.gate_sets.Gate.gate_idxs "qiskit_noise_learning.gate_sets.Gate.gate_idxs"). + + + diff --git a/docs/api/qiskit-noise-learning/generated/gate-sets-model-gate-set.mdx b/docs/api/qiskit-noise-learning/generated/gate-sets-model-gate-set.mdx new file mode 100644 index 000000000000..9500cbc515e7 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/gate-sets-model-gate-set.mdx @@ -0,0 +1,72 @@ +--- +title: ModelGateSet (latest version) +description: API reference for qiskit_noise_learning.gate_sets.ModelGateSet in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.gate_sets.ModelGateSet +--- + + + +# qiskit\_noise\_learning.gate\_sets.ModelGateSet + + + Bases: [`GateSet`](gate-sets-gate-set "qiskit_noise_learning.gate_sets.gate_set.GateSet")\[[`ModelGate`](gate-sets-model-gate "qiskit_noise_learning.gate_sets.model_gate.ModelGate")] + + A set of Clifford - MCM - reset gates represented as [`ModelGate`](gate-sets-model-gate "qiskit_noise_learning.gate_sets.ModelGate") instances. + + **Parameters** + + * **num\_qubits** – How many qubits the QPU of interest has. + * **qubit\_subset** – A subset of `range(num_qubits)` specifying the region of interest of the QPU. All gates added must act within this subset. By default, contains all qubits. + * **coupling\_map** – A coupling map for the device. Defaults to the full coupling map on `num_qubits`. + * **name** – Name for this gate set. If `None`, `name` falls back to the class name. + * **latex\_str** – An optional LaTeX string for rendering this gate set. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | + | [`__init__`](#qiskit_noise_learning.gate_sets.ModelGateSet.__init__ "qiskit_noise_learning.gate_sets.ModelGateSet.__init__")(num\_qubits, \*\[, qubit\_subset, ...]) | | + | `add_gate`(gate) | Add a gate to the gate set. | + | `draw`() | Draw the device topology with per-gate coloring. | + | `get`(k\[,d]) | | + | `items`() | | + | `keys`() | | + | `values`() | | + + ## Attributes + + | | | + | ---------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | + | [`coupling_map`](#qiskit_noise_learning.gate_sets.ModelGateSet.coupling_map "qiskit_noise_learning.gate_sets.ModelGateSet.coupling_map") | The coupling map for the device this gate set is modeling. | + | `label` | A string label for use in plotter legends. | + | `latex_str` | A LaTeX string for this gate set. | + | `math_label` | A string label for use within latex math mode. | + | [`model_gate_set`](#qiskit_noise_learning.gate_sets.ModelGateSet.model_gate_set "qiskit_noise_learning.gate_sets.ModelGateSet.model_gate_set") | Return a [`ModelGateSet`](#qiskit_noise_learning.gate_sets.ModelGateSet "qiskit_noise_learning.gate_sets.ModelGateSet") representing this gate set. | + | `name` | Name for this gate set, defaulting to the class name. | + | `num_qubits` | The total number of qubits of the device this gateset acts on. | + | `qubit_subset` | The indices of the subset of device qubits that all gates act on. | + | `target` | The target of this gateset, if one exists. | + + ### coupling\_map + + + Type: [`CouplingMap`](/docs/api/qiskit/qiskit.transpiler.CouplingMap) + + The coupling map for the device this gate set is modeling. + + + ### model\_gate\_set + + + Type: [`Self`](https://docs.python.org/3/library/typing.html#typing.Self) + + Return a [`ModelGateSet`](#qiskit_noise_learning.gate_sets.ModelGateSet "qiskit_noise_learning.gate_sets.ModelGateSet") representing this gate set. + + + diff --git a/docs/api/qiskit-noise-learning/generated/gate-sets-model-gate.mdx b/docs/api/qiskit-noise-learning/generated/gate-sets-model-gate.mdx new file mode 100644 index 000000000000..5aa1fd210fe2 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/gate-sets-model-gate.mdx @@ -0,0 +1,124 @@ +--- +title: ModelGate (latest version) +description: API reference for qiskit_noise_learning.gate_sets.ModelGate in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.gate_sets.ModelGate +--- + + + +# qiskit\_noise\_learning.gate\_sets.ModelGate + + + Bases: [`Gate`](gate-sets-gate "qiskit_noise_learning.gate_sets.gate.Gate") + + A model for a gate of the form Clifford - MCM - reset. + + **Parameters** + + * **cliffords** – An iterable of tuples of physical qubit indices and `Clifford`s corresponding to the ideal Clifford layer. The order of the iterable should start with the first applied Clifford and proceed temporally, and `None` is interpreted as the identity. + * **qubit\_idxs** – The physical qubit indices. + * **meas\_idxs** – The physical qubit indices that this gate measures. + * **prep\_idxs** – The physical qubit indices that this gate prepares, or resets. + * **latex\_str** – An optional LaTeX string for rendering this gate. + + **Raises** + + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – If both `cliffords` and `qubit_idxs` are not specified. + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – If any of the elements of `cliffords` have mismatched length of qubit indices and number of qubits of the Clifford. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- | + | [`__init__`](#qiskit_noise_learning.gate_sets.ModelGate.__init__ "qiskit_noise_learning.gate_sets.ModelGate.__init__")(name\[, cliffords, qubit\_idxs, ...]) | | + | [`clifford_propagate`](#qiskit_noise_learning.gate_sets.ModelGate.clifford_propagate "qiskit_noise_learning.gate_sets.ModelGate.clifford_propagate")(...) | Given a Pauli, propagate it through the ideal Clifford operation. | + + ## Attributes + + | | | + | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | + | [`clifford`](#qiskit_noise_learning.gate_sets.ModelGate.clifford "qiskit_noise_learning.gate_sets.ModelGate.clifford") | The overall Clifford operation for this gate. | + | [`cliffords`](#qiskit_noise_learning.gate_sets.ModelGate.cliffords "qiskit_noise_learning.gate_sets.ModelGate.cliffords") | A list of tuples of qubit indices and a Clifford that acts on them. | + | [`constituent_gate_idxs`](#qiskit_noise_learning.gate_sets.ModelGate.constituent_gate_idxs "qiskit_noise_learning.gate_sets.ModelGate.constituent_gate_idxs") | Iterator over tuples of physical indices that specify where constituent gates act. | + | `gate_idxs` | The physical indices where this gate undergoes unitary action. | + | `idling_idxs` | The physical qubit indices that this gate is idling on. | + | `label` | A string label for use in plotter legends. | + | `latex_str` | A LaTeX string for this gate. | + | `math_label` | A string label for use within latex math mode. | + | `meas_idxs` | The physical qubit indices that this gate measures. | + | [`model_gate`](#qiskit_noise_learning.gate_sets.ModelGate.model_gate "qiskit_noise_learning.gate_sets.ModelGate.model_gate") | Return a [`ModelGate`](#qiskit_noise_learning.gate_sets.ModelGate "qiskit_noise_learning.gate_sets.ModelGate") representing this gate. | + | `name` | The gate name. | + | `num_qubits` | The number of qubits this gate acts on. | + | `prep_idxs` | The physical qubit indices that this gate prepares (or resets). | + | `qubit_idxs` | The physical qubit indices this gate acts on. | + | `sorted_meas_idxs` | The indices of the measured qubits in increasing order. | + | `sorted_prep_idxs` | The indices of the reset qubits in increasing order. | + + ### clifford + + + Type: [`Clifford`](/docs/api/qiskit/qiskit.quantum_info.Clifford) + + The overall Clifford operation for this gate. + + + ### cliffords + + + Type: [`list`](https://docs.python.org/3/library/stdtypes.html#list)\[[`tuple`](https://docs.python.org/3/library/stdtypes.html#tuple)\[[`tuple`](https://docs.python.org/3/library/stdtypes.html#tuple)\[[`int`](https://docs.python.org/3/library/functions.html#int), ...], [`Clifford`](/docs/api/qiskit/qiskit.quantum_info.Clifford)]] + + A list of tuples of qubit indices and a Clifford that acts on them. + + The list is in temporal order. Each element contains the qubit indices that the corresponding Clifford acts on. + + + ### model\_gate + + + Type: [`Self`](https://docs.python.org/3/library/typing.html#typing.Self) + + Return a [`ModelGate`](#qiskit_noise_learning.gate_sets.ModelGate "qiskit_noise_learning.gate_sets.ModelGate") representing this gate. + + + ### constituent\_gate\_idxs + + + Type: [`Iterator`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterator)\[[`tuple`](https://docs.python.org/3/library/stdtypes.html#tuple)\[[`int`](https://docs.python.org/3/library/functions.html#int), ...]] + + Iterator over tuples of physical indices that specify where constituent gates act. + + Some subclasses may not have a meaningful notion of what a “constituent gate” is, because they don’t choose to represent unitary action by some seperable representation. The only contract they need to obey is that the union of all yielded integers is equal to [`gate_idxs`](gate-sets-gate#gate_idxs "qiskit_noise_learning.gate_sets.Gate.gate_idxs"). + + + ### clifford\_propagate + + + Given a Pauli, propagate it through the ideal Clifford operation. + + If `inverse == False` (the default), then this method returns $C P C^\dagger$, and otherwise returns $C^\dagger P C$. + + If the input is a phaseless Pauli type, the propagation will be phaseless. + + Note that the Clifford will be applied to on `self.qubit_idxs`. + + **Parameters** + + * **pauli** – The Pauli to propagate. + * **inverse** – Whether to apply the gate or its inverse. + + **Returns** + + The propagated result, which has the same type as the input. + + **Raises** + + [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError) – If invalid type supplied. + + + diff --git a/docs/api/qiskit-noise-learning/generated/gate-sets-qiskit-gate-set.mdx b/docs/api/qiskit-noise-learning/generated/gate-sets-qiskit-gate-set.mdx new file mode 100644 index 000000000000..6eaa78d13ae6 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/gate-sets-qiskit-gate-set.mdx @@ -0,0 +1,256 @@ +--- +title: QiskitGateSet (latest version) +description: API reference for qiskit_noise_learning.gate_sets.QiskitGateSet in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.gate_sets.QiskitGateSet +--- + + + +# qiskit\_noise\_learning.gate\_sets.QiskitGateSet + + + Bases: [`GateSet`](gate-sets-gate-set "qiskit_noise_learning.gate_sets.gate_set.GateSet")\[[`QiskitGate`](gate-sets-qiskit-gate "qiskit_noise_learning.gate_sets.qiskit_gate.QiskitGate")] + + A gate set whose noise is to be learned and that is specified using Qiskit objects. + + Here, we are using “gate” in the context of noise learning, where our operations of interest are not typically the smallest operations that are discretely executed on a device (such as `cz` gates), but rather collections of such operations whose noise will be learned together as a unit. To the point, typically, in this class, gates are layers. They need not be however; partial width layers and layers with overlapping operations within are valid. We require this object to represent a set of them because in certain cases their noise needs to be learned together in order to have a consistent gauge defined between their noise models, or to allow parametrizations of their noise models to be correlated. + + This object satisfies the Python mapping protocol so that, for example, gates can be extracted with dictionary syntax. The names of gates are always strings. + + ```python + >>> from qiskit_noise_learning.gate_sets import QiskitGateSet + >>> from qiskit.circuit import QuantumCircuit + + >>> # instantiate a new gate set on 10 qubits + >>> gate_set = QiskitGateSet(10) + + >>> # the gate set comes populated with preparation and measurement gates on all 10 qubits + >>> assert len(gate_set) == 2 + >>> assert "P" in gate_set and "M" in gate_set + ``` + + **Parameters** + + * **num\_qubits** – How many qubits the QPU of interest has. If a `target` is provided, this field may be omitted. + * **target** – An optional `Target` against which operations will be validated whenever gates are added to the gate set. Its number of qubits must match `num_qubits` if both are present. + * **qubit\_subset** – A subset of `range(num_qubits)` specifying the region of interest of the QPU. All gates added must act within this subset. By default, contains all qubits. When `add_default_spam` is `True`, the iteration order of this argument determines the qubit ordering of the default preparation and measurement gates. + * **add\_default\_spam** – Whether to initialize the gateset with gates that respectively implement state preparation (given name `"P"`) and state measurement (given name `"M"`) on all qubits in the region of interest. + * **name** – Name for this gate set. If `None`, `name` falls back to the class name. + * **latex\_str** – An optional LaTeX string for rendering this gate set. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | + | [`__init__`](#qiskit_noise_learning.gate_sets.QiskitGateSet.__init__ "qiskit_noise_learning.gate_sets.QiskitGateSet.__init__")(\[num\_qubits, target, qubit\_subset, ...]) | | + | [`add_box_as_gate`](#qiskit_noise_learning.gate_sets.QiskitGateSet.add_box_as_gate "qiskit_noise_learning.gate_sets.QiskitGateSet.add_box_as_gate")(box\_instr, \*\[, name, latex\_str]) | Add a Qiskit circuit instruction containing a box operation as a gate. | + | [`add_circuit_as_gate`](#qiskit_noise_learning.gate_sets.QiskitGateSet.add_circuit_as_gate "qiskit_noise_learning.gate_sets.QiskitGateSet.add_circuit_as_gate")(circuit\[, qubit\_idxs, ...]) | Add a quantum circuit object as a gate. | + | [`add_gate`](#qiskit_noise_learning.gate_sets.QiskitGateSet.add_gate "qiskit_noise_learning.gate_sets.QiskitGateSet.add_gate")(gate) | Add a gate to the gate set. | + | [`add_measurement`](#qiskit_noise_learning.gate_sets.QiskitGateSet.add_measurement "qiskit_noise_learning.gate_sets.QiskitGateSet.add_measurement")(qubit\_idxs, operation\_type, ...) | Add a gate to this gate set that measures specified qubits. | + | [`add_preparation`](#qiskit_noise_learning.gate_sets.QiskitGateSet.add_preparation "qiskit_noise_learning.gate_sets.QiskitGateSet.add_preparation")(\[qubit\_idxs, annotations, ...]) | Add a gate to this gate set that prepares (or resets) specified qubits. | + | [`build_new_gate`](#qiskit_noise_learning.gate_sets.QiskitGateSet.build_new_gate "qiskit_noise_learning.gate_sets.QiskitGateSet.build_new_gate")(\[name, idle\_unused, latex\_str]) | Return a circuit builder whose contents will be added as a gate. | + | `draw`() | Draw the device topology with per-gate coloring. | + | `get`(k\[,d]) | | + | `items`() | | + | `keys`() | | + | `values`() | | + + ## Attributes + + | | | + | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- | + | `label` | A string label for use in plotter legends. | + | `latex_str` | A LaTeX string for this gate set. | + | `math_label` | A string label for use within latex math mode. | + | [`model_gate_set`](#qiskit_noise_learning.gate_sets.QiskitGateSet.model_gate_set "qiskit_noise_learning.gate_sets.QiskitGateSet.model_gate_set") | The model for this gate set. | + | `name` | Name for this gate set, defaulting to the class name. | + | `num_qubits` | The total number of qubits of the device this gateset acts on. | + | `qubit_subset` | The indices of the subset of device qubits that all gates act on. | + | [`target`](#qiskit_noise_learning.gate_sets.QiskitGateSet.target "qiskit_noise_learning.gate_sets.QiskitGateSet.target") | The target of this gateset, if one exists. | + + ### model\_gate\_set + + + Type: [`ModelGateSet`](gate-sets-model-gate-set "qiskit_noise_learning.gate_sets.model_gate_set.ModelGateSet") + + The model for this gate set. + + + ### target + + + Type: [`Target`](/docs/api/qiskit/qiskit.transpiler.Target) | [`None`](https://docs.python.org/3/library/constants.html#None) + + The target of this gateset, if one exists. + + + ### add\_gate + + + Add a gate to the gate set. + + ```python + >>> from qiskit_noise_learning.gate_sets import QiskitGateSet, QiskitGate + >>> from qiskit.circuit import QuantumCircuit + + >>> gate_set = QiskitGateSet(10) + >>> circuit = QuantumCircuit(5) + >>> circuit.cx(3, 4) + >>> gate_set.add_gate(QiskitGate("gate0", circuit, [4, 5, 7, 8, 9])) + + >>> assert "gate0" in gate_set + ``` + + **Parameters** + + **gate** – The gate to add. + + **Raises** + + [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – If the gate acts on some qubits outside of the valid range, or this gate set has a target and some member of the gate does not comply, or if the name is already used in the gate set. + + + ### add\_box\_as\_gate + + + Add a Qiskit circuit instruction containing a box operation as a gate. + + ```python + >>> from qiskit_noise_learning.gate_sets import QiskitGateSet, QiskitGate + >>> from qiskit.circuit import QuantumCircuit + + >>> gate_set = QiskitGateSet(10) + >>> circuit = QuantumCircuit(10) + >>> with circuit.box(): + ... circuit.cx(3, 4) + ... # use noop to indicate that only the first 7 qubits will be part of the gate, + ... # otherwise it would be restricted to only qubits 3 and 4, and learned noise + ... # will only be with respect to those two qubits + ... circuit.noop(range(7)) + + >>> name = gate_set.add_box_as_gate(circuit[0]) + + >>> assert name in gate_set + ``` + + **Parameters** + + * **box\_instr** – The circuit instruction containing a box operation. + * **name** – The name of the gate, or `None` to have a name chosen for you. + * **latex\_str** – An optional LaTeX string for this gate. + + **Returns** + + The name of the added gate. + + **Raises** + + [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – If the provided instruction does not contain a [`qiskit.circuit.BoxOp`](/docs/api/qiskit/qiskit.circuit.BoxOp) operation, or if the instruction acts on non-physical qubits. + + + ### add\_circuit\_as\_gate + + + Add a quantum circuit object as a gate. + + This method is a thin wrapper for [`add_gate()`](#qiskit_noise_learning.gate_sets.QiskitGateSet.add_gate "qiskit_noise_learning.gate_sets.QiskitGateSet.add_gate") that constructs a [`QiskitGate`](gate-sets-qiskit-gate "qiskit_noise_learning.gate_sets.QiskitGate") for you. + + ```python + >>> from qiskit_noise_learning.gate_sets import QiskitGateSet, QiskitGate + >>> from qiskit.circuit import QuantumCircuit + + >>> gate_set = QiskitGateSet(10) + >>> circuit = QuantumCircuit(5) + >>> circuit.cx(3, 4) + >>> name = gate_set.add_circuit_as_gate(circuit, [4, 5, 7, 8, 9]) + + >>> assert name in gate_set + ``` + + + The `circuit.qubits` are completely irrelevant and do not, for example, represent physical qubits. Instead, the mapping `dict(zip(circuit.qubits, qubit_idxs))` provides the recipe for which physical qubits each qubit in the circuit corresponds to. + + + **Parameters** + + * **circuit** – The circuit to use as a gate. + * **qubit\_idxs** – The physical qubits on which the circuit acts. + * **annotations** – The annotations that describe how to implement the circuit, or `None` to use the default annotations of [`QiskitGate`](gate-sets-qiskit-gate "qiskit_noise_learning.gate_sets.QiskitGate"). + * **name** – The name of the gate, or `None` to have a name chosen for you. + * **latex\_str** – An optional LaTeX string for this gate. + + **Returns** + + The name of the added gate. + + + ### build\_new\_gate + + + Return a circuit builder whose contents will be added as a gate. + + ```python + >>> from qiskit_noise_learning.gate_sets import QiskitGateSet, QiskitGate + >>> from qiskit.circuit import QuantumCircuit + + >>> gate_set = QiskitGateSet(10) + >>> with gate_set.build_new_gate() as builder: + ... builder.circuit.cx(4, 5) + + >>> assert builder.name in gate_set + >>> assert set(gate_set[builder.name].qubit_idxs) == set(range(10)) + ``` + + **Parameters** + + * **name** – The name of the gate, or `None` to have a name chosen for you. + * **idle\_unused** – Whether all qubits in [`qubit_subset`](gate-sets-gate-set#qubit_subset "qiskit_noise_learning.gate_sets.GateSet.qubit_subset") that are not already part of the gate will be automatically included as idling qubits. + * **latex\_str** – An optional LaTeX string for this gate. + + **Returns** + + A circuit builder. + + + ### add\_measurement + + + Add a gate to this gate set that measures specified qubits. + + **Parameters** + + * **qubit\_idxs** – The physical qubit indices to measure. + * **operation\_type** – The type of measurement operation to apply on each qubit. + * **annotations** – The annotations that describe how to implement the measurement, or `None` to use the default annotations of [`QiskitGate`](gate-sets-qiskit-gate "qiskit_noise_learning.gate_sets.QiskitGate"). + * **name** – The name of the gate, or `None` to have a name chosen for you. + * **latex\_str** – An optional LaTeX string for this gate. + + **Returns** + + The name of the added gate. + + + ### add\_preparation + + + Add a gate to this gate set that prepares (or resets) specified qubits. + + **Parameters** + + * **qubit\_idxs** – The physical qubit indices to prepare. + * **annotations** – The annotations that describe how to implement the preparation, or `None` to use the default annotations of [`QiskitGate`](gate-sets-qiskit-gate "qiskit_noise_learning.gate_sets.QiskitGate"). + * **name** – The name of the gate, or `None` to have a name chosen for you. + * **latex\_str** – An optional LaTeX string for this gate. + + **Returns** + + The name of the added gate. + + + diff --git a/docs/api/qiskit-noise-learning/generated/gate-sets-qiskit-gate.mdx b/docs/api/qiskit-noise-learning/generated/gate-sets-qiskit-gate.mdx new file mode 100644 index 000000000000..b04560807666 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/gate-sets-qiskit-gate.mdx @@ -0,0 +1,131 @@ +--- +title: QiskitGate (latest version) +description: API reference for qiskit_noise_learning.gate_sets.QiskitGate in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.gate_sets.QiskitGate +--- + + + +# qiskit\_noise\_learning.gate\_sets.QiskitGate + + + Bases: [`Gate`](gate-sets-gate "qiskit_noise_learning.gate_sets.gate.Gate") + + Represents a single gate in a [`QiskitGateSet`](gate-sets-qiskit-gate-set "qiskit_noise_learning.gate_sets.QiskitGateSet"). + + It is assumed that the gate consists of a sequence of unitary operations, followed by measurements, with no qubit being measured more than once, and finally preparations or resets. This is not currently validated. + + In many ways, this class is similar to a [`CircuitInstruction`](/docs/api/qiskit/qiskit.circuit.CircuitInstruction) containing a [`BoxOp`](/docs/api/qiskit/qiskit.circuit.BoxOp) in that it represents the action on some subset of qubits, and possibly with some of those qubits idling. It differs in that the physical qubits are represented as integers rather than [`Qubit`](/docs/api/qiskit/circuit#qiskit.circuit.Qubit) objects, and that we explicitly store which physical qubit indices perform preparation (or reset) operations. + + This class also implements the equality operation, where two [`QiskitGate`](#qiskit_noise_learning.gate_sets.QiskitGate "qiskit_noise_learning.gate_sets.QiskitGate") instances are equal whenever their physical indices are equal, and their circuits are equal taking into account permutations of the lists `qubit_idxs` and `circuit.qubits`. + + **Parameters** + + * **name** – The name for the gate. + * **circuit** – The quantum circuit. + * **qubit\_idxs** – The physical qubit indices that `circuit.qubits` act on. + * **prep\_idxs** – The physical qubit indices that this gate prepares, or resets. This is included because explicitly using the `Reset` instruction is not common. + * **annotations** – The annotations that describe how to implement the gate. If `None`, this defaults to Pauli twirling. If no `samplomatic.Tag` annotation is provided, then one is added automatically whose tag name is equal to `name`. + * **latex\_str** – An optional LaTeX string for this gate. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- | + | [`__init__`](#qiskit_noise_learning.gate_sets.QiskitGate.__init__ "qiskit_noise_learning.gate_sets.QiskitGate.__init__")(name, circuit, qubit\_idxs\[, ...]) | | + | [`draw`](#qiskit_noise_learning.gate_sets.QiskitGate.draw "qiskit_noise_learning.gate_sets.QiskitGate.draw")(\*args, \*\*kwargs) | Draw this gate as a circuit diagram. | + | [`iter_ops`](#qiskit_noise_learning.gate_sets.QiskitGate.iter_ops "qiskit_noise_learning.gate_sets.QiskitGate.iter_ops")() | Iterate through the operations that compose this gate in circuit order. | + + ## Attributes + + | | | + | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | + | [`annotations`](#qiskit_noise_learning.gate_sets.QiskitGate.annotations "qiskit_noise_learning.gate_sets.QiskitGate.annotations") | The annotations to use with this gate. | + | [`circuit`](#qiskit_noise_learning.gate_sets.QiskitGate.circuit "qiskit_noise_learning.gate_sets.QiskitGate.circuit") | A circuit representation of this gate. | + | [`constituent_gate_idxs`](#qiskit_noise_learning.gate_sets.QiskitGate.constituent_gate_idxs "qiskit_noise_learning.gate_sets.QiskitGate.constituent_gate_idxs") | Iterator over tuples of physical indices that specify where constituent gates act. | + | `gate_idxs` | The physical indices where this gate undergoes unitary action. | + | `idling_idxs` | The physical qubit indices that this gate is idling on. | + | `label` | A string label for use in plotter legends. | + | `latex_str` | A LaTeX string for this gate. | + | `math_label` | A string label for use within latex math mode. | + | `meas_idxs` | The physical qubit indices that this gate measures. | + | [`model_gate`](#qiskit_noise_learning.gate_sets.QiskitGate.model_gate "qiskit_noise_learning.gate_sets.QiskitGate.model_gate") | The model for this gate. | + | `name` | The gate name. | + | `num_qubits` | The number of qubits this gate acts on. | + | `prep_idxs` | The physical qubit indices that this gate prepares (or resets). | + | `qubit_idxs` | The physical qubit indices this gate acts on. | + | `sorted_meas_idxs` | The indices of the measured qubits in increasing order. | + | `sorted_prep_idxs` | The indices of the reset qubits in increasing order. | + + ### circuit + + + Type: [`QuantumCircuit`](/docs/api/qiskit/qiskit.circuit.QuantumCircuit) + + A circuit representation of this gate. + + + The `circuit.qubits` are completely irrelevant and do not, for example, represent physical qubits. Instead, the mappnig `dict(zip(circuit.qubits, qubit_idxs))` provides the recipe for which physical qubits each qubit in the circuit corresponds to. See also [`iter_ops()`](#qiskit_noise_learning.gate_sets.QiskitGate.iter_ops "qiskit_noise_learning.gate_sets.QiskitGate.iter_ops"). + + + + ### annotations + + + Type: [`list`](https://docs.python.org/3/library/stdtypes.html#list)\[[`Annotation`](/docs/api/qiskit/qiskit.circuit.Annotation)] + + The annotations to use with this gate. + + + ### constituent\_gate\_idxs + + + Type: [`Iterator`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterator)\[[`tuple`](https://docs.python.org/3/library/stdtypes.html#tuple)\[[`int`](https://docs.python.org/3/library/functions.html#int), ...]] + + Iterator over tuples of physical indices that specify where constituent gates act. + + Some subclasses may not have a meaningful notion of what a “constituent gate” is, because they don’t choose to represent unitary action by some seperable representation. The only contract they need to obey is that the union of all yielded integers is equal to [`gate_idxs`](gate-sets-gate#gate_idxs "qiskit_noise_learning.gate_sets.Gate.gate_idxs"). + + + ### iter\_ops + + + Iterate through the operations that compose this gate in circuit order. + + **Yields** + + Tuples `(physical_qubits, operation)` for each instruction in [`circuit`](#qiskit_noise_learning.gate_sets.QiskitGate.circuit "qiskit_noise_learning.gate_sets.QiskitGate.circuit"). + + + ### model\_gate + + + Type: [`ModelGate`](gate-sets-model-gate "qiskit_noise_learning.gate_sets.model_gate.ModelGate") + + The model for this gate. + + + ### draw + + + Draw this gate as a circuit diagram. + + Wire labels display the mapping from virtual qubit indices (the circuit’s qubit ordering) to physical qubit indices, using the Qiskit `TranspileLayout` convention, e.g. `v_0 -> 5`. + + **Parameters** + + * **\*args** – Positional keyword arguments forwarded to [`draw()`](/docs/api/qiskit/qiskit.circuit.QuantumCircuit#draw). + * **\*\*kwargs** – Keyword arguments forwarded to [`draw()`](/docs/api/qiskit/qiskit.circuit.QuantumCircuit#draw). + + **Returns** + + Text, matplotlib figure, or latex depending on the `output` kwarg. + + + diff --git a/docs/api/qiskit-noise-learning/generated/math-composed-linear-map.mdx b/docs/api/qiskit-noise-learning/generated/math-composed-linear-map.mdx new file mode 100644 index 000000000000..20e141f4df32 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/math-composed-linear-map.mdx @@ -0,0 +1,81 @@ +--- +title: ComposedLinearMap (latest version) +description: API reference for qiskit_noise_learning.math.ComposedLinearMap in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.math.ComposedLinearMap +--- + + + +# qiskit\_noise\_learning.math.ComposedLinearMap + + + Bases: [`LinearMap`](math-linear-map "qiskit_noise_learning.math.linear_map.LinearMap")\[`InputIndex`, `OutputIndex`] + + A linear map formed by composing a chain of maps. + + Maps are stored in application order: `maps[0]` is applied first (innermost), `maps[-1]` is applied last (outermost). + + **Parameters** + + **maps** – The ordered sequence of maps to compose. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | -------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | + | [`__init__`](#qiskit_noise_learning.math.ComposedLinearMap.__init__ "qiskit_noise_learning.math.ComposedLinearMap.__init__")(maps) | | + | [`compose`](#qiskit_noise_learning.math.ComposedLinearMap.compose "qiskit_noise_learning.math.ComposedLinearMap.compose")(outer) | Post-compose: self maps I->O, outer maps O->C, result maps I->C. | + | `left_multiply`(matrix) | Multiply on the left by an explicit matrix. | + | [`pre_compose`](#qiskit_noise_learning.math.ComposedLinearMap.pre_compose "qiskit_noise_learning.math.ComposedLinearMap.pre_compose")(inner) | Pre-compose: inner maps A->I, self maps I->O, result maps A->O. | + | `projected_output`(output\_indices, vector) | Compute a projection of the map applied to a vector. | + | [`rows`](#qiskit_noise_learning.math.ComposedLinearMap.rows "qiskit_noise_learning.math.ComposedLinearMap.rows")(output\_indices) | Construct the sub-matrix whose rows are the given output indices. | + + ## Attributes + + | | | + | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | + | `input_space` | The input space. | + | [`maps`](#qiskit_noise_learning.math.ComposedLinearMap.maps "qiskit_noise_learning.math.ComposedLinearMap.maps") | The ordered list of maps in application order. | + | `output_space` | The output space. | + + ### maps + + + Type: [`list`](https://docs.python.org/3/library/stdtypes.html#list)\[[`LinearMap`](math-linear-map "qiskit_noise_learning.math.linear_map.LinearMap")] + + The ordered list of maps in application order. + + + ### rows + + + Construct the sub-matrix whose rows are the given output indices. + + **Parameters** + + **output\_indices** – The labels for the desired rows of the matrix. + + **Returns** + + [`IndexedMatrix`](math-indexed-matrix "qiskit_noise_learning.math.IndexedMatrix") + + + ### compose + + + Post-compose: self maps I->O, outer maps O->C, result maps I->C. + + + ### pre\_compose + + + Pre-compose: inner maps A->I, self maps I->O, result maps A->O. + + + diff --git a/docs/api/qiskit-noise-learning/generated/math-enumerated-indexed-space.mdx b/docs/api/qiskit-noise-learning/generated/math-enumerated-indexed-space.mdx new file mode 100644 index 000000000000..8a4609e37022 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/math-enumerated-indexed-space.mdx @@ -0,0 +1,48 @@ +--- +title: EnumeratedIndexedSpace (latest version) +description: API reference for qiskit_noise_learning.math.EnumeratedIndexedSpace in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.math.EnumeratedIndexedSpace +--- + + + +# qiskit\_noise\_learning.math.EnumeratedIndexedSpace + + + Bases: [`IndexedSpace`](math-indexed-space "qiskit_noise_learning.math.indexed_space.IndexedSpace")\[`Index`] + + An indexed space backed by an explicit finite collection of indices. + + **Parameters** + + **indices** – The collection of valid indices in this space. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ----------------------------------------------------------------------------------------------------------------------------------------------- | - | + | [`__init__`](#qiskit_noise_learning.math.EnumeratedIndexedSpace.__init__ "qiskit_noise_learning.math.EnumeratedIndexedSpace.__init__")(indices) | | + + ## Attributes + + | | | + | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | + | [`dim`](#qiskit_noise_learning.math.EnumeratedIndexedSpace.dim "qiskit_noise_learning.math.EnumeratedIndexedSpace.dim") | The dimension (cardinality) of the space. | + + ### dim + + + Type: [`int`](https://docs.python.org/3/library/functions.html#int) + + The dimension (cardinality) of the space. + + May be `math.inf` for infinite-dimensional spaces. + + + diff --git a/docs/api/qiskit-noise-learning/generated/math-indexed-matrix.mdx b/docs/api/qiskit-noise-learning/generated/math-indexed-matrix.mdx new file mode 100644 index 000000000000..2f18c5726187 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/math-indexed-matrix.mdx @@ -0,0 +1,160 @@ +--- +title: IndexedMatrix (latest version) +description: API reference for qiskit_noise_learning.math.IndexedMatrix in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.math.IndexedMatrix +--- + + + +# qiskit\_noise\_learning.math.IndexedMatrix + + + Bases: [`Generic`](https://docs.python.org/3/library/typing.html#typing.Generic)\[`RowIndex`, `ColumnIndex`] + + A matrix with float entries and arbitrary row and column index data. + + **Parameters** + + * **row\_index\_map** – A mapping from row indices to the integer row axes of `data`. + * **column\_index\_map** – A mapping from column indices to the integer column axes of `data`. + * **data** – The array for the given row and column indices. + + **Raises** + + [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – If the shape of `data` is inconsistent with the values of `row_index_map` or `column_index_map`. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | + | [`__init__`](#qiskit_noise_learning.math.IndexedMatrix.__init__ "qiskit_noise_learning.math.IndexedMatrix.__init__")(\[row\_index\_map, column\_index\_map, data]) | | + | [`add_rows`](#qiskit_noise_learning.math.IndexedMatrix.add_rows "qiskit_noise_learning.math.IndexedMatrix.add_rows")(row\_indices, rows\[, tol]) | Add rows to the matrix. | + | [`copy`](#qiskit_noise_learning.math.IndexedMatrix.copy "qiskit_noise_learning.math.IndexedMatrix.copy")() | Return a copy of self. | + | [`from_index_lists`](#qiskit_noise_learning.math.IndexedMatrix.from_index_lists "qiskit_noise_learning.math.IndexedMatrix.from_index_lists")(row\_indices, ...) | Construct from ordered lists of row and column indices. | + | [`from_rows`](#qiskit_noise_learning.math.IndexedMatrix.from_rows "qiskit_noise_learning.math.IndexedMatrix.from_rows")(row\_indices, rows\[, tol]) | Construct from row indices and their sparse [`IndexedVector`](math-indexed-vector "qiskit_noise_learning.math.IndexedVector") rows. | + | [`linearly_independent_rows`](#qiskit_noise_learning.math.IndexedMatrix.linearly_independent_rows "qiskit_noise_learning.math.IndexedMatrix.linearly_independent_rows")(\[tol]) | Return a submatrix containing a maximal set of linearly independent rows. | + + ## Attributes + + | | | + | -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | + | [`column_index_map`](#qiskit_noise_learning.math.IndexedMatrix.column_index_map "qiskit_noise_learning.math.IndexedMatrix.column_index_map") | Dictionary mapping column indices to the column axis integer of `self.data`. | + | [`data`](#qiskit_noise_learning.math.IndexedMatrix.data "qiskit_noise_learning.math.IndexedMatrix.data") | The numerical data. | + | [`rank`](#qiskit_noise_learning.math.IndexedMatrix.rank "qiskit_noise_learning.math.IndexedMatrix.rank") | The rank of the matrix. | + | [`row_index_map`](#qiskit_noise_learning.math.IndexedMatrix.row_index_map "qiskit_noise_learning.math.IndexedMatrix.row_index_map") | Dictionary mapping row indices to the row axis integer of `self.data`. | + | [`shape`](#qiskit_noise_learning.math.IndexedMatrix.shape "qiskit_noise_learning.math.IndexedMatrix.shape") | The shape of the matrix. | + + ### from\_index\_lists + + + Construct from ordered lists of row and column indices. + + **Parameters** + + * **row\_indices** – The list of row indices for the row axes of `data`. + * **column\_indices** – The list of column indices for the column axes of `data`. + * **data** – The data matrix. + + **Returns** + + An [`IndexedMatrix`](#qiskit_noise_learning.math.IndexedMatrix "qiskit_noise_learning.math.IndexedMatrix") whose row and column index maps are built from `row_indices` and `column_indices`. + + + ### from\_rows + + + Construct from row indices and their sparse [`IndexedVector`](math-indexed-vector "qiskit_noise_learning.math.IndexedVector") rows. + + **Parameters** + + * **row\_indices** – The index for each row. + * **rows** – The sparse rows, as [`IndexedVector`](math-indexed-vector "qiskit_noise_learning.math.IndexedVector") instances. + * **tol** – Tolerance below which row values are treated as `0.0`. + + **Returns** + + An [`IndexedMatrix`](#qiskit_noise_learning.math.IndexedMatrix "qiskit_noise_learning.math.IndexedMatrix") containing the (non-zero) rows. + + + ### row\_index\_map + + + Type: [`dict`](https://docs.python.org/3/library/stdtypes.html#dict)\[`RowIndex`, [`int`](https://docs.python.org/3/library/functions.html#int)] + + Dictionary mapping row indices to the row axis integer of `self.data`. + + + ### column\_index\_map + + + Type: [`dict`](https://docs.python.org/3/library/stdtypes.html#dict)\[`ColumnIndex`, [`int`](https://docs.python.org/3/library/functions.html#int)] + + Dictionary mapping column indices to the column axis integer of `self.data`. + + + ### data + + + Type: [`ndarray`](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray)\[[`float`](https://docs.python.org/3/library/functions.html#float)] + + The numerical data. + + + ### shape + + + Type: [`tuple`](https://docs.python.org/3/library/stdtypes.html#tuple)\[[`int`](https://docs.python.org/3/library/functions.html#int), [`int`](https://docs.python.org/3/library/functions.html#int)] + + The shape of the matrix. + + + ### rank + + + Type: [`int`](https://docs.python.org/3/library/functions.html#int) + + The rank of the matrix. + + + ### add\_rows + + + Add rows to the matrix. + + **Parameters** + + * **row\_indices** – A list of indices for the rows. + * **rows** – The list of rows. + * **tol** – Tolerance below which values in `rows` are assumed to be `0.0`. + + **Raises** + + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – If any row index is duplicated in `row_indices` or is already present in this instance. + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – If the number of row indices does not match the number of rows. + + + ### linearly\_independent\_rows + + + Return a submatrix containing a maximal set of linearly independent rows. + + Rows are processed in order (according to the indices in `self.row_index_map`): a row is kept if and only if it is linearly independent of all preceding kept rows. This guarantees earlier rows are always preferred. + + **Parameters** + + **tol** – The tolerance for determining linear independence based on the norm of the component of a row orthogonal to the span of preceding kept rows. + + + ### copy + + + Return a copy of self. + + + diff --git a/docs/api/qiskit-noise-learning/generated/math-indexed-space.mdx b/docs/api/qiskit-noise-learning/generated/math-indexed-space.mdx new file mode 100644 index 000000000000..6ab8ea2b6a24 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/math-indexed-space.mdx @@ -0,0 +1,44 @@ +--- +title: IndexedSpace (latest version) +description: API reference for qiskit_noise_learning.math.IndexedSpace in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.math.IndexedSpace +--- + + + +# qiskit\_noise\_learning.math.IndexedSpace + + + Bases: [`Generic`](https://docs.python.org/3/library/typing.html#typing.Generic)\[`Index`], [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC) + + Abstract description of a vector space with arbitrary basis index types. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | -------------------------------------------------------------------------------------------------------------------- | - | + | [`__init__`](#qiskit_noise_learning.math.IndexedSpace.__init__ "qiskit_noise_learning.math.IndexedSpace.__init__")() | | + + ## Attributes + + | | | + | --------------------------------------------------------------------------------------------------- | ----------------------------------------- | + | [`dim`](#qiskit_noise_learning.math.IndexedSpace.dim "qiskit_noise_learning.math.IndexedSpace.dim") | The dimension (cardinality) of the space. | + + ### dim + + + Type: [`int`](https://docs.python.org/3/library/functions.html#int) | [`float`](https://docs.python.org/3/library/functions.html#float) + + The dimension (cardinality) of the space. + + May be `math.inf` for infinite-dimensional spaces. + + + diff --git a/docs/api/qiskit-noise-learning/generated/math-indexed-vector.mdx b/docs/api/qiskit-noise-learning/generated/math-indexed-vector.mdx new file mode 100644 index 000000000000..dbe74e7e505e --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/math-indexed-vector.mdx @@ -0,0 +1,53 @@ +--- +title: IndexedVector (latest version) +description: API reference for qiskit_noise_learning.math.IndexedVector in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.math.IndexedVector +--- + + + +# qiskit\_noise\_learning.math.IndexedVector + + + Bases: [`dict`](https://docs.python.org/3/library/stdtypes.html#dict)\[`Index`, [`float`](https://docs.python.org/3/library/functions.html#float)] + + A vector of floats with arbitrary index, or axis label, data. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | + | [`__init__`](#qiskit_noise_learning.math.IndexedVector.__init__ "qiskit_noise_learning.math.IndexedVector.__init__")(\*args, \*\*kwargs) | | + | [`add`](#qiskit_noise_learning.math.IndexedVector.add "qiskit_noise_learning.math.IndexedVector.add")(other) | Return a new indexed vector that is the sum of self and other. | + | `clear`() | | + | `copy`() | | + | `fromkeys`(iterable\[, value]) | Create a new dictionary with keys from iterable and values set to value. | + | `get`(key\[, default]) | Return the value for key if key is in the dictionary, else default. | + | `items`() | | + | `keys`() | | + | [`mul`](#qiskit_noise_learning.math.IndexedVector.mul "qiskit_noise_learning.math.IndexedVector.mul")(const) | Return a new indexed vector by multipling self with a constant. | + | `pop`(k\[,d]) | If the key is not found, return the default if given; otherwise, raise a KeyError. | + | `popitem`() | Remove and return a (key, value) pair as a 2-tuple. | + | `setdefault`(key\[, default]) | Insert key with a value of default if key is not in the dictionary. | + | `update`(\[E, ]\*\*F) | If E is present and has a .keys() method, then does: for k in E.keys(): D\[k] = E\[k] If E is present and lacks a .keys() method, then does: for k, v in E: D\[k] = v In either case, this is followed by: for k in F: D\[k] = F\[k] | + | `values`() | | + + ### add + + + Return a new indexed vector that is the sum of self and other. + + + ### mul + + + Return a new indexed vector by multipling self with a constant. + + + diff --git a/docs/api/qiskit-noise-learning/generated/math-linear-map.mdx b/docs/api/qiskit-noise-learning/generated/math-linear-map.mdx new file mode 100644 index 000000000000..c65ca3374a85 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/math-linear-map.mdx @@ -0,0 +1,122 @@ +--- +title: LinearMap (latest version) +description: API reference for qiskit_noise_learning.math.LinearMap in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.math.LinearMap +--- + + + +# qiskit\_noise\_learning.math.LinearMap + + + Bases: [`Generic`](https://docs.python.org/3/library/typing.html#typing.Generic)\[`InputIndex`, `OutputIndex`], [`ABC`](https://docs.python.org/3/library/abc.html#abc.ABC) + + An implicit linear map between two indexed spaces. + + **Parameters** + + * **input\_space** – The input space. + * **output\_space** – The output space. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | + | [`__init__`](#qiskit_noise_learning.math.LinearMap.__init__ "qiskit_noise_learning.math.LinearMap.__init__")(input\_space, output\_space) | | + | [`compose`](#qiskit_noise_learning.math.LinearMap.compose "qiskit_noise_learning.math.LinearMap.compose")(outer) | Post-compose: self maps I->O, outer maps O->C, result maps I->C. | + | [`left_multiply`](#qiskit_noise_learning.math.LinearMap.left_multiply "qiskit_noise_learning.math.LinearMap.left_multiply")(matrix) | Multiply on the left by an explicit matrix. | + | [`pre_compose`](#qiskit_noise_learning.math.LinearMap.pre_compose "qiskit_noise_learning.math.LinearMap.pre_compose")(inner) | Pre-compose: inner maps A->I, self maps I->O, result maps A->O. | + | [`projected_output`](#qiskit_noise_learning.math.LinearMap.projected_output "qiskit_noise_learning.math.LinearMap.projected_output")(output\_indices, vector) | Compute a projection of the map applied to a vector. | + | [`rows`](#qiskit_noise_learning.math.LinearMap.rows "qiskit_noise_learning.math.LinearMap.rows")(output\_indices) | Construct the sub-matrix whose rows are the given output indices. | + + ## Attributes + + | | | + | ------------------------------------------------------------------------------------------------------------------------ | ----------------- | + | [`input_space`](#qiskit_noise_learning.math.LinearMap.input_space "qiskit_noise_learning.math.LinearMap.input_space") | The input space. | + | [`output_space`](#qiskit_noise_learning.math.LinearMap.output_space "qiskit_noise_learning.math.LinearMap.output_space") | The output space. | + + ### input\_space + + + Type: [`IndexedSpace`](math-indexed-space "qiskit_noise_learning.math.indexed_space.IndexedSpace")\[`InputIndex`] + + The input space. + + + ### output\_space + + + Type: [`IndexedSpace`](math-indexed-space "qiskit_noise_learning.math.indexed_space.IndexedSpace")\[`OutputIndex`] + + The output space. + + + ### rows + + + Construct the sub-matrix whose rows are the given output indices. + + **Parameters** + + **output\_indices** – The labels for the desired rows of the matrix. + + **Returns** + + [`IndexedMatrix`](math-indexed-matrix "qiskit_noise_learning.math.IndexedMatrix") + + + ### left\_multiply + + + Multiply on the left by an explicit matrix. + + **Parameters** + + **matrix** – A matrix whose column indices are output indices of this map. + + **Returns** + + The resulting matrix. + + + ### projected\_output + + + Compute a projection of the map applied to a vector. + + The projection is defined by an iterable of output indices: only the component of the vector on those output indices will be returned. + + **Parameters** + + * **output\_indices** – The output indices defining the projection. + * **vector** – A mapping from input indices to floats. + + **Returns** + + The projected output vector. + + **Raises** + + [**KeyError**](https://docs.python.org/3/library/exceptions.html#KeyError) – If an input index appearing in the rows is not present in `vector`. + + + ### compose + + + Post-compose: self maps I->O, outer maps O->C, result maps I->C. + + + ### pre\_compose + + + Pre-compose: inner maps A->I, self maps I->O, result maps A->O. + + + diff --git a/docs/api/qiskit-noise-learning/generated/models-contains-pauli-lindblad-model.mdx b/docs/api/qiskit-noise-learning/generated/models-contains-pauli-lindblad-model.mdx new file mode 100644 index 000000000000..f08982ad3846 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/models-contains-pauli-lindblad-model.mdx @@ -0,0 +1,24 @@ +--- +title: contains_pauli_lindblad_model (latest version) +description: API reference for qiskit_noise_learning.models.contains_pauli_lindblad_model in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit_noise_learning.models.contains_pauli_lindblad_model +--- + + + +# qiskit\_noise\_learning.models.contains\_pauli\_lindblad\_model + + + Whether a map is, or contains, a [`PauliLindbladModel`](models-pauli-lindblad-model "qiskit_noise_learning.models.PauliLindbladModel"). + + **Parameters** + + **model** – The map to inspect. + + **Returns** + + `True` if `model` is a [`PauliLindbladModel`](models-pauli-lindblad-model "qiskit_noise_learning.models.PauliLindbladModel") or a [`ComposedLinearMap`](math-composed-linear-map "qiskit_noise_learning.math.ComposedLinearMap") whose chain contains one. + + diff --git a/docs/api/qiskit-noise-learning/generated/models-generator-index.mdx b/docs/api/qiskit-noise-learning/generated/models-generator-index.mdx new file mode 100644 index 000000000000..be6342642b78 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/models-generator-index.mdx @@ -0,0 +1,30 @@ +--- +title: Qiskit noise learning API documentation (latest version) +description: Index of all the modules in the latest version of qiskit-noise-learning. +--- + + + +# qiskit\_noise\_learning.models.GeneratorIndex + + + Bases: [`object`](https://docs.python.org/3/library/functions.html#object) + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ------------------------------------------------------------------------------------------------------------------------------------------------- | - | + | [`__init__`](#qiskit_noise_learning.models.GeneratorIndex.__init__ "qiskit_noise_learning.models.GeneratorIndex.__init__")(gate\_name, generator) | | + + ## Attributes + + | | | + | ----------- | - | + | `gate_name` | | + | `generator` | | + + diff --git a/docs/api/qiskit-noise-learning/generated/models-get-noise-site.mdx b/docs/api/qiskit-noise-learning/generated/models-get-noise-site.mdx new file mode 100644 index 000000000000..2c89b01de4b2 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/models-get-noise-site.mdx @@ -0,0 +1,24 @@ +--- +title: get_noise_site (latest version) +description: API reference for qiskit_noise_learning.models.get_noise_site in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit_noise_learning.models.get_noise_site +--- + + + +# qiskit\_noise\_learning.models.get\_noise\_site + + + The noise-site mapping of the map’s [`PauliLindbladModel`](models-pauli-lindblad-model "qiskit_noise_learning.models.PauliLindbladModel"), if it has exactly one. + + **Parameters** + + **model** – The map to inspect. + + **Returns** + + The `{gate_name: "before" | "after"}` mapping from the map’s single [`PauliLindbladModel`](models-pauli-lindblad-model "qiskit_noise_learning.models.PauliLindbladModel"), or `None` if `model` is, or contains, no (or more than one) [`PauliLindbladModel`](models-pauli-lindblad-model "qiskit_noise_learning.models.PauliLindbladModel"). + + diff --git a/docs/api/qiskit-noise-learning/generated/models-identity-fidelity-model.mdx b/docs/api/qiskit-noise-learning/generated/models-identity-fidelity-model.mdx new file mode 100644 index 000000000000..af47d232149b --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/models-identity-fidelity-model.mdx @@ -0,0 +1,71 @@ +--- +title: IdentityFidelityModel (latest version) +description: API reference for qiskit_noise_learning.models.IdentityFidelityModel in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.models.IdentityFidelityModel +--- + + + +# qiskit\_noise\_learning.models.IdentityFidelityModel + + + Bases: [`LinearMap`](math-linear-map "qiskit_noise_learning.math.linear_map.LinearMap")\[[`FidelityIndex`](sequences-fidelity-index "qiskit_noise_learning.sequences.fidelity_index.FidelityIndex"), [`FidelityIndex`](sequences-fidelity-index "qiskit_noise_learning.sequences.fidelity_index.FidelityIndex")] + + A fidelity model whose parameters are the log fidelities themselves. + + The parameterization matrix is the identity: the input and output spaces are the same [`LogFidelitySpace`](models-log-fidelity-space "qiskit_noise_learning.models.LogFidelitySpace"), and the row of a fidelity index is the unit vector on that index. + + **Parameters** + + **gate\_set** – The gate set whose fidelities are being modelled. To be converted to a [`ModelGateSet`](gate-sets-model-gate-set "qiskit_noise_learning.gate_sets.ModelGateSet"). + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | + | [`__init__`](#qiskit_noise_learning.models.IdentityFidelityModel.__init__ "qiskit_noise_learning.models.IdentityFidelityModel.__init__")(gate\_set) | | + | `compose`(outer) | Post-compose: self maps I->O, outer maps O->C, result maps I->C. | + | `left_multiply`(matrix) | Multiply on the left by an explicit matrix. | + | `pre_compose`(inner) | Pre-compose: inner maps A->I, self maps I->O, result maps A->O. | + | `projected_output`(output\_indices, vector) | Compute a projection of the map applied to a vector. | + | [`rows`](#qiskit_noise_learning.models.IdentityFidelityModel.rows "qiskit_noise_learning.models.IdentityFidelityModel.rows")(output\_indices) | Construct the sub-matrix whose rows are the given fidelity indices. | + + ## Attributes + + | | | + | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | + | [`gate_set`](#qiskit_noise_learning.models.IdentityFidelityModel.gate_set "qiskit_noise_learning.models.IdentityFidelityModel.gate_set") | The gate set whose fidelities are being modelled. | + | `input_space` | The input space. | + | `output_space` | The output space. | + + ### gate\_set + + + Type: [`ModelGateSet`](gate-sets-model-gate-set "qiskit_noise_learning.gate_sets.model_gate_set.ModelGateSet") + + The gate set whose fidelities are being modelled. + + + ### rows + + + Construct the sub-matrix whose rows are the given fidelity indices. + + Each row is the unit vector on its fidelity index (the identity parameterization). + + **Parameters** + + **output\_indices** – The fidelity indices labelling the desired rows. + + **Returns** + + An [`IndexedMatrix`](math-indexed-matrix "qiskit_noise_learning.math.IndexedMatrix") whose rows and columns are both the requested fidelity indices, with identity data. + + + diff --git a/docs/api/qiskit-noise-learning/generated/models-is-fidelity-model.mdx b/docs/api/qiskit-noise-learning/generated/models-is-fidelity-model.mdx new file mode 100644 index 000000000000..2f04fc54f6d0 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/models-is-fidelity-model.mdx @@ -0,0 +1,24 @@ +--- +title: is_fidelity_model (latest version) +description: API reference for qiskit_noise_learning.models.is_fidelity_model in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit_noise_learning.models.is_fidelity_model +--- + + + +# qiskit\_noise\_learning.models.is\_fidelity\_model + + + Whether an object is a [`LinearMap`](math-linear-map "qiskit_noise_learning.math.LinearMap") with a [`LogFidelitySpace`](models-log-fidelity-space "qiskit_noise_learning.models.LogFidelitySpace") output space. + + **Parameters** + + **model** – The object to check. + + **Returns** + + `True` if `model` is a [`LinearMap`](math-linear-map "qiskit_noise_learning.math.LinearMap") whose output space is a [`LogFidelitySpace`](models-log-fidelity-space "qiskit_noise_learning.models.LogFidelitySpace"), otherwise `False`. + + diff --git a/docs/api/qiskit-noise-learning/generated/models-log-fidelity-space.mdx b/docs/api/qiskit-noise-learning/generated/models-log-fidelity-space.mdx new file mode 100644 index 000000000000..9974d38b98b2 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/models-log-fidelity-space.mdx @@ -0,0 +1,59 @@ +--- +title: LogFidelitySpace (latest version) +description: API reference for qiskit_noise_learning.models.LogFidelitySpace in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.models.LogFidelitySpace +--- + + + +# qiskit\_noise\_learning.models.LogFidelitySpace + + + Bases: [`IndexedSpace`](math-indexed-space "qiskit_noise_learning.math.indexed_space.IndexedSpace")\[[`FidelityIndex`](sequences-fidelity-index "qiskit_noise_learning.sequences.fidelity_index.FidelityIndex")] + + The space of log fidelities of a gate set. + + The basis indices are the [`FidelityIndex`](sequences-fidelity-index "qiskit_noise_learning.sequences.FidelityIndex") objects of the gate set, excluding the trivial identity fidelity of each gate. See [`FidelityIndex`](sequences-fidelity-index "qiskit_noise_learning.sequences.FidelityIndex") for more information. + + **Parameters** + + **gate\_set** – The gate set whose fidelities the space describes. Converted to a [`ModelGateSet`](gate-sets-model-gate-set "qiskit_noise_learning.gate_sets.ModelGateSet"). + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ----------------------------------------------------------------------------------------------------------------------------------------- | - | + | [`__init__`](#qiskit_noise_learning.models.LogFidelitySpace.__init__ "qiskit_noise_learning.models.LogFidelitySpace.__init__")(gate\_set) | | + + ## Attributes + + | | | + | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | + | [`dim`](#qiskit_noise_learning.models.LogFidelitySpace.dim "qiskit_noise_learning.models.LogFidelitySpace.dim") | The total number of fidelities of the gate set, excluding the trivial identity ones. | + | [`gate_set`](#qiskit_noise_learning.models.LogFidelitySpace.gate_set "qiskit_noise_learning.models.LogFidelitySpace.gate_set") | The gate set whose fidelities this space describes. | + + ### gate\_set + + + Type: [`ModelGateSet`](gate-sets-model-gate-set "qiskit_noise_learning.gate_sets.model_gate_set.ModelGateSet") + + The gate set whose fidelities this space describes. + + + ### dim + + + Type: [`int`](https://docs.python.org/3/library/functions.html#int) + + The total number of fidelities of the gate set, excluding the trivial identity ones. + + Each gate contributes the count given by Equation [(4)](guides/formalism#equation-num-fidelities) of the [mathematical formalism](guides/formalism), less one. + + + diff --git a/docs/api/qiskit-noise-learning/generated/models-pauli-lindblad-model.mdx b/docs/api/qiskit-noise-learning/generated/models-pauli-lindblad-model.mdx new file mode 100644 index 000000000000..6a50b7161bef --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/models-pauli-lindblad-model.mdx @@ -0,0 +1,194 @@ +--- +title: PauliLindbladModel (latest version) +description: API reference for qiskit_noise_learning.models.PauliLindbladModel in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.models.PauliLindbladModel +--- + + + +# qiskit\_noise\_learning.models.PauliLindbladModel + + + Bases: [`LinearMap`](math-linear-map "qiskit_noise_learning.math.linear_map.LinearMap")\[[`GeneratorIndex`](models-generator-index "qiskit_noise_learning.models.pauli_lindblad_model.GeneratorIndex"), [`FidelityIndex`](sequences-fidelity-index "qiskit_noise_learning.sequences.fidelity_index.FidelityIndex")] + + A linear mapping from Pauli-Lindblad generator rates to log fidelities. + + This model class assumes that every gate in the gate set is either a unitary, a pure preparation (all qubits are prepared and the unitary part is trivial), or a pure measurement (all qubits are measured and the unitary part is trivial). It is further assumed that at least one preparation and at least one measurement gate are present. + + The noise model for each gate in this case is a Pauli channel, parameterized in terms of the rates of a Pauli-Lindblad decomposition $\exp(\sum_{P \in \mathcal{P}_n} r_P L(P))$, where the $r_P$ are the rates, and $L(P) = P \cdot P - \cdot$. In the case of unitary gates, the noise can be modelled as either occuring before or after the ideal unitary. + + **Parameters** + + * **gate\_set** – The gate set whose fidelities are being modelled. To be converted to a `ModelGateSet`. + * **generators** – A dictionary mapping gate name to the set of Pauli-Lindblad generators for the noise model of that gate. The generators for each gate must be unique. + * **noise\_site** – A dictionary specifying, for each gate name, whether the noise model occurs before or after the gate, indicated with strings `"before"` and `"after"`. Any unspecified values for the gate set will be populated with default values: `"before"` for unitary gates and pure measurement gates, and `"after"` for pure preparation. An error will be raised if a value for pure measurement or preparation is specified that differs from the default. + + **Raises** + + [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – If the gate set is not of the required form, or if `noise_model_before_gate` has any invalid values. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | + | [`__init__`](#qiskit_noise_learning.models.PauliLindbladModel.__init__ "qiskit_noise_learning.models.PauliLindbladModel.__init__")(gate\_set, generators\[, noise\_site]) | | + | `compose`(outer) | Post-compose: self maps I->O, outer maps O->C, result maps I->C. | + | [`k_local`](#qiskit_noise_learning.models.PauliLindbladModel.k_local "qiskit_noise_learning.models.PauliLindbladModel.k_local")(gate\_set\[, k, gate\_k, paulis, ...]) | Construct a k-local model. | + | [`k_partition_local`](#qiskit_noise_learning.models.PauliLindbladModel.k_partition_local "qiskit_noise_learning.models.PauliLindbladModel.k_partition_local")(gate\_set\[, k, gate\_k, ...]) | Construct a k-local model according to qubit partitions. | + | `left_multiply`(matrix) | Multiply on the left by an explicit matrix. | + | `pre_compose`(inner) | Pre-compose: inner maps A->I, self maps I->O, result maps A->O. | + | `projected_output`(output\_indices, vector) | Compute a projection of the map applied to a vector. | + | [`rows`](#qiskit_noise_learning.models.PauliLindbladModel.rows "qiskit_noise_learning.models.PauliLindbladModel.rows")(output\_indices) | Construct the sub-matrix whose rows are the given fidelity indices. | + | [`to_pauli_lindblad_maps`](#qiskit_noise_learning.models.PauliLindbladModel.to_pauli_lindblad_maps "qiskit_noise_learning.models.PauliLindbladModel.to_pauli_lindblad_maps")(model\_data\[, ...]) | Return a dictionary of `PauliLindbladMap` for each gate in the model. | + + ## Attributes + + | | | + | ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | + | [`gate_set`](#qiskit_noise_learning.models.PauliLindbladModel.gate_set "qiskit_noise_learning.models.PauliLindbladModel.gate_set") | The gate set whose fidelities are being modelled. | + | [`generators`](#qiskit_noise_learning.models.PauliLindbladModel.generators "qiskit_noise_learning.models.PauliLindbladModel.generators") | The generators for the noise model. | + | `input_space` | The input space. | + | [`meas_names`](#qiskit_noise_learning.models.PauliLindbladModel.meas_names "qiskit_noise_learning.models.PauliLindbladModel.meas_names") | The names of the measurements in this model. | + | [`noise_site`](#qiskit_noise_learning.models.PauliLindbladModel.noise_site "qiskit_noise_learning.models.PauliLindbladModel.noise_site") | Whether each noise map occurs before or after each gate. | + | `output_space` | The output space. | + | [`prep_names`](#qiskit_noise_learning.models.PauliLindbladModel.prep_names "qiskit_noise_learning.models.PauliLindbladModel.prep_names") | The names of the preparation in this model. | + + ### gate\_set + + + Type: [`ModelGateSet`](gate-sets-model-gate-set "qiskit_noise_learning.gate_sets.model_gate_set.ModelGateSet") + + The gate set whose fidelities are being modelled. + + + ### generators + + + Type: [`dict`](https://docs.python.org/3/library/stdtypes.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`QubitSparsePauliList`](/docs/api/qiskit/qiskit.quantum_info.QubitSparsePauliList)] + + The generators for the noise model. + + + ### meas\_names + + + Type: [`set`](https://docs.python.org/3/library/stdtypes.html#set)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str)] + + The names of the measurements in this model. + + + ### noise\_site + + + Type: [`dict`](https://docs.python.org/3/library/stdtypes.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`str`](https://docs.python.org/3/library/stdtypes.html#str)] + + Whether each noise map occurs before or after each gate. + + + ### prep\_names + + + Type: [`set`](https://docs.python.org/3/library/stdtypes.html#set)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str)] + + The names of the preparation in this model. + + + ### rows + + + Construct the sub-matrix whose rows are the given fidelity indices. + + **Parameters** + + **output\_indices** – The fidelity indices labelling the desired rows. + + **Returns** + + An [`IndexedMatrix`](math-indexed-matrix "qiskit_noise_learning.math.IndexedMatrix") indexed by the (non-zero) requested fidelity indices and by the generator indices appearing in those rows. + + **Raises** + + [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – If any fidelity index labels a gate that is not in the model. + + + ### k\_partition\_local + + + Construct a k-local model according to qubit partitions. + + Note that the default partition for this method (described below) results in differing default behaviour for this method as compared to [`PauliLindbladModel.k_local()`](#qiskit_noise_learning.models.PauliLindbladModel.k_local "qiskit_noise_learning.models.PauliLindbladModel.k_local"). + + This method defines k-locality in terms of partitions of a set of $n$-qubits, generalizing the usual notion beyond single qubits. A partition is a collection of disjoint sets of qubit indices that covers $\{0, ..., n - 1\}$. Two qubit indices $i, j$ are neighbours if either edge $(i, j)$ or $(j, i)$ is in the coupling map, which is drawn from `gate_set` or defaults to the complete coupling map. Given a partition $P$, two distinct qubit index sets $B_0, B_1 \in P$ are neighbours if there exists indices $i \in B_0$ and $j \in B_1$ that are neighbours. Similarly, distinct $B_0, B_1 \in P$ are next-nearest neighbours if there exists a distinct $B_2 \in P$ which is neighbours with both $B_0$ and $B_1$, and so on. + + For a given gate, the $k$-local model is built recursively starting with $1$-local terms defined in the argument `local_paulis`, with $1$-local terms for subsets of size `m` given by `local_paulis[m]`. $2$-local terms are built via tensor product of $1$-local terms between pairs of neighbouring subsets. Generally, $k$-local terms are built from the tensor product of $(k - 1)$-local terms and $1$-local terms on sets of $k$ connected sets. + + If no `qubit_partition` is supplied, the partition of singletons is assumed. If no `local_paulis` is supplied, the set of all possible Paulis on the given number of qubits is assumed. + + **Parameters** + + * **gate\_set** – The gate set being modelled. Must contain only Clifford, pure preparation, and pure measurement layers. To be converted to a `ModelGateSet`. The coupling map is drawn from `gate_set.model_gate_set.coupling_map`, or if it is `None`, defaults to the complete coupling map. + * **k** – The default degree of locality of the model. Applies to all gates not specified in `gate_k`. Defaults to `2`. + * **gate\_k** – A dictionary mapping gate names to per-gate locality values that override `k` for the specified gates. + * **qubit\_partitions** – A dictionary indicating a qubit partition for each gate. Any unspecified partitions will be populated with a default in which qubits are grouped together if they are connected by unitary gate operations. + * **local\_paulis** – A dictionary indicating the 1-local Paulis to use each qubit partition for each gate. I.e. `len(local_paulis[gate_name])` must equal the maximum partition size in `qubit_partitions[gate_name]`, and `local_paulis[gate_name][k].num_qubits` must equal `k`. For Clifford gates, `local_paulis[gate_name][k]` defaults to all possible non-identity Paulis on `k` qubits, and for measurement and preparation, it defaults to all Paulis consisting of $\{I, X\}$ on `k` qubits. + * **noise\_site** – Dictionary indicating whether to model gate noise as `"before"` or `"after"` the gate. + + **Returns** + + A new [`PauliLindbladModel`](#qiskit_noise_learning.models.PauliLindbladModel "qiskit_noise_learning.models.PauliLindbladModel") instance. + + **Raises** + + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – If any `k` value exceeds `len(gate_set.qubit_subset)`. + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – If `gate_k` contains names not in the gate set. + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – Name not in `gate_set` is used in any other dictionary. + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – Any partition is ill-formed. + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – `local_paulis` does not satisfy the assumed form. + + + ### k\_local + + + Construct a k-local model. + + This is equivalent to calling [`PauliLindbladModel.k_partition_local()`](#qiskit_noise_learning.models.PauliLindbladModel.k_partition_local "qiskit_noise_learning.models.PauliLindbladModel.k_partition_local") with each partition specified as partition of singletons for each gate. + + **Parameters** + + * **gate\_set** – The gate set being modelled. Must contain only Clifford, pure preparation, and pure measurement layers. To be converted to a `ModelGateSet`. + * **k** – The default degree of locality of the model. Applies to all gates not specified in `gate_k`. Defaults to `2`. + * **gate\_k** – A dictionary mapping gate names to per-gate locality values that override `k` for the specified gates. + * **paulis** – A dictionary indicating the single-qubit Paulis to use in the k-local model for each gate. For Clifford gates, defaults to all single qubit Paulis, and for measurement and preparation, defaults to $\{I, X\}$. + * **noise\_site** – Dictionary indicating whether to model gate noise as `"before"` or `"after"` the gate. + + **Returns** + + A new `PauliFidelityModel` instance. + + + ### to\_pauli\_lindblad\_maps + + + Return a dictionary of `PauliLindbladMap` for each gate in the model. + + **Parameters** + + * **model\_fit** – The fitted model parameters and covariance. + * **include\_spam** – Whether to include SPAM gates in the output. + + **Returns** + + A dictionary from gate names to corresponding noise maps. + + **Raises** + + [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – If `model_data` does not contain the correct parameters. + + + diff --git a/docs/api/qiskit-noise-learning/generated/models-pauli-lindblad-split.mdx b/docs/api/qiskit-noise-learning/generated/models-pauli-lindblad-split.mdx new file mode 100644 index 000000000000..e9a15211f3a2 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/models-pauli-lindblad-split.mdx @@ -0,0 +1,70 @@ +--- +title: PauliLindbladSplit (latest version) +description: API reference for qiskit_noise_learning.models.PauliLindbladSplit in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.models.PauliLindbladSplit +--- + + + +# qiskit\_noise\_learning.models.PauliLindbladSplit + + + Bases: [`NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple) + + The decomposition of a map around its underlying [`PauliLindbladModel`](models-pauli-lindblad-model "qiskit_noise_learning.models.PauliLindbladModel"). + + The original map is equivalent to `after @ model @ before` (`before` applied first). A `None` value for `before` or `after` indicates there are no maps on that side of `model`. + + **Parameters** + + * **before** – The maps applied before `model` (mapping into `model`’s input space), or `None`. + * **model** – The underlying [`PauliLindbladModel`](models-pauli-lindblad-model "qiskit_noise_learning.models.PauliLindbladModel"). + * **after** – The maps applied after `model` (mapping out of `model`’s output space), or `None`. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------- | + | [`__init__`](#qiskit_noise_learning.models.PauliLindbladSplit.__init__ "qiskit_noise_learning.models.PauliLindbladSplit.__init__")() | | + | `count`(value, /) | Return number of occurrences of value. | + | `index`(value\[, start, stop]) | Return first index of value. | + + ## Attributes + + | | | + | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------ | + | [`after`](#qiskit_noise_learning.models.PauliLindbladSplit.after "qiskit_noise_learning.models.PauliLindbladSplit.after") | Alias for field number 2 | + | [`before`](#qiskit_noise_learning.models.PauliLindbladSplit.before "qiskit_noise_learning.models.PauliLindbladSplit.before") | Alias for field number 0 | + | [`model`](#qiskit_noise_learning.models.PauliLindbladSplit.model "qiskit_noise_learning.models.PauliLindbladSplit.model") | Alias for field number 1 | + + ### before + + + Type: [`ComposedLinearMap`](math-composed-linear-map "qiskit_noise_learning.math.linear_map.ComposedLinearMap") | [`None`](https://docs.python.org/3/library/constants.html#None) + + Alias for field number 0 + + + ### model + + + Type: [`PauliLindbladModel`](models-pauli-lindblad-model "qiskit_noise_learning.models.pauli_lindblad_model.PauliLindbladModel") + + Alias for field number 1 + + + ### after + + + Type: [`ComposedLinearMap`](math-composed-linear-map "qiskit_noise_learning.math.linear_map.ComposedLinearMap") | [`None`](https://docs.python.org/3/library/constants.html#None) + + Alias for field number 2 + + + diff --git a/docs/api/qiskit-noise-learning/generated/models-rate-space.mdx b/docs/api/qiskit-noise-learning/generated/models-rate-space.mdx new file mode 100644 index 000000000000..02b3fc3c36e7 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/models-rate-space.mdx @@ -0,0 +1,57 @@ +--- +title: RateSpace (latest version) +description: API reference for qiskit_noise_learning.models.RateSpace in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.models.RateSpace +--- + + + +# qiskit\_noise\_learning.models.RateSpace + + + Bases: [`IndexedSpace`](math-indexed-space "qiskit_noise_learning.math.indexed_space.IndexedSpace")\[[`GeneratorIndex`](models-generator-index "qiskit_noise_learning.models.pauli_lindblad_model.GeneratorIndex")] + + Space of Pauli-Lindblad generator rates, indexed by [`GeneratorIndex`](models-generator-index "qiskit_noise_learning.models.GeneratorIndex"). + + **Parameters** + + **generators** – A dictionary mapping gate name to the gate’s Pauli-Lindblad generators. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ---------------------------------------------------------------------------------------------------------------------------- | - | + | [`__init__`](#qiskit_noise_learning.models.RateSpace.__init__ "qiskit_noise_learning.models.RateSpace.__init__")(generators) | | + + ## Attributes + + | | | + | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | + | [`dim`](#qiskit_noise_learning.models.RateSpace.dim "qiskit_noise_learning.models.RateSpace.dim") | The dimension (cardinality) of the space. | + | [`generators`](#qiskit_noise_learning.models.RateSpace.generators "qiskit_noise_learning.models.RateSpace.generators") | The Pauli-Lindblad generators for each gate. | + + ### generators + + + Type: [`dict`](https://docs.python.org/3/library/stdtypes.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`QubitSparsePauliList`](/docs/api/qiskit/qiskit.quantum_info.QubitSparsePauliList)] + + The Pauli-Lindblad generators for each gate. + + + ### dim + + + Type: [`int`](https://docs.python.org/3/library/functions.html#int) | [`float`](https://docs.python.org/3/library/functions.html#float) + + The dimension (cardinality) of the space. + + May be `math.inf` for infinite-dimensional spaces. + + + diff --git a/docs/api/qiskit-noise-learning/generated/models-split-pauli-lindblad-model.mdx b/docs/api/qiskit-noise-learning/generated/models-split-pauli-lindblad-model.mdx new file mode 100644 index 000000000000..34670db05661 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/models-split-pauli-lindblad-model.mdx @@ -0,0 +1,28 @@ +--- +title: split_pauli_lindblad_model (latest version) +description: API reference for qiskit_noise_learning.models.split_pauli_lindblad_model in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit_noise_learning.models.split_pauli_lindblad_model +--- + + + +# qiskit\_noise\_learning.models.split\_pauli\_lindblad\_model + + + Split a map around its underlying [`PauliLindbladModel`](models-pauli-lindblad-model "qiskit_noise_learning.models.PauliLindbladModel"). + + **Parameters** + + **model** – The map to split. + + **Returns** + + A [`PauliLindbladSplit`](models-pauli-lindblad-split "qiskit_noise_learning.models.PauliLindbladSplit") `(before, model, after)` such that the input map is equivalent to `after @ model @ before`. + + **Raises** + + [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – If `model` does not contain exactly one [`PauliLindbladModel`](models-pauli-lindblad-model "qiskit_noise_learning.models.PauliLindbladModel"). + + diff --git a/docs/api/qiskit-noise-learning/generated/noise-learner-learning-options.mdx b/docs/api/qiskit-noise-learning/generated/noise-learner-learning-options.mdx new file mode 100644 index 000000000000..8fdfa92be679 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/noise-learner-learning-options.mdx @@ -0,0 +1,133 @@ +--- +title: LearningOptions (latest version) +description: API reference for qiskit_noise_learning.noise_learner.LearningOptions in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.noise_learner.LearningOptions +--- + + + +# qiskit\_noise\_learning.noise\_learner.LearningOptions + + + Bases: `BaseModel` + + Options for the noise learner. + + ### \_\_init\_\_ + + + Create a new model by parsing and validating input data from keyword arguments. + + Raises \[ValidationError]\[pydantic\_core.ValidationError] if the input data cannot be validated to form a valid model. + + self is explicitly positional-only to allow self as a field name. + + + ## Methods + + | | | + | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | + | [`__init__`](#qiskit_noise_learning.noise_learner.LearningOptions.__init__ "qiskit_noise_learning.noise_learner.LearningOptions.__init__")(\*\*data) | Create a new model by parsing and validating input data from keyword arguments. | + | `construct`(\[\_fields\_set]) | | + | `copy`(\*\[, include, exclude, update, deep]) | Returns a copy of the model. | + | `dict`(\*\[, include, exclude, by\_alias, ...]) | | + | `from_orm`(obj) | | + | `json`(\*\[, include, exclude, by\_alias, ...]) | | + | `model_construct`(\[\_fields\_set]) | Creates a new instance of the Model class with validated data. | + | `model_copy`(\*\[, update, deep]) | !!! abstract "Usage Documentation" | + | `model_dump`(\*\[, mode, include, exclude, ...]) | !!! abstract "Usage Documentation" | + | `model_dump_json`(\*\[, indent, ensure\_ascii, ...]) | !!! abstract "Usage Documentation" | + | `model_json_schema`(by\_alias, ref\_template, ...) | Generates a JSON schema for a model class. | + | `model_parametrized_name`(params) | Compute the class name for parametrizations of generic classes. | + | `model_post_init`(context, /) | Override this method to perform additional initialization after \_\_init\_\_ and model\_construct. | + | `model_rebuild`(\*\[, force, raise\_errors, ...]) | Try to rebuild the pydantic-core schema for the model. | + | `model_validate`(obj, \*\[, strict, extra, ...]) | Validate a pydantic model instance. | + | `model_validate_json`(json\_data, \*\[, strict, ...]) | !!! abstract "Usage Documentation" | + | `model_validate_strings`(obj, \*\[, strict, ...]) | Validate the given object with string data against the Pydantic model. | + | `parse_file`(path, \*\[, content\_type, ...]) | | + | `parse_obj`(obj) | | + | `parse_raw`(b, \*\[, content\_type, encoding, ...]) | | + | `schema`(\[by\_alias, ref\_template]) | | + | `schema_json`(\*\[, by\_alias, ref\_template]) | | + | `update_forward_refs`(\*\*localns) | | + | `validate`(value) | | + + ## Attributes + + | | | + | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- | + | `model_computed_fields` | | + | [`model_config`](#qiskit_noise_learning.noise_learner.LearningOptions.model_config "qiskit_noise_learning.noise_learner.LearningOptions.model_config") | Configuration for the model, should be a dictionary conforming to \[ConfigDict]\[pydantic.config.ConfigDict]. | + | `model_extra` | Get extra fields set during validation. | + | `model_fields` | | + | `model_fields_set` | Returns the set of fields that have been explicitly set on this model instance. | + | [`num_randomizations`](#qiskit_noise_learning.noise_learner.LearningOptions.num_randomizations "qiskit_noise_learning.noise_learner.LearningOptions.num_randomizations") | The number of randomizations to use per learning circuit. | + | [`shots_per_randomizations`](#qiskit_noise_learning.noise_learner.LearningOptions.shots_per_randomizations "qiskit_noise_learning.noise_learner.LearningOptions.shots_per_randomizations") | The number of shots to use per randomization. | + | [`fragment_depths`](#qiskit_noise_learning.noise_learner.LearningOptions.fragment_depths "qiskit_noise_learning.noise_learner.LearningOptions.fragment_depths") | The fragment depths to use (number of repetitions of each path's repeatable fragment). | + | [`k_locality`](#qiskit_noise_learning.noise_learner.LearningOptions.k_locality "qiskit_noise_learning.noise_learner.LearningOptions.k_locality") | The locality of the terms to include in the noise model. | + | [`path_generator`](#qiskit_noise_learning.noise_learner.LearningOptions.path_generator "qiskit_noise_learning.noise_learner.LearningOptions.path_generator") | The path generator to use. | + | [`analyzer`](#qiskit_noise_learning.noise_learner.LearningOptions.analyzer "qiskit_noise_learning.noise_learner.LearningOptions.analyzer") | The analyzer to use. | + + ### num\_randomizations + + + Type: [`int`](https://docs.python.org/3/library/functions.html#int) + + The number of randomizations to use per learning circuit. + + + ### shots\_per\_randomizations + + + Type: [`int`](https://docs.python.org/3/library/functions.html#int) + + The number of shots to use per randomization. + + + ### fragment\_depths + + + Type: [`list`](https://docs.python.org/3/library/stdtypes.html#list)\[[`int`](https://docs.python.org/3/library/functions.html#int)] + + The fragment depths to use (number of repetitions of each path’s repeatable fragment). + + + ### model\_config + + + Default value: `{}` + + Configuration for the model, should be a dictionary conforming to \[ConfigDict]\[pydantic.config.ConfigDict]. + + + ### k\_locality + + + Type: [`int`](https://docs.python.org/3/library/functions.html#int) + + The locality of the terms to include in the noise model. + + + ### path\_generator + + + Type: [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\[`'even_depth'`] + + The path generator to use. + + By default, the generator produces even depth paths for each gate for which to learn the noise. + + + ### analyzer + + + Type: [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\[`'standard'`] + + The analyzer to use. + + By default, the analyzer pipeline first computes observables, then curve fits exponentials, and finally uses non-negative least squares to solve for model parameters. + + + diff --git a/docs/api/qiskit-noise-learning/generated/noise-learner-noise-learner-job.mdx b/docs/api/qiskit-noise-learning/generated/noise-learner-noise-learner-job.mdx new file mode 100644 index 000000000000..4d2b8330548b --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/noise-learner-noise-learner-job.mdx @@ -0,0 +1,59 @@ +--- +title: NoiseLearnerJob (latest version) +description: API reference for qiskit_noise_learning.noise_learner.NoiseLearnerJob in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.noise_learner.NoiseLearnerJob +--- + + + +# qiskit\_noise\_learning.noise\_learner.NoiseLearnerJob + + + Bases: [`object`](https://docs.python.org/3/library/functions.html#object) + + A noise learner job. + + This class is a wrapper around the job returned by the executor that ran the experiment, which also includes attributes to analyze the outcome of a noise learning experiment. + + **Parameters** + + * **runtime\_job** – The job returned by the executor the program was submitted to. This is a [`RuntimeJobV2`](/docs/api/qiskit-ibm-runtime/runtime-job-v2 "(in Qiskit Runtime IBM Client)") unless a different executor was supplied to [`NoiseLearner`](noise-learner-noise-learner "qiskit_noise_learning.noise_learner.NoiseLearner"). + * **data\_mapper** – The data mapper describing the experiment layout. + * **analysis\_stage** – The analysis stage to process the data. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | + | [`__init__`](#qiskit_noise_learning.noise_learner.NoiseLearnerJob.__init__ "qiskit_noise_learning.noise_learner.NoiseLearnerJob.__init__")(runtime\_job, data\_mapper, ...) | | + | [`result`](#qiskit_noise_learning.noise_learner.NoiseLearnerJob.result "qiskit_noise_learning.noise_learner.NoiseLearnerJob.result")(\*args, \*\*kwargs) | Compute the result of the noise learning job. | + + ## Attributes + + | | | + | --------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | + | [`runtime_job`](#qiskit_noise_learning.noise_learner.NoiseLearnerJob.runtime_job "qiskit_noise_learning.noise_learner.NoiseLearnerJob.runtime_job") | The job returned by the executor the program was submitted to. | + + ### runtime\_job + + + Type: [`ProgramJob`](noise-learner-program-job "qiskit_noise_learning.noise_learner.noise_learner_job.ProgramJob") + + The job returned by the executor the program was submitted to. + + + ### result + + + Compute the result of the noise learning job. + + This method forwards arguments to [`ProgramJob.result()`](noise-learner-program-job#result "qiskit_noise_learning.noise_learner.ProgramJob.result"). + + + diff --git a/docs/api/qiskit-noise-learning/generated/noise-learner-noise-learner-result.mdx b/docs/api/qiskit-noise-learning/generated/noise-learner-noise-learner-result.mdx new file mode 100644 index 000000000000..7589a58cdcd7 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/noise-learner-noise-learner-result.mdx @@ -0,0 +1,55 @@ +--- +title: NoiseLearnerResult (latest version) +description: API reference for qiskit_noise_learning.noise_learner.NoiseLearnerResult in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.noise_learner.NoiseLearnerResult +--- + + + +# qiskit\_noise\_learning.noise\_learner.NoiseLearnerResult + + + Bases: [`object`](https://docs.python.org/3/library/functions.html#object) + + Result of noise learning. + + Wraps a [`Fit`](analysis-fit "qiskit_noise_learning.analysis.Fit") container and provides conversion to [`PauliLindbladMap`](/docs/api/qiskit/qiskit.quantum_info.PauliLindbladMap) per gate. + + **Parameters** + + **fit** – The completed fit containing model data. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | + | [`__init__`](#qiskit_noise_learning.noise_learner.NoiseLearnerResult.__init__ "qiskit_noise_learning.noise_learner.NoiseLearnerResult.__init__")(fit) | | + | [`to_dict`](#qiskit_noise_learning.noise_learner.NoiseLearnerResult.to_dict "qiskit_noise_learning.noise_learner.NoiseLearnerResult.to_dict")() | Convert the result to a dictionary mapping gate names to Pauli Lindblad maps. | + + ## Attributes + + | | | + | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | + | [`fit`](#qiskit_noise_learning.noise_learner.NoiseLearnerResult.fit "qiskit_noise_learning.noise_learner.NoiseLearnerResult.fit") | The underlying fit container. | + + ### fit + + + Type: [`Fit`](analysis-fit "qiskit_noise_learning.analysis.fit.Fit") + + The underlying fit container. + + + ### to\_dict + + + Convert the result to a dictionary mapping gate names to Pauli Lindblad maps. + + + diff --git a/docs/api/qiskit-noise-learning/generated/noise-learner-noise-learner.mdx b/docs/api/qiskit-noise-learning/generated/noise-learner-noise-learner.mdx new file mode 100644 index 000000000000..b86db5b91bc7 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/noise-learner-noise-learner.mdx @@ -0,0 +1,80 @@ +--- +title: NoiseLearner (latest version) +description: API reference for qiskit_noise_learning.noise_learner.NoiseLearner in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.noise_learner.NoiseLearner +--- + + + +# qiskit\_noise\_learning.noise\_learner.NoiseLearner + + + Bases: [`object`](https://docs.python.org/3/library/functions.html#object) + + A noise learner. + + + The arguments `backend` and `executor` are redundant. This is a temporary measure to enable simulated execution with an [`AerExecutor`](aer-executor-aer-executor "qiskit_noise_learning.aer_executor.AerExecutor") instance, and is not a stable interface. + + + **Parameters** + + * **backend** – The backend supplying the compilation target: the gate set, coupling map and qubit count that generated circuits are built against. When `executor` is given, this need not be the device the programs actually run on. + * **options** – Learning options. If `None`, default options are used. + * **executor** – Where generated programs are submitted. If `None` (default), a [`Executor`](/docs/api/qiskit-ibm-runtime/executor "(in Qiskit Runtime IBM Client)") in `backend`’s execution mode is used, so that programs run on `backend` itself. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | + | [`__init__`](#qiskit_noise_learning.noise_learner.NoiseLearner.__init__ "qiskit_noise_learning.noise_learner.NoiseLearner.__init__")(backend\[, options, executor]) | | + | [`run`](#qiskit_noise_learning.noise_learner.NoiseLearner.run "qiskit_noise_learning.noise_learner.NoiseLearner.run")(instructions) | Submit a job to learn the noise of the given instructions. | + + ## Attributes + + | | | + | --------------------------------------------------------------------------------------------------------------------------------- | --------------------- | + | [`backend`](#qiskit_noise_learning.noise_learner.NoiseLearner.backend "qiskit_noise_learning.noise_learner.NoiseLearner.backend") | The backend. | + | [`options`](#qiskit_noise_learning.noise_learner.NoiseLearner.options "qiskit_noise_learning.noise_learner.NoiseLearner.options") | The learning options. | + + ### backend + + + Type: [`BackendV2`](/docs/api/qiskit/qiskit.providers.BackendV2) + + The backend. + + + ### options + + + Type: [`LearningOptions`](noise-learner-learning-options "qiskit_noise_learning.noise_learner.learning_options.LearningOptions") + + The learning options. + + + ### run + + + Submit a job to learn the noise of the given instructions. + + **Parameters** + + **instructions** – The instructions to learn the noise of. Each instruction should contain a [`BoxOp`](/docs/api/qiskit/qiskit.circuit.BoxOp) operation. + + **Returns** + + The submitted job. The result of the job is a [`NoiseLearnerResult`](noise-learner-noise-learner-result "qiskit_noise_learning.noise_learner.NoiseLearnerResult"). + + **Raises** + + [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – If any instruction does not contain a `BoxOp`. + + + diff --git a/docs/api/qiskit-noise-learning/generated/noise-learner-program-executor.mdx b/docs/api/qiskit-noise-learning/generated/noise-learner-program-executor.mdx new file mode 100644 index 000000000000..233ef6e59b36 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/noise-learner-program-executor.mdx @@ -0,0 +1,49 @@ +--- +title: ProgramExecutor (latest version) +description: API reference for qiskit_noise_learning.noise_learner.ProgramExecutor in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.noise_learner.ProgramExecutor +--- + + + +# qiskit\_noise\_learning.noise\_learner.ProgramExecutor + + + Bases: [`Protocol`](https://docs.python.org/3/library/typing.html#typing.Protocol) + + The executor role that [`NoiseLearner`](noise-learner-noise-learner "qiskit_noise_learning.noise_learner.NoiseLearner") submits programs to. + + Only [`run()`](#qiskit_noise_learning.noise_learner.ProgramExecutor.run "qiskit_noise_learning.noise_learner.ProgramExecutor.run") is required, so both [`Executor`](/docs/api/qiskit-ibm-runtime/executor "(in Qiskit Runtime IBM Client)") and the Aer executor qualify without either declaring conformance. + + + This protocol, and the `executor` argument of [`NoiseLearner`](noise-learner-noise-learner "qiskit_noise_learning.noise_learner.NoiseLearner") that consumes it, are provisional. They exist so that a learning experiment can be run against a locally simulated executor, and this setup is expected to eventually change. + + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | + | [`__init__`](#qiskit_noise_learning.noise_learner.ProgramExecutor.__init__ "qiskit_noise_learning.noise_learner.ProgramExecutor.__init__")(\*args, \*\*kwargs) | | + | [`run`](#qiskit_noise_learning.noise_learner.ProgramExecutor.run "qiskit_noise_learning.noise_learner.ProgramExecutor.run")(program) | Submit a program for execution. | + + ### run + + + Submit a program for execution. + + **Parameters** + + **program** – The quantum program to submit. + + **Returns** + + A job carrying the program’s result. + + + diff --git a/docs/api/qiskit-noise-learning/generated/noise-learner-program-job.mdx b/docs/api/qiskit-noise-learning/generated/noise-learner-program-job.mdx new file mode 100644 index 000000000000..3be5e9dcdb11 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/noise-learner-program-job.mdx @@ -0,0 +1,41 @@ +--- +title: ProgramJob (latest version) +description: API reference for qiskit_noise_learning.noise_learner.ProgramJob in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.noise_learner.ProgramJob +--- + + + +# qiskit\_noise\_learning.noise\_learner.ProgramJob + + + Bases: [`Protocol`](https://docs.python.org/3/library/typing.html#typing.Protocol) + + The job role that [`NoiseLearnerJob`](noise-learner-noise-learner-job "qiskit_noise_learning.noise_learner.NoiseLearnerJob") wraps. + + Only [`result()`](#qiskit_noise_learning.noise_learner.ProgramJob.result "qiskit_noise_learning.noise_learner.ProgramJob.result") is required, so both [`RuntimeJobV2`](/docs/api/qiskit-ibm-runtime/runtime-job-v2 "(in Qiskit Runtime IBM Client)") and the job type returned by the Aer executor qualify without either declaring conformance. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | + | [`__init__`](#qiskit_noise_learning.noise_learner.ProgramJob.__init__ "qiskit_noise_learning.noise_learner.ProgramJob.__init__")(\*args, \*\*kwargs) | | + | [`result`](#qiskit_noise_learning.noise_learner.ProgramJob.result "qiskit_noise_learning.noise_learner.ProgramJob.result")(\*args, \*\*kwargs) | Return the result of the executed program. | + + ### result + + + Return the result of the executed program. + + **Returns** + + The program’s [`QuantumProgramResult`](/docs/api/qiskit-ibm-runtime/results-quantum-program-result "(in Qiskit Runtime IBM Client)"). + + + diff --git a/docs/api/qiskit-noise-learning/generated/sequences-apply-gate.mdx b/docs/api/qiskit-noise-learning/generated/sequences-apply-gate.mdx new file mode 100644 index 000000000000..97c4cee8fe4f --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/sequences-apply-gate.mdx @@ -0,0 +1,105 @@ +--- +title: ApplyGate (latest version) +description: API reference for qiskit_noise_learning.sequences.ApplyGate in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.sequences.ApplyGate +--- + + + +# qiskit\_noise\_learning.sequences.ApplyGate + + + Bases: `Instruction` + + An instruction that applies a fixed gate. + + **Parameters** + + **gate\_name** – The name of the gate to apply. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | + | [`__init__`](#qiskit_noise_learning.sequences.ApplyGate.__init__ "qiskit_noise_learning.sequences.ApplyGate.__init__")(gate\_name) | | + | [`complete`](#qiskit_noise_learning.sequences.ApplyGate.complete "qiskit_noise_learning.sequences.ApplyGate.complete")() | Returns self. | + | [`is_mergeable_with`](#qiskit_noise_learning.sequences.ApplyGate.is_mergeable_with "qiskit_noise_learning.sequences.ApplyGate.is_mergeable_with")(other) | Whether or not this apply gate is mergeable with another one. | + | [`merge`](#qiskit_noise_learning.sequences.ApplyGate.merge "qiskit_noise_learning.sequences.ApplyGate.merge")(other) | Merge self and other into a single instruction. | + + ## Attributes + + | | | + | ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | + | [`gate_name`](#qiskit_noise_learning.sequences.ApplyGate.gate_name "qiskit_noise_learning.sequences.ApplyGate.gate_name") | The name of the gate to apply. | + | [`is_complete`](#qiskit_noise_learning.sequences.ApplyGate.is_complete "qiskit_noise_learning.sequences.ApplyGate.is_complete") | Apply gate instructions are always complete. | + | [`structure_token`](#qiskit_noise_learning.sequences.ApplyGate.structure_token "qiskit_noise_learning.sequences.ApplyGate.structure_token") | A hashable summary of this instruction that constrains mergeability. | + + ### gate\_name + + + Type: [`str`](https://docs.python.org/3/library/stdtypes.html#str) + + The name of the gate to apply. + + + ### is\_complete + + + Type: [`bool`](https://docs.python.org/3/library/functions.html#bool) + + Apply gate instructions are always complete. + + + ### structure\_token + + + Type: [`Hashable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Hashable) + + A hashable summary of this instruction that constrains mergeability. + + This token serves as a cheap check of non-mergeability: instructions with unequal structure tokens are never mergeable. The token must therefore distinguish instruction types from one another. + + + ### complete + + + Returns self. + + + ### is\_mergeable\_with + + + Whether or not this apply gate is mergeable with another one. + + Mergeability of two [`ApplyGate`](#qiskit_noise_learning.sequences.ApplyGate "qiskit_noise_learning.sequences.ApplyGate") instructions is based on equality of the gate names. + + **Parameters** + + **other** – The other instruction to check mergeablitity with. + + **Returns** + + Whether this instruction is mergeable with the other. + + + ### merge + + + Merge self and other into a single instruction. + + **Parameters** + + **other** – The other instruction to merge with. + + **Returns** + + Some instruction (possibly the same instance) that simultaneously implements the action of this instruction and the other instruction. + + + diff --git a/docs/api/qiskit-noise-learning/generated/sequences-fidelity-index.mdx b/docs/api/qiskit-noise-learning/generated/sequences-fidelity-index.mdx new file mode 100644 index 000000000000..74facca3d006 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/sequences-fidelity-index.mdx @@ -0,0 +1,178 @@ +--- +title: Qiskit noise learning API documentation (latest version) +description: Index of all the modules in the latest version of qiskit-noise-learning. +--- + + + +# qiskit\_noise\_learning.sequences.FidelityIndex + + + Bases: [`object`](https://docs.python.org/3/library/functions.html#object) + + Index data for a fidelity in a Pauli-MCM-reset gate set. + + Let $K$ be the number of qubits, $[K] = \{0, ..., K-1\}$, $M\subset [K]$ denote the measured qubits, and $R \subset [K]$ the reset qubits for the gate. For a given gate, each fidelity is specified by: + + * A Pauli on the unmeasured and unreset qubits $Q \in P^{[K]\setminus (M \cup R)}$, + * A $Z$-type operator $Z^x$ on the measured qubits, $x \in Z_2^M$, and + * A $Z$-type operator $Z^y$ on the measured and reset qubits, $y \in Z_2^{M \cup R}$. + + This list constitutes the “index data” for a generalized fidelity for a given gate, in the sense that there is a bijection between all generalized fidelities and the above set of all objects satisfying the above description. See Equation [(3)](guides/formalism#equation-clifford-mcm-reset-form) of the [mathematical formalism](guides/formalism) for the decomposition in which these appear. + + The exponents $x$ and $y$ are stored as the sets of qubit indices on which they are non-zero, namely [`in_z_idxs`](#qiskit_noise_learning.sequences.FidelityIndex.in_z_idxs "qiskit_noise_learning.sequences.FidelityIndex.in_z_idxs") and [`out_z_idxs`](#qiskit_noise_learning.sequences.FidelityIndex.out_z_idxs "qiskit_noise_learning.sequences.FidelityIndex.out_z_idxs") – equivalently, the qubits on which $Z^x$ and $Z^y$ act non-trivially. + + The constructor [`FidelityIndex.from_gate()`](#qiskit_noise_learning.sequences.FidelityIndex.from_gate "qiskit_noise_learning.sequences.FidelityIndex.from_gate") builds a [`FidelityIndex`](#qiskit_noise_learning.sequences.FidelityIndex "qiskit_noise_learning.sequences.FidelityIndex") from a [`ModelGate`](gate-sets-model-gate "qiskit_noise_learning.gate_sets.ModelGate") and the above unique index data. Alternatively, [`FidelityIndex.from_transition()`](#qiskit_noise_learning.sequences.FidelityIndex.from_transition "qiskit_noise_learning.sequences.FidelityIndex.from_transition") can be used to build an instance from the Pauli transition implied by the index data. The [`FidelityIndex.__init__()`](#qiskit_noise_learning.sequences.FidelityIndex.__init__ "qiskit_noise_learning.sequences.FidelityIndex.__init__") is viewed as a “low-level” constructor which takes all stored properties without validation. + + **Parameters** + + * **gate\_name** – The name of the gate. + * **pauli** – A Pauli operator with support on unmeasured and unreset qubits. Note that `pauli.num_qubits` controls the size of the operators returned by `self.transition`. + * **in\_z\_idxs** – The qubit indices on which $x$ is non-zero. + * **out\_z\_idxs** – The qubit indices on which $y$ is non-zero. + * **input\_pauli** – The input Pauli of the transition. + * **output\_pauli** – The output Pauli of the transition. + * **sign\_flip** – Whether the transition involves a sign flip. + * **meas\_idxs** – The measurement qubit indices for the gate. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | + | [`__init__`](#qiskit_noise_learning.sequences.FidelityIndex.__init__ "qiskit_noise_learning.sequences.FidelityIndex.__init__")(gate\_name, pauli, in\_z\_idxs, ...) | | + | [`from_gate`](#qiskit_noise_learning.sequences.FidelityIndex.from_gate "qiskit_noise_learning.sequences.FidelityIndex.from_gate")(gate, pauli\[, in\_z\_idxs, out\_z\_idxs]) | Construct a fidelity index from a gate and unique index data. | + | [`from_transition`](#qiskit_noise_learning.sequences.FidelityIndex.from_transition "qiskit_noise_learning.sequences.FidelityIndex.from_transition")(gate, in\_pauli, out\_pauli) | Construct a fidelity index from a Pauli transition on the quantum registers. | + | [`is_valid_for_gate`](#qiskit_noise_learning.sequences.FidelityIndex.is_valid_for_gate "qiskit_noise_learning.sequences.FidelityIndex.is_valid_for_gate")(gate, pauli\[, in\_z\_idxs, ...]) | Whether the given index data forms a valid fidelity index for the gate. | + + ## Attributes + + | | | + | --------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | + | [`gate_name`](#qiskit_noise_learning.sequences.FidelityIndex.gate_name "qiskit_noise_learning.sequences.FidelityIndex.gate_name") | The name of the gate. | + | [`in_z_idxs`](#qiskit_noise_learning.sequences.FidelityIndex.in_z_idxs "qiskit_noise_learning.sequences.FidelityIndex.in_z_idxs") | The measured qubits carrying a $Z$ on the instrument input. | + | [`mask`](#qiskit_noise_learning.sequences.FidelityIndex.mask "qiskit_noise_learning.sequences.FidelityIndex.mask") | The mask for marginalizing measurement outcomes. | + | [`observable_idxs`](#qiskit_noise_learning.sequences.FidelityIndex.observable_idxs "qiskit_noise_learning.sequences.FidelityIndex.observable_idxs") | Qubit indices of the associated $Z$ observable in ascending order. | + | [`out_z_idxs`](#qiskit_noise_learning.sequences.FidelityIndex.out_z_idxs "qiskit_noise_learning.sequences.FidelityIndex.out_z_idxs") | The measured and reset qubits carrying a $Z$ on the instrument output. | + | [`pauli`](#qiskit_noise_learning.sequences.FidelityIndex.pauli "qiskit_noise_learning.sequences.FidelityIndex.pauli") | The Pauli operator on the Clifford portion of the model gate. | + | [`sign_flip`](#qiskit_noise_learning.sequences.FidelityIndex.sign_flip "qiskit_noise_learning.sequences.FidelityIndex.sign_flip") | Whether the transition associated with this fidelity involves a sign flip. | + | [`transition`](#qiskit_noise_learning.sequences.FidelityIndex.transition "qiskit_noise_learning.sequences.FidelityIndex.transition") | The phaseless Pauli operator transition associated with this fidelity index. | + + ### from\_gate + + + Construct a fidelity index from a gate and unique index data. + + **Parameters** + + * **gate** – The model gate. + * **pauli** – A Pauli operator with support on unmeasured and unreset qubits. + * **in\_z\_idxs** – The subset of measurement qubit indices carrying a $Z$ on the instrument input. + * **out\_z\_idxs** – The subset of the union of measurement and reset qubit indices carrying a $Z$ on the instrument output. + + **Raises** + + [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – If the provided data is inconsistent with the gate. + + + ### is\_valid\_for\_gate + + + Whether the given index data forms a valid fidelity index for the gate. + + This performs the same (side-effect-free) consistency checks as [`from_gate()`](#qiskit_noise_learning.sequences.FidelityIndex.from_gate "qiskit_noise_learning.sequences.FidelityIndex.from_gate"), without constructing the index or computing its transition. + + **Parameters** + + * **gate** – The model gate. + * **pauli** – A Pauli operator with support on unmeasured and unreset qubits. + * **in\_z\_idxs** – The subset of measurement qubit indices carrying a $Z$ on the instrument input. + * **out\_z\_idxs** – The subset of the union of measurement and reset qubit indices carrying a $Z$ on the instrument output. + + + ### from\_transition + + + Construct a fidelity index from a Pauli transition on the quantum registers. + + This constructor deduces the Pauli and $Z$ index sets of a [`FidelityIndex`](#qiskit_noise_learning.sequences.FidelityIndex "qiskit_noise_learning.sequences.FidelityIndex") from the given Pauli transition. + + **Parameters** + + * **gate** – The model gate. + * **in\_pauli** – The input Pauli on the quantum register. + * **out\_pauli** – The output Pauli on the quantum register. + + **Raises** + + [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – If the pair of Pauli operators do not imply a valid [`FidelityIndex`](#qiskit_noise_learning.sequences.FidelityIndex "qiskit_noise_learning.sequences.FidelityIndex"). + + + ### gate\_name + + + Type: [`str`](https://docs.python.org/3/library/stdtypes.html#str) + + The name of the gate. + + + ### pauli + + + Type: [`QubitSparsePauli`](/docs/api/qiskit/qiskit.quantum_info.QubitSparsePauli) + + The Pauli operator on the Clifford portion of the model gate. + + + ### in\_z\_idxs + + + Type: [`frozenset`](https://docs.python.org/3/library/stdtypes.html#frozenset)\[[`int`](https://docs.python.org/3/library/functions.html#int)] + + The measured qubits carrying a $Z$ on the instrument input. + + + ### out\_z\_idxs + + + Type: [`frozenset`](https://docs.python.org/3/library/stdtypes.html#frozenset)\[[`int`](https://docs.python.org/3/library/functions.html#int)] + + The measured and reset qubits carrying a $Z$ on the instrument output. + + + ### sign\_flip + + + Type: [`bool`](https://docs.python.org/3/library/functions.html#bool) + + Whether the transition associated with this fidelity involves a sign flip. + + + ### transition + + + Type: [`tuple`](https://docs.python.org/3/library/stdtypes.html#tuple)\[[`QubitSparsePauli`](/docs/api/qiskit/qiskit.quantum_info.QubitSparsePauli), [`QubitSparsePauli`](/docs/api/qiskit/qiskit.quantum_info.QubitSparsePauli)] + + The phaseless Pauli operator transition associated with this fidelity index. + + + ### mask + + + Type: [`ndarray`](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray)\[[`bool`](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.bool)] + + The mask for marginalizing measurement outcomes. + + + ### observable\_idxs + + + Type: [`list`](https://docs.python.org/3/library/stdtypes.html#list)\[[`int`](https://docs.python.org/3/library/functions.html#int)] + + Qubit indices of the associated $Z$ observable in ascending order. + + + diff --git a/docs/api/qiskit-noise-learning/generated/sequences-group-mergeable-instruction-sequences.mdx b/docs/api/qiskit-noise-learning/generated/sequences-group-mergeable-instruction-sequences.mdx new file mode 100644 index 000000000000..12b852bd07d3 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/sequences-group-mergeable-instruction-sequences.mdx @@ -0,0 +1,47 @@ +--- +title: group_mergeable_instruction_sequences (latest version) +description: API reference for qiskit_noise_learning.sequences.group_mergeable_instruction_sequences in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit_noise_learning.sequences.group_mergeable_instruction_sequences +--- + + + +# qiskit\_noise\_learning.sequences.group\_mergeable\_instruction\_sequences + + + Group the positions of instruction sequences that can be merged with each other. + + The returned groups partition the positions of `sequences`: every position appears in exactly one group, and the sequences within a group can all be merged together, in any order, into a single sequence via [`merge()`](sequences-instruction-sequence#merge "qiskit_noise_learning.sequences.InstructionSequence.merge"). + + In terms of strategy, the list of sequences is first partitioned into sets according to [`structure_key`](sequences-instruction-sequence#structure_key "qiskit_noise_learning.sequences.InstructionSequence.structure_key"). Each set is then further partitioned into the returned groups via a family of greedy algorithms. A single member of this family is specified by a grouping strategy, which pairs an order to visit the instruction sequences in with a strategy for choosing which group to merge each one into. Every grouping strategy in `grouping_strategies` is applied to every set, and the fewest groups found for a set are the ones returned for it, ties going to the earlier strategy. Because the sets are treated independently, supplying an additional grouping strategy can only decrease the total number of groups returned. + + A sequence is called more constrained if it specifies more Pauli mappings. The first entry of a grouping strategy, the order to visit the instruction sequences in, is one of: + + * `"most-constrained-first"`: ordered from most-constrained to least-constrained. + * `"least-constrained-first"`: ordered from least-constrained to most-constrained. + * `"qubitwise-lexicographic"`: ordered so that sequences agreeing on the Pauli mappings they specify, qubit by qubit from the first onwards, are considered consecutively. Which of two differing sequences comes first follows a fixed but arbitrary convention, making this one of many possible orderings that place sequences specifying similar mappings near each other. + * `"input"`: the order in which they were given. + + The second entry selects which of the groups a sequence can join it is merged into: + + * `"first"`: the group created earliest. + * `"most-constrained"`: the group that already admits the fewest complete permutations, which leaves the more flexible groups intact for later sequences. + * `"least-impacted"`: the group whose admissible complete permutations the instruction sequence rules out the fewest of. + + **Parameters** + + * **sequences** – The instruction sequences to group. + * **grouping\_strategies** – The grouping strategies to take the fewest groups found by any of. If `None`, an empirically determined default set of strategies is used. + + **Returns** + + The groups of positions of mergeable sequences. + + **Raises** + + * [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError) – If any sequence contains an instruction that is neither a gate application nor a partial Pauli permutation. + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – If `grouping_strategies` is empty, or if any of its entries is not a pairing of a documented instruction sequence order with a documented merging strategy. + + diff --git a/docs/api/qiskit-noise-learning/generated/sequences-instruction-sequence.mdx b/docs/api/qiskit-noise-learning/generated/sequences-instruction-sequence.mdx new file mode 100644 index 000000000000..21fdb460bc85 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/sequences-instruction-sequence.mdx @@ -0,0 +1,134 @@ +--- +title: InstructionSequence (latest version) +description: API reference for qiskit_noise_learning.sequences.InstructionSequence in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.sequences.InstructionSequence +--- + + + +# qiskit\_noise\_learning.sequences.InstructionSequence + + + Bases: `BaseSequence`\[`Instruction`] + + A sequence of instructions. + + **Parameters** + + * **start\_fragment** – The start of the sequence. + * **repeatable\_fragment** – The repeatable middle of the sequence. + * **end\_fragment** – The end of the sequence. + * **fragment\_depth** – The number of repetitions of the repeatable fragment. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | + | [`__init__`](#qiskit_noise_learning.sequences.InstructionSequence.__init__ "qiskit_noise_learning.sequences.InstructionSequence.__init__")(start\_fragment, ...\[, fragment\_depth]) | | + | `bind_at`(fragment\_depth) | Return a new instance with the same fragments bound to the fragment depth. | + | [`complete`](#qiskit_noise_learning.sequences.InstructionSequence.complete "qiskit_noise_learning.sequences.InstructionSequence.complete")() | Return a new instance whose data is the same as `self` except that all contained instructions are completed. | + | [`is_mergeable_with`](#qiskit_noise_learning.sequences.InstructionSequence.is_mergeable_with "qiskit_noise_learning.sequences.InstructionSequence.is_mergeable_with")(other) | Check if this instruction sequence is mergeable with another instruction sequence. | + | [`merge`](#qiskit_noise_learning.sequences.InstructionSequence.merge "qiskit_noise_learning.sequences.InstructionSequence.merge")(other) | Merge this instruction sequence with another instruction sequence. | + | `unbind`() | Return a new instance with the same fragments but fragment depth set to `None`. | + + ## Attributes + + | | | + | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | + | `end_fragment` | The ending fragment. | + | `fragment_depth` | The number of repetitions of the repeatable fragment. | + | [`gate_key`](#qiskit_noise_learning.sequences.InstructionSequence.gate_key "qiskit_noise_learning.sequences.InstructionSequence.gate_key") | A hashable summary of the gate applications in this instruction sequence. | + | [`is_complete`](#qiskit_noise_learning.sequences.InstructionSequence.is_complete "qiskit_noise_learning.sequences.InstructionSequence.is_complete") | Whether all contained instructions are completely specified. | + | `is_unbound` | Whether the sequence is unbound. | + | `repeatable_fragment` | The repeatable fragment. | + | `start_fragment` | The starting fragment. | + | [`structure_key`](#qiskit_noise_learning.sequences.InstructionSequence.structure_key "qiskit_noise_learning.sequences.InstructionSequence.structure_key") | A hashable summary of the instruction structure of this sequence. | + + ### is\_complete + + + Type: [`bool`](https://docs.python.org/3/library/functions.html#bool) + + Whether all contained instructions are completely specified. + + + ### complete + + + Return a new instance whose data is the same as `self` except that all contained instructions are completed. + + **Returns** + + A new [`InstructionSequence`](#qiskit_noise_learning.sequences.InstructionSequence "qiskit_noise_learning.sequences.InstructionSequence") instance. + + + ### gate\_key + + + Type: [`Hashable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Hashable) + + A hashable summary of the gate applications in this instruction sequence. + + Two instruction sequences have equal gate keys exactly when they have the same fragment depth and each of their fragments applies the same gates in the same order, however else they differ; every instruction that is not a gate application is ignored. The value itself is opaque, with only equality and hashability guaranteed. + + + ### structure\_key + + + Type: [`Hashable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Hashable) + + A hashable summary of the instruction structure of this sequence. + + This key comes with the following guarantees: + + * If two instruction sequences have different keys, they are not mergeable. + * If two instruction sequences have the same key, they have the same fragment depth, and their fragments contain the same sequence of instruction types on the same qubits. + + **Raises** + + [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError) – If this instruction sequence contains an object that is not an instruction. + + + ### is\_mergeable\_with + + + Check if this instruction sequence is mergeable with another instruction sequence. + + Two instruction sequences are mergeable if they have compatible fragment depths and their fragments are element-wise mergeable. + + **Parameters** + + **other** – The other [`InstructionSequence`](#qiskit_noise_learning.sequences.InstructionSequence "qiskit_noise_learning.sequences.InstructionSequence"). + + **Returns** + + Whether this instance is mergeable with another. + + + ### merge + + + Merge this instruction sequence with another instruction sequence. + + Assuming this instance is mergeable with `other`, the returned merged sequence is constructed by merging each corresponding fragment element-wise. + + **Parameters** + + **other** – The instruction sequence to merge this with. + + **Returns** + + The merged sequence of self and other. + + **Raises** + + [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – If the sequences are not mergeable. + + + diff --git a/docs/api/qiskit-noise-learning/generated/sequences-log-path-map.mdx b/docs/api/qiskit-noise-learning/generated/sequences-log-path-map.mdx new file mode 100644 index 000000000000..a16e991ff580 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/sequences-log-path-map.mdx @@ -0,0 +1,60 @@ +--- +title: LogPathMap (latest version) +description: API reference for qiskit_noise_learning.sequences.LogPathMap in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.sequences.LogPathMap +--- + + + +# qiskit\_noise\_learning.sequences.LogPathMap + + + Bases: [`LinearMap`](math-linear-map "qiskit_noise_learning.math.linear_map.LinearMap")\[[`FidelityIndex`](sequences-fidelity-index "qiskit_noise_learning.sequences.fidelity_index.FidelityIndex"), [`Path`](sequences-path "qiskit_noise_learning.sequences.path.Path")] + + The linear map from a space of log fidelities to its associated log path space. + + This map is purely combinatorial: the row of a path is the fragment-depth-weighted multiplicity of each fidelity index appearing in the path. It does not depend on any noise model, only on the [`Path`](sequences-path "qiskit_noise_learning.sequences.Path") structure and the fidelity indices’ membership in the input space. + + **Parameters** + + **fidelity\_space** – The space of log fidelities. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ----------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | + | [`__init__`](#qiskit_noise_learning.sequences.LogPathMap.__init__ "qiskit_noise_learning.sequences.LogPathMap.__init__")(fidelity\_space) | | + | `compose`(outer) | Post-compose: self maps I->O, outer maps O->C, result maps I->C. | + | `left_multiply`(matrix) | Multiply on the left by an explicit matrix. | + | `pre_compose`(inner) | Pre-compose: inner maps A->I, self maps I->O, result maps A->O. | + | `projected_output`(output\_indices, vector) | Compute a projection of the map applied to a vector. | + | [`rows`](#qiskit_noise_learning.sequences.LogPathMap.rows "qiskit_noise_learning.sequences.LogPathMap.rows")(output\_indices) | Construct the sub-matrix whose rows are the given output indices. | + + ## Attributes + + | | | + | -------------- | ----------------- | + | `input_space` | The input space. | + | `output_space` | The output space. | + + ### rows + + + Construct the sub-matrix whose rows are the given output indices. + + **Parameters** + + **output\_indices** – The labels for the desired rows of the matrix. + + **Returns** + + [`IndexedMatrix`](math-indexed-matrix "qiskit_noise_learning.math.IndexedMatrix") + + + diff --git a/docs/api/qiskit-noise-learning/generated/sequences-log-path-space.mdx b/docs/api/qiskit-noise-learning/generated/sequences-log-path-space.mdx new file mode 100644 index 000000000000..4872e1135746 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/sequences-log-path-space.mdx @@ -0,0 +1,66 @@ +--- +title: LogPathSpace (latest version) +description: API reference for qiskit_noise_learning.sequences.LogPathSpace in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.sequences.LogPathSpace +--- + + + +# qiskit\_noise\_learning.sequences.LogPathSpace + + + Bases: [`IndexedSpace`](math-indexed-space "qiskit_noise_learning.math.indexed_space.IndexedSpace")\[[`Path`](sequences-path "qiskit_noise_learning.sequences.path.Path")] + + The (infinite-dimensional) space of log path-fidelities. + + For a [`Path`](sequences-path "qiskit_noise_learning.sequences.Path"), the “path-fidelity” is: + + * If the path is unbound, the product of the fidelities in the repeatable fragment. + * If the path is bound, the product of all fidelities in the path (counting multiplicities). + + This corresponds to the sign-corrected observable of an experiment traversing the path. + + The log path space represents the vector space of such log path-fidelities, indexed by the paths themselves. It is defined relative to a space of log fidelities: a path is a member if all of the fidelity indices in its fragments are members of that fidelity space. + + **Parameters** + + **fidelity\_space** – The space of log fidelities whose fidelity indices the paths are built from. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | --------------------------------------------------------------------------------------------------------------------------------------------- | - | + | [`__init__`](#qiskit_noise_learning.sequences.LogPathSpace.__init__ "qiskit_noise_learning.sequences.LogPathSpace.__init__")(fidelity\_space) | | + + ## Attributes + + | | | + | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | + | [`dim`](#qiskit_noise_learning.sequences.LogPathSpace.dim "qiskit_noise_learning.sequences.LogPathSpace.dim") | The dimension (cardinality) of the space. | + | [`fidelity_space`](#qiskit_noise_learning.sequences.LogPathSpace.fidelity_space "qiskit_noise_learning.sequences.LogPathSpace.fidelity_space") | The space of log fidelities whose fidelity indices the paths are built from. | + + ### fidelity\_space + + + Type: [`IndexedSpace`](math-indexed-space "qiskit_noise_learning.math.indexed_space.IndexedSpace")\[[`FidelityIndex`](sequences-fidelity-index "qiskit_noise_learning.sequences.fidelity_index.FidelityIndex")] + + The space of log fidelities whose fidelity indices the paths are built from. + + + ### dim + + + Type: [`int`](https://docs.python.org/3/library/functions.html#int) | [`float`](https://docs.python.org/3/library/functions.html#float) + + The dimension (cardinality) of the space. + + May be `math.inf` for infinite-dimensional spaces. + + + diff --git a/docs/api/qiskit-noise-learning/generated/sequences-partial-pauli-permutation.mdx b/docs/api/qiskit-noise-learning/generated/sequences-partial-pauli-permutation.mdx new file mode 100644 index 000000000000..eee8a4c0f033 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/sequences-partial-pauli-permutation.mdx @@ -0,0 +1,264 @@ +--- +title: PartialPauliPermutation (latest version) +description: API reference for qiskit_noise_learning.sequences.PartialPauliPermutation in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.sequences.PartialPauliPermutation +--- + + + +# qiskit\_noise\_learning.sequences.PartialPauliPermutation + + + Bases: `Instruction` + + Partially-specified permutations of the single-qubit phaseless Paulis on `n` qubits. + + A [`PartialPauliPermutation`](#qiskit_noise_learning.sequences.PartialPauliPermutation "qiskit_noise_learning.sequences.PartialPauliPermutation") represents a partial-specification of a layer of single qubit Cliffords for situations where the specific phases of the Pauli group need not be constrained. The partial nature of the specification is to enable progressively building such layers. Once a partial permutation is “complete” in the sense that is a full specification of a permutation, as indicated by the `bool` property [`PartialPauliPermutation.is_complete`](#qiskit_noise_learning.sequences.PartialPauliPermutation.is_complete "qiskit_noise_learning.sequences.PartialPauliPermutation.is_complete"), a default Clifford implementing the permutation is assigned to each qubit according to the ordering in `COMPLETE_TO_C1_TABLEAU`. + + Two partial permutations on a qubit are mergeable (see [`is_mergeable_with()`](#qiskit_noise_learning.sequences.PartialPauliPermutation.is_mergeable_with "qiskit_noise_learning.sequences.PartialPauliPermutation.is_mergeable_with") and [`merge()`](#qiskit_noise_learning.sequences.PartialPauliPermutation.merge "qiskit_noise_learning.sequences.PartialPauliPermutation.merge")) if there exists a single-qubit Clifford that implements both of their permutations, which without loss of generality is the statement that one doesn’t map a Pauli to a different Pauli than the other. + + The main data representation of the class is a list of integers, where each integer indexes a particular single-qubit partial Pauli permutation given in `partial_permutation_sets()`, which provides a fixed ordering. + + However, a human-readable `set`-based representation can also be used for construction via the [`PartialPauliPermutation.from_sets()`](#qiskit_noise_learning.sequences.PartialPauliPermutation.from_sets "qiskit_noise_learning.sequences.PartialPauliPermutation.from_sets") class method, or can be retrieved from an instance via the [`PartialPauliPermutation.to_sets()`](#qiskit_noise_learning.sequences.PartialPauliPermutation.to_sets "qiskit_noise_learning.sequences.PartialPauliPermutation.to_sets") method. For a single qubit, the partial permutation is specified as a `set` whose entries are `tuple`s of the form `(p0, p1)`, where `p0` and `p1` are strings drawn from `["Z", "X", "Y"]`. This `tuple` indicates that `p0` is mapped by the permutation to `p1`. + + **Parameters** + + **partial\_permutation\_indices** – A numpy array of index-specified partial permutations. The number of qubits is determined from the length. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | + | [`__init__`](#qiskit_noise_learning.sequences.PartialPauliPermutation.__init__ "qiskit_noise_learning.sequences.PartialPauliPermutation.__init__")(partial\_permutation\_indices) | | + | [`complete`](#qiskit_noise_learning.sequences.PartialPauliPermutation.complete "qiskit_noise_learning.sequences.PartialPauliPermutation.complete")() | Return a new partial Permutation that is complete and consistent with self. | + | [`compose`](#qiskit_noise_learning.sequences.PartialPauliPermutation.compose "qiskit_noise_learning.sequences.PartialPauliPermutation.compose")(other) | Compose with another partial permutation. | + | [`empty`](#qiskit_noise_learning.sequences.PartialPauliPermutation.empty "qiskit_noise_learning.sequences.PartialPauliPermutation.empty")(num\_qubits) | Generate the completely unspecified instance on `num_qubits`. | + | [`from_qubit_sparse_pauli_lists`](#qiskit_noise_learning.sequences.PartialPauliPermutation.from_qubit_sparse_pauli_lists "qiskit_noise_learning.sequences.PartialPauliPermutation.from_qubit_sparse_pauli_lists")(in\_paulis, ...) | Construct a `PartialPauliPermutation` that maps `in_paulis` to `out_paulis`. | + | [`from_qubit_sparse_paulis`](#qiskit_noise_learning.sequences.PartialPauliPermutation.from_qubit_sparse_paulis "qiskit_noise_learning.sequences.PartialPauliPermutation.from_qubit_sparse_paulis")(in\_pauli, out\_pauli) | Construct a `PartialPauliPermutation` that maps `in_pauli` to `out_pauli`. | + | [`from_sets`](#qiskit_noise_learning.sequences.PartialPauliPermutation.from_sets "qiskit_noise_learning.sequences.PartialPauliPermutation.from_sets")(sets) | Construct from a list of sets. | + | [`is_mergeable_with`](#qiskit_noise_learning.sequences.PartialPauliPermutation.is_mergeable_with "qiskit_noise_learning.sequences.PartialPauliPermutation.is_mergeable_with")(other) | Whether or not this instruction is mergeable with another one. | + | [`merge`](#qiskit_noise_learning.sequences.PartialPauliPermutation.merge "qiskit_noise_learning.sequences.PartialPauliPermutation.merge")(other) | Merge self and other into a single instruction. | + | [`propagate`](#qiskit_noise_learning.sequences.PartialPauliPermutation.propagate "qiskit_noise_learning.sequences.PartialPauliPermutation.propagate")(...) | Given a Pauli, propagate it through the Clifford implied by this permutation. | + | [`to_sets`](#qiskit_noise_learning.sequences.PartialPauliPermutation.to_sets "qiskit_noise_learning.sequences.PartialPauliPermutation.to_sets")() | Return the set representation. | + + ## Attributes + + | | | + | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | + | [`inverse`](#qiskit_noise_learning.sequences.PartialPauliPermutation.inverse "qiskit_noise_learning.sequences.PartialPauliPermutation.inverse") | Return the inversion of this partial permutation. | + | [`is_complete`](#qiskit_noise_learning.sequences.PartialPauliPermutation.is_complete "qiskit_noise_learning.sequences.PartialPauliPermutation.is_complete") | Whether self represents a complete specification of single-qubit Pauli permutations. | + | `num_qubits` | | + | [`partial_permutation_indices`](#qiskit_noise_learning.sequences.PartialPauliPermutation.partial_permutation_indices "qiskit_noise_learning.sequences.PartialPauliPermutation.partial_permutation_indices") | Raw numerical format of the partial permutation. | + | [`structure_token`](#qiskit_noise_learning.sequences.PartialPauliPermutation.structure_token "qiskit_noise_learning.sequences.PartialPauliPermutation.structure_token") | A hashable summary of this instruction that constrains mergeability. | + + ### inverse + + + Type: [`Self`](https://docs.python.org/3/library/typing.html#typing.Self) + + Return the inversion of this partial permutation. + + This returns a partially-specified inversion: only the existing mappings in this instance will be inverted. Note that the completion convention has been chosen to be consistent with inversion, in the sense that `self.inverse.complete() == self.complete().inverse`. Furthermore, the Clifford implied by `COMPLETE_TO_C1_TABLEAU` is the inverse of the implied Clifford. + + + ### is\_complete + + + Type: [`bool`](https://docs.python.org/3/library/functions.html#bool) + + Whether self represents a complete specification of single-qubit Pauli permutations. + + + ### partial\_permutation\_indices + + + Type: `NDArray`\[`int8`] + + Raw numerical format of the partial permutation. + + + ### structure\_token + + + Type: [`Hashable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Hashable) + + A hashable summary of this instruction that constrains mergeability. + + This token serves as a cheap check of non-mergeability: instructions with unequal structure tokens are never mergeable. The token must therefore distinguish instruction types from one another. + + + ### complete + + + Return a new partial Permutation that is complete and consistent with self. + + Note that the conventions have been chosen to ensure that: + + * Any partially-specified permutation consistent with the identity is mapped to the identity, and + * `self.inverse.complete() == self.complete().inverse`. + + **Returns** + + A new [`PartialPauliPermutation`](#qiskit_noise_learning.sequences.PartialPauliPermutation "qiskit_noise_learning.sequences.PartialPauliPermutation") containing the completion of `self`. + + + ### compose + + + Compose with another partial permutation. + + For complete permutations, `self.compose(other)` returns the permutation assciated with `C1 @ C2`, where `C1` and `C2` are the Cliffords associated, respectively, with `self` and `other`. Partially specified permutations only contain a single mapping, and the composition is defined in the natural way only when the output of `other` is the input of `self`. Note finally that composition is not defined if one of `self` and `other` is incomplete, and the other is complete. This is due to the inability to ensure the commutation of completion and composition, described below. + + Note that the completion convention has been chosen to be consistent with composition, in the sense that `self.compose(other).complete() == self.complete().compose(other.complete())`. Furthermore, for complete permutations, the mapping to the Clifford implied by `COMPLETE_TO_C1_TABLEAU` is a group homomorphism (preserves multiplication). + + **Parameters** + + **other** – The other to compose with. + + **Returns** + + The composed permutation. + + **Raises** + + [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – If the composition of `self` with `other` is undefined. + + + ### empty + + + Generate the completely unspecified instance on `num_qubits`. + + **Parameters** + + **num\_qubits** – Number of qubits. + + **Returns** + + A new, trivial [`PartialPauliPermutation`](#qiskit_noise_learning.sequences.PartialPauliPermutation "qiskit_noise_learning.sequences.PartialPauliPermutation"). + + + ### from\_qubit\_sparse\_paulis + + + Construct a `PartialPauliPermutation` that maps `in_pauli` to `out_pauli`. + + **Parameters** + + * **in\_pauli** – The Pauli to be mapped. + * **out\_pauli** – The Pauli to be mapped to. + + **Returns** + + A new [`PartialPauliPermutation`](#qiskit_noise_learning.sequences.PartialPauliPermutation "qiskit_noise_learning.sequences.PartialPauliPermutation") that maps `in_pauli` to `out_pauli`. + + **Raises** + + [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – If `in_pauli` and `out_pauli` are not on the same number of qubits, or if they do not act on the same qubits. + + + ### from\_qubit\_sparse\_pauli\_lists + + + Construct a `PartialPauliPermutation` that maps `in_paulis` to `out_paulis`. + + **Parameters** + + * **in\_paulis** – The Paulis to be mapped. + * **out\_paulis** – The Paulis to be mapped to. + + **Returns** + + A new [`PartialPauliPermutation`](#qiskit_noise_learning.sequences.PartialPauliPermutation "qiskit_noise_learning.sequences.PartialPauliPermutation"). + + **Raises** + + [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – If the number of qubits are inconsistent, or the implied permutations are inconsistent. + + + ### from\_sets + + + Construct from a list of sets. + + See the class documentation for a description of the expected format. + + **Parameters** + + **sets** – The sets specifying the partial permutation. + + **Returns** + + A new instance. + + **Raises** + + [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – If any of the sets are not valid. + + + ### is\_mergeable\_with + + + Whether or not this instruction is mergeable with another one. + + Two instructions are mergeable if a third instruction exists that simultaneously implements both of their actions. The trivial case is when the instructions are equal: the third instruction can be a third instance of the same instruction. However, non-trivial cases are possible because some instruction types, notably [`PartialPauliPermutation`](#qiskit_noise_learning.sequences.PartialPauliPermutation "qiskit_noise_learning.sequences.PartialPauliPermutation"), do not necessarily fully specify their own action, so that unequal instances can nevertheless still have their constraints simultaneously satisfied by a single third instance. + + If this method returns `True`, then the method [`merge()`](#qiskit_noise_learning.sequences.PartialPauliPermutation.merge "qiskit_noise_learning.sequences.PartialPauliPermutation.merge") should succeed. + + **Parameters** + + **other** – The other instruction to check mergeablitity with. + + **Returns** + + Whether this instruction is mergeable with the other. + + + ### merge + + + Merge self and other into a single instruction. + + **Parameters** + + **other** – The other instruction to merge with. + + **Returns** + + Some instruction (possibly the same instance) that simultaneously implements the action of this instruction and the other instruction. + + + ### propagate + + + Given a Pauli, propagate it through the Clifford implied by this permutation. + + This method works for both phased and unphased propagation depending on the type of the Pauli supplied. Unphased propagation can be performed on incomplete permutations, so long as the permutation is defined on the Pauli. Phased propagation requires `self` to be complete, so that an explicit Clifford can be associated with this instance. + + **Parameters** + + **pauli** – The Pauli to apply the layer to. + + **Returns** + + The evolved Pauli. + + **Raises** + + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – If `pauli.num_qubits != self.num_qubits`, or if `isinstance(pauli, PhasedQubitSparsePauli and not self.is_complete`, or if `pauli` is unphased and this instance is undefined on it. + * [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError) – If `pauli` is an invalid type. + + + ### to\_sets + + + Return the set representation. + + + diff --git a/docs/api/qiskit-noise-learning/generated/sequences-path.mdx b/docs/api/qiskit-noise-learning/generated/sequences-path.mdx new file mode 100644 index 000000000000..0508fa31878f --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/sequences-path.mdx @@ -0,0 +1,155 @@ +--- +title: Path (latest version) +description: API reference for qiskit_noise_learning.sequences.Path in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: class +python_api_name: qiskit_noise_learning.sequences.Path +--- + + + +# qiskit\_noise\_learning.sequences.Path + + + Bases: `BaseSequence`\[[`FidelityIndex`](sequences-fidelity-index "qiskit_noise_learning.sequences.fidelity_index.FidelityIndex")] + + A sequence of fidelity indices. + + **Parameters** + + * **start\_fragment** – The start of the sequence. + * **repeatable\_fragment** – The repeatable middle of the sequence. + * **end\_fragment** – The end of the sequence. + * **fragment\_depth** – The number of repetitions of the repeatable fragment. + + ### \_\_init\_\_ + + + + ## Methods + + | | | + | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | + | [`__init__`](#qiskit_noise_learning.sequences.Path.__init__ "qiskit_noise_learning.sequences.Path.__init__")(start\_fragment, ...\[, fragment\_depth]) | | + | `bind_at`(fragment\_depth) | Return a new instance with the same fragments bound to the fragment depth. | + | [`extend_permutations`](#qiskit_noise_learning.sequences.Path.extend_permutations "qiskit_noise_learning.sequences.Path.extend_permutations")(instruction\_sequence) | Return an instruction sequence with extended permutations to traverse self. | + | [`fragment_sign_flips`](#qiskit_noise_learning.sequences.Path.fragment_sign_flips "qiskit_noise_learning.sequences.Path.fragment_sign_flips")(instruction\_sequence) | Whether the instruction sequence fragments flip the observable sign when traversing self. | + | [`is_traversed_by`](#qiskit_noise_learning.sequences.Path.is_traversed_by "qiskit_noise_learning.sequences.Path.is_traversed_by")(instruction\_sequence) | Whether or not this path is traversed by the instruction sequence. | + | [`to_instruction_sequence`](#qiskit_noise_learning.sequences.Path.to_instruction_sequence "qiskit_noise_learning.sequences.Path.to_instruction_sequence")() | Return a minimally-specified instruction sequence that traverses this path. | + | `unbind`() | Return a new instance with the same fragments but fragment depth set to `None`. | + + ## Attributes + + | | | + | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | + | `end_fragment` | The ending fragment. | + | [`end_fragment_observable_idxs`](#qiskit_noise_learning.sequences.Path.end_fragment_observable_idxs "qiskit_noise_learning.sequences.Path.end_fragment_observable_idxs") | The observable indices of the end fragment. | + | `fragment_depth` | The number of repetitions of the repeatable fragment. | + | `is_unbound` | Whether the sequence is unbound. | + | `repeatable_fragment` | The repeatable fragment. | + | [`repeatable_fragment_observable_idxs`](#qiskit_noise_learning.sequences.Path.repeatable_fragment_observable_idxs "qiskit_noise_learning.sequences.Path.repeatable_fragment_observable_idxs") | The observable indices of the repeatable fragment. | + | `start_fragment` | The starting fragment. | + | [`start_fragment_observable_idxs`](#qiskit_noise_learning.sequences.Path.start_fragment_observable_idxs "qiskit_noise_learning.sequences.Path.start_fragment_observable_idxs") | The observable indices of the start fragment. | + + ### start\_fragment\_observable\_idxs + + + Type: [`list`](https://docs.python.org/3/library/stdtypes.html#list)\[[`list`](https://docs.python.org/3/library/stdtypes.html#list)\[[`int`](https://docs.python.org/3/library/functions.html#int)]] + + The observable indices of the start fragment. + + + ### repeatable\_fragment\_observable\_idxs + + + Type: [`list`](https://docs.python.org/3/library/stdtypes.html#list)\[[`list`](https://docs.python.org/3/library/stdtypes.html#list)\[[`int`](https://docs.python.org/3/library/functions.html#int)]] + + The observable indices of the repeatable fragment. + + + ### end\_fragment\_observable\_idxs + + + Type: [`list`](https://docs.python.org/3/library/stdtypes.html#list)\[[`list`](https://docs.python.org/3/library/stdtypes.html#list)\[[`int`](https://docs.python.org/3/library/functions.html#int)]] + + The observable indices of the end fragment. + + + ### extend\_permutations + + + Return an instruction sequence with extended permutations to traverse self. + + Given an `instruction_sequence`, this method attempts to extend its definition by constructing a new instruction sequence with the same structure as the input, but for which the [`PartialPauliPermutation`](sequences-partial-pauli-permutation "qiskit_noise_learning.sequences.PartialPauliPermutation")s are extended to specify the minimal superset of mappings required to traverse this path. If this is not possible, the function will return `None`, indicating that the procedure failed. + + In terms of the specific algorithm, when encountering a [`PartialPauliPermutation`](sequences-partial-pauli-permutation "qiskit_noise_learning.sequences.PartialPauliPermutation") while jointly iterating through `self` and `instruction_sequence`, this method will attempt to extend the permutation to map the current Pauli in the path to the Pauli in the next relevant [`FidelityIndex`](sequences-fidelity-index "qiskit_noise_learning.sequences.FidelityIndex"). Note that this can lead to failures in instances when multiple permutations occur in a row, even if it is technically possible to find a super instruction sequence that traverses the path. + + **Parameters** + + **instruction\_sequence** – The base instruction sequence. + + **Returns** + + The extended instruction sequence, or `None` if an extension is not possible. + + **Raises** + + [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – If the transitions of `self` do not start and end with the identity. + + + ### is\_traversed\_by + + + Whether or not this path is traversed by the instruction sequence. + + Whether or not a [`Path`](#qiskit_noise_learning.sequences.Path "qiskit_noise_learning.sequences.Path") is traversed by an [`InstructionSequence`](sequences-instruction-sequence "qiskit_noise_learning.sequences.InstructionSequence") is determined on a fragment-by-fragment basis. + + Requires the path starts and ends at the identity. + + **Parameters** + + **instruction\_sequence** – The instruction sequence. + + **Returns** + + Whether or not the path is traversed. + + **Raises** + + [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – If the path does not start and end at the identity. + + + ### fragment\_sign\_flips + + + Whether the instruction sequence fragments flip the observable sign when traversing self. + + Requires the path starts and ends at the identity. This method ignores the fragment depths of the path and instruction sequence, operating only on the fragment structure. + + **Parameters** + + **instruction\_sequence** – An instruction sequence that traverses this path. + + **Returns** + + A tuple of booleans, the first indicating whether the combined action of the start and end fragments flip the sign, and the second indicating whether the repeatable fragment flips the sign. + + **Raises** + + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – If the path does not satisfy the assumptions. + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – If the instruction sequence does not traverse the path. + + + ### to\_instruction\_sequence + + + Return a minimally-specified instruction sequence that traverses this path. + + The single-qubit Clifford layers between gate set elements are given as [`PartialPauliPermutation`](sequences-partial-pauli-permutation "qiskit_noise_learning.sequences.PartialPauliPermutation")s specifying only the mappings required to traverse this path. The fragment depth of the returned instruction sequence is `self.fragment_depth`. + + **Returns** + + An instruction sequence traversing this path. + + + diff --git a/docs/api/qiskit-noise-learning/generated/visualizations-fidelity-index-math-label.mdx b/docs/api/qiskit-noise-learning/generated/visualizations-fidelity-index-math-label.mdx new file mode 100644 index 000000000000..ee170ac1b10e --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/visualizations-fidelity-index-math-label.mdx @@ -0,0 +1,32 @@ +--- +title: fidelity_index_math_label (latest version) +description: API reference for qiskit_noise_learning.visualizations.fidelity_index_math_label in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit_noise_learning.visualizations.fidelity_index_math_label +--- + + + +# qiskit\_noise\_learning.visualizations.fidelity\_index\_math\_label + + + Return a math-mode LaTeX label for a fidelity index. + + **Parameters** + + * **gate\_set** – The gate set the fidelity index belongs to, used to look up the gate’s [`math_label`](gate-sets-gate#math_label "qiskit_noise_learning.gate_sets.Gate.math_label"). + * **fidelity\_index** – The fidelity index to label. + * **style** – Either `"transition"` (shows input $\to$ output Pauli) or `"formula"` (shows the index data [`pauli`](sequences-fidelity-index#pauli "qiskit_noise_learning.sequences.FidelityIndex.pauli") alongside the $Z$ exponents $x$ and $y$, displayed as the qubit indices on which they are non-zero, i.e. [`in_z_idxs`](sequences-fidelity-index#in_z_idxs "qiskit_noise_learning.sequences.FidelityIndex.in_z_idxs") and [`out_z_idxs`](sequences-fidelity-index#out_z_idxs "qiskit_noise_learning.sequences.FidelityIndex.out_z_idxs")). + * **noise\_site** – An optional mapping from gate name to `"before"` or `"after"`, indicating the gate noise is modelled as a Pauli-channel occuring either before or after the gate. This simplifies the `style="formula"` label to only display the Pauli passing through the Pauli channel. + * **qubit\_labels** – An optional mapping from qubit index to a display symbol, used to relabel the qubit subscripts (e.g. `{25: "i", 26: "j"}` renders `X_{25}` as `X_{i}`). Indices absent from the mapping render as their integer value. + + **Returns** + + A math-mode LaTeX label. + + **Raises** + + [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – If `style` is not `"transition"` or `"formula"`. + + diff --git a/docs/api/qiskit-noise-learning/generated/visualizations-gate-set-topology.mdx b/docs/api/qiskit-noise-learning/generated/visualizations-gate-set-topology.mdx new file mode 100644 index 000000000000..446d0c1b4037 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/visualizations-gate-set-topology.mdx @@ -0,0 +1,35 @@ +--- +title: gate_set_topology (latest version) +description: API reference for qiskit_noise_learning.visualizations.gate_set_topology in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit_noise_learning.visualizations.gate_set_topology +--- + + + +# qiskit\_noise\_learning.visualizations.gate\_set\_topology + + + Draw the device topology with per-gate coloring. + + Gates with 2-qubit interactions are drawn as colored edges on the device coupling graph. Gates that act only on individual qubits (such as preparation and measurement) are shown as colored arcs around the relevant nodes, with one arc sector per gate per qubit. The arc sectors are arranged so that the first gate in the set occupies the right-hand side of the circle (angle 0), and subsequent gates proceed counter-clockwise. Qubits that are idling in a given gate receive a slightly transparent arc. + + Two legends switch what is shown: one per gate, and one per kind of mark. Gates that only prepare or only measure open switched off, since they touch every qubit at once and would otherwise bury the rest; their legend entry brings them back. + + Qubits are placed in the device’s conventional layout where it has one, and laid out from its coupling graph otherwise. A target that constrains connectivity nowhere – an ideal or all-to-all device – has no topology to draw and no graph to lay out from, so its qubits are drawn without edges, in the conventional layout if its size has one. + + **Parameters** + + **gate\_set** – The gate set to visualize. Must have a non-`None` [`target`](gate-sets-gate-set#target "qiskit_noise_learning.gate_sets.GateSet.target") so that qubit coordinates and the device topology can be determined. + + **Returns** + + The figure. + + **Raises** + + * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – If `gate_set.target` is `None`, or if the device’s size is not one of the conventionally drawn ones and its target constrains connectivity nowhere, leaving no coupling graph to derive a layout from. + * [**ImportError**](https://docs.python.org/3/library/exceptions.html#ImportError) – If `matplotlib` is not installed. + + diff --git a/docs/api/qiskit-noise-learning/generated/visualizations-path-math-label.mdx b/docs/api/qiskit-noise-learning/generated/visualizations-path-math-label.mdx new file mode 100644 index 000000000000..8a39db806019 --- /dev/null +++ b/docs/api/qiskit-noise-learning/generated/visualizations-path-math-label.mdx @@ -0,0 +1,29 @@ +--- +title: path_math_label (latest version) +description: API reference for qiskit_noise_learning.visualizations.path_math_label in the latest version of qiskit-noise-learning +in_page_toc_min_heading_level: 1 +python_api_type: function +python_api_name: qiskit_noise_learning.visualizations.path_math_label +--- + + + +# qiskit\_noise\_learning.visualizations.path\_math\_label + + + Return a math-mode LaTeX label for a path. + + **Parameters** + + * **gate\_set** – The gate set the path’s fidelity indices belong to, used to look up each gate’s [`math_label`](gate-sets-gate#math_label "qiskit_noise_learning.gate_sets.Gate.math_label"). + * **path** – The path to label. + * **style** – The style to use for each fidelity index label. `"transition"` displays the Pauli operator transitions induced by each gate, and `"formula"` displays the fidelity label formula associated with this path. + * **noise\_site** – An optional noise-site mapping forwarded to [`fidelity_index_math_label()`](visualizations-fidelity-index-math-label "qiskit_noise_learning.visualizations.fidelity_index_math_label") for the `"formula"` style (see that function for details). + * **repeatable\_only** – If `True`, only render the repeatable fragment without brackets or fragment-depth exponent. + * **qubit\_labels** – An optional mapping from qubit index to a display symbol, used to relabel the qubit subscripts (e.g. `{25: "i", 26: "j"}` renders `X_{25}` as `X_{i}`). Indices absent from the mapping render as their integer value. + + **Returns** + + A math-mode LaTeX label. + + diff --git a/docs/api/qiskit-noise-learning/math.mdx b/docs/api/qiskit-noise-learning/math.mdx index 95e0b4b1ed09..d4b5001b9606 100644 --- a/docs/api/qiskit-noise-learning/math.mdx +++ b/docs/api/qiskit-noise-learning/math.mdx @@ -18,12 +18,12 @@ General mathematical objects. ## Classes -| | | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | -| [`IndexedMatrix`](generated/math-indexed-matrix#qiskit_noise_learning.math.IndexedMatrix "qiskit_noise_learning.math.IndexedMatrix") | A matrix with float entries and arbitrary row and column index data. | -| [`EnumeratedIndexedSpace`](generated/math-enumerated-indexed-space#qiskit_noise_learning.math.EnumeratedIndexedSpace "qiskit_noise_learning.math.EnumeratedIndexedSpace") | An indexed space backed by an explicit finite collection of indices. | -| [`IndexedSpace`](generated/math-indexed-space#qiskit_noise_learning.math.IndexedSpace "qiskit_noise_learning.math.IndexedSpace") | Abstract description of a vector space with arbitrary basis index types. | -| [`IndexedVector`](generated/math-indexed-vector#qiskit_noise_learning.math.IndexedVector "qiskit_noise_learning.math.IndexedVector") | A vector of floats with arbitrary index, or axis label, data. | -| [`ComposedLinearMap`](generated/math-composed-linear-map#qiskit_noise_learning.math.ComposedLinearMap "qiskit_noise_learning.math.ComposedLinearMap") | A linear map formed by composing a chain of maps. | -| [`LinearMap`](generated/math-linear-map#qiskit_noise_learning.math.LinearMap "qiskit_noise_learning.math.LinearMap") | An implicit linear map between two indexed spaces. | +| | | +| ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | +| [`IndexedMatrix`](generated/math-indexed-matrix "qiskit_noise_learning.math.IndexedMatrix") | A matrix with float entries and arbitrary row and column index data. | +| [`EnumeratedIndexedSpace`](generated/math-enumerated-indexed-space "qiskit_noise_learning.math.EnumeratedIndexedSpace") | An indexed space backed by an explicit finite collection of indices. | +| [`IndexedSpace`](generated/math-indexed-space "qiskit_noise_learning.math.IndexedSpace") | Abstract description of a vector space with arbitrary basis index types. | +| [`IndexedVector`](generated/math-indexed-vector "qiskit_noise_learning.math.IndexedVector") | A vector of floats with arbitrary index, or axis label, data. | +| [`ComposedLinearMap`](generated/math-composed-linear-map "qiskit_noise_learning.math.ComposedLinearMap") | A linear map formed by composing a chain of maps. | +| [`LinearMap`](generated/math-linear-map "qiskit_noise_learning.math.LinearMap") | An implicit linear map between two indexed spaces. | diff --git a/docs/api/qiskit-noise-learning/models.mdx b/docs/api/qiskit-noise-learning/models.mdx index c1c685300210..2f7e6d3bf09e 100644 --- a/docs/api/qiskit-noise-learning/models.mdx +++ b/docs/api/qiskit-noise-learning/models.mdx @@ -18,29 +18,29 @@ Gate set noise models. ## Classes -| | | -| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`IdentityFidelityModel`](generated/models-identity-fidelity-model#qiskit_noise_learning.models.IdentityFidelityModel "qiskit_noise_learning.models.IdentityFidelityModel") | A fidelity model whose parameters are the log fidelities themselves. | -| [`LogFidelitySpace`](generated/models-log-fidelity-space#qiskit_noise_learning.models.LogFidelitySpace "qiskit_noise_learning.models.LogFidelitySpace") | The space of log fidelities of a gate set. | -| [`GeneratorIndex`](generated/models-generator-index#qiskit_noise_learning.models.GeneratorIndex "qiskit_noise_learning.models.GeneratorIndex") | | -| [`PauliLindbladModel`](generated/models-pauli-lindblad-model#qiskit_noise_learning.models.PauliLindbladModel "qiskit_noise_learning.models.PauliLindbladModel") | A linear mapping from Pauli-Lindblad generator rates to log fidelities. | -| [`RateSpace`](generated/models-rate-space#qiskit_noise_learning.models.RateSpace "qiskit_noise_learning.models.RateSpace") | Space of Pauli-Lindblad generator rates, indexed by [`GeneratorIndex`](generated/models-generator-index#qiskit_noise_learning.models.GeneratorIndex "qiskit_noise_learning.models.GeneratorIndex"). | -| [`PauliLindbladSplit`](generated/models-pauli-lindblad-split#qiskit_noise_learning.models.PauliLindbladSplit "qiskit_noise_learning.models.PauliLindbladSplit") | The decomposition of a map around its underlying [`PauliLindbladModel`](generated/models-pauli-lindblad-model#qiskit_noise_learning.models.PauliLindbladModel "qiskit_noise_learning.models.PauliLindbladModel"). | +| | | +| ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`IdentityFidelityModel`](generated/models-identity-fidelity-model "qiskit_noise_learning.models.IdentityFidelityModel") | A fidelity model whose parameters are the log fidelities themselves. | +| [`LogFidelitySpace`](generated/models-log-fidelity-space "qiskit_noise_learning.models.LogFidelitySpace") | The space of log fidelities of a gate set. | +| [`GeneratorIndex`](generated/models-generator-index "qiskit_noise_learning.models.GeneratorIndex") | | +| [`PauliLindbladModel`](generated/models-pauli-lindblad-model "qiskit_noise_learning.models.PauliLindbladModel") | A linear mapping from Pauli-Lindblad generator rates to log fidelities. | +| [`RateSpace`](generated/models-rate-space "qiskit_noise_learning.models.RateSpace") | Space of Pauli-Lindblad generator rates, indexed by [`GeneratorIndex`](generated/models-generator-index "qiskit_noise_learning.models.GeneratorIndex"). | +| [`PauliLindbladSplit`](generated/models-pauli-lindblad-split "qiskit_noise_learning.models.PauliLindbladSplit") | The decomposition of a map around its underlying [`PauliLindbladModel`](generated/models-pauli-lindblad-model "qiskit_noise_learning.models.PauliLindbladModel"). | ## Functions -| | | -| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| [`contains_pauli_lindblad_model`](generated/models-contains-pauli-lindblad-model#qiskit_noise_learning.models.contains_pauli_lindblad_model "qiskit_noise_learning.models.contains_pauli_lindblad_model")(model) | Whether a map is, or contains, a [`PauliLindbladModel`](generated/models-pauli-lindblad-model#qiskit_noise_learning.models.PauliLindbladModel "qiskit_noise_learning.models.PauliLindbladModel"). | -| [`get_noise_site`](generated/models-get-noise-site#qiskit_noise_learning.models.get_noise_site "qiskit_noise_learning.models.get_noise_site")(model) | The noise-site mapping of the map's [`PauliLindbladModel`](generated/models-pauli-lindblad-model#qiskit_noise_learning.models.PauliLindbladModel "qiskit_noise_learning.models.PauliLindbladModel"), if it has exactly one. | -| [`is_fidelity_model`](generated/models-is-fidelity-model#qiskit_noise_learning.models.is_fidelity_model "qiskit_noise_learning.models.is_fidelity_model")(model) | Whether an object is a [`LinearMap`](generated/math-linear-map#qiskit_noise_learning.math.LinearMap "qiskit_noise_learning.math.LinearMap") with a [`LogFidelitySpace`](generated/models-log-fidelity-space#qiskit_noise_learning.models.LogFidelitySpace "qiskit_noise_learning.models.LogFidelitySpace") output space. | -| [`split_pauli_lindblad_model`](generated/models-split-pauli-lindblad-model#qiskit_noise_learning.models.split_pauli_lindblad_model "qiskit_noise_learning.models.split_pauli_lindblad_model")(model) | Split a map around its underlying [`PauliLindbladModel`](generated/models-pauli-lindblad-model#qiskit_noise_learning.models.PauliLindbladModel "qiskit_noise_learning.models.PauliLindbladModel"). | +| | | +| ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`contains_pauli_lindblad_model`](generated/models-contains-pauli-lindblad-model "qiskit_noise_learning.models.contains_pauli_lindblad_model")(model) | Whether a map is, or contains, a [`PauliLindbladModel`](generated/models-pauli-lindblad-model "qiskit_noise_learning.models.PauliLindbladModel"). | +| [`get_noise_site`](generated/models-get-noise-site "qiskit_noise_learning.models.get_noise_site")(model) | The noise-site mapping of the map's [`PauliLindbladModel`](generated/models-pauli-lindblad-model "qiskit_noise_learning.models.PauliLindbladModel"), if it has exactly one. | +| [`is_fidelity_model`](generated/models-is-fidelity-model "qiskit_noise_learning.models.is_fidelity_model")(model) | Whether an object is a [`LinearMap`](generated/math-linear-map "qiskit_noise_learning.math.LinearMap") with a [`LogFidelitySpace`](generated/models-log-fidelity-space "qiskit_noise_learning.models.LogFidelitySpace") output space. | +| [`split_pauli_lindblad_model`](generated/models-split-pauli-lindblad-model "qiskit_noise_learning.models.split_pauli_lindblad_model")(model) | Split a map around its underlying [`PauliLindbladModel`](generated/models-pauli-lindblad-model "qiskit_noise_learning.models.PauliLindbladModel"). | ## Type aliases ### qiskit\_noise\_learning.models.FidelityModel - alias of [`LinearMap`](generated/math-linear-map#qiskit_noise_learning.math.LinearMap "qiskit_noise_learning.math.linear_map.LinearMap")\[[`Hashable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Hashable), [`FidelityIndex`](generated/sequences-fidelity-index#qiskit_noise_learning.sequences.FidelityIndex "qiskit_noise_learning.sequences.fidelity_index.FidelityIndex")] + alias of [`LinearMap`](generated/math-linear-map "qiskit_noise_learning.math.linear_map.LinearMap")\[[`Hashable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Hashable), [`FidelityIndex`](generated/sequences-fidelity-index "qiskit_noise_learning.sequences.fidelity_index.FidelityIndex")] diff --git a/docs/api/qiskit-noise-learning/noise-learner.mdx b/docs/api/qiskit-noise-learning/noise-learner.mdx index 00ef4b1a0082..13d22d8e7590 100644 --- a/docs/api/qiskit-noise-learning/noise-learner.mdx +++ b/docs/api/qiskit-noise-learning/noise-learner.mdx @@ -18,12 +18,12 @@ Noise learner. ## Classes -| | | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`LearningOptions`](generated/noise-learner-learning-options#qiskit_noise_learning.noise_learner.LearningOptions "qiskit_noise_learning.noise_learner.LearningOptions") | Options for the noise learner. | -| [`NoiseLearner`](generated/noise-learner-noise-learner#qiskit_noise_learning.noise_learner.NoiseLearner "qiskit_noise_learning.noise_learner.NoiseLearner") | A noise learner. | -| [`NoiseLearnerJob`](generated/noise-learner-noise-learner-job#qiskit_noise_learning.noise_learner.NoiseLearnerJob "qiskit_noise_learning.noise_learner.NoiseLearnerJob") | A noise learner job. | -| [`NoiseLearnerResult`](generated/noise-learner-noise-learner-result#qiskit_noise_learning.noise_learner.NoiseLearnerResult "qiskit_noise_learning.noise_learner.NoiseLearnerResult") | Result of noise learning. | -| [`ProgramExecutor`](generated/noise-learner-program-executor#qiskit_noise_learning.noise_learner.ProgramExecutor "qiskit_noise_learning.noise_learner.ProgramExecutor") | The executor role that [`NoiseLearner`](generated/noise-learner-noise-learner#qiskit_noise_learning.noise_learner.NoiseLearner "qiskit_noise_learning.noise_learner.NoiseLearner") submits programs to. | -| [`ProgramJob`](generated/noise-learner-program-job#qiskit_noise_learning.noise_learner.ProgramJob "qiskit_noise_learning.noise_learner.ProgramJob") | The job role that [`NoiseLearnerJob`](generated/noise-learner-noise-learner-job#qiskit_noise_learning.noise_learner.NoiseLearnerJob "qiskit_noise_learning.noise_learner.NoiseLearnerJob") wraps. | +| | | +| ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| [`LearningOptions`](generated/noise-learner-learning-options "qiskit_noise_learning.noise_learner.LearningOptions") | Options for the noise learner. | +| [`NoiseLearner`](generated/noise-learner-noise-learner "qiskit_noise_learning.noise_learner.NoiseLearner") | A noise learner. | +| [`NoiseLearnerJob`](generated/noise-learner-noise-learner-job "qiskit_noise_learning.noise_learner.NoiseLearnerJob") | A noise learner job. | +| [`NoiseLearnerResult`](generated/noise-learner-noise-learner-result "qiskit_noise_learning.noise_learner.NoiseLearnerResult") | Result of noise learning. | +| [`ProgramExecutor`](generated/noise-learner-program-executor "qiskit_noise_learning.noise_learner.ProgramExecutor") | The executor role that [`NoiseLearner`](generated/noise-learner-noise-learner "qiskit_noise_learning.noise_learner.NoiseLearner") submits programs to. | +| [`ProgramJob`](generated/noise-learner-program-job "qiskit_noise_learning.noise_learner.ProgramJob") | The job role that [`NoiseLearnerJob`](generated/noise-learner-noise-learner-job "qiskit_noise_learning.noise_learner.NoiseLearnerJob") wraps. | diff --git a/docs/api/qiskit-noise-learning/sequences.mdx b/docs/api/qiskit-noise-learning/sequences.mdx index 9e4c394f53d6..3e157dd18036 100644 --- a/docs/api/qiskit-noise-learning/sequences.mdx +++ b/docs/api/qiskit-noise-learning/sequences.mdx @@ -18,19 +18,19 @@ Path and instruction sequences. ## Classes -| | | -| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | -| [`ApplyGate`](generated/sequences-apply-gate#qiskit_noise_learning.sequences.ApplyGate "qiskit_noise_learning.sequences.ApplyGate") | An instruction that applies a fixed gate. | -| [`FidelityIndex`](generated/sequences-fidelity-index#qiskit_noise_learning.sequences.FidelityIndex "qiskit_noise_learning.sequences.FidelityIndex") | Index data for a fidelity in a Pauli-MCM-reset gate set. | -| [`InstructionSequence`](generated/sequences-instruction-sequence#qiskit_noise_learning.sequences.InstructionSequence "qiskit_noise_learning.sequences.InstructionSequence") | A sequence of instructions. | -| [`LogPathMap`](generated/sequences-log-path-map#qiskit_noise_learning.sequences.LogPathMap "qiskit_noise_learning.sequences.LogPathMap") | The linear map from a space of log fidelities to its associated log path space. | -| [`LogPathSpace`](generated/sequences-log-path-space#qiskit_noise_learning.sequences.LogPathSpace "qiskit_noise_learning.sequences.LogPathSpace") | The (infinite-dimensional) space of log path-fidelities. | -| [`PartialPauliPermutation`](generated/sequences-partial-pauli-permutation#qiskit_noise_learning.sequences.PartialPauliPermutation "qiskit_noise_learning.sequences.PartialPauliPermutation") | Partially-specified permutations of the single-qubit phaseless Paulis on `n` qubits. | -| [`Path`](generated/sequences-path#qiskit_noise_learning.sequences.Path "qiskit_noise_learning.sequences.Path") | A sequence of fidelity indices. | +| | | +| ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | +| [`ApplyGate`](generated/sequences-apply-gate "qiskit_noise_learning.sequences.ApplyGate") | An instruction that applies a fixed gate. | +| [`FidelityIndex`](generated/sequences-fidelity-index "qiskit_noise_learning.sequences.FidelityIndex") | Index data for a fidelity in a Pauli-MCM-reset gate set. | +| [`InstructionSequence`](generated/sequences-instruction-sequence "qiskit_noise_learning.sequences.InstructionSequence") | A sequence of instructions. | +| [`LogPathMap`](generated/sequences-log-path-map "qiskit_noise_learning.sequences.LogPathMap") | The linear map from a space of log fidelities to its associated log path space. | +| [`LogPathSpace`](generated/sequences-log-path-space "qiskit_noise_learning.sequences.LogPathSpace") | The (infinite-dimensional) space of log path-fidelities. | +| [`PartialPauliPermutation`](generated/sequences-partial-pauli-permutation "qiskit_noise_learning.sequences.PartialPauliPermutation") | Partially-specified permutations of the single-qubit phaseless Paulis on `n` qubits. | +| [`Path`](generated/sequences-path "qiskit_noise_learning.sequences.Path") | A sequence of fidelity indices. | ## Functions -| | | -| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | -| [`group_mergeable_instruction_sequences`](generated/sequences-group-mergeable-instruction-sequences#qiskit_noise_learning.sequences.group_mergeable_instruction_sequences "qiskit_noise_learning.sequences.group_mergeable_instruction_sequences") | Group the positions of instruction sequences that can be merged with each other. | +| | | +| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | +| [`group_mergeable_instruction_sequences`](generated/sequences-group-mergeable-instruction-sequences "qiskit_noise_learning.sequences.group_mergeable_instruction_sequences") | Group the positions of instruction sequences that can be merged with each other. | diff --git a/docs/api/qiskit-noise-learning/visualizations.mdx b/docs/api/qiskit-noise-learning/visualizations.mdx index 38a23ebe333e..abdafa964ff1 100644 --- a/docs/api/qiskit-noise-learning/visualizations.mdx +++ b/docs/api/qiskit-noise-learning/visualizations.mdx @@ -18,9 +18,9 @@ Visualization utilities. ## Functions -| | | -| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | -| [`fidelity_index_math_label`](generated/visualizations-fidelity-index-math-label#qiskit_noise_learning.visualizations.fidelity_index_math_label "qiskit_noise_learning.visualizations.fidelity_index_math_label")(gate\_set, ...\[, ...]) | Return a math-mode LaTeX label for a fidelity index. | -| [`path_math_label`](generated/visualizations-path-math-label#qiskit_noise_learning.visualizations.path_math_label "qiskit_noise_learning.visualizations.path_math_label")(gate\_set, path\[, style, ...]) | Return a math-mode LaTeX label for a path. | -| [`gate_set_topology`](generated/visualizations-gate-set-topology#qiskit_noise_learning.visualizations.gate_set_topology "qiskit_noise_learning.visualizations.gate_set_topology")(gate\_set) | Draw the device topology with per-gate coloring. | +| | | +| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | +| [`fidelity_index_math_label`](generated/visualizations-fidelity-index-math-label "qiskit_noise_learning.visualizations.fidelity_index_math_label")(gate\_set, ...\[, ...]) | Return a math-mode LaTeX label for a fidelity index. | +| [`path_math_label`](generated/visualizations-path-math-label "qiskit_noise_learning.visualizations.path_math_label")(gate\_set, path\[, style, ...]) | Return a math-mode LaTeX label for a path. | +| [`gate_set_topology`](generated/visualizations-gate-set-topology "qiskit_noise_learning.visualizations.gate_set_topology")(gate\_set) | Draw the device topology with per-gate coloring. | diff --git a/public/docs/api/qiskit-noise-learning/objects.inv b/public/docs/api/qiskit-noise-learning/objects.inv index 00d276ad5255a67072a4d64e016d4276fdc4f1ef..f560111d4d8e8809ed13d872cba47da34a13b657 100644 GIT binary patch delta 7027 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 z z$tG8OgEpnPnDXzokg;vY8~bs{EUsSLLJEKksoik!qvi12w#ceVGk#Fp=lVfZCqaw; z0(D3g*KLyF#&%yUT-`=Pg{s0(K%gS*VK7~DMDQy^Pb`GW^Fit#r`_ndKCdANGskBF z1>*}blYahs_x|DAOgg%<{b_iw- z-WowC0tlDsG$$Lvn25^e#^yKP9k<)0*lZVsM}H9C#(8W6OI7v4%J_xWyW}l<(MH*W zyWh1>Y(+l2qXZ+FLoAj<-m#&Sprz!NW9$(DFY@9`{VQSl?e$^LL1?utf$R5AkC<4c);wbZLmA3=|r9md%+J(ez$sY1ybG`AMc*q zhKH*5(GYFJx0?s*GgugA*vE)v)5{_8ju#}@SEcbLg()LvXUNLn`G}3crFLK%J%692 z&*#X}1*;iVrUrJa6{)CD`@yMd@%E^A1!>&+ZCu5L^(^9C3xF?@xw#Cp6XWJuTS6cp z9~o|a!p-d@s-~U{){A#~t!_6TX&O0Xkb}Mrd1SQ2!0z@V2v3ENf6>iZ9}Y45Tupd} z1xE(~_y`aV6hB6`GYqR!W0cpz&3|jKip;cSG6=Zm*91F8`_AYgxlo@khIe97SRg}T z4fU1FhUU|4%fs^i{FQr+fByZ2UP|ZJ+AQ|>xqu7ZMB2C`TEIInhyEygs;aumtJ4{Z z-3OT^eL^^9*DtWS?Ko~0pS$}I#wROCS8_*46Z2() zV*dU`|Fa@Xe=sJ$zT0ss?D_)9WOA>4|L8sR+Q<=hybE%IHpDwl%=mA9y?2Bf(?apewu?j}8+lsAsZY5X6x2k6O3dJVy{fl z6Z>PBwn!JdHUX(7DbN^ro;v7PqYyj~Z2}C>YYY#bjd*1rxk3=tDSyb3D-_jh7(CaH zTsgSu^9XJs9>_VbA1bMySk4Yk5;?C)T}ee``#DNDp4{EjpKWxvrz(GSb=F*d=_AHT z^Epbm2RU}4hck$o`4Y%#l^68szMoFm++%;b=ypW|@1 zGF!q4Vf$$eT>@r133uXwgJ=6cCMvK7{KiCu(SUQ|U~*TpkelAh?ItpxmZm+U)T;^5 zXcu13jY26z$d%S5_q47VK0jJ*Y2TAh>kkXggND1gJ)H#86Mv&@9QD`rtzk%qBopJp zrgN=8IJ$T2mE|mRFwEPpoSY`oa5PNx5(kO)sv;MKK@yGtxUvv66jCpb^vyv;&^IT8 zP6`zav8wn2GKBrp!|gqex2$P_ zB|M;nQ0>N@pk~yMeSreTCm7Kl%qCa-I(SWP=uO~KgD3$?>*C(v1SK3yZspdUMQ&>s`Xm_9 zIA$vsIIYuLyCo_?gW!nHFTz^qH@{jdflBlu<0>m~0R3W1iq)uzy^yB7oayUWXS?P{Og~7Gi7L=q<&f zPLKdW6x#^X2#O|zb%F%IQXFG}+n9}!#S@q`EDig81~zKe%M22KP;3q^Zbh(bo9UGZ z2|_HE)b+gtRz)LGD&|T!mYpTMyp861Z280!4ouu0eQ=SqJ<4I?f#b<`7K9K$b@o?+ zMSqAua&=3mBWz&e0Th957atGJxC_qd2j|KAGRz}@^kq27!~-XcEwDXIA~Pm9>0o+G zr?3{8EuHL2z%o7f%uioAIL%K_Bq-S)+?Gx@IT$WE#u5)454MxTP7adOGgJv&tUo7< zy|#9WD#3{MV77LW$w6}U=v3kf=tW(9c7O9!pA(264}91GNC!dC>Bl4r6>t{8hrJf_ z20iJOgn|3!=K9zeBo|j_#u7g;U)Glg&mf#HPMsw_Km%WXIWDyiZXbS21UoV@Q`W^r z&oqDE>wn&_`-{edPTj@fQvvOh`}V*0w%NicW`6h6MB3ayHnv&P|MebVd5jQ?-G6+1 zI4&%`cl6*< Date: Thu, 10 Sep 2026 13:39:33 -0400 Subject: [PATCH 11/15] Fix API doc generation for equation anchors, nested page paths, and addon guide links - Preserve anchor IDs on `math-wrapper` divs so numbered Sphinx equations keep working links (previously only `section` divs kept their `id`). - Kebab-case only the final path segment when rewriting links to nested generated pages, so folder separators aren't collapsed. - Rewrite relative `guides/...` links in addon API reference pages to absolute paths under `docs/addons//guides/`. --- scripts/js/lib/api/htmlToMd.ts | 6 +++++- scripts/js/lib/api/pipelineStages.ts | 20 +++++++++++++++++++- 2 files changed, 24 insertions(+), 2 deletions(-) diff --git a/scripts/js/lib/api/htmlToMd.ts b/scripts/js/lib/api/htmlToMd.ts index e0ffb05f20d2..25b1e2d27fbf 100644 --- a/scripts/js/lib/api/htmlToMd.ts +++ b/scripts/js/lib/api/htmlToMd.ts @@ -137,7 +137,11 @@ function prepareHandlers(meta: Metadata): Record { return buildApiVersionAdmonition(node, handlers, "info"); } - return node.properties.id && nodeClasses.includes("section") + // `math-wrapper` divs carry the anchor ID for numbered Sphinx equations + // (e.g. `id="equation-foo"`), which is otherwise dropped by the default + // div handler since it isn't a `section`. + return node.properties.id && + (nodeClasses.includes("section") || nodeClasses.includes("math-wrapper")) ? [buildSpanId(node.properties.id), ...all(h, node)] : defaultHandlers.div(h, node); }, diff --git a/scripts/js/lib/api/pipelineStages.ts b/scripts/js/lib/api/pipelineStages.ts index 6f2682817609..4e2cdafa9175 100644 --- a/scripts/js/lib/api/pipelineStages.ts +++ b/scripts/js/lib/api/pipelineStages.ts @@ -163,8 +163,16 @@ function rewriteApiDocsLinks(results: HtmlToMdResultWithUrl[], pkg: Pkg) { const targetPkg = pkg.isCApi() ? pythonSiblingPkg : pkg.name; const targetUsesKebab = pkg.kebabCaseAndShortenUrls && targetPkg !== "qiskit"; + // `page` may include a nested folder, e.g. `generated/qiskit_pkg.Foo`. + // Kebab-case only the final segment so folder separators survive — + // kebabCase() itself would otherwise turn `generated/foo` into + // `generated-foo`. + const pageParts = page.split("/"); const kebabPage = targetUsesKebab - ? kebabCaseAndShortenPage(page, targetPkg) + ? [ + ...pageParts.slice(0, -1), + kebabCaseAndShortenPage(pageParts.at(-1)!, targetPkg), + ].join("/") : page; return `](${pythonApiBase}/${kebabPage}${anchor ?? ""})`; }, @@ -178,6 +186,16 @@ function rewriteApiDocsLinks(results: HtmlToMdResultWithUrl[], pkg: Pkg) { "g", ), `](${apiBase}/release-notes$1)`, + ) + // Addon API reference pages link back to guides with paths relative to + // the sphinx source tree (e.g. `../../guides/formalism#anchor`). + // Rewrite these to the guide's absolute path under docs/addons. + .replace( + /\]\((?:\.\.\/)*guides\/([^)#]+)(#[^)]+)?\)/g, + (match, page, anchor) => + pkg.isAddon() + ? `](${DOCS_BASE_PATH}/addons/${pkg.name}/guides/${page}${anchor ?? ""})` + : match, ); } } From c15bc4f39478f58dfeac6e2be800b5b0eebbbc95 Mon Sep 17 00:00:00 2001 From: Kaelyn Ferris <43348706+kaelynj@users.noreply.github.com> Date: Thu, 10 Sep 2026 13:40:25 -0400 Subject: [PATCH 12/15] Fix links in regenerated addons pages --- .../guides/formalism.mdx | 22 +++-- .../guides/noise-learner.mdx | 15 ++- .../qiskit-noise-learning/guides/workflow.mdx | 21 ++--- .../generated/models-log-fidelity-space.mdx | 2 +- .../generated/sequences-fidelity-index.mdx | 2 +- ...0665f8a0513450d76bfc5ab63e24f40c6b8f6.avif | Bin 105531 -> 515630 bytes .../config/historical-pages-to-latest.json | 86 +++++++++++++++++- 7 files changed, 118 insertions(+), 30 deletions(-) diff --git a/docs/addons/qiskit-noise-learning/guides/formalism.mdx b/docs/addons/qiskit-noise-learning/guides/formalism.mdx index 96a57b1a12d6..6b68a7c47e9a 100644 --- a/docs/addons/qiskit-noise-learning/guides/formalism.mdx +++ b/docs/addons/qiskit-noise-learning/guides/formalism.mdx @@ -52,7 +52,7 @@ This is a general class of operations that includes unitary Clifford gates, meas As outlined in [\[1\]](#references), [\[7\]](#references) for the no-reset case, if a specific twirling strategy is applied to a noisy instance of such a gate, then the action of the resulting operation can be modeled mathematically as a *uniform Pauli instrument*. That is, within the quantum instrument notation, $\mathcal{E}_m = \mathcal{U}_mG$, where $G$ is the Clifford unitary, and: $$ - \mathcal{U}_m = \sum_{a,b \in \mathbb{Z}_2^M} \Lambda_{a,b} \otimes | m + a \rangle\!\rangle \langle\!\langle m + b |, + \mathcal{U}_m = \sum_{a,b \in \mathbb{Z}_2^M} \Lambda_{a,b} \otimes | m + a \rangle\!\rangle\langle\!\langle m + b |, $$ where each $\Lambda_{a,b}$ is a sub-normalized Pauli channel on the unmeasured qubits $N = [K] \setminus M$. It is implied by this being a quantum instrument that $\sum_{a,b} \Lambda_{a,b}$ is also trace-preserving. Some notes: @@ -66,31 +66,39 @@ Note that we are not concerned here with the specifics of the twirling strategy: In Lemma 1 of [\[7\]](#references), it is shown that $\mathcal{E}_m = \mathcal{U}_mG$ can be rewritten as: + + $$ \mathcal{E}_m = \frac{1}{2^{2|M| + |N|}}\sum_{x, y \in \mathbb{Z}_2^M, Q \in \mathcal{P}^N} (-1)^{m \cdot (x + y)} -\lambda^Q_{x, y}| Q \otimes Z^y \rangle\!\rangle \langle\!\langle G^\dagger(Q \otimes Z^x) |. +\lambda^Q_{x, y}| Q \otimes Z^y \rangle\!\rangle\langle\!\langle G^\dagger(Q \otimes Z^x) |. $$ for some real numbers $\lambda_{x,y}^Q$, which are called the *fidelities* of the instrument. Adding reset to this picture is relatively straightforward. A noisy reset operation on qubits $R \subset [K]$ can be modeled according to the decomposition: + + $$ - \frac{1}{2^{|R|}}\sum_{r \in \mathbb{Z}_2^{R}} \lambda_r | Z^r \rangle\!\rangle \langle\!\langle I_R |. + \frac{1}{2^{|R|}}\sum_{r \in \mathbb{Z}_2^{R}} \lambda_r | Z^r \rangle\!\rangle\langle\!\langle I_R |. $$ The above form explicitly utilizes the assumption that the reset is along the $Z$-axis for each qubit. Noise in the operation is encoded in the reset fidelities $\lambda_r$, which are simply indexed by qubit subsets. An analog to Equation [(1)](#equation-clifford-mcm-form) that includes a reset operation at the end can be attained by simply composing it with Equation [(2)](#equation-reset-form). This composition, after some simplification, yields: + + $$ \begin{split} \frac{1}{2^{2|M|+|N|}} \sum_{\substack{x \in \mathbb{Z}_2^M, y \in \mathbb{Z}_2^{M \cup R} \\ Q \in \mathcal{P}^{N\setminus R}}} (-1)^{m \cdot (x + y|_M)} \lambda^Q_{x,y} | Q \otimes -Z^y \rangle\!\rangle \langle\!\langle G^\dagger(Q \otimes I_{N \cap R} \otimes Z^x) |. \end{split} +Z^y \rangle\!\rangle\langle\!\langle G^\dagger(Q \otimes I_{N \cap R} \otimes Z^x) |. \end{split} $$ This decomposition indicates that the number of fidelities $\lambda^Q_{x, y}$ is + + $$ 4^{|N \setminus R|} 2^{|M|}2^{|M \cup R|} = 4^{K}2^{|M|}2^{-|M \cup R|} = 4^K 2^{-|R \setminus M|}. $$ @@ -124,7 +132,7 @@ $$ In other words, if we compute the expectation value $Z^{x + y|_M}$ on the classical register output by the MCM, then the “Heisenberg picture” evolution of an observable through the Clifford-MCM-reset gate maps $Q \otimes Z^y \rightarrow Q \otimes I_{N \cap R} \otimes Z^x$. This fact alone enables recovery of PTG-like analysis beyond the unitary gate set case: with a particular post-processing of the measurement results, even gates with measurements and resets can be viewed as deterministically mapping one Pauli operator to another. -Before proving this, we write Equation [(3)](#equation-clifford-mcm-reset-form) in a more suggestive way. Note that for $x, y \in \mathbb{Z}_2^M$, it holds that $Z^{x+y} = \sum_{m \in \mathbb{Z}_2^M} (-1)^{m \cdot (x + y)} | m \rangle\langle m |$, and as such (in super operator notation) we have: +Before proving this, we write Equation [(3)](#equation-clifford-mcm-reset-form) in a more suggestive way. Note that for $x, y \in \mathbb{Z}_2^M$, it holds that $Z^{x+y} = \sum_{m \in \mathbb{Z}_2^M} (-1)^{m \cdot (x + y)}| m \rangle\langle m |$, and as such (in super operator notation) we have: $$ \begin{split} \begin{aligned} \sum_{m \in \mathbb{Z}_2^M} \mathcal{E}_m \otimes | m \rangle\!\rangle_M = \frac{1}{2^{2|M|+|N|}}\sum_{\substack{x \in @@ -141,13 +149,13 @@ $$ \begin{split} \begin{aligned} &\langle\!\langle Q \otimes Z^y | \otimes \langle\!\langle Z^{x + y|_M} | \left(\sum_{m\in \mathbb{Z}_2^M} \mathcal{E}_m \otimes | m \rangle\!\rangle\right)\\ -&= \langle\!\langle Q \otimes Z^y | \otimes \langle\!\langle Z^{x + y|_M} | \left( \frac{1}{2^{2|M|+|N|}} \sum_{\substack{a \in \mathbb{Z}_2^M, b \in \mathbb{Z}_2^{M \cup R} \\ P \in \mathcal{P}^{N\setminus R}}} \lambda^P_{a,b} | P \otimes Z^b \rangle\!\rangle \langle\!\langle G^\dagger(P \otimes I_{N \cap R} \otimes Z^a) | \otimes | Z^{a + b|_M} \rangle\!\rangle \right) \\ +&= \langle\!\langle Q \otimes Z^y | \otimes \langle\!\langle Z^{x + y|_M} | \left( \frac{1}{2^{2|M|+|N|}} \sum_{\substack{a \in \mathbb{Z}_2^M, b \in \mathbb{Z}_2^{M \cup R} \\ P \in \mathcal{P}^{N\setminus R}}} \lambda^P_{a,b} | P \otimes Z^b \rangle\!\rangle\langle\!\langle G^\dagger(P \otimes I_{N \cap R} \otimes Z^a) | \otimes | Z^{a + b|_M} \rangle\!\rangle \right) \\ &=\frac{1}{2^{2|M| + |N|}}\sum_{\substack{a \in \mathbb{Z}_2^M, b \in \mathbb{Z}_2^{M \cup R} \\ P \in \mathcal{P}^{N \setminus R}}} \lambda^P_{a, b}\underbrace{\langle Q \otimes Z^y, P \otimes Z^b \rangle}_{2^{|M| + |N|} \delta_{P, Q}\delta_{y,b}} \underbrace{\langle Z^{x + y|_M}, Z^{a + b|_M} \rangle}_{2^{|M|}\delta_{x+y|_M,a+b|_M}}\langle\!\langle G^\dagger(P \otimes I_{N \cap R} \otimes Z^a) | \end{aligned} \end{split} $$ - Lastly, observe that $\delta_{y,b}\delta_{x+y|_M,a+b|_M} = \delta_{y,b}\delta_{x,a}$, and hence the final term above collapses down to the single term $\lambda^Q_{x,y} \langle\!\langle G^\dagger(Q \otimes I_{N \cap R} \otimes Z^x) |$, yielding the desired result. + Lastly, observe that $\delta_{y,b}\delta_{x+y|_M,a+b|_M} = \delta_{y,b}\delta_{x,a}$, and hence the final term above collapses down to the single term $\lambda^Q_{x,y} \opbra{G^\dagger(Q \otimes I_{N \cap R} \otimes Z^x)}$, yielding the desired result. See [\[7\]](#references) for development beyond this point: the definition of the PTG, paths through the PTG, and the proof that any properly-defined path corresponds to an experiment. diff --git a/docs/addons/qiskit-noise-learning/guides/noise-learner.mdx b/docs/addons/qiskit-noise-learning/guides/noise-learner.mdx index 24e8e7edb794..f129e2427647 100644 --- a/docs/addons/qiskit-noise-learning/guides/noise-learner.mdx +++ b/docs/addons/qiskit-noise-learning/guides/noise-learner.mdx @@ -5,7 +5,7 @@ description: "Learn the noise model of a gate with NoiseLearner for the latest v # Learn the noise model of a gate with NoiseLearner -This guide demonstrates using [`NoiseLearner`](/docs/api/qiskit-noise-learning/generated-noise-learner-noise-learner#qiskit_noise_learning.noise_learner.NoiseLearner "qiskit_noise_learning.noise_learner.NoiseLearner") to learn a noise model for a unitary gate. +This guide demonstrates using [`NoiseLearner`](/docs/api/qiskit-noise-learning/generated/noise-learner-noise-learner#qiskit_noise_learning.noise_learner.NoiseLearner "qiskit_noise_learning.noise_learner.NoiseLearner") to learn a noise model for a unitary gate. 1. Define the gate 2. Set up local simulation @@ -52,7 +52,7 @@ with circuit.box([Twirl(), InjectNoise("cz_gate")]): ## 2. Set up local simulation -An [`AerExecutor`](/docs/api/qiskit-noise-learning/generated-aer-executor-aer-executor#qiskit_noise_learning.aer_executor.AerExecutor "qiskit_noise_learning.aer_executor.AerExecutor") runs a program on a local Aer simulator, injecting Pauli-Lindblad noise at the barriers Samplomatic places around each twirled gate. +An [`AerExecutor`](/docs/api/qiskit-noise-learning/generated/aer-executor-aer-executor#qiskit_noise_learning.aer_executor.AerExecutor "qiskit_noise_learning.aer_executor.AerExecutor") runs a program on a local Aer simulator, injecting Pauli-Lindblad noise at the barriers Samplomatic places around each twirled gate. The Pauli indices inside each map are local to the gate, in ascending physical-qubit order: @@ -98,7 +98,7 @@ spam_noise = PauliLindbladMap.from_sparse_list( noise_dict = {"cz_gate": cz_noise, "P": spam_noise, "M": spam_noise} ``` -Instantiate [`AerExecutor`](/docs/api/qiskit-noise-learning/generated-aer-executor-aer-executor#qiskit_noise_learning.aer_executor.AerExecutor "qiskit_noise_learning.aer_executor.AerExecutor") with the stabilizer method. Set `root_seed` to make the simulated data reproducible. +Instantiate [`AerExecutor`](/docs/api/qiskit-noise-learning/generated/aer-executor-aer-executor#qiskit_noise_learning.aer_executor.AerExecutor "qiskit_noise_learning.aer_executor.AerExecutor") with the stabilizer method. Set `root_seed` to make the simulated data reproducible. ```python from qiskit_aer import AerSimulator @@ -118,7 +118,7 @@ executor = AerExecutor( ## 3. Run the learner -[`LearningOptions`](/docs/api/qiskit-noise-learning/generated-noise-learner-learning-options#qiskit_noise_learning.noise_learner.LearningOptions "qiskit_noise_learning.noise_learner.LearningOptions") controls the shape of the experiment: how deep the twirled gate is repeated, and how many randomizations and shots are spent at each depth. Passing `executor` diverts the generated program to the simulator; leave it out and [`NoiseLearner`](/docs/api/qiskit-noise-learning/generated-noise-learner-noise-learner#qiskit_noise_learning.noise_learner.NoiseLearner "qiskit_noise_learning.noise_learner.NoiseLearner") submits to `backend` through IBM Quantum instead. +[`LearningOptions`](/docs/api/qiskit-noise-learning/generated/noise-learner-learning-options#qiskit_noise_learning.noise_learner.LearningOptions "qiskit_noise_learning.noise_learner.LearningOptions") controls the shape of the experiment: how deep the twirled gate is repeated, and how many randomizations and shots are spent at each depth. Passing `executor` diverts the generated program to the simulator; leave it out and [`NoiseLearner`](/docs/api/qiskit-noise-learning/generated/noise-learner-noise-learner#qiskit_noise_learning.noise_learner.NoiseLearner "qiskit_noise_learning.noise_learner.NoiseLearner") submits to `backend` through IBM Quantum instead. ```python from qiskit_noise_learning.noise_learner import LearningOptions, NoiseLearner @@ -145,7 +145,7 @@ result = job.result() ## 4. Read the results -Everything the analysis pipeline produced is reachable through [`fit`](/docs/api/qiskit-noise-learning/generated-noise-learner-noise-learner-result#qiskit_noise_learning.noise_learner.NoiseLearnerResult.fit "qiskit_noise_learning.noise_learner.NoiseLearnerResult.fit"). Use the fit to plot per-qubit-pair fidelity decays: both the data and the exponential fit. +Everything the analysis pipeline produced is reachable through [`fit`](/docs/api/qiskit-noise-learning/generated/noise-learner-noise-learner-result#qiskit_noise_learning.noise_learner.NoiseLearnerResult.fit "qiskit_noise_learning.noise_learner.NoiseLearnerResult.fit"). Use the fit to plot per-qubit-pair fidelity decays: both the data and the exponential fit. ```python result.fit.plot_qubit_pair_decays( @@ -155,7 +155,7 @@ result.fit.plot_qubit_pair_decays( ) ``` -Extract the learned noise from [`to_dict()`](/docs/api/qiskit-noise-learning/generated-noise-learner-noise-learner-result#qiskit_noise_learning.noise_learner.NoiseLearnerResult.to_dict "qiskit_noise_learning.noise_learner.NoiseLearnerResult.to_dict"): one [`PauliLindbladMap`](/docs/api/qiskit/qiskit.quantum_info.PauliLindbladMap) per learned gate, keyed by the name from the `InjectNoise` annotation, and expressed in the backend’s own qubit indexing rather than that of the gate. +Extract the learned noise from [`to_dict()`](/docs/api/qiskit-noise-learning/generated/noise-learner-noise-learner-result#qiskit_noise_learning.noise_learner.NoiseLearnerResult.to_dict "qiskit_noise_learning.noise_learner.NoiseLearnerResult.to_dict"): one [`PauliLindbladMap`](/docs/api/qiskit/qiskit.quantum_info.PauliLindbladMap) per learned gate, keyed by the name from the `InjectNoise` annotation, and expressed in the backend’s own qubit indexing rather than that of the gate. ```python learned = result.to_dict()["cz_gate"] @@ -166,5 +166,4 @@ learned.num_terms 144 ``` -By default [`NoiseLearner`](/docs/api/qiskit-noise-learning/generated-noise-learner-noise-learner#qiskit_noise_learning.noise_learner.NoiseLearner "qiskit_noise_learning.noise_learner.NoiseLearner") fits a 2-local model, so the map carries a term for every Pauli supported on a connected pair of the gate’s qubits — 144 of them, of which only 24 were given a nonzero rate in step 2. - +By default [`NoiseLearner`](/docs/api/qiskit-noise-learning/generated/noise-learner-noise-learner#qiskit_noise_learning.noise_learner.NoiseLearner "qiskit_noise_learning.noise_learner.NoiseLearner") fits a 2-local model, so the map carries a term for every Pauli supported on a connected pair of the gate’s qubits — 144 of them, of which only 24 were given a nonzero rate in step 2. diff --git a/docs/addons/qiskit-noise-learning/guides/workflow.mdx b/docs/addons/qiskit-noise-learning/guides/workflow.mdx index b33a3377dc5a..4966dd3d9e63 100644 --- a/docs/addons/qiskit-noise-learning/guides/workflow.mdx +++ b/docs/addons/qiskit-noise-learning/guides/workflow.mdx @@ -27,7 +27,7 @@ This guide demonstrates how to build a standard learning experiment from scratch ## 1. Define a gate set on a ring of qubits -Build a [`QiskitGateSet`](/docs/api/qiskit-noise-learning/generated-gate-sets-qiskit-gate-set#qiskit_noise_learning.gate_sets.QiskitGateSet "qiskit_noise_learning.gate_sets.QiskitGateSet") from a backend [`Target`](/docs/api/qiskit/qiskit.transpiler.Target) and a subset of its qubits — here a twelve-qubit ring of [`FakeMarrakesh`](/docs/api/qiskit-ibm-runtime/fake-provider-fake-marrakesh "(in Qiskit Runtime IBM Client)") — then add one gate to it: a layer of six `CZ` gates covering that ring. By default the gate set is initialized with a preparation gate `P` and a measurement gate `M`. +Build a [`QiskitGateSet`](/docs/api/qiskit-noise-learning/generated/gate-sets-qiskit-gate-set#qiskit_noise_learning.gate_sets.QiskitGateSet "qiskit_noise_learning.gate_sets.QiskitGateSet") from a backend [`Target`](/docs/api/qiskit/qiskit.transpiler.Target) and a subset of its qubits — here a twelve-qubit ring of [`FakeMarrakesh`](/docs/api/qiskit-ibm-runtime/fake-provider-fake-marrakesh "(in Qiskit Runtime IBM Client)") — then add one gate to it: a layer of six `CZ` gates covering that ring. By default the gate set is initialized with a preparation gate `P` and a measurement gate `M`. ```python from qiskit_ibm_runtime.fake_provider import FakeMarrakesh @@ -60,7 +60,7 @@ list(gate_set) ``` -Call [`draw()`](/docs/api/qiskit-noise-learning/generated-gate-sets-gate-set#qiskit_noise_learning.gate_sets.GateSet.draw "qiskit_noise_learning.gate_sets.GateSet.draw") to see the gate on the device topology: the ring of qubits in the gate set, and which pairs of them the gate entangles. +Call [`draw()`](/docs/api/qiskit-noise-learning/generated/gate-sets-gate-set#qiskit_noise_learning.gate_sets.GateSet.draw "qiskit_noise_learning.gate_sets.GateSet.draw") to see the gate on the device topology: the ring of qubits in the gate set, and which pairs of them the gate entangles. ```python gate_set.draw() @@ -70,7 +70,7 @@ gate_set.draw() ## 2. Choose a 2-local Pauli-Lindblad model -Decide which Pauli-Lindblad generators the noise is allowed to have with a [`PauliLindbladModel`](/docs/api/qiskit-noise-learning/generated-models-pauli-lindblad-model#qiskit_noise_learning.models.PauliLindbladModel "qiskit_noise_learning.models.PauliLindbladModel"). Build that generator set from the gate set’s connectivity with [`k_local()`](/docs/api/qiskit-noise-learning/generated-models-pauli-lindblad-model#qiskit_noise_learning.models.PauliLindbladModel.k_local "qiskit_noise_learning.models.PauliLindbladModel.k_local") — here every 2-local Pauli on connected qubit pairs of the unitary gate, and single-qubit Paulis for preparation and measurement. +Decide which Pauli-Lindblad generators the noise is allowed to have with a [`PauliLindbladModel`](/docs/api/qiskit-noise-learning/generated/models-pauli-lindblad-model#qiskit_noise_learning.models.PauliLindbladModel "qiskit_noise_learning.models.PauliLindbladModel"). Build that generator set from the gate set’s connectivity with [`k_local()`](/docs/api/qiskit-noise-learning/generated/models-pauli-lindblad-model#qiskit_noise_learning.models.PauliLindbladModel.k_local "qiskit_noise_learning.models.PauliLindbladModel.k_local") — here every 2-local Pauli on connected qubit pairs of the unitary gate, and single-qubit Paulis for preparation and measurement. ```python from qiskit_noise_learning.models import PauliLindbladModel @@ -92,7 +92,7 @@ Display the unknown parameter count for the noise model of each gate. ## 3. Build the learning experiment -Assemble an [`Experiment`](/docs/api/qiskit-noise-learning/generated-experiment-builder-experiment#qiskit_noise_learning.experiment_builder.Experiment "qiskit_noise_learning.experiment_builder.Experiment") by composing builder stages. Each stage reads what earlier stages wrote, so order matters: +Assemble an [`Experiment`](/docs/api/qiskit-noise-learning/generated/experiment-builder-experiment#qiskit_noise_learning.experiment_builder.Experiment "qiskit_noise_learning.experiment_builder.Experiment") by composing builder stages. Each stage reads what earlier stages wrote, so order matters: ```python from qiskit_noise_learning.experiment_builder import ( @@ -148,7 +148,7 @@ Design matrix rank: 120 ## 4. Generate circuits -Compile the experiment with an [`ExecutorCircuitGenerator`](/docs/api/qiskit-noise-learning/generated-circuit-generator-executor-circuit-generator#qiskit_noise_learning.circuit_generator.ExecutorCircuitGenerator "qiskit_noise_learning.circuit_generator.ExecutorCircuitGenerator"), generating a [`QuantumProgram`](/docs/api/qiskit-ibm-runtime/quantum-program-quantum-program "(in Qiskit Runtime IBM Client)") — one parameterized template circuit per fragment depth — together with a data mapper that records how to interpret results. +Compile the experiment with an [`ExecutorCircuitGenerator`](/docs/api/qiskit-noise-learning/generated/circuit-generator-executor-circuit-generator#qiskit_noise_learning.circuit_generator.ExecutorCircuitGenerator "qiskit_noise_learning.circuit_generator.ExecutorCircuitGenerator"), generating a [`QuantumProgram`](/docs/api/qiskit-ibm-runtime/quantum-program-quantum-program "(in Qiskit Runtime IBM Client)") — one parameterized template circuit per fragment depth — together with a data mapper that records how to interpret results. ```python from qiskit_noise_learning.circuit_generator import ExecutorCircuitGenerator @@ -175,9 +175,9 @@ quantum_program.items[0].circuit.draw("mpl", idle_wires=False, fold=False) ## 5. Set up local simulation -An [`AerExecutor`](/docs/api/qiskit-noise-learning/generated-aer-executor-aer-executor#qiskit_noise_learning.aer_executor.AerExecutor "qiskit_noise_learning.aer_executor.AerExecutor") runs a program on a local Aer simulator, injecting Pauli-Lindblad noise at the barriers Samplomatic places around each twirled gate. +An [`AerExecutor`](/docs/api/qiskit-noise-learning/generated/aer-executor-aer-executor#qiskit_noise_learning.aer_executor.AerExecutor "qiskit_noise_learning.aer_executor.AerExecutor") runs a program on a local Aer simulator, injecting Pauli-Lindblad noise at the barriers Samplomatic places around each twirled gate. -Unlike the hand-picked noise of the [`NoiseLearner`](/docs/api/qiskit-noise-learning/generated-noise-learner-noise-learner#qiskit_noise_learning.noise_learner.NoiseLearner "qiskit_noise_learning.noise_learner.NoiseLearner") guide, give *every one* of the model’s 168 generators an independent random rate. The model’s generators are already exactly the Paulis to put in a [`PauliLindbladMap`](/docs/api/qiskit/qiskit.quantum_info.PauliLindbladMap), so pair each one with a rate and build the map per gate directly: +Unlike the hand-picked noise of the [`NoiseLearner`](/docs/api/qiskit-noise-learning/generated/noise-learner-noise-learner#qiskit_noise_learning.noise_learner.NoiseLearner "qiskit_noise_learning.noise_learner.NoiseLearner") guide, give *every one* of the model’s 168 generators an independent random rate. The model’s generators are already exactly the Paulis to put in a [`PauliLindbladMap`](/docs/api/qiskit/qiskit.quantum_info.PauliLindbladMap), so pair each one with a rate and build the map per gate directly: ```python import numpy as np @@ -201,7 +201,7 @@ true_maps = { {'M': 156, 'P': 156, 'cz_gate': 156} ``` -Those maps are as wide as the device, since the model is expressed in `backend`’s qubit indexing, but [`AerExecutor`](/docs/api/qiskit-noise-learning/generated-aer-executor-aer-executor#qiskit_noise_learning.aer_executor.AerExecutor "qiskit_noise_learning.aer_executor.AerExecutor") wants each map to be as wide as the gate it applies to, with Pauli indices running over the gate’s qubits in ascending physical order. Narrow them with [`keep_qubits()`](/docs/api/qiskit/qiskit.quantum_info.PauliLindbladMap#keep_qubits), which traces out everything off the ring: +Those maps are as wide as the device, since the model is expressed in `backend`’s qubit indexing, but [`AerExecutor`](/docs/api/qiskit-noise-learning/generated/aer-executor-aer-executor#qiskit_noise_learning.aer_executor.AerExecutor "qiskit_noise_learning.aer_executor.AerExecutor") wants each map to be as wide as the gate it applies to, with Pauli indices running over the gate’s qubits in ascending physical order. Narrow them with [`keep_qubits()`](/docs/api/qiskit/qiskit.quantum_info.PauliLindbladMap#keep_qubits), which traces out everything off the ring: ```python noise_dict = { @@ -214,7 +214,7 @@ noise_dict = { {'M': 12, 'P': 12, 'cz_gate': 12} ``` -Instantiate [`AerExecutor`](/docs/api/qiskit-noise-learning/generated-aer-executor-aer-executor#qiskit_noise_learning.aer_executor.AerExecutor "qiskit_noise_learning.aer_executor.AerExecutor") with the stabilizer method. Set `root_seed` to make the simulated data reproducible. +Instantiate [`AerExecutor`](/docs/api/qiskit-noise-learning/generated/aer-executor-aer-executor#qiskit_noise_learning.aer_executor.AerExecutor "qiskit_noise_learning.aer_executor.AerExecutor") with the stabilizer method. Set `root_seed` to make the simulated data reproducible. ```python from qiskit_aer import AerSimulator @@ -234,7 +234,7 @@ executor = AerExecutor( ## 6. Run the program -Run the program, then pair the returned bitstrings with the data mapper using [`collect()`](/docs/api/qiskit-noise-learning/generated-circuit-generator-executor-circuit-generator#qiskit_noise_learning.circuit_generator.ExecutorCircuitGenerator.collect "qiskit_noise_learning.circuit_generator.ExecutorCircuitGenerator.collect"), which produces a [`Fit`](/docs/api/qiskit-noise-learning/generated-analysis-fit#qiskit_noise_learning.analysis.Fit "qiskit_noise_learning.analysis.Fit") — the container the analysis stages read from and write to. +Run the program, then pair the returned bitstrings with the data mapper using [`collect()`](/docs/api/qiskit-noise-learning/generated/circuit-generator-executor-circuit-generator#qiskit_noise_learning.circuit_generator.ExecutorCircuitGenerator.collect "qiskit_noise_learning.circuit_generator.ExecutorCircuitGenerator.collect"), which produces a [`Fit`](/docs/api/qiskit-noise-learning/generated/analysis-fit#qiskit_noise_learning.analysis.Fit "qiskit_noise_learning.analysis.Fit") — the container the analysis stages read from and write to. ```python job = executor.run(quantum_program) @@ -291,4 +291,3 @@ fit.plot_qubit_pair_decays( model_prediction=True, ) ``` - diff --git a/docs/api/qiskit-noise-learning/generated/models-log-fidelity-space.mdx b/docs/api/qiskit-noise-learning/generated/models-log-fidelity-space.mdx index 9974d38b98b2..e62ff270a4ed 100644 --- a/docs/api/qiskit-noise-learning/generated/models-log-fidelity-space.mdx +++ b/docs/api/qiskit-noise-learning/generated/models-log-fidelity-space.mdx @@ -53,7 +53,7 @@ python_api_name: qiskit_noise_learning.models.LogFidelitySpace The total number of fidelities of the gate set, excluding the trivial identity ones. - Each gate contributes the count given by Equation [(4)](guides/formalism#equation-num-fidelities) of the [mathematical formalism](guides/formalism), less one. + Each gate contributes the count given by Equation [(4)](/docs/addons/qiskit-noise-learning/guides/formalism#equation-num-fidelities) of the [mathematical formalism](/docs/addons/qiskit-noise-learning/guides/formalism), less one. diff --git a/docs/api/qiskit-noise-learning/generated/sequences-fidelity-index.mdx b/docs/api/qiskit-noise-learning/generated/sequences-fidelity-index.mdx index 74facca3d006..6acd5871546e 100644 --- a/docs/api/qiskit-noise-learning/generated/sequences-fidelity-index.mdx +++ b/docs/api/qiskit-noise-learning/generated/sequences-fidelity-index.mdx @@ -18,7 +18,7 @@ description: Index of all the modules in the latest version of qiskit-noise-lear * A $Z$-type operator $Z^x$ on the measured qubits, $x \in Z_2^M$, and * A $Z$-type operator $Z^y$ on the measured and reset qubits, $y \in Z_2^{M \cup R}$. - This list constitutes the “index data” for a generalized fidelity for a given gate, in the sense that there is a bijection between all generalized fidelities and the above set of all objects satisfying the above description. See Equation [(3)](guides/formalism#equation-clifford-mcm-reset-form) of the [mathematical formalism](guides/formalism) for the decomposition in which these appear. + This list constitutes the “index data” for a generalized fidelity for a given gate, in the sense that there is a bijection between all generalized fidelities and the above set of all objects satisfying the above description. See Equation [(3)](/docs/addons/qiskit-noise-learning/guides/formalism#equation-clifford-mcm-reset-form) of the [mathematical formalism](/docs/addons/qiskit-noise-learning/guides/formalism) for the decomposition in which these appear. The exponents $x$ and $y$ are stored as the sets of qubit indices on which they are non-zero, namely [`in_z_idxs`](#qiskit_noise_learning.sequences.FidelityIndex.in_z_idxs "qiskit_noise_learning.sequences.FidelityIndex.in_z_idxs") and [`out_z_idxs`](#qiskit_noise_learning.sequences.FidelityIndex.out_z_idxs "qiskit_noise_learning.sequences.FidelityIndex.out_z_idxs") – equivalently, the qubits on which $Z^x$ and $Z^y$ act non-trivially. diff --git a/public/docs/images/addons/qiskit-noise-learning/cbfeb7989573772757ac81e9b3a0665f8a0513450d76bfc5ab63e24f40c6b8f6.avif b/public/docs/images/addons/qiskit-noise-learning/cbfeb7989573772757ac81e9b3a0665f8a0513450d76bfc5ab63e24f40c6b8f6.avif index 8075ff8a30fcc6c1e50bb42d85466d21930edc69..a366873d0c331626c071c8541cd41f430c1b11c9 100644 GIT binary patch literal 515630 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%0D7YLm7jZYAOTG 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

Bi9(9*}W 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%0D#+t=KjW#N5IO|u-7yUw9t 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%0ANGJr=4TBP>KriY_ajJB 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

1*&O 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

e%Q8q?N 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

yYL4A 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 Fjlf+~Jn#Sj diff --git a/scripts/config/historical-pages-to-latest.json b/scripts/config/historical-pages-to-latest.json index 0833ae92bf0a..d281ef8001df 100644 --- a/scripts/config/historical-pages-to-latest.json +++ b/scripts/config/historical-pages-to-latest.json @@ -1543,7 +1543,6 @@ "0.17": {} }, "qiskit-c": { - "1.4": {}, "2.0": {}, "2.1": {}, "2.2": { @@ -1589,5 +1588,88 @@ "qiskit-fermions-c": {}, "pauli-prop": {}, "qiskit-addon-slc": {}, - "qiskit-noise-learning": {} + "qiskit-noise-learning": { + "generated": { + "aer-executor-aer-executor": "/", + "aer-executor-aer-runtime-job": "/", + "aer-executor-inline-samplexes": "/", + "analysis-analysis-pipeline": "/", + "analysis-analysis-stage": "/", + "analysis-average-observables": "/", + "analysis-compute-observables": "/", + "analysis-curve-fit-observables": "/", + "analysis-fit": "/", + "analysis-flip-post-select": "/", + "analysis-legacy-solve": "/", + "analysis-linear-system-data": "/", + "analysis-lsq-linear-solve": "/", + "analysis-nnls-solve": "/", + "analysis-positivity-min-solve": "/", + "analysis-symmetrize-fidelities": "/", + "analysis-symmetrize-generators": "/", + "analysis-zero-post-select": "/", + "circuit-generator-executor-circuit-generator": "/", + "circuit-generator-executor-data-mapper": "/", + "data-aggregated-observable-data": "/", + "data-leveled-data": "/", + "data-model-data": "/", + "data-observable-data": "/", + "data-raw-data": "/", + "experiment-builder-add-instruction-sequences": "/", + "experiment-builder-add-paths": "/", + "experiment-builder-bind-fragment-depths": "/", + "experiment-builder-complete-sequences": "/", + "experiment-builder-depth-1-paths": "/", + "experiment-builder-even-depth-paths": "/", + "experiment-builder-even-depth-vanilla-paths": "/", + "experiment-builder-experiment-builder-stage": "/", + "experiment-builder-experiment-builder": "/", + "experiment-builder-experiment": "/", + "experiment-builder-generate-instruction-sequences": "/", + "experiment-builder-identify-relations": "/", + "experiment-builder-merge-instruction-sequences": "/", + "experiment-builder-rank-reduce-paths": "/", + "experiment-builder-spam-paths": "/", + "experiment-builder-vanilla-instruction-sequences": "/", + "gate-sets-gate-set": "/", + "gate-sets-gate": "/", + "gate-sets-model-gate-set": "/", + "gate-sets-model-gate": "/", + "gate-sets-qiskit-gate-set": "/", + "gate-sets-qiskit-gate": "/", + "math-composed-linear-map": "/", + "math-enumerated-indexed-space": "/", + "math-indexed-matrix": "/", + "math-indexed-space": "/", + "math-indexed-vector": "/", + "math-linear-map": "/", + "models-contains-pauli-lindblad-model": "/", + "models-generator-index": "/", + "models-get-noise-site": "/", + "models-identity-fidelity-model": "/", + "models-is-fidelity-model": "/", + "models-log-fidelity-space": "/", + "models-pauli-lindblad-model": "/", + "models-pauli-lindblad-split": "/", + "models-rate-space": "/", + "models-split-pauli-lindblad-model": "/", + "noise-learner-learning-options": "/", + "noise-learner-noise-learner-job": "/", + "noise-learner-noise-learner-result": "/", + "noise-learner-noise-learner": "/", + "noise-learner-program-executor": "/", + "noise-learner-program-job": "/", + "sequences-apply-gate": "/", + "sequences-fidelity-index": "/", + "sequences-group-mergeable-instruction-sequences": "/", + "sequences-instruction-sequence": "/", + "sequences-log-path-map": "/", + "sequences-log-path-space": "/", + "sequences-partial-pauli-permutation": "/", + "sequences-path": "/", + "visualizations-fidelity-index-math-label": "/", + "visualizations-gate-set-topology": "/", + "visualizations-path-math-label": "/" + } + } } From f76f8e1fd1048653452be999b35f54b6c3e48896 Mon Sep 17 00:00:00 2001 From: Kaelyn Ferris <43348706+kaelynj@users.noreply.github.com> Date: Thu, 10 Sep 2026 13:44:30 -0400 Subject: [PATCH 13/15] Run prettier on typescript changes --- scripts/js/lib/api/apiDocsPipeline.ts | 7 ++++++- scripts/js/lib/api/htmlToMd.ts | 3 ++- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/scripts/js/lib/api/apiDocsPipeline.ts b/scripts/js/lib/api/apiDocsPipeline.ts index 8b5c26aee11a..4ac6a827acd7 100644 --- a/scripts/js/lib/api/apiDocsPipeline.ts +++ b/scripts/js/lib/api/apiDocsPipeline.ts @@ -86,7 +86,12 @@ async function determineFilePaths( const extraFiles = pkg.isCApi() ? [`${C_API_BASE_PATH}/**.html`, "apidocs/**/**.html"] - : ["apidocs/**/**.html", "apidoc/**/**.html", "stubs/**/**.html", "pydoc/**/**.html"]; + : [ + "apidocs/**/**.html", + "apidoc/**/**.html", + "stubs/**/**.html", + "pydoc/**/**.html", + ]; const files = await globby( [...extraFiles, "release_notes.html", "release-notes.html"], { diff --git a/scripts/js/lib/api/htmlToMd.ts b/scripts/js/lib/api/htmlToMd.ts index 25b1e2d27fbf..47efc19a19e2 100644 --- a/scripts/js/lib/api/htmlToMd.ts +++ b/scripts/js/lib/api/htmlToMd.ts @@ -141,7 +141,8 @@ function prepareHandlers(meta: Metadata): Record { // (e.g. `id="equation-foo"`), which is otherwise dropped by the default // div handler since it isn't a `section`. return node.properties.id && - (nodeClasses.includes("section") || nodeClasses.includes("math-wrapper")) + (nodeClasses.includes("section") || + nodeClasses.includes("math-wrapper")) ? [buildSpanId(node.properties.id), ...all(h, node)] : defaultHandlers.div(h, node); }, From 5cdfb4d00c1c48b2c40ea3d8770effeb40780d01 Mon Sep 17 00:00:00 2001 From: Kaelyn Ferris <43348706+kaelynj@users.noreply.github.com> Date: Fri, 11 Sep 2026 11:17:19 -0400 Subject: [PATCH 14/15] Add noise learning to addons page --- docs/guides/addons.mdx | 26 ++++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/docs/guides/addons.mdx b/docs/guides/addons.mdx index 7bd38794af9a..79afeb23e344 100644 --- a/docs/guides/addons.mdx +++ b/docs/guides/addons.mdx @@ -68,15 +68,15 @@ These capabilities are useful for reducing circuit depth and typically come with /> -## Manage noise for expectation value estimation -Use the following addons to manage noise when building quantum workloads that estimate expectation values of observables. +## Noise learning +Use the following tools for learning and refining noise models as part of your error mitigation strategy +## Manage noise for expectation value estimation +Use the following addons to manage noise when building quantum workloads that estimate expectation values of observables. + + + + + + ## Manage noise for sampling results These techniques are useful for managing noise on sampling results. From 103b2251403f28a623c13123944e5dff82fa5e5a Mon Sep 17 00:00:00 2001 From: Kaelyn Ferris <43348706+kaelynj@users.noreply.github.com> Date: Fri, 11 Sep 2026 14:34:16 -0400 Subject: [PATCH 15/15] Change section title --- docs/guides/addons.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/addons.mdx b/docs/guides/addons.mdx index 79afeb23e344..e3623129f2a0 100644 --- a/docs/guides/addons.mdx +++ b/docs/guides/addons.mdx @@ -68,7 +68,7 @@ These capabilities are useful for reducing circuit depth and typically come with /> -## Noise learning +## Learn noise models Use the following tools for learning and refining noise models as part of your error mitigation strategy