:py:mod:`bfit.fit` ================== .. py:module:: bfit.fit .. autoapi-nested-parse:: Fitting Algorithms. .. !! processed by numpydoc !! Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: bfit.fit.KLDivergenceSCF bfit.fit.ScipyFit .. py:class:: KLDivergenceSCF(grid, density, model, mask_value=0.0, integral_dens=None, spherical=False) Bases: :py:obj:`_BaseFit` Kullback-Leibler Divergence Self-Consistent Fitting. This class optimizes the following objective function using self-consistent fitting method .. math:: \min_{\{c_i\}, \{\alpha\}} \int f(x) \log \bigg(\frac{f(x)}{\sum c_i b_i(x, \alpha_i)} \bigg)dx + \lambda(N - \sum c_i) where :math:`f` is the true density to be fitted, :math:`\lambda` is the Lagrange multiplier, :math:`c_i` is the coefficient of the ith basis function that all sum to the integral of density function :math:`N= \int f(x)dx`, and :math:`\alpha_i` is the exponent of the basis function :math:`b_i`. Construct the KLDivergenceSCF class. :param grid: Grid class that contains the grid points and integration methods on them. :type grid: (_BaseRadialGrid, CubicGrid) :param density: The true density evaluated on the grid points. :type density: ndarray :param model: The Gaussian basis model density. Located in `model.py`. :type model: (AtomicGaussianDensity, MolecularGaussianDensity) :param mask_value: The elements less than or equal to this number are masked in a division. :type mask_value: float, optional :param integral_dens: If this is provided, then the model is constrained to integrate to this value. If not, then the model is constrained to the numerical integration of the density. Useful when one knows the actual integration value of the density. :type integral_dens: float, optional :param spherical: Whether to perform spherical integration by adding :math:`4 \pi r^2` term to the integrand. Only used when grid is one-dimensional and positive (radial grid). :type spherical: bool .. !! processed by numpydoc !! .. py:method:: lagrange_multiplier(self) :property: Lagrange multiplier of Kullback-Leibler optimization problem. .. !! processed by numpydoc !! .. py:method:: run(self, c0, e0, opt_coeffs=True, opt_expons=True, maxiter=500, c_threshold=1e-06, e_threshold=1e-06, d_threshold=1e-06, disp=False) Optimize the coefficients & exponents of Gaussian basis functions self-consistently. :param c0: The initial coefficients of Gaussian basis functions. :type c0: ndarray :param e0: The initial exponents of Gaussian basis functions. :type e0: ndarray :param opt_coeffs: Whether to optimize coefficients of Gaussian basis functions. Default is true. :type opt_coeffs: bool, optional :param opt_expons: Whether to optimize exponents of Gaussian basis functions. Default is true. :type opt_expons: bool, optional :param maxiter: Maximum number of iterations. :type maxiter: int, optional :param c_threshold: The termination threshold for absolute change in coefficients. Default is 1e-6. :type c_threshold: float :param e_threshold: The termination threshold for absolute change in exponents. Default is 1e-6. :type e_threshold: float :param d_threshold: The termination threshold for absolute change in divergence value. Default is 1e-6. :type d_threshold: float :param disp: If true, then at each iteration various error measures will be printed. :type disp: bool :returns: The optimization results presented as a dictionary with keys: "coeffs" : ndarray The optimized coefficients of the Gaussian model. "exps" : ndarray The optimized exponents of the Gaussian model. "success": bool Whether the optimization exited successfully. "fun" : ndarray Values of the KL divergence (objective function) at each iteration. "performance" : ndarray Values of various performance measures of modeled density at each iteration, as computed by `goodness_of_fit()` method. "time" : float The time in seconds it took to complete the algorithm. :rtype: dict .. !! processed by numpydoc !! .. py:method:: grid(self) :property: Return grid object containing points and integration method. .. !! processed by numpydoc !! .. py:method:: density(self) :property: Return the true density evaluated on the grid points. .. !! processed by numpydoc !! .. py:method:: model(self) :property: Return the Gaussian basis model density. .. !! processed by numpydoc !! .. py:method:: measure(self) :property: Return the deviation measure between true density and model density. .. !! processed by numpydoc !! .. py:method:: integral_dens(self) :property: Return integration value of the density. .. !! processed by numpydoc !! .. py:method:: spherical(self) :property: Whether to perform spherical integration. .. !! processed by numpydoc !! .. py:method:: integrate(self, integrand) Integrate the integrand. :param integrand: The integrand :math:`f(x)` being integrated defined on :math:`N` points. If `spherical` attribute is true, then the radial component is integrated in spherical coordinates. :type integrand: ndarray(N,) :returns: Returns the integration :math:`\int f(x) dx` or if spherical is true then returns :math:`\int_0^\infty f(r) 4 \pi r^2 dr`. :rtype: float .. !! processed by numpydoc !! .. py:method:: goodness_of_fit(self, coeffs, expons) Compute various measures over the grid to determine the accuracy of the fitted model. In particular, it computes the integral of the model, the :math:`L_1` distance, the :math:`L_\infty` distance and attribute `measure` distance between true and model functions. :param coeffs: The coefficients of Gaussian basis functions. :type coeffs: ndarray :param expons: The exponents of Gaussian basis functions. :type expons: ndarray :returns: * **integral** (*float*) -- Integral of approximate model density, i.e. norm of approximate model density. * **l_1** (*float*) -- Integral of absolute difference between density and approximate model density. This is defined to be :math:`L_(f, g) = \int |f(x) - g(x)| dx`. * **l_infinity** (*float*) -- The maximum absolute difference between density and approximate model density. This is defined to be :math:`L_\infty(f, g) = \max |f(x) - g(x)|`. * **least_squares** (*float*) -- Square of the :math:`L_2` norm between density and approximate model density. This is defined to be :math:`L_2^2(f, g) = \int (f(x) - g(x))^2 dx`. * **kullback_leibler** (*float*) -- Kullback-Leibler divergence between density and approximate model density. This is defined to be :math:`KL(f, g) = \int f(x) \log\bigg(\frac{f(x)}{g(x)}\bigg)dx`. If :math:`g` is negative, then this returns infinity. .. !! processed by numpydoc !! .. py:class:: ScipyFit(grid, density, model, measure=KLDivergence, method='SLSQP', weights=None, integral_dens=None, spherical=False) Bases: :py:obj:`_BaseFit` Optimize least-squares or Kullback-Leibler of Gaussian functions using `Scipy.optimize`. Least-squares objective function w.r.t. Gaussian basis-functions is defined as .. math:: \min_{\{c_i\}, \{\alpha\}} \int \bigg(f(x) - \sum c_i b_k(x, \alpha_i) \bigg)^2 dx The Kullback-Leibler divergence function is defined as .. math:: \min_{\{c_i\}, \{\alpha\}, \sum c_i = N} \int f(x) \log \bigg(\frac{f(x)}{\sum c_i b_i(x, \alpha_i)} \bigg)dx, where :math:`f` is the density to be fitted to, :math:`c_i, \alpha_i` are the coefficeints and exponents of the Gaussian basis functions, and :math:`N = \int f(x)dx` is the integral of the density function. .. rubric:: Notes - Note that the Kullback-Leibler between two functions :math:`f` and :math:`g` is positive if and only if the integrals of :math:`f` and :math:`g` are identical. The `with_constraint` attribute must be True for optimizing Kullback-Leibler. Construct the ScipyFit object. :param grid: The grid class. :type grid: (_BaseRadialGrid, CubicGrid) :param density: The true density evaluated on the grid points. :type density: ndarray(N,) :param model: The Gaussian basis model density. :type model: (AtomicGaussianDensity, MolecularGaussianDensity) :param measure: The deviation measure between true density and model density. See bfit.measure.py for examples of measures to use. :type measure: bfit.measure.Measure :param method: The method used for optimizing parameters. Default is "slsqp". See "scipy.optimize.minimize" for options. :type method: str, optional :param weights: The weights of objective function at each point. If `None`, 1.0 is used. :type weights: ndarray, optional :param integral_dens: If this is provided, then the model is constrained to integrate to this value. If not, then the model is constrained to the numerical integration of the density. Useful when one knows the actual integration value of the density. :type integral_dens: float, optional :param spherical: Whether to perform spherical integration by adding :math:`4 \pi r^2` term to the integrand. Only used when grid is one-dimensional and positive (radial grid). :type spherical: bool .. !! processed by numpydoc !! .. py:method:: run(self, c0, e0, opt_coeffs=True, opt_expons=True, maxiter=1000, tol=1e-14, disp=False, with_constraint=True) Optimize coefficients and/or exponents of Gaussian basis functions with constraint. :param c0: Initial guess for coefficients of Gaussian basis functions. :type c0: ndarray :param e0: Initial guess for exponents of Gaussian basis functions. :type e0: ndarray :param opt_coeffs: Whether to optimize coefficients of Gaussian basis functions. :type opt_coeffs: bool, optional :param opt_expons: Whether to optimize exponents of Gaussian basis functions. :type opt_expons: bool, optional :param maxiter: Maximum number of iterations. :type maxiter: int, optional :param tol: For slsqp. precision goal for the value of objective function in the stopping criterion. For trust-constr, it is precision goal for the change in the variables. :type tol: float, optional :param disp: If True, then it will print the iteration errors, convergence messages from the optimizer and will print out various error measures at each iteration. :type disp: bool :param with_constraint: If true, then adds the constraint that the integration of the model density must be equal to the constraint of true density. The default is True. :type with_constraint: bool :returns: The optimization results presented as a dictionary containing: "coeffs" : ndarray The optimized coefficients of the Gaussian model. "exps" : ndarray The optimized exponents of the Gaussian model. "success": bool Whether the optimization exited successfully. "message" : str Information about the cause of termination. "fun" : float Values of KL divergence (objective function) at the final iteration. "jacobian": ndarray The Jacobian of the objective function w.r.t. coefficients and exponents. "performance" : list Values of various performance measures of modeled density at each iteration, as computed by `_BaseFit.goodness_of_fit` method. "time" : float The time in seconds it took to optimize. :rtype: dict .. rubric:: Notes - The coefficients and exponents are bounded to be positive. .. !! processed by numpydoc !! .. py:method:: func(self, x, *args) Compute objective function and its derivative w.r.t. Gaussian basis parameters. :param x: The parameters of Gaussian basis which is being optimized. Contains both the coefficients and exponents together in a 1-D array. :type x: ndarray :param args: Additional arguments to the model. :returns: The objective function value and its derivative wrt to coefficients and exponents. :rtype: (float, ndarray) .. !! processed by numpydoc !! .. py:method:: const_norm(self, x, *args) Compute deviation in normalization constraint :math:`\sum c_i - \int f(x) dx`. :param x: The parameters of Gaussian basis-functions. Contains both the coefficients and exponents together in a 1-D array. :type x: ndarray :param args: Additional parameters for the model. :returns: The deviation of the integrla with the normalization constant. :rtype: float .. !! processed by numpydoc !! .. py:method:: evaluate_model(self, x, *args) Evaluate the model density & its derivative. :param x: The parameters of Gaussian basis-functions. Contains both the coefficients and exponents together in a 1-D array. :type x: ndarray :param args: Additional parameters for the model. :returns: Evaluates the model density & its derivative. :rtype: float, ndarray .. !! processed by numpydoc !! .. py:method:: grid(self) :property: Return grid object containing points and integration method. .. !! processed by numpydoc !! .. py:method:: density(self) :property: Return the true density evaluated on the grid points. .. !! processed by numpydoc !! .. py:method:: model(self) :property: Return the Gaussian basis model density. .. !! processed by numpydoc !! .. py:method:: measure(self) :property: Return the deviation measure between true density and model density. .. !! processed by numpydoc !! .. py:method:: integral_dens(self) :property: Return integration value of the density. .. !! processed by numpydoc !! .. py:method:: spherical(self) :property: Whether to perform spherical integration. .. !! processed by numpydoc !! .. py:method:: integrate(self, integrand) Integrate the integrand. :param integrand: The integrand :math:`f(x)` being integrated defined on :math:`N` points. If `spherical` attribute is true, then the radial component is integrated in spherical coordinates. :type integrand: ndarray(N,) :returns: Returns the integration :math:`\int f(x) dx` or if spherical is true then returns :math:`\int_0^\infty f(r) 4 \pi r^2 dr`. :rtype: float .. !! processed by numpydoc !! .. py:method:: goodness_of_fit(self, coeffs, expons) Compute various measures over the grid to determine the accuracy of the fitted model. In particular, it computes the integral of the model, the :math:`L_1` distance, the :math:`L_\infty` distance and attribute `measure` distance between true and model functions. :param coeffs: The coefficients of Gaussian basis functions. :type coeffs: ndarray :param expons: The exponents of Gaussian basis functions. :type expons: ndarray :returns: * **integral** (*float*) -- Integral of approximate model density, i.e. norm of approximate model density. * **l_1** (*float*) -- Integral of absolute difference between density and approximate model density. This is defined to be :math:`L_(f, g) = \int |f(x) - g(x)| dx`. * **l_infinity** (*float*) -- The maximum absolute difference between density and approximate model density. This is defined to be :math:`L_\infty(f, g) = \max |f(x) - g(x)|`. * **least_squares** (*float*) -- Square of the :math:`L_2` norm between density and approximate model density. This is defined to be :math:`L_2^2(f, g) = \int (f(x) - g(x))^2 dx`. * **kullback_leibler** (*float*) -- Kullback-Leibler divergence between density and approximate model density. This is defined to be :math:`KL(f, g) = \int f(x) \log\bigg(\frac{f(x)}{g(x)}\bigg)dx`. If :math:`g` is negative, then this returns infinity. .. !! processed by numpydoc !!