Skip to content

Commit

Permalink
Sk docs update (#23)
Browse files Browse the repository at this point in the history 
* Update docs main page

* Update `README.md`

* Add `-h` CLI help options

* `yapf` formatting

* Update `Guide` docs

* Update NaBiS2 figure to have title centred

* Update atom-projected NaBiS2 figures to have titles centred

* Refactor `Guide` to `Tutorial` as this is more recognisable to people in the field (otherwise most will skip to the examples)

* Update `publications.md`

* Update `theory.md`

* Add links to Theory page

* Update `Installation` docs page

* Recentre Si222 images

* Fix typos and make output more informative

* Add symlinked `README.md`s for the other examples as well as Si222

* Update `Si222` docs example

* Update `Si` CASTEP docs example

* Update `MgO` docs example

* Fix `colors`/`cmap` handling and docstrings

* Update `NaBiS2` example

* Fix `plot_projected` default

* Update `NaBiS2` example

* Show only the actual No of supercel kpoints in CLI

---------

Co-authored-by: Bonan Zhu <[email protected]>
  • Loading branch information
@kavanase @zhubonan
kavanase and zhubonan authored Jun 27, 2023
1 parent 1ae0d0f commit 93e8a8e
Show file tree
Hide file tree
Showing 30 changed files with 580 additions and 424 deletions.
115 changes: 72 additions & 43 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,54 +1,68 @@
# Easyunfold


![build](https://github.com/SMTG-UCL/easyunfold/actions/workflows/ci.yaml/badge.svg)
[![docs](https://github.com/SMTG-UCL/easyunfold/actions/workflows/docs.yaml/badge.svg)](https://smtg-ucl.github.io/easyunfold/)
[![codecov](https://codecov.io/gh/SMTG-UCL/easyunfold/branch/main/graph/badge.svg?token=XLLWWU5UM2)](https://codecov.io/gh/SMTG-UCL/easyunfold)
[![PyPI](https://img.shields.io/pypi/v/easyunfold)](https://pypi.org/project/easyunfold)
[![Downloads](https://img.shields.io/pypi/dm/easyunfold)](https://smtg-ucl.github.io/easyunfold/)
<!--- When JOSS submitted, add this: [![JOSS](https://joss.theoj.org/papers/10.21105/joss.04817/status.
svg)](https://doi.org/10.21105/joss.)--->

![easyunfold](docs/img/logo.svg)
[![easyunfold](docs/img/logo.svg)](https://smtg-ucl.github.io/easyunfold/)

Documentation: https://smtg-ucl.github.io/easyunfold/
`Easyunfold` is intended for obtaining the effective band structure of a supercell for a certain _k_-point
path of the primitive cell. It was originally based on
[PyVaspwfc](https://github.com/QijingZheng/VaspBandUnfolding) for reading VASP wavefunction outputs,
with a notable improvement being that symmetry-breaking is properly accounted for by sampling necessary
additional _k_-points and averaging accordingly. Documentation site
[here](https://smtg-ucl.github.io/easyunfold/)!

This package is intended for obtaining the effective band structure of a supercell for a certain path of the primitive cell.
It was originally based on [PyVaspwfc](https://github.com/QijingZheng/VaspBandUnfolding) for reading wavefunction output of VASP, and contains some code of the latter.
An notable improvement is that breaking symmetry is taken accounted of by sampling additional kpoints and taking average accordingly, which was previously missing.
Our goal is to make the unfolding process easier to carry out and less likely to go wrong.

For the methodology, see: https://link.aps.org/doi/10.1103/PhysRevB.85.085201
Our goal is to implement the band structure unfolding workflow in a robust and user-friendly software
package.

For the methodology of supercell band unfolding, see
[here](https://link.aps.org/doi/10.1103/PhysRevB.85.085201).

## Usage

Main goal of this tool is to make the unfolding process easier.
To generate a unfolded band structure, one typically needs to perform the following step:

1. Create a primitive cell, and generate a k point path for this primitive cell.
2. Create a supercell, and obtain its optimised structure.
3. Generate a series of kpoints in the supercell to be calculated.
4. Perform a band structure calculation using the supercell, and save its wave function.
5. Run post-processing to obtain the unfolded band structure.

The supercell usually contains certain defects, or a special quasi random structure.
In both cases, its symmetry is lowered when compared to the perfect primitive cell.
Hence, for a given kpoint path in the primitive cell, additional kpoints may need to be sampled, and the extracted spectral weights need to be averaged in the end to obtained the effective band structure (EBS).

At the moment, only VASP calculations are supported, although in principle other PW code can be supported easily if the wavefunction can be read in.

Please see the documentation for guide and examples.
To generate an unfolded band structure, one typically needs to perform the following steps:

1. Create a primitive unit cell, and generate a band structure _k_-point path corresponding to this
primitive cell.
2. Create a supercell (e.g. disordered, defective, surface slab etc.), and obtain its optimised structure.
3. Generate a series of _k_-points for the supercell to be calculated.
4. Perform a band structure calculation with the supercell, and save its wavefunction output to file.
5. Post-process the supercell wavefunction to obtain the unfolded band structure in the _k_-point path
of the primitive unit cell.

These generation and analysis steps are automated in `easyunfold`, with only the primitive unit cell and
supercell structures required as inputs from the user.

Typically, the supercell comprises some form of symmetry-breaking relative to the primitive cell, such
as defects, disorder (e.g. special quasi-random structures (SQS) for site disorder – other forms of
disorder such as magnetic, dynamic/vibrational, polar, elastic etc. also possible), or a surface/interface
slab.
In all cases, the supercell symmetry is lowered compared to the pristine primitive cell.
Hence, for a given _k_-point path in the primitive cell Brillouin Zone, additional _k_-points are
required to be sampled for the supercell, and the extracted spectral weights need to be appropriately
averaged to obtain the correct effective band structure (EBS). See the docs
[Theory](https://smtg-ucl.github.io/easyunfold/theory.html) page for more details.
<!-- when JOSS submitted, add link to paper (discussion of theory) here! -->
<!--- When JOSS submitted, add 'License and Citation' section here, and `CITATION.cff` file --->

Please see the [documentation](https://smtg-ucl.github.io/easyunfold/) for guides and examples.

## Installation

### Install from pip
### Install from `pip`

The package can be installed from `pip`
`easyunfold` can be installed from `pip`:

```
pip install easyunfold
```

This will also install the dependencies, if they are missing.
This will also install the package dependencies, if any are missing.

After installation, run `easyunfold` should give the following output:
After installation, running `easyunfold` on the command-line should give the following output:

```
Usage: easyunfold [OPTIONS] COMMAND [ARGS]...
Expand All @@ -63,8 +77,9 @@ Commands:
unfold Perform unfolding and plotting
```

### Install from source
A recently version of `pip` is needed to do this, due to the use of new style `pyproject.toml` configuration file.
### Developer Installation (from source)
A recent version of `pip` is needed to do this, due to the new style of the `pyproject.toml` configuration
file.
To upgrade your `pip`, do:

```
Expand All @@ -78,22 +93,36 @@ pip install ./easyunfold
```

## Studies using `easyunfold`

We'll add papers that use `easyunfold` to this list as they come out!

- Y. T. Huang & S. R. Kavanagh et al. [_Nature Communications_](https://www.nature.com/articles/s41467-022-32669-3) 2022
- A. T. J. Nicolson et al. [_ChemRxiv_](https://chemrxiv.org/engage/chemrxiv/article-details/63a5d1ffa53ea69e935559e2) 2023
- A. T. J. Nicolson et al. [_Journal of the Americal Chemical Society_](https://doi.org/10.1021/jacs.2c13336) 2023
- Y. Wang & S. R. Kavanagh et al. [_Nature Photonics_](https://www.nature.com/articles/s41566-021-00950-4) 2022 (early version)

<!-- Others? -->

## DFT code support

## Contributors
At the moment, easyunfold supports [VASP](https://www.vasp.at) and [CASTEP](http://www.castep.org), but most of the routines are abstracted from the code specific details.
In principle, support for other plane wave DFT code can be added by:

Code Contributors:
[Bonan Zhu](https://github.com/zhubonan)
[Seán Kavanagh](https://github.com/kavanase)
[Adair Nicolson](https://github.com/https://github.com/adair-nicolson)
- Implementing a subclass of `WaveFunction` that handles reading the wave function output.
- Implementing functions for reading/writing _k_-points.
- Adding branches for dispatching based on the `dft_code` attribute of the `UnfoldKSet` object in
various places within the code.

And those who helped in the development:
The Atomic Simulation Environment ([ASE](https://wiki.fysik.dtu.dk/ase/)) is used by `easyunfold` for
reading in structures, so structure file IO is natively supported for essentially all public DFT codes.

[Joe Willis](https://github.com/joebesity)
[David O. Scanlon](http://davidscanlon.com/?page_id=5)
### Code Compatibility Notes
- Atom-projected band structures are currently only supported for `VASP` calculation outputs.
- Gamma-only and non-collinear spin calculations are not supported for `CASTEP`.

## Contributors
- [Bonan Zhu](https://github.com/zhubonan)
- [Seán Kavanagh](https://github.com/kavanase)
- [Adair Nicolson](https://github.com/adair-nicolson)

And those who helped in the development:
- [Joe Willis](https://github.com/joebesity)
- [David O. Scanlon](http://davidscanlon.com/?page_id=5)
5 changes: 3 additions & 2 deletions docs/examples.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
# Examples

Worked examples show-casing the capability of the package.
Input files can be found [here](https://github.com/SMTG-UCL/easyunfold/tree/main/examples).
Worked examples showcasing the capability of the `Easyunfold`.
Input files for these examples can be found
[here](https://github.com/SMTG-UCL/easyunfold/tree/main/examples).

```{toctree}
:maxdepth: 1
Expand Down
51 changes: 29 additions & 22 deletions docs/examples/example_mgo.md
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,16 @@
# MgO with atomic projections

:::{note}
Relevant files can be found in the `examples/MgO` folder.
The files needed for this example are provided in the
[examples/MgO](https://github.com/SMTG-UCL/easyunfold/tree/main/examples/MgO) folder.
:::

In some cases, it is useful to know the atomic contributions of the bands.
This can be done for unfolded bands as well.
Often it is useful to know the various contributions of atoms in the structure to the electronic bands
in the band structure, to analyse the chemistry and orbital interactions at play in the system. This
can be computed for unfolded bands as well.

For a normal band structure, the contributions can be inferred by colouring the band according to the elemental contributions.
For a normal band structure calculation, the contributions can be inferred by colouring the band
according to the elemental contributions, which can be done using [sumo](https://github.com/SMTG-UCL/sumo).

```{figure} ../../examples/MgO/MgO/band.png
:width: 400px
Expand All @@ -16,40 +19,44 @@ For a normal band structure, the contributions can be inferred by colouring the
Band structure of MgO with atomic contribution </figcaption>
```

Similar plots can be generate for unfolded band structure. However, because the spectral function itself contains both the *location* of the band and its *intensity*, adding a third information regarding the projection can be tricky.
Similar plots can be generated for unfolded band structures. However, because the unfolded spectral
function itself contains both the *location* of the band and its *intensity*, adding a third
dimension of information (atomic projection) can be tricky to visualise.

In this example, we unfold the bands from a MgO 2x1x2 supercell with the first Mg atom displaced. The procedure is essentially the same as the Si supercell example.
In this example, we unfold the bands from a MgO 2x1x2 supercell with a Mg atom displaced to break
symmetry. The procedure is essentially the same as described in the
[Si supercell example](https://smtg-ucl.github.io/easyunfold/examples/example_si222.html).

The only difference is that we turn on the calculation of orbital projections with `LORBIT=11` in the `INCAR` file.

When plotting the unfolded band, the `plot-projections` subcommand is used:
The only difference here is that we turn on the calculation of orbital projections in `VASP` with
`LORBIT = 11` in the `INCAR` file, and then use the `plot-projections` subcommand when plotting the
unfolded band structure:

```bash
easyunfold unfold plot-projections --procar MgO_super/PROCAR \
--atoms-idx="1-4|5-8" --out-file unfold_project.png --combined --cmap="Greens|Reds" \
--emin=-15 --emax=15
easyunfold unfold plot-projections --procar MgO_super/PROCAR --atoms-idx="1-4|5-8" \
--out-file unfold_project.png --combined --emin=-15 --emax=15
```

Note that the path of the `PROCAR` is passed along with the group of atoms.
In this example, the first four atoms are `Mg` the last four are `O`, and we would
like to show the contribution of the band based on the elements.
Different groups are separated by `|`, and `-` can be used to define the range.
Note that use of one-based indexing for atoms, although in python zero-based indexing is used internally.

Note that the path of the `PROCAR` is passed along with the desired groupings of atoms (with
`--atoms-idx`).
In this example, the first four atoms are `Mg` (`1-4`) and the last four are `O` (`5-8`), and we would
like to show the elemental contributions to the bands. Different groups are separated by `|`, and `-`
can be used to define the range. Note that use of one-based indexing for atoms, although in python
zero-based indexing is used internally.

:::{note}
The projections are not stored in the `easyunfold.json` data file. So the `PROCAR` should be kept for replotting in the future.
The atomic projections are not stored in the `easyunfold.json` data file, so the `PROCAR` file should be
kept for replotting in the future.
:::

The `--combined` option creates a combined plot with each group colour with different colour maps.
The `--combined` option creates a combined plot with different colour maps for each atomic grouping.
The spectral intensity is used to define the transparency (`alpha`) allowing the fusion of multiple
projections into a single plot.

```{figure} ../../examples/MgO/unfold_project.png
:alt: MgO unfolded band structure
:width: 400px
:align: center
Unfolded MgO band structure with projections. Green for Mg atoms and red for O atoms.
Unfolded MgO band structure with atomic projections. Red for Mg and green for O atoms.
```


Expand All @@ -64,5 +71,5 @@ easyunfold unfold plot-projections --procar MgO_super/PROCAR --atoms-idx="1-4|5
:width: 800 px
:alt: Projected MgO band structure
Unfolded MgO band structure with projections plotted separately
Unfolded MgO band structure with atomic projections plotted separately (Mg left and O right).
```
29 changes: 21 additions & 8 deletions docs/examples/example_nabis2.md
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,22 @@
# Cation-Disordered NaBiS<sub>2</sub> with and without Atomic Projections
# Cation-Disordered NaBiS<sub>2</sub> with atomic projections

:::{note}
Relevant files can be found in the [examples/NaBiS2](https://github.com/SMTG-UCL/easyunfold/tree/main/examples/NaBiS2) folder.
Note that the `PROCAR.gz` file will need to be decompressed with `gzip -d PROCAR.gz` if reproducing these example plots with the raw data.
The files needed for reproducing this example are provided in the
[examples/NaBiS2](https://github.com/SMTG-UCL/easyunfold/tree/main/examples/NaBiS2) folder.
Note that the `PROCAR.gz` file will need to be decompressed with `gzip -d PROCAR.gz` if recalculating
and reproducing these example plots.
:::

In this example, we unfold the bands from a 80-atom special-quasirandom (SQS) supercell of
NaBiS<sub>2</sub>, where the Na and Bi cations are quasi-randomly distributed, in order to simulate
randomised cation disorder in the material.

:::{tip}
SQS supercells can be generated using tools like
[icet](https://icet.materialsmodeling.org/moduleref_icet/tools.html#module-icet.tools.structure_generation)
or [ATAT](https://www.brown.edu/Departments/Engineering/Labs/avdw/atat/).
:::

In this example, we unfold the bands from a 80-atom special-quasirandom (SQS) supercell of NaBiS<sub>2</sub>, where the Na and
Bi cations are quasi-randomly distributed, in order to simulate randomised cation disorder in the material.
These results were published in Y. T. Huang & S. R. Kavanagh et al. 2022 [^1], and an early version of
`easyunfold` was used for the similar AgBiS$_2$ in Y. Wang & S. R. Kavanagh et al. 2022 [^2],
with these plots demonstrating the key
Expand Down Expand Up @@ -64,7 +74,8 @@ Note that we use "1-based indexing" for the atoms here, matching the VASP format
not zero as in python).

:::{note}
The projections are not stored in the `easyunfold.json` data file. So the `PROCAR` should be kept for replotting in the future.
The atomic projections are not stored in the `easyunfold.json` data file, so the `PROCAR` file should be
kept for replotting in the future.
:::

While the main conclusions of S dominating the valence band and Bi dominating the conduction band are clear from the
Expand All @@ -85,7 +96,8 @@ Unfolded band structure of NaBiS<sub>2</sub> with atomic contributions plotted s
```


An alternative option here is also to just plot only the contributions of Na and Bi cations, with no S projections:
An alternative option here is also to just plot only the contributions of Na (`1-20`) and Bi (`21-40`)
cations, with no S projections:
```bash
easyunfold unfold plot-projections --atoms-idx="1-20|21-40" --procar PROCAR --intensity=2 --combined --colors="r,g"
```
Expand All @@ -98,7 +110,8 @@ Unfolded band structure of NaBiS<sub>2</sub> with atomic contributions of only N
```

While this plot isn't the most aesthetic, it clearly shows that Bi (green) contributes to both the conduction band and
(less so) valence states, but Na (red) doesn't contribute significantly at all.
(less so) valence band states, but Na (red) doesn't contribute significantly at near the band edges
(it's a spectator ion!).

[^1]: [Huang, YT., Kavanagh, S.R., Righetto, M. et al. Strong absorption and ultrafast localisation in NaBiS2 nanocrystals with slow charge-carrier recombination. Nat Commun 13, 4960 (2022)](https://www.nature.com/articles/s41467-022-32669-3)
[^2]: [Wang, Y., Kavanagh, S.R., Burgués-Ceballos, I. et al. Cation disorder engineering yields AgBiS2 nanocrystals with enhanced optical absorption for efficient ultrathin solar cells. Nat. Photon. 16, 235–241 (2022).](https://www.nature.com/articles/s41566-021-00950-4)
Loading

0 comments on commit 93e8a8e

Please sign in to comment.