diff --git a/docs/README.md b/docs/README.md index dc8e892b4..3b264ca2b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,3 +1,20 @@ # What is ConcreteFHE -To be done +## Introduction + +ConcreteFHE, or Concrete for short, is a python package which aims to simplify the use of so-called fully homomorphic encryption (FHE) for datascientists. FHE is a new powerful cryptographic tool, which allows e.g. servers to perform computations directly on encrypted data, without needing any kind of secret key. With FHE, privacy is at the center, and one can build services which ensure full privacy of the user and are the perfect equivalent of their unsecure counterpart. FHE is also a killer feature regarding data breaches: as anything done on the server is done over encrypted data, even if the server is compromised, there is in the end no leak of any kind of useful data. + +Concrete framework is made of several parts: +- a library, called concrete-lib, which contains the core cryptographic API's for computing with FHE +- a compiler, called concrete-compiler, which allows to turn an MLIR program into an FHE program, on the top of concrete-lib +- some frontends, which convert different langages to MLIR, to finally be compiled. + +In the first version of Concrete framework, there is a single frontend, called concrete-hnp, which is the equivalent of numpy. With our toolchain, a data scientist can convert a numpy program into an FHE program, without any a-priori knowledge on cryptography. + +## Organization of the Documentation + +Basically, we have divided our documentation into several parts: +- one about basic elements, notably description of the installation, that you are currently reading +- one dedicated to _users_ of Concrete, with tutorials, how-to's and deeper explanations +- and finally, one dedicated to _developpers_ of Concrete, who could be internal or external contributors to the framework + diff --git a/docs/dev/explanation/MLIR.md b/docs/dev/explanation/MLIR.md index 74c37dea7..ad49e6ca3 100644 --- a/docs/dev/explanation/MLIR.md +++ b/docs/dev/explanation/MLIR.md @@ -1,4 +1,4 @@ # MLIR -to be done +To be done by Ayoub, #311 diff --git a/docs/dev/howto/DOCUMENTING.md b/docs/dev/howto/DOCUMENTING.md index b208ac272..1c73f7df1 100644 --- a/docs/dev/howto/DOCUMENTING.md +++ b/docs/dev/howto/DOCUMENTING.md @@ -1,7 +1,7 @@ # Documenting -## Making docs with Sphinx +## Using Sphinx One can simply create docs with Sphinx and open them, by doing: @@ -9,7 +9,9 @@ One can simply create docs with Sphinx and open them, by doing: make docs ``` -The documentation contains both files written by hand by developpers and files automatically created by parsing the source files. +Remark that this needs to be done in docker. + +The documentation contains both files written by hand by developpers (the .md files) and files automatically created by parsing the source files. ### Opening doc diff --git a/docs/index.rst b/docs/index.rst index fcbe69845..803b85f7c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -24,9 +24,7 @@ Homomorphic Development Kit's documentation user/howto/COMPILE.md user/howto/REDUCE_NEEDED_PRECISION.md - user/howto/DEBUG.md - user/howto/SUBMIT_ISSUE.md - user/howto/SUPPORT.md + user/howto/DEBUG_SUPPORT_SUBMIT_ISSUES.md user/howto/FAQ.md .. toctree:: diff --git a/docs/user/explanation/FHE_LIMITS.md b/docs/user/explanation/FHE_LIMITS.md index df9defe8c..4c69ca8a6 100644 --- a/docs/user/explanation/FHE_LIMITS.md +++ b/docs/user/explanation/FHE_LIMITS.md @@ -1,2 +1,3 @@ # FHE Limits +Benoit to do: write it \ No newline at end of file diff --git a/docs/user/explanation/FUTURE_FEATURES.md b/docs/user/explanation/FUTURE_FEATURES.md index 2ee513008..1e2537417 100644 --- a/docs/user/explanation/FUTURE_FEATURES.md +++ b/docs/user/explanation/FUTURE_FEATURES.md @@ -1,2 +1,3 @@ # Future Features +Alex to do: #321 \ No newline at end of file diff --git a/docs/user/explanation/QUANTIZATION.md b/docs/user/explanation/QUANTIZATION.md index 7ab168d56..e007a4481 100644 --- a/docs/user/explanation/QUANTIZATION.md +++ b/docs/user/explanation/QUANTIZATION.md @@ -1,2 +1,3 @@ # Quantization +Arthur to do: #319 \ No newline at end of file diff --git a/docs/user/explanation/WHAT_IS_FHE.md b/docs/user/explanation/WHAT_IS_FHE.md index ce4af9382..233285aab 100644 --- a/docs/user/explanation/WHAT_IS_FHE.md +++ b/docs/user/explanation/WHAT_IS_FHE.md @@ -1 +1,3 @@ # What is FHE? + +Benoit to do: write it diff --git a/docs/user/howto/COMPILE.md b/docs/user/howto/COMPILE.md index 6d6a98c48..77627afdc 100644 --- a/docs/user/howto/COMPILE.md +++ b/docs/user/howto/COMPILE.md @@ -1 +1,4 @@ # Compiling + +Umut or Arthur, who wants to do this part? + diff --git a/docs/user/howto/DEBUG.md b/docs/user/howto/DEBUG.md deleted file mode 100644 index 1e584c954..000000000 --- a/docs/user/howto/DEBUG.md +++ /dev/null @@ -1 +0,0 @@ -# Debugging diff --git a/docs/user/howto/DEBUG_SUPPORT_SUBMIT_ISSUES.md b/docs/user/howto/DEBUG_SUPPORT_SUBMIT_ISSUES.md new file mode 100644 index 000000000..7660f0f73 --- /dev/null +++ b/docs/user/howto/DEBUG_SUPPORT_SUBMIT_ISSUES.md @@ -0,0 +1,59 @@ +# Debugging / Support / Submitting Issues + +First, let's not forget that this version of Concrete framework is a beta product, meaning that it is not completely polished, contains several bugs (would they be known or unknown at this time). Also, let's not forget that FHE is an highly hot topic, and notably, that it cannot be considered as a solved problem. + +Anyway, let's list some ways to debug your problems here. If nothing seems conclusive, you can still report the issue, as explained in a later section of this page. + +## Is it a bug by the framework or by the user? + +If ever your numpy program fails, it may be because: +- of bugs due to Concrete framework +- of bugs due to the user, notably who would not use the framework as expected or not consider the limits of the framework. + +For the latter kind of bugs, we encourage the user to have a look to: +- the error message she gets +- the documentation of the product +- the known limits of the product (such as the reduced set of supported operations at this time, or the limited precision of the computations). + +Once the user has tried to see if the bug was not her own, it is time to go further. + +## Having a reproducible bug + +Once you're sure it is a bug, it would be nice to try to +- make it highly reproducible: e.g., by reducing as much the randomness as possible; e.g., if you can find an input which fails, there is no reason to let the input random +- reduce it to the smallest possible bug: it is easier to investigate bugs which are small, so when you have an issue, please try to reduce to a smaller issue, notably with less lines of code, smaller parameters, less complex function to compile, faster scripts etc + +## Asking the community + +We have created a Slack channel (TODO: LINK TO BE ADDED), such that you can directly ask the developpers and community about your issue. + +Hopefully, it is just a misunderstanding or a small mistake on your side, that one can help you fix easily. And, the good point with your feedback is that, once we have heard the problem or misunderstanding, we can make the documentation even clearer (such as, increasing the FAQ). + +## Having a look to the compilation artifacts + +When things are more complicated, or if you want to have a look by yourself, you may want to have a look to the compilation reports, which are called artifacts. This is as simple as described in [TODO: add the link to the tutorial about having artifacts]. + +This function will create a directory, containing notably: +[TODO: Umut to fix / complete the following information] +- bounds.txt: a file describing the expected ranges of data in the different steps of the computation +- cryptographic_parameters.txt: a file describing the different keys +- ir_nodes.txt: a file describing the different nodes in the intermediate representation (IR) +- optimizations_applied.txt: a file describing the different optimizations which were applied +- target_nodes.txt: a file describing the different nodes in the VM graph + +Attaching the artifact with your issue or Slack message may help people to have a look at the core of the problem. +The more precise your bug, the more likely we can reproduce and fix + +[TODO: Umut, is it still needed or do we already have some of those information in artifacts?] +In order to simplify our work and let us reproduce your bug easily, any information is useful. Notably, in addition to the python script, some information like +- the OS version +- the python version +- the python packages you use +- the reproducibility rate you see on your side +- any insight you might have on the bug +- any workaround you have been able to find +may be useful to us. Don't remember, Concrete is a project where we are open to contribution, more information at Contributing (TODO: add a link). + +## 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. diff --git a/docs/user/howto/FAQ.md b/docs/user/howto/FAQ.md index 9a2b02bd1..7b976a960 100644 --- a/docs/user/howto/FAQ.md +++ b/docs/user/howto/FAQ.md @@ -1,3 +1,14 @@ # FAQ -to be done +## What is Concrete FHE? + +See [here](../../README.md) + +## Is it an open source project? + +## Can I use it freely? + +## Can I contribute? + +## What are the future features of Concrete? + diff --git a/docs/user/howto/REDUCE_NEEDED_PRECISION.md b/docs/user/howto/REDUCE_NEEDED_PRECISION.md index 6877dc089..02fd87227 100644 --- a/docs/user/howto/REDUCE_NEEDED_PRECISION.md +++ b/docs/user/howto/REDUCE_NEEDED_PRECISION.md @@ -1 +1,3 @@ # Having a Function Which Requires Less Precision + +Arthur to do: #319 \ No newline at end of file diff --git a/docs/user/howto/SUBMIT_ISSUE.md b/docs/user/howto/SUBMIT_ISSUE.md deleted file mode 100644 index 3e72eafda..000000000 --- a/docs/user/howto/SUBMIT_ISSUE.md +++ /dev/null @@ -1 +0,0 @@ -# Submitting Issues diff --git a/docs/user/howto/SUPPORT.md b/docs/user/howto/SUPPORT.md deleted file mode 100644 index 85d1c2942..000000000 --- a/docs/user/howto/SUPPORT.md +++ /dev/null @@ -1 +0,0 @@ -# Support diff --git a/docs/user/tutorial/FIRST_TUTORIAL.md b/docs/user/tutorial/FIRST_TUTORIAL.md index 6c1c7b9bc..4e747fe30 100644 --- a/docs/user/tutorial/FIRST_TUTORIAL.md +++ b/docs/user/tutorial/FIRST_TUTORIAL.md @@ -1,3 +1,5 @@ # First Tutorial -To be continued +Umut to do: #312 + + diff --git a/docs/user/tutorial/SECOND_TUTORIAL.md b/docs/user/tutorial/SECOND_TUTORIAL.md index 9167da9e6..26642fb74 100644 --- a/docs/user/tutorial/SECOND_TUTORIAL.md +++ b/docs/user/tutorial/SECOND_TUTORIAL.md @@ -1,3 +1,3 @@ # Second Tutorial -To be continued +Umut to do: #313 diff --git a/docs/user/tutorial/THIRD_TUTORIAL.md b/docs/user/tutorial/THIRD_TUTORIAL.md index 44fd7293d..661b4e60f 100644 --- a/docs/user/tutorial/THIRD_TUTORIAL.md +++ b/docs/user/tutorial/THIRD_TUTORIAL.md @@ -1,3 +1,3 @@ # Third Tutorial -To be continued +Umut to do: #314