Merge pull request #21 from SMTG-UCL/pr-docs-update

Update documentation

docs/guide.md

@@ -1,4 +1,5 @@
 # Guide
+
 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:
 
@@ -13,8 +14,9 @@ In both cases, its symmetry is lowered when compared to the perfect primitive ce
 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.
-Use of VASP is assumed for the guide below.
+At the moment, two plane wave DFT codes, VASP[^vasp] and CASTEP[^castep], are supported. In principle, other PW code can be supported easily if the wavefunction can be read in.
+
+Below is a guide for performing unfolding when using VASP.
 
 ## Step 1 - Generate the kpoints path of the primitive cell
 
@@ -138,4 +140,8 @@ easyunfold unfold plot
 ```
 
 to generate a plot of the spectral function.
-It is possible to further customise the plot though command line arguments - see the help with `easyunfold unfold plot --help`.
+It is possible to further customise the plot though command line arguments - see the help with `easyunfold unfold plot --help`.
+
+
+[^vasp]: https://www.vasp.at
+[^castep]: http://www.castep.org

docs/index.md

@@ -41,7 +41,7 @@ We'll add papers that use `easyunfold` to this list as they come out!
 
 ## DFT code support
 
-At the moment, easyunfold supports VASP and CASTEP, but most of the routines are abstracted from the code specific details.
+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:
 
 - Implementing a subclass of `WaveFunction` that handles reading the wave function output.
@@ -106,6 +106,8 @@ installation.md
 guide.md
 examples.md
 theory.md
+references.md
+publications.md
 cli.rst
 apidocs/index
 ```

docs/publications.md

@@ -0,0 +1,7 @@
+# Publications
+
+* Nicolson, A.; Breternitz, J.; Kavanagh, S. R.; Tomm, Y.; Morita, K.; Squires, A. G.; Tovar, M.; Walsh, A.; Schorr, S.; Scanlon, D. O. Interplay of Static and Dynamic Disorder in the Mixed-Metal Chalcohalide Sn2SbS2I3. J. Am. Chem. Soc. 2023. https://doi.org/10.1021/jacs.2c13336.
+
+* Huang, Y.-T.; Kavanagh, S. R.; Righetto, M.; Rusu, M.; Levine, I.; Unold, T.; Zelewski, S. J.; Sneyd, A. J.; Zhang, K.; Dai, L.; Britton, A. J.; Ye, J.; Julin, J.; Napari, M.; Zhang, Z.; Xiao, J.; Laitinen, M.; Torrente-Murciano, L.; Stranks, S. D.; Rao, A.; Herz, L. M.; Scanlon, D. O.; Walsh, A.; Hoye, R. L. Z. Strong Absorption and Ultrafast Localisation in NaBiS2 Nanocrystals with Slow Charge-Carrier Recombination. Nat Commun 2022, 13 (1), 4960. https://doi.org/10.1038/s41467-022-32669-3.
+
+* Wang, Y.; Kavanagh, S. R.; Burgués-Ceballos, I.; Walsh, A.; Scanlon, D. O.; Konstantatos, G. Cation Disorder Engineering Yields AgBiS2 Nanocrystals with Enhanced Optical Absorption for Efficient Ultrathin Solar Cells. Nat. Photon. 2022, 16 (3), 235–241. https://doi.org/10.1038/s41566-021-00950-4.

docs/references.md

@@ -0,0 +1,7 @@
+# References
+
+These works provide theoretical background of band structure unfolding:
+
+* Popescu, V.; Zunger, A. Effective Band Structure of Random Alloys. Phys. Rev. Lett. 2010, 104 (23), 236403. https://doi.org/10.1103/PhysRevLett.104.236403.
+
+* Popescu, V.; Zunger, A. Extracting $E$ versus $\vec{k}$ Effective Band Structure from Supercell Calculations on Alloys and Impurities. Phys. Rev. B 2012, 85 (8), 085201. https://doi.org/10.1103/PhysRevB.85.085201.

docs/theory.md

@@ -1,7 +1,10 @@
 # Theory of unfolding
 
+Theoretical background of the methodology used in this package is available in the literature[^1][^2].
+Here, only a brief summary is given for brevity.
 
 Notation: $\vec{k}$ is the kpoint of the supercell and $\vec{k}$ is that of the primitive cell. 
+
 Reference: [https://link.aps.org/doi/10.1103/PhysRevB.85.085201](https://link.aps.org/doi/10.1103/PhysRevB.85.085201)  
 
 Each $k$ in the primitive cell can be mapped to that in the supercell where:
@@ -14,7 +17,7 @@ with $\vec{G}_0$ being an reciprocal lattice vector.
 Naturally, each $\vec{K}$ in the supercell can be unfolded into a set of $\vec{k}_i$:
 
 $$
-\vec{k_i} = \vec{K} + \vec{G}_i, i=1,...,N_\vec{K}.
+\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.
@@ -27,7 +30,8 @@ P_{\vec{K}m}(\vec{k}_i) = \sum_n |\braket{\vec{K}m |\vec{k}_i n}|^2.
 $$
 
 where $P$ represents the probability of finding a set of primitive cell stats $\ket{\vec{k}_in}$ 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 dervice the spectral function of $E$:
+
+Based on this, one can further derive the spectral function of $E$:
 
 $$
 A(\vec{k}_i, E) = \sum_m P_{\vec{K}m}(\vec{k}_i)\delta(E_m - E).
@@ -42,17 +46,23 @@ $$
 P_{\vec{K}m}(\vec{k}_j) = \sum_{\vec{g}} |C_{\vec{Km}}(\vec{g} + \vec{G_j})|^2,
 $$
 
-where $C_{\vec{Km}}(\vec{g} + \vec{G_j})$ the plane wave coefficients of the supercell. 
+where $C_{\vec{Km}}(\vec{g} + \vec{G_j})$ are the plane wave coefficients of the supercell.
+Because the supercell is commensurate with the primitive cell, the vectors $\vec{g}$ are included in the basis set of the supercell calculations. 
+Since $\vec{G_{j}}$ is the reciprocal lattice vector that wraps $\vec{k}$ to $\vec{K}$,
+all plane wave coefficients that are needed to obtain $P_{\vec{K}_m}(\vec{k}_j)$ are present in the wave function output of the supercell calculation. 
 
 
 ## Symmetry considerations
 
-In practice, the set of primitive cell kpoints $\vec{k}_i$ is taken from a given path in the Brouline zone going through multiple high symmetry points. 
-This selection of the path depends on the space group of the primitive cell.
-Only a limited set of paths are needed because of the presence of point group symmetry, as symmetrically equivalent kpoints contains the same eigenstates. 
+The set of primitive cell kpoints $\vec{k}_i$ are located on a given path in the Brillouin zone, going through multiple high symmetry points. 
+The selection of the path is not unique, but often depends on the space group of the primitive cell.
+Only a limited set of paths are needed because of the presence of point group symmetry, as symmetrically equivalent $\vec{k}$ contains the same eigenstates. 
+
+However, the supercell to be unfolded does not necessarily contain the same point group symmetry due to imperfections (presence of defects, strain, distortions).
+The broken symmetry means that previously equivalent $\vec{k}$ are no longer equivalent. 
 
-However, the supercell to be unfolded often contains reduced point group symmetry compared to that of the primitive cell due to imperfections (presence of defects, strain, distorations e.t.c).
-This broken symmetry means that previously equivalent kpoints are no longer equivalent. 
+We address this by first expanding each $\vec{k}$ based on the symmetry operations of the primitive cell, followed by a reduction using the symmetry of the supercell.
+The spectral weight at each $\vec{k}$ is then a weighted combination of that from a set of $\vec{k_s^\prime}$ points that are inequivalent under the symmetry of the supercell.
 
-We account of this by including images of the primitive kpoints that are no longer equivalent under the point group of that of the supercell. 
-Weighted contributions of these extra kpoints are added to the spectral function. 
+[^1]: Popescu, V.; Zunger, A. Effective Band Structure of Random Alloys. Phys. Rev. Lett. 2010, 104 (23), 236403. https://doi.org/10.1103/PhysRevLett.104.236403.
+[^2]: Popescu, V.; Zunger, A. Extracting $E$ versus $\vec{k}$ Effective Band Structure from Supercell Calculations on Alloys and Impurities. Phys. Rev. B 2012, 85 (8), 085201. https://doi.org/10.1103/PhysRevB.85.085201.