Add Mirror RB experiment

.github/workflows/main.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        python-version: [3.7, 3.8, 3.9, "3.10"]
+        python-version: [3.7, 3.8, 3.9, "3.10", "3.11"]
         os: ["ubuntu-latest", "macOS-latest", "windows-latest"]
     steps:
       - name: Print Concurrency Group

.pylintrc

@@ -297,7 +297,7 @@ ignore-mixin-members=yes
 # (useful for modules/projects where namespaces are manipulated during runtime
 # and thus existing member attributes cannot be deduced by static analysis. It
 # supports qualified module names, as well as Unix pattern matching.
-ignored-modules=matplotlib.cm,numpy.random,retworkx
+ignored-modules=matplotlib.cm,numpy.random,rustworkx
 
 # List of class names for which member attributes should not be checked (useful
 # for classes with dynamically set attributes). This supports the use of

MANIFEST.in

@@ -1,3 +1,5 @@
 include LICENSE.txt
 include requirements.txt
 include qiskit_experiments/VERSION.txt
+include qiskit_experiments/library/randomized_benchmarking/data/*.npz
+exclude qiskit_experiments/library/randomized_benchmarking/data/generate_clifford_data.py

docs/_ext/autodoc_visualization.py

@@ -0,0 +1,99 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2021, 2023.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""
+Documentation extension for visualization classes.
+"""
+
+from typing import Any
+
+from docs._ext.custom_styles.styles import VisualizationDocstring
+from qiskit.exceptions import QiskitError
+from qiskit_experiments.visualization import BasePlotter, BaseDrawer
+from sphinx.application import Sphinx
+from sphinx.ext.autodoc import ClassDocumenter
+
+
+class VisualizationDocumenter(ClassDocumenter):
+    """Sphinx extension for the custom documentation of the standard visualization classes."""
+
+    objtype = "visualization"  # Must be overwritten by subclasses.
+    directivetype = "class"
+    priority = 10 + ClassDocumenter.priority
+    option_spec = dict(ClassDocumenter.option_spec)
+
+    def add_content(self, more_content: Any, no_docstring: bool = False) -> None:
+        sourcename = self.get_sourcename()
+        try:
+            class_doc, init_doc = self.get_doc()
+        except ValueError:
+            raise QiskitError(
+                f"Documentation of {self.name} doesn't match with the expected format."
+                "Please run sphinx build without using the visualization template."
+            )
+
+        # format visualization class documentation into the visualization style
+        class_doc_parser = VisualizationDocstring(
+            target_cls=self.object,
+            docstring_lines=class_doc,
+            config=self.env.app.config,
+            indent=self.content_indent,
+        )
+
+        # write introduction
+        for i, line in enumerate(self.process_doc(class_doc_parser.generate_class_docs())):
+            self.add_line(line, sourcename, i)
+        self.add_line("", sourcename)
+
+        # write init method documentation
+        self.add_line(".. rubric:: Initialization", sourcename)
+        self.add_line("", sourcename)
+        for i, line in enumerate(self.process_doc([init_doc])):
+            self.add_line(line, sourcename, i)
+        self.add_line("", sourcename)
+
+        # method and attributes
+        if more_content:
+            for line, src in zip(more_content.data, more_content.items):
+                self.add_line(line, src[0], src[1])
+
+
+class PlotterDocumenter(VisualizationDocumenter):
+    """Sphinx extension for the custom documentation of plotter classes."""
+
+    objtype = "plotter"
+
+    @classmethod
+    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any) -> bool:
+        return isinstance(member, BasePlotter)
+
+
+class DrawerDocumenter(VisualizationDocumenter):
+    """Sphinx extension for the custom documentation of drawer classes."""
+
+    objtype = "drawer"
+
+    @classmethod
+    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any) -> bool:
+        return isinstance(member, BaseDrawer)
+
+
+def setup(app: Sphinx):
+    # Add plotter documenter
+    existing_documenter = app.registry.documenters.get(PlotterDocumenter.objtype)
+    if existing_documenter is None or not issubclass(existing_documenter, PlotterDocumenter):
+        app.add_autodocumenter(PlotterDocumenter, override=True)
+
+    # Add drawer documenter
+    existing_documenter = app.registry.documenters.get(DrawerDocumenter.objtype)
+    if existing_documenter is None or not issubclass(existing_documenter, DrawerDocumenter):
+        app.add_autodocumenter(DrawerDocumenter, override=True)

docs/_ext/autoref.py

@@ -30,6 +30,7 @@ class WebSite(Directive):
         .. ref_website:: qiskit-experiments, https://github.com/Qiskit/qiskit-experiments
 
     """
+
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = True
@@ -67,6 +68,7 @@ class Arxiv(Directive):
     If an article is not found, no journal information will be shown.
 
     """
+
     required_arguments = 2
     optional_arguments = 0
     final_argument_whitespace = False

docs/_ext/custom_styles/formatter.py

@@ -1,6 +1,6 @@
 # This code is part of Qiskit.
 #
-# (C) Copyright IBM 2021.
+# (C) Copyright IBM 2021, 2023.
 #
 # This code is licensed under the Apache License, Version 2.0. You may
 # obtain a copy of this license in the LICENSE.txt file in the root directory
@@ -215,3 +215,35 @@ def format_fit_parameters(self, lines: List[str]) -> List[str]:
         format_lines.append("")
 
         return format_lines
+
+class VisualizationSectionFormatter(DocstringSectionFormatter):
+    """Formatter for visualization classes."""
+
+    @_check_no_indent
+    def format_opts(self, lines: List[str]) -> List[str]:
+        """Format options section."""
+
+        format_lines = [
+            ".. rubric:: Options",
+            "",
+            "The following can be set using :meth:`set_options`.",
+            "",
+        ]
+        format_lines.extend(lines)
+        format_lines.append("")
+
+        return format_lines
+
+    @_check_no_indent
+    def format_figure_opts(self, lines: List[str]) -> List[str]:
+        """Format figure options section."""
+        format_lines = [
+            ".. rubric:: Figure Options",
+            "",
+            "The following can be set using :meth:`set_figure_options`.",
+            "",
+        ]
+        format_lines.extend(lines)
+        format_lines.append("")
+
+        return format_lines

docs/_ext/custom_styles/styles.py

@@ -1,6 +1,6 @@
 # This code is part of Qiskit.
 #
-# (C) Copyright IBM 2021.
+# (C) Copyright IBM 2021, 2023.
 #
 # This code is licensed under the Apache License, Version 2.0. You may
 # obtain a copy of this license in the LICENSE.txt file in the root directory
@@ -21,12 +21,14 @@
 
 from qiskit_experiments.framework.base_analysis import BaseAnalysis
 from qiskit_experiments.framework.base_experiment import BaseExperiment
+from qiskit_experiments.visualization import BaseDrawer, BasePlotter
 from sphinx.config import Config as SphinxConfig
 
 from .formatter import (
     ExperimentSectionFormatter,
     AnalysisSectionFormatter,
     DocstringSectionFormatter,
+    VisualizationSectionFormatter,
 )
 from .section_parsers import load_standard_section, load_fit_parameters
 from .utils import (
@@ -310,3 +312,85 @@ def _extra_sections(self, sectioned_docstring: Dict[str, List[str]]):
             option_desc.append("No option available for this analysis.")
 
         sectioned_docstring["analysis_opts"] = option_desc
+
+
+class VisualizationDocstring(QiskitExperimentDocstring):
+    """Documentation parser for visualization classes' introductions."""
+
+    __sections__ = {
+        "header": load_standard_section,
+        "warning": load_standard_section,
+        "overview": load_standard_section,
+        "reference": load_standard_section,
+        "tutorial": load_standard_section,
+        "opts": None,           # For standard options
+        "figure_opts": None,    # For figure options
+        "example": load_standard_section,
+        "note": load_standard_section,
+        "see_also": load_standard_section,
+    }
+
+    __formatter__ = VisualizationSectionFormatter
+
+    def __init__(
+        self,
+        target_cls: Union[BaseDrawer, BasePlotter],
+        docstring_lines: Union[str, List[str]],
+        config: SphinxConfig,
+        indent: str = "",
+    ):
+        """Create new parser and parse formatted docstring."""
+        super().__init__(target_cls, docstring_lines, config, indent)
+
+    def _extra_sections(self, sectioned_docstring: Dict[str, List[str]]):
+        """Generate extra sections."""
+        # add options
+        option_desc = []
+        figure_option_desc = []
+
+        docs_config = copy.copy(self._config)
+        docs_config.napoleon_custom_sections = [
+            ("options", "args"),
+            ("figure options", "args"),
+        ]
+
+        # Generate options docs
+        option = _generate_options_documentation(
+            current_class=self._target_cls,
+            method_name="_default_options",
+            config=docs_config,
+            indent=self._indent,
+        )
+        if option:
+            option_desc.extend(option)
+            option_desc.append("")
+            option_desc.extend(
+                _format_default_options(
+                    defaults=self._target_cls._default_options().__dict__,
+                    indent=self._indent,
+                )
+            )
+        else:
+            option_desc.append("No options available.")
+
+        # Generate figure options docs
+        figure_option = _generate_options_documentation(
+            current_class=self._target_cls,
+            method_name="_default_figure_options",
+            config=docs_config,
+            indent=self._indent,
+        )
+        if figure_option:
+            figure_option_desc.extend(figure_option)
+            figure_option_desc.append("")
+            figure_option_desc.extend(
+                _format_default_options(
+                    defaults=self._target_cls._default_figure_options().__dict__,
+                    indent=self._indent,
+                )
+            )
+        else:
+            figure_option_desc.append("No figure options available.")
+
+        sectioned_docstring["opts"] = option_desc
+        sectioned_docstring["figure_opts"] = figure_option_desc

docs/_templates/autosummary/drawer.rst

@@ -0,0 +1,49 @@
+{% if referencefile %}
+.. include:: {{ referencefile }}
+{% endif %}
+
+{{ objname }}
+{{ underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autodrawer:: {{ objname }}
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:
+
+   {% block attributes_summary %}
+   {% if attributes %}
+
+   .. rubric:: Attributes
+
+   .. autosummary::
+      :toctree: ../stubs/
+   {% for item in all_attributes %}
+      {%- if not item.startswith('_') %}
+      {{ name }}.{{ item }}
+      {%- endif -%}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block methods_summary %}
+   {% if methods %}
+
+   .. rubric:: Methods
+
+   .. autosummary::
+      :toctree: ../stubs/
+   {% for item in all_methods %}
+      {%- if not item.startswith('_') or item in ['__call__', '__mul__', '__getitem__', '__len__'] %}
+      {{ name }}.{{ item }}
+      {%- endif -%}
+   {%- endfor %}
+   {% for item in inherited_members %}
+      {%- if item in ['__call__', '__mul__', '__getitem__', '__len__'] %}
+      {{ name }}.{{ item }}
+      {%- endif -%}
+   {%- endfor %}
+
+   {% endif %}
+   {% endblock %}

docs/_templates/autosummary/plotter.rst

@@ -0,0 +1,50 @@
+{% if referencefile %}
+.. include:: {{ referencefile }}
+{% endif %}
+
+{{ objname }}
+{{ underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoplotter:: {{ objname }}
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:
+
+   {% block attributes_summary %}
+   {% if attributes %}
+
+   .. rubric:: Attributes
+
+   .. autosummary::
+      :toctree: ../stubs/
+   {% for item in all_attributes %}
+      {%- if not item.startswith('_') %}
+      {{ name }}.{{ item }}
+      {%- endif -%}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block methods_summary %}
+   {% if methods %}
+
+   .. rubric:: Methods
+
+   .. autosummary::
+      :toctree: ../stubs/
+
+   {% for item in all_methods %}
+      {%- if not item.startswith('_') or item in ['__call__', '__mul__', '__getitem__', '__len__'] %}
+      {{ name }}.{{ item }}
+      {%- endif -%}
+   {%- endfor %}
+   {% for item in inherited_members %}
+      {%- if item in ['__call__', '__mul__', '__getitem__', '__len__'] %}
+      {{ name }}.{{ item }}
+      {%- endif -%}
+   {%- endfor %}
+
+   {% endif %}
+   {% endblock %}