feat: Added examples for dot product and matrix multiplication

Author: jcabrero

examples/dot_product/README.md

@@ -0,0 +1,44 @@
+# Dot Product Tutorial
+
+This tutorial shows how to efficiently program a dot product in Nada using Nada Algebra. 
+
+```python
+from nada_dsl import *
+# Step 0: Nada Algebra is imported with this line
+import nada_algebra as na
+
+
+def nada_main():
+    # Step 1: We use Nada Algebra wrapper to create "Party0", "Party1" and "Party2"
+    parties = na.parties(3)
+
+    # Step 2: Party0 creates an array of dimension (3, ) with name "A"
+    a = na.array([3], parties[0], "A")
+
+    # Step 3: Party1 creates an array of dimension (3, ) with name "B"
+    b = na.array([3], parties[1], "B")
+
+    # Step 4: The result is of computing the dot product between the two
+    result = a.dot(b)
+
+    # Step 5: We can use result.output() to produce the output for Party2 and variable name "my_output"
+    return result.output(parties[1], "my_output")
+
+```
+
+0. We import Nada algebra using `import nada_algebra as na`.
+1. We create an array of parties, with our wrapper using `parties = na.parties(3)` which creates an array of parties named: `Party0`, `Party1` and `Party2`.
+2. We create our input array `a` with `na.array([3], parties[0], "A")`, meaning our array will have dimension 3, `Party0` will be in charge of giving its inputs and the name of the variable is `"A"`.
+3. We create our input array `b` with `na.array([3], parties[1], "B")`, meaning our array will have dimension 3, `Party1` will be in charge of giving its inputs and the name of the variable is `"B"`.
+4. Then, we use the `dot` function to compute the dot product like `a.dot(b)`, which will encompass all the functionality.
+5. Finally, we use Nada Algebra to produce the outputs of the array like:  `result.output(parties[2], "my_output")` establishing that the output party will be `Party2`and the name of the output variable will be `my_output`. 
+# How to run the tutorial.
+
+1. First, we need to compile the nada program running: `nada build`.
+2. Then, we can test our program is running with: `nada test`. 
+
+Inspecting `tests/dot-product.yml`, we see how the inputs for the file are two vectors of 3s: 
+
+$$ A = (3, 3, 3), B = (3, 3, 3)$$
+And we obtain:
+$$A \times B = 3 \cdot 3 + 3 \cdot 3 + 3 \cdot 3 = 27$$

examples/dot_product/nada-project.toml

@@ -0,0 +1,7 @@
+name = "dot_product"
+version = "0.1.0"
+authors = [""]
+
+[[programs]]
+path = "src/main.py"
+prime_size = 128

examples/dot_product/src/main.py

@@ -0,0 +1,21 @@
+from nada_dsl import *
+
+# Step 0: Nada Algebra is imported with this line
+import nada_algebra as na
+
+
+def nada_main():
+    # Step 1: We use Nada Algebra wrapper to create "Party0", "Party1" and "Party2"
+    parties = na.parties(3)
+
+    # Step 2: Party0 creates an array of dimension (3, ) with name "A"
+    a = na.array([3], parties[0], "A")
+
+    # Step 3: Party1 creates an array of dimension (3, ) with name "B"
+    b = na.array([3], parties[1], "B")
+
+    # Step 4: The result is of computing the dot product between the two
+    result = a.dot(b)
+
+    # Step 5: We can use result.output() to produce the output for Party2 and variable name "my_output"
+    return result.output(parties[1], "my_output")

examples/dot_product/target/.gitignore

@@ -0,0 +1,5 @@
+# This directory is kept purposely, so that no compilation errors arise.
+# Ignore everything in this directory
+*
+# Except this file
+!.gitignore

examples/dot_product/tests/dot-product.yaml

@@ -0,0 +1,20 @@
+---
+program: main
+inputs:
+  secrets:
+    A_0:
+      SecretInteger: "3"
+    A_1:
+      SecretInteger: "3"
+    A_2:
+      SecretInteger: "3"
+    B_0:
+      SecretInteger: "3"
+    B_1:
+      SecretInteger: "3"
+    B_2:
+      SecretInteger: "3"
+  public_variables: {}
+expected_outputs:
+  my_output_0:
+    SecretInteger: "27"

examples/matrix_multiplication/README.md

@@ -0,0 +1,56 @@
+# Matrix Multiplication Tutorial
+
+This tutorial shows how to efficiently program a matrix multiplication in Nada using Nada Algebra. 
+
+```python
+from nada_dsl import *
+# Step 0: Nada Algebra is imported with this line
+import nada_algebra as na
+
+
+def nada_main():
+    # Step 1: We use Nada Algebra wrapper to create "Party0", "Party1" and "Party2"
+    parties = na.parties(3)
+
+    # Step 2: Party0 creates an array of dimension (3 x 3) with name "A"
+    a = na.array([3, 3], parties[0], "A")
+
+    # Step 3: Party1 creates an array of dimension (3 x 3) with name "B"
+    b = na.array([3, 3], parties[1], "B")
+
+    # Step 4: The result is of computing the dot product between the two which is another (3 x 3) matrix
+    result = a @ b
+
+    # Step 5: We can use result.output() to produce the output for Party2 and variable name "my_output"
+    return result.output(parties[1], "my_output")
+
+```
+
+0. We import Nada algebra using `import nada_algebra as na`.
+1. We create an array of parties, with our wrapper using `parties = na.parties(3)` which creates an array of parties named: `Party0`, `Party1` and `Party2`.
+2. We create our input array `a` with `na.array([3], parties[0], "A")`, meaning our array will have dimension 3, `Party0` will be in charge of giving its inputs and the name of the variable is `"A"`.
+3. We create our input array `b` with `na.array([3], parties[1], "B")`, meaning our array will have dimension 3, `Party1` will be in charge of giving its inputs and the name of the variable is `"B"`.
+4. Then, we use the `dot` function to compute the dot product like `a.dot(b)`, which will encompass all the functionality.
+5. Finally, we use Nada Algebra to produce the outputs of the array like:  `result.output(parties[2], "my_output")` establishing that the output party will be `Party2`and the name of the output variable will be `my_output`. 
+
+# How to Run the Tutorial
+
+1. Start by compiling the Nada program using the command:
+   ```
+   nada build
+   ```
+
+2. Next, ensure that the program functions correctly by testing it with:
+   ```
+   nada test
+   ```
+
+Upon inspecting the `tests/matrix-multiplication.yml` file, you'll observe that the inputs consist of two matrices with dimensions (3 x 3):
+
+$$
+A = \begin{pmatrix} 1 & 2 & 3 \\ 4 & 5 & 6 \\ 7 & 8 & 9 \end{pmatrix}, \quad B = \begin{pmatrix} 1 & 2 & 3 \\ 4 & 5 & 6 \\ 7 & 8 & 9 \end{pmatrix}
+$$
+And we obtain an output matrix:
+
+$$
+C = A \times B = \begin{pmatrix} 1 \cdot 1 + 2 \cdot 4 + 3 \cdot 7  & 1 \cdot 2 + 2 \cdot 5 + 3 \cdot 8  & 1 \cdot 3 + 2 \cdot 6 + 3 \cdot 9  \\ 4 \cdot 1 + 5 \cdot 4 + 6 \cdot 7  &  4 \cdot 2 + 5 \cdot 5 + 6 \cdot 8  & 4 \cdot 3 + 4 \cdot 6 + 6 \cdot 9 \\ 7 \cdot 1 + 8 \cdot 4 + 9 \cdot 7  &  7 \cdot 2 + 8 \cdot 5 + 9 \cdot 8  & 7 \cdot 3 + 8 \cdot 6 + 9 \cdot 9 \end{pmatrix} = \begin{pmatrix} 30 & 36 & 42 \\ 66 & 81 & 96 \\ 102 & 126 & 150 \end{pmatrix} $$ 

examples/matrix_multiplication/nada-project.toml

@@ -0,0 +1,7 @@
+name = "matrix_multiplication"
+version = "0.1.0"
+authors = [""]
+
+[[programs]]
+path = "src/main.py"
+prime_size = 128

examples/matrix_multiplication/src/main.py

@@ -0,0 +1,21 @@
+from nada_dsl import *
+
+# Step 0: Nada Algebra is imported with this line
+import nada_algebra as na
+
+
+def nada_main():
+    # Step 1: We use Nada Algebra wrapper to create "Party0", "Party1" and "Party2"
+    parties = na.parties(3)
+
+    # Step 2: Party0 creates an array of dimension (3 x 3) with name "A"
+    a = na.array([3, 3], parties[0], "A")
+
+    # Step 3: Party1 creates an array of dimension (3 x 3) with name "B"
+    b = na.array([3, 3], parties[1], "B")
+
+    # Step 4: The result is of computing the dot product between the two which is another (3 x 3) matrix
+    result = a @ b
+
+    # Step 5: We can use result.output() to produce the output for Party2 and variable name "my_output"
+    return result.output(parties[1], "my_output")

examples/matrix_multiplication/target/.gitignore

@@ -0,0 +1,5 @@
+# This directory is kept purposely, so that no compilation errors arise.
+# Ignore everything in this directory
+*
+# Except this file
+!.gitignore

examples/matrix_multiplication/tests/matrix-multiplication.yaml

@@ -0,0 +1,60 @@
+---
+program: main
+inputs:
+  secrets:
+    A_0_0:
+      SecretInteger: "1"
+    A_0_1:
+      SecretInteger: "2"
+    A_0_2:
+      SecretInteger: "3"
+    A_1_0:
+      SecretInteger: "4"
+    A_1_1:
+      SecretInteger: "5"
+    A_1_2:
+      SecretInteger: "6"
+    A_2_0:
+      SecretInteger: "7"
+    A_2_1:
+      SecretInteger: "8"
+    A_2_2:
+      SecretInteger: "9"
+    B_0_0:
+      SecretInteger: "1"
+    B_0_1:
+      SecretInteger: "2"
+    B_0_2:
+      SecretInteger: "3"
+    B_1_0:
+      SecretInteger: "4"
+    B_1_1:
+      SecretInteger: "5"
+    B_1_2:
+      SecretInteger: "6"
+    B_2_0:
+      SecretInteger: "7"
+    B_2_1:
+      SecretInteger: "8"
+    B_2_2:
+      SecretInteger: "9"
+  public_variables: {}
+expected_outputs:
+    my_output_0_0:
+      SecretInteger: "30"
+    my_output_0_1:
+      SecretInteger: "36"
+    my_output_0_2:
+      SecretInteger: "42"
+    my_output_1_0:
+      SecretInteger: "66"
+    my_output_1_1:
+      SecretInteger: "81"
+    my_output_1_2:
+      SecretInteger: "96"
+    my_output_2_0:
+      SecretInteger: "102"
+    my_output_2_1:
+      SecretInteger: "126"
+    my_output_2_2:
+      SecretInteger: "150"