Merge pull request #327 from andreasgrv/docs

Improve Documentation

cirkit/__init__.py

@@ -0,0 +1,5 @@
+"""
+cirkit: a python framework to build, learn and reason about probabilistic circuits and tensor networks.
+
+Use the menu on the left to navigate through the library structure and access the documentation for every module.
+"""

cirkit/backend/__init__.py

@@ -0,0 +1,5 @@
+"""
+This module contains code that makes the symbolic representations concrete - i.e. it translates the symbolic computational graph to a computational graph with parameters that supports back-propagation.
+The backend decides data type precision, folding and how parameters are allocated in the computational graph.
+We currently support PyTorch as a backend.
+"""

cirkit/symbolic/__init__.py

@@ -0,0 +1,7 @@
+"""
+This module implements abstract symbolic representations of circuits.
+These symbolic representations need compiling to some backend before they can be executed or used to perform inference with.
+More specifically, the module defines operations on circuits, circuit components and the computational graph that defines the computed function.
+The parameters are symbolically defined but not materialised/allocated in memory.
+While data types are defined here, they are abstract (int, real, complex); the precision is decided at compile time based on the backend.
+"""

cirkit/templates/__init__.py

@@ -0,0 +1,4 @@
+"""
+This module contains functions to build circuit structures out of templates for different data modalities.
+For example, you can build a circuit from a region graph for image data.
+"""

cirkit/utils/__init__.py

@@ -0,0 +1,3 @@
+"""
+This module contains helper functions and classes.
+"""

docs/css/style.css

@@ -0,0 +1,3 @@
+.md-header__title {
+    visibility: hidden;
+}

docs/index.md

@@ -0,0 +1,71 @@
+---
+hide:
+    - toc
+    - navigation
+    - title
+---
+
+<div class="grid" markdown>
+
+
+<div markdown>
+# Building efficient and trustworthy AI
+**cirkit** is a framework for building, learning and reasoning about **probabilistic machine learning** models, such as [circuits](https://arxiv.org/abs/2409.07953) and [tensor networks](https://arxiv.org/abs/1708.00006), which are **tractable** and **expressive**.
+</div>
+
+
+* ⚡ **Exact and Efficient Inference** : Automatically compile tractable models to efficient computational graphs that run on the GPU.
+* **Compatible**: Seamlessly integrate your circuit with deep learning models; run on any device compatible with PyTorch.
+* **Modular and Extensible**: Support for user-defined layers and parameterizations that extend the symbolic language of cirkit.
+* **Templates for Common Cases**: Templates for constructing circuits by mixing layers and structures with a few lines of code.
+
+
+</div>
+
+<h1>Getting Started</h1>
+
+<div class="grid cards" markdown>
+
+-   :fontawesome-solid-screwdriver-wrench:{ .lg .middle } __Build a circuit...__
+
+    ---
+    [:octicons-arrow-right-24: from region graphs](https://github.com/april-tools/cirkit/blob/main/notebooks/region-graphs-and-parametrisation.ipynb)
+
+<!--
+
+    [:octicons-arrow-right-24: with different layers :fontawesome-solid-layer-group:{.lg}](#)
+
+--->
+
+-   :fontawesome-solid-gears:{ .lg .middle } __Learn a circuit...__
+
+    ---
+    [:octicons-arrow-right-24: for distribution estimation :fontawesome-solid-chart-area:{.lg}](https://github.com/april-tools/cirkit/blob/main/notebooks/learning-a-circuit.ipynb)
+
+	[:octicons-arrow-right-24: for tensor compression :fontawesome-solid-file-zipper:](https://github.com/april-tools/cirkit/blob/main/notebooks/compression-cp-factorization.ipynb)
+
+    [:octicons-arrow-right-24: ... all of the above, with PICs :fontawesome-solid-camera:](https://github.com/april-tools/cirkit/blob/main/notebooks/learning-a-circuit-with-pic.ipynb)
+
+<!--
+
+    [:octicons-arrow-right-24: as a (generative) multi-class classifier](#)
+--->
+
+-   :material-scale-balance:{ .lg .middle }__Advanced reasoning...__
+
+    ---
+    [:octicons-arrow-right-24: with squared circuits $($:fontawesome-solid-plug-circle-minus:{.lg}$)^2$](https://github.com/april-tools/cirkit/blob/main/notebooks/sum-of-squares-circuits.ipynb)
+
+    [:octicons-arrow-right-24: with logic circuits :fontawesome-solid-square-binary:{.lg}...](https://github.com/april-tools/cirkit/blob/main/notebooks/logic-circuits.ipynb)
+
+	</br>
+    ...to enforce constraints in neural nets
+
+<!--
+-   :fontawesome-solid-code-merge:{ .lg .middle } __Integrate with other PyTorch libraries...__
+
+    ---
+    [:octicons-arrow-right-24: ZUKO: normalising flows](#)
+--->
+
+</div>

docs/notebooks/compilation-options.ipynb

@@ -0,0 +1 @@
+../../notebooks/compilation-options.ipynb

docs/notebooks/compression-cp-factorization.ipynb

@@ -0,0 +1 @@
+../../notebooks/compression-cp-factorization.ipynb

docs/notebooks/learning-a-circuit-with-pic.ipynb

@@ -0,0 +1 @@
+../../notebooks/learning-a-circuit-with-pic.ipynb

docs/notebooks/learning-a-circuit.ipynb

@@ -0,0 +1 @@
+../../notebooks/learning-a-circuit.ipynb

docs/notebooks/logic-circuits.ipynb

@@ -0,0 +1 @@
+../../notebooks/logic-circuits.ipynb

docs/notebooks/region-graphs-and-parametrisation.ipynb

@@ -0,0 +1 @@
+../../notebooks/region-graphs-and-parametrisation.ipynb

docs/notebooks/sum-of-squares-circuits.ipynb

@@ -0,0 +1 @@
+../../notebooks/sum-of-squares-circuits.ipynb

mkdocs.yml

@@ -2,12 +2,22 @@ site_name: cirkit
 site_url: https://example.com
 repo_url: https://github.com/april-tools/cirkit
 nav:
-  - Home: 'README.md'
-  - Notebooks: 'notebooks/README.md'
+  - Getting Started: 'index.md'
+  - Notebooks:
+    - Overview: 'notebooks/README.md'
+    - Overview:
+      - nb1: 'notebooks/learning-a-circuit.ipynb'
+      - nb2: 'notebooks/region-graphs-and-parametrisation.ipynb'
+      - nb3: 'notebooks/sum-of-squares-circuits.ipynb'
+      - nb4: 'notebooks/compilation-options.ipynb'
+      - nb5: 'notebooks/learning-a-circuit-with-pic.ipynb'
+      - nb6: 'notebooks/logic-circuits.ipynb'
+      - nb7: 'notebooks/compression-cp-factorization.ipynb'
   - API documentation: 'api/'
 plugins:
   - search
   - autorefs
+  - mkdocs-jupyter 
   - gen-files:
       scripts:
         - scripts/generate_api_pages.py
@@ -31,6 +41,7 @@ plugins:
             show_if_no_docstring: true
 theme:
   name: "material"
+  logo: "assets/logo.png"
   palette:
     primary: blue
     accent: orange
@@ -53,6 +64,11 @@ theme:
 markdown_extensions:
   - pymdownx.arithmatex:
       generic: true
+  - attr_list
+  - md_in_html
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
   - pymdownx.superfences:
       custom_fences:
         - name: mermaid
@@ -65,4 +81,5 @@ extra_javascript:
   - https://unpkg.com/katex@0/dist/katex.min.js
   - https://unpkg.com/katex@0/dist/contrib/auto-render.min.js
 extra_css:
-  - https://unpkg.com/katex@0/dist/katex.min.css
+   - css/style.css
+   - https://unpkg.com/katex@0/dist/katex.min.css

pyproject.toml

@@ -65,6 +65,7 @@ docs = [
   "mkdocs-gen-files",
   "mkdocs-literate-nav",
   "mkdocs-section-index",
+  "mkdocs-jupyter",
 ]
 notebooks = [
   "notebook",