Add links to YouTube tutorial to docs, and short section of v_O calcu…

…lation with MgO example

README.md

@@ -26,6 +26,8 @@ For the methodology of supercell band unfolding, see
 :-------------------------:|:------------------------------------:
 <img src="docs/img/CSTB_easyunfold.gif" height="400"/> | <img src="examples/MgO/unfold_project_MgO_v_O_0_tall.png" height="400"/>
 
+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:

docs/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.
+:::

docs/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.

docs/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:

docs/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:

examples/MgO/v_O_0_YT_tutorial/POSCAR

@@ -0,0 +1,103 @@
+v_O ~[0.3750,0.3750,0.6250] 0
+1.0
+ 8.4956800000000001 -4.2478400000000001 -4.2478400000000001
+ -4.2478400000000001 8.4956800000000001 -4.2478400000000001
+ 4.2478400000000001 4.2478400000000001 8.4956800000000001
+Mg O
+48 47
+direct
+ 0.8333330000000000 0.1666670000000000 0.0000000000000000 Mg
+ 0.9166670000000000 0.0833330000000000 0.2500000000000000 Mg
+ 0.8333330000000000 0.6666670000000000 0.0000000000000000 Mg
+ 0.6666670000000000 0.3333330000000000 0.0000000000000000 Mg
+ 0.9166670000000000 0.5833330000000000 0.2500000000000000 Mg
+ 0.5000000000000000 0.0000000000000000 0.0000000000000000 Mg
+ 0.7500000000000000 0.2500000000000000 0.2500000000000000 Mg
+ 0.8333330000000000 0.1666670000000000 0.5000000000000000 Mg
+ 0.9166670000000000 0.0833330000000000 0.7500000000000000 Mg
+ 0.6666670000000000 0.8333330000000000 0.0000000000000000 Mg
+ 0.5000000000000000 0.5000000000000000 0.0000000000000000 Mg
+ 0.7500000000000000 0.7500000000000000 0.2500000000000000 Mg
+ 0.3333330000000000 0.1666670000000000 0.0000000000000000 Mg
+ 0.5833330000000000 0.4166670000000000 0.2500000000000000 Mg
+ 0.8333330000000000 0.6666670000000000 0.5000000000000000 Mg
+ 0.4166670000000000 0.0833330000000000 0.2500000000000000 Mg
+ 0.6666670000000000 0.3333330000000000 0.5000000000000000 Mg
+ 0.9166670000000000 0.5833330000000000 0.7500000000000000 Mg
+ 0.5000000000000000 0.0000000000000000 0.5000000000000000 Mg
+ 0.7500000000000000 0.2500000000000000 0.7500000000000000 Mg
+ 0.3333330000000000 0.6666670000000000 0.0000000000000000 Mg
+ 0.5833330000000000 0.9166670000000000 0.2500000000000000 Mg
+ 0.1666670000000000 0.3333330000000000 0.0000000000000000 Mg
+ 0.4166670000000000 0.5833330000000000 0.2500000000000000 Mg
+ 0.6666670000000000 0.8333330000000000 0.5000000000000000 Mg
+ 0.0000000000000000 0.0000000000000000 0.0000000000000000 Mg
+ 0.2500000000000000 0.2500000000000000 0.2500000000000000 Mg
+ 0.5000000000000000 0.5000000000000000 0.5000000000000000 Mg
+ 0.7500000000000000 0.7500000000000000 0.7500000000000000 Mg
+ 0.3333330000000000 0.1666670000000000 0.5000000000000000 Mg
+ 0.5833330000000000 0.4166670000000000 0.7500000000000000 Mg
+ 0.4166670000000000 0.0833330000000000 0.7500000000000000 Mg
+ 0.1666670000000000 0.8333330000000000 0.0000000000000000 Mg
+ 0.0000000000000000 0.5000000000000000 0.0000000000000000 Mg
+ 0.2500000000000000 0.7500000000000000 0.2500000000000000 Mg
+ 0.0833330000000000 0.4166670000000000 0.2500000000000000 Mg
+ 0.3333330000000000 0.6666670000000000 0.5000000000000000 Mg
+ 0.5833330000000000 0.9166670000000000 0.7500000000000000 Mg
+ 0.1666670000000000 0.3333330000000000 0.5000000000000000 Mg
+ 0.4166670000000000 0.5833330000000000 0.7500000000000000 Mg
+ 0.0000000000000000 0.0000000000000000 0.5000000000000000 Mg
+ 0.2500000000000000 0.2500000000000000 0.7500000000000000 Mg
+ 0.0833330000000000 0.9166670000000000 0.2500000000000000 Mg
+ 0.1666670000000000 0.8333330000000000 0.5000000000000000 Mg
+ 0.0000000000000000 0.5000000000000000 0.5000000000000000 Mg
+ 0.2500000000000000 0.7500000000000000 0.7500000000000000 Mg
+ 0.0833330000000000 0.4166670000000000 0.7500000000000000 Mg
+ 0.0833330000000000 0.9166670000000000 0.7500000000000000 Mg
+ 0.9583330000000000 0.2916670000000000 0.3750000000000000 O
+ 0.0416670000000000 0.2083330000000000 0.6250000000000000 O
+ 0.9583330000000000 0.7916670000000000 0.3750000000000000 O
+ 0.7916670000000000 0.4583330000000000 0.3750000000000000 O
+ 0.0416670000000000 0.7083330000000000 0.6250000000000000 O
+ 0.6250000000000000 0.1250000000000000 0.3750000000000000 O
+ 0.8750000000000000 0.3750000000000000 0.6250000000000000 O
+ 0.9583330000000000 0.2916670000000000 0.8750000000000000 O
+ 0.0416670000000000 0.2083330000000000 0.1250000000000000 O
+ 0.7916670000000000 0.9583330000000000 0.3750000000000000 O
+ 0.6250000000000000 0.6250000000000000 0.3750000000000000 O
+ 0.8750000000000000 0.8750000000000000 0.6250000000000000 O
+ 0.4583330000000000 0.2916670000000000 0.3750000000000000 O
+ 0.7083330000000000 0.5416670000000000 0.6250000000000000 O
+ 0.9583330000000000 0.7916670000000000 0.8750000000000000 O
+ 0.5416670000000000 0.2083330000000000 0.6250000000000000 O
+ 0.7916670000000000 0.4583330000000000 0.8750000000000000 O
+ 0.0416670000000000 0.7083330000000000 0.1250000000000000 O
+ 0.6250000000000000 0.1250000000000000 0.8750000000000000 O
+ 0.8750000000000000 0.3750000000000000 0.1250000000000000 O
+ 0.4583330000000000 0.7916670000000000 0.3750000000000000 O
+ 0.7083330000000000 0.0416670000000000 0.6250000000000000 O
+ 0.2916670000000000 0.4583330000000000 0.3750000000000000 O
+ 0.5416670000000000 0.7083330000000000 0.6250000000000000 O
+ 0.7916670000000000 0.9583330000000000 0.8750000000000000 O
+ 0.1250000000000000 0.1250000000000000 0.3750000000000000 O
+ 0.6250000000000000 0.6250000000000000 0.8750000000000000 O
+ 0.8750000000000000 0.8750000000000000 0.1250000000000000 O
+ 0.4583330000000000 0.2916670000000000 0.8750000000000000 O
+ 0.7083330000000000 0.5416670000000000 0.1250000000000000 O
+ 0.5416670000000000 0.2083330000000000 0.1250000000000000 O
+ 0.2916670000000000 0.9583330000000000 0.3750000000000000 O
+ 0.1250000000000000 0.6250000000000000 0.3750000000000000 O
+ 0.3750000000000000 0.8750000000000000 0.6250000000000000 O
+ 0.2083330000000000 0.5416670000000000 0.6250000000000000 O
+ 0.4583330000000000 0.7916670000000000 0.8750000000000000 O
+ 0.7083330000000000 0.0416670000000000 0.1250000000000000 O
+ 0.2916670000000000 0.4583330000000000 0.8750000000000000 O
+ 0.5416670000000000 0.7083330000000000 0.1250000000000000 O
+ 0.1250000000000000 0.1250000000000000 0.8750000000000000 O
+ 0.3750000000000000 0.3750000000000000 0.1250000000000000 O
+ 0.2083330000000000 0.0416670000000000 0.6250000000000000 O
+ 0.2916670000000000 0.9583330000000000 0.8750000000000000 O
+ 0.1250000000000000 0.6250000000000000 0.8750000000000000 O
+ 0.3750000000000000 0.8750000000000000 0.1250000000000000 O
+ 0.2083330000000000 0.5416670000000000 0.1250000000000000 O
+ 0.2083330000000000 0.0416670000000000 0.1250000000000000 O