From 085537a791caafd7b32d7355db2748b74fbdb7bf Mon Sep 17 00:00:00 2001 From: matulni Date: Mon, 7 Sep 2026 19:09:00 +0200 Subject: [PATCH 1/2] Basic skeleton --- docs/source/conf.py | 20 +++++------ docs/source/development/apiref/index.rst | 21 ++++++++++++ .../apiref/source}/channels.rst | 0 .../apiref/source}/clifford.rst | 0 .../{ => development/apiref/source}/data.rst | 0 .../apiref/source}/extraction.rst | 0 .../apiref/source}/generator.rst | 0 .../apiref/source}/graphsim.rst | 0 .../apiref/source}/modifier.rst | 0 .../apiref/source}/open_graph.rst | 0 .../apiref/source}/optimization.rst | 0 .../apiref/source}/random_objects.rst | 0 .../apiref/source}/simulator.rst | 0 .../apiref/source}/visualization.rst | 0 docs/source/development/compatibility.rst | 3 ++ .../source/{ => development}/contributing.rst | 0 docs/source/getting_started.rst | 13 +++++++ docs/source/index.rst | 34 +++++++++++++------ docs/source/installation.rst | 4 +++ docs/source/plugins/index.rst | 3 ++ docs/source/references.rst | 18 ---------- docs/source/research_workflows/index.rst | 3 ++ docs/source/tutorials/index.rst | 21 ++++++++++++ .../tutorials/source/circuit_extraction.rst | 2 ++ docs/source/tutorials/source/flows.rst | 4 +++ docs/source/tutorials/source/graph_mbqc.rst | 6 ++++ .../tutorials/source/measurement_calculus.rst | 6 ++++ .../tutorials/source/pattern_simulation.rst | 5 +++ .../source/pattern_standardization.rst | 3 ++ .../source/tutorials/source/pauli_removal.rst | 2 ++ .../tutorials/source/space_minimization.rst | 3 ++ docs/source/tutorials/source/symbolic.rst | 2 ++ .../source/tutorials/source/transpilation.rst | 3 ++ docs/source/tutorials/source/type_safety.rst | 3 ++ 34 files changed, 140 insertions(+), 39 deletions(-) create mode 100644 docs/source/development/apiref/index.rst rename docs/source/{ => development/apiref/source}/channels.rst (100%) rename docs/source/{ => development/apiref/source}/clifford.rst (100%) rename docs/source/{ => development/apiref/source}/data.rst (100%) rename docs/source/{ => development/apiref/source}/extraction.rst (100%) rename docs/source/{ => development/apiref/source}/generator.rst (100%) rename docs/source/{ => development/apiref/source}/graphsim.rst (100%) rename docs/source/{ => development/apiref/source}/modifier.rst (100%) rename docs/source/{ => development/apiref/source}/open_graph.rst (100%) rename docs/source/{ => development/apiref/source}/optimization.rst (100%) rename docs/source/{ => development/apiref/source}/random_objects.rst (100%) rename docs/source/{ => development/apiref/source}/simulator.rst (100%) rename docs/source/{ => development/apiref/source}/visualization.rst (100%) create mode 100644 docs/source/development/compatibility.rst rename docs/source/{ => development}/contributing.rst (100%) create mode 100644 docs/source/getting_started.rst create mode 100644 docs/source/installation.rst create mode 100644 docs/source/plugins/index.rst delete mode 100644 docs/source/references.rst create mode 100644 docs/source/research_workflows/index.rst create mode 100644 docs/source/tutorials/index.rst create mode 100644 docs/source/tutorials/source/circuit_extraction.rst create mode 100644 docs/source/tutorials/source/flows.rst create mode 100644 docs/source/tutorials/source/graph_mbqc.rst create mode 100644 docs/source/tutorials/source/measurement_calculus.rst create mode 100644 docs/source/tutorials/source/pattern_simulation.rst create mode 100644 docs/source/tutorials/source/pattern_standardization.rst create mode 100644 docs/source/tutorials/source/pauli_removal.rst create mode 100644 docs/source/tutorials/source/space_minimization.rst create mode 100644 docs/source/tutorials/source/symbolic.rst create mode 100644 docs/source/tutorials/source/transpilation.rst create mode 100644 docs/source/tutorials/source/type_safety.rst diff --git a/docs/source/conf.py b/docs/source/conf.py index 8ee360ba4..e27039e5c 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -27,7 +27,7 @@ "sphinx.ext.autosummary", "sphinx.ext.autosectionlabel", "sphinx.ext.napoleon", - "sphinx_gallery.gen_gallery", + # "sphinx_gallery.gen_gallery", ] templates_path = ["_templates"] @@ -85,15 +85,15 @@ def setup(app: Sphinx) -> None: default_role = "any" -sphinx_gallery_conf = { - # path to your example scripts - "examples_dirs": ["../../examples"], - # path to where to save gallery generated output - "gallery_dirs": ["gallery"], - "filename_pattern": "/", - "thumbnail_size": (800, 550), - "parallel": True, -} +# sphinx_gallery_conf = { +# # path to your example scripts +# "examples_dirs": ["../../examples"], +# # path to where to save gallery generated output +# "gallery_dirs": ["gallery"], +# "filename_pattern": "/", +# "thumbnail_size": (800, 550), +# "parallel": True, +# } suppress_warnings = ["config.cache"] diff --git a/docs/source/development/apiref/index.rst b/docs/source/development/apiref/index.rst new file mode 100644 index 000000000..52395a54c --- /dev/null +++ b/docs/source/development/apiref/index.rst @@ -0,0 +1,21 @@ +API Reference +=========== +*Coming soon...* + +Old API Ref (to be updated): + +.. toctree:: + :maxdepth: 2 + + source/generator + source/data + source/modifier + source/simulator + source/graphsim + source/extraction + source/clifford + source/visualization + source/channels + source/random_objects + source/open_graph + source/optimization \ No newline at end of file diff --git a/docs/source/channels.rst b/docs/source/development/apiref/source/channels.rst similarity index 100% rename from docs/source/channels.rst rename to docs/source/development/apiref/source/channels.rst diff --git a/docs/source/clifford.rst b/docs/source/development/apiref/source/clifford.rst similarity index 100% rename from docs/source/clifford.rst rename to docs/source/development/apiref/source/clifford.rst diff --git a/docs/source/data.rst b/docs/source/development/apiref/source/data.rst similarity index 100% rename from docs/source/data.rst rename to docs/source/development/apiref/source/data.rst diff --git a/docs/source/extraction.rst b/docs/source/development/apiref/source/extraction.rst similarity index 100% rename from docs/source/extraction.rst rename to docs/source/development/apiref/source/extraction.rst diff --git a/docs/source/generator.rst b/docs/source/development/apiref/source/generator.rst similarity index 100% rename from docs/source/generator.rst rename to docs/source/development/apiref/source/generator.rst diff --git a/docs/source/graphsim.rst b/docs/source/development/apiref/source/graphsim.rst similarity index 100% rename from docs/source/graphsim.rst rename to docs/source/development/apiref/source/graphsim.rst diff --git a/docs/source/modifier.rst b/docs/source/development/apiref/source/modifier.rst similarity index 100% rename from docs/source/modifier.rst rename to docs/source/development/apiref/source/modifier.rst diff --git a/docs/source/open_graph.rst b/docs/source/development/apiref/source/open_graph.rst similarity index 100% rename from docs/source/open_graph.rst rename to docs/source/development/apiref/source/open_graph.rst diff --git a/docs/source/optimization.rst b/docs/source/development/apiref/source/optimization.rst similarity index 100% rename from docs/source/optimization.rst rename to docs/source/development/apiref/source/optimization.rst diff --git a/docs/source/random_objects.rst b/docs/source/development/apiref/source/random_objects.rst similarity index 100% rename from docs/source/random_objects.rst rename to docs/source/development/apiref/source/random_objects.rst diff --git a/docs/source/simulator.rst b/docs/source/development/apiref/source/simulator.rst similarity index 100% rename from docs/source/simulator.rst rename to docs/source/development/apiref/source/simulator.rst diff --git a/docs/source/visualization.rst b/docs/source/development/apiref/source/visualization.rst similarity index 100% rename from docs/source/visualization.rst rename to docs/source/development/apiref/source/visualization.rst diff --git a/docs/source/development/compatibility.rst b/docs/source/development/compatibility.rst new file mode 100644 index 000000000..156dd426b --- /dev/null +++ b/docs/source/development/compatibility.rst @@ -0,0 +1,3 @@ +Compatibility +============= +*Refer to compatiblity.md* \ No newline at end of file diff --git a/docs/source/contributing.rst b/docs/source/development/contributing.rst similarity index 100% rename from docs/source/contributing.rst rename to docs/source/development/contributing.rst diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst new file mode 100644 index 000000000..0d55eb28e --- /dev/null +++ b/docs/source/getting_started.rst @@ -0,0 +1,13 @@ +Getting started +=============== + +*To be written* + +*Simple description of what Graphix does* + + + +Running your first program +-------------------------- + +*Simple circuit transpilation and pattern simulation* \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index 5007448cf..b22065d29 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,23 +1,35 @@ .. graphix documentation master file, created by sphinx-quickstart on Sun Nov 20 00:43:54 2022. -Graphix - optimizing and simulating MBQC -======================================== +Graphix +======= +An open-source framework for Measurement-Based Quantum Computation -**Graphix** is an open-source library to generate, optimize and simulate the measurement-based quantum computing (MBQC) command sequence. +.. toctree:: + :caption: Documentation + installation + getting_started + tutorials/index + research_workflows/index + .. toctree:: + :caption: Development :maxdepth: 1 - :caption: Documentation + + development/contributing + development/compatibility + development/apiref/index - tutorial - gallery/index - references - contributing .. toctree:: - :maxdepth: 2 - :caption: Introduction to LC-MBQC + :caption: Graphix plugins + plugins/index + +.. toctree:: + :caption: Old sections + + tutorial intro - lc-mbqc + lc-mbqc \ No newline at end of file diff --git a/docs/source/installation.rst b/docs/source/installation.rst new file mode 100644 index 000000000..c15117604 --- /dev/null +++ b/docs/source/installation.rst @@ -0,0 +1,4 @@ +Installation +============ + +*To be written* \ No newline at end of file diff --git a/docs/source/plugins/index.rst b/docs/source/plugins/index.rst new file mode 100644 index 000000000..ba03ea278 --- /dev/null +++ b/docs/source/plugins/index.rst @@ -0,0 +1,3 @@ +Graphix plugins +=============== +*Coming soon...* \ No newline at end of file diff --git a/docs/source/references.rst b/docs/source/references.rst deleted file mode 100644 index ac670e0bc..000000000 --- a/docs/source/references.rst +++ /dev/null @@ -1,18 +0,0 @@ -Module reference -================ - -.. toctree:: - :maxdepth: 2 - - generator - data - modifier - simulator - graphsim - extraction - clifford - visualization - channels - random_objects - open_graph - optimization diff --git a/docs/source/research_workflows/index.rst b/docs/source/research_workflows/index.rst new file mode 100644 index 000000000..40406c5b5 --- /dev/null +++ b/docs/source/research_workflows/index.rst @@ -0,0 +1,3 @@ +Research workflows +================== +*Coming soon...* \ No newline at end of file diff --git a/docs/source/tutorials/index.rst b/docs/source/tutorials/index.rst new file mode 100644 index 000000000..cdd9b6b6e --- /dev/null +++ b/docs/source/tutorials/index.rst @@ -0,0 +1,21 @@ +Tutorials +========= + +*Overview of MBQC, we can borrow beginning of Sec. 2* + +.. toctree:: + source/graph_mbqc + source/measurement_calculus + source/transpilation + source/flows + source/pattern_standardization + source/space_minimization + source/pauli_removal + source/pattern_simulation + source/circuit_extraction + +.. toctree:: + :caption: Advanced Tutorials + + source/symbolic + source/type_safety diff --git a/docs/source/tutorials/source/circuit_extraction.rst b/docs/source/tutorials/source/circuit_extraction.rst new file mode 100644 index 000000000..fc1e0b342 --- /dev/null +++ b/docs/source/tutorials/source/circuit_extraction.rst @@ -0,0 +1,2 @@ +Circuit extraction +================== diff --git a/docs/source/tutorials/source/flows.rst b/docs/source/tutorials/source/flows.rst new file mode 100644 index 000000000..8542306b6 --- /dev/null +++ b/docs/source/tutorials/source/flows.rst @@ -0,0 +1,4 @@ +Flows and determinism +===================== + +*This tutorial should cover sections 2.3 and 3.2 of the paper.* diff --git a/docs/source/tutorials/source/graph_mbqc.rst b/docs/source/tutorials/source/graph_mbqc.rst new file mode 100644 index 000000000..6906c1961 --- /dev/null +++ b/docs/source/tutorials/source/graph_mbqc.rst @@ -0,0 +1,6 @@ +Open graphs and correction functions +==================================== + +*This tutorial should cover section 2.1 of the paper, a bit less of theory and some more examples* + + diff --git a/docs/source/tutorials/source/measurement_calculus.rst b/docs/source/tutorials/source/measurement_calculus.rst new file mode 100644 index 000000000..4a8f78d46 --- /dev/null +++ b/docs/source/tutorials/source/measurement_calculus.rst @@ -0,0 +1,6 @@ +Patterns and the measurement calculus +===================================== + +*This tutorial should cover section 2.2 of the paper without standardization.* +*Instead of simulating the pattern (box 2.2), we can put a pattern visualization* + diff --git a/docs/source/tutorials/source/pattern_simulation.rst b/docs/source/tutorials/source/pattern_simulation.rst new file mode 100644 index 000000000..eea13e7de --- /dev/null +++ b/docs/source/tutorials/source/pattern_simulation.rst @@ -0,0 +1,5 @@ +Pattern simulation +=================== + +*This tutorial could start with a simple pattern simulation example (like in "Getting started"), then cover sections 3.6. No need to put the Figure.* +*There should be subsections: branch selection, noisy simulation and maybe "Advance usage" : custom noise models.* \ No newline at end of file diff --git a/docs/source/tutorials/source/pattern_standardization.rst b/docs/source/tutorials/source/pattern_standardization.rst new file mode 100644 index 000000000..4a874eaf4 --- /dev/null +++ b/docs/source/tutorials/source/pattern_standardization.rst @@ -0,0 +1,3 @@ +Pattern standardization +======================= +*Basic example and maybe some details on `StandardizedPattern` class* \ No newline at end of file diff --git a/docs/source/tutorials/source/pauli_removal.rst b/docs/source/tutorials/source/pauli_removal.rst new file mode 100644 index 000000000..17863d95a --- /dev/null +++ b/docs/source/tutorials/source/pauli_removal.rst @@ -0,0 +1,2 @@ +Pauli measurement removal +========================= \ No newline at end of file diff --git a/docs/source/tutorials/source/space_minimization.rst b/docs/source/tutorials/source/space_minimization.rst new file mode 100644 index 000000000..2a91d3c12 --- /dev/null +++ b/docs/source/tutorials/source/space_minimization.rst @@ -0,0 +1,3 @@ +Space minimization +================== +*Basic example and details on `SpaceMinimizationHeuristic`* \ No newline at end of file diff --git a/docs/source/tutorials/source/symbolic.rst b/docs/source/tutorials/source/symbolic.rst new file mode 100644 index 000000000..610556741 --- /dev/null +++ b/docs/source/tutorials/source/symbolic.rst @@ -0,0 +1,2 @@ +Symbolic manipulation +===================== diff --git a/docs/source/tutorials/source/transpilation.rst b/docs/source/tutorials/source/transpilation.rst new file mode 100644 index 000000000..0d99d8f25 --- /dev/null +++ b/docs/source/tutorials/source/transpilation.rst @@ -0,0 +1,3 @@ +From circuits to patterns +========================= +*This tutorial should describe the JCZ transpiler and the Circuit API. Fig. 7 is potentially useful* \ No newline at end of file diff --git a/docs/source/tutorials/source/type_safety.rst b/docs/source/tutorials/source/type_safety.rst new file mode 100644 index 000000000..96f6a794c --- /dev/null +++ b/docs/source/tutorials/source/type_safety.rst @@ -0,0 +1,3 @@ +Type safety +=========== +*Description of type hierachies* \ No newline at end of file From 9750e54cf61649be15e728ea58b7fc71dda198d2 Mon Sep 17 00:00:00 2001 From: matulni Date: Mon, 14 Sep 2026 12:04:14 +0200 Subject: [PATCH 2/2] Fix warnings in old docs --- docs/source/development/apiref/index.rst | 2 +- docs/source/tutorial.rst | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/development/apiref/index.rst b/docs/source/development/apiref/index.rst index 52395a54c..d8c80777a 100644 --- a/docs/source/development/apiref/index.rst +++ b/docs/source/development/apiref/index.rst @@ -1,5 +1,5 @@ API Reference -=========== +============= *Coming soon...* Old API Ref (to be updated): diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst index dca2e9b4c..312e8f3a4 100644 --- a/docs/source/tutorial.rst +++ b/docs/source/tutorial.rst @@ -4,7 +4,7 @@ Tutorial Graphix provides a high-level interface to generate, optimize and classically simulate the measurement-based quantum computing (MBQC). In this tutorial, we look at how to program MBQC using graphix library. -We will explain the basics here along with the code, and you can go to :doc:`intro` to learn more about the theoretical background of MBQC and :doc:`references` for module references. +We will explain the basics here along with the code, and you can go to :doc:`intro` to learn more about the theoretical background of MBQC and references for module references. Generating measurement patterns ------------------------------- @@ -229,7 +229,7 @@ With this, we only need the memory space for three qubits. This procedure is more effective when the resource state size is large compared to the logical input qubit count; for example, the three-qubit `quantum Fourier transform (QFT) -`_ circuit requires 12 qubits in the resource state after :meth:`~graphix.pattern.Pattern.perform_pauli_measurements()` (see the code in :ref:`QFT example `); with the proper reordering of the commands, the max_space reduces to 4. +`_ circuit requires 12 qubits in the resource state after :meth:`~graphix.pattern.Pattern.perform_pauli_measurements()` (see the code in sphx_glr_gallery_qft_with_tn.py); with the proper reordering of the commands, the max_space reduces to 4. In fact, for patterns transpiled from gate network, the minimum *space* we can realize is typically :math:`n_w+1` where :math:`n_w` is the width of the circuit.