docstr: This method evaluates the model at each perturbed input and identifies
  the minimum perturbation that leads to an incorrect model prediction.
  
  It is recommended to provide a single input (batch size = 1) when using
  this to identify a minimal perturbation for the chosen example. If a
  batch of examples is provided, the default correct function identifies
  the minimal perturbation for at least 1 example in the batch to be
  misclassified. A custom correct_fn can be provided to customize
  this behavior and define correctness for the batch.
  
  Args:
  
      inputs (Any): Input for which minimal perturbation
              is computed. It can be provided as a tensor, tuple of tensors,
              or any raw input type (e.g. PIL image or text string).
              This input is provided directly as input to preproc function
              as well as any attack applied before preprocessing. If no
              pre-processing function is provided,
              this input is provided directly to the main model and all attacks.
  
      additional_forward_args (Any, optional): If the forward function
              requires additional arguments other than the preprocessing
              outputs (or inputs if preproc_fn is None), this argument
              can be provided. It must be either a single additional
              argument of a Tensor or arbitrary (non-tuple) type or a
              tuple containing multiple additional arguments including
              tensors or any arbitrary python types. These arguments
              are provided to forward_func in order following the
              arguments in inputs.
              For a tensor, the first dimension of the tensor must
              correspond to the number of examples. For all other types,
              the given argument is used for all forward evaluations.
              Default: ``None``
      target (TargetType): Target class for classification. This is required if
          using the default ``correct_fn``.
  
      perturbations_per_eval (int, optional): Allows perturbations of multiple
              attacks to be grouped and evaluated in one call of forward_fn
              Each forward pass will contain a maximum of
              perturbations_per_eval * #examples samples.
              For DataParallel models, each batch is split among the
              available devices, so evaluations on each available
              device contain at most
              (perturbations_per_eval * #examples) / num_devices
              samples.
              In order to apply this functionality, the output of preproc_fn
              (or inputs itself if no preproc_fn is provided) must be a tensor
              or tuple of tensors.
              Default: ``1``
      attack_kwargs (dict, optional): Optional dictionary of keyword
              arguments provided to attack function
      correct_fn_kwargs (dict, optional): Optional dictionary of keyword
              arguments provided to correct function
  
  Returns:
  
      Tuple of (perturbed_inputs, param_val) if successful
      else Tuple of (None, None)
  
      - **perturbed inputs** (Any):
             Perturbed input (output of attack) which results in incorrect
             prediction.
      - param_val (int, float)
              Param value leading to perturbed inputs causing misclassification
  
  Examples::
  
  >>> def gaussian_noise(inp: Tensor, std: float) -> Tensor:
  >>>     return inp + std*torch.randn_like(inp)
  
  >>> min_pert = MinParamPerturbation(forward_func=resnet18,
                                     attack=gaussian_noise,
                                     arg_name="std",
                                     arg_min=0.0,
                                     arg_max=2.0,
                                     arg_step=0.01,
                                  )
  >>> for images, labels in dataloader:
  >>>     noised_image, min_std = min_pert.evaluate(inputs=images, target=labels)
docstr_tok: ["This","method","evaluates","the","model","at","each","perturbed","input","and","identifies","the","minimum","perturbation","that","leads","to","an","incorrect","model","prediction",".","It","is","recommended","to","provide","a","single","input","(","batch","size","=","1",")","when","using","this","to","identify","a","minimal","perturbation","for","the","chosen","example",".","If","a","batch","of","examples","is","provided",",","the","default","correct","function","identifies","the","minimal","perturbation","for","at","least","1","example","in","the","batch","to","be","misclassified",".","A","custom","correct_fn","can","be","provided","to","customize","this","behavior","and","define","correctness","for","the","batch",".","Args",":","inputs","(","Any",")",":","Input","for","which","minimal","perturbation","is","computed",".","It","can","be","provided","as","a","tensor",",","tuple","of","tensors",",","or","any","raw","input","type","(","e.g",".","PIL","image","or","text","string",")",".","This","input","is","provided","directly","as","input","to","preproc","function","as","well","as","any","attack","applied","before","preprocessing",".","If","no","pre-processing","function","is","provided",",","this","input","is","provided","directly","to","the","main","model","and","all","attacks",".","additional_forward_args","(","Any",",","optional",")",":","If","the","forward","function","requires","additional","arguments","other","than","the","preprocessing","outputs","(","or","inputs","if","preproc_fn","is","None",")",",","this","argument","can","be","provided",".","It","must","be","either","a","single","additional","argument","of","a","Tensor","or","arbitrary","(","non-tuple",")","type","or","a","tuple","containing","multiple","additional","arguments","including","tensors","or","any","arbitrary","python","types",".","These","arguments","are","provided","to","forward_func","in","order","following","the","arguments","in","inputs",".","For","a","tensor",",","the","first","dimension","of","the","tensor","must","correspond","to","the","number","of","examples",".","For","all","other","types",",","the","given","argument","is","used","for","all","forward","evaluations",".","Default",":","``","None","``","target","(","TargetType",")",":","Target","class","for","classification",".","This","is","required","if","using","the","default","``","correct_fn","``",".","perturbations_per_eval","(","int",",","optional",")",":","Allows","perturbations","of","multiple","attacks","to","be","grouped","and","evaluated","in","one","call","of","forward_fn","Each","forward","pass","will","contain","a","maximum","of","perturbations_per_eval","*","#","examples","samples",".","For","DataParallel","models",",","each","batch","is","split","among","the","available","devices",",","so","evaluations","on","each","available","device","contain","at","most","(","perturbations_per_eval","*","#","examples",")","\/","num_devices","samples",".","In","order","to","apply","this","functionality",",","the","output","of","preproc_fn","(","or","inputs","itself","if","no","preproc_fn","is","provided",")","must","be","a","tensor","or","tuple","of","tensors",".","Default",":","``","1","``","attack_kwargs","(","dict",",","optional",")",":","Optional","dictionary","of","keyword","arguments","provided","to","attack","function","correct_fn_kwargs","(","dict",",","optional",")",":","Optional","dictionary","of","keyword","arguments","provided","to","correct","function","Returns",":","Tuple","of","(","perturbed_inputs",",","param_val",")","if","successful","else","Tuple","of","(","None",",","None",")","-","*","*","perturbed","inputs","*","*","(","Any",")",":","Perturbed","input","(","output","of","attack",")","which","results","in","incorrect","prediction",".","-","param_val","(","int",",","float",")","Param","value","leading","to","perturbed","inputs","causing","misclassification","Examples",":",":",">",">",">","def","gaussian_noise","(","inp",":","Tensor",",","std",":","float",")","-",">","Tensor",":",">",">",">","return","inp","+","std","*","torch.randn_like","(","inp",")",">",">",">","min_pert","=","MinParamPerturbation","(","forward_func=resnet18",",","attack=gaussian_noise",",","arg_name=","''","std","''",",","arg_min=0.0",",","arg_max=2.0",",","arg_step=0.01",",",")",">",">",">","for","images",",","labels","in","dataloader",":",">",">",">","noised_image",",","min_std","=","min_pert.evaluate","(","inputs=images",",","target=labels",")"]
code: def evaluate(
      self,
      inputs: Any,
      additional_forward_args: Optional[Tuple] = None,
      target: TargetType = None,
      perturbations_per_eval: int = 1,
      attack_kwargs: Optional[Dict[str, Any]] = None,
      correct_fn_kwargs: Optional[Dict[str, Any]] = None,
  ) -> Tuple[Any, Optional[Union[int, float]]]:
      r"""
      This method evaluates the model at each perturbed input and identifies
      the minimum perturbation that leads to an incorrect model prediction.
  
      It is recommended to provide a single input (batch size = 1) when using
      this to identify a minimal perturbation for the chosen example. If a
      batch of examples is provided, the default correct function identifies
      the minimal perturbation for at least 1 example in the batch to be
      misclassified. A custom correct_fn can be provided to customize
      this behavior and define correctness for the batch.
  
      Args:
  
          inputs (Any): Input for which minimal perturbation
                  is computed. It can be provided as a tensor, tuple of tensors,
                  or any raw input type (e.g. PIL image or text string).
                  This input is provided directly as input to preproc function
                  as well as any attack applied before preprocessing. If no
                  pre-processing function is provided,
                  this input is provided directly to the main model and all attacks.
  
          additional_forward_args (Any, optional): If the forward function
                  requires additional arguments other than the preprocessing
                  outputs (or inputs if preproc_fn is None), this argument
                  can be provided. It must be either a single additional
                  argument of a Tensor or arbitrary (non-tuple) type or a
                  tuple containing multiple additional arguments including
                  tensors or any arbitrary python types. These arguments
                  are provided to forward_func in order following the
                  arguments in inputs.
                  For a tensor, the first dimension of the tensor must
                  correspond to the number of examples. For all other types,
                  the given argument is used for all forward evaluations.
                  Default: ``None``
          target (TargetType): Target class for classification. This is required if
              using the default ``correct_fn``.
  
          perturbations_per_eval (int, optional): Allows perturbations of multiple
                  attacks to be grouped and evaluated in one call of forward_fn
                  Each forward pass will contain a maximum of
                  perturbations_per_eval * #examples samples.
                  For DataParallel models, each batch is split among the
                  available devices, so evaluations on each available
                  device contain at most
                  (perturbations_per_eval * #examples) / num_devices
                  samples.
                  In order to apply this functionality, the output of preproc_fn
                  (or inputs itself if no preproc_fn is provided) must be a tensor
                  or tuple of tensors.
                  Default: ``1``
          attack_kwargs (dict, optional): Optional dictionary of keyword
                  arguments provided to attack function
          correct_fn_kwargs (dict, optional): Optional dictionary of keyword
                  arguments provided to correct function
  
      Returns:
  
          Tuple of (perturbed_inputs, param_val) if successful
          else Tuple of (None, None)
  
          - **perturbed inputs** (Any):
                 Perturbed input (output of attack) which results in incorrect
                 prediction.
          - param_val (int, float)
                  Param value leading to perturbed inputs causing misclassification
  
      Examples::
  
      >>> def gaussian_noise(inp: Tensor, std: float) -> Tensor:
      >>>     return inp + std*torch.randn_like(inp)
  
      >>> min_pert = MinParamPerturbation(forward_func=resnet18,
                                         attack=gaussian_noise,
                                         arg_name="std",
                                         arg_min=0.0,
                                         arg_max=2.0,
                                         arg_step=0.01,
                                      )
      >>> for images, labels in dataloader:
      >>>     noised_image, min_std = min_pert.evaluate(inputs=images, target=labels)
  
      """
      additional_forward_args = _format_additional_forward_args(
          additional_forward_args
      )
      expanded_additional_args = (
          _expand_additional_forward_args(
              additional_forward_args, perturbations_per_eval
          )
          if perturbations_per_eval > 1
          else additional_forward_args
      )
      preproc_input = (
          inputs if not self.preproc_fn else self.preproc_fn(inputs)
      )
  
      if self.mode is MinParamPerturbationMode.LINEAR:
          search_fn = self._linear_search
      elif self.mode is MinParamPerturbationMode.BINARY:
          search_fn = self._binary_search
      else:
          raise NotImplementedError(
              "Chosen MinParamPerturbationMode is not supported!"
          )
  
      return search_fn(
          inputs,
          preproc_input,
          attack_kwargs,
          additional_forward_args,
          expanded_additional_args,
          correct_fn_kwargs,
          target,
          perturbations_per_eval,
      )
  
file_path: captum/captum/robust/_core/metrics/min_param_perturbation.py
imports: import math
  from enum import Enum
  from typing import Any, Callable, cast, Dict, Generator, List, Optional, Tuple, Union
  import torch
  from captum._utils.common import _expand_additional_forward_args, _format_additional_forward_args, _reduce_list
  from captum._utils.typing import TargetType
  from captum.log import log_usage
  from captum.robust._core.perturbation import Perturbation
  from torch import Tensor
label_desc: Use image node_id 6 for calling the MinParamPerturbation obj's underlying member method code with example usage: obj.evaluate(inputs, additional_forward_args, target, perturbations_per_eval, attack_kwargs, correct_fn_kwargs) and returns: search_fn