First, create the base environment using the provided environment.yml:

conda env create -f environment.yml
conda activate detnqs

The project requires MathDX 25.12.0. It must be installed manually into your conda environment directory to satisfy build dependencies.

# 1. Download the CUDA 12 compatible package
wget https://developer.nvidia.com/downloads/compute/cuSOLVERDx/redist/cuSOLVERDx/cuda12/nvidia-mathdx-25.12.0-cuda12.tar.gz

# 2. Extract
tar -xzf nvidia-mathdx-25.12.0-cuda12.tar.gz --strip-components=1 -C "$CONDA_PREFIX"

# 3. Verify the installation
ls "$CONDA_PREFIX/nvidia/mathdx/25.12/include/cusolverdx.hpp"
ls "$CONDA_PREFIX/nvidia/mathdx/25.12/include/cusolverdx_io.hpp"

With the environment and MathDX in place, install the package in editable mode.

pip install -e . -v --no-build-isolation \
  -Cbuild-dir=build \
  --config-settings=cmake.define.detnqs_CUDA_ARCHS=80 \
  --config-settings=cmake.define.detnqs_CUSOLVERDX_SM=800

Note: The values 80 and 800 in the example above are configured for the NVIDIA Ampere (A100) architecture. Please adjust these flags to match the Compute Capability of your specific GPU (e.g., use 90 and 900 for H100, or 120 and 1200 for RTX 50-series). You can find your GPU's Compute Capability here.

To verify your installation and run a basic calculation, use the provided example script. This example performs a deterministic optimization on the H2O molecule using the 6-31G basis set.

# Ensure you are in the project root directory
python DetNQS/examples/run_single.py ../benchmark/FCIDUMP/H2O_631g.FCIDUMP --output runs/test

The main hyperparameters can be directly modified within the run_single.py script.

For a detailed theoretical background of the deterministic framework and the hybrid CPU-GPU implementation, please refer to our accompanying paper.

If you find this work useful for your research, or if you use the DetNQS source code in your project, we would appreciate it if you could cite our work:

@article{che2026detnqs,
  title={A Deterministic Framework for Neural Network Quantum States in Quantum Chemistry},
  author={Che, Zheng},
  journal={arXiv preprint arXiv:2601.21310},
  year={2026}
}

This project is licensed under the Apache 2.0 License. See the LICENSE file for more details.