CQPES (ChongQing Potential Energy Surface)

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

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.

Run the installer:

# 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:

(cqpes-env)$ pip install cqpes

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

(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

(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:

(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₄B system like CH₄). 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.
2. Library: You can also find pre-computed basis sets in the 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:

{
    "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:

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

Pack them into efficient NumPy arrays using the prepare command:

MSA:

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

JaxPIP:

(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:

(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:

(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:

{
    "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:

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 (DeePMD data) and 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:

(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.

(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

(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:

# 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

from cqpes import CQPESPot, CQPESCalculator

Fortran

examples/CH4/interface/Fortran

Gaussian

examples/CH4/interface/Gaussian

Polyrate

CQPES Legacy + Polyrate

VENUS96

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.