Updated tutorial 2 docs

docs/_static/tutorials/fetch.py

@@ -21,8 +21,7 @@ def extract(filename_in, filename_out, start=0, end=None, heading=None):
             if not line.startswith(' ' * (indent + 1)):
                 end = i
                 break
-
-        if end is None:
+        else:
             raise ValueError(f'Could not find the end of the {heading} block')
 
     flines = flines[start:end]
@@ -41,6 +40,14 @@ def extract(filename_in, filename_out, start=0, end=None, heading=None):
 
 if __name__ == '__main__':
 
+    # Tutorial 2
+    extract('../../../tutorials/tutorial_2/si_wannierize.md', 'tutorial_2/md_excerpts/si_wannierize.md', start=18)
+    extract('../../../tutorials/tutorial_2/si_ki.md', 'tutorial_2/md_excerpts/si_ki_wannierize.md', heading="Wannierize")
+    extract('../../../tutorials/tutorial_2/si_ki.md', 'tutorial_2/md_excerpts/si_ki_fold.md', heading="Fold To Supercell")
+    extract('../../../tutorials/tutorial_2/si_ki.md', 'tutorial_2/md_excerpts/si_ki_screening.md', 51, 61)
+    extract('../../../tutorials/tutorial_2/si_ki.md',
+            'tutorial_2/md_excerpts/si_ki_postproc.md', heading="Unfold And Interpolate")
+
     # Tutorial 3
     extract('../../../tutorials/tutorial_3/01-ki/zno.md',
             'tutorial_3/md_excerpts/zno_wannierize_section.md', heading='Wannierize')

docs/_static/tutorials/tutorial_2/md_excerpts/si_ki_fold.md

@@ -0,0 +1,3 @@
+- **Fold To Supercell**
+  - ✅ `01-convert_block_1_to_supercell` completed  
+  - ✅ `02-convert_block_2_to_supercell` completed  

docs/_static/tutorials/tutorial_2/md_excerpts/si_ki_postproc.md

@@ -0,0 +1,16 @@
+- **Unfold And Interpolate**
+  - **Wannierize**
+    - ✅ `01-scf` completed  
+    - ✅ `02-nscf` completed  
+    - **Wannierize Block 1**
+      - ✅ `01-wannier90_preproc` completed  
+      - ✅ `02-pw2wannier90` completed  
+      - ✅ `03-wannier90` completed  
+    - **Wannierize Block 2**
+      - ✅ `01-wannier90_preproc` completed  
+      - ✅ `02-pw2wannier90` completed  
+      - ✅ `03-wannier90` completed  
+    - ✅ `05-bands` completed  
+    - ✅ `06-projwfc` completed  
+  - ✅ `02-unfold_and_interpolate_occ` completed  
+  - ✅ `03-unfold_and_interpolate_emp` completed  

docs/_static/tutorials/tutorial_2/md_excerpts/si_ki_screening.md

@@ -0,0 +1,9 @@
+   - **Calculate Screening Via DSCF**
+     - **Iteration 1**
+       - ✅ `01-ki` completed  
+       - **Orbital 32**
+         - ✅ `01-dft_n-1` completed  
+       - **Orbital 33**
+         - ✅ `01-dft_n+1_dummy` completed  
+         - ✅ `02-pz_print` completed  
+         - ✅ `03-dft_n+1` completed  

docs/_static/tutorials/tutorial_2/md_excerpts/si_ki_wannierize.md

@@ -0,0 +1,11 @@
+- **Wannierize**
+  - ✅ `01-scf` completed  
+  - ✅ `02-nscf` completed  
+  - **Wannierize Block 1**
+    - ✅ `01-wannier90_preproc` completed  
+    - ✅ `02-pw2wannier90` completed  
+    - ✅ `03-wannier90` completed  
+  - **Wannierize Block 2**
+    - ✅ `01-wannier90_preproc` completed  
+    - ✅ `02-pw2wannier90` completed  
+    - ✅ `03-wannier90` completed  

docs/_static/tutorials/tutorial_2/md_excerpts/si_wannierize.md

@@ -0,0 +1,13 @@
+ - ✅ `01-scf` completed  
+ - ✅ `02-nscf` completed  
+ - **Wannierize Block 1**
+   - ✅ `01-wannier90_preproc` completed  
+   - ✅ `02-pw2wannier90` completed  
+   - ✅ `03-wannier90` completed  
+ - **Wannierize Block 2**
+   - ✅ `01-wannier90_preproc` completed  
+   - ✅ `02-pw2wannier90` completed  
+   - ✅ `03-wannier90` completed  
+ - ✅ `05-bands` completed  
+ - ✅ `06-projwfc` completed  
+ **Workflow complete** 🎉

docs/conf.py

@@ -72,7 +72,7 @@
 
 # -- Autodoc options ----------------------------------------------------------
 autodoc_typehints = 'none'
-autodoc_mock_imports = ['ase']
+autodoc_mock_imports = ['ase', 'pydantic']
 numpydoc_show_class_members = False
 
 # -- Chronological bibliography style -----------------------------------------

docs/input_file.rst

@@ -128,7 +128,7 @@ These individual projections (either as dictionaries or as strings) must be prov
 
 We can achieve both of the above via the list-of-lists syntax. Consider the following example for the wannierization of bulk ZnO
 
-.. literalinclude:: ../tutorials/tutorial_3/zno.json
+.. literalinclude:: ../tutorials/tutorial_3/01-ki/zno.json
   :lines: 47-55
   :dedent:
 

docs/tutorials/tutorial_2.rst

@@ -80,44 +80,48 @@ We run this calculation as per usual:
 
 .. code-block:: bash
 
-  koopmans si.json | tee si_wannierize.out
+  koopmans si.json | tee si_wannierize.md
 
 After the usual header, you should see something like the following:
 
-.. literalinclude:: ../../tutorials/tutorial_2/si_wannierize.out
-  :lines: 15-
+----
 
-These various calculations that are required to obtain the MLWFs of bulk silicon. You can inspect the  and various output files will have been generated in a new ``wannier/`` directory.
+.. include:: ../_static/tutorials/tutorial_2/md_excerpts/si_wannierize.md
+  :parser: myst_parser.sphinx_
+
+----
+
+These various calculations that are required to obtain the MLWFs of bulk silicon. You can inspect the  and various output files will have been generated in corresponding directories.
 
 .. collapse:: Click here for detailed descriptions of each calculation
 
-  scf
+  ``01-scf``
     a ``pw.x`` self-consistent DFT calculation performed with no empty bands. This obtains the ground-state electronic density
 
-  nscf
+  ``02-nscf``
     a ``pw.x`` non-self-consistent DFT calculation that determines the Hamiltonian, now including some empty bands
 
-  block_1/wann_preproc
+  ``03-wannierize-block-1/01-wannier_preproc``
     a preprocessing ``wannier90.x`` calculation that generates some files required by ``pw2wannier90.x``
 
-  block_1/pw2wan
-    a ``pw2wannier90.x`` calculation that extracts from the eariler ``pw.x`` calculations several key quantities required for generating the Wannier orbitals for the occupied manifold: namely, the overlap matrix of the cell-periodic part of the Block states (this is the ``wann.mmn`` file) and the projection of the Bloch states onto some trial localised orbitals (``wann.amn``)
+  ``03-wannierize-block-1/02-pw2wannier90``
+    a ``pw2wannier90.x`` calculation that extracts from the eariler ``pw.x`` calculations several key quantities required for generating the Wannier orbitals for the occupied manifold: namely, the overlap matrix of the cell-periodic part of the Block states (this is the ``wannier90.mmn`` file) and the projection of the Bloch states onto some trial localised orbitals (``wannier90.amn``)
 
-  block_1/wann
+  ``03-wannierize-block-1/03-wannier90``
     the ``wannier90.x`` calculation that obtains the MLWFs for the occupied manifold
 
-  block_2/...
-    the analogous calculations as those in ``occ/``, but for the empty manifold
+  ``04-wannierize-block-2/...``
+    the analogous calculations as those in ``03-wannierize-block-1/``, but for the empty manifold
 
-  bands
+  ``05-bands``
     a ``pw.x`` calculation that calculates the band structure of silicon explicitly, used for verification of the Wannierization (see the next section)
 
-  pdos/projwfc
+  ``06-projwfc``
     a ``projwfc.x`` calculation that calculates the projected density of states, also used for checking the Wannierization
 
 |
 
-The main output files of interest in ``wannier/`` are files ``block_1/wann.wout`` and ``block_2/wann.wout``, which contain the output of ``wannier90.x`` for the Wannierization of the occupied and empty manifolds. If you inspect either of these files you will be able to see a lot of starting information, and then under a heading like
+The main output files of interest are the files ``03-wannierize-block-1/03-wannier90/wannier90.wout`` and ``04-wannierize-block-2/03-wannier90/wannier90.wout``, which contain the output of ``wannier90.x`` for the Wannierization of the occupied and empty manifolds. If you inspect either of these files you will be able to see a lot of starting information, and then under a heading like
 
 .. code-block::
 
@@ -132,9 +136,9 @@ How do I know if the Wannier functions I have calculated are "good"?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Performing a Wannierization calculation is not a straightforward procedure, and requires the tweaking of the Wannier90 input parameters in order to obtain a "good" set of Wannier functions.
 
-One check is to see if an interpolated bandstructure generated by the MLWFs resembles an explicitly-calculated band structure. (For an explanation of how one can use Wannier functions to interpolate band structures, refer to Ref. :cite:`Marzari2012`.) You might have noticed that when we ran ``koopmans`` earlier it also generated a file called ``si_wannierize_bandstructure.png``. It should look something like this:
+One check is to see if an interpolated bandstructure generated by the MLWFs resembles an explicitly-calculated band structure. (For an explanation of how one can use Wannier functions to interpolate band structures, refer to Ref. :cite:`Marzari2012`.) You might have noticed that when we ran ``koopmans`` earlier it also generated a file called ``si_bandstructure.png``. It should look something like this:
 
-.. figure:: ../../tutorials/tutorial_2/2x2x2/si_wannierize_bandstructure.png
+.. figure:: ../../tutorials/tutorial_2/2x2x2/si_bandstructure.png
   :width: 400
   :align: center
   :alt: comparison of the interpolated and explicitly-calculated band structures of silicon
@@ -150,7 +154,7 @@ Clearly, we can see that the interpolation is no good! (The interpolated band st
   .. literalinclude:: ../../tutorials/tutorial_2/wannierize.py
 
 .. tip::
-  You may also notice a file called ``si_wannierize_bandstructure.fig.pkl``. This is a version of the figure that you can load in python and modify as you see fit. e.g. here is a script that changes the y-axis limits and label:
+  You may also notice a file called ``si_bandstructure.fig.pkl``. This is a version of the figure that you can load in python and modify as you see fit. e.g. here is a script that changes the y-axis limits and label:
 
   .. literalinclude:: ../../tutorials/tutorial_2/load_pickled_figure.py
 
@@ -166,31 +170,36 @@ Initialization
 ^^^^^^^^^^^^^^
 If you run this new input the output will be remarkably similar to that from the previous tutorial, with a couple of exceptions. At the start of the workflow you will see there is a Wannierization procedure, much like we had earlier when we running with the ``wannierize`` task:
 
-.. literalinclude:: ../../tutorials/tutorial_2/si_ki.out
-  :lines: 20-31
-  :lineno-start: 20
-  :language: text
+----
+
+.. include:: ../_static/tutorials/tutorial_2/md_excerpts/si_ki_wannierize.md
+  :parser: myst_parser.sphinx_
+
+----
 
 which replaces the previous series of semi-local and PZ calculations that we used to initialize the variational orbitals for a molecule.
 
 There is then an new "folding to supercell" subsection:
 
-.. literalinclude:: ../../tutorials/tutorial_2/si_ki.out
-  :lines: 32-35
-  :lineno-start: 32
-  :language: text
+----
+
+.. include:: ../_static/tutorials/tutorial_2/md_excerpts/si_ki_fold.md
+  :parser: myst_parser.sphinx_
+
+----
 
 In order to understand what these calculations are doing, we must think ahead to the next step in our calculation, where we will calculate the screening parameters using the ΔSCF method. These calculations, where we remove/add an electron from/to the system, require us to work in a supercell. This means that we must transform the :math:`k`-dependent primitive cell results from previous calculations into equivalent :math:`\Gamma`-only supercell quantities that can be read by ``kcp``. This is precisely what the above ``wan2odd`` calculations do.
 
 Calculating the screening parameters
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Having transformed into a supercell, the calculation of the screening parameters proceeds as usual. The one difference to tutorial 1 that you might notice at this step is that we are skipping the calculation of screening parameters for some of the orbitals:
 
-.. literalinclude:: ../../tutorials/tutorial_2/si_ki.out
-  :lines: 42-52
-  :lineno-start: 42
-  :emphasize-lines: 7
-  :language: text
+----
+
+.. include:: ../_static/tutorials/tutorial_2/md_excerpts/si_ki_screening.md
+  :parser: myst_parser.sphinx_
+
+----
 
 The code is doing this because of what we provided for the ``orbital_groups`` in the input file:
 
@@ -205,10 +214,12 @@ The final calculation and postprocessing
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 The final difference for the solids calculation is that there is an additional preprocessing step at the very end:
 
-.. literalinclude:: ../../tutorials/tutorial_2/si_ki.out
-  :lines: 89-
-  :lineno-start: 89
-  :language: text
+----
+
+.. include:: ../_static/tutorials/tutorial_2/md_excerpts/si_ki_postproc.md
+  :parser: myst_parser.sphinx_
+
+----
 
 Here, we transform back our results from the supercell sampled at :math:`\Gamma` to the primitive cell with :math:`k`-space sampling. This allows us to obtain a bandstructure. The extra Wannierization step that is being performed is to assist the interpolation of the band structure in the primitive cell, and has been performed because in the input file we specified
 
@@ -221,7 +232,7 @@ For more details on the "unfold and interpolate" procedure see :ref:`here <input
 
 Extracting the KI bandstructure and the bandgap of Si
 -----------------------------------------------------
-The bandstructure can be found in ``postproc/bands_interpolated.dat`` as a raw data file, but there is a more flexible way for plotting the final bandstructure using the python machinery of ``koopmans``:
+The bandstructure can be found in ``01-koopmans-dscf/04-unfold-and-interpolate/02-unfold_and_interpolate_occ`` and ``01-koopmans-dscf/04-unfold-and-interpolate/03-unfold_and_interpolate_emp`` as raw data files, but there is a more flexible way for plotting the final bandstructure using the python machinery of ``koopmans``:
 
 .. literalinclude:: ../../tutorials/tutorial_2/plot_bandstructure.py
 

src/koopmans/processes/power_spectrum.py

@@ -6,6 +6,7 @@
 
 import numpy as np
 from ase.cell import Cell
+from pydantic import ConfigDict
 
 from koopmans import ml, utils
 from koopmans.bands import Band
@@ -15,6 +16,8 @@
 
 
 class ExtractCoefficientsFromXMLInput(IOModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
     n_max: int
     l_max: int
     r_min: float
@@ -26,19 +29,15 @@ class ExtractCoefficientsFromXMLInput(IOModel):
     orbital_densities_xml: List[FilePointer]
     bands: List[Band]
 
-    class Config:
-        arbitrary_types_allowed = True
-
 
 class ExtractCoefficientsFromXMLOutput(IOModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
     precomputed_alphas: FilePointer
     precomputed_betas: FilePointer
     total_coefficients: List[FilePointer]
     orbital_coefficients: List[FilePointer]
 
-    class Config:
-        arbitrary_types_allowed = True
-
 
 class ExtractCoefficientsFromXMLProcess(Process):
 

src/koopmans/processes/ui/_process.py

@@ -67,7 +67,7 @@ class UnfoldAndInterpolateOutputs(IOModel):
     model_config = ConfigDict(arbitrary_types_allowed=True, frozen=True)
 
     band_structure: BandStructure
-    dos: DOS | None = None
+    dos: Optional[DOS] = None
 
 
 class UnfoldAndInterpolateProcess(Process):

src/koopmans/workflows/_unfold_and_interp.py

@@ -25,7 +25,7 @@
 
 class UnfoldAndInterpolateOutput(outputs.OutputModel):
     band_structure: BandStructure
-    dos: DOS | None
+    dos: Optional[DOS]
 
     class Config:
         arbitrary_types_allowed = True