jahn-teller-dynamics 1.0.2

Dynamic Jahn-Teller Effect Calculator

Jahn-Teller-Dynamics - Dynamic Jahn-Teller Effect Calculator

Table of Contents

• About the Project
• Installation
• Usage
• Configuration Examples
• Output Options
• Eigenstates

About the project

A Python framework for implementing and calculating dynamic Jahn-Teller effects, spin-orbit interactions, and energy splitting of degenerate electron states from DFT calculations.

This codebase serves as a foundation for implementing dynamic Jahn-Teller (DJT) problems, providing:

• Core mathematical infrastructure (matrix mechanics, eigenvalue solvers, bra-ket formalism)
• Quantum system construction and management
• Hamiltonian building blocks (DJT, spin-orbit, field interactions)
• Flexible I/O system for configuration and results

In this version, the E⊗e dynamic Jahn-Teller problem is fully implemented for point defects and molecules. The framework provides a complete solution for:

• The E⊗e dynamic Jahn-Teller effect in point defects (e.g., group-IV vacancies in diamond/SiC)
• The E⊗e dynamic Jahn-Teller effect in molecules
• Spin-orbit interaction and coupling
• Energy splitting of degenerate electron states
• ZPL (zero phonon line) shift in magnetic field
• Reduction factor calculations
• Model Hamiltonian parameter extraction

This project was built with Python 3.10.

Installation

Installation directly from PyPI:

pip install jahn-teller-dynamics

Installation from Github

1. Download the project:

   git clone https://github.com/tbalu98/Jahn-Teller-Dynamics.git
   

   or download the zip file

2. Install dependencies:

   pip3 install -r requirements.txt
   

Usage

To run a calculation, you need to:

1. Create a configuration file (.cfg) that specifies your Jahn-Teller active system parameters
2. Run the following command, replacing configuration_file.cfg with your config file name:

Exe configuration_file.cfg

Test Data

To test the code, download the config_files and data folder that contains the vasprunxml files for the negatively charged tin vacancy (SnV) from: Google Drive

Configuration Examples

This section provides an introduction to configuration files. For complete, working examples with detailed comments and all available options, see the .cfg files in the config_files folder. The examples below highlight the key concepts and structure; refer to the actual config files for comprehensive documentation.

Configuration File Structure

Configuration files use INI format with the following sections:

1. [essentials] - Always first section

   • Basic settings: vibrational quanta, output paths, orbital basis representation
   • Output options: which files to save
   • Basis vectors for E⊗e coordinate system

2. [atom_structure_parameters] - Second section (when using CSV files)

   • Atomic masses (in Da), chemical symbols, atom counts
   • Lattice basis vectors (in Angstrom)

3. [system_parameters] or [ground_state_parameters]/[excited_state_parameters]

   • Geometry files (vasprun.xml or CSV)
   • Spin-orbit coupling from DFT (λ_DFT) in meV
   • Orbital reduction factor (g_L)
   • Energies from DFT (in eV)

4. [magnetic_field] - Optional

   • Field strength range and direction

Common Parameters:

• maximum_number_of_vibrational_quanta: Size of vibrational basis (typically 10-15)
• orbital_basis_states: 'real' or 'complex' - basis representation
• orbital_reduction_factor (gL): Typically 0-1, accounts for covalency
• DFT_spin-orbit_coupling: Spin-orbit coupling from DFT (in meV, negative for holes)

1. Single Case Calculation (vasprun.xml input)

Purpose: Calculate Jahn-Teller dynamics for a single state using vasprun.xml files.

Key sections:

• [essentials]: Basic settings and output options
• [system_parameters]: Geometry files (vasprun.xml), spin-orbit coupling, orbital reduction factor
• [magnetic_field]: Optional magnetic field parameters

See: SnV_gnd_vasprunxml.cfg in config_files/ for a complete example.

Output: The program calculates and displays:

• Jahn-Teller energy (E_JT), barrier energy (δ), Taylor coefficients (F, G)
• Ham reduction factor (p), theoretical energy splitting (λ_theory)
• Saves eigenenergies, eigenstates, and magnetic field dependence (if specified)

2. ZPL (Zero Phonon Line) Shift Calculation

Purpose: Calculate zero phonon line shift in magnetic field for transitions between ground and excited states.

Key sections:

• [essentials]: Must include basis vectors for E⊗e coordinate system
• [ground_state_parameters]: Ground state geometries, SOC, gL
• [excited_state_parameters]: Excited state geometries, SOC, gL
• [magnetic_field]: Magnetic field parameters

See: SnV_ZPL_shift_vasprunxml.cfg or SnV_ZPL_shift_csv.cfg in config_files/ for complete examples.

3. Using CSV Geometry Files

Purpose: Use previously saved CSV geometry files instead of vasprun.xml files.

Key difference: Requires [atom_structure_parameters] section with atomic masses (in Da), chemical symbols, and lattice basis vectors.

Note: When save_raw_parameters = true, the program automatically saves geometries as CSV files and creates a configuration file with all structural parameters.

See: SnV_gnd_csv.cfg or SnV_ZPL_shift_csv.cfg in config_files/ for complete examples.

4. Direct Jahn-Teller Parameter Input

Purpose: Specify Jahn-Teller parameters directly (E_JT, δ, ℏω) instead of using geometry files.

Key parameters:

• Jahn-Teller_energy (E_JT) - in meV
• barrier_energy (δ) - in meV
• vibrational_energy_quantum (ℏω) - in meV
• Distances between geometries - in Å√(Da)

See: SnV_gnd_JT_pars.cfg or SnV_ZPL_shift_JT_pars.cfg in config_files/ for complete examples.

5. Four-State Model Hamiltonian

Purpose: Use a simplified four-state model Hamiltonian (faster than full dynamic Jahn-Teller calculation).

Key parameters:

• spin-orbit_splitting_energy (λ) - in meV
• orbital_reduction_factor (gL)
• f and delta_f - model Hamiltonian parameters

Note: When save_model_hamiltonian_cfg = true, the code saves model config files without the model_hamiltonian option. These saved files contain only the model parameters and can be used directly.

See: SnV_gnd_model.cfg or SnV_ZPL_shift_model.cfg in config_files/ for complete examples.

Output Options

The tool can generate various output files based on configuration:

• save_raw_parameters = true: Saves geometries in CSV format and generates the corresponding configuration file with atomic parameters such as chemical symbol, mass, basis vector of the supercell.
• save_model_hamiltonian_cfg = true: Generates four state model Hamiltonian configuration
• save_taylor_coeffs_cfg = true: Saves .cfg files that contains Taylor coefficients for the dynamic Jahn-Teller interaction

Eigenstates

The script can save eigenstates using real or complex basis to represent the orbital states:

• Complex basis (e₊, e_-): Superpositions of degenerate orbitals (e_x, e_y)
  • e₊ = -(e_x+ie_y)
  • e_- = e_x-ie_y

To use complex eigenstates, set:

orbital_basis_states = complex

Directory Structure

Jahn-Teller-Dynamics/
├── src/
│   └── jahn_teller_dynamics/          # Main package
│       ├── __init__.py
│       ├── Exe.py                     # Main executable script
│       ├── io/                        # Input/Output modules
│       │   ├── __init__.py
│       │   ├── config/                # Configuration parsing
│       │   │   ├── __init__.py
│       │   │   ├── parser.py          # Main config parser
│       │   │   ├── reader.py          # File reading utilities
│       │   │   ├── writer.py          # Config file writing
│       │   │   ├── constants.py       # Configuration constants
│       │   │   ├── atom_parser.py     # Atomic structure parsing
│       │   │   ├── field_parser.py    # Field vector parsing
│       │   │   ├── parameter_extractor.py  # Parameter extraction
│       │   │   └── section_detector.py    # Section type detection
│       │   ├── file_io/               # File I/O operations
│       │   │   ├── __init__.py
│       │   │   ├── csv_writer.py     # CSV output handling
│       │   │   ├── results_formatter.py  # Results formatting
│       │   │   ├── vasp.py            # VASP file handling
│       │   │   └── xml_parser.py      # XML parsing
│       │   ├── theory/                # Theory building and calculations
│       │   │   ├── __init__.py
│       │   │   ├── builder.py         # Theory builder
│       │   │   └── calculator.py      # Calculation helper
│       │   ├── workflow/              # Workflow orchestration
│       │   │   ├── __init__.py
│       │   │   └── orchestrator.py    # Main orchestrator
│       │   ├── utils/                 # I/O utilities
│       │   │   ├── __init__.py
│       │   │   ├── file_utils.py      # File utility functions
│       │   │   └── path_manager.py    # Path management
│       │   └── visualization/         # Plotting and visualization
│       │       ├── __init__.py
│       │       └── plotter.py         # Plotting functionality
│       ├── math/                      # Mathematical utilities
│       │   ├── __init__.py
│       │   ├── matrix_mechanics.py    # Matrix operators, eigenstates
│       │   ├── eigen_solver.py        # Eigenvalue/eigenvector solvers
│       │   ├── braket_formalism.py    # Bra-ket notation
│       │   └── maths.py              # Math utilities
│       ├── physics/                   # Physics modules
│       │   ├── __init__.py
│       │   ├── jahn_teller_theory.py  # JT theory calculations
│       │   ├── quantum_physics.py     # Main execution tree (Exe_tree)
│       │   ├── quantum_system.py      # Quantum system tree structure
│       │   ├── constants.py           # Physical constants
│       │   ├── hamiltonians/          # Hamiltonian construction
│       │   │   ├── __init__.py
│       │   │   ├── djt_hamiltonian.py      # DJT Hamiltonians
│       │   │   ├── spin_orbit.py           # Spin-orbit coupling
│       │   │   └── field_interactions.py   # Field interactions
│       │   ├── models/                # Model building
│       │   │   ├── __init__.py
│       │   │   ├── system_builder.py       # System tree construction
│       │   │   ├── reduction_factors.py    # Reduction factor calculations
│       │   │   └── operator_manager.py     # Operator management
│       │   └── numerics/              # Numerical calculations
│       │       ├── __init__.py
│       │       └── observables.py          # Observable calculations
├── config_files/                      # Example configuration files
│   ├── SnV_gnd_csv.cfg
│   ├── SnV_ZPL_shift_csv.cfg
│   ├── SnV_gnd_model.cfg
│   └── ... (other config examples)
├── data/                             # Data directory (user-provided)
├── results/                          # Output results directory (user-provided)
├── requirements.txt                  # Python dependencies
├── setup.py                          # Package installation script
└── README.md                         # This file

Key Components:

• src/jahn_teller_dynamics/: Main package containing all Python modules
• io/: Input/Output modules organized by functionality:
  • config/: Configuration file parsing and writing (parser, reader, writer, field/atom parsers, parameter extraction)
  • file_io/: File I/O operations (CSV, VASP, XML, results formatting)
  • theory/: Theory building and calculation helpers
  • workflow/: Workflow orchestration
  • utils/: I/O utility functions (file utilities, path management)
  • visualization/: Plotting and visualization
• math/: Mathematical utilities for braket formalism, matrix mechanics, and Hilbert spaces:
  • matrix_mechanics.py: Matrix operators, ket/bra vectors, Hilbert space bases
  • eigen_solver.py: Extensible eigenvalue/eigenvector solver framework (supports dense matrices, extensible for sparse)
  • braket_formalism.py: Bra-ket notation implementation
  • maths.py: Core mathematical operations and matrix utilities
• physics/: Core physics modules organized by functionality:
  • Core modules: Jahn-Teller theory, quantum physics, quantum systems
  • hamiltonians/: Hamiltonian construction (DJT, spin-orbit, fields)
  • models/: Model building (system construction, reduction factors, operators)
  • numerics/: Numerical calculations (observables, transitions)
• config_files/: Example configuration files for different calculation types
• data/: Directory for user input data (VASP files, CSV files, etc.)
• results/: Output directory for calculation results