diff --git a/README.md b/README.md index 3b9c350..ccb4421 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,12 @@ -BFit -==== +# `BFit` + [![This project supports Python 3.9+](https://img.shields.io/badge/Python-3.9+-blue.svg)](https://python.org/downloads) [![GitHub Actions CI Tox Status](https://github.com/theochem/bfit/actions/workflows/ci_tox.yml/badge.svg?branch=master)](https://github.com/theochem/bfit/actions/workflows/ci_tox.yml) [![GPLv3 License](https://img.shields.io/badge/License-GPL%20v3-yellow.svg)](https://opensource.org/licenses/) [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/theochem/bfit/master?labpath=%2Fexamples%2F) +## About + BFit is a Python library for fitting a convex sum of Gaussian functions to any probability distribution. It is primarily intended for quantum chemistry applications, where the basis functions are Gaussians and the fitted probability distribution is a scalar function like @@ -16,7 +18,7 @@ or various files in the example [folder](https://github.com/theochem/BFit/tree/m to see specific examples on how to fit using the different algorithms and objective functions. For further information about the api, please visit -[**BFit Documentation**](https://bfit.qcdevs.org/). +[--BFit Documentation--](https://bfit.qcdevs.org/). The instructions to access the results of the fitted atomic densities using KL-FI method is shown in the section below. @@ -24,38 +26,41 @@ shown in the section below. To report any issues or ask questions, either [open an issue]( https://github.com/theochem/bfit/issues/new) or email [qcdevs@gmail.com](). +## Citation -Citation --------- Please use the following citation in any publication using BFit library: -> Tehrani, A., M. Anderson, J. S., Chakraborty, D., Rodriguez-Hernandez, J. I., Thompson, D. C., Verstraelen, T., Ayers, P. W., & Heidar-Zadeh, F. -> An information-theoretic approach to basis-set fitting of electron densities and other non-negative functions. -> Journal of Computational Chemistry. https://doi.org/10.1002/jcc.27170 - +```bibtex +@article{bfit2023, +author = {Tehrani, Alireza and Anderson, James S. M. and Chakraborty, Debajit and Rodriguez-Hernandez, Juan I. and Thompson, David C. and Verstraelen, Toon and Ayers, Paul W. and Heidar-Zadeh, Farnaz}, +title = {An information-theoretic approach to basis-set fitting of electron densities and other non-negative functions}, +journal = {Journal of Computational Chemistry}, +volume = {44}, +number = {25}, +pages = {1998-2015}, +doi = {https://doi.org/10.1002/jcc.27170}, +url = {https://onlinelibrary.wiley.com/doi/abs/10.1002/jcc.27170}, +year = {2023} +} +``` -Dependencies ------------- -* Python >= 3.0: http://www.python.org/ -* NumPy >= 1.18.5: http://www.numpy.org/ -* SciPy >= 1.5.0: http://www.scipy.org/ -* Matplotlib >=3.2.0: https://matplotlib.org/ -* Sphinx >= 2.3.0: https://www.sphinx-doc.org/ +## Dependencies +- Python >= 3.9: http://www.python.org/ +- NumPy >= 1.18.5: http://www.numpy.org/ +- SciPy >= 1.5.0: http://www.scipy.org/ +- Matplotlib >=3.2.0: https://matplotlib.org/ +- Sphinx >= 2.3.0: https://www.sphinx-doc.org/ +## Installation -Installation ------------- -Three options to install BFit: +There are two options to install BFit: ```bash # install from source git clone https://github.com/theochem/bfit.git pip install . - # or install using conda. -conda install -c theochem qc-bfit - # or install using pip. pip install qc-bfit @@ -64,34 +69,33 @@ pytest -v . ``` -Features --------- +## Features The features of this software are: -* Gaussian Basis set model: - * Construct s-type and p-type Gaussian functions, - * Compute Atomic Densities or Molecular Densities. +- Gaussian Basis set model: + - Construct s-type and p-type Gaussian functions, + - Compute Atomic Densities or Molecular Densities. + +- Fitting measures: + - Least-squares, + - Kullback-Leibler divergence, + - Tsallis divergence. -* Fitting measures: - * Least-squares, - * Kullback-Leibler divergence, - * Tsallis divergence. +- Optimization procedures + - Optimize using SLSQP in "scipy.minimize" procedures. + - Optimize Kullback-Leibler using self-consistent iterative method see [paper](#citing). + - Greedy method for optimization of Kullback-Leibler and Least-Squares, see [paper](#citing). -* Optimization procedures - * Optimize using SLSQP in "scipy.minimize" procedures. - * Optimize Kullback-Leibler using self-consistent iterative method see [paper](#citing). - * Greedy method for optimization of Kullback-Leibler and Least-Squares, see [paper](#citing). +- Read/Parse Hatree-Fock wavefunctions for atomic systems: + - Includes: anions, cations and heavy elements, see [data](data/README.md) page. + - Compute: + - Atomic density, including core, and valence densities, + - Positive definite kinetic energy density. -* Read/Parse Hatree-Fock wavefunctions for atomic systems: - * Includes: anions, cations and heavy elements, see [data](data/README.md) page. - * Compute: - * Atomic density, including core, and valence densities, - * Positive definite kinetic energy density. +## Final Models of Fitting Atomic Densities -Final Models of Fitting Atomic Densities ------------------------------------------- The final model of fitting the atomic densities using the Kullback-Leibler (KL) divergence fixed point iteration method can be accessed by opening the file `./bfit/data/kl_fpi_results.npz` with numpy. Similarly, the results from optimizing KL with SLSQP method using `kl_fpi_results.npz` @@ -112,6 +116,7 @@ print(exponents[:num_s]) print("p-type exponents") print(exponents[num_s:]) ``` + Alternatively, one can load these results using JSON file. ```python import json @@ -138,12 +143,11 @@ model = AtomicGaussianDensity(grid.points, num_s=num_s, num_p=num_p, normalize=T model_pts = model.evaluate(coefficients, exponents) print("Numerical integral (spherically) of the model %f." % - grid.integrate(model_pts * 4.0 * np.pi * grid.points**2.0) + grid.integrate(model_pts - 4.0 - np.pi - grid.points--2.0) ) ``` - -## Example +## Examples There are four steps to using BFit. ### 1. Specify the Grid Object.