diff --git a/_images/unfold.png b/_images/unfold.png
index fa9b41c..85c6d57 100644
Binary files a/_images/unfold.png and b/_images/unfold.png differ
diff --git a/_images/unfold1.png b/_images/unfold1.png
index c37dced..fa9b41c 100644
Binary files a/_images/unfold1.png and b/_images/unfold1.png differ
diff --git a/_images/unfold2.png b/_images/unfold2.png
new file mode 100644
index 0000000..c37dced
Binary files /dev/null and b/_images/unfold2.png differ
diff --git a/_sources/examples/example_mgo.md b/_sources/examples/example_mgo.md
index 51697fa..c9c500e 100644
--- a/_sources/examples/example_mgo.md
+++ b/_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.
+:::
\ No newline at end of file
diff --git a/_sources/examples/example_si222.md b/_sources/examples/example_si222.md
index 73b835f..fbc0e60 100644
--- a/_sources/examples/example_si222.md
+++ b/_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.
diff --git a/_sources/index.md b/_sources/index.md
index b0609ce..3214a1f 100644
--- a/_sources/index.md
+++ b/_sources/index.md
@@ -25,6 +25,10 @@ For the methodology of supercell band unfolding, see
|:-------------------------------------------------------------------------------------------:|:---------------------------------------------------------------------------:|
| | |
+:::{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:
diff --git a/_sources/tutorial.md b/_sources/tutorial.md
index c840970..cec8c85 100644
--- a/_sources/tutorial.md
+++ b/_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:
diff --git a/apidocs/easyunfold/easyunfold.cli.html b/apidocs/easyunfold/easyunfold.cli.html
index 5ca553c..a9a0642 100644
--- a/apidocs/easyunfold/easyunfold.cli.html
+++ b/apidocs/easyunfold/easyunfold.cli.html
@@ -193,8 +193,8 @@
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.
As shown in the easyunfold YouTube tutorial, 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.
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:
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:
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 dopedDefectsGenerator.supercell_matrix attribute and supply this with the --matrix option.
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 folder.