doc: let's document the framework

refs #143

docs/README.md

@@ -20,13 +20,13 @@ Basically, we have divided our documentation into several parts:
 
 ## A work in progress
 
-Concrete is a work in progress, and is currently limited to a certain number of operators and features. In the future, there will be improvements as described in this [section](user/explanation/FUTURE_FEATURES.md). 
+Concrete is a work in progress, and is currently limited to a certain number of operators and features. In the future, there will be improvements as described in this [section](user/explanation/FUTURE_FEATURES.md).
 
 The main _current_ limits are:
 - Concrete is only supporting unsigned integers
 - Concrete needs the integer to be less than 7 bits (included)
 - Concrete is mostly restricted to scalars (by opposition to tensors). The only exception is the `dot` operator, which can dot a tensor of encrypted values with a tensor of constant values
 
-The first two limits can be taken care of with the use of quantization, as explained a bit further in [this](user/explanation/QUANTIZATION.md) and [this](user/howto/REDUCE_NEEDED_PRECISION.md) parts of the documentation. 
+The first two limits can be taken care of with the use of quantization, as explained a bit further in [this](user/explanation/QUANTIZATION.md) and [this](user/howto/REDUCE_NEEDED_PRECISION.md) parts of the documentation.
 
-The scalar limitation is mainly an engineering issue, and will be fixed in the next release. Today, one needs to split all the tensors into small scalars, which is inconvenient and will be no more needed very soon. 
+The scalar limitation is mainly an engineering issue, and will be fixed in the next release. Today, one needs to split all the tensors into small scalars, which is inconvenient and will be no more needed very soon.

docs/_static/css/zama.css

@@ -26,7 +26,9 @@
     top: 0;
     left: 50%;
     padding: 0;
-    margin: 0 0 0 -100px !important;
+
+    /* Adjust this to change the adjustment of the Zama's logo, on the top left */
+    margin: 0 0 0 -80px !important;
 }
 
 .rst-content code.literal, .rst-content tt.literal {

docs/conf.py

@@ -17,7 +17,7 @@
 
 # -- Project information -----------------------------------------------------
 
-project = "Homomorphic Development Kit"
+project = "Concrete Framework"
 copyright = "2021, Zama"
 author = "Zama"
 

docs/index.rst

@@ -1,4 +1,4 @@
-Homomorphic Development Kit's documentation
+Concrete Framework's documentation
 ===========================================
 
 
@@ -7,6 +7,7 @@ Homomorphic Development Kit's documentation
    :caption: Basics
 
    README.md
+   Installing <user/howto/INSTALLING.md>
 
 .. toctree::
    :maxdepth: 2
@@ -21,7 +22,7 @@ Homomorphic Development Kit's documentation
    :caption: How to
 
    user/howto/INSTALLING.md
-   user/howto/COMPILE.md
+   user/howto/COMPILING_AND_EXECUTING.md
    user/howto/REDUCE_NEEDED_PRECISION.md
    user/howto/DEBUG_SUPPORT_SUBMIT_ISSUES.md
    user/howto/FAQ.md
@@ -31,7 +32,7 @@ Homomorphic Development Kit's documentation
    :caption: Explanation
 
    user/explanation/WHAT_IS_FHE.md
-   user/explanation/FHE_LIMITS.md
+   user/explanation/FHE_AND_FRAMEWORK_LIMITS.md
    user/explanation/QUANTIZATION.md
    user/explanation/FUTURE_FEATURES.md
 

docs/user/explanation/FHE_AND_FRAMEWORK_LIMITS.md

@@ -0,0 +1,35 @@
+# FHE and Concrete Framework Limits
+
+## FHE Limits
+
+FHE used to be an impossible thing to imagine, twenty years ago. Then, with advances due to [Craig Gentry](https://crypto.stanford.edu/craig/), this became a dream come true. And, even more recently, with several generations of new scheme, FHE became practical. 
+
+### Speed
+
+However, one still has to consider that FHE is slow, as compared to the vanilla implementations. With the different HW pluggins that can be added to Concrete, an important speed factor can be achieved.
+
+### Multiplying by constants
+
+In the scheme used in the Concrete Framework, namely [TFHE](https://tfhe.github.io/tfhe/), multiplications by constants is only defined for integer constants. Notably, one can't multiply by floats. As float multiplication is very usual in the data science (think of weights of dense layers, for example), this could be a problem, but quantization is at our rescue. See [this](QUANTIZATION.md) section for more details.
+
+### Achieving computations of not-linear functions
+
+For most FHE scheme but TFHE, the application of a non-linear function is complicated and slow, if not impossible. Typically, this is a blocker, since activation functions _are_ non-linear. However, in the Concrete Framework, we use an operation called _programmable bootstrapping_ (described in this [white paper](https://whitepaper.zama.ai)), which allows to apply any table lookup: by quantizing the non-linear function, any function can thus be replaced. 
+
+## Concrete Framework Limits
+
+Since this is an early version of the product, not everything is done, to say the least. What we wanted to tackle first was the cryptographic complexities. This is why we concentrated on the cryptographic part, and let some engineering problems for later. 
+
+### Limited to scalars
+
+Today, the Concrete Framework is mostly limited to scalars. Notably, in our numpy frontend, we can not use [tensors](https://numpy.org/doc/stable/user/theory.broadcasting.html?highlight=vector). As explained in [this section](FUTURE_FEATURES.md), this limit will be removed in the next version.
+
+### Currently executing locally
+
+As of today, the execution of the FHE program is done locally. Notably, in the current version, there is no client (on which we encrypt the private data, or decrypt the returned result) or server (on which the computation is done completely over encrypted data), but a single host. As explained in [this section](FUTURE_FEATURES.md), this limit will be removed in the next version, such that the Concrete Framework can be used in production.
+
+### Currently slow
+
+As we explained, we wanted to focus first on cryptographic challenges. Performance has been postponed, and will be tackled in the next release.
+
+

docs/user/explanation/FHE_LIMITS.md

@@ -1,3 +0,0 @@
-# FHE Limits
-
-Benoit to do: write it

docs/user/explanation/FUTURE_FEATURES.md

@@ -1,3 +1,3 @@
 # Future Features
 
-Alex to do: #321
+Alex to do: #321

docs/user/explanation/QUANTIZATION.md

@@ -1,3 +1,3 @@
 # Quantization
 
-Arthur to do: #319
+Arthur to do: #319

docs/user/explanation/WHAT_IS_FHE.md

@@ -1,3 +1,12 @@
 # What is FHE?
 
-Benoit to do: write it
+Fully Homomorphic Encryption (FHE for short) is a technology that enables computing on encrypted data directly, without having to decrypt it.
+Users would encrypt their data using their own secret key, then send it to your servers for processing. Your servers would process the encrypted data blindly, producing a result which itself is encrypted, and that only the user can decrypt with their secret key.
+
+From the user's perspective, nothing changes (but the fact that her data is never in clear on the server), they are still sending data to your service and getting a response. But you now no longer need to worry about securing your user data, as it is now encrypted both in transit and during processing, i.e., it is encrypted end-to-end.
+
+You can learn more about FHE using the following links:
+- [quick overview](https://6min.zama.ai/)
+- [monthly technical FHE.org meetup](https://www.meetup.com/fhe-org/)
+- [videos and resources](http://fhe.org/)
+

docs/user/howto/COMPILE.md

@@ -1,4 +0,0 @@
-# Compiling
-
-Umut or Arthur, who wants to do this part?
-

docs/user/howto/COMPILING_AND_EXECUTING.md

@@ -0,0 +1,10 @@
+# Compiling and Executing
+
+Umut or Arthur, who wants to do this part?
+
+## Compiling
+
+## Executing
+
+
+

docs/user/howto/DEBUG_SUPPORT_SUBMIT_ISSUES.md

@@ -56,4 +56,4 @@ may be useful to us. Don't remember, Concrete is a project where we are open to
 
 ## Submitting an issue
 
-In case you have a bug, which is reproducible, that you have reduced to a small piece of code,  we have our issue tracker (TODO: LINK TO BE ADDED). Remember that a well-described short issue is an issue which is more likely to be studied and fixed. The more issues we receive, the better the product will be.   
+In case you have a bug, which is reproducible, that you have reduced to a small piece of code,  we have our issue tracker (TODO: LINK TO BE ADDED). Remember that a well-described short issue is an issue which is more likely to be studied and fixed. The more issues we receive, the better the product will be.

docs/user/howto/REDUCE_NEEDED_PRECISION.md

@@ -1,3 +1,3 @@
 # Having a Function Which Requires Less Precision
 
-Arthur to do: #319
+Arthur to do: #319