# Hamiltonian-Guided Autoregressive Selected-Configuration Interaction(HAAR-SCI) Achieves Chemical Accuracy in Strongly Correlated Systems
The current project temporarily named as Quantum-Many-Body (`qmb`) which is a powerful tool designed to solve quantum-many-body problems especially for strongly correlated systems.
## About The Project
This repository hosts a [Python][python-url] package named `qmb`, dedicated to solving quantum-many-body problem.
It implements a suite of algorithms and interfaces with various model descriptors, such as the [OpenFermion][openfermion-url] format and FCIDUMP.
Additionally, `qmb` can efficiently utilize accelerators such as GPU(s) to enhance its performance.
The package's main entry point is a command line interface (CLI) application, also named `qmb`.
## Getting Started
Users can run this application either using [Docker][docker-url] or locally.
Both approaches require GPU(s) with [CUDA][cuda-url] support and a properly installed GPU driver, which is typically included with the installation of the CUDA Toolkit.
### Run with Docker
After installing [Docker][docker-url] with [CUDA support][docker-cuda-url], pull [our prebuilt Docker image][our-docker-url] using:
```
docker pull hzhangxyz/qmb
```
If users experience network issues, consider [configuring Docker mirrors][docker-mirror-url].
Then, user can run `qmb` with
```
docker run --device=nvidia.com/gpu=all --rm -it hzhangxyz/qmb --help
```
This command utilizes Docker's [CDI][docker-cuda-cdi-url] feature to enable CUDA devices in `--device=nvidia.com/gpu=all`.
Alternatively, for [legacy][docker-cuda-legacy-url] support, users can run:
```
docker run --gpus all --rm -it hzhangxyz/qmb --help
```
Please note that we currently provide Docker images for Linux/AMD64 only.
When running with Docker, users might want to [mount][docker-mount-url] a local folder to share storage between the container and the local machine such as using the `-v` option.
### Run locally
To install locally, users first needs to install the [CUDA toolkit][cuda-url].
The `qmb` requires Python >= 3.12.
After setting up a compatible Python environment such as using [Anaconda][anaconda-url], [Miniconda][miniconda-url], [venv][venv-url] or [pyenv][pyenv-url], users can install [our prebuilt package][our-pypi-url] using:
```
pip install qmb
```
If users face network issues, consider setting up a mirror with the `-i` option.
Users can then invoke the `qmb` script with:
```
qmb --help
```
Please note that if the CUDA toolkit version is too old, users must install a compatible PyTorch version before running `pip install qmb`.
For example, use `pip install torch --index-url https://download.pytorch.org/whl/cu118` for CUDA 11.8 (see [PyTorch’s guide][pytorch-install-url] for details).
This older CUDA-compatible PyTorch must be installed first, otherwise, users will need to uninstall all existing PyTorch/CUDA-related python packages before reinstalling the correct version.
## Usage
The main entry point of this package is a CLI script named `qmb`.
Use the following command to view its usage:
```
qmb --help
```
This command provides a collection of subcommands, such as `imag`.
To access detailed help for a specific subcommand, users can append `--help` to the command.
For example, use `qmb haar --help` to view the help information for the `imag` subcommand.
Typically, `qmb` requires a specific descriptor for a particular physical or chemical model to execute.
We have collected a set of such models [here][models-url].
Users can clone or download this dataset into a folder named `models` within their current working directory.
This folder `models` is the default location which `qmb` will search for the necessary model files.
Alternatively, users can specify a custom path by setting the `$QMB_MODEL_PATH` environment variable, thereby overriding the default behavior.
After cloning or downloading the dataset, users can calculate the ground state of the $N_2$ system by running the command:
```
qmb haar openfermion mlp -PN2
```
This command utilizes the `imag` subcommand with the descriptor in OpenFermion format and the [mlp network][naqs-url],
It specifies the $N_2$ model via the `-PN2` flag since the $N_2$ model is loaded from the file `N2.hdf5` in the folder `models`.
For more detailed information, please refer to the help command and the documentation.
## Contributing
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
## License
This project is distributed under the GPLv3 License. See [LICENSE.md](LICENSE.md) for more information.
[python-url]: https://www.python.org/
[openfermion-url]: https://quantumai.google/openfermion
[docker-url]: https://www.docker.com/
[cuda-url]: https://docs.nvidia.com/cuda/
[docker-cuda-url]: https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/index.html
[our-docker-url]: https://hub.docker.com/r/hzhangxyz/qmb
[docker-mirror-url]: https://docs.docker.com/docker-hub/image-library/mirror/
[docker-cuda-cdi-url]: https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/cdi-support.html
[docker-cuda-legacy-url]: https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html
[anaconda-url]: https://www.anaconda.com/
[miniconda-url]: https://docs.anaconda.com/miniconda/
[venv-url]: https://docs.python.org/3/library/venv.html
[pyenv-url]: https://github.com/pyenv/pyenv
[our-pypi-url]: https://pypi.org/project/qmb/
[docker-mount-url]: https://docs.docker.com/engine/storage/volumes/
[pytorch-install-url]: https://pytorch.org/get-started/locally/
[models-url]: https://huggingface.co/datasets/USTC-KnowledgeComputingLab/qmb-models
[naqs-url]: https://github.com/tomdbar/naqs-for-quantum-chemistry
Raw data
{
"_id": null,
"home_page": null,
"name": "qmb",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "quantum, manybody, quantum-chemistry, quantum-simulation, molecular-simulation, algorithms, simulation, wave-function, ground-state, ansatz, torch, pytorch",
"author": null,
"author_email": "Hao Zhang <hzhangxyz@outlook.com>",
"download_url": "https://files.pythonhosted.org/packages/4e/8a/e8b11e2867410c99f3547c73681bb34942d622070808210ec0ca578df583/qmb-0.0.52.tar.gz",
"platform": null,
"description": "# Hamiltonian-Guided Autoregressive Selected-Configuration Interaction(HAAR-SCI) Achieves Chemical Accuracy in Strongly Correlated Systems\n\nThe current project temporarily named as Quantum-Many-Body (`qmb`) which is a powerful tool designed to solve quantum-many-body problems especially for strongly correlated systems.\n\n## About The Project\n\nThis repository hosts a [Python][python-url] package named `qmb`, dedicated to solving quantum-many-body problem.\nIt implements a suite of algorithms and interfaces with various model descriptors, such as the [OpenFermion][openfermion-url] format and FCIDUMP.\nAdditionally, `qmb` can efficiently utilize accelerators such as GPU(s) to enhance its performance.\nThe package's main entry point is a command line interface (CLI) application, also named `qmb`.\n\n## Getting Started\n\nUsers can run this application either using [Docker][docker-url] or locally.\nBoth approaches require GPU(s) with [CUDA][cuda-url] support and a properly installed GPU driver, which is typically included with the installation of the CUDA Toolkit.\n\n### Run with Docker\n\nAfter installing [Docker][docker-url] with [CUDA support][docker-cuda-url], pull [our prebuilt Docker image][our-docker-url] using:\n```\ndocker pull hzhangxyz/qmb\n```\nIf users experience network issues, consider [configuring Docker mirrors][docker-mirror-url].\n\nThen, user can run `qmb` with\n```\ndocker run --device=nvidia.com/gpu=all --rm -it hzhangxyz/qmb --help\n```\n\nThis command utilizes Docker's [CDI][docker-cuda-cdi-url] feature to enable CUDA devices in `--device=nvidia.com/gpu=all`.\nAlternatively, for [legacy][docker-cuda-legacy-url] support, users can run:\n```\ndocker run --gpus all --rm -it hzhangxyz/qmb --help\n```\n\nPlease note that we currently provide Docker images for Linux/AMD64 only.\n\nWhen running with Docker, users might want to [mount][docker-mount-url] a local folder to share storage between the container and the local machine such as using the `-v` option.\n\n### Run locally\n\nTo install locally, users first needs to install the [CUDA toolkit][cuda-url].\n\nThe `qmb` requires Python >= 3.12.\nAfter setting up a compatible Python environment such as using [Anaconda][anaconda-url], [Miniconda][miniconda-url], [venv][venv-url] or [pyenv][pyenv-url], users can install [our prebuilt package][our-pypi-url] using:\n```\npip install qmb\n```\nIf users face network issues, consider setting up a mirror with the `-i` option.\n\nUsers can then invoke the `qmb` script with:\n```\nqmb --help\n```\n\nPlease note that if the CUDA toolkit version is too old, users must install a compatible PyTorch version before running `pip install qmb`.\nFor example, use `pip install torch --index-url https://download.pytorch.org/whl/cu118` for CUDA 11.8 (see [PyTorch\u2019s guide][pytorch-install-url] for details).\nThis older CUDA-compatible PyTorch must be installed first, otherwise, users will need to uninstall all existing PyTorch/CUDA-related python packages before reinstalling the correct version.\n\n## Usage\n\nThe main entry point of this package is a CLI script named `qmb`.\nUse the following command to view its usage:\n```\nqmb --help\n```\n\nThis command provides a collection of subcommands, such as `imag`.\nTo access detailed help for a specific subcommand, users can append `--help` to the command.\nFor example, use `qmb haar --help` to view the help information for the `imag` subcommand.\n\nTypically, `qmb` requires a specific descriptor for a particular physical or chemical model to execute.\nWe have collected a set of such models [here][models-url].\nUsers can clone or download this dataset into a folder named `models` within their current working directory.\nThis folder `models` is the default location which `qmb` will search for the necessary model files.\nAlternatively, users can specify a custom path by setting the `$QMB_MODEL_PATH` environment variable, thereby overriding the default behavior.\n\nAfter cloning or downloading the dataset, users can calculate the ground state of the $N_2$ system by running the command:\n```\nqmb haar openfermion mlp -PN2\n```\nThis command utilizes the `imag` subcommand with the descriptor in OpenFermion format and the [mlp network][naqs-url],\nIt specifies the $N_2$ model via the `-PN2` flag since the $N_2$ model is loaded from the file `N2.hdf5` in the folder `models`.\n\nFor more detailed information, please refer to the help command and the documentation.\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n## License\n\nThis project is distributed under the GPLv3 License. See [LICENSE.md](LICENSE.md) for more information.\n\n[python-url]: https://www.python.org/\n[openfermion-url]: https://quantumai.google/openfermion\n[docker-url]: https://www.docker.com/\n[cuda-url]: https://docs.nvidia.com/cuda/\n[docker-cuda-url]: https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/index.html\n[our-docker-url]: https://hub.docker.com/r/hzhangxyz/qmb\n[docker-mirror-url]: https://docs.docker.com/docker-hub/image-library/mirror/\n[docker-cuda-cdi-url]: https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/cdi-support.html\n[docker-cuda-legacy-url]: https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html\n[anaconda-url]: https://www.anaconda.com/\n[miniconda-url]: https://docs.anaconda.com/miniconda/\n[venv-url]: https://docs.python.org/3/library/venv.html\n[pyenv-url]: https://github.com/pyenv/pyenv\n[our-pypi-url]: https://pypi.org/project/qmb/\n[docker-mount-url]: https://docs.docker.com/engine/storage/volumes/\n[pytorch-install-url]: https://pytorch.org/get-started/locally/\n[models-url]: https://huggingface.co/datasets/USTC-KnowledgeComputingLab/qmb-models\n[naqs-url]: https://github.com/tomdbar/naqs-for-quantum-chemistry\n",
"bugtrack_url": null,
"license": null,
"summary": "Quantum Manybody Problem",
"version": "0.0.52",
"project_urls": {
"Documentation": "https://github.com/USTC-KnowledgeComputingLab/qmb",
"Homepage": "https://github.com/USTC-KnowledgeComputingLab/qmb",
"Issues": "https://github.com/USTC-KnowledgeComputingLab/qmb/issues",
"Repository": "https://github.com/USTC-KnowledgeComputingLab/qmb.git"
},
"split_keywords": [
"quantum",
" manybody",
" quantum-chemistry",
" quantum-simulation",
" molecular-simulation",
" algorithms",
" simulation",
" wave-function",
" ground-state",
" ansatz",
" torch",
" pytorch"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c0a9e885a5e383f4cfd78405484b0de0a54dddf8b5f9f78682463744b60391b5",
"md5": "cf450107748aa3a474cc12fc56cebef6",
"sha256": "7eca1becce41562d8f835a565410f6eaa18d5f4b07e418917886a53e93c733b0"
},
"downloads": -1,
"filename": "qmb-0.0.52-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cf450107748aa3a474cc12fc56cebef6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 80718,
"upload_time": "2025-09-05T06:39:50",
"upload_time_iso_8601": "2025-09-05T06:39:50.746682Z",
"url": "https://files.pythonhosted.org/packages/c0/a9/e885a5e383f4cfd78405484b0de0a54dddf8b5f9f78682463744b60391b5/qmb-0.0.52-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4e8ae8b11e2867410c99f3547c73681bb34942d622070808210ec0ca578df583",
"md5": "3cc0b891def8e1c90f59cd1738a955b6",
"sha256": "ed1ac4e359740521228d006cd768907cee8136c4db9e350319011cfa573666e6"
},
"downloads": -1,
"filename": "qmb-0.0.52.tar.gz",
"has_sig": false,
"md5_digest": "3cc0b891def8e1c90f59cd1738a955b6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 77528,
"upload_time": "2025-09-05T06:39:52",
"upload_time_iso_8601": "2025-09-05T06:39:52.032925Z",
"url": "https://files.pythonhosted.org/packages/4e/8a/e8b11e2867410c99f3547c73681bb34942d622070808210ec0ca578df583/qmb-0.0.52.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-05 06:39:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "USTC-KnowledgeComputingLab",
"github_project": "qmb",
"github_not_found": true,
"lcname": "qmb"
}
JSON
