class_docstr: Compute the `KL divergence`_.
  
  .. math::
      D_{KL}(P||Q) = \sum_{x\in\mathcal{X}} P(x) \log\frac{P(x)}{Q{x}}
  
  Where :math:`P` and :math:`Q` are probability distributions where :math:`P` usually represents a distribution
  over data and :math:`Q` is often a prior or approximation of :math:`P`. It should be noted that the KL divergence
  is a non-symmetrical metric i.e. :math:`D_{KL}(P||Q) \neq D_{KL}(Q||P)`.
  
  As input to ``forward`` and ``update`` the metric accepts the following input:
  
  - ``p`` (:class:`~torch.Tensor`): a data distribution with shape ``(N, d)``
  - ``q`` (:class:`~torch.Tensor`): prior or approximate distribution with shape ``(N, d)``
  
  As output of ``forward`` and ``compute`` the metric returns the following output:
  
  - ``kl_divergence`` (:class:`~torch.Tensor`): A tensor with the KL divergence
  
  Args:
      log_prob: bool indicating if input is log-probabilities or probabilities. If given as probabilities,
          will normalize to make sure the distributes sum to 1.
      reduction:
          Determines how to reduce over the ``N``/batch dimension:
  
          - ``'mean'`` [default]: Averages score across samples
          - ``'sum'``: Sum score across samples
          - ``'none'`` or ``None``: Returns score per sample
  
      kwargs: Additional keyword arguments, see :ref:`Metric kwargs` for more info.
  
  Raises:
      TypeError:
          If ``log_prob`` is not an ``bool``.
      ValueError:
          If ``reduction`` is not one of ``'mean'``, ``'sum'``, ``'none'`` or ``None``.
  
  .. note::
      Half precision is only support on GPU for this metric
  
  Example:
      >>> from torch import tensor
      >>> from torchmetrics.regression import KLDivergence
      >>> p = tensor([[0.36, 0.48, 0.16]])
      >>> q = tensor([[1/3, 1/3, 1/3]])
      >>> kl_divergence = KLDivergence()
      >>> kl_divergence(p, q)
      tensor(0.0853)
class_docstr_tok: ["Compute","the","`","KL","divergence","`","_",".","..","math",":",":","D_","{","KL","}","(","P||Q",")","=","\\sum_","{","x\\in\\mathcal","{","X","}","}","P","(","x",")","\\log\\frac","{","P","(","x",")","}","{","Q","{","x","}","}","Where",":","math",":","`","P","`","and",":","math",":","`","Q","`","are","probability","distributions","where",":","math",":","`","P","`","usually","represents","a","distribution","over","data","and",":","math",":","`","Q","`","is","often","a","prior","or","approximation","of",":","math",":","`","P","`",".","It","should","be","noted","that","the","KL","divergence","is","a","non-symmetrical","metric","i.e",".",":","math",":","`","D_","{","KL","}","(","P||Q",")","\\neq","D_","{","KL","}","(","Q||P",")","`",".","As","input","to","``","forward","``","and","``","update","``","the","metric","accepts","the","following","input",":","-","``","p","``","(",":","class",":","`","~torch.Tensor","`",")",":","a","data","distribution","with","shape","``","(","N",",","d",")","``","-","``","q","``","(",":","class",":","`","~torch.Tensor","`",")",":","prior","or","approximate","distribution","with","shape","``","(","N",",","d",")","``","As","output","of","``","forward","``","and","``","compute","``","the","metric","returns","the","following","output",":","-","``","kl_divergence","``","(",":","class",":","`","~torch.Tensor","`",")",":","A","tensor","with","the","KL","divergence","Args",":","log_prob",":","bool","indicating","if","input","is","log-probabilities","or","probabilities",".","If","given","as","probabilities",",","will","normalize","to","make","sure","the","distributes","sum","to","1.","reduction",":","Determines","how","to","reduce","over","the","``","N","``","\/batch","dimension",":","-","``","'mean","'","``","[","default","]",":","Averages","score","across","samples","-","``","'sum","'","``",":","Sum","score","across","samples","-","``","'none","'","``","or","``","None","``",":","Returns","score","per","sample","kwargs",":","Additional","keyword","arguments",",","see",":","ref",":","`","Metric","kwargs","`","for","more","info",".","Raises",":","TypeError",":","If","``","log_prob","``","is","not","an","``","bool","``",".","ValueError",":","If","``","reduction","``","is","not","one","of","``","'mean","'","``",",","``","'sum","'","``",",","``","'none","'","``","or","``","None","``",".","..","note",":",":","Half","precision","is","only","support","on","GPU","for","this","metric","Example",":",">",">",">","from","torch","import","tensor",">",">",">","from","torchmetrics.regression","import","KLDivergence",">",">",">","p","=","tensor","(","[","[","0.36",",","0.48",",","0.16","]","]",")",">",">",">","q","=","tensor","(","[","[","1\/3",",","1\/3",",","1\/3","]","]",")",">",">",">","kl_divergence","=","KLDivergence","(",")",">",">",">","kl_divergence","(","p",",","q",")","tensor","(","0.0853",")"]
docstr: Plot a single or multiple values from the metric.
  
  Args:
      val: Either a single result from calling `metric.forward` or `metric.compute` or a list of these results.
          If no value is provided, will automatically call `metric.compute` and plot that result.
      ax: An matplotlib axis object. If provided will add plot to that axis
  
  Returns:
      Figure and Axes object
  
  Raises:
      ModuleNotFoundError:
          If `matplotlib` is not installed
  
  .. plot::
      :scale: 75
  
      >>> from torch import randn
      >>> # Example plotting a single value
      >>> from torchmetrics.regression import KLDivergence
      >>> metric = KLDivergence()
      >>> metric.update(randn(10,3).softmax(dim=-1), randn(10,3).softmax(dim=-1))
      >>> fig_, ax_ = metric.plot()
  
  .. plot::
      :scale: 75
  
      >>> from torch import randn
      >>> # Example plotting multiple values
      >>> from torchmetrics.regression import KLDivergence
      >>> metric = KLDivergence()
      >>> values = []
      >>> for _ in range(10):
      ...     values.append(metric(randn(10,3).softmax(dim=-1), randn(10,3).softmax(dim=-1)))
      >>> fig, ax = metric.plot(values)
docstr_tok: ["Plot","a","single","or","multiple","values","from","the","metric",".","Args",":","val",":","Either","a","single","result","from","calling","`","metric.forward","`","or","`","metric.compute","`","or","a","list","of","these","results",".","If","no","value","is","provided",",","will","automatically","call","`","metric.compute","`","and","plot","that","result",".","ax",":","An","matplotlib","axis","object",".","If","provided","will","add","plot","to","that","axis","Returns",":","Figure","and","Axes","object","Raises",":","ModuleNotFoundError",":","If","`","matplotlib","`","is","not","installed","..","plot",":",":",":","scale",":","75",">",">",">","from","torch","import","randn",">",">",">","#","Example","plotting","a","single","value",">",">",">","from","torchmetrics.regression","import","KLDivergence",">",">",">","metric","=","KLDivergence","(",")",">",">",">","metric.update","(","randn","(","10,3",")",".softmax","(","dim=-1",")",",","randn","(","10,3",")",".softmax","(","dim=-1",")",")",">",">",">","fig_",",","ax_","=","metric.plot","(",")","..","plot",":",":",":","scale",":","75",">",">",">","from","torch","import","randn",">",">",">","#","Example","plotting","multiple","values",">",">",">","from","torchmetrics.regression","import","KLDivergence",">",">",">","metric","=","KLDivergence","(",")",">",">",">","values","=","[","]",">",">",">","for","_","in","range","(","10",")",":","...","values.append","(","metric","(","randn","(","10,3",")",".softmax","(","dim=-1",")",",","randn","(","10,3",")",".softmax","(","dim=-1",")",")",")",">",">",">","fig",",","ax","=","metric.plot","(","values",")"]
code: def plot(
      self,
      val: Optional[Union[Tensor, Sequence[Tensor]]] = None,
      ax: Optional[_AX_TYPE] = None,
  ) -> _PLOT_OUT_TYPE:
      """Plot a single or multiple values from the metric.
  
      Args:
          val: Either a single result from calling `metric.forward` or `metric.compute` or a list of these results.
              If no value is provided, will automatically call `metric.compute` and plot that result.
          ax: An matplotlib axis object. If provided will add plot to that axis
  
      Returns:
          Figure and Axes object
  
      Raises:
          ModuleNotFoundError:
              If `matplotlib` is not installed
  
      .. plot::
          :scale: 75
  
          >>> from torch import randn
          >>> # Example plotting a single value
          >>> from torchmetrics.regression import KLDivergence
          >>> metric = KLDivergence()
          >>> metric.update(randn(10,3).softmax(dim=-1), randn(10,3).softmax(dim=-1))
          >>> fig_, ax_ = metric.plot()
  
      .. plot::
          :scale: 75
  
          >>> from torch import randn
          >>> # Example plotting multiple values
          >>> from torchmetrics.regression import KLDivergence
          >>> metric = KLDivergence()
          >>> values = []
          >>> for _ in range(10):
          ...     values.append(metric(randn(10,3).softmax(dim=-1), randn(10,3).softmax(dim=-1)))
          >>> fig, ax = metric.plot(values)
  
      """
      return self._plot(val, ax)
  
file_path: torchmetrics/src/torchmetrics/regression/kl_divergence.py
imports: from typing import Any, Optional, Sequence, Union
  import torch
  from torch import Tensor
  from typing_extensions import Literal
  from torchmetrics.functional.regression.kl_divergence import _kld_compute, _kld_update
  from torchmetrics.metric import Metric
  from torchmetrics.utilities.data import dim_zero_cat
  from torchmetrics.utilities.imports import _MATPLOTLIB_AVAILABLE
  from torchmetrics.utilities.plot import _AX_TYPE, _PLOT_OUT_TYPE
label_desc: Use image node_id 4 for calling the KLDivergence obj's underlying member method code with example usage: obj.plot(val, ax) and returns: self