Metadata-Version: 2.4
Name: jahn_teller_dynamics
Version: 1.6.0
Summary: Dynamic Jahn-Teller Effect Calculator
Home-page: https://github.com/tbalu98/Jahn-Teller-Dynamics
Author: Balázs Tóth
Author-email: toth.balazs@wigner.hun-ren.hu
License: GPLv3
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: contourpy==1.3.3
Requires-Dist: cycler==0.12.1
Requires-Dist: e==1.4.5
Requires-Dist: fonttools==4.62.1
Requires-Dist: iniconfig==2.3.0
Requires-Dist: kiwisolver==1.5.0
Requires-Dist: matplotlib==3.10.9
Requires-Dist: memory-profiler==0.61.0
Requires-Dist: networkx==3.6.1
Requires-Dist: numpy==2.4.4
Requires-Dist: packaging==26.0
Requires-Dist: pandas==3.0.2
Requires-Dist: pillow==12.2.0
Requires-Dist: pluggy==1.6.0
Requires-Dist: psutil==7.2.2
Requires-Dist: Pygments==2.20.0
Requires-Dist: pyparsing==3.3.2
Requires-Dist: pytest==9.0.3
Requires-Dist: python-dateutil==2.9.0.post0
Requires-Dist: pytz==2026.1.post1
Requires-Dist: scipy==1.17.1
Requires-Dist: six==1.17.0
Requires-Dist: tzdata==2026.2
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

﻿# Jahn-Teller-Dynamics - Dynamic Jahn-Teller Effect Calculator


[![Python 3.10](https://img.shields.io/badge/python-3.10-blue.svg)](https://www.python.org/downloads/release/python-3100/)
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![Email](https://img.shields.io/badge/Email-toth.balazs%40wigner.hun--ren.hu-blue)](mailto:toth.balazs@wigner.hun-ren.hu)




## Table of Contents

- [About the Project](#about-the-project)
- [Installation](#installation)
- [Usage](#usage)
- [jtd_run Configuration Examples](#jtd_run-configuration-examples#)
- [Exe Configuration Examples](#exe-configuration-examples)
- [Output Options](#output-options)
- [Eigenstates](#eigenstates)


<a id="about-the-project"></a>
## 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.

<a id="installation"></a>
## Installation



### Installation directly from PyPI:

```
pip install jahn-teller-dynamics
```
### Installation from Github


1. Download the project:
   ```bash
   git clone https://github.com/tbalu98/Jahn-Teller-Dynamics.git
   ```
   or download the [zip file](https://github.com/tbalu98/Jahn-Teller-Dynamics/archive/refs/heads/main.zip)

2. Install dependencies:
   ```bash
   pip3 install -r requirements.txt
   ```




<a id="usage"></a>
## 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:

```bash
Exe configuration_file.cfg
```




<a id="jtd_run-configuration-examples"></a>
## `jtd_run` configuration examples

Run
```bash
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.



<a id="exe-configuration-examples"></a>
## `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](https://drive.google.com/drive/folders/1_L-j08JW8fuGhRihFijjS_vfALAPvC43?usp=sharing)

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.

<a id="output-options"></a>
## 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

<a id="eigenstates"></a>
## Eigenstates

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

- Complex basis (e<sub>+</sub>, e<sub>-</sub>): Superpositions of degenerate orbitals (e<sub>x</sub>, e<sub>y</sub>)
  - e<sub>+</sub> = -(e<sub>x</sub>+ie<sub>y</sub>)
  - e<sub>-</sub> = e<sub>x</sub>-ie<sub>y</sub>

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
