Metadata-Version: 2.4
Name: unfolding
Version: 0.3.0
Summary: Bloch wave unfolding
Author-email: Xu He <mailhexu@gmail.com>
License: BSD-2-Clause
Project-URL: Homepage, https://github.com/mailhexu/unfolding
Project-URL: Documentation, https://mailhexu.github.io/unfolding/
Project-URL: Issues, https://github.com/mailhexu/unfolding/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: matplotlib
Requires-Dist: ase
Requires-Dist: tomli; python_version < "3.11"
Provides-Extra: phonopy
Requires-Dist: phonopy; extra == "phonopy"
Provides-Extra: abipy
Requires-Dist: abipy; extra == "abipy"
Provides-Extra: abinit
Requires-Dist: HamiltonIO>=0.3.8; extra == "abinit"
Requires-Dist: netCDF4; extra == "abinit"
Provides-Extra: siesta
Requires-Dist: HamiltonIO[siesta]>=0.3.8; extra == "siesta"
Provides-Extra: tb2j
Requires-Dist: TB2J; extra == "tb2j"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: sympy; extra == "dev"
Dynamic: license-file

# Unfolding

[![GitHub Pages](https://github.com/mailhexu/unfolding/actions/workflows/gh-pages.yml/badge.svg)](https://mailhexu.github.io/unfolding/)
[![License](https://img.shields.io/badge/License-BSD_2--Clause-blue.svg)](https://opensource.org/licenses/BSD-2-Clause)

A Python utility to unfold band structures of quasi-particles (electrons, phonons, magnons, etc.) from supercell calculations into the primitive cell representation. This is particularly useful for visualizing and analyzing the effects of defects, disorder, or complex magnetic order on the electronic or vibrational properties of materials.

## Features

- Unfold phonon band structures from **Phonopy** calculations.
- Unfold phonon band structures from **Abinit** DDB files.
- A simple and intuitive API (`phonopy_unfold` is the main entry point; the core weights come from `unfolding.phonon_unfolder.phonon_unfolder`).
- Integration with popular materials science libraries like [ASE](https://wiki.fysik.dtu.dk/ase/) and [Matplotlib](https://matplotlib.org/).

> Note: the legacy generic class `unfolding.unfolder.Unfolder` is deprecated
> in favor of `unfolding.phonon_unfolder.phonon_unfolder` (phonons) and
> `unfolding.wannier_unfold.WannierUnfolder` (electrons).

## Installation

You can install `unfolding` via pip:

```bash
pip install unfolding
```

Or, for the latest development version, you can install directly from the source:

```bash
git clone https://github.com/mailhexu/unfolding.git
cd unfolding
pip install .
```

## Usage

The [example gallery](https://mailhexu.github.io/unfolding/examples/)
provides downloadable input bundles. After unpacking one, run either
the unified CLI or the same TOML file through Python:

```bash
unfolding --config unfold.toml
```

```python
from unfolding import load_config, run
run(load_config("unfold.toml"))
```

`unfolding <route> --help` lists explicit flags for that route.
The CLI takes either all flags or `--config unfold.toml` as its sole
parameter; each example page documents its structures, k-path, and
route parameters.

Here is a simple example of how to unfold the phonon band structure of a 3x3x3 FCC Cu supercell to the primitive cell, using data from a Phonopy calculation.

```python
import numpy as np
from ase.dft.kpoints import get_special_points, bandpath
import matplotlib.pyplot as plt
from unfolding.phonopy_unfolder import phonopy_unfold

# 1. Define the k-path for the primitive cell
from ase.build import bulk
atoms = bulk('Cu', 'fcc', a=3.61)
points = get_special_points('fcc', atoms.cell, eps=0.01)
path_highsym = [points[k] for k in 'GXWGL']
kpts, x, X = bandpath(path_highsym, atoms.cell, 300)
names = [r'$\Gamma$', r'X', r'W', r'$\Gamma$', r'L']

# 2. Perform the unfolding
ax = phonopy_unfold(
    sc_mat=np.diag([1, 1, 1]),  # Supercell matrix for phonopy
    unfold_sc_mat=np.diag([3, 3, 3]),  # Supercell matrix for unfolding
    force_constants='FORCE_CONSTANTS',  # Path to FORCE_CONSTANTS file
    sposcar='SPOSCAR',  # Path to SPOSCAR file
    qpts=kpts,  # q-points in the primitive cell
    qnames=names,  # Names of high-symmetry q-points
    xqpts=x,  # x-axis for the q-path
    Xqpts=X  # x-axis for high-symmetry q-points
)

# 3. Plot and save the result
plt.savefig('unfolded_band_structure.png', dpi=300)
plt.show()
```

This will produce the following unfolded band structure plot:

![Phonopy Unfolded Band Structure](docs/static/images/phonopy_unfolded_band_structure.png)

## Documentation

For more detailed information, tutorials, and API reference, please visit the official documentation at [https://mailhexu.github.io/unfolding/](https://mailhexu.github.io/unfolding/).

## Contributing

Contributions are welcome! If you find a bug, have a feature request, or would like to contribute code, please feel free to open an issue or a pull request on the [GitHub repository](https://github.com/mailhexu/unfolding).

### Adding a new backend interface

The contributor recipe for connecting a new data source or projection —
engine selection, parser/adapter contracts, route registration
(TOML/CLI/JSON), local example data, and verification — is
[`devdoc/adding-an-unfolding.md`](devdoc/adding-an-unfolding.md).

### Re-running the symbolic derivations

The weight identities (LCAO dual-basis projection, spectral sum rule, and the
Allen-style phonon projection sum rule) are derived and verified by the
scripts in [`derivations/`](derivations/). They run standalone and write
LaTeX fragments to `derivations/out/`:

```bash
python derivations/lcao_weight.py
python derivations/normalization.py
python derivations/phonon_projection.py
```

The same checks run in CI via `tests/test_derivations.py`.

## License

This project is licensed under the BSD 2-Clause License. See the [LICENSE](LICENSE) file for details.
