docs: added support and examples, updates

Cargo.toml

@@ -4,7 +4,7 @@ version = "0.1.5"
 edition = "2021"
 description = "Rust package of the OpenFHE Fully Homomorphic Encryption Library."
 license = "BSD-2-Clause"
-documentation = "https://fair-math.gitbook.io/docs/"
+documentation = "https://openfhe-rust-wrapper.readthedocs.io/"
 repository = "https://github.com/fairmath/openfhe-rs"
 
 [dependencies]

docs/source/function_evaluation.rst

@@ -0,0 +1,71 @@
+Arbitrary smooth function evaluation in CKKS via OpenFHE-rs
+===========================================================
+
+Overview
+--------
+
+This document describes how to evaluate an arbitrary smooth function on a ciphertext in CKKS using `Chebyshev approximation <https://www.gnu.org/software/gsl/doc/html/cheb.html>`_.
+The Chebyshev approximation is a method of approximating a smooth function using polynomials, see more `on Wiki <https://en.wikipedia.org/wiki/Chebyshev_polynomials>`_.
+
+Rust example
+------------
+
+The example for this code is located in `examples/function_evaluation.rs <https://github.com/fairmath/openfhe-rs/blob/master/examples/function_evaluation.rs>`_.
+The file gives examples of how to run `EvalLogistic`, the logistic function $\frac{1}{1 + e^{-x}}$, and an arbitrary function using `EvalChebyshevFunction`.
+We use the square root function in our example for `EvalChebyshevFunction`.
+
+Input parameters
+----------------
+
+Our Rust wrapper is based on the original OpenFHE interface; `EvalLogistic` function requires the following input parameters:
+
+- `ciphertext`: the ciphertext we wish to operate on.
+- `a`: the lower bound of underlying plaintext values we could have.
+- `b`: the upper bound of underlying plaintext values we could have.
+- `degree`: the desired polynomial degree of the Chebyshev approximation.
+  A higher degree gives a more precise estimate but takes longer to run.
+
+Running the example
+-------------------
+
+1. Ensure the `openfhe-rs` library is installed and properly configured, see the `Installation guide <../getting-started/installation.md>`.
+2. Go to the `examples` directory and make sure that the needed example is there - `function_evaluation.rs`.
+3. Compile and run the Rust file:
+
+   .. code-block:: sh
+
+      rustc function_evaluation.rs -o function_evaluation
+      ./function_evaluation
+
+   This should output the results of the homomorphic computations to the console.
+
+How to choose a multiplicative depth
+-------------------------------------
+
+Each run of `EvalChebyshevFunction` requires a certain number of multiplications which depends on the input polynomial degree.
+We provide a table below to map polynomial degrees to multiplicative depths.
+
++-------------+---------------------+
+| Degree      | Multiplicative Depth|
++=============+=====================+
+| 3-5         | 4                   |
++-------------+---------------------+
+| 6-13        | 5                   |
++-------------+---------------------+
+| 14-27       | 6                   |
++-------------+---------------------+
+| 28-59       | 7                   |
++-------------+---------------------+
+| 60-119      | 8                   |
++-------------+---------------------+
+| 120-247     | 9                   |
++-------------+---------------------+
+| 248-495     | 10                  |
++-------------+---------------------+
+| 496-1007    | 11                  |
++-------------+---------------------+
+| 1008-2031   | 12                  |
++-------------+---------------------+
+
+Note that for a range $(a, b) = (-1, 1)$, the multiplicative depth is 1 less than the depths listed in the table.
+

docs/source/index.rst

@@ -24,7 +24,7 @@ OpenFHE-rs is a joint project by `Fair Math <https://fairmath.xyz/>`_ & `OpenFHE
 
 .. note::
 
-   🔔 Keep in mind that the library is WIP and may contain some unpolished interfaces. If you encounter any issues or have any suggestions, feel free to ping us on our Discord server or open a new issue in the `GitHub repository <https://github.com/fairmath/openfhe-rs/tree/master>`_.
+   🔔 Keep in mind that the library is WIP and may contain some unpolished interfaces. If you encounter any issues or have any suggestions, feel free to look for :doc:`support`.
 
 OpenFHE-rs is a Rust interface for the OpenFHE library, which is renowned for its comprehensive suite of Fully Homomorphic Encryption (FHE) schemes, all implemented in C++. By providing a Rust wrapper for OpenFHE, we aim to make these advanced FHE capabilities easily accessible to Rust developers.
 
@@ -40,5 +40,8 @@ Contents
    intro
    limitations
    base_types_and_alg
+   support
    simple_integers
    simple_real_numbers
+   function_evaluation
+   polynomial_evaluation

docs/source/intro.rst

@@ -141,5 +141,5 @@ Contributions are always welcome! If you find bugs, have feature requests, or wa
 License
 =======
 
-`OpenFHE-rs` is licensed under the **BSD 2-Clause License**. See the `LICENSE <LICENSE>`_ file for more details.
+`OpenFHE-rs` is licensed under the **BSD 2-Clause License**. See the `LICENSE <https://github.com/fairmath/openfhe-rs/blob/master/LICENSE>`_ file for more details.
 

docs/source/limitations.rst

@@ -9,13 +9,12 @@ See the `Security Notes for Homomorphic Encryption <https://openfhe-development.
 Rust wrapper
 ------------
 
-The library is WIP and may contain some unpolished interfaces. If you struggle with anything or have suggestions, feel free to ping us on our Discord server or open a new issue in the `GitHub repository <https://github.com/fairmath/openfhe-rs/tree/master>`_.
-
 At the moment, only a certain set of OpenFHE functionality has been implemented.
 
-We use the `CXX crate <https://cxx.rs/>`_ for our Rust binding to reduce the amount of abstraction levels. OpenFHE types are represented as opaque types on the Rust side using `cxx::UniquePtr <https://docs.rs/cxx/latest/cxx/struct.UniquePtr.html>`_ from the CXX crate. Instead of the usual `std::vec <https://doc.rust-lang.org/std/vec/>`_, we use `cxx::CxxVector <https://docs.rs/cxx/latest/cxx/struct.CxxVector.html>`_ for primitive types, and also `CxxVector<ComplexPair>` for representing `std::vector<std::complex<double>>` type.
+We use the `CXX crate <https://cxx.rs/>`_ for our Rust binding to reduce the amount of abstraction levels. OpenFHE types are represented as opaque types on the Rust side using `cxx::UniquePtr <https://docs.rs/cxx/latest/cxx/struct.UniquePtr.html>`_ from the CXX crate. Instead of the usual `std::vec <https://doc.rust-lang.org/std/vec/>`_, we use `cxx::CxxVector <https://docs.rs/cxx/latest/cxx/struct.CxxVector.html>`_ for primitive types, and also `cxx::CxxVector<ComplexPair>` for representing `std::vector<std::complex<double>>` type.
 
-The main difference lies in the current `cxx::CxxVector` supported functional, limited compared to `std::vector`, e.g. you need to init `cxx::CxxVector` element by element. Since `cxx` currently does not support `cxx::CxxVector` of opaque types, we are using a separate type for each vector of opaque type. Since `cxx` currently does not support alternatives for `std::unordered_map` and `std::map`, we are using separate types for them. The implementations of these types are very simple because we are planning to switch `cxx` variants further. But before switching these types can be extended to support basic functional of `std::vector`, `std::map` and `std::unordered_map` if required.
+The main difference lies in the current `cxx::CxxVector` supported functional, limited compared to `std::vector`, e.g. you need to init `cxx::CxxVector` element by element. Since `cxx` currently does not support `cxx::CxxVector` of opaque types, we are using a separate type for each vector of opaque type. Since `CXX` currently does not support alternatives for `std::unordered_map` and `std::map`, we are using separate types for them. The implementations of these types are very simple because we are planning to switch `cxx` variants further. But before switching these types can be extended to support basic functional of `std::vector`, `std::map` and `std::unordered_map` if required.
 
-Since Rust does not support default parameters and function overloading, default parameters are mentioned in comments after the corresponding parameter name, and overloaded functions are represented by slightly different names. Calling member functions of generated null types (generated by GenNull... functions) results in undefined behavior. Since `CXX` crate has limited support for function pointers - only functions without a return type are supported) - EvalChebychevFunction expects `fn(f64, ret: &mut f64)` as the callable object.
+Since Rust does not support default parameters and function overloading, default parameters are mentioned in comments after the corresponding parameter name, and overloaded functions are represented by slightly different names. Calling member functions of instances, generated by GenNull… functions results in undefined behavior.
 
+Since `CXX` crate has limited support for function pointers (only functions without a return type are supported), EvalChebychevFunction expects fn(f64, ret: &mut f64) as the callable object.

docs/source/polynomial_evaluation.rst

@@ -0,0 +1,42 @@
+Polynomial evaluation in CKKS via OpenFHE-rs
+=============================================
+
+Overview
+--------
+
+This document describes how to call polynomial evaluation on a ciphertext in CKKS.
+Polynomial evaluation refers to the computation of the value of a polynomial when its indeterminates are substituted for some values, see more `on Wiki <https://en.wikipedia.org/wiki/Polynomial_evaluation>`_.
+
+Rust example
+------------
+
+The example for this code is located in `examples/polynomial_evaluation.rs <https://github.com/fairmath/openfhe-rs/blob/master/examples/polynomial_evaluation.rs>`_.
+This code gives an example of how to run `EvalPoly` function and outputs in the log input parameters, the result of evaluation and the evaluation time.
+
+Input parameters
+----------------
+
+Our Rust wrapper is based on the original OpenFHE interface; `EvalPoly` function requires the following input parameters:
+
+- `ciphertext`: the ciphertext we wish to operate on.
+- `coefficients`: the coefficients to run polynomial evaluation upon, a vector array of doubles.
+  In this example, we run the evaluation upon two sets of coefficients:
+
+    1. {0.15, 0.75, 0, 1.25, 0, 0, 1, 0, 1, 2, 0, 1, 0, 0, 0, 0, 1}
+    2. {1, 2, 3, 4, 5, -1, -2, -3, -4, -5, 0.1, 0.2, 0.3, 0.4, 0.5, -0.1, -0.2, -0.3, -0.4, -0.5, 0.1, 0.2, 0.3, 0.4, 0.5, -0.1, -0.2, -0.3, -0.4, -0.5}.
+
+For this example, we set the multiplicative depth at 6 and the scaling mod size at 50.
+
+Running the example
+-------------------
+
+1. Ensure the `openfhe-rs` library is installed and properly configured, see the `Installation guide <../getting-started/installation.md>`.
+2. Go to the `examples` directory and make sure that the needed example is there - `polynomial_evaluation.rs`.
+3. Compile and run the Rust file:
+
+   .. code-block:: sh
+
+      rustc polynomial_evaluation.rs -o polynomial_evaluation
+      ./polynomial_evaluation
+
+   This should output the results of the homomorphic computations to the console.

docs/source/support.rst

@@ -0,0 +1,17 @@
+Help
+----
+
+If you have any questions, you can:
+
+- Contact us by email: support@fherma.io
+- Join our `Discord server <https://discord.gg/NfhXwyr9M5>`_, and ask your questions in the `#fherma channel <https://discord.com/channels/1163764915803279360/1167875954392187030>`.
+- Open an issue in the `GitHub Repository <https://github.com/fairmath/openfhe-rs/tree/master>`_.
+- Use `OpenFHE Discourse <https://openfhe.discourse.group/>`_ for OpenFHE related issues.
+
+Useful Links
+------------
+
+- `OpenFHE documentation <https://openfhe-development.readthedocs.io/en/latest/>`_
+- `OpenFHE repository <https://github.com/openfheorg/openfhe-development>`_, README, and installation guide.
+- `OpenFHE Python repository <https://github.com/openfheorg/openfhe-python>`_, README, and installation guide.
+- A vast collection of resources collected by `FHE.org <http://fhe.org/>`_, `FHE resources <https://fhe.org/resources>`_: including tutorials and walk-throughs, use-cases and demos.