Metadata-Version: 2.4
Name: banduppy
Version: 0.5.0
Summary: BandUPpy: Python Package for Band Unfolding of Plane-wave Based First-Principles Calculations.
Author-email: "Stepan S. Tsirkin" <stepan.tsirkin@ehu.eus>, Badal Mondal <badalmondal.chembgc@gmail.com>
Maintainer-email: "Stepan S. Tsirkin" <stepan.tsirkin@ehu.eus>, Badal Mondal <badalmondal.chembgc@gmail.com>
License-Expression: GPL-3.0-only
Project-URL: Homepage, https://github.com/band-unfolding/banduppy.git
Project-URL: Documentation, https://github.com/band-unfolding/banduppy/blob/master/docs/USAGE.md
Project-URL: Repository, https://github.com/band-unfolding/banduppy.git
Project-URL: Issues, https://github.com/band-unfolding/banduppy/issues
Project-URL: Changelog, https://github.com/band-unfolding/banduppy/blob/master/docs/RELEASE.md
Project-URL: Releasenotes, https://github.com/band-unfolding/banduppy/releases
Keywords: band unfolding,supercell,first-principles,effective mass,alloy scattering
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy>=1.0
Requires-Dist: matplotlib
Requires-Dist: irrep<3.5,>=3.0
Requires-Dist: ase
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-cov>=4.1; extra == "test"
Dynamic: license-file

# `BandUPpy`: Python Package for Band Unfolding of Plane-wave Based First-Principles Calculations             

__Note:__ This is a Python version to the [BandUP](https://github.com/band-unfolding/bandup) code (not to be confused with bandupy - the interface and plotting tool of BandUP), made in order to restore
support for modern versions of QuantumEspresso and other codes. In order ot read the wavefunctions stored by ab-initio codes, the routines of [irrep](https://github.com/stepan-tsirkin/irrep) are used. 

<!-- =========================================================== -->

<!-- =========================================================== -->
![](https://raw.githubusercontent.com/band-unfolding/banduppy/refs/heads/master/imgs/Si50Ge50.png)  |  ![](https://raw.githubusercontent.com/band-unfolding/banduppy/refs/heads/master/imgs/Si50Ge50_.png) |  ![](https://raw.githubusercontent.com/band-unfolding/banduppy/refs/heads/master/imgs/SiGeOverlayBandStructure.png) 
:-------------------------:|:-------------------------:|:-------------------------:
Unfolded band structure - flatband mode (Si0.5Ge0.5, Red: unfolded, gray: folded) |  Unfolded band structure - density mode (Si0.5Ge0.5) | Band structures overlay (Si0.5Ge0.5: Red, pure Si: black, pure Ge: blue) 
![](https://raw.githubusercontent.com/band-unfolding/banduppy/refs/heads/master/imgs/band_center_width.png)  |  ![](https://raw.githubusercontent.com/band-unfolding/banduppy/refs/heads/master/imgs/effective_mass_plot_0.png) |  ![](https://raw.githubusercontent.com/band-unfolding/banduppy/refs/heads/master/imgs/effective_mass_plot_1.png) 
Band centers and band width (Si0.5Ge0.5) |  Band centers (Al0.84Ga0.16N) | SCF fitting of good band centers (Al0.84Ga0.16N5)
<!-- =========================================================== -->

<!-- =========================================================== -->
## Developers and contributors
<!-- =========================================================== -->

__BandUPpy Package Developer/Maintainer:__ [Stepan S. Tsirkin](https://github.com/stepan-tsirkin), [Badal Mondal](https://github.com/bmondal94) 

__BandUPpy Contributors:__  [Contributors](https://github.com/band-unfolding/banduppy/graphs/contributors)

* We sincerely thank each and every contributor for their valuable input and support.

__Contact us:__ [Email developer/maintainer team](mailto:stepan.tsirkin@ehu.eus,badalmondal.chembgc@gmail.com) 

* If you would like to contribute to the development of `BandUPpy` or request new functionality, please get in touch with [us](mailto:stepan.tsirkin@ehu.eus,badalmondal.chembgc@gmail.com) or open a pull request. We appreciate and respect our users' views and are committed to providing the best experience possible. Your feedback is highly valued. We will be happy to support your request ASAP. 

__Special mention:__ `BandUPpy` originated from the ideas and implementation developed in the original [BandUP](https://github.com/band-unfolding/bandup) code. `BandUP` was originally developed by _Paulo V. C. Medeiros_ (then at Linköping University, presently at the Swedish Meteorological and Hydrological Institute), _Jonas Björk_ (Linköping University), and [Stepan S. Tsirkin](https://github.com/stepan-tsirkin).

<!-- =========================================================== -->

<!-- =========================================================== -->
## Installation

### 1. Requirements
```
    1. python>=3.7
    2. collections
    3. numpy
    4. pickle
    5. scipy>=1.0
    6. irrep>=2.6.3
    7. matplotlib
    8. ase (optional)
```

### 2. Installation using `pip` [*recommended]

```
    pip install banduppy
```

### 3. Installation from github repository

```
    git clone https://github.com/band-unfolding/banduppy.git
    cd banduppy
    pip install .  
```
Or, without cloning
```
    pip install git+https://github.com/band-unfolding/banduppy.git #@specific_branch
```

<!-- =========================================================== -->

<!-- =========================================================== -->
##  Plane-wave codes currently supported by `BandUPpy`

At the moment, `BandUPpy` can parse wavefunctions generated by: 

  * [VASP](http://www.vasp.at)
  * [Quantum ESPRESSO](http://www.quantum-espresso.org)
  * [ABINIT](http://www.abinit.org)
  * any code that has interface to [Wannier90](http://wannier.org) (via reading the UNK* and *.eig files)
  * [GPAW](https://gpaw.readthedocs.io)

<!-- =========================================================== -->

<!-- =========================================================== -->
## Usage
__Documentation__: [here](https://github.com/band-unfolding/banduppy/blob/master/docs/USAGE.md)

The detailed documentation is available [here](https://github.com/band-unfolding/banduppy/blob/master/docs/USAGE.md). Explore the [tutorial](https://github.com/band-unfolding/banduppy/tree/master/tutorials) folder for example tutorials. Below are quick snippets showcasing what you can achieve with `BandUPpy`:
```
banduppy package:
    1. Unfolding class 
        1.1 propose_maximum_minimum_folding()
        1.2 generate_SC_Kpts_from_pc_kpts()
        1.3 generate_SC_Kpts_from_pc_k_path()
        1.3 Unfold()
        1.4 plot_ebs() [Note: Similar to Plotting class but can not plot band centers]
    2. Properties class
        2.1 collect_bandstr_data_only_in_energy_window()
        2.2 band_centers_broadening_bandstr()
        2.3 calculate_effecfive_mass()
        2.4 effective_mass_fit_functions()
        2.5 calculate_alloy_scattering_potential()
        2.6 alloy_scattering_lifetime_function()
    3. SaveBandStructuredata class
        3.1 save_unfolded_pc_kpts()
        3.2 save_unfolded_bandstucture()
        3.3 save_merge_unfolded_kp_bd_data()
        3.4 save_unfolded_bandcenter()
    4. Plotting class
        4.1 plot_ebs()
        4.2 plot_scf()
        4.3 save_plot_figure()
    5. HighLevelProperties class
        5.1 scf_refine_effecfive_mass_calculator()
        5.2 calculate_effective_masses()
        5.3 merge_zero_weight_2_sc_kpoint_file()
```

<!-- =========================================================== -->
## Tips and tricks:

__FAQs__: [here](https://github.com/band-unfolding/banduppy/blob/master/docs/FAQs.md)

You can find a list of common user issues encountered while using this software [here](https://github.com/band-unfolding/banduppy/blob/master/docs/FAQs.md). We appreciate and respect our users' views and are committed to providing the best experience possible. Your feedback is highly valued.

<!-- =========================================================== -->

<!-- =========================================================== -->
## Citations and references:

If you use `BandUPpy` in your work, please:

  * **State EXPLICITLY that you have used the BandUPpy code** (or a modified version of it, if this is the case), for instance, adding a sentence like: 

         "The unfolding has been performed using the BandUPpy code"

  * **How to cite the package:** (use appropriate version number and doi corresponding to your installed banduppy)

>> 1. <author_list\>, "band-unfolding/banduppy: version-0.3.5 (v0.3.5))". Zenodo, 2026. [doi:10.5281/zenodo.XXXXX](https://doi.org/10.5281/zenodo.XXXXX)
>> 2. Mikel Iraola, Juan L. Mañes, Barry Bradlyn, Titus Neupert, Maia G. Vergniory, Stepan S. Tsirkin, "IrRep: Symmetry eigenvalues and irreducible representations of ab initio band structures", [Comput. Phys. Commun. **272**, 108226 (2022)](https://doi.org/10.1016/j.cpc.2021.108226)

  * **Read and cite the following papers** (and the appropriate references therein):
    
>> 1. Paulo V. C. Medeiros, Sven Stafström, and Jonas Björk, [Phys. Rev. B **89**, 041407(R) (2014)](http://doi.org/10.1103/PhysRevB.89.041407)  
>> 2. Paulo V. C. Medeiros, Stepan S. Tsirkin, Sven Stafström, and Jonas Björk, [Phys. Rev. B **91**, 041116(R) (2015)](http://doi.org/10.1103/PhysRevB.91.041116)  

If you use the `band center determination` or `effective mass` modules/functions from `BandUPpy` in your work, please:

  * **Additionally read and cite the following papers** (and the appropriate references therein):
    
>> 4. TBA 

If you use the `alloy scattering` modules/functions from `BandUPpy` in your work, please:

  * **Additionally read and cite the following papers** (and the appropriate references therein):

>> 5. TBA    
>> 6. Nick Pant, Zihao Deng, and Emmanouil Kioupakis,
   [Appl. Phy. Lett. **117**, 242105 (2020)](http://doi.org/10.1063/5.0027802)  

__Bibliography file:__ Here is the [bibliography file](https://github.com/band-unfolding/banduppy/blob/master/docs/REFERENCES.md) for your convenience.

<!-- =========================================================== -->

<!-- =========================================================== -->
## Version release
Chekout out [version release history here](https://github.com/band-unfolding/banduppy/blob/master/docs/RELEASE.md) for the full list of updates and upgrades.

<!-- =========================================================== -->

<!-- =========================================================== -->
## License

`BandUPpy` is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

`BandUPpy` is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details: [GNU General Public License v3.0](https://github.com/band-unfolding/banduppy/blob/master/LICENSE)
<!-- =========================================================== -->

<!-- =========================================================== -->
## Upcoming (TBD)
1. Inverse participation ratio implementation
2. Orbital contribution projection implementation
3. Set up wiki
<!-- =========================================================== -->

