deploy: 918a729

_sources/apidocs/easyunfold/easyunfold.cli.md

@@ -132,7 +132,7 @@
 ```
 ````
 
-````{py:function} generate(pc_file, code, sc_file, matrix, kpoints, time_reversal, out_file, no_expand, symprec, nk_per_split, scf_kpoints, yes)
+````{py:function} generate(pc_file, code, sc_file, matrix, kpoints, time_reversal, out_file, no_expand, symprec, nk_per_split, scf_kpoints, yes, separate_folders)
 :canonical: easyunfold.cli.generate
 
 ```{autodoc2-docstring} easyunfold.cli.generate
@@ -167,7 +167,7 @@
 ```
 ````
 
-````{py:function} unfold_effective_mass(ctx, intensity_threshold, spin, band_filter, npoints, extrema_detect_tol, degeneracy_detect_tol, nocc, plot, plot_fit, fit_label, out_file)
+````{py:function} unfold_effective_mass(ctx, intensity_threshold, spin, band_filter, npoints, extrema_detect_tol, nocc, plot, plot_fit, fit_label, out_file, emin, emax, manual_extrema)
 :canonical: easyunfold.cli.unfold_effective_mass
 
 ```{autodoc2-docstring} easyunfold.cli.unfold_effective_mass

_sources/apidocs/easyunfold/easyunfold.effective_mass.md

@@ -125,14 +125,14 @@
 ```
 ````
 
-````{py:function} points_with_tol(array, value, tol=0.0001)
+````{py:function} points_with_tol(array, value, tol=0.0001, sign=1)
 :canonical: easyunfold.effective_mass.points_with_tol
 
 ```{autodoc2-docstring} easyunfold.effective_mass.points_with_tol
 ```
 ````
 
-`````{py:class} EffectiveMass(unfold: easyunfold.unfold.UnfoldKSet, intensity_tol: float = 0.1, extrema_tol: float = 0.001, degeneracy_tol: float = 0.01, parabolic: bool = True, npoints: float = 3)
+`````{py:class} EffectiveMass(unfold: easyunfold.unfold.UnfoldKSet, intensity_tol: float = 0.1, extrema_tol: float = 0.001, parabolic: bool = True, npoints: float = 3)
 :canonical: easyunfold.effective_mass.EffectiveMass
 
 ```{autodoc2-docstring} easyunfold.effective_mass.EffectiveMass
@@ -168,7 +168,7 @@
 
 ````
 
-````{py:method} get_band_extrema(mode: str = 'cbm', extrema_tol: float = None, degeneracy_tol: float = None, ispin=0)
+````{py:method} get_band_extrema(mode: str = 'cbm', extrema_tol: float = None, ispin=0)
 :canonical: easyunfold.effective_mass.EffectiveMass.get_band_extrema
 
 ```{autodoc2-docstring} easyunfold.effective_mass.EffectiveMass.get_band_extrema
@@ -192,23 +192,15 @@
 
 ````
 
-````{py:method} get_npoints(override: typing.Union[float, None] = None)
-:canonical: easyunfold.effective_mass.EffectiveMass.get_npoints
-
-```{autodoc2-docstring} easyunfold.effective_mass.EffectiveMass.get_npoints
-```
-
-````
-
-````{py:method} get_effective_masses(npoints: typing.Union[float, None] = None, ispin=0)
+````{py:method} get_effective_masses(npoints: typing.Union[float, None] = None, ispin=0, iks=None, iband=None, mode=None)
 :canonical: easyunfold.effective_mass.EffectiveMass.get_effective_masses
 
 ```{autodoc2-docstring} easyunfold.effective_mass.EffectiveMass.get_effective_masses
 ```
 
 ````
 
-````{py:method} _get_effective_masses(mode: str = 'cbm', ispin: int = 0, npoints: typing.Union[None, int] = None)
+````{py:method} _get_effective_masses(mode: str = 'cbm', ispin: int = 0, npoints: typing.Union[None, int] = None, iks=None, iband=None)
 :canonical: easyunfold.effective_mass.EffectiveMass._get_effective_masses
 
 ```{autodoc2-docstring} easyunfold.effective_mass.EffectiveMass._get_effective_masses

_sources/apidocs/easyunfold/easyunfold.plotting.md

@@ -53,6 +53,7 @@
 
 ````{py:method} plot_dos(ax, dos_plotter, dos_label, dos_options, ylim, eref, atoms=None, colours=None, orbitals_subplots=None)
 :canonical: easyunfold.plotting.UnfoldPlotter.plot_dos
+:staticmethod:
 
 ```{autodoc2-docstring} easyunfold.plotting.UnfoldPlotter.plot_dos
 ```

_sources/apidocs/easyunfold/easyunfold.unfold.md

@@ -256,7 +256,7 @@ Bases: {py:obj}`monty.json.MSONable`
 
 ````
 
-````{py:method} write_sc_kpoints(file: str, nk_per_split: typing.Union[None, list] = None, scf_kpoints_and_weights: typing.Union[None, list] = None, **kwargs)
+````{py:method} write_sc_kpoints(file: str, nk_per_split: typing.Union[None, list] = None, scf_kpoints_and_weights: typing.Union[None, list] = None, use_separate_folders=False, **kwargs)
 :canonical: easyunfold.unfold.UnfoldKSet.write_sc_kpoints
 
 ```{autodoc2-docstring} easyunfold.unfold.UnfoldKSet.write_sc_kpoints

_sources/examples/example_mgo.md

@@ -108,3 +108,58 @@ Unfolded MgO band structure with atomic projections plotted separately.
 There are _many_ customisation options available for the plotting functions in `easyunfold`. See `easyunfold plot -h` or 
 `easyunfold unfold plot-projections -h` for more details!
 :::
+
+
+The command `easyunfold unfold effective-mass` can be used to find the effective masses of the unfolded band structure.
+
+The example output is shown below:
+
+```
+Loaded data from easyunfold.json
+Band extrema data:
+  Kpoint index  Kind      Sub-kpoint index    Band indices
+--------------  ------  ------------------  --------------
+             0  cbm                      0              16
+            47  cbm                      0              16
+             0  vbm                      0              15
+            47  vbm                      0              15
+
+Electron effective masses:
+  index  Kind      Effective mass    Band index  from                      to
+-------  ------  ----------------  ------------  ------------------------  -------------------
+      0  m_e             0.373553            16  [0.0, 0.0, 0.0] (\Gamma)  [0.5, 0.5, 0.5] (L)
+      1  m_e             0.367203            16  [0.0, 0.0, 0.0] (\Gamma)  [0.5, 0.0, 0.5] (X)
+
+Hole effective masses:
+  index  Kind      Effective mass    Band index  from                      to
+-------  ------  ----------------  ------------  ------------------------  -------------------
+      0  m_h             -3.44604            15  [0.0, 0.0, 0.0] (\Gamma)  [0.5, 0.5, 0.5] (L)
+      1  m_h             -2.13525            15  [0.0, 0.0, 0.0] (\Gamma)  [0.5, 0.0, 0.5] (X)
+Unfolded band structure can be ambiguous, please cross-check with the spectral function plot.
+```
+
+If detected band extrema are not consistent with the band structure, one should adjust the `--intensity-tol` and `--extrema-detect-tol`.
+Increasing the value of `--intensity-tol` will filter away bands with very small spectral weights.
+On the other hand, increasing `--extrema-detect-tol` will increase the energy window with respect 
+to the VBM or CBM to assign extrema points. 
+One can also inspect if the detected bands makes sense by using the `--plot` option.
+A Jupyter Notebook example can be found [here](../../examples/MgO/effective-mass.ipynb).
+
+
+```{figure} ../../examples/MgO/unfold-effective-mass.png
+:width: 800 px
+:alt: Effective bands extracted  
+
+Extracted bands at CBM and VBM for an unfolded MgO band structure.
+```
+
+
+:::{warning}
+Make sure the band extrema data tabulated is correct and consistent before using any of the reported values.
+The results can unreliable for systems with little or no band gaps and those with complex unfolded band structures.
+:::
+
+
+:::{tip}
+For complex systems where the detection is difficult, one can manually pass the kpoint and the band indices using the `--manual-extrema` option.
+:::

_sources/index.md

@@ -21,7 +21,7 @@ package.
 For the methodology of supercell band unfolding, see 
 [here](https://link.aps.org/doi/10.1103/PhysRevB.85.085201).
 
-### Example Outputs
+## Example Outputs
 | [Cs₂(Sn/Ti)Br₆ Vacancy-Ordered Perovskite Alloys](https://doi.org/10.1021/acs.jpcc.3c05204) |                        Oxygen Vacancy (*V*ₒ⁰) in MgO                         |
 |:-------------------------------------------------------------------------------------------:|:---------------------------------------------------------------------------:|
 |                      <img src="img/CSTB_easyunfold.gif" height="400"/>                      | <img src="../examples/MgO/unfold_project_MgO_v_O_0_tall.png" height="400"/> |

_sources/theory.md

@@ -74,5 +74,40 @@ cell, followed by a reduction using the symmetry of the supercell. The spectral
 is then a weighted combination of that set of $\vec{k_s^\prime}$ points that are inequivalent under the 
 symmetry of the supercell.
 
+
+## Cell and Transformation Matrix convention
+
+The cell matrix may be consisted of column or row lattice vectors. In this package we use the **row vector**
+convention as commonly found in many post-processing tools and DFT codes. The cell matrix is defined as:
+
+$$
+\mathbf{C} = \begin{pmatrix}
+x_a & y_a & z_a \\
+x_b & y_b & z_b \\
+x_c & y_c & z_c
+\end{pmatrix}
+$$
+
+where $x_a$, $y_a$, $z_a$ are components of the lattice vector $\mathbf{a}$.
+
+The cell matrix of the supercell $\mathbf{C_s}$ is obtained by (left) multiplying the original unit cell $\mathbf{C_u}$ by the transformation matrix $\mathbf{M}$:
+
+
+$$
+\mathbf{C_{s}} = \mathbf{M} \, \mathbf{C_u}
+$$
+
+:::{note}
+Sometimes the cell matrix is defined by **column** vectors of the lattice parameters, e.g. $\mathbf{C_u^c} = \mathbf{C_u^T}$, and the relationship becomes:
+$$
+\mathbf{C_u^c} = \mathbf{C_u^T} \, \mathbf{M^T}
+$$
+
+Hence, when the column vector convention is used, the transformation matrix is the **transpose** of that used by the row convention.
+
+One example of code using the column vector convention is [Phonopy](https://phonopy.github.io/phonopy/setting-tags.html#dim).
+:::
+
+
 [^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.

_static/locales/ar/LC_MESSAGES/booktheme.po

@@ -8,68 +8,68 @@ msgstr ""
 "Language: ar\n"
 "Plural-Forms: nplurals=2; plural=(n != 1);\n"
 
+msgid "Download source file"
+msgstr "تنزيل ملف المصدر"
+
 msgid "suggest edit"
 msgstr "أقترح تحرير"
 
-msgid "Last updated on"
-msgstr "آخر تحديث في"
-
-msgid "Edit this page"
-msgstr "قم بتحرير هذه الصفحة"
-
-msgid "Launch"
-msgstr "إطلاق"
-
-msgid "Print to PDF"
-msgstr "طباعة إلى PDF"
+msgid "Toggle navigation"
+msgstr "تبديل التنقل"
 
 msgid "open issue"
 msgstr "قضية مفتوحة"
 
 msgid "Download notebook file"
 msgstr "تنزيل ملف دفتر الملاحظات"
 
-msgid "Toggle navigation"
-msgstr "تبديل التنقل"
+msgid "repository"
+msgstr "مخزن"
 
-msgid "Source repository"
-msgstr "مستودع المصدر"
+msgid "Theme by the"
+msgstr "موضوع بواسطة"
 
-msgid "By the"
-msgstr "بواسطة"
+msgid "Print to PDF"
+msgstr "طباعة إلى PDF"
 
-msgid "next page"
-msgstr "الصفحة التالية"
+msgid "Download this page"
+msgstr "قم بتنزيل هذه الصفحة"
 
-msgid "repository"
-msgstr "مخزن"
+msgid "Copyright"
+msgstr "حقوق النشر"
+
+msgid "Last updated on"
+msgstr "آخر تحديث في"
+
+msgid "Launch"
+msgstr "إطلاق"
+
+msgid "Open an issue"
+msgstr "افتح قضية"
+
+msgid "Fullscreen mode"
+msgstr "وضع ملء الشاشة"
 
 msgid "Sphinx Book Theme"
 msgstr "موضوع كتاب أبو الهول"
 
-msgid "Download source file"
-msgstr "تنزيل ملف المصدر"
-
 msgid "Contents"
 msgstr "محتويات"
 
-msgid "By"
-msgstr "بواسطة"
+msgid "Edit this page"
+msgstr "قم بتحرير هذه الصفحة"
 
-msgid "Copyright"
-msgstr "حقوق النشر"
+msgid "next page"
+msgstr "الصفحة التالية"
 
-msgid "Fullscreen mode"
-msgstr "وضع ملء الشاشة"
+msgid "Source repository"
+msgstr "مستودع المصدر"
 
-msgid "Open an issue"
-msgstr "افتح قضية"
+msgid "By"
+msgstr "بواسطة"
+
+msgid "By the"
+msgstr "بواسطة"
 
 msgid "previous page"
 msgstr "الصفحة السابقة"
-
-msgid "Download this page"
-msgstr "قم بتنزيل هذه الصفحة"
-
-msgid "Theme by the"
-msgstr "موضوع بواسطة"