Update docs for v3.1 (#650)

docs/docs/icicle/colab-instructions.md

@@ -90,19 +90,48 @@ Now we are ready to clone ICICE repository,
 !git clone https://github.com/ingonyama-zk/icicle.git
 ```
 
-We now can browse the repository and run tests to check the runtime environment:
+We can browse the repository and run tests to check the runtime environment:
 
 ```sh
 !ls -la
-%cd icicle
+%cd /content/icicle
 ```
 
+## Download CUDA backend
+
+First let's create a backend directory
+
+```sh
+%cd /content
+!rm -rf cuda_backend/
+!mkdir cuda_backend
+%cd cuda_backend
+```
+
+Download and extract a backend from [ICICLE released](https://github.com/ingonyama-zk/icicle/releases) backends
+In this example we are using [ICICLE Cuda backend v3.1.0](https://github.com/ingonyama-zk/icicle/releases/download/v3.1.0/icicle_3_1_0-ubuntu22-cuda122.tar.gz)
+
+```sh
+!curl -O -L https://github.com/ingonyama-zk/icicle/releases/download/v3.1.0/icicle_3_1_0-ubuntu22-cuda122.tar.gz
+!tar -xvf icicle_3_1_0-ubuntu22-cuda122.tar.gz
+```
+
+## Setting CUDA backend installation directory
+Point colab to the extracted cuda backend using an [environment variable](https://github.com/ingonyama-zk/icicle/blob/f638e9d3056d2a5d6271a67ba4f63973a2ba2c1a/docs/docs/icicle/getting_started.md#backend-loading)
+
+```sh
+import os
+os.envvar["ICICLE_BACKEND_INSTALL_DIR"] = "/content/cuda_backend/icicle"
+```
+
+## Fun with ICICLE
+
 Let's run a test!
 Navigate to icicle/wrappers/rust/icicle-curves/icicle-bn254 and run cargo test:
 
 ```sh
-%cd wrappers/rust/icicle-curves/icicle-bn254/
-!cargo test --release
+%cd /content/icicle/wrappers/rust/icicle-curves/icicle-bn254/
+!cargo test --release -- ntt
 ```
 
 :::note
@@ -114,25 +143,20 @@ Compiling the first time may take a while
 Test run should end like this:
 
 ```sh
-running 15 tests
-test curve::tests::test_ark_point_convert ... ok
-test curve::tests::test_ark_scalar_convert ... ok
-test curve::tests::test_affine_projective_convert ... ok
-test curve::tests::test_point_equality ... ok
-test curve::tests::test_field_convert_montgomery ... ok
-test curve::tests::test_scalar_equality ... ok
-test curve::tests::test_points_convert_montgomery ... ok
-test msm::tests::test_msm ... ok
-test msm::tests::test_msm_skewed_distributions ... ok
+running 9 tests
+[WARNING] Defaulting to Ingonyama icicle-cuda-license-server at `[email protected]`. For more information about icicle-cuda-license, please contact [email protected].
+[INFO] ICICLE backend loaded from $ICICLE_BACKEND_INSTALL_DIR=/content/cuda_backend/icicle
+test ecntt::tests::test_ecntt::test_ecntt_batch ... ok
 test ntt::tests::test_ntt ... ok
 test ntt::tests::test_ntt_arbitrary_coset ... ok
-test msm::tests::test_msm_batch has been running for over 60 seconds
-test msm::tests::test_msm_batch ... ok
+test ntt::tests::test_ntt_batch ... ok
 test ntt::tests::test_ntt_coset_from_subgroup ... ok
+test ntt::tests::test_ntt_coset_interpolation_nm ... ok
+test ecntt::tests::test_ecntt::test_ecntt ... ok
 test ntt::tests::test_ntt_device_async ... ok
-test ntt::tests::test_ntt_batch ... ok
+test ntt::tests::test_ntt_release_domain ... ok
 
-test result: ok. 15 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 99.39s
+test result: ok. 9 passed; 0 failed; 0 ignored; 0 measured; 36 filtered out; finished in 42.71s
 ```
 
 Viola, ICICLE in Colab!

docs/docs/icicle/getting_started.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-This guide will walk you through the entire process of building, testing, and installing ICICLE using your preferred programming language—C++, Rust, or Go. Whether you're deploying on a CPU or leveraging CUDA for accelerated performance, this guide provides comprehensive instructions to get you started. It also outlines the typical workflow for a user, including key installation steps:
+This guide will walk you through the entire process of building, testing, and installing ICICLE using your preferred programming language: C++, Rust, or Go. Whether you're deploying on a CPU or leveraging CUDA for accelerated performance, this guide provides comprehensive instructions to get you started. It also outlines the typical workflow for a user, including key installation steps:
 
 
 1. **Install ICICLE or build it from source**: This is explained in this guide. For building from source, refer to the [Build from Source page](./build_from_source.md).
@@ -141,7 +141,7 @@ pub fn load_backend_from_env_or_default() -> Result<(), eIcicleError>;
 ```
 **Go**
 ```go
-TODO
+func LoadBackendFromEnvOrDefault() EIcicleError
 ```
 
 ### Custom Backend Loading
@@ -164,5 +164,7 @@ extern "C" eIcicleError icicle_load_backend(const char* path, bool is_recursive)
 
 **Go**
 ```go
-TODO
+func LoadBackend(path string, isRecursive bool) EIcicleError
 ```
+- **`path`**: The directory where the backend libraries are located.
+- **`isRecursive`**: If `true`, the function will search for backend libraries recursively within the specified path.

docs/docs/icicle/multi-device.md

@@ -76,4 +76,4 @@ extern "C" eIcicleError icicle_get_device_count(int& device_count /*OUT*/);
 - **Launch One CPU Thread per Device:** To avoid [common errors](https://developer.nvidia.com/blog/cuda-pro-tip-always-set-current-device-avoid-multithreading-bugs/) and ensure code readability, we recommend creating a dedicated thread for each device. Within each CPU thread, you can launch as many tasks as you like for a device, as long as they all run on the same device ID. This will make your code more manageable, easier to read, and performant.
 ---
 
-This guide provides an overview of multi-device support in ICICLE, explaining the approaches and best practices for efficiently scaling ZK computations across multiple devices. For further information or support, please refer to our [documentation](./) or join the discussion on [Discord](https://discord.gg/6vYrE7waPj).
+This guide provides an overview of multi-device support in ICICLE, explaining the approaches and best practices for efficiently scaling ZK computations across multiple devices. For further information or support, please refer to our [documentation](../introduction.md) or join the discussion on [Discord](https://discord.gg/6vYrE7waPj).

docs/docs/icicle/overview.md

@@ -56,7 +56,7 @@ For a detailed guide on setting up Google Colab with ICICLE, refer to [this arti
 
 [ICICLE](https://github.com/ingonyama-zk/icicle) can be used similarly to any other cryptography library. Through various integrations, ICICLE has proven effective in multiple use cases:
 
-### Circuit Developers
+### Boost Your ZK Prover Performance
 
 If you're a circuit developer facing bottlenecks, integrating ICICLE into your prover may solve performance issues. ICICLE is integrated into popular ZK provers like [Gnark](https://github.com/Consensys/gnark) and [Halo2](https://github.com/zkonduit/halo2), enabling immediate GPU acceleration without additional code changes.
 

docs/docs/icicle/primitives/hash.md

@@ -67,8 +67,13 @@ auto keccak512 = Keccak512::create();
 auto sha3_256 = Sha3_256::create();
 auto sha3_512 = Sha3_512::create();
 auto blake2s = Blake2s::create();
-// Poseidon requires specifying the field type and arity (supported 3,5,9,12)
-auto poseidon = Poseidon::create<scalar_t>(arity); 
+// Poseidon requires specifying the field-type and t parameter (supported 3,5,9,12) as defined by the Poseidon paper.
+auto poseidon = Poseidon::create<scalar_t>(t); 
+// Optionally, Poseidon can accept a domain-tag, which is a field element used to separate applications or contexts.
+// The domain tag acts as the first input to the hash function, with the remaining t-1 inputs following it.
+scalar_t domain_tag = scalar_t::zero(); // Example using zero; this can be set to any valid field element.
+auto poseidon_with_domain_tag = Poseidon::create<scalar_t>(t, &domain_tag);
+// This version of the hasher with a domain tag expects t-1 additional inputs for hashing.
 ```
 
 ### 2. Hashing Data

docs/docs/icicle/primitives/msm.md

@@ -152,7 +152,7 @@ msm(..., config,...); // msm backend is reading the config-extension
 
 ### Choosing optimal parameters
 
-`is_big_triangle` should be `false` in almost all cases. It might provide better results only for very small MSMs (smaller than 2^8^) with a large batch (larger than 100) but this should be tested per scenario.
+`is_big_triangle` should be `false` in almost all cases. It might provide better results only for very small MSMs (smaller than 2^8) with a large batch (larger than 100) but this should be tested per scenario.
 Large buckets exist in two cases:
 1. When the scalar distribution isn't uniform.
 2. When `c` does not divide the scalar bit-size.

docs/docs/icicle/primitives/ntt.md

@@ -117,7 +117,7 @@ template <typename S> S get_root_of_unity(uint64_t max_size);
 
 Finally, release the domain to free up device memory when not required:
 ```cpp
-template <typename S> S get_root_of_unity(uint64_t max_size);
+template <typename S> eIcicleError ntt_release_domain();
 ```
 
 where
@@ -169,7 +169,7 @@ To compute a batch, set the `batch_size` and `columns_batch` fields of the confi
 
 ### Example
 
-The following example demonstartes how to use ntt and how pass custom configurations to the CUDA backend. This is discussed below.
+The following example demonstartes how to use ntt and how pass custom configurations to the CUDA backend. Details are discussed below.
 
 ```cpp
 #include "icicle/backend/ntt_config.h"

docs/docs/icicle/programmers_guide/go.md

@@ -292,5 +292,3 @@ if result != runtime.SUCCESS {
     // Handle error
 }
 ```
-
-This guide provides an overview of the essential APIs available in Icicle for C++. The provided examples should help you get started with integrating Icicle into your high-performance computing projects.

docs/docs/icicle/rust-bindings/hash.md

@@ -70,25 +70,41 @@ The Poseidon hash is designed for cryptographic field elements and curves, makin
 Poseidon hash using babybear field:
 
 ```rust
-    use icicle_babybear::field::{ScalarCfg, ScalarField};
-    use icicle_core::hash::HashConfig;
-    use icicle_core::poseidon::{Poseidon, PoseidonHasher};
-    use icicle_core::traits::FieldImpl;
-    use icicle_runtime::memory::HostSlice;
-
-    let batch = 1 << 10;
-    let arity = 3;
-    let inputs = ScalarCfg::generate_random(batch * arity);
-    let mut outputs = vec![ScalarField::zero(); batch]; // note output array is sized for batch
-
-    let poseidon_hasher = Poseidon::new::<ScalarField>(arity as u32).unwrap();
-
-    poseidon_hasher
-        .hash(
-            HostSlice::from_slice(&inputs),
-            &HashConfig::default(),
-            HostSlice::from_mut_slice(&mut outputs),
-        )
-        .unwrap();
+use icicle_babybear::field::{ScalarCfg, ScalarField};
+use icicle_core::hash::HashConfig;
+use icicle_core::poseidon::{Poseidon, PoseidonHasher};
+use icicle_core::traits::FieldImpl;
+use icicle_runtime::memory::HostSlice;
+
+let batch = 1 << 10; // Number of hashes to compute in a single batch
+let t = 3; // Poseidon parameter that specifies the arity (number of inputs) for each hash function
+let mut outputs = vec![ScalarField::zero(); batch]; // Output array sized for the batch count
+
+// Case (1): Hashing without a domain tag
+// Generates 'batch * t' random input elements as each hash needs 't' inputs
+let inputs = ScalarCfg::generate_random(batch * t);
+let poseidon_hasher = Poseidon::new::<ScalarField>(t as u32, None /*=domain-tag*/).unwrap(); // Instantiate Poseidon without domain tag
+
+poseidon_hasher
+    .hash(
+        HostSlice::from_slice(&inputs),           // Input slice for the hash function
+        &HashConfig::default(),                   // Default hashing configuration
+        HostSlice::from_mut_slice(&mut outputs),  // Output slice to store hash results
+    )
+    .unwrap();
+
+// Case (2): Hashing with a domain tag
+// Generates 'batch * (t - 1)' inputs, as domain tag counts as one input in each hash
+let inputs = ScalarCfg::generate_random(batch * (t - 1));
+let domain_tag = ScalarField::zero(); // Example domain tag (can be any valid field element)
+let poseidon_hasher_with_domain_tag = Poseidon::new::<ScalarField>(t as u32, Some(&domain_tag) /*=domain-tag*/).unwrap();
+
+poseidon_hasher_with_domain_tag
+    .hash(
+        HostSlice::from_slice(&inputs),           // Input slice with 't - 1' elements per hash
+        &HashConfig::default(),                   // Default hashing configuration
+        HostSlice::from_mut_slice(&mut outputs),  // Output slice to store hash results
+    )
+    .unwrap();
 ```
 

docs/docusaurus.config.js

@@ -29,7 +29,7 @@ const config = {
           remarkPlugins: [math, require('mdx-mermaid')],
           rehypePlugins: [katex],
           sidebarPath: require.resolve('./sidebars.js'),
-          editUrl: 'https://github.com/ingonyama-zk/icicle/tree/main',
+          editUrl: 'https://github.com/ingonyama-zk/icicle/tree/main/docs',
         },
         blog: {
           remarkPlugins: [math, require('mdx-mermaid')],

docs/sidebars.js

@@ -75,11 +75,11 @@ module.exports = {
               label: "Multi-Device Support",
               id: "icicle/multi-device",
             },
-            {
-              type: "doc",
-              label: "Build Your Own Backend",
-              id: "icicle/build_your_own_backend"
-            },
+            // {
+            //   type: "doc",
+            //   label: "Build Your Own Backend",
+            //   id: "icicle/build_your_own_backend"
+            // },
           ]
         },
         {
@@ -241,16 +241,16 @@ module.exports = {
           label: "Migrate from ICICLE v2",
           id: "icicle/migrate_from_v2",
         },
-        {
-          type: "doc",
-          label: "Benchmarks",
-          id: "icicle/benchmarks",
-        },
-        {
-          type: "doc",
-          label: "FAQ and Troubleshooting",
-          id: "icicle/faq_and_troubleshooting",
-        },
+        // {
+        //   type: "doc",
+        //   label: "Benchmarks",
+        //   id: "icicle/benchmarks",
+        // },
+        // {
+        //   type: "doc",
+        //   label: "FAQ and Troubleshooting",
+        //   id: "icicle/faq_and_troubleshooting",
+        // },
         {
           type: "doc",
           label: "Google Colab Instructions",