jahn-teller-dynamics 1.6.0

Dynamic Jahn-Teller Effect Calculator

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

Table of Contents

• About the Project
• Installation
• Usage
• jtd_run Configuration Examples
• Exe 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

jtd_run configuration examples

Run

jtd_run --config configuration_file.cfg

command to perform calculation with jtd_run

This section provides and introduction to the configuration files of jtd_run. You can find .cfg and .csv files for testing in jtd_run_demo folder

The structure of the .cfg files is the following

1. [essentials] - Always first section

   • input folder path
   • output folder path
   • use_sparse

2. [model] – Defines model-specific inputs and settings for the Jahn-Teller system:

   • Specify file names for electron_energies (electronic state energies)
   • modes (names of vibrational modes and energy of vibrational quantum),
   • coupling (electron-phonon coupling constants between electron states).
   • Vibrational coordinate options: Set dimensionless_coordinates to use either physical or dimensionless vibrational coordinates; null_point_vib determines whether to include null point phonon vibrations
   • Phonon basis truncation: Control how the vibrational basis is truncated, either by total phonon number, energy cutoff, per-mode occupation caps, or by reading mode-specific caps from the modes CSV.

3. [eigensolver] — Diagonalization backend and spectral options for the Hamiltonian (SciPy Lanczos / ARPACK or SLEPc on MPI clusters).

4. [builder] - In case of huge Hamiltonian operators building time can take so long, that it worth using parallel oprator building method that can be specified by

   • lined_coupling_batches Split coupling rows into memory waves; cache cleared between waves
   • lined_coupling_workers Worker processes per wave

Eigensolver Options

The eigensolver diagonalizes the assembled Hamiltonian and writes eigenvalues/eigenvectors. Options below go in the [eigensolver] section (some I/O keys such as separator, save_csv, and save_npz may also appear in [essentials]).

Backend and spectrum size:

• solver Diagonalization backend:
  • Sparse / SciPy Lanczos: scipy, (uses scipy.sparse.linalg.eigsh)
  • Dense: dense (full or partial spectrum via dense solvers)
  • MPI / PETSc: slepc (requires PETSc/SLEPc)
• num_eigs — Number of eigenpairs to compute; use all for the full spectrum (dense backend).

Spectral selection (sparse / SLEPc):

• spectral_which (alias: which) — Which eigenvalues to target, e.g. smallest_real, largest_real, nearest, or SciPy tokens SA, LA, LM, …
• sigma (aliases: shift, target, spectral_sigma) — Shift–invert target for interior eigenvalues (used with spectral_which = nearest or LM).
• mode — Shift–invert mode when sigma is set: normal, buckling, or cayley.

Convergence knobs (sparse eigsh and SLEPc):

• tol — Convergence tolerance (default ~1e-10 for SciPy sparse).
• max_iter (alias: maxiter) — Maximum Lanczos iterations.
• ncv — Krylov subspace size (must be larger than num_eigs).

Output:

• return_eigenvectors — true / false (default true).
• save_csv, save_npz — Write eigenvalues/eigenvectors to CSV and/or NPZ.
• separator — Field separator for saved CSV results.

Other:

• use_block_diagonalization — Use block structure in the sparse solver (default true).
• require_hermitian (alias: allow_non_hermitian when set to false) — If false, allow non-Hermitian H and use general eigen solvers (eigs / SLEPc NHEP) instead of aborting.

Example settings

Option	Example	Description
SciPy sparse	solver = scipy, num_eigs = 10	Lowest 10 eigenpairs via Lanczos
Shift–invert	solver = scipy, sigma = 0.5, spectral_which = nearest	Eigenvalues near a target

See jtd_run_demo/butatrien_cation/butatrien_cation.cfg and jtd_run_demo/methoxy_radical/methoxy_radical.cfg for commented examples.

Phonon Basis Options

The phonon basis determines how vibrational (phonon) states are represented and truncated in the quantum model. Different choices affect both the accuracy and computational cost of the Jahn-Teller calculations. You can control the phonon basis using the following options and keywords within the [model] section of the .cfg configuration file.

Available phonon basis truncation methods:

• Total phonon number cutoff:
  Limits the sum of occupation numbers across all modes:

  maximum_number_of_vibrational_quanta = N
  

  Only basis states where the total number of vibrational excitations (summed across all modes) does not exceed N are included.

• Energy cutoff:
  Limits basis states by allowed vibrational energy:

  phonon_encut = <energy_threshold>
  

  Only basis states with a total vibrational energy (sum of n_i * e_i for each mode i, with e_i as the mode energy) below the given threshold are included.

• Per-mode maximum occupation:
  Restricts each phonon mode i to have at most maximum_number_of_quanta_per_dim quanta:

  maximum_number_of_quanta_per_dim = N
  

  All states where n_i ≤ N for every mode are included (may generate a much larger basis than the total sum cutoff).

• Mode-specific occupancy caps:
  Allows the maximum for each mode to be set individually (read from the modes.csv file):

  use_maximum_quanta_from_modes_csv = true
  

  Each mode's maximum occupation is taken from a maximum_quanta column in the modes.csv file.

Additional basis options:

• dimensionless_coordinates: Set true to use dimensionless vibrational coordinates (typical in theoretical models); set false to use physical units.
• null_point_vib: Set true to shift coordinate origin to the minimum of the Adiabatic Potential Energy Surface (APES); false leaves the origin at the undistorted point.

Example Basis Selection

Method	Example setting	Description
Total number cutoff	maximum_number_of_vibrational_quanta = 2	Basis states with total phonon number ≤ 2
Energy cutoff	phonon_encut = 0.025	Basis states with total vibronic energy ≤ 0.025
Per-mode cutoff	maximum_number_of_quanta_per_dim = 4	Each mode has ≤ 4 quanta, total unrestricted
Mode-specific	use_maximum_quanta_from_modes_csv = true	Each mode's cap taken from modes.csv

Choosing the truncation method and cutoff depends on computational resources and the physical details of the system. Tighter cutoffs are faster but may miss important contributions; looser cutoffs increase accuracy but require more memory and longer computation times.

Exe.py Configuration Examples

Test Data for Exe.py

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

This section provides an introduction to configuration files of Exe.py. 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