class_docstr: Fast Gradient Sign Method is a one-step method that can generate
  adversarial examples.
  
  For non-targeted attack, the formulation is::
  
      x' = x + epsilon * sign(gradient of L(theta, x, y))
  
  For targeted attack on t, the formulation is::
  
      x' = x - epsilon * sign(gradient of L(theta, x, t))
  
  ``L(theta, x, y)`` is the model's loss function with respect to model
  parameters, inputs and labels.
  
  More details on Fast Gradient Sign Method can be found in the original
  paper: https://arxiv.org/abs/1412.6572
class_docstr_tok: ["Fast","Gradient","Sign","Method","is","a","one-step","method","that","can","generate","adversarial","examples",".","For","non-targeted","attack",",","the","formulation","is",":",":","x","'","=","x","+","epsilon","*","sign","(","gradient","of","L","(","theta",",","x",",","y",")",")","For","targeted","attack","on","t",",","the","formulation","is",":",":","x","'","=","x","-","epsilon","*","sign","(","gradient","of","L","(","theta",",","x",",","t",")",")","``","L","(","theta",",","x",",","y",")","``","is","the","model","'s","loss","function","with","respect","to","model","parameters",",","inputs","and","labels",".","More","details","on","Fast","Gradient","Sign","Method","can","be","found","in","the","original","paper",":","https",":","\/\/arxiv.org\/abs\/1412.6572"]
docstr: This method computes and returns the perturbed input for each input tensor.
  It supports both targeted and non-targeted attacks.
  
  Args:
  
      inputs (Tensor or tuple[Tensor, ...]): Input for which adversarial
                  attack is computed. It can be provided as a single
                  tensor or a tuple of multiple tensors. If multiple
                  input tensors are provided, the batch sizes must be
                  aligned across all tensors.
      epsilon (float): Step size of perturbation.
      target (Any): True labels of inputs if non-targeted attack is
                  desired. Target class of inputs if targeted attack
                  is desired. Target will be passed to the loss function
                  to compute loss, so the type needs to match the
                  argument type of the loss function.
  
                  If using the default negative log as loss function,
                  labels should be of type int, tuple, tensor or list.
                  For general 2D outputs, labels can be either:
  
                  - a single integer or a tensor containing a single
                    integer, which is applied to all input examples
  
                  - a list of integers or a 1D tensor, with length matching
                    the number of examples in inputs (dim 0). Each integer
                    is applied as the label for the corresponding example.
  
                  For outputs with > 2 dimensions, labels can be either:
  
                  - A single tuple, which contains #output_dims - 1
                    elements. This label index is applied to all examples.
  
                  - A list of tuples with length equal to the number of
                    examples in inputs (dim 0), and each tuple containing
                    #output_dims - 1 elements. Each tuple is applied as the
                    label for the corresponding example.
  
      additional_forward_args (Any, optional): If the forward function
                  requires additional arguments other than the inputs for
                  which attributions should not be computed, this argument
                  can be provided. These arguments are provided to
                  forward_func in order following the arguments in inputs.
                  Default: None.
      targeted (bool, optional): If attack should be targeted.
                  Default: False.
      mask (Tensor or tuple[Tensor, ...], optional): mask of zeroes and ones
                  that defines which elements within the input tensor(s) are
                  perturbed. This mask must have the same shape and
                  dimensionality as the inputs. If this argument is not
                  provided, all elements will be perturbed.
                  Default: None.
  
  
  Returns:
  
      - **perturbed inputs** (*Tensor* or *tuple[Tensor, ...]*):
                  Perturbed input for each
                  input tensor. The perturbed inputs have the same shape and
                  dimensionality as the inputs.
                  If a single tensor is provided as inputs, a single tensor
                  is returned. If a tuple is provided for inputs, a tuple of
                  corresponding sized tensors is returned.
docstr_tok: ["This","method","computes","and","returns","the","perturbed","input","for","each","input","tensor",".","It","supports","both","targeted","and","non-targeted","attacks",".","Args",":","inputs","(","Tensor","or","tuple","[","Tensor",",","...","]",")",":","Input","for","which","adversarial","attack","is","computed",".","It","can","be","provided","as","a","single","tensor","or","a","tuple","of","multiple","tensors",".","If","multiple","input","tensors","are","provided",",","the","batch","sizes","must","be","aligned","across","all","tensors",".","epsilon","(","float",")",":","Step","size","of","perturbation",".","target","(","Any",")",":","True","labels","of","inputs","if","non-targeted","attack","is","desired",".","Target","class","of","inputs","if","targeted","attack","is","desired",".","Target","will","be","passed","to","the","loss","function","to","compute","loss",",","so","the","type","needs","to","match","the","argument","type","of","the","loss","function",".","If","using","the","default","negative","log","as","loss","function",",","labels","should","be","of","type","int",",","tuple",",","tensor","or","list",".","For","general","2D","outputs",",","labels","can","be","either",":","-","a","single","integer","or","a","tensor","containing","a","single","integer",",","which","is","applied","to","all","input","examples","-","a","list","of","integers","or","a","1D","tensor",",","with","length","matching","the","number","of","examples","in","inputs","(","dim","0",")",".","Each","integer","is","applied","as","the","label","for","the","corresponding","example",".","For","outputs","with",">","2","dimensions",",","labels","can","be","either",":","-","A","single","tuple",",","which","contains","#","output_dims","-","1","elements",".","This","label","index","is","applied","to","all","examples",".","-","A","list","of","tuples","with","length","equal","to","the","number","of","examples","in","inputs","(","dim","0",")",",","and","each","tuple","containing","#","output_dims","-","1","elements",".","Each","tuple","is","applied","as","the","label","for","the","corresponding","example",".","additional_forward_args","(","Any",",","optional",")",":","If","the","forward","function","requires","additional","arguments","other","than","the","inputs","for","which","attributions","should","not","be","computed",",","this","argument","can","be","provided",".","These","arguments","are","provided","to","forward_func","in","order","following","the","arguments","in","inputs",".","Default",":","None",".","targeted","(","bool",",","optional",")",":","If","attack","should","be","targeted",".","Default",":","False",".","mask","(","Tensor","or","tuple","[","Tensor",",","...","]",",","optional",")",":","mask","of","zeroes","and","ones","that","defines","which","elements","within","the","input","tensor","(","s",")","are","perturbed",".","This","mask","must","have","the","same","shape","and","dimensionality","as","the","inputs",".","If","this","argument","is","not","provided",",","all","elements","will","be","perturbed",".","Default",":","None",".","Returns",":","-","*","*","perturbed","inputs","*","*","(","*","Tensor","*","or","*","tuple","[","Tensor",",","...","]","*",")",":","Perturbed","input","for","each","input","tensor",".","The","perturbed","inputs","have","the","same","shape","and","dimensionality","as","the","inputs",".","If","a","single","tensor","is","provided","as","inputs",",","a","single","tensor","is","returned",".","If","a","tuple","is","provided","for","inputs",",","a","tuple","of","corresponding","sized","tensors","is","returned","."]
code: def perturb(
      self,
      inputs: TensorOrTupleOfTensorsGeneric,
      epsilon: float,
      target: Any,
      additional_forward_args: Any = None,
      targeted: bool = False,
      mask: Optional[TensorOrTupleOfTensorsGeneric] = None,
  ) -> TensorOrTupleOfTensorsGeneric:
      r"""
      This method computes and returns the perturbed input for each input tensor.
      It supports both targeted and non-targeted attacks.
  
      Args:
  
          inputs (Tensor or tuple[Tensor, ...]): Input for which adversarial
                      attack is computed. It can be provided as a single
                      tensor or a tuple of multiple tensors. If multiple
                      input tensors are provided, the batch sizes must be
                      aligned across all tensors.
          epsilon (float): Step size of perturbation.
          target (Any): True labels of inputs if non-targeted attack is
                      desired. Target class of inputs if targeted attack
                      is desired. Target will be passed to the loss function
                      to compute loss, so the type needs to match the
                      argument type of the loss function.
  
                      If using the default negative log as loss function,
                      labels should be of type int, tuple, tensor or list.
                      For general 2D outputs, labels can be either:
  
                      - a single integer or a tensor containing a single
                        integer, which is applied to all input examples
  
                      - a list of integers or a 1D tensor, with length matching
                        the number of examples in inputs (dim 0). Each integer
                        is applied as the label for the corresponding example.
  
                      For outputs with > 2 dimensions, labels can be either:
  
                      - A single tuple, which contains #output_dims - 1
                        elements. This label index is applied to all examples.
  
                      - A list of tuples with length equal to the number of
                        examples in inputs (dim 0), and each tuple containing
                        #output_dims - 1 elements. Each tuple is applied as the
                        label for the corresponding example.
  
          additional_forward_args (Any, optional): If the forward function
                      requires additional arguments other than the inputs for
                      which attributions should not be computed, this argument
                      can be provided. These arguments are provided to
                      forward_func in order following the arguments in inputs.
                      Default: None.
          targeted (bool, optional): If attack should be targeted.
                      Default: False.
          mask (Tensor or tuple[Tensor, ...], optional): mask of zeroes and ones
                      that defines which elements within the input tensor(s) are
                      perturbed. This mask must have the same shape and
                      dimensionality as the inputs. If this argument is not
                      provided, all elements will be perturbed.
                      Default: None.
  
  
      Returns:
  
          - **perturbed inputs** (*Tensor* or *tuple[Tensor, ...]*):
                      Perturbed input for each
                      input tensor. The perturbed inputs have the same shape and
                      dimensionality as the inputs.
                      If a single tensor is provided as inputs, a single tensor
                      is returned. If a tuple is provided for inputs, a tuple of
                      corresponding sized tensors is returned.
      """
      is_inputs_tuple = _is_tuple(inputs)
      inputs: Tuple[Tensor, ...] = _format_tensor_into_tuples(inputs)
      masks: Union[Tuple[int, ...], Tuple[Tensor, ...]] = (
          _format_tensor_into_tuples(mask)
          if (mask is not None)
          else (1,) * len(inputs)
      )
      gradient_mask = apply_gradient_requirements(inputs)
  
      def _forward_with_loss() -> Tensor:
          additional_inputs = _format_additional_forward_args(
              additional_forward_args
          )
          outputs = self.forward_func(  # type: ignore
              *(*inputs, *additional_inputs)  # type: ignore
              if additional_inputs is not None
              else inputs
          )
          if self.loss_func is not None:
              return self.loss_func(outputs, target)
          else:
              loss = -torch.log(outputs)
              return _select_targets(loss, target)
  
      grads = compute_gradients(_forward_with_loss, inputs)
      undo_gradient_requirements(inputs, gradient_mask)
      perturbed_inputs = self._perturb(
          inputs, grads, epsilon, targeted, masks
      )
      perturbed_inputs = tuple(
          self.bound(perturbed_inputs[i])
          for i in range(len(perturbed_inputs))
      )
      return _format_output(is_inputs_tuple, perturbed_inputs)
  
file_path: captum/captum/robust/_core/fgsm.py
imports: from typing import Any, Callable, Optional, Tuple, Union
  import torch
  from captum._utils.common import _format_additional_forward_args, _format_output, _format_tensor_into_tuples, _is_tuple, _select_targets
  from captum._utils.gradient import apply_gradient_requirements, compute_gradients, undo_gradient_requirements
  from captum._utils.typing import TensorOrTupleOfTensorsGeneric
  from captum.log import log_usage
  from captum.robust._core.perturbation import Perturbation
  from torch import Tensor
label_desc: Use image node_id 2 for calling the FGSM obj's underlying member method code with example usage: obj.perturb(inputs, epsilon, target, additional_forward_args, targeted, mask) and returns: _format_output, self, _select_targets