Metadata-Version: 2.4
Name: diffpes
Version: 2026.6.3
Summary: Differentiable ARPES simulations in JAX
Keywords: ARPES,MBE,JAX,Differentiable Programming
Author: Debangshu Mukherjee, Jacob Cook
Author-email: Debangshu Mukherjee <mukherjeed@ornl.gov>, Jacob Cook <cookjl2@ornl.gov>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Dist: numpy>=2.2.1
Requires-Dist: matplotlib>=3.10.0
Requires-Dist: jax>=0.7.0
Requires-Dist: jaxtyping>=0.3.0
Requires-Dist: chex>=0.1.85
Requires-Dist: beartype>=0.21.0
Requires-Dist: jupyter>=1.1.1
Requires-Dist: ipykernel>=7.2.0
Requires-Dist: h5py>=3.15.1
Requires-Dist: equinox>=0.13.8
Requires-Dist: optimistix>=0.1.0
Requires-Dist: optax>=0.2.8
Requires-Dist: lineax>=0.1.0
Requires-Dist: diffpes[docs,test,dev,notebooks,cuda] ; extra == 'all'
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: diffpes[docs,test,notebooks] ; extra == 'dev'
Requires-Dist: ruff>=0.12.9 ; extra == 'dev'
Requires-Dist: pygount>=3.1.0 ; extra == 'dev'
Requires-Dist: pre-commit>=4.5.1 ; extra == 'dev'
Requires-Dist: ty>=0.0.19 ; extra == 'dev'
Requires-Dist: diffpes[dev,cuda] ; extra == 'dev-cuda'
Requires-Dist: sphinx>=7.0.0 ; extra == 'docs'
Requires-Dist: sphinx-rtd-theme>=3.0.2 ; extra == 'docs'
Requires-Dist: nbsphinx>=0.9.7 ; extra == 'docs'
Requires-Dist: myst-parser>=2.0.0 ; extra == 'docs'
Requires-Dist: myst-nb>=1.1.0 ; extra == 'docs'
Requires-Dist: ipykernel>=6.29.5 ; extra == 'docs'
Requires-Dist: nbconvert>=7.16.6 ; extra == 'docs'
Requires-Dist: furo>=2025.7.19 ; extra == 'docs'
Requires-Dist: sphinx-autodoc-typehints>=3.0.1 ; extra == 'docs'
Requires-Dist: numpydoc>=1.9.0 ; extra == 'docs'
Requires-Dist: pydoclint>=0.7.3 ; extra == 'docs'
Requires-Dist: interrogate>=1.7.0 ; 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>=6.0.0 ; extra == 'test'
Requires-Dist: pytest-xdist>=3.0.0 ; extra == 'test'
Requires-Dist: chex>=0.1.89 ; extra == 'test'
Requires-Dist: psutil>=5.9 ; extra == 'test'
Requires-Dist: hypothesis>=6.100 ; extra == 'test'
Requires-Dist: mpmath>=1.3.0 ; extra == 'test'
Requires-Dist: scipy>=1.15.0 ; extra == 'test'
Maintainer: Debangshu Mukherjee
Maintainer-email: Debangshu Mukherjee <mukherjeed@ornl.gov>
Requires-Python: >=3.12, <3.15
Provides-Extra: all
Provides-Extra: cuda
Provides-Extra: dev
Provides-Extra: dev-cuda
Provides-Extra: docs
Provides-Extra: notebooks
Provides-Extra: test
Description-Content-Type: text/markdown

# diffpes

[![License](https://img.shields.io/pypi/l/diffpes.svg)](https://github.com/debangshu-mukherjee/diffpes/blob/main/LICENSE)
[![PyPI Downloads](https://static.pepy.tech/badge/diffpes)](https://pepy.tech/projects/diffpes)
[![PyPI version](https://img.shields.io/pypi/v/diffpes.svg)](https://pypi.python.org/pypi/diffpes)
[![Python Versions](https://img.shields.io/pypi/pyversions/diffpes.svg)](https://pypi.python.org/pypi/diffpes)
[![Documentation Status](https://readthedocs.org/projects/diffpes/badge/?version=latest)](https://diffpes.readthedocs.io/en/latest/?badge=latest)
[![tests](https://github.com/debangshu-mukherjee/diffpes/actions/workflows/tests.yml/badge.svg)](https://github.com/debangshu-mukherjee/diffpes/actions/workflows/tests.yml)
[![codecov](https://codecov.io/gh/debangshu-mukherjee/diffpes/graph/badge.svg)](https://codecov.io/gh/debangshu-mukherjee/diffpes)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19037631.svg)](https://doi.org/10.5281/zenodo.19037631)
[![Ruff](https://img.shields.io/badge/lint%20and%20format-ruff-D7FF64?logo=ruff&logoColor=1D1D1D)](https://github.com/astral-sh/ruff)
[![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)
[![jax_badge](https://tinyurl.com/mucknrvu)](https://docs.jax.dev/)
[![Lines of Code](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/debangshu-mukherjee/diffpes/main/.github/badges/loc.json)](https://github.com/debangshu-mukherjee/diffpes)

diffpes is a JAX-based ARPES simulation toolkit with Python-native APIs and
certified forward execution. A certified run stores its observable and
scientific evidence in the same differentiable PyTree. The evidence includes
bounded physics claims, provenance, domain margins, derivatives, local
information-flow diagnostics, and a named assurance policy. JAX compiles and
batches the numerical certification path. Portable serialization stays at the
filesystem boundary.

Certification here means bounded scientific evidence, not a security
credential. Storage consistency markers detect accidental mismatches only.

## Expanded-input workflows

The package provides expanded-input wrappers for plain arrays and scalars.
These wrappers run the same JAX kernels as the typed interfaces.

### Function mapping

- `ARPES_simulation_Novice` -> `diffpes.simul.simulate_novice_expanded`
- `ARPES_simulation_Basic` -> `diffpes.simul.simulate_basic_expanded`
- `ARPES_simulation_Basicplus` -> `diffpes.simul.simulate_basicplus_expanded`
- `ARPES_simulation_Advanced` -> `diffpes.simul.simulate_advanced_expanded`
- `ARPES_simulation_Expert` -> `diffpes.simul.simulate_expert_expanded`
- `ARPES_simulation_SOC` -> `diffpes.simul.simulate_soc_expanded`
- Dynamic dispatch by level -> `diffpes.simul.simulate_expanded`
  (use `level="soc"` with `surface_spin` for SOC)

### Notes

- Default energy-axis padding behavior:
  `min(eigenbands)-1` to `max(eigenbands)+1`.
- Expanded wrappers interpret incident angles in degrees.
- Wrappers return the standard `ArpesSpectrum` PyTree.

### Python indexing conventions

Use standard Python/NumPy indexing everywhere (zero-based, end-exclusive).

- Non-s orbitals: `slice(1, 9)` -> indices 1..8
- p orbitals: `slice(1, 4)` -> indices 1..3
- d orbitals: `slice(4, 9)` -> indices 4..8

Do not use MATLAB-style indexing notation in Python code.

### Example

```python
import jax.numpy as jnp

from diffpes.simul import simulate_expanded

# [nkpt, nband]
eigenbands = jnp.linspace(-2.0, 0.5, 100).reshape(20, 5)
# [nkpt, nband, natom, 9]
surface_orb = jnp.ones((20, 5, 2, 9)) * 0.1

spectrum = simulate_expanded(
    level="advanced",
    eigenbands=eigenbands,
    surface_orb=surface_orb,
    ef=0.0,
    sigma=0.04,
    fidelity=2500,
    temperature=15.0,
    photon_energy=11.0,
    polarization="unpolarized",
    incident_theta=45.0,
    incident_phi=0.0,
    polarization_angle=0.0,
)
```

## Test coverage

Test coverage identifies the source lines that the tests execute. Run the
coverage check with this command:

```bash
source .venv/bin/activate
pytest tests/ --cov=src/diffpes --cov-report=term-missing
```

Use these priorities to increase coverage toward 100%:

1. **Simulation and types:** These modules already have good coverage.
   Add a test for each new polarization or dispatch branch.
2. **Expanded dispatch:** Test every `simulate_expanded(level=...)` branch.
   Also test the `ValueError` for an unknown level.
3. **HDF5:** Round-trip every PyTree type. Test each load and save error path.
4. **VASP file readers:** Test `read_doscar`, `read_eigenval`, `read_kpoints`,
   `read_poscar`, and `read_procar` with minimal repository fixtures.
5. **Plotting:** Exercise the public plotting API in tests. GUI code can use a
   lower coverage target.
6. **Edge branches:** Cover optional arguments and their error messages.
   Include `make_band_structure(..., kpoint_weights=...)`.
