Frontend/Backend docs clean up (#2124)

* remove/simplify broken directives * add short summary ahead of details * avoid using `ref` role when not needed the `doc` role is more suited for the purposes here of linking to pages. If one wishes to link to a specific section, the `ref` role would be the way to go. Here we were mostly only using `ref` superficially to link to headers. If that's the case linking to the document itself makes most sense. * ensure all docs have correct jupytext metadata this ensures proper format when using `jupytext` to convert between markdown and notebook formats (e.g. ipynb)
unitaryfund · Dec 14, 2023 · 6b21429 · 6b21429
1 parent c618688
commit 6b21429
Show file tree

Hide file tree

Showing 54 changed files with 72 additions and 79 deletions.
diff --git a/docs/source/examples/cirq-ibmq-backends.md b/docs/source/examples/cirq-ibmq-backends.md
@@ -1,7 +1,7 @@
 ---
 jupytext:
   text_representation:
-    extension: .myst
+    extension: .md
     format_name: myst
     format_version: 0.13
     jupytext_version: 1.11.1
@@ -39,7 +39,6 @@ USE_REAL_HARDWARE = False
 
 **Note:** When `USE_REAL_HARDWARE` is set to `False`, a classically simulated noisy backend is used instead of a real quantum computer.
 
-(examples/cirq-ibmq-backends/setup-defining-a-circuit)=
 ## Setup: Defining a circuit in Cirq
 
 +++
@@ -70,7 +69,7 @@ the expectation value to mitigate. This function will:
 2. Run the circuit.
 3. Convert from raw measurement statistics (or a different output format) to an expectation value.
 
-For information on how to define more advanced executors, see the {ref}`Executors <guide/executors/executors>` section of the Mitiq user guide.
+For information on how to define more advanced executors, see the {doc}`../guide/executors` section of the Mitiq user guide.
 
 We define the executor function in the following code block. Because we are using IBMQ backends, we first load our account.
 

diff --git a/docs/source/examples/ddd_tutorial.md b/docs/source/examples/ddd_tutorial.md
@@ -1,7 +1,7 @@
 ---
 jupytext:
   text_representation:
-    extension: .myst
+    extension: .md
     format_name: myst
     format_version: 0.13
     jupytext_version: 1.11.1

diff --git a/docs/source/examples/ggi_summer_school_solved.md b/docs/source/examples/ggi_summer_school_solved.md
@@ -3,7 +3,7 @@ orphan: true
 
 jupytext:
   text_representation:
-    extension: .myst
+    extension: .md
     format_name: myst
     format_version: 0.13
     jupytext_version: 1.12.0

diff --git a/docs/source/examples/ggi_summer_school_unsolved.md b/docs/source/examples/ggi_summer_school_unsolved.md
@@ -1,7 +1,7 @@
 ---
 jupytext:
   text_representation:
-    extension: .myst
+    extension: .md
     format_name: myst
     format_version: 0.13
     jupytext_version: 1.12.0

diff --git a/docs/source/examples/hamiltonians.md b/docs/source/examples/hamiltonians.md
@@ -1,7 +1,7 @@
 ---
 jupytext:
   text_representation:
-    extension: .myst
+    extension: .md
     format_name: myst
     format_version: 0.13
     jupytext_version: 1.11.4

diff --git a/docs/source/examples/ibmq-backends.md b/docs/source/examples/ibmq-backends.md
@@ -1,7 +1,7 @@
 ---
 jupytext:
   text_representation:
-    extension: .myst
+    extension: .md
     format_name: myst
     format_version: 0.13
     jupytext_version: 1.11.1
@@ -43,7 +43,6 @@ from mitiq.interface.mitiq_qiskit.qiskit_utils import initialized_depolarizing_n
 USE_REAL_HARDWARE = False
 ```
 
-(examples/ibmq-backends/setup-defining-a-circuit)=
 ## Setup: Defining a circuit
 
 +++

diff --git a/docs/source/examples/learning-depolarizing-noise.md b/docs/source/examples/learning-depolarizing-noise.md
@@ -1,7 +1,7 @@
 ---
 jupytext:
   text_representation:
-    extension: .myst
+    extension: .md
     format_name: myst
     format_version: 0.13
     jupytext_version: 1.14.1

diff --git a/docs/source/examples/maxcut-demo.md b/docs/source/examples/maxcut-demo.md
@@ -1,7 +1,7 @@
 ---
 jupytext:
   text_representation:
-    extension: .myst
+    extension: .md
     format_name: myst
     format_version: 0.13
     jupytext_version: 1.11.4

diff --git a/docs/source/examples/molecular_hydrogen.md b/docs/source/examples/molecular_hydrogen.md
@@ -1,7 +1,7 @@
 ---
 jupytext:
   text_representation:
-    extension: .myst
+    extension: .md
     format_name: myst
     format_version: 0.13
     jupytext_version: 1.11.1

diff --git a/docs/source/examples/pec_tutorial.md b/docs/source/examples/pec_tutorial.md
@@ -1,7 +1,7 @@
 ---
 jupytext:
   text_representation:
-    extension: .myst
+    extension: .md
     format_name: myst
     format_version: 0.13
     jupytext_version: 1.12.0

diff --git a/docs/source/examples/pennylane-ibmq-backends.md b/docs/source/examples/pennylane-ibmq-backends.md
@@ -1,7 +1,7 @@
 ---
 jupytext:
   text_representation:
-    extension: .myst
+    extension: .md
     format_name: myst
     format_version: 0.13
     jupytext_version: 1.11.1
@@ -23,8 +23,6 @@ In this tutorial we will cover how to use Mitiq in conjunction with [PennyLane](
 
 +++
 
-(examples/ibmq-backends-pennylane/setup-defining-a-circuit)=
-
 ## Setup: Defining a circuit
 
 +++

diff --git a/docs/source/examples/rshadows_tutorial.md b/docs/source/examples/rshadows_tutorial.md
@@ -1,7 +1,7 @@
 ---
 jupytext:
   text_representation:
-    extension: .myst
+    extension: .md
     format_name: myst
     format_version: 0.13
     jupytext_version: 1.11.1

diff --git a/docs/source/examples/shadows_tutorial.md b/docs/source/examples/shadows_tutorial.md
@@ -1,7 +1,7 @@
 ---
 jupytext:
   text_representation:
-    extension: .myst
+    extension: .md
     format_name: myst
     format_version: 0.13
     jupytext_version: 1.11.1

diff --git a/docs/source/examples/simple-landscape-cirq.md b/docs/source/examples/simple-landscape-cirq.md
@@ -1,7 +1,7 @@
 ---
 jupytext:
   text_representation:
-    extension: .myst
+    extension: .md
     format_name: myst
     format_version: 0.13
     jupytext_version: 1.11.4

diff --git a/docs/source/examples/simple-landscape-pennylane.md b/docs/source/examples/simple-landscape-pennylane.md
@@ -2,7 +2,7 @@
 jupytext:
   formats: md:myst,ipynb
   text_representation:
-    extension: .myst
+    extension: .md
     format_name: myst
     format_version: 0.13
     jupytext_version: 1.23.4

diff --git a/docs/source/examples/simple-landscape-qiskit.md b/docs/source/examples/simple-landscape-qiskit.md
@@ -2,7 +2,7 @@
 jupytext:
   formats: md:myst,ipynb
   text_representation:
-    extension: .myst
+    extension: .md
     format_name: myst
     format_version: 0.13
     jupytext_version: 1.11.1

diff --git a/docs/source/examples/zne-braket-ionq.md b/docs/source/examples/zne-braket-ionq.md
@@ -1,7 +1,7 @@
 ---
 jupytext:
   text_representation:
-    extension: .myst
+    extension: .md
     format_name: myst
     format_version: 0.13
     jupytext_version: 1.11.1

diff --git a/docs/source/guide/cdr-1-intro.md b/docs/source/guide/cdr-1-intro.md
@@ -1,7 +1,7 @@
 ---
 jupytext:
   text_representation:
-    extension: .myst
+    extension: .md
     format_name: myst
     format_version: 0.13
     jupytext_version: 1.11.1

diff --git a/docs/source/guide/cdr-2-use-case.md b/docs/source/guide/cdr-2-use-case.md
@@ -1,7 +1,7 @@
 ---
 jupytext:
   text_representation:
-    extension: .myst
+    extension: .md
     format_name: myst
     format_version: 0.13
     jupytext_version: 1.11.1

diff --git a/docs/source/guide/cdr-3-options.md b/docs/source/guide/cdr-3-options.md
@@ -1,7 +1,7 @@
 ---
 jupytext:
   text_representation:
-    extension: .myst
+    extension: .md
     format_name: myst
     format_version: 0.13
     jupytext_version: 1.11.1

diff --git a/docs/source/guide/cdr-4-low-level.md b/docs/source/guide/cdr-4-low-level.md
@@ -1,7 +1,7 @@
 ---
 jupytext:
   text_representation:
-    extension: .myst
+    extension: .md
     format_name: myst
     format_version: 0.13
     jupytext_version: 1.11.1

diff --git a/docs/source/guide/cdr-5-theory.md b/docs/source/guide/cdr-5-theory.md
@@ -1,7 +1,7 @@
 ---
 jupytext:
   text_representation:
-    extension: .myst
+    extension: .md
     format_name: myst
     format_version: 0.13
     jupytext_version: 1.11.1

diff --git a/docs/source/guide/ddd-1-intro.md b/docs/source/guide/ddd-1-intro.md
@@ -1,7 +1,7 @@
 ---
 jupytext:
   text_representation:
-    extension: .myst
+    extension: .md
     format_name: myst
     format_version: 0.13
     jupytext_version: 1.11.1

diff --git a/docs/source/guide/ddd-2-use-case.md b/docs/source/guide/ddd-2-use-case.md
@@ -1,7 +1,7 @@
 ---
 jupytext:
   text_representation:
-    extension: .myst
+    extension: .md
     format_name: myst
     format_version: 0.13
     jupytext_version: 1.10.3

diff --git a/docs/source/guide/ddd-3-options.md b/docs/source/guide/ddd-3-options.md
@@ -1,7 +1,7 @@
 ---
 jupytext:
   text_representation:
-    extension: .myst
+    extension: .md
     format_name: myst
     format_version: 0.13
     jupytext_version: 1.11.1

diff --git a/docs/source/guide/ddd-4-low-level.md b/docs/source/guide/ddd-4-low-level.md
@@ -1,7 +1,7 @@
 ---
 jupytext:
   text_representation:
-    extension: .myst
+    extension: .md
     format_name: myst
     format_version: 0.13
     jupytext_version: 1.11.1

diff --git a/docs/source/guide/ddd-5-theory.md b/docs/source/guide/ddd-5-theory.md
@@ -1,7 +1,7 @@
 ---
 jupytext:
   text_representation:
-    extension: .myst
+    extension: .md
     format_name: myst
     format_version: 0.13
     jupytext_version: 1.11.1

diff --git a/docs/source/guide/executors.md b/docs/source/guide/executors.md
@@ -1,7 +1,7 @@
 ---
 jupytext:
   text_representation:
-    extension: .myst
+    extension: .md
     format_name: myst
     format_version: 0.13
     jupytext_version: 1.14.1
@@ -11,7 +11,6 @@ kernelspec:
   name: python3
 ---
 
-(guide/executors/executors)=
 # Executors
 
 +++

diff --git a/docs/source/guide/frontends-backends.md b/docs/source/guide/frontends-backends.md
@@ -1,7 +1,7 @@
 ---
 jupytext:
   text_representation:
-    extension: .myst
+    extension: .md
     format_name: myst
     format_version: 0.13
     jupytext_version: 1.11.4
@@ -11,12 +11,14 @@ kernelspec:
   name: python3
 ---
 
-
 # Frontends and Backends
 
+In short, a frontend is the tool used to write a quantum program, and a backend is the tool that executes said program.
+What follows is more detailed information as to how these concepts are handled in Mitiq.
+
 ## Mitiq-specific types
 
-There are a number of types that are specific to Mitiq, the most important being `mitiq.QPROGRAM` and {class}`.QuantumResult`.
+There are a number of types that are specific to Mitiq, the most important being `mitiq.QPROGRAM` and `mitiq.QuantumResult`.
 These types are both unions of a number of other types that make it easier to annotate other functions in Mitiq, independent of the user choice of frameworks.
 The Mitiq-defined type `mitiq.QPROGRAM` uses any of the program types from the supported platforms that are installed on the system.
 For example, if you haven't installed PyQuil, then even though Mitiq supports it, you will not be able to use PyQuil programs in Mitiq until it is installed.
@@ -25,9 +27,9 @@ For example, if you haven't installed PyQuil, then even though Mitiq supports it
 Mitiq only supports non-adaptive quantum programs without classical control flow or mid-circuit measurements. This class of programs is more commonly known as _circuits_ by many other tools and frameworks in quantum computing.
 ```
 
-The Mitiq-defined type {class}`.QuantumResult` is a union of the types defined in `mitiq.typing` that are used to represent the results of running a quantum program.
+The Mitiq-defined type `mitiq.QuantumResult` is a union of the types defined in `mitiq.typing` that are used to represent the results of running a quantum program.
 For example, for hardware, the result can be a list of bitstrings (representing raw measurements) or an expectation value expressed as a real number.
-For simulators, more information can be made available like the resulting density matrix, which is a valid object of the {class}`.QuantumResult` type.
+For simulators, more information can be made available like the resulting density matrix, which is a valid object of the `mitiq.QuantumResult` type.
 
 ## Frontends
 
@@ -44,16 +46,16 @@ mitiq.SUPPORTED_PROGRAM_TYPES.keys()
 with Cirq being used for the internal implementations of the mitigation methods.
 There is also frontend support for any circuit description that complies with the OpenQASM 2.0 standard.
 
-With any of these frontends (with the exception of Cirq), the circuit representation will be converted internally to a Cirq circuit object with the relevant conversion methods in {py:mod}`mitiq.interface` for each frontend.
+With any of these frontends (with the exception of Cirq), the circuit representation will be converted internally to a Cirq circuit object with the relevant conversion methods in `mitiq.interface` for each frontend.
 For example, you can use {func}`mitiq.interface.mitiq_braket.conversions.from_braket()` to convert a Braket circuit to a Cirq circuit.
 
 Examples for using each of the frameworks to represent the input to a mitigation method are linked below.
 
-- {ref}`Cirq <examples/cirq-ibmq-backends/setup-defining-a-circuit>`
-- {ref}`Qiskit <examples/ibmq-backends/setup-defining-a-circuit>`
-- {ref}`PyQuil <examples/pyquil_demo>`
-- {ref}`PennyLane <examples/ibmq-backends-pennylane/setup-defining-a-circuit>`
-- {ref}`Braket <examples/braket_mirror_circuit/define-the-circuit>`
+- {doc}`Cirq <../examples/cirq-ibmq-backends>`
+- {doc}`Qiskit <../examples/ibmq-backends>`
+- {doc}`PyQuil <../examples/pyquil_demo>`
+- {doc}`PennyLane <../examples/pennylane-ibmq-backends>`
+- {doc}`Braket <../examples/braket_mirror_circuit>`
 
 ## Backends
 
@@ -64,12 +66,12 @@ Backends are used by Mitiq in the {class}`.Executor` class to run the mitigated
 ## Executing programs
 
 Once you have selected a frontend and backend combination that are compatible, the next step is to set up the execution of a quantum program.
-The {class}`.Executor` class is used to execute quantum programs, and is constructed by providing a function with the following signature: `mitiq.QPROGRAM` -> {class}`.QuantumResult`.
-For more information on executors, see the {doc}`Executors <executors>` section of this guide.
+The {class}`.Executor` class is used to execute quantum programs, and is constructed by providing a function with the following signature: `mitiq.QPROGRAM -> mitiq.QuantumResult`.
+For more information on executors, see the {doc}`executors` section of this guide.
 
 ### Batch execution of programs
 
 You can also use the {class}`.Executor` class to execute a batch of quantum programs all in one go.
 To perform batched execution, you can use the same mitiq.Executor class constructor and pass a function with the following signature: `T[mitiq.QPROGRAM] -> T[{class}".QuantumResult"]` where T is `Sequence`, `List`, `Tuple`, or `Iterable`.
 
-For more information on batched executors and example code, see the {doc}`Executors <executors>` section of this guide.
+For more information on batched executors and example code, see the {doc}`executors` section of this guide.
diff --git a/docs/source/guide/glossary.md b/docs/source/guide/glossary.md
@@ -1,7 +1,7 @@
 ---
 jupytext:
   text_representation:
-    extension: .myst
+    extension: .md
     format_name: myst
     format_version: 0.13
     jupytext_version: 1.11.1

diff --git a/docs/source/guide/observables.md b/docs/source/guide/observables.md
@@ -1,7 +1,7 @@
 ---
 jupytext:
   text_representation:
-    extension: .myst
+    extension: .md
     format_name: myst
     format_version: 0.13
     jupytext_version: 1.11.1

diff --git a/docs/source/guide/pec-1-intro.md b/docs/source/guide/pec-1-intro.md
@@ -1,7 +1,7 @@
 ---
 jupytext:
   text_representation:
-    extension: .myst
+    extension: .md
     format_name: myst
     format_version: 0.13
     jupytext_version: 1.11.1