{"id":13833139,"url":"https://github.com/theochem/tinydft","last_synced_at":"2025-04-05T08:05:05.765Z","repository":{"id":141457665,"uuid":"187008810","full_name":"theochem/tinydft","owner":"theochem","description":"A minimalistic atomic Density Functional Theory (DFT) code","archived":false,"fork":false,"pushed_at":"2025-03-24T20:25:56.000Z","size":119,"stargazers_count":131,"open_issues_count":2,"forks_count":27,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-03-29T07:06:04.754Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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.txt","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}},"created_at":"2019-05-16T10:49:35.000Z","updated_at":"2025-03-24T23:29:35.000Z","dependencies_parsed_at":"2024-01-07T19:41:56.226Z","dependency_job_id":"293a7fbf-9bdf-4c02-804d-a0dc87550889","html_url":"https://github.com/theochem/tinydft","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theochem%2Ftinydft","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theochem%2Ftinydft/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theochem%2Ftinydft/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theochem%2Ftinydft/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/theochem","download_url":"https://codeload.github.com/theochem/tinydft/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247305933,"owners_count":20917208,"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-08-04T11:00:40.655Z","updated_at":"2025-04-05T08:05:05.737Z","avatar_url":"https://github.com/theochem.png","language":"Python","funding_links":[],"categories":["demo/toy proj"],"sub_categories":[],"readme":"# Tiny DFT\n\nTiny DFT is a minimalistic atomic Density Functional Theory (DFT) code, mainly for educational purposes.\nIt only supports spherically symmetric atoms and local exchange-correlation functionals (at the moment only Dirac exchange).\n\nThe code is designed with the following criteria in mind:\n\n- It depends only on established scientific Python libraries:\n  [numpy](https://www.numpy.org/),\n  [scipy](https://www.scipy.org/),\n  [matplotlib](https://matplotlib.org/) and\n  (the lesser known) [autograd](https://github.com/HIPS/autograd/).\n  The latter is a library for algorithmic differentiation,\n  used to computed the analytic exchange(-correlation) potential and the grid transformation.\n\n- The numerical integration and differentiation algorithms should be precise\n  enough to at least 6 significant digits for the total energy, but in many\n  cases the numerical precision is better.\n  Some integrals over Gaussian basis functions are computed analytically.\n  The pseudo-spectral method with Legendre polynomials is used for the Poisson solver.\n\n- The total number of lines should be minimal and the source-code should be easy\n  to understand, provided some background in DFT and spectral methods.\n  As in most atomic DFT codes, the occupation numbers of the orbitals are all given\n  the same value within one pair of angular and principal quantum number, to\n  obtain a spherically symmetric density.\n  The code only keeps track of the total number of electrons for each pair of quantum numbers.\n\n\n## Installation\n\n1. Download the Tiny DFT repository. This can be done with your browser, after which you unpack\n   the archive: https://github.com/theochem/tinydft/archive/main.zip.\n   Or you can use git:\n\n   ```bash\n   git clone https://github.com/theochem/tinydft.git\n   cd tinydft\n   ```\n\n1. Install the `tinydft` package from source in development mode (for easy hacking):\n\n   ```bash\n   pip install -e .\n   ```\n\n\n## Usage\n\nTo run a series of atomic DFT calculation, up to argon, run the mendelejev demo\n\n```bash\ntinydft-demo-mendelejev\n```\n\nThis generates some screen output with SCF convergence, energy contributions and\nthe figures `rho_z0*.png` with the radial electron densities on a semi-log plot.\nTo modify the settings for these calculation, you can directly edit the source code.\n\nWhen you make serious modifications to Tiny DFT, you can run the unit tests to\nmake sure the original features still work.\n\nFor this, you first need to install [pytest](https://pytest.org/) in a development setup.\nFor example:\n\n```bash\ngit clone git@github.com:theochem/tinydft.git\ncd tinydft\npython3 -m venv venv\nsource venv/bin/activate\npython3 -m pip install -e .[dev]\npre-commit install\npytest\n```\n\nSee [the QC-Devs Contributor Guide](https://github.com/theochem/.github/blob/main/CONTRIBUTING.md) for more details.\n\n\n## Programming assignments\n\nIn order of increasing difficulty:\n\n1. Change `tinydft/demo_mendelejev.py` to also make plots of the radial probability density,\n   the occupied orbitals, the potentials (external, Kohn-Sham) with horizontal lines for the\n   (higher but still negative) energy levels.\n   Does this code reproduce the Rydberg spectral series well? (See\n   https://en.wikipedia.org/wiki/Hydrogen_spectral_series#Rydberg_formula)\n\n1. Add a second unit test for the Poisson solver in `tests/test_tinydft.py`.\n   The current unit test checks if the Poisson solver can correctly compute the\n   electrostatic potential of a spherical exponential density distribution (Slater-type).\n   Add a similar test for a Gaussian density distribution.\n   Use the [`erf`](https://docs.scipy.org/doc/scipy/reference/generated/scipy.special.erf.html#scipy.special.erf)\n   function from `scipy.special` to compute the analytic result.\n\n1. At the moment, the DFT calculations assume spin-unpolarized densities, which\n   mainly affects the exchange-correlation energy.\n   Change the code to work with spin-polarized densities.\n   For this, also the occupation numbers for each angular momentum and principal quantum number\n   should be split into a spin-up and spin-down occupation number.\n\n1. Change the external potential to take into account the finite extent of the nucleus.\n   You can use a Gaussian density distribution.\n   Write a python script that combines\n   isotope abundancies from [NUBASE2016](http://amdc.in2p3.fr/nubase/nubase2016.txt) and\n   nucleotide radii from [ADNDT](https://www-nds.iaea.org/radii/) to build a table of\n   abundance-averaged nuclear radii.\n\n1. Add a correlation energy density to the function `excfunction` and check if\n   it improve the results in assignment (2).\n   The following correlation functional has a good compromise between simplicity and accuracy:\n\n   - https://aip.scitation.org/doi/10.1063/1.4958669 and\n   - https://aip.scitation.org/doi/full/10.1063/1.4964758\n\n1. The provided implementation has a rigid algorithm to assign occupation numbers using the Klechkowski rule.\n   Replace this by an algorithm that just looks for all the relevant lowest-energy orbitals at every SCF iteration.\n\n1. Implement an SCF convergence test, which checks if the new Fock operator,\n   in the basis of occupied orbitals from a previous iteration,\n   is diagonal with orbital energies from the previous iteration on the diagonal\n\n1. Implement the zeroth-order regular approximation to the Dirac equation (ZORA).\n   ZORA needs a pro-atomic Kohn-Sham potential as input, which remains fixed during the SCF cycle.\n   Add an outer loop where the first iteration is without ZORA and\n   subsequent iterations use the Kohn-Sham potential from the previous SCF loop as pro-density for ZORA.\n   (To avoid that the density diverges at the nucleus, assignment 4 should be implemented first.)\n\n   In ZORA, the following operator should be added to the Hamiltonian:\n\n   ![t_{ab} = \\int (\\nabla \\chi_a) (\\nabla \\chi_b) \\frac{v_{KS}(\\mathbf{r})}{4/\\alpha^2 - 2v_{KS}(\\mathbf{r})} \\mathrm{d}\\mathbf{r}](zora.png)\n\n   where the first factors are the gradients of the basis functions (similar to the kinetic energy operator).\n   The Kohn-Sham potential from the previous outer iteration can be used.\n   The parameter alpha is the dimensionless inverse fine-structure constant, see\n   https://physics.nist.gov/cgi-bin/cuu/Value?alphinv and\n   https://docs.scipy.org/doc/scipy/reference/constants.html\n   (`inverse fine-structure constant`).\n   Before ZORA can be implemented, the formula needs to be worked out in spherical coordinates,\n   separating it in a radial and an angular contribution.\n\n1. Extend the program to perform unrestricted Spin-polarized KS-DFT calculations.\n   (Assignment 6 should done prior to this one.)\n   In addition to the Aufbau rule, you now also have to implement the Hund rule.\n   You also need to keep track of spin-up and spin-down orbitals.\n   The original code uses the angular momentum quantum number, `angqn` as keys in the `eps_orbs_u`\n   dictionary.\n   Instead, you can now use `(angqn, spinqn)` keys.\n\n1. Extend the program to support (fractional) Hartree-Fock exchange.\n\n1. Extend the program to support (meta) generalized gradient functionals.\n\n\n## Dictionary of variable names\n\nThe variable names are not always the shortest possible, e.g. `atnum` instead\nof `z`, to make them more self-explaining and to comply with good practices.\n\n- `alphas`: Gaussian exponents in basis functions\n- `atcharge`: Atomic charge\n- `atnum`: Atomic number\n- `angqn`: Angular momentum (or azimuthal) quantum number\n- `coeffs`: Expansion coefficients of a function in Gaussian primitives or\n  Legendre polynomials.\n- `econf`: Electronic configuration\n- `energy_hartree`: Hartree energy, i.e. classical electron-electron repulsion.\n- `eps`: Orbital energies\n- `eps_orbs_u`: A list of tuples of (orbital energy, orbital coefficients).\n  One tuple for each angular momentum quantum number. The orbital coefficients\n  represent the radial solutions U = R/r.\n- `energy_xc`: Exchange-correlation energy\n- `exc`: Exchange-correlation energy density\n- `evals`: Eigenvalues\n- `evecs`: Eigenvectors\n- `ext`: Integrals for interaction with the external field (proton)\n- `fnvals`: Function values on grid points\n- `fock`: Fock operator\n- `iscf`: Current SCF iteration\n- `jxc`: Hartree-Exchange-Correlation operator\n- `kin_rad`: Radial kinetic energy integrals\n- `kin_ang`: Angular kinetic energy integrals\n- `maxangqn`: Maximum angular quantum number of the occupied orbitals\n- `nbasis`: Number of basis functions\n- `nelec`: Number of electrons\n- `nscf`: Number of SCF iterations\n- `occups`: Occupation numbers\n- `olp`: Overlap integrals\n- `orb_u`: Orbital divided by r: U = R/r\n- `orb_r`: Orbital: R = U*r\n- `priqn`: Primary quantum numbers\n- `rho`: Electron density on grid points\n- `vhartree`: Hartree potential, i.e. minus classical electrostatic potential\n  due to the electrons.\n- `vol`: Volume element in spherical coordinates\n- `vxc`: Exchange-correlation potential\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheochem%2Ftinydft","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftheochem%2Ftinydft","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheochem%2Ftinydft/lists"}