-
Notifications
You must be signed in to change notification settings - Fork 23
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'release-v0.11.2' into 'stable'
Release v0.11.2 See merge request secml/secml!12
- Loading branch information
Showing
27 changed files
with
1,059 additions
and
99 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,14 @@ | ||
| Contributing to SecML | ||
| ===================== | ||
|
|
||
| The contributing and developer's guide is available in the repository at | ||
| `docs/source/developers/index.rst`, or online at: | ||
|
|
||
| https://secml.gitlab.io/developers/ | ||
|
|
||
| References | ||
| ---------- | ||
| * [SecML Releases](https://gitlab.com/secml/secml/releases) | ||
| * [Bugs and new features tracker](https://gitlab.com/secml/secml/issues) | ||
| * [Coding Guidelines](http://secml.gitlab.io/developers/contributing.code.html#coding-guidelines) | ||
| * [Creating Extensions](http://secml.gitlab.io/developers/contributing.extensions.html) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,142 @@ | ||
| ################## | ||
| Code Contributions | ||
| ################## | ||
|
|
||
| Contribution consisting on new code the library are much welcome. | ||
| One of our maintainers will review the contributions and will help | ||
| with the needed changes before integration, if any. | ||
|
|
||
| Development Installation | ||
| ======================== | ||
|
|
||
| Start by creating a `fork <https://gitlab.com/secml/secml/-/forks/new>`_ | ||
| of our repository. Then, set up the project locally by the following means: | ||
|
|
||
| 1. Install from local GitLab repository: | ||
|
|
||
| - Clone the project repository in a directory of your choice | ||
| - Run installation as: ``pip install .`` | ||
|
|
||
| 2. Install from remote GitLab repository. In this case, given ``{repourl}`` | ||
| in the format, es., ``gitlab.com/secml/secml``: | ||
|
|
||
| - ``pip install git+ssh://git@{repourl}.git[@branch]#egg=secml`` | ||
| A specific branch to install can be specified using ``[@branch]`` parameter. | ||
| If omitted, the default branch will be installed. | ||
|
|
||
| Contributions can be sent in the form of a merge request via our | ||
| `GitLab issue tracker <https://gitlab.com/secml/secml/issues>`_. | ||
| See `how to create a merge request <https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html>`_ | ||
| guide for more information. | ||
|
|
||
| Editable Installation | ||
| --------------------- | ||
|
|
||
| For SecML developers or users want to use the latest ``dev`` version of | ||
| the library (soon available to the public), ``pip`` provides a convenient | ||
| option which is called: **editable mode**. | ||
|
|
||
| By calling ``pip install`` with the ``-e`` option or ``python setup.py develop``, | ||
| only a reference to the project files is "installed" in the active | ||
| environment. In this way, project files can be edited/updated and the | ||
| new versions will be automatically executed by the Python interpreter. | ||
|
|
||
| Two common scenarios are listed below: | ||
|
|
||
| 1. Editable install from a previously cloned local repository | ||
|
|
||
| - Navigate to the repository directory | ||
| - Run ``python setup.py develop`` | ||
|
|
||
| 2. Editable install from remote repository | ||
|
|
||
| - Run ``pip install -e git+ssh://git@{repourl}.git[@branch]#egg=secml`` | ||
| - Project will be cloned automatically in ``<venv path>/src/secml`` | ||
| - The new repository can then be updated using standard ``git`` commands | ||
|
|
||
| Merge request checklist | ||
| ======================= | ||
|
|
||
| Please follow this checklist before sending a new merge request: | ||
|
|
||
| 1. Use informative names for classes, methods, functions and variables. | ||
| 2. Make sure your code passes the existing tests. | ||
| Remember to test both CPU and GPU (CUDA) mode, if applicable. | ||
| 3. Make sure your code is well documented and commented when possible. | ||
| Make sure the documentation renders properly by compiling it. | ||
| 4. Add tests if you are contributing to a new feature. | ||
| 5. Make sure your code does not violate `PEP-8 <https://www.python.org/dev/peps/pep-0008/>`_ | ||
| codestyle convention. | ||
| 6. When applicable, re-use the code in the library without rewriting | ||
| procedures that are already implemented somewhere else. | ||
| 7. (optional) Provide an example of usage in the merge request, so that | ||
| the contribution to the library will become clear to | ||
| the reviewers as well as other contributors. | ||
|
|
||
| Coding guidelines | ||
| ================= | ||
|
|
||
| In this section, we summarize standards and conventions used in our library. | ||
|
|
||
| Code style | ||
| ---------- | ||
|
|
||
| We follow python `PEP-8 <https://www.python.org/dev/peps/pep-0008/>`_ | ||
| convention for ensuring code readability. 4-spaces indentation should be used. | ||
|
|
||
| Documentation style | ||
| ------------------- | ||
|
|
||
| We use informative docstrings for our code. Make sure your code is always | ||
| commented and documented. The docstrings should follow the | ||
| `NumPy documentation format <https://numpydoc.readthedocs.io/en/latest/format.html>`_. | ||
|
|
||
| To locally build the documentation, run the following command: | ||
| ``tox -e docs``. | ||
|
|
||
| Compiled files will be available in the ``docs/build/html`` folder. | ||
|
|
||
| Packages | ||
| -------- | ||
|
|
||
| Our packages are nested inside macro-categories. Every package can contain | ||
| modules, other packages or just directories for keeping everything structured | ||
| and tidy. | ||
|
|
||
| Modules | ||
| ------- | ||
|
|
||
| We use separate files for each class so that they can be easily | ||
| found within the package structure. Modules can also be created to group | ||
| utility functions together. | ||
|
|
||
| Classes | ||
| ------- | ||
|
|
||
| Our class names all start with ``C + <class_name>``, e.g. ``CClassifier``. | ||
| Hidden utility classes, accessible only internally from other classes, | ||
| have names starting with underscores (``_C + <class_name>``). | ||
|
|
||
| The packages's superclass often expose public methods that call inner | ||
| abstract methods. If you are subclassing one of these classes, take care of | ||
| reading the superclass code and check out the inner methods that you need | ||
| to implement. See: `Extending SecML <contributing.extensions.html>`_. | ||
|
|
||
| Tests | ||
| ----- | ||
|
|
||
| We test our code with pervasive unit tests, build on Python's | ||
| `unittest <https://docs.python.org/3/library/unittest.html>`_ framework. | ||
| Existing unittests can be run using `tox <https://tox.readthedocs.io/>`_. | ||
|
|
||
| You can also contribute to writing tests for our code. We have ``tests`` | ||
| subdirectories in all our packages. | ||
|
|
||
| The main interface from which new tests should be inherited is the | ||
| :class:`secml.testing.c_unittest.CUnitTest` class. | ||
|
|
||
| Tests should run smoothly and fast, performing accurate initialization and | ||
| cleanup. Implement the initialization in the ``setUp`` method, | ||
| and the single test cases in other separate methods. | ||
|
|
||
| New test modules should be have name starting with ``test_``. |
69 changes: 69 additions & 0 deletions
69
docs/source/developers/contributing.extensions.cclassifier.rst
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,69 @@ | ||
| CClassifier | ||
| =========== | ||
|
|
||
| The unified interface :class:`CClassifier` defines the structure of classifiers. | ||
|
|
||
| We differentiate a standard classifier from Deep Neural Networks (DNNs), | ||
| which require a more advanced interface defined by :class:`CClassifierDNN` | ||
| (described below). | ||
|
|
||
| Standard classifiers (``CClassifier``) | ||
| -------------------------------------- | ||
|
|
||
| List of methods to implement: | ||
|
|
||
| - ``_forward``: performs a forward pass of the input x. | ||
| It should return the output of the decision function of the classifier. | ||
|
|
||
| - ``_backward``: this method returns the gradient of the decision function | ||
| output with respect to data. It takes a ``CArray`` as input, ``w``, | ||
| which pre-multiplies the gradient as in standard reverse-mode autodiff. | ||
|
|
||
| - ``_fit``: fit the classifier on the data. Takes as input a ``CDataset``. | ||
|
|
||
| DNN backends (``CClassifierDNN``) | ||
| --------------------------------- | ||
|
|
||
| The backend for DNN (:class:`CClassifierDNN`) is based on the ``CClassifier`` | ||
| interface, adding more methods specific to DNNs and their frameworks. | ||
|
|
||
| An example of how to extend the ``CClassifierDNN`` interface is our | ||
| PyTorch wrapper :class:`CClassifierPyTorch`. | ||
|
|
||
| List of methods to implement: | ||
|
|
||
| - ``_forward``: performs a forward pass of the input x. It is slightly | ||
| different from the ``_forward`` method of ``CClassifier``, as it returns | ||
| the output of the layer of the DNN specified in the attribute ``_out_layer``. | ||
| If ``_out_layer`` is ``None``, the last layer output is returned (applies | ||
| the softmax if ``softmax_outputs`` is True). | ||
|
|
||
| - ``_backward``: returns the gradient of the output of the DNN layer specified | ||
| in ``_out_layer``, with respect to the input data. | ||
|
|
||
| - ``_fit``: trains the classifier. Takes as input a ``CDataset``. | ||
|
|
||
| - ``layers`` (property): returns a list of tuples containing the layers of the | ||
| model, each tuple is structured as ``(layer_name, layer)``. | ||
|
|
||
| - ``layer_shapes`` (property): returns the output shape of each layer | ||
| (as a dictionary with layer names as keys). | ||
|
|
||
| - ``_to_tensor``: converts a ``CArray`` into the tensor data type of the | ||
| backend framework. | ||
|
|
||
| - ``_from_tensor``: converts a backend tensor data type to a ``CArray``. | ||
|
|
||
| - ``save_model``: saves the model weight and parameters into a gz archive. | ||
| If possible, it should allow model restoring as a checkpoint, i.e. the user | ||
| should be able to continue training of the restored model. | ||
|
|
||
| - ``load_model``: restores the model. If possible, it restores also the | ||
| optimization parameters as the user may need to continue training. | ||
|
|
||
| It may be necessary to implement a custom data loader for the specific DNN | ||
| backend. The data loader should take as input a ``CDataset`` and load the data | ||
| for the backend. This is necessary because the inputs to the network may have | ||
| their own shapes, whereas the ``CArray`` treats each sample as a row vector. | ||
| We suggest to add the ``input_shape`` as an input parameter of the wrapper | ||
| and handle the conversion inside. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,70 @@ | ||
| ############### | ||
| Extending SecML | ||
| ############### | ||
|
|
||
| We provide details on how to implement new library modules, extending our | ||
| abstract interfaces. | ||
|
|
||
| Remember to check out | ||
| `latest version <https://gitlab.com/secml/secml/-/releases>`_ and | ||
| `roadmap <https://secml.gitlab.io/roadmap.html>`_ before developing new code. | ||
|
|
||
| Abstract Base Classes | ||
| ===================== | ||
|
|
||
| The packages's abstract superclasses (e.g. :class:`CClassifier`) expose | ||
| public methods that call inner abstract methods. If you are creating a new | ||
| extension, inherit from one of these classes, taking care of reading the | ||
| superclass code and check out the inner methods that you need to implement. | ||
|
|
||
| New extensions should handle our main data type :class:`CArray`. | ||
| This class wraps the dense numpy :class:`numpy.ndarray` and the scipy sparse | ||
| :class:`scipy.sparse.csr_matrix`, so that they have the same interface | ||
| for the user. | ||
|
|
||
| The shape of a ``CArray`` is either a vector or a matrix (multi-dimensional | ||
| arrays will be added in a future version) of rows where each row represents | ||
| a sample. | ||
|
|
||
| Two ``CArray`` are needed to compose a :class:`CDataset` | ||
| that can be used to store samples (attribute X) and labels (attribute Y). | ||
|
|
||
| Creating new extensions | ||
| ======================= | ||
|
|
||
| The following guides illustrate how to extend the superclasses for the | ||
| different packages of the library: | ||
|
|
||
| .. toctree:: | ||
| :hidden: | ||
|
|
||
| contributing.extensions.cclassifier | ||
|
|
||
|
|
||
| * `CClassifier <contributing.extensions.cclassifier.html>`_ - | ||
| classifiers including Deep Neural Networks. | ||
|
|
||
| The following contribution guides will be added in a future versions. | ||
|
|
||
| * Data processing | ||
|
|
||
| - :class:`CPreprocess` | ||
| - :class:`CKernel` | ||
|
|
||
| * Data | ||
|
|
||
| - :class:`CDataLoader` | ||
|
|
||
| * Visualization | ||
|
|
||
| - :class:`CPlot` | ||
|
|
||
| * Attacks | ||
|
|
||
| - :class:`CAttack` | ||
| - :class:`CAttackEvasion` | ||
| - :class:`CAttackPoisoning` | ||
|
|
||
| * Optimization | ||
|
|
||
| - :class:`COptimizer` |
Oops, something went wrong.