class_docstr: All gradient based attribution algorithms extend this class. It requires a
  forward function, which most commonly is the forward function of the model
  that we want to interpret or the model itself.
class_docstr_tok: ["All","gradient","based","attribution","algorithms","extend","this","class",".","It","requires","a","forward","function",",","which","most","commonly","is","the","forward","function","of","the","model","that","we","want","to","interpret","or","the","model","itself","."]
docstr: Here we provide a specific implementation for `compute_convergence_delta`
  which is based on a common property among gradient-based attribution algorithms.
  In the literature sometimes it is also called completeness axiom. Completeness
  axiom states that the sum of the attribution must be equal to the differences of
  NN Models's function at its end and start points. In other words:
  sum(attributions) - (F(end_point) - F(start_point)) is close to zero.
  Returned delta of this method is defined as above stated difference.
  
  This implementation assumes that both the `start_point` and `end_point` have
  the same shape and dimensionality. It also assumes that the target must have
  the same number of examples as the `start_point` and the `end_point` in case
  it is provided in form of a list or a non-singleton tensor.
  
  Args:
  
          attributions (Tensor or tuple[Tensor, ...]): Precomputed attribution
                      scores. The user can compute those using any attribution
                      algorithm. It is assumed the shape and the
                      dimensionality of attributions must match the shape and
                      the dimensionality of `start_point` and `end_point`.
                      It also assumes that the attribution tensor's
                      dimension 0 corresponds to the number of
                      examples, and if multiple input tensors are provided,
                      the examples must be aligned appropriately.
          start_point (Tensor or tuple[Tensor, ...], optional): `start_point`
                      is passed as an input to model's forward function. It
                      is the starting point of attributions' approximation.
                      It is assumed that both `start_point` and `end_point`
                      have the same shape and dimensionality.
          end_point (Tensor or tuple[Tensor, ...]): `end_point`
                      is passed as an input to model's forward function. It
                      is the end point of attributions' approximation.
                      It is assumed that both `start_point` and `end_point`
                      have the same shape and dimensionality.
          target (int, tuple, Tensor, or list, optional): Output indices for
                      which gradients are computed (for classification cases,
                      this is usually the target class).
                      If the network returns a scalar value per example,
                      no target index is necessary.
                      For general 2D outputs, targets 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 target for the corresponding example.
  
                      For outputs with > 2 dimensions, targets can be either:
  
                      - A single tuple, which contains #output_dims - 1
                        elements. This target 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
                        target for the corresponding example.
  
                      Default: None
          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. 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.
                      `additional_forward_args` is used both for `start_point`
                      and `end_point` when computing the forward pass.
                      Default: None
  
  Returns:
  
          *Tensor* of **deltas**:
          - **deltas** (*Tensor*):
              This implementation returns convergence delta per
              sample. Deriving sub-classes may do any type of aggregation
              of those values, if necessary.
docstr_tok: ["Here","we","provide","a","specific","implementation","for","`","compute_convergence_delta","`","which","is","based","on","a","common","property","among","gradient-based","attribution","algorithms",".","In","the","literature","sometimes","it","is","also","called","completeness","axiom",".","Completeness","axiom","states","that","the","sum","of","the","attribution","must","be","equal","to","the","differences","of","NN","Models","'s","function","at","its","end","and","start","points",".","In","other","words",":","sum","(","attributions",")","-","(","F","(","end_point",")","-","F","(","start_point",")",")","is","close","to","zero",".","Returned","delta","of","this","method","is","defined","as","above","stated","difference",".","This","implementation","assumes","that","both","the","`","start_point","`","and","`","end_point","`","have","the","same","shape","and","dimensionality",".","It","also","assumes","that","the","target","must","have","the","same","number","of","examples","as","the","`","start_point","`","and","the","`","end_point","`","in","case","it","is","provided","in","form","of","a","list","or","a","non-singleton","tensor",".","Args",":","attributions","(","Tensor","or","tuple","[","Tensor",",","...","]",")",":","Precomputed","attribution","scores",".","The","user","can","compute","those","using","any","attribution","algorithm",".","It","is","assumed","the","shape","and","the","dimensionality","of","attributions","must","match","the","shape","and","the","dimensionality","of","`","start_point","`","and","`","end_point","`",".","It","also","assumes","that","the","attribution","tensor's","dimension","0","corresponds","to","the","number","of","examples",",","and","if","multiple","input","tensors","are","provided",",","the","examples","must","be","aligned","appropriately",".","start_point","(","Tensor","or","tuple","[","Tensor",",","...","]",",","optional",")",":","`","start_point","`","is","passed","as","an","input","to","model","'s","forward","function",".","It","is","the","starting","point","of","attributions","'","approximation",".","It","is","assumed","that","both","`","start_point","`","and","`","end_point","`","have","the","same","shape","and","dimensionality",".","end_point","(","Tensor","or","tuple","[","Tensor",",","...","]",")",":","`","end_point","`","is","passed","as","an","input","to","model","'s","forward","function",".","It","is","the","end","point","of","attributions","'","approximation",".","It","is","assumed","that","both","`","start_point","`","and","`","end_point","`","have","the","same","shape","and","dimensionality",".","target","(","int",",","tuple",",","Tensor",",","or","list",",","optional",")",":","Output","indices","for","which","gradients","are","computed","(","for","classification","cases",",","this","is","usually","the","target","class",")",".","If","the","network","returns","a","scalar","value","per","example",",","no","target","index","is","necessary",".","For","general","2D","outputs",",","targets","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","target","for","the","corresponding","example",".","For","outputs","with",">","2","dimensions",",","targets","can","be","either",":","-","A","single","tuple",",","which","contains","#","output_dims","-","1","elements",".","This","target","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","target","for","the","corresponding","example",".","Default",":","None","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",".","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",".","`","additional_forward_args","`","is","used","both","for","`","start_point","`","and","`","end_point","`","when","computing","the","forward","pass",".","Default",":","None","Returns",":","*","Tensor","*","of","*","*","deltas","*","*",":","-","*","*","deltas","*","*","(","*","Tensor","*",")",":","This","implementation","returns","convergence","delta","per","sample",".","Deriving","sub-classes","may","do","any","type","of","aggregation","of","those","values",",","if","necessary","."]
code: def compute_convergence_delta(
      self,
      attributions: Union[Tensor, Tuple[Tensor, ...]],
      start_point: Union[
          None,
          int,
          float,
          Tensor,
          Tuple[Union[int, float, Tensor], ...],
      ],
      end_point: Union[Tensor, Tuple[Tensor, ...]],
      target: TargetType = None,
      additional_forward_args: Any = None,
  ) -> Tensor:
      r"""
      Here we provide a specific implementation for `compute_convergence_delta`
      which is based on a common property among gradient-based attribution algorithms.
      In the literature sometimes it is also called completeness axiom. Completeness
      axiom states that the sum of the attribution must be equal to the differences of
      NN Models's function at its end and start points. In other words:
      sum(attributions) - (F(end_point) - F(start_point)) is close to zero.
      Returned delta of this method is defined as above stated difference.
  
      This implementation assumes that both the `start_point` and `end_point` have
      the same shape and dimensionality. It also assumes that the target must have
      the same number of examples as the `start_point` and the `end_point` in case
      it is provided in form of a list or a non-singleton tensor.
  
      Args:
  
              attributions (Tensor or tuple[Tensor, ...]): Precomputed attribution
                          scores. The user can compute those using any attribution
                          algorithm. It is assumed the shape and the
                          dimensionality of attributions must match the shape and
                          the dimensionality of `start_point` and `end_point`.
                          It also assumes that the attribution tensor's
                          dimension 0 corresponds to the number of
                          examples, and if multiple input tensors are provided,
                          the examples must be aligned appropriately.
              start_point (Tensor or tuple[Tensor, ...], optional): `start_point`
                          is passed as an input to model's forward function. It
                          is the starting point of attributions' approximation.
                          It is assumed that both `start_point` and `end_point`
                          have the same shape and dimensionality.
              end_point (Tensor or tuple[Tensor, ...]): `end_point`
                          is passed as an input to model's forward function. It
                          is the end point of attributions' approximation.
                          It is assumed that both `start_point` and `end_point`
                          have the same shape and dimensionality.
              target (int, tuple, Tensor, or list, optional): Output indices for
                          which gradients are computed (for classification cases,
                          this is usually the target class).
                          If the network returns a scalar value per example,
                          no target index is necessary.
                          For general 2D outputs, targets 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 target for the corresponding example.
  
                          For outputs with > 2 dimensions, targets can be either:
  
                          - A single tuple, which contains #output_dims - 1
                            elements. This target 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
                            target for the corresponding example.
  
                          Default: None
              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. 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.
                          `additional_forward_args` is used both for `start_point`
                          and `end_point` when computing the forward pass.
                          Default: None
  
      Returns:
  
              *Tensor* of **deltas**:
              - **deltas** (*Tensor*):
                  This implementation returns convergence delta per
                  sample. Deriving sub-classes may do any type of aggregation
                  of those values, if necessary.
      """
      end_point, start_point = _format_input_baseline(
          end_point, start_point
      )
      additional_forward_args = _format_additional_forward_args(
          additional_forward_args
      )
      # tensorizing start_point in case it is a scalar or one example baseline
      # If the batch size is large we could potentially also tensorize only one
      # sample and expand the output to the rest of the elements in the batch
      start_point = _tensorize_baseline(end_point, start_point)
  
      attributions = _format_tensor_into_tuples(attributions)
  
      # verify that the attributions and end_point match on 1st dimension
      for attribution, end_point_tnsr in zip(attributions, end_point):
          assert end_point_tnsr.shape[0] == attribution.shape[0], (
              "Attributions tensor and the end_point must match on the first"
              " dimension but found attribution: {} and end_point: {}".format(
                  attribution.shape[0], end_point_tnsr.shape[0]
              )
          )
  
      num_samples = end_point[0].shape[0]
      _validate_input(end_point, start_point)
      _validate_target(num_samples, target)
  
      with torch.no_grad():
          start_out_sum = _sum_rows(
              _run_forward(
                  self.forward_func,
                  start_point,
                  target,
                  additional_forward_args,
              )
          )
  
          end_out_sum = _sum_rows(
              _run_forward(
                  self.forward_func,
                  end_point,
                  target,
                  additional_forward_args,
              )
          )
          row_sums = [
              _sum_rows(attribution) for attribution in attributions
          ]
          attr_sum = torch.stack(
              [cast(Tensor, sum(row_sum)) for row_sum in zip(*row_sums)]
          )
          _delta = attr_sum - (end_out_sum - start_out_sum)
      return _delta
  
imports: from typing import Any, Callable, cast, Generic, List, Tuple, Type, Union
  import torch
  import torch.nn.functional
  from captum._utils.common import _format_additional_forward_args, _format_tensor_into_tuples, _run_forward, _validate_target
  from captum._utils.gradient import compute_gradients
  from captum._utils.typing import ModuleOrModuleList, TargetType
  from captum.attr._utils.common import _format_input_baseline, _sum_rows, _tensorize_baseline, _validate_input
  from captum.log import log_usage
  from torch import Tensor
  from torch.nn import Module
label_desc: Use image node_id 2 for calling the GradientAttribution obj's underlying member method code with example usage: obj.compute_convergence_delta(attributions, start_point, end_point, target, additional_forward_args) and returns: _delta