Metadata-Version: 2.4
Name: deepqmc
Version: 1.3.0
Summary: Deep-learning quantum Monte Carlo for electrons in real space
Author: Jan Hermann
Author-email: Zeno Schätzle <zeno.schaetzle@fu-berlin.de>, Péter Bernát Szabó <peter.bernat.szabo@fu-berlin.de>, Matěj Mezera <m.mezera@fu-berlin.de>
Maintainer-email: Zeno Schätzle <zeno.schaetzle@fu-berlin.de>, Matěj Mezera <m.mezera@fu-berlin.de>
License: MIT
Project-URL: homepage, https://deepqmc.github.io
Project-URL: repository, https://github.com/deepqmc/deepqmc
Project-URL: documentation, https://deepqmc.github.io
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: GPU :: NVIDIA CUDA
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: dm-haiku
Requires-Dist: folx
Requires-Dist: h5py
Requires-Dist: hydra-core
Requires-Dist: jax<0.9.0
Requires-Dist: jaxlib
Requires-Dist: jax-dataclasses
Requires-Dist: kfac-jax
Requires-Dist: scipy
Requires-Dist: optax
Requires-Dist: pyscf
Requires-Dist: tensorboardX
Requires-Dist: pyyaml
Requires-Dist: tqdm
Requires-Dist: uncertainties
Requires-Dist: chex<1.0.0
Requires-Dist: jaxtyping
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-regressions; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: codespell; extra == "dev"
Requires-Dist: pep8-naming; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: pydocstyle; extra == "dev"
Requires-Dist: pyright; extra == "dev"
Provides-Extra: doc
Requires-Dist: sphinx; extra == "doc"
Requires-Dist: Jinja2; extra == "doc"
Requires-Dist: sphinxcontrib-katex; extra == "doc"
Requires-Dist: toml; extra == "doc"
Requires-Dist: docutils; extra == "doc"
Requires-Dist: pydata-sphinx-theme; extra == "doc"
Requires-Dist: nbsphinx; extra == "doc"
Provides-Extra: notebooks
Requires-Dist: jupyter; extra == "notebooks"
Requires-Dist: ipykernel; extra == "notebooks"
Dynamic: license-file

# DeepQMC

![checks](https://img.shields.io/github/actions/workflow/status/deepqmc/deepqmc/tests.yaml?label=tests)
[![coverage](https://img.shields.io/codecov/c/github/deepqmc/deepqmc.svg)](https://codecov.io/gh/deepqmc/deepqmc)
![python](https://img.shields.io/pypi/pyversions/deepqmc.svg)
[![pypi](https://img.shields.io/pypi/v/deepqmc.svg)](https://pypi.org/project/deepqmc/)
[![commits since](https://img.shields.io/github/commits-since/deepqmc/deepqmc/latest.svg)](https://github.com/deepqmc/deepqmc/releases)
[![last commit](https://img.shields.io/github/last-commit/deepqmc/deepqmc.svg)](https://github.com/deepqmc/deepqmc/commits/master)
[![license](https://img.shields.io/github/license/deepqmc/deepqmc.svg)](https://github.com/deepqmc/deepqmc/blob/master/LICENSE)
[![code style](https://img.shields.io/badge/code%20style-black-202020.svg)](https://github.com/ambv/black)
[![Checked with pyright](https://microsoft.github.io/pyright/img/pyright_badge.svg)](https://microsoft.github.io/pyright/)
[![doi](https://img.shields.io/badge/doi-10.5281%2Fzenodo.3960826-blue)](http://doi.org/10.5281/zenodo.3960826)

DeepQMC is an open-source software suite for variational optimization of deep-learning molecular wave functions. It implements the simulation of electronic ground and excited states using deep neural network trial wave functions. The package is based on [JAX](https://github.com/google/jax) and [Haiku](https://github.com/deepmind/dm-haiku) and is configured through a cli build of [Hydra](https://hydra.cc/).

The program solves the molecular Hamiltonian, allowing the use of effective core potentials. Excited states are obtained via a penalty-based excited-state optimization approach. A spin penalty allows states in a fixed spin sector to be targeted. Furthermore, DeepQMC implements geometric transferability, that is a single ansatz can be optimized across multiple configurations of a set of atoms. This can either be done by training on a fixed set of molecular configurations or by dynamically sampling molecular configurations throughout the optimization, and can be combined with the optimization of electronic excited states.

The software suite includes a general neural network wave function ansatz, that can be configured to obtain a wide range of molecular neural network wave functions. Config files for the instantiation of variants of [Psiformer](https://arxiv.org/abs/2211.13672), [PauliNet](https://doi.org/10.1038/s41557-020-0544-y), [FermiNet](https://link.aps.org/doi/10.1103/PhysRevResearch.2.033429), [DeepErwin](https://arxiv.org/abs/2205.09438), [LapNet](https://doi.org/10.1038/s42256-024-00794-x) and a transferable extension of the self-attention ansatz [TransPsiformer](https://arxiv.org/abs/2503.19847) can be found under `src/deepqmc/conf/ansatz`.


### Installation

Install and update to the latest release using [Pip](https://pip.pypa.io/en/stable/quickstart/):

```
pip install -U deepqmc
```

To install DeepQMC from a local Git repository run:

```
git clone https://github.com/deepqmc/deepqmc
cd deepqmc
pip install -e .[dev]
```

If Pip complains about `setup.py` not being found, please update to the latest Pip version.

The above installation will result in the CPU version of JAX. However, running DeepQMC on the GPU is highly recommended. To enable GPU support make sure to upgrade JAX to match the CUDA and cuDNN versions of your system. For most users this can be achieved with:

```
# CUDA 12 installation
pip install "jax[cuda12]" -f https://storage.googleapis.com/jax-releases/jax_cuda_releases.html
```

For further help setting up JAX, visit the [JAX Install Guide](https://github.com/google/jax#installation).

To validate the correct installation of DeepQMC and its dependencies run:

```
deepqmc
```

### Documentation and exemplary usage

For further information about the DeepQMC package and tutorials covering the basic usage visit the [documentation](https://deepqmc.github.io).

An introduction to the methodology, implementation details and exemplary experiments can be found in the associated [software paper](https://doi.org/10.1063/5.0157512).

The penalty-based excited states approach and its implementation in DeepQMC is discussed in our recent paper on [excited state optimization](https://doi.org/10.1021/acs.jctc.4c00678).

The geometrically transferable simulation with DeepQMC on fixed datasets is demonstrated in our paper on [tranferable simulation of excited state potential energy surfaces](https://arxiv.org/abs/2503.19847).

An optimization of wave functions across continuous potential energy surfaces and subsequent optimization of molecular geometries is employed in our latest paper on [ab initio geometry optimization](https://arxiv.org/abs/2603.25381).

### Citation

If you use DeepQMC for your work, please cite our implementation paper:

```
@article{10.1063/5.0157512,
    author = {Schätzle, Z. and Szabó, P. B. and Mezera, M. and Hermann, J. and Noé, F.},
    title = "{DeepQMC: An open-source software suite for variational optimization of deep-learning molecular wave functions}",
    journal = {The Journal of Chemical Physics},
    volume = {159},
    number = {9},
    pages = {094108},
    year = {2023},
    month = {09},
    issn = {0021-9606},
    doi = {10.1063/5.0157512},
    url = {https://doi.org/10.1063/5.0157512},
}

```

Experiments including excited state optimization may cite our excited state paper:

```
@article{10.1021/acs.jctc.4c00678,
    author = {Szabó, P. B. and Schätzle, Z. and Entwistle, M. and Noé, F.},
    title = "{An Improved Penalty-Based Excited-State Variational Monte Carlo Approach with Deep-Learning Ansatzes}",
    journal = {Journal of Chemical Theory and Computation},
    year = {2024},
    month = {08},
    issn = {1549-9618},
    doi = {10.1021/acs.jctc.4c00678},
    url = {https://doi.org/10.1021/acs.jctc.4c00678},
}

```

When employing transferable optimization consider citing:

```
@online{schatzle2025a,
  author = {Schätzle, Z. and Szabó, P. B. and Cuzzocrea, A. and Noé, F.},
  title = {Ab-Initio Simulation of Excited-State Potential Energy Surfaces with Transferable Deep Quantum {{Monte Carlo}}},
  year = {2025},
  month = {03},
  doi = {10.48550/arXiv.2503.19847},
  pubstate = {prepublished},
}

```

The repository can be cited as:

```
@software{deepqmc,
	author = {Hermann, J. and Schätzle, Z. and Szabó, P. B. and Mezera, M and {DeepQMC Contributors}},
	title = "{DeepQMC}",
	year = {2026},
	publisher = {Zenodo},
	copyright = {MIT},
	url = {https://github.com/deepqmc/deepqmc},
	doi = {10.5281/zenodo.3960826},
}
```
