Merge pull request #1319 from Trusted-AI/development_documentation

Development documentation

Author: beat-buesser

art/attacks/attack.py

@@ -85,7 +85,7 @@ def replacement_function(self, *args, **kwargs):
                 setattr(cls, item, new_function)
 
 
-class Attack(abc.ABC, metaclass=InputFilter):
+class Attack(abc.ABC):
     """
     Abstract base class for all attack abstract base classes.
     """
@@ -197,7 +197,7 @@ def generate(  # lgtm [py/inheritance/incorrect-overridden-signature]
 
         :param x: An array with the original inputs to be attacked.
         :param y: Correct labels or target labels for `x`, depending if the attack is targeted
-               or not. This parameter is only used by some of the attacks.
+                  or not. This parameter is only used by some of the attacks.
         :return: An array holding the adversarial examples.
         """
         raise NotImplementedError

art/attacks/evasion/brendel_bethge.py

@@ -1943,22 +1943,6 @@ def _distance(self, x0, x):
 
 
 class BrendelBethgeAttack(EvasionAttack):
-
-    attack_params = EvasionAttack.attack_params + [
-        "norm",
-        "targeted",
-        "init_attack",
-        "overshoot",
-        "steps",
-        "lr",
-        "lr_decay",
-        "lr_num_decay",
-        "momentum",
-        "binary_search_steps",
-        "init_size",
-    ]
-    _estimator_requirements = (BaseEstimator, LossGradientsMixin, ClassifierMixin)
-
     """
     Base class for the Brendel & Bethge adversarial attack [#Bren19]_, a powerful gradient-based adversarial attack that
     follows the adversarial boundary (the boundary between the space of adversarial and non-adversarial images as
@@ -1968,43 +1952,34 @@ class BrendelBethgeAttack(EvasionAttack):
     https://github.com/bethgelab/foolbox/blob/master/foolbox/attacks/brendel_bethge.py.
 
     Implementation differs from the attack used in the paper in two ways:
+
     * The initial binary search is always using the full 10 steps (for ease of implementation).
     * The adaptation of the trust region over the course of optimisation is less
       greedy but is more robust, reliable and simpler (decay every K steps)
 
-    Args:
-        estimator : A trained ART classifier providing loss gradients.
-        norm : The norm of the adversarial perturbation. Possible values: "inf", np.inf, 1 or 2.
-        targeted : Flag determining if attack is targeted.
-        overshoot : If 1 the attack tries to return exactly to the adversarial boundary
-            in each iteration. For higher values the attack tries to overshoot
-            over the boundary to ensure that the perturbed sample in each iteration
-            is adversarial.
-        steps : Maximum number of iterations to run. Might converge and stop
-            before that.
-        lr : Trust region radius, behaves similar to a learning rate. Smaller values
-            decrease the step size in each iteration and ensure that the attack
-            follows the boundary more faithfully.
-        lr_decay : The trust region lr is multiplied with lr_decay in regular intervals (see
-            lr_num_decay).
-        lr_num_decay : Number of learning rate decays in regular intervals of
-            length steps / lr_num_decay.
-        momentum : Averaging of the boundary estimation over multiple steps. A momentum of
-            zero would always take the current estimate while values closer to one
-            average over a larger number of iterations.
-        binary_search_steps : Number of binary search steps used to find the adversarial boundary
-            between the starting point and the clean image.
-        batch_size : Batch size for evaluating the model for predictions and gradients.
-        init_size : Maximum number of random search steps to find initial adversarial example.
-
     References:
-        .. [#Bren19] Wieland Brendel, Jonas Rauber, Matthias Kümmerer,
-            Ivan Ustyuzhaninov, Matthias Bethge,
+        .. [#Bren19] Wieland Brendel, Jonas Rauber, Matthias Kümmerer, Ivan Ustyuzhaninov, Matthias Bethge,
             "Accurate, reliable and fast robustness evaluation",
             33rd Conference on Neural Information Processing Systems (2019)
             https://arxiv.org/abs/1907.01003
     """
 
+    attack_params = EvasionAttack.attack_params + [
+        "norm",
+        "targeted",
+        "init_attack",
+        "overshoot",
+        "steps",
+        "lr",
+        "lr_decay",
+        "lr_num_decay",
+        "momentum",
+        "binary_search_steps",
+        "init_size",
+    ]
+
+    _estimator_requirements = (BaseEstimator, LossGradientsMixin, ClassifierMixin)
+
     def __init__(
         self,
         estimator: "CLASSIFIER_LOSS_GRADIENTS_TYPE",
@@ -2020,6 +1995,25 @@ def __init__(
         init_size: int = 100,
         batch_size: int = 32,
     ):
+        """
+        :param estimator: A trained ART classifier providing loss gradients.
+        :param norm: The norm of the adversarial perturbation. Possible values: "inf", np.inf, 1 or 2.
+        :param targeted: Flag determining if attack is targeted.
+        :param overshoot: If 1 the attack tries to return exactly to the adversarial boundary in each iteration. For
+                          higher values the attack tries to overshoot over the boundary to ensure that the perturbed
+                          sample in each iteration is adversarial.
+        :param steps: Maximum number of iterations to run. Might converge and stop before that.
+        :param lr: Trust region radius, behaves similar to a learning rate. Smaller values decrease the step size in
+                   each iteration and ensure that the attack follows the boundary more faithfully.
+        :param lr_decay: The trust region lr is multiplied with lr_decay in regular intervals (see lr_num_decay).
+        :param lr_num_decay: Number of learning rate decays in regular intervals of length steps / lr_num_decay.
+        :param momentum: Averaging of the boundary estimation over multiple steps. A momentum of zero would always take
+                         the current estimate while values closer to one average over a larger number of iterations.
+        :param binary_search_steps: Number of binary search steps used to find the adversarial boundary between the
+                                    starting point and the clean image.
+        :param init_size: Maximum number of random search steps to find initial adversarial example.
+        :param batch_size: Batch size for evaluating the model for predictions and gradients.
+        """
         from art.estimators.classification import TensorFlowV2Classifier, PyTorchClassifier
 
         if isinstance(estimator, TensorFlowV2Classifier):
@@ -2170,22 +2164,25 @@ def logits_difference(y_pred, y_true):  # type: ignore
         else:
             self.theta = 0.01 / np.prod(self.estimator.input_shape)
 
-    def generate(  # pylint: disable=W0221
+    def generate(
         self,
         x: np.ndarray,
         y: Optional[np.ndarray] = None,
-        starting_points: Optional[np.ndarray] = None,
-        early_stop: Optional[float] = None,
         **kwargs,
     ) -> np.ndarray:
         """
         Applies the Brendel & Bethge attack.
 
         :param x: The original clean inputs.
         :param y: The labels for inputs `x`.
-        :param starting_points: Adversarial inputs to use as a starting points, in particular for targeted attacks.
-        :param early_stop: Early-stopping criteria.
+
+        :Keyword Arguments:
+            * *starting_points* (``np.ndarray``)
+                Optional. Adversarial inputs to use as a starting points, in particular for targeted attacks.
         """
+        starting_points = kwargs.get("starting_points")
+        # early_stop = kwargs.get("early_stop")
+
         originals = x.copy()
 
         y = check_and_transform_label_format(y, self.estimator.nb_classes)

docs/modules/attacks/evasion.rst

@@ -50,6 +50,12 @@ Brendel and Bethge Attack
    :members:
    :special-members:
 
+Carlini and Wagner L_0 Attack
+-----------------------------
+.. autoclass:: CarliniL0Method
+   :members:
+   :special-members:
+
 Carlini and Wagner L_2 Attack
 -----------------------------
 .. autoclass:: CarliniL2Method
@@ -188,6 +194,12 @@ Projected Gradient Descent (PGD) - TensorFlowV2
    :members:
    :special-members:
 
+LowProFool
+----------
+.. autoclass:: LowProFool
+   :members:
+   :special-members:
+
 NewtonFool
 ----------
 .. autoclass:: NewtonFool