CDFCI

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #claude-code #codex #cli #developer-tools #react #windows

★ 20 Open GitHub ↗

C++ implemented Coordinate Descent Full Configuration Interaction (CDFCI) package for quantum chemistry calculation.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# CDFCI

[![CDFCI\_Test](https://github.com/CDFCI/CDFCI/actions/workflows/cdfci_test.yml/badge.svg?branch=master)](https://github.com/CDFCI/CDFCI/actions/workflows/cdfci_test.yml)

CDFCI (Coordinate Descent Full Configuration Interaction) is a modern, efficient solver for the ground-state electronic structure problem in quantum chemistry. It is implemented in modern C++17 with support for large-scale sparse wavefunctions and adaptive compression strategies.

📖 中文说明请参见：[README\_zh.md](doc/README_zh.md)

---

## ✨ Overview

CDFCI reformulates the full configuration interaction (FCI) eigenvalue problem as a large-scale unconstrained nonconvex optimization problem. It solves this problem using adaptive coordinate descent with deterministic compression.

Key features:

* Coordinate-wise update of Slater determinants
* Adaptive compression via `z_threshold`
* Deterministic and memory-aware wavefunction storage
* Optional support for OpenMP (multi-threaded)

---

## 📄 Citation

The primary paper for this software package is:

* **CDFCI Software Paper**
  Y. Zhang, Z. Wang, J. Lu, Y. Li, [*arXiv:2605.04483*, 2026](https://arxiv.org/abs/2605.04483)

Algorithm-specific papers:

* **CDFCI Core Algorithm**
  Z. Wang, Y. Li, J. Lu, [*JCTC*, 15(6), 2019](https://pubs.acs.org/doi/10.1021/acs.jctc.9b00138)

* **Optimal Orbital Selection (OptOrbFCI)**
  Y. Li, J. Lu, [*JCTC*, 16(10), 2020](https://pubs.acs.org/doi/10.1021/acs.jctc.0c00613)

* **Low-lying Excited States Extension**
  Z. Wang, Z. Zhang, J. Lu, Y.Li, [*JCTC*, 19(21), 2023](https://pubs.acs.org/doi/abs/10.1021/acs.jctc.3c00452)

* **Multicoordinate Parallel Extension**
  Y. Zhang, W. Gao, Y. Li, [*JCTC*, 21(5), 2025](https://pubs.acs.org/doi/10.1021/acs.jctc.4c01530)

with convergence guarantee:

* **Coordinate Descent Convergence Theory**
  Y. Li, J. Lu, Z. Wang, [*SIAM J. Sci. Comput.*, 41(4), 2019](https://doi.org/10.1137/18M1202505)

Please cite the relevant paper(s) if you use this software.

---

## 🚀 Getting Started

For Python workflows and advanced scripting usage, see the [Python Interface User Manual](./PYTHON_INTERFACE_USER_MANUAL.md).

### Clone and Build

```bash
git clone --recursive https://github.com/CDFCI/CDFCI.git
cd CDFCI
make
```

The following executables will be generated in the `bin` directory:

* `cdfci`: single-threaded version
* `cdfci_omp`: OpenMP-enabled version
* `xcdfci`: for excited states
* `optorbfci`: for orbital rotation and compression
* `cdfci_tools`: auxiliary utilities

Alternatively, you may use `make cdfci `, `make optorbfci` or  `make xcdfci` to generate specific executable.

Useful release-related targets:

* `make check`: run test gate (`make test` alias)
* `make install PREFIX=/path`: install binaries to `${PREFIX}/bin` (default `/usr/local/bin`)
* `make uninstall PREFIX=/path`: remove installed binaries
* `make release-check`: run clean build + regression tests + examples

### Requirements

* C++17 compiler (GCC ≥ 9, Clang ≥ 10, or ICC)
* [Eigen3](https://eigen.tuxfamily.org) (will be clone recursively)
* OpenMP (optional)
---

## 📥 Input Format (JSON)

The solver accepts a JSON input file. Example:

```json
{
    "hamiltonian": {
        "type": "molecule",
        "molecule": {
            "fcidump_path": "/path/to/FCIDUMP",
            "threshold": 0.0
        }
    },
    "solver":{
        "type": "cdfci",
        "cdfci": {
            "num_iterations": 150000,
            "report_interval": 10000,
            "z_threshold": 0,
            "z_threshold_search": false
        }
    },
    "max_memory": 0.005
}
```

More examples, including [a full documentation for input and output](./examples/README.md), can be found in the `examples/` directory.

Quickstart:
```bash
cd examples && ../bin/cdfci demo_input_cdfci.json
```

---

## 🧪 Testing

To compile and run regression tests:

```bash
make test
```

Example systems and expected energies are provided in `regression_tests`.

---

## 📊 Reproducibility

The `examples/` directory mainly contains simple, small-scale examples for quick runs. The `papers/` directory contains examples discussed in the experimental sections of related papers, including those from the primary software paper and the algorithm-specific papers listed above. Python and [PySCF](https://github.com/pyscf/pyscf) are required to generate FCIDUMP files.

---

## 👥 Developers

* [Yuejia Zhang](https://ninotreve.github.io/) (School of Mathematical Sciences, Fudan University)
* Zhe Wang (Department of Mathematics, Duke University)
* [Jianfeng Lu](https://services.math.duke.edu/~jianfeng/) (Department of Mathematics,
  Department of Physics and Department of Chemistry, Duke University)
* [Yingzhou Li](http://yingzhouli.com/) (School of Mathematical Sciences and
  Shanghai Key Laboratory for Contemporary Applied Mathematics,
  Fudan University)

---

## 🪙 Acknowledgements

This work was supported in part
by the National Natural Science Foundation of China under Grant
Nos. 12271109 and 12526211;
by the U.S. National Science Foundation
(NSF) under Grant Nos. DMS-1454939 and DMS-2012286;
by the Shanghai Pilot Program for Basic Research-Fudan University
under Grant No. 21TQ1400100 (22TQ017);
by the Scientific Research Innovation Capability Support Project
for Young Faculty under Grant No. SRICSPYF-ZY2025159;
and by the Xuemin Institute of Advanced Studies, Fudan University.

---

## ⚖️ License

This project is licensed under the BSD 3-Clause License. See the [LICENSE](./LICENSE) file for details.

CDFCI

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README