Merge pull request #288 from andreasgrv/region-graphs-notebook

Region graphs and parametrisation notebook

cirkit/templates/circuit_templates/_factories.py

@@ -17,7 +17,7 @@
     SoftmaxParameter,
     TensorParameter,
 )
-from cirkit.templates.region_graph import PoonDomingos, QuadGraph, QuadTree, RegionGraph
+from cirkit.templates.region_graph import PoonDomingos, QuadGraph, QuadTree, RandomBinaryTree, RegionGraph
 from cirkit.utils.scope import Scope
 
 
@@ -44,6 +44,8 @@ def build_image_region_graph(
         return QuadTree(image_shape, num_patch_splits=4)
     if name == "quad-graph":
         return QuadGraph(image_shape)
+    if name == "random-binary-tree":
+        return RandomBinaryTree(np.prod(image_shape))
     if name == "poon-domingos":
         delta = max(np.ceil(image_shape[0] / 8), np.ceil(image_shape[1] / 8))
         return PoonDomingos(image_shape, delta=delta)

cirkit/templates/circuit_templates/data.py

@@ -29,6 +29,7 @@ def image_data(
             'quad-tree-2' (the Quad-Tree with two splits per region node),
             'quad-tree-4' (the Quad-Tree with four splits per region node),
             'quad-graph'  (the Quad-Graph region graph),
+            'random-binary-tree' (the random binary tree on "flat" pixels),
             'poon-domingos' (the Poon-Domingos architecture).
         input_layer: The name of the input layer. It can be one of the following:
             'categorical' (encoding a Categorical distribution over pixel channel values),
@@ -52,7 +53,7 @@ def image_data(
     Raises:
         ValueError: If one of the arguments is not one of the specified allowed ones.
     """
-    if region_graph not in ["quad-tree-2", "quad-tree-4", "quad-graph", "poon-domingos"]:
+    if region_graph not in ["quad-tree-2", "quad-tree-4", "quad-graph", "random-binary-tree", "poon-domingos"]:
         raise ValueError(f"Unknown region graph called {region_graph}")
     if input_layer not in ["categorical", "binomial"]:
         raise ValueError(f"Unknown input layer called {input_layer}")

notebooks/README.md

@@ -0,0 +1,19 @@
+# Running Notebooks
+
+
+```bash
+pip install ".[notebooks]"
+jupyter notebook
+```
+
+
+# Suggested Path through Notebooks
+
+
+While you can explore the notebooks in any order, we recommend you start from [learning a circuit](learning-a-circuit.ipynb) and proceed as in the graph below.
+
+```mermaid
+graph TD;
+    A[<a href='https://github.com/april-tools/cirkit/blob/main/notebooks/learning-a-circuit.ipynb'>Learning a circuit</a>]-->B[<a href='https://github.com/april-tools/cirkit/blob/main/notebooks/compilation-options.ipynb'>Compilation Options</a>];
+    A-->C[<a href='https://github.com/april-tools/cirkit/blob/main/notebooks/region-graphs-and-parametrisation.ipynb'>Region Graphs and Parametrisation</a>];
+    A-->D[<a href='https://github.com/april-tools/cirkit/blob/main/notebooks/learning-a-circuit-with-pic.ipynb'>Probabilistic Integral Circuits</a>];