diff --git a/docs/source/contribute.md b/docs/source/contribute.md index 6e343db6..639e3007 100644 --- a/docs/source/contribute.md +++ b/docs/source/contribute.md @@ -28,27 +28,27 @@ local: true ### Prerequisites -#### Python 3.8+ environment +#### Python 3.9+ environment The use of a virtual environment is recommended, and you will need to ensure that the environment use a Python version -greater than 3.8. +greater than 3.9. This can be achieved for instance either by using [conda](https://docs.conda.io/en/latest/) or by using [pyenv](https://github.com/pyenv/pyenv) (or [pyenv-win](https://github.com/pyenv-win/pyenv-win) on windows) and [venv](https://docs.python.org/fr/3/library/venv.html) module. -The following examples show how to create a virtual environment with Python version 3.8.13 with the mentioned methods. +The following examples show how to create a virtual environment with Python version 3.10.13 with the mentioned methods. ##### With conda (all platforms) ```shell -conda create -n do-env python=3.8.13 +conda create -n do-env python=3.10.13 conda activate do-env ``` ##### With pyenv + venv (Linux/MacOS) ```shell -pyenv install 3.8.13 -pyenv shell 3.8.13 +pyenv install 3.10.13 +pyenv shell 3.10.13 python -m venv do-venv source do-venv/bin/activate ``` @@ -56,17 +56,36 @@ source do-venv/bin/activate ##### With pyenv-win + venv (Windows) ```shell -pyenv install 3.8.13 -pyenv shell 3.8.13 +pyenv install 3.10.13 +pyenv shell 3.10.13 python -m venv do-venv do-venv\Scripts\activate ``` -#### Tensorflow 2.6+ +#### Keras 3+ + +Decomon relies on [Keras 3](https://keras.io/keras_3/) which allows the use of several backends: Tensorflow, PyTorch, and JAX. + +To use it, you need to install at least one of the backends (refer to the documentation of each backend). +You can find the version needed to be compatible with keras 3 in +the [Keras 3 compatibility matrix](https://keras.io/getting_started/#compatibility-matrix) + +You choose the backend used at runtime by setting the environment variable `KERAS_BACKEND`. Read more about it in +[Keras documentation](https://keras.io/getting_started/#configuring-your-backend). + + +##### Warning when using backend Tensorflow 2.15 + +When installing Tensorflow 2.15, the version 2.15 of Keras will be installed automatically. Be sure to get back keras 3 +by fully uninstalling Keras then reinstalling Keras 3: + +```shell +pip uninstall keras +pip install "keras>=3" +``` + +The problem will not occur starting from tensorflow 2.16. -A version of tensorflow greater than 2.6 is required. If no package tensorflow is detected when installing decomon, a package tensorflow will be installed. -Howver it is better to do it beforehand to ensure having a version that is adapted to your GPU/CPU. See [tensorflow documentation](https://www.tensorflow.org/install/pip) -to see how to install it properly. ### Installing from source in developer mode @@ -176,10 +195,19 @@ tox If all python versions are not available or if you want to test only on a given version, specify the tox environment you want to test on. For instance: ```shell -tox -e py39 +tox l # list all environments available +tox run -e py39-torch # pytorch backend +tox run -e py39-tf # tensorflow backend ``` -Under the table, tox is actually calling [pytest](https://docs.pytest.org/) to perform the tests. You could also directly +You can also run a specific test, let say the function `test_get_adv_box_1d` from file +"tests/test_wrapper.py" like that: +```shell +tox run -e py39-torch -- tests/test_wrapper.py::test_get_adv_box_1d +``` + + +Under the hood, tox is actually calling [pytest](https://docs.pytest.org/) to perform the tests. You could also directly call it (after installing it in your development environment) with: ```shell pytest tests -v @@ -253,6 +281,8 @@ These are actually extracted from the first cell. To enable that, each notebook - start with a markdown cell, - its first line being the title starting with one number sign ("# "), - the remaining lines being used as the description. +- you can add lines that will be seen in notebook but not extracted in the description by wrapping them + into `` (see first cells of existing tutorials) For instance: ```markdown @@ -261,6 +291,12 @@ For instance: A quick description of the main features of the notebook. Can be on several lines. + +- Documentation +- Github +- Tutorials + + Can include a nice thumbnail. ![Notebook_thumbnail](https://upload.wikimedia.org/wikipedia/commons/2/27/MnistExamples.png) ``` diff --git a/docs/source/index.md b/docs/source/index.md index 79e804a8..988da9e6 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -5,7 +5,7 @@ `decomon` is a library that allows the derivation of upper and lower bounds -for the predictions of a Tensorflow/Keras neural network with perturbed inputs. +for the predictions of a Keras neural network with perturbed inputs. In the current release, these bounds are represented as affine functions with respect to some variable under perturbation. Previous works that tackled certified robustness with backward propagation relied on forward upper and lower bounds. In `decomon`, @@ -21,7 +21,8 @@ convex sets described by their vertices. We believe that decomon is a complementary tool to existing libraries for the certification of neural networks. -Since we rely on Tensorflow and not Pytorch, we are opening up the possibility for a new community +Since we rely on [Keras 3](https://keras.io/keras_3/) which allows in particular Tensorflow *and* Pytorch backends, +we are opening up the possibility for a new community to formally assess the robustness of their networks, without worrying about the technicality of the implementation. In this way, we hope to promote the formal certification of neural networks into safety critical systems. diff --git a/docs/source/install.md b/docs/source/install.md index 18ee922f..9982120f 100644 --- a/docs/source/install.md +++ b/docs/source/install.md @@ -3,27 +3,27 @@ ## Prerequisites -### Python 3.8+ environment +### Python 3.9+ environment The use of a virtual environment is recommended, and you will need to ensure that the environment use a Python version -greater than 3.8. +greater than 3.9. This can be achieved for instance either by using [conda](https://docs.conda.io/en/latest/) or by using [pyenv](https://github.com/pyenv/pyenv) (or [pyenv-win](https://github.com/pyenv-win/pyenv-win) on windows) and [venv](https://docs.python.org/fr/3/library/venv.html) module. -The following examples show how to create a virtual environment with Python version 3.8.13 with the mentioned methods. +The following examples show how to create a virtual environment with Python version 3.10.13 with the mentioned methods. #### With conda (all platforms) ```shell -conda create -n do-env python=3.8.13 +conda create -n do-env python=3.10.13 conda activate do-env ``` #### With pyenv + venv (Linux/MacOS) ```shell -pyenv install 3.8.13 -pyenv shell 3.8.13 +pyenv install 3.10.13 +pyenv shell 3.10.13 python -m venv do-venv source do-venv/bin/activate ``` @@ -31,17 +31,35 @@ source do-venv/bin/activate #### With pyenv-win + venv (Windows) ```shell -pyenv install 3.8.13 -pyenv shell 3.8.13 +pyenv install 3.10.13 +pyenv shell 3.10.13 python -m venv do-venv do-venv\Scripts\activate ``` -### Tensorflow 2.6+ +### Keras 3+ -A version of tensorflow greater than 2.6 is required. If no package tensorflow is detected when installing decomon, a package tensorflow will be installed. -Howver it is better to do it beforehand to ensure having a version that is adapted to your GPU/CPU. See [tensorflow documentation](https://www.tensorflow.org/install/pip) -to see how to install it properly. +Decomon relies on [Keras 3](https://keras.io/keras_3/) which allows the use of several backends: Tensorflow, PyTorch, and JAX. + +To use it, you need to install at least one of the backends (refer to the documentation of each backend). +You can find the version needed to be compatible with keras 3 in +the [Keras 3 compatibility matrix](https://keras.io/getting_started/#compatibility-matrix) + +You choose the backend used at runtime by setting the environment variable `KERAS_BACKEND`. Read more about it in +[Keras documentation](https://keras.io/getting_started/#configuring-your-backend). + + +#### Warning when using backend Tensorflow 2.15 + +When installing Tensorflow 2.15, the version 2.15 of Keras will be installed automatically. Be sure to get back keras 3 +by fully uninstalling Keras then reinstalling Keras 3: + +```shell +pip uninstall keras +pip install "keras>=3" +``` + +The problem will not occur starting from tensorflow 2.16. ## Pip install decomon library