document circuit creation

Author: jjcmoon

docs/circuit_creation.rst

@@ -0,0 +1,85 @@
+.. _circuit_construction:
+
+Circuit Creation
+================
+
+There are several ways to create a circuit. You can either load in a circuit compiled by a PySDD or d4, or you can manually the circuit.
+
+Loading Circuits
+********************
+
+An SDD can be loaded from a file as follows.
+
+.. code-block:: Python
+
+   import klaycircuits
+
+   circuit = klaycircuits.Circuit()
+   circuit.add_SDD_from_file("path/to/my.sdd")
+
+Similarly, for d4 we can use
+
+.. code-block:: Python
+
+   circuit = klaycircuits.Circuit()
+   circuit.add_D4_from_file("path/to/my.nnf")
+
+SDDs can also be loaded directly from a PySDD :code:`SddNode` object.
+
+.. code-block:: Python
+
+   from pysdd.sdd import SddManager
+
+   manager = SddManager(var_count = 2)
+   sdd_node = manager.literal(1) & manager.literal(2)
+
+   circuit = klaycircuits.Circuit()
+   circuit.add_sdd(sdd_node)
+
+
+Multi-Rooted Circuits
+*********************
+
+If you want to evaluate multiple circuits in parallel, you can merge them into a single multi-rooted circuit.
+
+.. code-block:: Python
+
+   circuit = klaycircuits.Circuit()
+   circuit.add_sdd(first_sdd)
+   circuit.add_sdd(second_sdd)
+
+Evaluating this circuit will result in an output tensor with two elements. The order in which the circuits are added
+determines the order in the output when evaluating.
+
+
+Manual Circuits
+***************************
+
+If you want to create a custom circuit, you can manually define the circuit structure.
+We start by defining some literals.
+
+.. code-block:: Python
+
+    circuit = klaycircuits.Circuit()
+    a = circuit.literal_node(1)
+    b = circuit.literal_node(-2)
+
+Next, create and/or nodes as follows.
+
+.. code-block:: Python
+
+    and_node = circuit.and_node([a, b])
+
+To indicate that a node is a root (i.e. it will be part of the output), you need to mark it as root.
+
+.. code-block:: Python
+
+    circuit.set_root(and_node)
+
+As we support multi-rooted circuits, you can later add more nodes and mark them as root.
+
+.. code-block:: Python
+
+    or_node = circuit.or_node([a, b])
+    circuit.set_root(or_node)
+

docs/index.rst

@@ -13,11 +13,14 @@ At its core, KLay transforms sparse directed acyclic graphs into layers that can
 .. image:: _static/scatter_reduce.png
   :width: 400
 
+----
 
+Contents
+********
 
 .. toctree::
 
    Home <self>
    quickstart
-   api
+   circuit_creation
 

docs/quickstart.rst

@@ -18,8 +18,7 @@ Usage
 *****
 
 First, we need to create a circuit. You can both manually define the circuit, or import it from a knowledge compiler.
-So far KLay supports the PySDD and d4 circuit formats.
-For example, you can load in a PySDD circuit as follows.
+For more information, check out the :ref:`circuit_construction` guide.
 
 .. code-block:: Python
 
@@ -28,21 +27,27 @@ For example, you can load in a PySDD circuit as follows.
    circuit = klaycircuits.Circuit()
    circuit.add_sdd(sdd_node)
 
-For more information on circuit construction, check out <todo>.
-
 Now that we have the circuit, we can evaluate it. To do this, we first turn the circuit into a PyTorch module.
-Other backends such as Jax are also supported.
 
 .. code-block:: Python
 
    import torch
 
    module = circuit.to_torch_module()
+   module = module.to("cuda:0")
 
-We can use this module as any other PyTorch module. The expected input is a tensor with the weights for each literal.
+We can use our circuit as any other PyTorch module. The input should be a tensor with the weights for each literal, and the output is the result of evaluating circuit.
 
 .. code-block:: Python
 
-   weights = torch.tensor([...])
+   weights = torch.tensor([...], device="cuda:0")
    result = module(weights)
-   result.backward()
+   result.backward()
+
+Backends
+********
+
+KLay needs a backend to evaluate the circuit in. So far, we implemented two different backends.
+
+- PyTorch: :code:`torch_module = circuit.to_torch_module()`
+- Jax: :code:`jax_function = circuit.to_jax_function()`