:py:mod:`bfit.measure` ====================== .. py:module:: bfit.measure .. autoapi-nested-parse:: Measure Module. .. !! processed by numpydoc !! Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: bfit.measure.SquaredDifference bfit.measure.KLDivergence bfit.measure.TsallisDivergence .. py:class:: SquaredDifference Bases: :py:obj:`Measure` Squared Difference Class for performing the Least-Squared method. .. !! processed by numpydoc !! .. py:method:: evaluate(self, density, model, deriv=False) Evaluate squared difference b/w density & model on the grid points. This is defined to be :math:`(f(x) - g(x))^2`, where, :math:`f` is the true function, and :math:`g` is the model function, :param density: The exact density evaluated on the grid points. :type density: ndarray(N,) :param model: The model density evaluated on the grid points. :type model: ndarray(N,) :param deriv: Whether to compute the derivative of squared difference w.r.t. model density. Default is false. :type deriv: bool, optional :returns: * **m** (*ndarray(N,)*) -- The squared difference between density & model on the grid points. * **dm** (*ndarray(N,)*) -- The derivative of squared difference w.r.t. model density evaluated on the grid points, only returned if `deriv=True`. .. rubric:: Notes - This class returns the squared difference at each point in the domain. One would need to integrate this to get the desired least-squares. .. !! processed by numpydoc !! .. py:class:: KLDivergence(mask_value=1e-12, negative_val=100000.0) Bases: :py:obj:`Measure` Kullback-Leibler Divergence Class. Construct the Kullback-Leibler class. :param mask_value: The elements less than or equal to this number are masked in a division, and then replaced with the value of one so that logarithm of one is zero. :type mask_value: float, optional :param negative_val: Constant value that gets returned if the model density is negative (i.e. not a true probability distribution). Useful for optimization algorithms with weak constraints. :type negative_val: (float, np.inf), optional .. !! processed by numpydoc !! .. py:method:: mask_value(self) :property: Masking value used when evaluating the measure. .. !! processed by numpydoc !! .. py:method:: negative_val(self) :property: Value that gets returned if the model density is negative. .. !! processed by numpydoc !! .. py:method:: evaluate(self, density, model, deriv=False) Evaluate the integrand of Kullback-Leibler divergence b/w true & model. .. math :: D(f, g) := \int_G f(x) \ln \bigg( \frac{f(x)}{g(x)} \bigg) dx where, :math:`f` is the true probability distribution, :math:`g` is the model probability distribution, :math:`G` is the grid being integrated on. If the model density is negative, then this function will return infinity. If :math:`g(x) < \text{mask value}` then :math:`\frac{f(x)}{g(x)} = 1`. :param density: The exact density evaluated on the grid points. :type density: ndarray(N,) :param model: The model density evaluated on the grid points. :type model: ndarray(N,) :param deriv: Whether to return the derivative of divergence w.r.t. model density, as well. Default is false. :type deriv: bool, optional :returns: * **m** (*ndarray(N,)*) -- The Kullback-Leibler divergence between density & model on the grid points. * **dm** (*ndarray(N,)*) -- The derivative of divergence w.r.t. model density evaluated on the grid points. Only returned if `deriv=True`. :raises ValueError :: If the model density is negative, then the integrand is un-defined. .. rubric:: Notes - Values of nodel density that are less than `mask_value` are masked when used in division and then replaced with the value of 1 so that logarithm of one is zero. - This class does not return the Kullback-Leibler divergence. One would need to integrate this to get the KL value. .. !! processed by numpydoc !! .. py:class:: TsallisDivergence(alpha=1.001, mask_value=1e-12) Bases: :py:obj:`Measure` Tsallis Divergence Class. Construct the Kullback-Leibler class. :param alpha: The alpha parameter of the Tsallis divergence. If it tends towards one, then Tsallis divergence approaches Kullback-Leibler. See Notes for more information. :type alpha: float :param mask_value: The elements less than or equal to this number are masked in a division, and then replaced with the value of one so that logarithm of one is zero. :type mask_value: float, optional .. rubric:: Notes - Care should be taken on :math:`\alpha`. If :math:`\alpha > 1` and it isn't too close to 1, then Tsallis divergence upper bounds the Kullback-Leibler and can be useful for optimization purposes. .. !! processed by numpydoc !! .. py:method:: alpha(self) :property: Return alpha parameter of the Tsallis divergence. .. !! processed by numpydoc !! .. py:method:: mask_value(self) :property: Return masking value used when evaluating the measure. .. !! processed by numpydoc !! .. py:method:: evaluate(self, density, model, deriv=False) Evaluate the integrand of Tsallis divergence ([R10aca1d8b724-1]_, [R10aca1d8b724-2]_) on grid points. Defined as follows: .. math:: \int_G \frac{1}{\alpha - 1} f(x) \bigg(\frac{f(x)}{g(x)}^{q- 1} - 1\bigg) dx, where :math:`f` is the true probability distribution, :math:`g` is the model probability distribution. :math:`G` is the grid being integrated on. :param density: The exact density evaluated on the grid points. :type density: ndarray(N,) :param model: The model density evaluated on the grid points. :type model: ndarray(N,) :param deriv: Whether to compute the derivative of squared difference w.r.t. model density. :type deriv: bool, optional :returns: * **m** (*ndarray(N,)*) -- The Tsallis divergence between density & model on the grid points. * **dm** (*ndarray(N,)*) -- The derivative of divergence w.r.t. model density evaluated on the grid points. Only returned if `deriv=True`. .. rubric:: Notes - This does not impose non-negativity of the model density, unlike the Kullback-Leibler. - Values of Model density that are less than `mask_value` are masked when used in division and then replaced with the value of 0. - As :math:`\alpha` parameter tends towards one, then this converges to the Kullback-Leibler. This is particularly useful for trust-region methods that don't impose strict constraints during the optimization procedure. - Care should be taken on :math:`\alpha`. If :math:`\alpha > 1` and it isn't too close to 1, then Tsallis divergence upper bounds the Kullback-Leibler and can be useful for optimization purposes. .. rubric:: References .. [R10aca1d8b724-1] Ayers, Paul W. "Information theory, the shape function, and the Hirshfeld atom." Theoretical Chemistry Accounts 115.5 (2006): 370-378. .. [R10aca1d8b724-2] Heidar-Zadeh, Farnaz, Ivan Vinogradov, and Paul W. Ayers. "Hirshfeld partitioning from non-extensive entropies." Theoretical Chemistry Accounts 136.4 (2017): 54. .. !! processed by numpydoc !!