bfit.measure

Measure Module.

Module Contents

Classes

SquaredDifference	Squared Difference Class for performing the Least-Squared method.
KLDivergence	Kullback-Leibler Divergence Class.
TsallisDivergence	Tsallis Divergence Class.

class bfit.measure.SquaredDifference

Bases: Measure

Squared Difference Class for performing the Least-Squared method.

evaluate(self, density, model, deriv=False)

Evaluate squared difference b/w density & model on the grid points.

This is defined to be \((f(x) - g(x))^2\), where, \(f\) is the true function, and \(g\) is the model function,

Parameters

• density (ndarray(N,)) – The exact density evaluated on the grid points.

• model (ndarray(N,)) – The model density evaluated on the grid points.

• deriv (bool, optional) – Whether to compute the derivative of squared difference w.r.t. model density. Default is false.

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.

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.

class bfit.measure.KLDivergence(mask_value=1e-12, negative_val=100000.0)

Bases: Measure

Kullback-Leibler Divergence Class.

Construct the Kullback-Leibler class.

Parameters

• mask_value (float, optional) – 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.

• negative_val ((float, np.inf), optional) – 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.

property mask_value(self)

Masking value used when evaluating the measure.

property negative_val(self)

Value that gets returned if the model density is negative.

evaluate(self, density, model, deriv=False)

Evaluate the integrand of Kullback-Leibler divergence b/w true & model.

\[D(f, g) := \int_G f(x) \ln \bigg( \frac{f(x)}{g(x)} \bigg) dx\]

where, \(f\) is the true probability distribution, \(g\) is the model probability distribution, \(G\) is the grid being integrated on.

If the model density is negative, then this function will return infinity. If \(g(x) < \text{mask value}\) then \(\frac{f(x)}{g(x)} = 1\).

Parameters

• density (ndarray(N,)) – The exact density evaluated on the grid points.

• model (ndarray(N,)) – The model density evaluated on the grid points.

• deriv (bool, optional) – Whether to return the derivative of divergence w.r.t. model density, as well. Default is false.

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.

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.

class bfit.measure.TsallisDivergence(alpha=1.001, mask_value=1e-12)

Bases: Measure

Tsallis Divergence Class.

Construct the Kullback-Leibler class.

Parameters

• alpha (float) – The alpha parameter of the Tsallis divergence. If it tends towards one, then Tsallis divergence approaches Kullback-Leibler. See Notes for more information.

• mask_value (float, optional) – 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.

Notes

• Care should be taken on \(\alpha\). If \(\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.

property alpha(self)

Return alpha parameter of the Tsallis divergence.

property mask_value(self)

Return masking value used when evaluating the measure.

evaluate(self, density, model, deriv=False)

Evaluate the integrand of Tsallis divergence ([1], [2]) on grid points.

Defined as follows:

\[\int_G \frac{1}{\alpha - 1} f(x) \bigg(\frac{f(x)}{g(x)}^{q- 1} - 1\bigg) dx,\]

where \(f\) is the true probability distribution, \(g\) is the model probability distribution. \(G\) is the grid being integrated on.

Parameters

• density (ndarray(N,)) – The exact density evaluated on the grid points.

• model (ndarray(N,)) – The model density evaluated on the grid points.

• deriv (bool, optional) – Whether to compute the derivative of squared difference w.r.t. model density.

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.

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 \(\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 \(\alpha\). If \(\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.

References

1

Ayers, Paul W. “Information theory, the shape function, and the Hirshfeld atom.” Theoretical Chemistry Accounts 115.5 (2006): 370-378.

2

Heidar-Zadeh, Farnaz, Ivan Vinogradov, and Paul W. Ayers. “Hirshfeld partitioning from non-extensive entropies.” Theoretical Chemistry Accounts 136.4 (2017): 54.