{"id":20795237,"url":"https://github.com/theochem/denspart","last_synced_at":"2025-05-06T00:32:23.451Z","repository":{"id":24139280,"uuid":"193593398","full_name":"theochem/denspart","owner":"theochem","description":"Atoms-in-molecules density partitioning schemes based on stockholder recipe","archived":false,"fork":false,"pushed_at":"2025-05-05T20:35:01.000Z","size":745,"stargazers_count":22,"open_issues_count":6,"forks_count":11,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-05-05T21:38:45.288Z","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.rst","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,"zenodo":null}},"created_at":"2019-06-24T23:07:58.000Z","updated_at":"2025-01-08T17:01:32.000Z","dependencies_parsed_at":"2023-10-03T19:57:23.904Z","dependency_job_id":"fc25039c-bdf6-4740-9543-08f8f8860633","html_url":"https://github.com/theochem/denspart","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%2Fdenspart","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theochem%2Fdenspart/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theochem%2Fdenspart/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theochem%2Fdenspart/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/theochem","download_url":"https://codeload.github.com/theochem/denspart/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252598661,"owners_count":21774269,"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:30.562Z","updated_at":"2025-05-06T00:32:23.434Z","avatar_url":"https://github.com/theochem.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"DensPart\n########\n\n\nDensPart is an atoms-in-molecules density partitioning program. At the moment, it only\nfeatures one method to partition the density, namely the Minimal Basis Iterative\nStockholder (MBIS) scheme. See http://dx.doi.org/10.1021/acs.jctc.6b00456\n\n**Disclaimer:** This implementation is a prototype and is not extensively tested yet.\nFuture revisions may break backward compatibility of the API and file formats.\n\n\nMinimal setup\n=============\n\nRequired dependencies:\n\n- NumPy: https://numpy.org\n- QC-Grid: https://github.com/theochem/grid\n\nInstall (with dependencies):\n\n.. code-block:: bash\n\n    pip install git+https://github.com/theochem/grid.git\n    pip install git+https://github.com/theochem/denspart.git\n\n(There are no releases yet.)\n\n\nUsage\n=====\n\nOne needs to construct a ``density.npz`` file, which is used as input for the ``denspart``\nscript. (The optional dependencies below provide convenient tools to make such files.)\n\nThe file ``density.npz`` uses the NumPy ZIP (NPZ) format, which is a simple container file\nformat for arrays. More details on NPZ can be found here in `the NumPy documentation\n\u003chttps://numpy.org/doc/stable/reference/routines.io.html\u003e`_. The file ``density.npz``\nshould contain at least the following arrays:\n\n- ``points``: Quadrature grid points, shape ``(npoint, 3)``.\n- ``weights``: Quadrature grid weights, shape ``(npoint, )``.\n- ``density``: Electron density at the grid points, shape ``(npoint, )``.\n- ``atnums``: Atomic numbers, shape ``(natom, )``.\n- ``atcoords``: Nuclear coordinates, shape ``(natom, 3)``.\n- ``cellvecs``: (Optional) One, two or three cell vectors (rows) defining periodic boundary\n  conditions, shape ``(nvec, 3)``.\n\nAll data are assumed to be in atomic units.\n\nWith a ``density.npz`` file, one can perform the partitioning as follows:\n\n.. code-block:: bash\n\n    denspart density.npz results.npz\n\nThe output is stored in ``results.npz``, and contains the following arrays. (These may\nbe subject to change in future code revisions.)\n\n- Copied from the input file ``density.npz``:\n\n  - ``atnums``: Atomic numbers, shape ``(natom, )``.\n  - ``atcoords``: Nuclear coordinates, shape ``(natom, 3)``.\n\n- General outputs:\n\n  - ``atnfn``: The number of pro-density basis functions on each atom, shape ``(natom, )``.\n  - ``atnpar``: The number of pro-density parameters for each atom, shape ``(natom, )``.\n  - ``charges``: atomic partial charges, shape ``(natom,)``.\n  - ``multipole_moments``: Multipole moments (using spherical harmonics), for ``l`` going\n    from 1 to 4, shape ``(natom, (lmax + 1)**2 - 1)``. The moments are in HORTON 2 order.\n\n    .. code-block::\n\n        c10 c11 s11\n        c20 c21 s21 c22 s22\n        c30 c31 s31 c32 s32 c33 s33\n        c40 c41 s41 c42 s42 c43 s43 c44 s44\n\n    In this list, the prefix ``c`` denotes cosine-like real spherical harmonics and\n    ``s`` denotes the sine-like functions. The first digit refers to the degree ``l`` and\n    the second to the order ``m``.\n  - ``propars``: The pro-density parameters, shape ``(sum(atnpar), )``.\n  - ``radial_moments``: Expectation values of ``r**n``, for ``n`` going from 0 to 4,\n    shape ``(natom, 5)``.\n\n- MBIS-specific outputs:\n\n  - ``core_charges``: MBIS core charges, shape ``(natom,)``.\n  - ``valence_charges``: MBIS valence charges, shape ``(natom,)``.\n  - ``valence_widths``: MBIS valence widths, shape ``(natom,)``.\n\n- Algorithm settings:\n\n  - ``gtol``: A stopping condition that was used for the optimization of the pro-density\n    parameters. This is a threshold on the gradient of the extended KL divergence.\n  - ``maxiter``: A stopping condition that was used for the optimization of the pro-density\n    parameters. This is the maximum number of iterations allowed in SciPy's trust-constr\n    minimizer.\n  - ``density_cutoff``: A density cutoff parameter that was used to determine the cutoff radii\n    for the local integration grids.\n\nThe arrays in the ``results.npz`` file can be accessed in Python as follows:\n\n.. code-block:: python\n\n    import numpy as np\n    results = np.load(\"results.npz\")\n    print(\"charges\", results[\"charges\"])\n\n    # From here, one can convert data to other formats:\n    # - CSV\n    np.savetxt(\"charges.csv\", results[\"charges\"], delimiter=\",\")\n    # - JSON\n    import json\n    json.dump(results[\"charges\"].tolist(), open(\"charges.json\", \"w\"))\n\n    # One can also easily post-process the results with some scripting:\n    # - Molecular dipole moment predicted by the atomic charges.\n    print(np.dot(results[\"atcoords\"].T, results[\"charges\"]))\n    # - Contribution to the molecular dipole moment due to the atomic dipoles.\n    #   (This includes a reordering the spherical harmonics.)\n    print(results[\"multipole_moments\"][:, [1, 2, 0]].sum(axis=0))\n\n\n\n\nOptional dependencies and interfaces to quantum chemistry codes\n===============================================================\n\n\nIOData\n------\n\nSee https://github.com/theochem/iodata\n\nInstall as follows:\n\n.. code-block:: bash\n\n    pip install git+https://github.com/theochem/iodata.git\n\nWhen IOData is installed, the npz output of the partitioning can be converted into an\nextended XYZ file as follows:\n\n.. code-block:: bash\n\n    denspart-write-extxyz results.npz results.xyz\n\n\nIOData and GBasis\n-----------------\n\nIn order to derive a ``density.npz`` from several wavefunction file formats\n(wfn, wfx, molden, fchk, ...), one needs install a two dependencies:\n\n- https://github.com/theochem/iodata\n- https://github.com/theochem/gbasis\n\nInstall as follows:\n\n.. code-block:: bash\n\n    pip install git+https://github.com/theochem/iodata.git\n    pip install git+https://github.com/theochem/gbasis.git\n\nOnce these are installed, one can compute densities on a grid from a wavefunction file.\nFor example:\n\n.. code-block:: bash\n\n    denspart-from-horton3 some-file.fchk density.npz\n\nA minimal working example showing how to partition a density from a Gaussian FCHK\ncan be found in `examples/horton3 \u003cexamples/horton3\u003e`_.\n\n\nGPAW\n----\n\nOne may also derive a ``density.npz`` file from a\n`GPAW \u003chttps://wiki.fysik.dtu.dk/gpaw/\u003e`_ calculation.\nWhen GPAW is installed, one can run:\n\n.. code-block:: bash\n\n    denspart-from-gpaw some-file.gpw density.npz\n\nA minimal working example can be found in `examples/gpaw \u003cexamples/gpaw\u003e`_.\nNote that you may have to add `mpirun` in front of the command.\nHowever, the conversion does not yet support parallel execution and thus only works for the case of a single process, even when using `mpirun`.\n\n\nADF (AMS 2021.202)\n------------------\n\nOne may also derive a ``density.npz`` from an ADF AMSJob.\nWhen `AMS \u003chttps://www.scm.com/amsterdam-modeling-suite/\u003e`_ is installed, you can install\ndenspart in the AMS Python environment as follows:\n\n\n.. code-block:: bash\n\n    # If needed:\n    source ${ADFHOME}/amsbashrc.sh\n    # Avoid setting ADF and AMS environment variables manually, because these may change\n    # with different versions of AMS.\n\n    amspython -m pip install git+https://github.com/theochem/grid.git\n    amspython -m pip install git+https://github.com/theochem/denspart.git\n    # For writing the extended XYZ file:\n    amspython -m pip install git+https://github.com/theochem/iodata.git\n\n\nThen, the conversion and partitioning are done as follows:\n\n.. code-block:: bash\n\n    amspython -m denspart.adapters.adf ams.results density.npz\n    amspython -m denspart density.npz results.npz\n    amspython -m denspart.utils.write_extxyz results.npz results.xyz\n\nwhere ``ams.results`` is the directory with output files. You need to disable symmetry\nand write out the TAPE10 file. More details can be found the the ``denspart.adapters.adf``\nmodule. A minimal working example can be found in `examples/adf \u003cexamples/adf\u003e`_.\n\n\nPsi4\n----\n\nBy adding a few lines to the `Psi4 \u003chttps://psicode.org/\u003e`_ input script, it will write\nan NPZ file with Psi4's built-in molecular quadrature grids:\n\n.. code-block:: python\n\n    energy, wfn = psi4.energy(return_wfn=True)\n    from denspart.adapters.psi4 import write_density_npz\n    write_density_npz(wfn)\n\nSymmetry is not supported, so you need to set the point group to ``c1`` when specifying\nthe geometry. A minimal working example can be found in `examples/psi4 \u003cexamples/psi4\u003e`_.\n\n\nDevelopment setup\n=================\n\nThe development environment is configured as follows.\nIt is assumed that you have `direnv \u003chttps://direnv.net/\u003e`_ installed.\n(If not, you can manually the virtual environment.)\n\n.. code-block:: bash\n\n    # Clone git repo, assuming you have ssh access to github\n    git clone git@github.com:theochem/denspart.git\n    cd denspart\n    # Create a virtual environment with all dependencies needed for testing\n    python -m venv venv\n    cat \u003e .envrc \u003c\u003c 'EOL'\n    source venv/bin/activate\n    export GPAW_SETUP_PATH=${PWD}/venv/share/gpaw-setups-0.9.20000\n    EOL\n    direnv allow\n    pip install -U pip\n    pip install -e .\n    # Mandatory dependency, but not yet included in setup.py\n    pip install --upgrade git+https://github.com/theochem/grid.git\n    # Development tools\n    pip install --upgrade pre-commit ruff black\n    # Extra dependency for testing adapters\n    pip install --upgrade git+https://github.com/theochem/iodata.git\n    pip install --upgrade git+https://github.com/theochem/gbasis.git\n    pip install --upgrade git+https://github.com/tovrstra/pytest-regressions@npz\n    pip install --upgrade ase\n    # (Make sure BLAS and LibXC are installed, so GPAW can link to them.)\n    # Fedora: sudo dnf install libxc-devel blas-devel\n    pip install --upgrade gpaw\n    # Install GPAW pseudopotentials\n    gpaw install-data venv/share\n\nTo run all tests locally:\n\n.. code-block:: bash\n\n    pre-commit run --all\n    pytest\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheochem%2Fdenspart","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftheochem%2Fdenspart","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheochem%2Fdenspart/lists"}