Merge branch 'main' into paper

.gitignore

@@ -44,7 +44,6 @@ POTCAR
 *.check
 *.cst_esp
 KPOINTS
-PROCAR
 *.json
 *.DS_Store
 

README.md

@@ -13,18 +13,19 @@ 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/)!
+[here](https://smtg-bham.github.io/easyunfold/)!
 
 Our goal is to implement the band structure unfolding workflow in a robust and user-friendly software
 package.
+Typical applications of band structure unfolding are the electronic structure analysis of defects, disorder, alloys, surfaces (and more), as illustrated in the example outputs below and [docs examples](https://smtg-bham.github.io/easyunfold/examples.html).
 
 For the methodology of supercell band unfolding, see
 [here](https://link.aps.org/doi/10.1103/PhysRevB.85.085201).
 
 ### Example Outputs
-Cs₂(Sn/Ti)Br₆ Vacancy-Ordered Perovskite Alloys |     Symmetry-broken Si Supercell
+[Cs₂(Sn/Ti)Br₆ Vacancy-Ordered Perovskite Alloys](https://doi.org/10.1021/acs.jpcc.3c05204) |     Oxygen Vacancy (*V*ₒ⁰) in MgO
 :-------------------------:|:------------------------------------:
-<img src="docs/img/CSTB_easyunfold.gif" height="400"/> | <img src="examples/Si222/unfold_tall.png" height="400"/>
+<img src="docs/img/CSTB_easyunfold.gif" height="400"/> | <img src="examples/MgO/unfold_project_MgO_v_O_0_tall.png" height="400"/>
 
 ## Usage
 
@@ -49,11 +50,11 @@ In all cases, the supercell symmetry is lowered compared to the pristine primiti
 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.
+[Theory](https://smtg-bham.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.
+Please see the [documentation](https://smtg-bham.github.io/easyunfold/) for guides and examples.
 
 ## Installation
 
@@ -105,6 +106,7 @@ dependencies for using pre-commit hooks (`pre-commit`).
 
 We'll add papers that use `easyunfold` to this list as they come out!
 
+- S. M. Liga & S. R. Kavanagh, A. Walsh, D. O. Scanlon and G. Konstantatos [_Journal of Physical Chemistry C_](https://doi.org/10.1021/acs.jpcc.3c05204) 2023
 - 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. [_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)

docs/index.md

@@ -13,6 +13,7 @@ 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.
+Typical applications of band structure unfolding are the electronic structure analysis of defects, disorder, alloys, surfaces (and more), as illustrated in the example outputs below and [docs examples](https://smtg-ucl.github.io/easyunfold/examples.html).
 
 Our goal is to implement the band structure unfolding workflow in a robust and user-friendly software 
 package.
@@ -21,9 +22,9 @@ For the methodology of supercell band unfolding, see
 [here](https://link.aps.org/doi/10.1103/PhysRevB.85.085201).
 
 ### Example Outputs
-|    Cs₂(Sn/Ti)Br₆ Vacancy-Ordered Perovskite Alloys    |                Symmetry-broken Si Supercell                 |
-|:-----------------------------------------------------:|:-----------------------------------------------------------:|
-|   <img src="img/CSTB_easyunfold.gif" height="400"/>   | <img src="../examples/Si222/unfold_tall.png" height="400"/> |
+| [Cs₂(Sn/Ti)Br₆ Vacancy-Ordered Perovskite Alloys](https://doi.org/10.1021/acs.jpcc.3c05204) |                        Oxygen Vacancy (*V*ₒ⁰) in MgO                         |
+|:-------------------------------------------------------------------------------------------:|:---------------------------------------------------------------------------:|
+|                      <img src="img/CSTB_easyunfold.gif" height="400"/>                      | <img src="../examples/MgO/unfold_project_MgO_v_O_0_tall.png" height="400"/> |
 
 ## Usage
 
@@ -50,12 +51,13 @@ required to be sampled for the supercell, and the extracted spectral weights nee
 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 --->
+<!--- When JOSS submitted, add 'Citation' section here, and CITATION.cff --->
 
 ## Studies using `easyunfold`
 
 We'll add papers that use `easyunfold` to this list as they come out!
 
+- S. M. Liga & S. R. Kavanagh, A. Walsh, D. O. Scanlon and G. Konstantatos [_Journal of Physical Chemistry C_](https://doi.org/10.1021/acs.jpcc.3c05204) 2023
 - 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. [_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)

docs/theory.md

@@ -18,11 +18,11 @@ $$
 \vec{k_i} = \vec{K} + \vec{G}_i\  ; \  i=1,...,N_{\vec{K}}
 $$
 
-The key implication is that for a given $\vec{k}$, there is a unique $\vec{K}$ that it folds to.
+The key implication is that for a given $\vec{k}_i$, there is a unique $\vec{K}$ that it folds to.
 
 The goal of the band folding procedure is to obtain the $E(\vec{k})$ from the complicated $E(\vec{K})$, 
-where E is the energy/eigenvalue of the Kohn-Sham electronic states. 
-This can be achieved by projecting $\ket{\vec{K}m}$ on all of the primitive cell Block states 
+where $E(\vec{k})$ is the energy/eigenvalue of the Kohn-Sham electronic states at $\vec{k}$ in the Brillouin zone of the primitive cell. 
+This can be achieved by projecting $\ket{\vec{K}m}$ on all of the primitive cell Bloch states 
 $\ket{\vec{k}_i n}$ of a fixed $\vec{k}_i$, where $m$ and $n$ are band indices in the supercell and 
 primitive cell respectively, and compute the spectral weight:
 
@@ -34,17 +34,16 @@ where $P$ represents the probability of finding a set of primitive cell states $
 contributing to the supercell state $\ket{\vec{K}m}$, or the amount of Bloch character $\vec{k}_i$ 
 preserved in $\ket{\vec{K}m}$ at the same energy. 
 
-Based on this, one can further derive the spectral function of $E$, which represents the probability of 
+Based on this, one can further derive the spectral function $A(\vec{k}_i, E)$, which represents the probability of 
 an electronic state with energy $E$ at $\vec{k}_i$ (i.e. a 'band structure density'):
 
 $$
 A(\vec{k}_i, E) = \sum_m P_{\vec{K}m}(\vec{k}_i)\delta(E_m - E).
 $$
 
-In practice, the $\delta$ function is replaced with a Gaussian or Lorentzian function to smear the 
-contribution with discretised $E$. 
+In practice, the $\delta$ function is replaced with a Gaussian or Lorentzian function to smear the contribution over a discretised energy grid. 
 
-Hence, the central quantity to be calculated is the $P_{\vec{K}m}(\vec{k}_i)$.
+Hence, the central quantity to be calculated is $P_{\vec{K}m}(\vec{k}_i)$.
 For a plane-wave basis, it can be shown that (equation 15 in Popescu et al.[^2]):
 
 $$

docs/tutorial.md

@@ -32,6 +32,12 @@ Below is a guide for performing band structure unfolding when using VASP.
 
 ## Step 1 - Generate the _k_-point path for the primitive cell
 
+In this step, we first generate the band structure _k_-point path we want to calculate. To do this, we use the prototype _high-symmetry primitive_ structure to get the corresponding _k_-point path. 
+
+:::{note}
+For disordered materials, this primitive cell should be the idealised primitive cell of the material (i.e. the primitive structure where all disordered sites have been set equal), not the SQS cell, and for defect supercells this should be the _primitive_ cell of the host compound, not the bulk supercell.
+:::
+
 This can be done by well-established packages such as 
 [seekpath](https://www.materialscloud.org/work/tools/seekpath) or 
 [sumo](https://github.com/SMTG-UCL/sumo).