deploy: 556aaff

_sources/examples/example_mgo.md

@@ -1,4 +1,4 @@
-# MgO with atomic projections
+# MgO with atomic projections, effective masses & defects
 
 :::{note}
 The files needed for this example are provided in the 
@@ -23,6 +23,8 @@ Similar plots can be generated for unfolded band structures. However, because th
 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.
 
+## Displaced Mg Supercell Band Unfolding
+
 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-Bham.github.io/easyunfold/examples/example_si222.html).
@@ -109,6 +111,7 @@ There are _many_ customisation options available for the plotting functions in `
 `easyunfold unfold plot-projections -h` for more details!
 :::
 
+### Carrier Effective Masses
 
 The command `easyunfold unfold effective-mass` can be used to find the effective masses of the unfolded band structure.
 
@@ -163,3 +166,87 @@ The results can unreliable for systems with little or no band gaps and those wit
 :::{tip}
 For complex systems where the detection is difficult, one can manually pass the kpoint and the band indices using the `--manual-extrema` option.
 :::
+
+## Defects
+As shown in the [`easyunfold` YouTube tutorial](https://youtu.be/9zeABbd1r1U?si=Oix3Bamiw8DZaMO4), band structure unfolding can often be useful for analysing the impact of defects and dopants on the electronic structure of materials – particularly under high concentrations. 
+
+As a brief example, here we show base steps in calculating the unfolded band structure of a defective supercell with `easyunfold`, following the procedure shown in the [YouTube tutorial](https://youtu.be/9zeABbd1r1U?si=Oix3Bamiw8DZaMO4). 
+
+### Step 1. Defect Supercell Generation
+For this, we can use the [`doped`](https://doped.readthedocs.io/en/latest) defect package as shown in the tutorial:
+
+```python
+from pymatgen.core.structure import Structure
+from doped.generation import DefectsGenerator
+
+mgo_prim = Structure.from_file('MgO_prim_POSCAR')
+defect_gen = DefectsGenerator(mgo_prim)
+```
+
+```
+Generating DefectEntry objects: 100.0%|██████████| [00:23,   4.26it/s]                             
+Vacancies    Guessed Charges    Conv. Cell Coords    Wyckoff
+-----------  -----------------  -------------------  ---------
+v_Mg         [+1,0,-1,-2]       [0.000,0.000,0.000]  4a
+v_O          [+2,+1,0,-1]       [0.500,0.500,0.500]  4b
+
+Substitutions    Guessed Charges    Conv. Cell Coords    Wyckoff
+---------------  -----------------  -------------------  ---------
+Mg_O             [+4,+3,+2,+1,0]    [0.500,0.500,0.500]  4b
+O_Mg             [0,-1,-2,-3,-4]    [0.000,0.000,0.000]  4a
+
+Interstitials    Guessed Charges    Conv. Cell Coords    Wyckoff
+---------------  -----------------  -------------------  ---------
+Mg_i_Td          [+2,+1,0]          [0.250,0.250,0.250]  8c
+O_i_Td           [0,-1,-2]          [0.250,0.250,0.250]  8c
+
+The number in the Wyckoff label is the site multiplicity/degeneracy of that defect in the conventional ('conv.') unit cell, which comprises 4 formula unit(s) of MgO.
+Note that Wyckoff letters can depend on the ordering of elements in the conventional standard structure, for which doped uses the spglib convention.
+```
+
+and then write the VASP output files for the supercell relaxations:
+
+```python
+from doped.vasp import DefectsSet
+
+ds = DefectsSet(defect_gen)
+ds.write_files(unperturbed_poscar=True)
+```
+
+:::{tip}
+See the [`doped`](https://doped.readthedocs.io) tutorials [here](https://doped.readthedocs.io/en/latest/Tutorials.html) if you're interested in using it for defect calculations. 
+:::
+
+### Step 2. Band Structure _k_-point Generation
+
+When our defect supercell relaxations have completed, we can then generate our k-point paths for the supercell band structure calculation, as usual with `easyunfold`:
+
+```bash
+easyunfold generate MgO_prim_POSCAR supercell_POSCAR MgO_prim_KPOINTS_band --scf-kpoints supercell_IBZKPT
+```
+
+where `MgO_prim_KPOINTS_band` contains the _k_-point path for the primitive cell band structure (e.g. generated by `sumo-kgen`) and here we are performing a hybrid DFT calculation and so we need to use the `--scf-kpoints` option. If for any reason `easyunfold` cannot automatically guess the supercell transformation matrix, we can also access this from the `doped` `DefectsGenerator.supercell_matrix` attribute and supply this with the `--matrix` option.
+
+### Step 3. Band Structure Parsing
+When our supercell band structure calculation has then completed, we can parse the wavefunction output to obtain the unfolded band structure:
+
+```bash
+easyunfold unfold calculate WAVECAR
+```
+
+and then plot the unfolded band structure with atomic projections:
+
+```bash
+easyunfold unfold plot-projections --intensity 60 --dos vasprun.xml.gz --gaussian 0.03 --atoms="Mg,O" --combined --scale 40 --no-total
+```
+
+```{figure} ../../examples/MgO/v_O_0_YT_tutorial/unfold.png
+:width: 800 px
+:alt: Neutral oxygen vacancy in MgO
+
+Atom-projected unfolded band structure for a neutral oxygen vacancy in MgO, showing that the single-particle state introduced by the vacancy is the band gap is comprised of both Mg and O contributions.
+```
+
+:::{note}
+The example files for this unfolded band structure calculation of the neutral oxygen vacancy supercell are provided in the [examples/MgO/v_O_0_YT_tutorial](https://github.com/SMTG-Bham/easyunfold/tree/main/examples/MgO/v_O_0_YT_tutorial) folder.
+:::

_sources/examples/example_si222.md

@@ -1,4 +1,4 @@
-# Si supercell with a displaced atom
+# Silicon with a displaced atom
 
 Below is a step-by-step guide for unfolding the electronic structure of a `2x2x2` supercell of 
 crystalline silicon (Si) which contains a displaced atom, breaking symmetry.

_sources/index.md

@@ -25,6 +25,10 @@ For the methodology of supercell band unfolding, see
 |:-------------------------------------------------------------------------------------------:|:---------------------------------------------------------------------------:|
 |                      <img src="img/CSTB_easyunfold.gif" height="400"/>                      | <img src="../examples/MgO/unfold_project_MgO_v_O_0_tall.png" height="400"/> |
 
+:::{tip}
+See the [`easyunfold` YouTube tutorial](https://youtu.be/9zeABbd1r1U?si=Oix3Bamiw8DZaMO4) for a quick overview of the theory of band structure unfolding, and a walkthrough of the calculation & analysis workflow with `easyunfold`. 
+:::
+
 ## Usage
 
 To generate an unfolded band structure, one typically needs to perform the following steps:

_sources/tutorial.md

@@ -1,5 +1,9 @@
 # Tutorial
 
+:::{tip}
+See the [`easyunfold` YouTube tutorial](https://youtu.be/9zeABbd1r1U?si=Oix3Bamiw8DZaMO4) for a quick overview of the theory of band structure unfolding, and a walkthrough of the calculation & analysis workflow with `easyunfold`. 
+:::
+
 The main goal of `easyunfold` is to make the band structure unfolding workflow easier to implement and 
 less error-prone. To generate an unfolded band structure, one typically needs to perform the following 
 steps:

apidocs/easyunfold/easyunfold.cli.html

@@ -193,8 +193,8 @@
 <li class="toctree-l1"><a class="reference internal" href="../../installation.html">Installation</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../tutorial.html">Tutorial</a></li>
 <li class="toctree-l1 has-children"><a class="reference internal" href="../../examples.html">Examples</a><input checked class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-1"><i class="fa-solid fa-chevron-down"></i></label><ul>
-<li class="toctree-l2"><a class="reference internal" href="../../examples/example_si222.html">Si supercell with a displaced atom</a></li>
-<li class="toctree-l2"><a class="reference internal" href="../../examples/example_mgo.html">MgO with atomic projections</a></li>
+<li class="toctree-l2"><a class="reference internal" href="../../examples/example_si222.html">Silicon with a displaced atom</a></li>
+<li class="toctree-l2"><a class="reference internal" href="../../examples/example_mgo.html">MgO with atomic projections, effective masses &amp; defects</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../examples/example_nabis2.html">Disordered NaBiS<sub>2</sub> with atomic/orbital projections &amp; DOS plotting</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../examples/example_si211_castep.html">Si supercell using CASTEP</a></li>
 </ul>

apidocs/easyunfold/easyunfold.effective_mass.html

@@ -193,8 +193,8 @@
 <li class="toctree-l1"><a class="reference internal" href="../../installation.html">Installation</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../tutorial.html">Tutorial</a></li>
 <li class="toctree-l1 has-children"><a class="reference internal" href="../../examples.html">Examples</a><input checked class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-1"><i class="fa-solid fa-chevron-down"></i></label><ul>
-<li class="toctree-l2"><a class="reference internal" href="../../examples/example_si222.html">Si supercell with a displaced atom</a></li>
-<li class="toctree-l2"><a class="reference internal" href="../../examples/example_mgo.html">MgO with atomic projections</a></li>
+<li class="toctree-l2"><a class="reference internal" href="../../examples/example_si222.html">Silicon with a displaced atom</a></li>
+<li class="toctree-l2"><a class="reference internal" href="../../examples/example_mgo.html">MgO with atomic projections, effective masses &amp; defects</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../examples/example_nabis2.html">Disordered NaBiS<sub>2</sub> with atomic/orbital projections &amp; DOS plotting</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../examples/example_si211_castep.html">Si supercell using CASTEP</a></li>
 </ul>

apidocs/easyunfold/easyunfold.html

@@ -193,8 +193,8 @@
 <li class="toctree-l1"><a class="reference internal" href="../../installation.html">Installation</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../tutorial.html">Tutorial</a></li>
 <li class="toctree-l1 has-children"><a class="reference internal" href="../../examples.html">Examples</a><input checked class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-1"><i class="fa-solid fa-chevron-down"></i></label><ul>
-<li class="toctree-l2"><a class="reference internal" href="../../examples/example_si222.html">Si supercell with a displaced atom</a></li>
-<li class="toctree-l2"><a class="reference internal" href="../../examples/example_mgo.html">MgO with atomic projections</a></li>
+<li class="toctree-l2"><a class="reference internal" href="../../examples/example_si222.html">Silicon with a displaced atom</a></li>
+<li class="toctree-l2"><a class="reference internal" href="../../examples/example_mgo.html">MgO with atomic projections, effective masses &amp; defects</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../examples/example_nabis2.html">Disordered NaBiS<sub>2</sub> with atomic/orbital projections &amp; DOS plotting</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../examples/example_si211_castep.html">Si supercell using CASTEP</a></li>
 </ul>

apidocs/easyunfold/easyunfold.plotting.html

@@ -193,8 +193,8 @@
 <li class="toctree-l1"><a class="reference internal" href="../../installation.html">Installation</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../tutorial.html">Tutorial</a></li>
 <li class="toctree-l1 has-children"><a class="reference internal" href="../../examples.html">Examples</a><input checked class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-1"><i class="fa-solid fa-chevron-down"></i></label><ul>
-<li class="toctree-l2"><a class="reference internal" href="../../examples/example_si222.html">Si supercell with a displaced atom</a></li>
-<li class="toctree-l2"><a class="reference internal" href="../../examples/example_mgo.html">MgO with atomic projections</a></li>
+<li class="toctree-l2"><a class="reference internal" href="../../examples/example_si222.html">Silicon with a displaced atom</a></li>
+<li class="toctree-l2"><a class="reference internal" href="../../examples/example_mgo.html">MgO with atomic projections, effective masses &amp; defects</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../examples/example_nabis2.html">Disordered NaBiS<sub>2</sub> with atomic/orbital projections &amp; DOS plotting</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../examples/example_si211_castep.html">Si supercell using CASTEP</a></li>
 </ul>

apidocs/easyunfold/easyunfold.procar.html

@@ -193,8 +193,8 @@
 <li class="toctree-l1"><a class="reference internal" href="../../installation.html">Installation</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../tutorial.html">Tutorial</a></li>
 <li class="toctree-l1 has-children"><a class="reference internal" href="../../examples.html">Examples</a><input checked class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-1"><i class="fa-solid fa-chevron-down"></i></label><ul>
-<li class="toctree-l2"><a class="reference internal" href="../../examples/example_si222.html">Si supercell with a displaced atom</a></li>
-<li class="toctree-l2"><a class="reference internal" href="../../examples/example_mgo.html">MgO with atomic projections</a></li>
+<li class="toctree-l2"><a class="reference internal" href="../../examples/example_si222.html">Silicon with a displaced atom</a></li>
+<li class="toctree-l2"><a class="reference internal" href="../../examples/example_mgo.html">MgO with atomic projections, effective masses &amp; defects</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../examples/example_nabis2.html">Disordered NaBiS<sub>2</sub> with atomic/orbital projections &amp; DOS plotting</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../examples/example_si211_castep.html">Si supercell using CASTEP</a></li>
 </ul>

apidocs/easyunfold/easyunfold.unfold.html

@@ -195,8 +195,8 @@
 <li class="toctree-l1"><a class="reference internal" href="../../installation.html">Installation</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../tutorial.html">Tutorial</a></li>
 <li class="toctree-l1 has-children"><a class="reference internal" href="../../examples.html">Examples</a><input checked class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-1"><i class="fa-solid fa-chevron-down"></i></label><ul>
-<li class="toctree-l2"><a class="reference internal" href="../../examples/example_si222.html">Si supercell with a displaced atom</a></li>
-<li class="toctree-l2"><a class="reference internal" href="../../examples/example_mgo.html">MgO with atomic projections</a></li>
+<li class="toctree-l2"><a class="reference internal" href="../../examples/example_si222.html">Silicon with a displaced atom</a></li>
+<li class="toctree-l2"><a class="reference internal" href="../../examples/example_mgo.html">MgO with atomic projections, effective masses &amp; defects</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../examples/example_nabis2.html">Disordered NaBiS<sub>2</sub> with atomic/orbital projections &amp; DOS plotting</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../examples/example_si211_castep.html">Si supercell using CASTEP</a></li>
 </ul>

apidocs/easyunfold/easyunfold.utils.html

@@ -192,8 +192,8 @@
 <li class="toctree-l1"><a class="reference internal" href="../../installation.html">Installation</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../tutorial.html">Tutorial</a></li>
 <li class="toctree-l1 has-children"><a class="reference internal" href="../../examples.html">Examples</a><input checked class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-1"><i class="fa-solid fa-chevron-down"></i></label><ul>
-<li class="toctree-l2"><a class="reference internal" href="../../examples/example_si222.html">Si supercell with a displaced atom</a></li>
-<li class="toctree-l2"><a class="reference internal" href="../../examples/example_mgo.html">MgO with atomic projections</a></li>
+<li class="toctree-l2"><a class="reference internal" href="../../examples/example_si222.html">Silicon with a displaced atom</a></li>
+<li class="toctree-l2"><a class="reference internal" href="../../examples/example_mgo.html">MgO with atomic projections, effective masses &amp; defects</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../examples/example_nabis2.html">Disordered NaBiS<sub>2</sub> with atomic/orbital projections &amp; DOS plotting</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../examples/example_si211_castep.html">Si supercell using CASTEP</a></li>
 </ul>

apidocs/easyunfold/easyunfold.vasp_constant.html

@@ -193,8 +193,8 @@
 <li class="toctree-l1"><a class="reference internal" href="../../installation.html">Installation</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../tutorial.html">Tutorial</a></li>
 <li class="toctree-l1 has-children"><a class="reference internal" href="../../examples.html">Examples</a><input checked class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-1"><i class="fa-solid fa-chevron-down"></i></label><ul>
-<li class="toctree-l2"><a class="reference internal" href="../../examples/example_si222.html">Si supercell with a displaced atom</a></li>
-<li class="toctree-l2"><a class="reference internal" href="../../examples/example_mgo.html">MgO with atomic projections</a></li>
+<li class="toctree-l2"><a class="reference internal" href="../../examples/example_si222.html">Silicon with a displaced atom</a></li>
+<li class="toctree-l2"><a class="reference internal" href="../../examples/example_mgo.html">MgO with atomic projections, effective masses &amp; defects</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../examples/example_nabis2.html">Disordered NaBiS<sub>2</sub> with atomic/orbital projections &amp; DOS plotting</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../examples/example_si211_castep.html">Si supercell using CASTEP</a></li>
 </ul>

apidocs/easyunfold/easyunfold.wavecar.html

@@ -195,8 +195,8 @@
 <li class="toctree-l1"><a class="reference internal" href="../../installation.html">Installation</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../../tutorial.html">Tutorial</a></li>
 <li class="toctree-l1 has-children"><a class="reference internal" href="../../examples.html">Examples</a><input checked class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-1"><i class="fa-solid fa-chevron-down"></i></label><ul>
-<li class="toctree-l2"><a class="reference internal" href="../../examples/example_si222.html">Si supercell with a displaced atom</a></li>
-<li class="toctree-l2"><a class="reference internal" href="../../examples/example_mgo.html">MgO with atomic projections</a></li>
+<li class="toctree-l2"><a class="reference internal" href="../../examples/example_si222.html">Silicon with a displaced atom</a></li>
+<li class="toctree-l2"><a class="reference internal" href="../../examples/example_mgo.html">MgO with atomic projections, effective masses &amp; defects</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../examples/example_nabis2.html">Disordered NaBiS<sub>2</sub> with atomic/orbital projections &amp; DOS plotting</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../examples/example_si211_castep.html">Si supercell using CASTEP</a></li>
 </ul>