defectpl 0.2.0

A unified package for optical properties of point defects.

DefectPL

A high-performance computational toolkit for calculating and visualizing the photoluminescence (PL) spectra, electron-phonon coupling characteristics, and optical lineshapes of quantum defect centers in insulators and semiconductors.

⚠️ Development Status: This package is under active development. Features, APIs, and documentation are subject to rapid updates.

---

📌 Overview & Key Features

DefectPL implements photoluminescence calculation framework based on standard generating function methodologies (New J. Phys. 16 073026 (2014)) to evaluate electronic-vibrational coupling profiles of point defects in solids from first-principles data. It bridges ab initio electronic structure outputs with experimentally observable optical lineshapes, specifically supporting high Huang-Rhys (HR) factor regimes.

The core engine provides automated pipelines to compute, serialize, and visualize:

• Macroscopic Optical Lineshapes: Full photoluminescence (PL) spectra sidebands accounting for multi-phonon convolutions.
• Coupling Parameters: Quantified total and mode-resolved partial Huang-Rhys factors ($S_k$), alongside temperature-dependent Debye-Waller factors ($I_{\text{ZPL}}/I_{\text{tot}}$).
• Phonon Localization Metrics: Spatial confinement analytics via Inverse Participation Ratios (IPR) and structural localization index mappings.
• Spectral Density Mapping: Multi-mode Electron-Phonon Spectral Density functions, $S(\omega)$.
• Isotope Engineering: Analytical evaluation of localized isotope substitution impacts on vibrational mode coupling pathways.

---

📚 Documentation & Reference

For comprehensive API references, mathematical formulations, and step-by-step tutorials, visit the official documentation portal: 👉 https://Shibu778.github.io/defectpl/

Citation

If you utilize DefectPL in your peer-reviewed scientific workflows, please cite the following original research works:

📄 Carbon with Stone-Wales Defect as Quantum Emitter in h-BN, Phys. Rev. B 111, 104109 (2025). DOI: 10.1103/PhysRevB.111.104109

📄 High-throughput Computational Search for Group-IV-related Quantum Defects as Spin-photon Interfaces in 4H-SiC, Phys. Rev. B 112, 184112 (2025). DOI: 10.1103/PhysRevB.112.184112

---

🚀 Installation

DefectPL can be seamlessly integrated via your preferred package manager ecosystem.

Standard Installation via PyPI

pip install defectpl

Stable Pre-compiled Binaries via Conda-Forge

conda install conda-forge::defectpl

Editable Source Build (For Developers)

git clone [https://github.com/Shibu778/defectpl.git](https://github.com/Shibu778/defectpl.git)
cd defectpl
pip install -e .

---

🧑‍💻 Architectural Tracks & Examples

DefectPL natively exposes two core calculation modalities: Displacement Mode (evaluating structural coordinate shift vectors) and Force Mode (evaluating vertical electronic excitation forces). All core engine classes inherit from Monty’s MSONable, ensuring atomic state serialization into lightweight JSON formats.

1. Displacement Mode (Structure Coordinates Tracking)

Ideal when relaxed atomic geometries for both the ground state (GS) and excited state (ES) are completely resolved alongside Phonopy supercell calculations.

from pathlib import Path
from pymatgen.core import Structure
from monty.serialization import dumpfn

from defectpl.phonon import read_band_yaml
from defectpl.vasp_wrapper import calc_dR
from defectpl.defectpl import Photoluminescence

# 1. Parse ground/excited state geometry and Phonopy coordinates
struct_gs = Structure.from_file("CONTCAR_GS")
struct_es = Structure.from_file("CONTCAR_ES")
frequencies, eigenvectors, masses = read_band_yaml("band.yaml")

# 2. Extract periodic-boundary-condition safe displacement matrices
dR = calc_dR(struct_gs, struct_es)

# 3. Initialize core execution engine
pl_engine = Photoluminescence(
    frequencies=frequencies,
    eigenvectors=eigenvectors,
    masses=masses,
    dR=dR,          # Pass dR matrix for Displacement mode
    dF=None,
    EZPL=1.95,
    gamma=2.0
)

# 4. Generate publication-quality graphics & serialize configuration states
pl_engine.generate_plots(out_dir="./plots", fig_format="png")
dumpfn(pl_engine, "properties.json", indent=4)

2. Force Mode (Force Difference Matrix Tracking)

Ideal for high-throughput pipelines, utilizing the force landscape acting on the ground-state structure under a vertical electronic excitation constraint.

from defectpl.vasp_wrapper import prepare_dF_files
from defectpl.defectpl import Photoluminescence
from defectpl.phonon import read_band_yaml

# 1. Parse standard Phonopy baseline calculations
frequencies, eigenvectors, masses = read_band_yaml("band.yaml")

# 2. Extract force difference vectors (dF = F_excited - F_ground) from VASP output streams
dF = prepare_dF_files("OUTCAR_GS", "OUTCAR_ES")

# 3. Execute solver via Force Matrix track
pl_engine = Photoluminescence(
    frequencies=frequencies,
    eigenvectors=eigenvectors,
    masses=masses,
    dR=None,
    dF=dF,          # Pass dF matrix for Force mode
    EZPL=1.95,
    gamma=2.0
)
pl_engine.generate_plots(out_dir="./plots", fig_format="png")

---

🤝 Contributing & Bug Reporting

We welcome community contributions, optimization proposals, and workflow suggestions! If you uncover numerical bugs or wish to request feature additions, please systematically log them through our official GitHub Issues portal or submit a structured Pull Request.

---

👤 Maintainers & Acknowledgements

Project Lead Maintainers: * Shibu Meher * Manoj Dey

Special Acknowledgements

The development of this software was supported and inspired by several foundational open-source packages within the materials physics community:

• PyPhotonics
• nonrad
• sumo
• phonopy