Metadata-Version: 2.3
Name: difftb
Version: 2025.12.16
Summary: Differentiable Density Functional Tight Binding in JAX
Keywords: tight-binding,DFTB,electronic-structure,JAX,automatic-differentiation,materials-science,inverse-problems,ARPES
Author: Debangshu Mukherjee
Author-email: Debangshu Mukherjee <mukherjeed@ornl.gov>
License: MIT License
         
         Copyright (c) 2025 Debangshu Mukherjee, Oak Ridge National Laboratory
         
         Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Dist: numpy>=1.13.0
Requires-Dist: scipy>=1.0.0
Requires-Dist: matplotlib>=2.2.0
Requires-Dist: matplotlib-scalebar>=0.5.0
Requires-Dist: cmocean>=4.0.3
Requires-Dist: tqdm>=4.66.0
Requires-Dist: jaxtyping>0.3.2
Requires-Dist: chex>=0.1.85
Requires-Dist: optax>=0.1.8
Requires-Dist: pytest>=8.0.0
Requires-Dist: jax>=0.7.0 ; sys_platform == 'win64'
Requires-Dist: jax>=0.7.0 ; sys_platform == 'darwin'
Requires-Dist: jax>=0.7.0 ; sys_platform == 'linux'
Requires-Dist: pytest-cov>=6.2.1
Requires-Dist: jupyterlab>=4.4.5
Requires-Dist: jupyter>=1.1.1
Requires-Dist: ipykernel>=6.29.5
Requires-Dist: black[jupyter]>=25.1.0
Requires-Dist: beartype>=0.21.0
Requires-Dist: jax[cuda12]>=0.7.0 ; platform_machine == 'x86_64' and sys_platform == 'linux' and extra == 'cuda'
Requires-Dist: nvidia-cudnn-cu12>=9.5.0 ; platform_machine == 'x86_64' and sys_platform == 'linux' and extra == 'cuda'
Requires-Dist: difftb[docs,notebooks,test] ; extra == 'dev'
Requires-Dist: black>=25.1.0 ; extra == 'dev'
Requires-Dist: ipykernel>=6.29.5 ; extra == 'dev'
Requires-Dist: isort>=6.0.1 ; extra == 'dev'
Requires-Dist: myst-parser>=4.0.1 ; extra == 'dev'
Requires-Dist: nbsphinx>=0.9.6 ; extra == 'dev'
Requires-Dist: pydata-sphinx-theme>=0.16.1 ; extra == 'dev'
Requires-Dist: ruff>=0.12.9 ; extra == 'dev'
Requires-Dist: sphinx>=8.1.3 ; extra == 'dev'
Requires-Dist: sphinx-rtd-theme>=3.0.2 ; extra == 'dev'
Requires-Dist: sphinxcontrib-napoleon>=0.7 ; extra == 'dev'
Requires-Dist: twine>=6.1.0 ; extra == 'dev'
Requires-Dist: difftb[cuda,dev] ; extra == 'dev-cuda'
Requires-Dist: furo>=2025.7.19 ; extra == 'docs'
Requires-Dist: ipykernel>=6.29.5 ; extra == 'docs'
Requires-Dist: myst-parser>=4.0.1 ; extra == 'docs'
Requires-Dist: nbsphinx>=0.9.6 ; extra == 'docs'
Requires-Dist: pydata-sphinx-theme>=0.16.1 ; extra == 'docs'
Requires-Dist: sphinx>=8.1.3 ; extra == 'docs'
Requires-Dist: sphinx-autodoc-typehints>=3.0.1 ; extra == 'docs'
Requires-Dist: sphinx-rtd-theme>=3.0.2 ; extra == 'docs'
Requires-Dist: sphinxcontrib-napoleon>=0.7 ; extra == 'docs'
Requires-Dist: pydoclint>=0.7.3 ; extra == 'docs'
Requires-Dist: interrogate>=1.7.0 ; extra == 'docs'
Requires-Dist: pandoc>=2.4 ; extra == 'docs'
Requires-Dist: ipywidgets>=8.1.0 ; extra == 'notebooks'
Requires-Dist: ipykernel>=6.29.5 ; extra == 'notebooks'
Requires-Dist: nbconvert>=7.16.6 ; extra == 'notebooks'
Requires-Dist: pytest>=8.3.5 ; extra == 'test'
Requires-Dist: pytest-cov>=4.0.0 ; extra == 'test'
Requires-Dist: pytest-xdist>=3.0.0 ; extra == 'test'
Requires-Dist: chex>=0.1.89 ; extra == 'test'
Maintainer: Debangshu Mukherjee
Maintainer-email: Debangshu Mukherjee <mukherjeed@ornl.gov>
Requires-Python: >=3.11, <3.14
Project-URL: Homepage, https://github.com/debangshu-mukherjee/difftb
Provides-Extra: cuda
Provides-Extra: dev
Provides-Extra: dev-cuda
Provides-Extra: docs
Provides-Extra: notebooks
Provides-Extra: test
Description-Content-Type: text/markdown

# DiffTB: Differentiable Density Functional Tight Binding

A JAX-based implementation of DFTB with automatic differentiation support, enabling gradient-based optimization of Slater-Koster parameters against experimental data.

## Features

- **Fully Differentiable**: Built on JAX for automatic differentiation through all calculations
- **Spin Polarization**: Support for magnetic systems with collinear spin
- **Spin-Orbit Coupling**: On-site L·S coupling for heavy elements (Bi, Te, etc.)
- **Periodic Systems**: k-space Hamiltonian construction with Brillouin zone sampling
- **Inverse Problems**: Tools for fitting SK parameters to experimental ARPES data

## Installation

```bash
pip install difftb
```

For development:
```bash
git clone https://github.com/debangshu-ornl/difftb.git
cd difftb
pip install -e ".[dev]"
```

## Quick Start

```python
import jax.numpy as jnp
from difftb import (
    CrystalStructure,
    SlaterKosterParams,
    compute_bands,
    BrillouinZone,
)
from difftb.io.structure import bi2te3_structure
from difftb.io.slater_koster import create_test_sk_params

# Load structure
structure = bi2te3_structure()

# Create SK parameters (use create_test_sk_params for testing)
sk_params = create_test_sk_params(['Bi', 'Te'])

# Define k-path
from difftb.core.lattice import Lattice, hexagonal_path

lattice = Lattice.from_vectors(
    structure.lattice_vectors[0],
    structure.lattice_vectors[1],
    structure.lattice_vectors[2]
)
bz = BrillouinZone.from_path(lattice, hexagonal_path(), num_points=100)

# Compute band structure
# (Full example requires Hamiltonian construction - see examples/)
```

## Core Components

### Slater-Koster Tables
```python
from difftb.io.slater_koster import SlaterKosterTable, interpolate_sk_integrals

# Interpolation is differentiable!
H_sk, S_sk = interpolate_sk_integrals(distances, sk_table)
```

### Spin-Orbit Coupling
```python
from difftb.physics.soc import build_spinor_hamiltonian, get_soc_params

soc_params = get_soc_params(['Bi', 'Te'])  # Uses tabulated ξ values
H_soc, S_soc = build_spinor_hamiltonian(H, S, elements, soc_params, orbital_info)
```

### Parameter Fitting
```python
from difftb.utils.optimization import fit_parameters, hierarchical_fit

# Define loss function (e.g., MSE to experimental ARPES)
def loss_fn(params):
    # Compute predicted spectrum
    # Compare to experiment
    return mse

# Fit parameters
result = fit_parameters(loss_fn, initial_params, max_iterations=1000)

# Hierarchical fitting for transferability
final_params, results = hierarchical_fit(
    loss_fn,
    param_groups=[bi_te_params, mn_params],
    group_names=['Bi-Te', 'Mn']
)
```

## Acknowledgments

DiffTB builds on ideas from:
- [Jrystal](https://github.com/sail-sg/jrystal) - JAX-based DFT
- [dxtb](https://github.com/grimme-lab/dxtb) - Differentiable xTB
- [DFTB+](https://dftbplus.org/) - Reference DFTB implementation
