DDPC - DFT Data Processing Core

DDPC aims to be a handy Python library for processing and analyzing density functional theory (DFT) calculation data. It provides a unified interface for reading, writing, and manipulating crystal structures, electronic band structures, and density of states data from various DFT codes, such as VASP, DS-PAW, and RESCU.

📢 Announcement

This package is in early stage with limited functions. Use at your own risk.

API reference

✨ Key Features

• 🔄 Universal Structure I/O: Read and write crystal structures in multiple formats (VASP, DS-PAW, RESCU, CIF, etc.)
• 📊 Electronic Structure Analysis: Process band structure and density of states data from HDF5 and JSON files
• 🧮 Structure Utilities: Find primitive cells, create orthogonal supercells, and manipulate atomic positions
• ⚡ High Performance: Built on modern Python libraries for efficient data processing
• 🎯 Type Safety: Full type annotations for better development experience
• 📖 Comprehensive Documentation: Detailed API documentation with examples
• 🛠️ Unified CLI: Command-line interface for all DDPC functionality

🚀 Quick Start

Installation

pip install "ddpc[full]"

Basic Usage

Structure I/O

from ddpc import read_structure, write_structure

# Read crystal structure from various formats
atoms = read_structure("input.vasp")  # VASP POSCAR
atoms = read_structure("structure.as")  # DS-PAW format
atoms = read_structure("crystal.cif")   # CIF format

# Write to different formats
write_structure("output.vasp", atoms)
write_structure("structure.xyz", atoms)

Electronic Structure Analysis

Currently only support DS-PAW output hdf5/json format, will support others in the future.

from ddpc import read_band, read_dos

# Read band structure data
df_band, fermi_energy, has_projections = read_band("band.h5", mode=5)
print(f"Fermi energy: {fermi_energy:.3f} eV")

# Read density of states
df_dos, fermi_energy, has_projections = read_dos("dos.json", mode=1)

Structure Utilities

from ddpc import find_primitive, find_orthogonal, scale_positions
from ddpc import read_structure, write_structure

# Find primitive cell
atoms = read_structure("input.vasp")
prim = find_primitive(atoms, symprec=1e-5, angle_tolerance=-1.0)
write_structure("primitive.vasp", prim, format="vasp")

# Create orthogonal supercell
orth = find_orthogonal(atoms, min_length=15.0, max_length=20.0)
write_structure("ortho.vasp", orth, format="vasp")

# Convert to fractional coordinates
scaled = scale_positions(atoms)
write_structure("scaled.vasp", scaled, format="vasp", direct=True)

🛠️ Command-Line Interface

DDPC provides a unified command-line interface for all functionality:

Structure Commands

# Convert structure formats
ddpc structure convert input.vasp output.cif

# Show structure information
ddpc structure info input.vasp

# Find primitive cell
ddpc structure primitive input.vasp -o primitive.vasp

# Find orthogonal supercell
ddpc structure orthogonal input.vasp -o ortho.vasp

# Convert to fractional coordinates
ddpc structure scale input.vasp -o scaled.vasp

Data Commands

# Read band structure data
ddpc data band read band.h5 -o band_data.csv

# Show band structure info
ddpc data band info band.h5

# Read DOS data
ddpc data dos read dos.json -o dos_data.csv

# Show DOS info
ddpc data dos info dos.json

📚 Supported Formats

Crystal Structures

• VASP: POSCAR/CONTCAR files
• DS-PAW: Custom .as format with constraints and magnetism
• RESCU: Extended .xyz format with magnetic moments
• Standard formats: CIF, XYZ, and other ASE-supported formats

Electronic Structure Data

• HDF5 files: Band structure and DOS data from DFT calculations
• JSON files: Alternative format for smaller datasets
• Projected data: Orbital-resolved band structures and DOS

🛠️ Advanced Features

Constraint Handling

DDPC preserves and processes atomic and lattice constraints from specialized DFT codes:

# DS-PAW format with constraints
atoms = read_structure("constrained.as")
print(atoms.info)  # Shows constraint information

Magnetic Systems

Support for both collinear and non-collinear magnetic systems:

# Read magnetic structure
atoms = read_structure("magnetic.xyz")
print(atoms.get_initial_magnetic_moments())

Data Processing Modes

Multiple projection modes for electronic structure analysis:

# Different projection modes for band structure
df, ef, proj = read_band("band.h5", mode=1)  # Element-resolved
df, ef, proj = read_band("band.h5", mode=2)  # Orbital-resolved (s,p,d,f)
df, ef, proj = read_band("band.h5", mode=5)  # Detailed orbital projections

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🗓️ Changelog

v2025.11.24

• remove pymatgen and loguru dependencies, simplify dep tree.

v2025.11.21

✨ New Features

• Complete structure I/O system supporting DS-PAW, RESCU, and standard formats
• Electronic structure data processing for band structures and density of states
• Structure manipulation utilities (primitive cell finding, orthogonalization)
• Full type annotations and comprehensive documentation
• Support for magnetic systems and atomic constraints
• Unified command-line interface with rich formatting
• Modular architecture with optional dependencies

🔧 Technical Details

• Built on modern Python 3.12+ with full type safety
• Modular design with optional dependencies via extras
• Comprehensive test suite with high coverage
• Professional documentation with API reference