USTC-KnowledgeComputingLab · hzhangxyz · Mar 5, 2026 · Mar 5, 2026
diff --git a/README.md b/README.md
@@ -1,34 +1,132 @@
 # Quantum Many-Body Problem Kit (qmp-kit)
 
-The quantum many-body problem kit (`qmp-kit`) is a powerful tool designed to solve quantum-many-body problems especially for strongly correlated systems. This project includes our work on [Hamiltonian-Guided Autoregressive Selected-Configuration Interaction Achieves Chemical Accuracy in Strongly Correlated Systems](https://pubs.acs.org/doi/10.1021/acs.jctc.5c01415).
+The quantum many-body problem kit (`qmp-kit`) is a powerful tool designed to solve quantum-many-body problems especially for strongly correlated systems. This project includes our work on [Hamiltonian-Guided Autoregressive Selected-Configuration Interaction Achieves Chemical Accuracy in Strongly Correlated Systems][haar-url].
 
 ## About The Project
 
 This repository hosts a [Python][python-url] package named `qmp-kit`, dedicated to solving the 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, `qmp` 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 `qmp`.
 
 ## Getting Started
 
-To run this application locally, you need GPU(s) with [CUDA][cuda-url] support and a properly installed GPU driver (typically included with the CUDA Toolkit installation).
+### Installation
 
-### Local Installation
+The `qmp-kit` requires Python >= 3.12 and CUDA-compatible environment for GPU acceleration.
 
-To install locally, users first needs to install the [CUDA toolkit][cuda-url].
+You can install the package via pip:
+```bash
+pip install qmp-kit
+```
 
-The `qmp` 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:
+Or run it directly using `uvx` (recommended):
+```bash
+uvx qmp-kit
 ```
-pip install qmp-kit
+
+### Usage
+
+The application is now configured via a `config.yaml` file located in the working directory. It uses [Hydra][hydra-url] for configuration management.
+
+To run the application:
+```bash
+# Using the installed script
+qmp
+
+# Or using uvx
+uvx qmp-kit
+```
+
+#### Configuration Structure
+
+A typical `config.yaml` includes several sections: `common`, `model`, `network`, `optimizer`, and `action`.
+
+```yaml
+# Example config.yaml
+model:
+  name: fcidump
+  params:
+    model_path: /path/to/molecule.fcidump
+    ref_energy: -7.44606892
+
+network:
+  name: mlp/u1u1
+  params:
+    hidden: [512, 512]
+
+optimizer:
+  name: Adam
+  params:
+    lr: 0.001
+
+common:
+  random_seed: 2333
+  device: cuda
+  dtype: bfloat16
+
+action:
+  name: haar
+  params:
+    sampling_count_from_neural_network: 1024
+    krylov_iteration: 32
 ```
-If users face network issues, consider setting up a mirror with the `-i` option.
 
-Users can then invoke the `qmp` script.
+#### Configuration Options
+
+##### Common Settings (`common`)
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `device` | Computing device (`cuda`, `cpu`, `cuda:0`, etc.) | `cuda:0` |
+| `dtype` | Data type (`bfloat16`, `float16`, `float32`, `float64`) | `None` |
+| `random_seed` | Manual random seed for reproducibility | `None` |
+| `checkpoint_interval` | Interval (in steps) to save checkpoints | `5` |
+| `parent_path` | Path to load a checkpoint from | `None` |
+| `max_absolute_step` | Maximum absolute step for the process | `None` |
+| `max_relative_step` | Maximum relative step for the process | `None` |
+
+##### Model Settings (`model`)
+- **fcidump**: Interface for FCIDUMP files.
+  - `model_path`: Path to the FCIDUMP file.
+  - `ref_energy`: Reference energy (optional).
+- **hubbard**: 2D Hubbard model.
+  - `m`, `n`: Lattice dimensions.
+  - `t`, `u`: Model coefficients.
+  - `electron_number`: Number of electrons.
+- **ising**: 2D Ising-like model on a lattice.
+  - `m`, `n`: Lattice dimensions.
+  - `x`, `y`, `z`: Coefficients for the transverse and longitudinal fields.
+  - `xh`, `yh`, `zh`: Coefficients for horizontal bond interactions (XX, YY, ZZ).
+  - `xv`, `yv`, `zv`: Coefficients for vertical bond interactions.
+  - `xd`, `yd`, `zd`: Coefficients for diagonal bond interactions.
+  - `xa`, `ya`, `za`: Coefficients for anti-diagonal bond interactions.
 
-Please note that if the CUDA toolkit version is too old, users must install a compatible PyTorch version before running `pip install qmp-kit`.
-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.
+##### Network Settings (`network`)
+The available network architectures and their naming conventions depend on the chosen model, as they implement specific symmetry and conservation laws. **Explicit naming is recommended** to clarify the constraints being used (e.g., total electron number `u1` or spin-resolved `u1u1`).
+
+For models like **fcidump** and **hubbard**, recommended options include:
+- **mlp/u1u1**: Multi-Layer Perceptron with $U(1) \times U(1)$ symmetry (conserves spin-up and spin-down electrons separately).
+- **mlp/u1**: MLP with $U(1)$ symmetry (conserves total electron number).
+- **transformers/u1u1**: Transformer architecture with $U(1) \times U(1)$ symmetry.
+- **transformers/u1**: Transformer architecture with $U(1)$ symmetry.
+
+Parameters for these networks:
+- **mlp** variants:
+  - `hidden`: Tuple of hidden layer widths (e.g., `[512, 512]`).
+- **transformers** variants:
+  - `embedding_dim`, `heads_num`, `depth`, etc.
+
+##### Action Settings (`action`)
+The `action` section determines the algorithm to run. The primary algorithms are **haar** and **vmc**. Each action has its own set of parameters defined in its corresponding configuration class.
+
+Example for `haar` action:
+```yaml
+action:
+  name: haar
+  params:
+    sampling_count_from_neural_network: 1024
+    krylov_iteration: 32
+    # ... other haar specific parameters
+```
 
 ## Contributing
 
@@ -47,5 +145,5 @@ This project is distributed under the GPLv3 License. See [LICENSE.md](LICENSE.md
 [pyenv-url]: https://github.com/pyenv/pyenv
 [our-pypi-url]: https://pypi.org/project/qmp-kit/
 [pytorch-install-url]: https://pytorch.org/get-started/locally/
-[models-url]: https://huggingface.co/datasets/USTC-KnowledgeComputingLab/qmp-models
-[naqs-url]: https://github.com/tomdbar/naqs-for-quantum-chemistry
+[hydra-url]: https://hydra.cc/
+[haar-url]: https://pubs.acs.org/doi/10.1021/acs.jctc.5c01415