DeePaTB: A Deep Learning-Powered Semi-Empirical Quantum Mechanical Method

Install Manual

Requirements

First, you need to install Amesp. You can download it from the official website: https://www.amesp.xyz/download/. We also provide a compatible version of Amesp for your convenience.
We strongly recommend using python==3.9.0 to ensure optimal compatibility. and the datasets in https://zenodo.org/records/19156102

Step 1: Configure Amesp and Python environment

# Add Amesp binary directory to system PATH
export PATH=$PATH:/path/to/amesp/bin/

# Create a dedicated Conda environment with Python 3.9.0
mamba create -n deepatb2 python=3.9.0 -y

# Activate the environment (critical step)
conda activate deepatb2

# Install Python dependencies
pip install -r requirements.txt

# Install the DeePaTB utilities from this checkout
pip install -e .

# Alternative: Install with Tsinghua PyPI mirror for faster download (China mainland)
pip install -r requirements.txt -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple

Step 2: Install modified DeePKS-kit

cd deepks-kit

cd deepks-kit
python setup.py install

Usage

A complete example job for Qm7BT is provided in the job directory. Follow the steps below to run the workflow:

Step 1: Prepare training datasets

cd job/01_prepare

# Generate Amesp input files (.aip) - charge and spin are set to 0 and 1 for all systems
python 00_xyzaip.py

# Run Amesp calculations - ensure all jobs complete successfully
sh 01_run.sh

# Generate atom.npy file in npydata directory
python 02_xyztoatomnpy.py --dir file

# Generate descriptors and frozen-density derivatives (dm_eig and grad_vx)
python 03_get_aTB_decriptor.py --dir file

# Generate energy label file
python 04_get_delta_energy.py

# Generate force labels. Reference arrays are named <system>.npy and are
# converted to the canonical Hartree/Bohr unit.
python 05_get_delta_force.py \
    --amesp-dir file \
    --reference-dir reference_force \
    --reference-force-unit hartree/bohr

Step 1: Train the model

cd ../02_train  # Navigate to training directory

# Start model training
sh train.sh

# On this machine a GPU can be requested through Slurm. Activate the intended
# GPU-enabled DeePaTB environment before running this command.
sh train_gpu.sh

# Calculate predicted energies using the trained DeePaTB model
python get_deepatb_ene.py

# Calculate predicted energies and frozen-density analytic forces
python get_deepatb_force.py --save-results

For a direct XYZ single point from the repository root:

python job/03_force/evaluate_xyz.py \
    --xyz molecule.xyz \
    --model job/02_train/model.pth \
    --force-output analytic_force.npy

Validate that force against total-energy central differences:

python job/03_force/check_force_finite_difference.py \
    --xyz molecule.xyz \
    --coordinate-unit angstrom \
    --workdir "$PWD" \
    --command 'python job/03_force/evaluate_xyz.py --xyz {xyz} --model job/02_train/model.pth --energy-only --plain-energy' \
    --analytic-force analytic_force.npy

The default force mode is the frozen-density DeePKS contraction -dE_NN/d(dm_eig) * d(dm_eig)/dR. An experimental post-SCF analytic response mode is also available for the exact official Amesp build profiled in deepatb/amesp_response.py:

python job/03_force/evaluate_xyz.py \
    --xyz molecule.xyz \
    --model job/02_train/model.pth \
    --amesp /path/to/official/Amesp/Bin/amesp \
    --amesp-method aTB1 \
    --response-mode amesp-gdb \
    --force-output analytic_force.npy

This path requires GDB, the profiled 2026-08-23 binary, aTB1, and a restricted closed-shell system. It injects the ML W/L response matrices into Amesp's existing TDA-aTB CPSCC gradient and subtracts an uninjected carrier calculation. H2O validation against the same total-energy finite difference gave a maximum force-component error of about 1.56e-5 Hartree/Bohr.

The reusable correction potential dE_NN/dD is provided in deepatb/self_consistent.py. Fully self-consistent DeePKS forces still require an Amesp callback that adds this potential during every SCF iteration. See ANALYTIC_FORCE_IMPLEMENTATION.md for the derivation, validation criteria, and backend contract.

A direct dm_eig path with newer Amesp builds

The bundled Amesp 2.1(dev) executable rejects deephf as an unknown >ope keyword. Use 03_get_aTB_decriptor.py for the bundled executable, or install a newer Amesp build that explicitly provides this extension. The official build downloaded on 2026-08-26 accepts deephf on, requires aTB1/aTB2 instead of the old aTB alias, and writes <stem>.deephf containing the projected descriptor.

This option is descriptor output only. The current manual describes it as Calculate the deepHF density project, and a real aTB1 force probe contains no DeepHF/NN gradient term. It does not provide the SCF correction-potential and gradient callbacks required for strict self-consistent DeePaTB forces.

! aTB1
>ope
deephf on
end
>xyz 0 1
C      -4.602780000000000      2.228670000000000      0.000000000000000
H      -3.532780000000000      2.228670000000000      0.000000000000000
H      -4.959440000000000      1.272170000000000      0.320630000000000
H      -4.959440000000000      2.429240000000000     -0.988670000000000
H      -4.959440000000000      2.984590000000000      0.668030000000000
end