Describe Usage of Avalanche updaters and their Limitations (#202)

doc/getting_started/avalanche.rst

@@ -0,0 +1,53 @@
+Avalanche - Usage and Limitations
+*********************************
+
+`Avalanche <https://github.com/ContinualAI/avalanche>`__ is a popular continual learning library for rapid prototyping
+and benchmarking algorithms. For that reason, we make some Avalanche updaters available in Renate. Avalanche updaters
+can be used in the same way you can use other Renate updaters but they have some limitations you should be aware of.
+
+Usage
+=====
+Using Avalanche updaters for training works the same as with Renate updaters which we explained earlier in
+:doc:`how_to_run_training`. You can select an Avalanche updater by passing the respective string to the ``updater``
+argument of :py:func:`~renate.training.training.run_training_job`. The available Avalanche options are
+``"Avalanche-ER"``, ``"Avalanche-EWC"``, ``"Avalanche-LwF"``, and ``"Avalanche-iCaRL"``.
+More details about these algorithms are given in :doc:`supported_algorithms`.
+Further Avalanche updaters can be created if needed.
+
+Limitations
+===========
+Not all Renate features work with every Avalanche updater. In the following, we list the limitations you face when
+using an Avalanche updater. These limitations are subject to change.
+
+PyTorch 1.13.1
+--------------
+The checkpointing functionality in Avalanche does not work with the latest version of PyTorch 1. Therefore, you will
+be required to use PyTorch 1.12.1 instead.
+
+.. warning::
+    There is a `known vulnerability <https://nvd.nist.gov/vuln/detail/CVE-2022-45907>`__ with PyTorch <= 1.13.0.
+
+No Scalable Buffers
+-------------------
+Renate stores the memory buffer on disk. In contrast, Avalanche requires it to be in memory. Therefore, Avalanche
+updaters may not work if you intend to use very large buffer sizes.
+
+No Multi-Fidelity HPO
+---------------------
+Currently, we do not support multi-fidelity hyperparameter optimization with Avalanche updaters. For that reason,
+please do not use ``asha`` as a scheduler but use ``random`` or ``bo`` instead.
+For more details about HPO in Renate, please refer to the
+:ref:`Renate HPO section <getting_started/how_to_run_training:run a training job with hpo>`.
+
+No Early-Stopping
+-----------------
+Currently, Avalanche updaters will not work with early stopping. Please keep ``early_stopping=True`` (default setting).
+
+iCaRL Limitations
+-----------------
+The implementation of iCaRL makes strong assumptions about the continual learning scenario. Only classification is
+supported and it assumes that data points of a particular class only occur in one update. If this is not the case,
+iCaRL will crash as soon as you attempt an update with a class seen before. Furthermore, it requires a specific
+model interface to account for its strategy. For that purpose, please create a model class which extends
+:py:class:`RenateBenchmarkingModule <renate.benchmark.models.base.RenateBenchmarkingModule>` or copy the relevant
+parts over to your ``RenateModule``.

doc/getting_started/index.rst

@@ -4,7 +4,7 @@ Getting Started
 
 This section covers the usage of Renate from the installation to the training
 of a model. The content is intended to explain the basic steps to be taken when creating a new
-training pipeline based on Rente.
+training pipeline based on Renate.
 
 If your goal is to test multiple Renate algorithms on your dataset or to test a specific algorithm on
 multiple datasets and scenarios, you will be better served by the benchmarking functionalities 
@@ -18,3 +18,4 @@ provided in :doc:`../benchmarking/renate_benchmarks`.
     how_to_run_training
     output
     supported_algorithms
+    avalanche

doc/getting_started/supported_algorithms.rst

@@ -3,7 +3,7 @@ Supported Algorithms
 
 Renate provides implementations of various continual learning methods. The following table provides
 an overview with links to the documentation, and a short description. When initiating model updates
-using Renate (e.g., using :py:func:`renate.training.training.run_training_job`; see
+using Renate (e.g., using :py:func:`~renate.training.training.run_training_job`; see
 :doc:`how_to_run_training`), a method may be selected using the shorthand provided below.
 
 .. list-table:: Supported Algorithms
@@ -36,3 +36,15 @@ using Renate (e.g., using :py:func:`renate.training.training.run_training_job`;
    * - ``"FineTuning"``
      - :py:class:`Learner <renate.updaters.learner.Learner>`
      - A simple method which trains the current model on only the new data without any sort of mitigation for forgetting. Used as "lower bound" baseline in experiments.
+   * - ``"Avalanche-ER"``
+     - :py:class:`AvalancheReplayLearner <renate.updaters.avalanche.learner.AvalancheReplayLearner>`
+     - A wrapper which gives access to Experience Replay as implemented in the Avalanche library. This method is the equivalent to our Offline-ER.
+   * - ``"Avalanche-EWC"``
+     - :py:class:`AvalancheEWCLearner <renate.updaters.avalanche.learner.AvalancheEWCLearner>`
+     - A wrapper which gives access to Elastic Weight Consolidation as implemented in the Avalanche library. EWC updates the model in such a way that the parameters after the update remain close to the parameters before the update to avoid catastrophic forgetting. [`Paper <https://arxiv.org/abs/1612.00796>`__]
+   * - ``"Avalanche-LwF"``
+     - :py:class:`AvalancheLwFLearner <renate.updaters.avalanche.learner.AvalancheLwFLearner>`
+     - A wrapper which gives access to Learning without Forgetting as implemented in the Avalanche library. LwF does not require to retain old data. It assumes that each new data chunk is its own task. A common backbone is shared across all task and each task has its own prediction head. [`Paper <https://arxiv.org/abs/1606.09282>`__]
+   * - ``"Avalanche-iCaRL"``
+     - :py:class:`AvalancheICaRLLearner <renate.updaters.avalanche.learner.AvalancheICaRLLearner>`
+     - A wrapper which gives access to iCaRL as implemented in the Avalanche library. This method is limited to class-incremental learning and combines knowledge distillation with nearest neighbors classification. [`Paper <https://arxiv.org/abs/1611.07725>`__]