{"id":20795238,"url":"https://github.com/theochem/bfit","last_synced_at":"2025-07-03T20:33:51.671Z","repository":{"id":40242602,"uuid":"135759959","full_name":"theochem/BFit","owner":"theochem","description":"Fit a convex sum of positive basis functions to any probability distribution","archived":false,"fork":false,"pushed_at":"2025-06-26T02:48:56.000Z","size":84332,"stargazers_count":6,"open_issues_count":4,"forks_count":4,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-06-26T03:32:11.581Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://bfit.qcdevs.org/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/theochem.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-06-01T20:21:04.000Z","updated_at":"2025-06-26T02:48:59.000Z","dependencies_parsed_at":"2024-11-17T16:21:54.247Z","dependency_job_id":"c17d333d-b199-4d72-baf3-f2d7206caf70","html_url":"https://github.com/theochem/BFit","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/theochem/BFit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theochem%2FBFit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theochem%2FBFit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theochem%2FBFit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theochem%2FBFit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/theochem","download_url":"https://codeload.github.com/theochem/BFit/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theochem%2FBFit/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261995998,"owners_count":23242208,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-17T16:20:32.408Z","updated_at":"2025-07-03T20:33:51.636Z","avatar_url":"https://github.com/theochem.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `BFit`\n\n[![This project supports Python 3.9+](https://img.shields.io/badge/Python-3.9+-blue.svg)](https://python.org/downloads)\n[![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)\n[![GPLv3 License](https://img.shields.io/badge/License-GPL%20v3-yellow.svg)](https://opensource.org/licenses/)\n[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/theochem/bfit/master?labpath=%2Fexamples%2F)\n\n## About\n\nBFit is a Python library for fitting a convex sum of Gaussian functions to any\nprobability distribution. It is primarily intended for quantum chemistry applications, where the\nbasis functions are Gaussians and the fitted probability distribution is a scalar function like\nthe electron density.\n\nSee the example [section](#kl-fpi-models-of-atomic-densities) down below or the interactive\n[Jupyter binder](https://mybinder.org/v2/gh/theochem/bfit/master?labpath=%2Fexamples%2)\nor various files in the example [folder](https://github.com/theochem/BFit/tree/master/examples)\nto see specific examples on how to fit using the different algorithms and objective\nfunctions.\nFor further information about the api, please visit\n[--BFit Documentation--](https://bfit.qcdevs.org/).\n\nThe instructions to access the results of the fitted atomic densities using KL-FI method is\nshown in the section below.\n\nTo report any issues or ask questions, either [open an issue](\nhttps://github.com/theochem/bfit/issues/new) or email [qcdevs@gmail.com]().\n\n## Citation\n\nPlease use the following citation in any publication using BFit library:\n\n```bibtex\n@article{bfit2023,\nauthor = {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},\ntitle = {An information-theoretic approach to basis-set fitting of electron densities and other non-negative functions},\njournal = {Journal of Computational Chemistry},\nvolume = {44},\nnumber = {25},\npages = {1998-2015},\ndoi = {https://doi.org/10.1002/jcc.27170},\nurl = {https://onlinelibrary.wiley.com/doi/abs/10.1002/jcc.27170},\nyear = {2023}\n}\n```\n\n## Dependencies\n\n- Python \u003e= 3.9: http://www.python.org/\n- NumPy \u003e= 1.18.5: http://www.numpy.org/\n- SciPy \u003e= 1.5.0: http://www.scipy.org/\n- Matplotlib \u003e=3.2.0: https://matplotlib.org/\n- Sphinx \u003e= 2.3.0: https://www.sphinx-doc.org/\n\n## Installation\n\nThere are two options to install BFit:\n\n```bash\n# install from source\ngit clone https://github.com/theochem/bfit.git\npip install .\n\n# or install using pip.\npip install qc-bfit\n\n# run tests to make sure BFit was installed properly\npytest -v .\n```\n\n\n## Features\n\nThe features of this software are:\n\n- Gaussian Basis set model:\n  - Construct s-type and p-type Gaussian functions,\n  - Compute Atomic Densities or Molecular Densities.\n\n- Fitting measures:\n  - Least-squares,\n  - Kullback-Leibler divergence,\n  - Tsallis divergence.\n\n- Optimization procedures\n  - Optimize using SLSQP in \"scipy.minimize\" procedures.\n  - Optimize Kullback-Leibler using self-consistent iterative method see [paper](#citing).\n  - Greedy method for optimization of Kullback-Leibler and Least-Squares, see [paper](#citing).\n\n- Read/Parse Hatree-Fock wavefunctions for atomic systems:\n  - Includes: anions, cations and heavy elements, see [data](data/README.md) page.\n  - Compute:\n    - Atomic density, including core, and valence densities,\n    - Positive definite kinetic energy density.\n\n\n## Final Models of Fitting Atomic Densities\n\nThe final model of fitting the atomic densities using the Kullback-Leibler (KL) divergence fixed point iteration method\ncan be accessed by opening the file `./bfit/data/kl_fpi_results.npz` with numpy.\nSimilarly, the results from optimizing KL with SLSQP method using `kl_fpi_results.npz`\nas initial guesses can be accessed by opening the file `./bfit/data/kl_slsqp_results.npz` with numpy.\nIn general, we recommend KL-SLSQP results over the KL-FPI results.\n```python\nimport numpy as np\n\nelement = \"be\"\nresults = np.load(\"./bfit/data/kl_fpi_results.npz\")\nnum_s = results[\"be_num_s\"]  # Number of s-type Gaussian function\nnum_p = results[\"be_num_p\"]  # Number of p-type Gaussian functions\ncoeffcients = results[\"be_coeffs\"]\nexponents = results[\"be_exps\"]\n\nprint(\"s-type exponents\")\nprint(exponents[:num_s])\nprint(\"p-type exponents\")\nprint(exponents[num_s:])\n```\n\nAlternatively, one can load these results using JSON file.\n```python\nimport json\nimport numpy as np\n\nelement = \"be\"\nwith open(\"./bfit/data/kl_fpi_results.json\") as file:\n    data = json.load(file)\n    data_element = data[element]\n\n    num_s = data_element[\"num_s\"]\n    num_p = data_element[\"num_p\"]\n    coeffcients = np.array(data_element[\"coeffs\"])\n    exponents = np.array(data_element[\"exps\"])\n```\n\nEvaluation of the normalized Gaussian model at a given set of points can also be computed\n```python\nfrom bfit.grid import ClenshawRadialGrid\nfrom bfit.model import AtomicGaussianDensity\n\ngrid = ClenshawRadialGrid(4, num_core_pts=10000, num_diffuse_pts=899, extra_pts=[50, 75, 100])\nmodel = AtomicGaussianDensity(grid.points, num_s=num_s, num_p=num_p, normalize=True)\nmodel_pts = model.evaluate(coefficients, exponents)\n\nprint(\"Numerical integral (spherically) of the model %f.\" %\n      grid.integrate(model_pts - 4.0 - np.pi - grid.points--2.0)\n)\n```\n\n## Examples\nThere are four steps to using BFit.\n\n### 1. Specify the Grid Object.\nThe grid is a uniform one-dimension grid with 100 points from 0. to 50.\n```python\nimport numpy as np\nfrom bfit.grid import UniformRadialGrid\ngrid = UniformRadialGrid(num_pts=100, min_radii=0., max_radii=50.)\n```\nSee [grid.py](bfit/grid.py), for different assortment of grids.\n\n### 2. Specify the Model Object.\nHere, the model distribution is 5 s-type, normalized Gaussian functions with center at the origin.\n```python\nfrom bfit.model import AtomicGaussianDensity\nmodel = AtomicGaussianDensity(grid.points, num_s=5, num_p=0, normalize=True)\n```\nSee [model.py](bfit/model.py) for more options of Gaussian models.\n\n### 3. Specify error measure.\nThe algorithm is fitted based on the [paper](#citing).\n\n```python\nfrom bfit.fit import KLDivergenceFPI\n\n# What you want fitted to should also be defined on `grid.points`.\ndensity = np.array([...])\nfit = KLDivergenceFPI(grid, density, model)\n```\nSee [fit.py](bfit/fit.py) for options of fitting algorithms.\n\n### 4. Run the optimization procedure.\nInitial guesses for the coefficients and exponents of the 5 s-type Gaussians must be provided.\n```python\n# Provide Initial Guesses\nc0 = np.array([1., 1., 1., 1.])\ne0 = np.array([0.001, 0.1, 1., 5., 100.])\n\n# Optimize both coefficients and exponents and print while running.\nresult = fit.run(c0, e0, opt_coeffs=True, opt_expons=True, maxiter=1000, disp=True)\n\nprint(\"Was it successful? \", result[\"success\"])\nprint(\"Optimized coefficients are: \", result[\"coeffs\"])\nprint(\"Optimized exponents are: \", result[\"exps\"])\nprint(\"Final performance measures are: \", result[\"fun\"][-1])\n```\nSee the [example directory](examples/) for more examples or launch the interactive binder\n[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/theochem/bfit/master?labpath=%2Fexamples%2F)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheochem%2Fbfit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftheochem%2Fbfit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheochem%2Fbfit/lists"}