Skip to content

README.md

Latest commit

 

History

History
195 lines (151 loc) · 4.84 KB

README.md

File metadata and controls

195 lines (151 loc) · 4.84 KB
Raw

DeePTB Pardiso Integration - Example Directory

This directory contains examples for using DeePTB's Pardiso backend for band structure and density-of-states calculations.

Files

Data Files

  • min.vasp: Example structure file (C84 fullerene)
  • nnsk.iter_ovp0.000.pth: Pre-trained DeePTB model
  • band.json: Configuration file for band structure calculation
  • dos.json: Configuration file for density-of-states calculation

Notebooks

  • pardiso_tutorial.ipynb ⭐: Complete tutorial covering:

    • Python API usage (to_pardiso_json())
    • CLI integration (dptb pdso)
    • Manual Julia execution
    • Result visualization
    • Backward compatibility

  • dptb_to_Pardiso_new.ipynb: Legacy notebook (kept for reference)

  • dptb_to_Pardiso.ipynb: Original notebook (deprecated)

Scripts

  • test_pardiso_new.py: Automated test script for the export workflow

Quick Start

Option 1: Using CLI (Recommended)

dptb pdso \
  band.json \
  -i nnsk.iter_ovp0.000.pth \
  -stu min.vasp \
  -o ./output

With custom solver parameters:

dptb pdso \
  band.json \
  -i nnsk.iter_ovp0.000.pth \
  -stu min.vasp \
  -o ./output \
  --ill_project false \
  --ill_threshold 1e-3

Results will be in ./output/results/.

To calculate DOS instead of bands:

dptb pdso \
  dos.json \
  -i nnsk.iter_ovp0.000.pth \
  -stu min.vasp \
  -o ./output_dos

To reuse an existing Pardiso export directory without re-running DeePTB:

dptb pdso \
  band.json \
  -d ./output \
  -o ./rerun_output

Option 2: Using Python API

from dptb.postprocess.unified.system import TBSystem

# Initialize
tbsys = TBSystem(data="min.vasp", calculator="nnsk.iter_ovp0.000.pth")

# Export
tbsys.to_pardiso_json(output_dir="pardiso_data")

# Run Julia backend
import subprocess
subprocess.run([
    "julia", "../../dptb/postprocess/pardiso/main.jl",
    "--input_dir", "pardiso_data",
    "--output_dir", "results",
    "--config", "band.json"
])

Option 3: Interactive Tutorial

Open pardiso_tutorial.ipynb in Jupyter for a complete walkthrough.

Configuration File Format

band.json example:

{
  "task_options": {
    "task": "band",
    "eig_solver": "numpy",
    "kline_type": "abacus",
    "kpath": [
      [0.0, 0.0, 0.0, 30],
      [0.0, 0.0, 0.5, 1]
    ],
    "klabels": ["G", "Z"],
    "E_fermi": -9.03841,
    "emin": -2,
    "emax": 2
  },
  "num_band": 30,
  "max_iter": 400,
  "isspinful": "false"
}

dos.json uses the same export format with task: "dos" and a Monkhorst-Pack-style kmesh:

{
  "task_options": {
    "task": "dos",
    "eig_solver": "numpy",
    "kmesh": [1, 1, 1],
    "fermi_level": -9.03841,
    "epsilon": 0.05,
    "omegas": [-2.0, 2.0, 401]
  },
  "num_band": 30,
  "max_iter": 400,
  "isspinful": "false"
}

The example configs use "eig_solver": "numpy" so they run on machines without MKL/Pardiso. On Linux systems with MKL/Pardiso available, remove this field or set it to "pardiso" to use the Pardiso eigensolver path.

Output Files

After running the workflow, you'll get:

Export Directory (pardiso_data/)

  • structure.json: Structure and basis information
  • predicted_hamiltonians.h5: Hamiltonian matrix blocks
  • predicted_overlaps.h5: Overlap matrix blocks

Results Directory (results/)

  • bandstructure.h5: Band structure data (HDF5 format, band task)
  • bands.dat: Text format band data (band task)
  • egvals.dat: Eigenvalues on the DOS k-mesh (DOS task)
  • dos.dat: Text format DOS data when epsilon and omegas are configured (DOS task)

Advanced Usage

Backward Compatibility

For legacy workflows, use to_pardiso_debug() to export .dat files:

tbsys.to_pardiso_debug(output_dir="legacy_data")

The Julia backend will automatically detect and load these files if structure.json is missing.

Performance Tuning

Edit band.json or dos.json:

  • num_band: Number of bands to calculate (default: 30)
  • max_iter: Maximum iterations for eigenvalue solver (default: 400)
  • emin, emax: Plotting energy window for band structure
  • kmesh: K-point mesh for DOS calculations
  • epsilon, omegas: Gaussian broadening and energy grid for DOS output

For ill-conditioned systems, run Julia with:

julia main.jl --input_dir data --output_dir results --config band.json --ill_project true

Troubleshooting

Issue: structure.json not found

  • Solution: Run tbsys.to_pardiso_json() first

Issue: Eigenvalues don't converge

  • Solution: Increase max_iter in config or adjust E_fermi

Issue: Dimension mismatch for spinful systems

  • Solution: Ensure isspinful matches your model (check hasattr(model, 'soc_param'))

References