Metadata-Version: 2.4
Name: cqpes
Version: 2.3.0
Summary: A GPU-Aided Software Package for Developing Full-Dimensional Accurate Potential Energy Surfaces
Author-email: mizu-bai <shiragawa4519@outlook.com>, kshsong <songks@foxmail.com>
License: BSD 2-Clause Simplified License
Project-URL: Homepage, https://github.com/CQPES/cqpes-legacy
Keywords: potential-energy-surface,neural-network,chemical-reaction-dynamics
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# CQPES (ChongQing Potential Energy Surface)

[![DOI](https://img.shields.io/badge/DOI-10.3390/chemistry7060201-B31B1B)](https://doi.org/10.3390/chemistry7060201)
[![PyPI version](https://img.shields.io/pypi/v/cqpes)](https://pypi.org/project/cqpes/)
[![GitHub license](https://img.shields.io/github/license/CQPES/cqpes-legacy)](https://github.com/CQPES/cqpes-legacy/blob/main/LICENSE)
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/CQPES/cqpes-legacy)
[![zread](https://img.shields.io/badge/Ask_Zread-_.svg?style=flat&color=00b0aa&labelColor=000000&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTQuOTYxNTYgMS42MDAxSDIuMjQxNTZDMS44ODgxIDEuNjAwMSAxLjYwMTU2IDEuODg2NjQgMS42MDE1NiAyLjI0MDFWNC45NjAxQzEuNjAxNTYgNS4zMTM1NiAxLjg4ODEgNS42MDAxIDIuMjQxNTYgNS42MDAxSDQuOTYxNTZDNS4zMTUwMiA1LjYwMDEgNS42MDE1NiA1LjMxMzU2IDUuNjAxNTYgNC45NjAxVjIuMjQwMUM1LjYwMTU2IDEuODg2NjQgNS4zMTUwMiAxLjYwMDEgNC45NjE1NiAxLjYwMDFaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00Ljk2MTU2IDEwLjM5OTlIMi4yNDE1NkMxLjg4ODEgMTAuMzk5OSAxLjYwMTU2IDEwLjY4NjQgMS42MDE1NiAxMS4wMzk5VjEzLjc1OTlDMS42MDE1NiAxNC4xMTM0IDEuODg4MSAxNC4zOTk5IDIuMjQxNTYgMTQuMzk5OUg0Ljk2MTU2QzUuMzE1MDIgMTQuMzk5OSA1LjYwMTU2IDE0LjExMzQgNS42MDE1NiAxMy43NTk5VjExLjAzOTlDNS42MDE1NiAxMC42ODY0IDUuMzE1MDIgMTAuMzk5OSA0Ljk2MTU2IDEwLjM5OTlaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik0xMy43NTg0IDEuNjAwMUgxMS4wMzg0QzEwLjY4NSAxLjYwMDEgMTAuMzk4NCAxLjg4NjY0IDEwLjM5ODQgMi4yNDAxVjQuOTYwMUMxMC4zOTg0IDUuMzEzNTYgMTAuNjg1IDUuNjAwMSAxMS4wMzg0IDUuNjAwMUgxMy43NTg0QzE0LjExMTkgNS42MDAxIDE0LjM5ODQgNS4zMTM1NiAxNC4zOTg0IDQuOTYwMVYyLjI0MDFDMTQuMzk4NCAxLjg4NjY0IDE0LjExMTkgMS42MDAxIDEzLjc1ODQgMS42MDAxWiIgZmlsbD0iI2ZmZiIvPgo8cGF0aCBkPSJNNCAxMkwxMiA0TDQgMTJaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00IDEyTDEyIDQiIHN0cm9rZT0iI2ZmZiIgc3Ryb2tlLXdpZHRoPSIxLjUiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIvPgo8L3N2Zz4K&logoColor=ffffff)](https://zread.ai/CQPES/cqpes-legacy)

This package is a Python implementation of potential energy surface (PES) fitting with permutational invariant polynomials neural network (PIP-NN).

Paper: [CQPES: A GPU-Aided Software Package for Developing Full-Dimensional Accurate Potential Energy Surfaces by Permutation-Invariant-Polynomial Neural Network](https://doi.org/10.3390/chemistry7060201)

If CQPES helps your work, please cite correctly.

> Li, J.; Song, K.; Li, J. CQPES: A GPU-Aided Software Package for Developing Full-Dimensional Accurate Potential Energy Surfaces by Permutation-Invariant-Polynomial Neural Network. _Chemistry (Basel)_ **2025**, _7_ (6), 201. https://doi.org/10.3390/chemistry7060201.

## Installation

We provide pre-packaged installers including all dependencies (TensorFlow, CUDA, etc.). This is the most stable way to use CQPES.

### Step 1: Deploy the Environment

Download the installer from [Releases](https://github.com/cqpes/cqpes-legacy/releases).

Run the installer:

```bash
# cpu version
$ bash ./cqpes-cpu-2.3.0-Linux-x86_64.sh
# cuda version
$ cat cqpes-cu129-2.3.0-Linux-x86_64.sh.part* > cqpes-cu129-2.3.0-Linux-x86_64.sh
$ bash ./cqpes-cu129-2.3.0-Linux-x86_64.sh
```

### Step 2: Install CQPES

Activate your environment first:

```
$ conda activate /path/to/cqpes-env
```

For standard users, simply install via `pip`:

```bash
(cqpes-env)$ pip install cqpes
```

For beginners and developers, or offline environments, clone the repository and install from source:

```bash

(cqpes-env)$ git clone https://github.com/CQPES/cqpes-legacy.git
(cqpes-env)$ cd cqpes-legacy
# For users
(cqpes-env)$ pip install .
# For developers
(cqpes-env)$ pip install -e .
```

### Step 3: Verify the installation

```bash
(cqpes-env)$ cqpes -h
usage: cqpes [-h] [-v] {prepare,train,test,export,predict,run} ...

CQPES: GPU-Aided Potential Energy Surface Development Toolkit

positional arguments:
  {prepare,train,test,export,predict,run}
                        Sub-commands
    prepare             Prepare dataset from raw files
    train               Train PIP-NN model via Keras & TensorFlow
    test                Evaluate model performance and plot errors
    export              Export trained model for dynamics interfaces
    predict             Predict energies for a given XYZ trajectory
    run                 Run tasks (Opt, TS, Freq, MD) using trained PES via ASE

options:
  -h, --help            show this help message and exit
  -v, --version         show program's version number and exit
```

## The CQPES Workflow

CQPES provides a unified Command Line Interface (CLI) for the entire PES development lifecycle: from data preparation and training, to model evaluation and dynamic simulations.

You can try the following steps in directory `examples/CH4`!

## Step 0. Choose Your Backend

CQPES now supports two powerful backends to balance compatibility and performance:

| Feature | **MSA (Legacy)** | **JaxPIP (Modern)** |
| :---: | :---: | :---: |
| **Core Engine** | TensorFlow + Keras | JAX + Equinox |
| **PIP Logic** | `f2py` Dynamic Linking Library (wrapper for MSA-2.0) | Native JaxPIP Implementation |
| **Derivatives** | Analytical (Hybrid Fortran-based & Tensorflow) | Automatic Differentiation |
| **Performance** | Baseline | Extreme (XLA Optimized) |

### Step 1. Generate PIP Basis

#### MSA Backend

We provide a wrapper for MSA-2.0 to generate the PIP basis. Clone the builder repository:

```bash
(cqpes-env)$ git clone https://github.com/CQPES/PyMSA-Builder.git
(cqpes-env)$ cd PyMSA-Builder
(cqpes-env)$ python3 build.py
```

Follow the interactive prompts to configure your molecular system (e.g., `4 1` for an A<sub>4</sub>B system like CH<sub>4</sub>). Once built, copy the generated .so library into your working directory.

#### JaxPIP Backend

1. **Basis Conversion**: Convert your existing PIP definitions to JaxPIP JSON format using the cli tool [`jaxpip bas2json`](https://github.com/CQPES/JaxPIP).
2. **Library**: You can also find pre-computed basis sets in the [JaxPIP Basis Library](https://github.com/CQPES/JaxPIP-Basis-Library).


### Step 2: Prepare Dataset

Two input formats are supported for the raw data:

**Legacy plain-text** - a standard xyz file plus a plain-text file of absolute electronic energies (one per frame, in **Hartree**). A reference energy is subtracted (`ref_energy` in the config, default: the dataset minimum) and the dataset stores `V = (E - E_ref)` in eV together with the reference:

```json
{
    "xyz": "rawdata/CH4.xyz",
    "energy": "rawdata/CH4_CCSD-T.dat",
    "ref_energy": null,
    "alpha": 1.0,
    "output": "data"
}
```

**extxyz** - a single self-describing extxyz file; point `xyz` and `energy` at the same file and the embedded energies (in **eV**, ASE convention) are used **as-is**: they are V, the quantity the PES reproduces verbatim - no reference is subtracted and `ref_energy` is ignored:

```json
{
    "xyz": "rawdata/CH4.extxyz",
    "energy": "rawdata/CH4.extxyz",
    "alpha": 1.0,
    "output": "data"
}
```

Pack them into efficient NumPy arrays using the prepare command:

`MSA`:

```bash
(cqpes-env)$ cqpes prepare config/prepare.json --msa msa.cpython-310-x86_64-linux-gnu.so
```

`JaxPIP`:

```bash
(cqpes-env)$ cqpes prepare config/prepare.json --jaxpip MOL_x_y_z_k.json
```

This handles the Morse-like variable transformations and structural unpacking automatically based on your JSON configuration.

### Step 3: Model Training

Train the PIP-NN model using Levenberg-Marquardt (LM) or other optimizers defined in your configuration file:

```bash
(cqpes-env)$ cqpes train config/train.json
```

The trained models and training logs will be saved in a timestamped output path for model, e.g., `model_20260315_123751`.

The training log reports physical-unit errors alongside the scaled LM loss: `E_MAE/E_RMSE` in meV and, for force-aided fits, `F_MAE/F_RMSE` in meV/Angstrom.
 
#### Weighting Function
 
By default, all samples are weighted equally. To emphasize specific energy regions (e.g., near the potential well), provide a custom weighting function via the `-w` / `--weighting` flag:
 
```bash
(cqpes-env)$ cqpes train config/train.json -w weighting.py
```

If the flag is omitted, CQPES reports that uniform weighting is active.

#### Force-Aided Fitting (Gradients)

CQPES can fit energies and forces simultaneously. Force-aided fitting uses a **single extxyz file**: point `xyz`, `energy` and `force` at the same file in your `prepare.json`:

```json
{
    "xyz": "rawdata/CH4.extxyz",
    "energy": "rawdata/CH4.extxyz",
    "force": "rawdata/CH4.extxyz",
    "alpha": 1.0,
    "output": "data"
}
```

Coordinates, energies and forces are extracted from the file, following ASE conventions: energies in eV, forces in eV/Angstrom. The energy values are used **as-is** (they are V, the quantity the PES reproduces verbatim - no reference is subtracted, and `ref_energy` is ignored in this mode). Structures with a periodic boundary are rejected unless the cell is a vacuum box much larger than the molecule (a warning is printed).

Any tool that writes extxyz works - for a DeePMD-kit dataset, four lines of `dpdata` produce it:

```python
import dpdata
from ase.io import write
frames = [dpdata.LabeledSystem(d, fmt="deepmd/npy").to_ase_structure()
          for d in ["00.data/training_data", "00.data/validation_data"]]
write("dataset.extxyz", [a for split in frames for a in split])
```

During `prepare`, the PIP Jacobian `dp/dxyz` is stored in the dataset (`dbemsav` for the `MSA` backend, forward-mode AD for `JaxPIP`). During training, the force residuals

```
F = -dV/dxyz = -(dV/dy · dX/dp · dp/dxyz) · (dy/dX)
```

are assembled per sample — `dy/dX` via an analytic matmul chain, the constant factors folded into a scale vector — and appended to the LM residual vector, so `tf_levenberg_marquardt` fits energies and forces in one shot (fully FP64).

Both residual blocks are normalized to O(1) before fitting: energies via the min-max scaling to `[-1, 1]`, forces by their dataset RMS (DeePMD-style `sigma_F`), so the loss is

```
loss = MSE(ΔE / s_E) + force_weight · MSE(ΔF / F_rms)
```

and `fit.force_weight` in `train.json` is a dataset-independent relative weight (`1` balances the two relative errors). The "physical" balance where a 1 meV/Å force error counts the same as a 1 meV energy error corresponds to `force_weight = (F_rms / s_E)²` with `s_E = (V_max - V_min) / 2` — about `98` for the CH₄ example below.

See [`examples/CH4-with-forces`](examples/CH4-with-forces) (DeePMD data) and [`examples/CH4-MSA-2.0`](examples/CH4-MSA-2.0) (MSA-2.0 `geom.inp` data) for complete runs.

### Step 4. Model Evaluation

Evaluate the accuracy of your trained PES against the test set:

```bash
(cqpes-env)$ cqpes test model_20260315_123751/
```

This will automatically compute MAE, MSE, and RMSE for your training, validation, and test subsets. Additionally, fitting error scatter plots and histograms will be generated and saved in the model path for visual diagnostics.

For datasets with forces, a second table reports force MAE/RMSE/MaxErr (meV/Angstrom) together with the per-frame force-norm error and the cosine similarity between predicted and reference force vectors.

### Step 5. Model Export

CQPES can be exported in 2 formats:

- Standard Keras `h5` format, required by `predict` and `run` commands if `MSA` backend used.
- Experimental `JaxPIP` format, required by `predict` and `run` commands if `JaxPIP` backend used.
- Legacy `potfit` plain text format, compatible with fortran interface for software like Polyrate, VENUS96C, or Caracal.

```bash
(cqpes-env)$ cqpes export -t h5 model_20260315_123751/
(cqpes-env)$ cqpes export -t jaxpip model_20260315_123751/
(cqpes-env)$ cqpes export -t potfit model_20260315_123751/
```

The exported files will be stored in model path.

### Step 6. Property Prediction

```bash
(cqpes-env)$ cqpes predict model_20260315_123751 new_trajectory.xyz --output predictions.xyz
```

### Step 7. Running Simulations

CQPES is fully integrated with the Atomic Simulation Environment (ASE). You can perform high-level computational chemistry tasks directly via the CLI:

```bash
# Geometry optimization followed by analytical frequency analysis
(cqpes-env)$ cqpes run model_20260315_123751 ch4.xyz --opt min --freq

# Transition State (TS) search (requires Sella)
(cqpes-env)$ cqpes run model_20260315_123751 guess_ts.xyz --opt ts --freq

# Molecular Dynamics (NVT ensemble at 300K)
(cqpes-env)$ cqpes run model_20260315_123751 input.xyz --md nvt --temp 300.0 --dt 1.0 --steps 5000 -o md.xyz
```

## Supported Interfaces & Interoperability

### Python

```python
from cqpes import CQPESPot, CQPESCalculator
```

### Fortran

[`examples/CH4/interface/Fortran`](https://github.com/CQPES/cqpes-legacy/tree/main/examples/CH4/interface/Fortran)

### Gaussian

[`examples/CH4/interface/Gaussian`](https://github.com/CQPES/cqpes-legacy/tree/main/examples/CH4/interface/Gaussian)

### Polyrate

[CQPES Legacy + Polyrate](https://github.com/CQPES/cqpes-legacy-polyrate)

### VENUS96

[`examples/CH4/interface/VENUS96C`](https://github.com/CQPES/cqpes-legacy/tree/main/examples/CH4/interface/VENUS96C)

### Caracal

## Reference

- (1) Xie, Z.; Bowman, J. M. Permutationally Invariant Polynomial Basis for Molecular Energy Surface Fitting via Monomial Symmetrization. _J. Chem. Theory Comput._ **2010**, _6_ (1), 26–34. https://doi.org/10.1021/ct9004917.
- (2) Nandi, A.; Qu, C.; Bowman, J. M. Using Gradients in Permutationally Invariant Polynomial Potential Fitting: A Demonstration for CH4 Using as Few as 100 Configurations. _J. Chem. Theory Comput._ **2019**, _15_ (5), 2826–2835. https://doi.org/10.1021/acs.jctc.9b00043.
- (3) Jiang, B.; Guo, H. Permutation Invariant Polynomial Neural Network Approach to Fitting Potential Energy Surfaces. _J. Chem. Phys._ **2013**, _139_ (5). https://doi.org/10.1063/1.4817187.
- (4) Li, J.; Jiang, B.; Guo, H. Permutation Invariant Polynomial Neural Network Approach to Fitting Potential Energy Surfaces. II. Four-Atom Systems. _J. Chem. Phys._ **2013**, _139_ (20). https://doi.org/10.1063/1.4832697.
- (5) Li, J.; Song, K.; Li, J. CQPES: A GPU-Aided Software Package for Developing Full-Dimensional Accurate Potential Energy Surfaces by Permutation-Invariant-Polynomial Neural Network. _Chemistry (Basel)_ **2025**, _7_ (6), 201. https://doi.org/10.3390/chemistry7060201.
