Develop

CHANGELOG.rst

@@ -1,6 +1,15 @@
 Change Log
 ==========
 
+v.2.4.7
+----------
+- Update doping/carrier concentration functions to be more accurate and robust (following logic discussed
+  here: https://github.com/materialsproject/pymatgen/pull/3879).
+- Improve reverse-supercell-matrix determination for `generate_supercell=False`
+- Refactor `bulk_band_gap_path` to `bulk_band_gap_vr` in `DefectsParser`/`DefectParser`,
+- Update docstrings to reiterate that bulk supercell VBM is used as VBM reference point for the Fermi level
+  by default, unless alternative `bulk_band_gap_vr` provided.
+
 v.2.4.6
 ----------
 - Update ``Defect``, ``DefectEntry`` and ``DefectThermodynamics`` properties/methods to be even more

README.md

@@ -68,7 +68,7 @@ Solar Absorbers: In-depth Investigation into CuSbSe<sub>2</sub>_** [_arXiv_](htt
 - J. Hu et al. **_Enabling ionic transport in Li3AlP2 the roles of defects and disorder_** [_ChemRxiv_](https://doi.org/10.26434/chemrxiv-2024-3s0kh) 2024
 - X. Wang et al. **_Upper efficiency limit of Sb<sub>2</sub>Se<sub>3</sub> solar cells_** [_Joule_](https://doi.org/10.1016/j.joule.2024.05.004) 2024
 - I. Mosquera-Lois et al. **_Machine-learning structural reconstructions for accelerated point defect calculations_** [_npj Computational Materials_](https://doi.org/10.1038/s41524-024-01303-9) 2024
-- W. Dou et al. **_Giant Band Degeneracy via Orbital Engineering Enhances Thermoelectric Performance from Sb<sub>2</sub>Si<sub>2</sub>Te<sub>6</sub> to Sc<sub>2</sub>Si<sub>2</sub>Te<sub>6</sub>_** [_ChemRxiv_](https://doi.org/10.26434/chemrxiv-2024-hm6vh) 2024
+- W. Dou et al. **_Band Degeneracy and Anisotropy Enhances Thermoelectric Performance from Sb<sub>2</sub>Si<sub>2</sub>Te<sub>6</sub> to Sc<sub>2</sub>Si<sub>2</sub>Te<sub>6</sub>_** [_Journal of the American Chemical Society_](https://doi.org/10.1021/jacs.4c01838) 2024
 - K. Li et al. **_Computational Prediction of an Antimony-based n-type Transparent Conducting Oxide: F-doped Sb<sub>2</sub>O<sub>5</sub>_** [_Chemistry of Materials_](https://doi.org/10.1021/acs.chemmater.3c03257) 2023
 - X. Wang et al. **_Four-electron negative-U vacancy defects in antimony selenide_** [_Physical Review B_](https://journals.aps.org/prb/abstract/10.1103/PhysRevB.108.134102) 2023
 - Y. Kumagai et al. **_Alkali Mono-Pnictides: A New Class of Photovoltaic Materials by Element Mutation_** [_PRX Energy_](http://dx.doi.org/10.1103/PRXEnergy.2.043002) 2023

docs/conf.py

@@ -25,7 +25,7 @@
 author = 'Seán R. Kavanagh'
 
 # The full version, including alpha/beta/rc tags
-release = '2.4.6'
+release = '2.4.7'
 
 
 # -- General configuration ---------------------------------------------------

docs/index.rst

@@ -96,7 +96,7 @@ Studies using ``doped``, so far
 - J\. Hu et al. **Enabling ionic transport in Li3AlP2 the roles of defects and disorder** `ChemRxiv <https://doi.org/10.26434/chemrxiv-2024-3s0kh>`_ 2024
 - X\. Wang et al. **Upper efficiency limit of Sb₂Se₃ solar cells** `Joule <https://doi.org/10.1016/j.joule.2024.05.004>`_ 2024
 - I\. Mosquera-Lois et al. **Machine-learning structural reconstructions for accelerated point defect calculations** `npj Computational Materials <https://doi.org/10.1038/s41524-024-01303-9>`_ 2024
-- W\. Dou et al. **Giant Band Degeneracy via Orbital Engineering Enhances Thermoelectric Performance from Sb₂Si₂Te₆ to Sc₂Si₂Te₆** `ChemRxiv <https://doi.org/10.26434/chemrxiv-2024-hm6vh>`_ 2024
+- W\. Dou et al. **Band Degeneracy and Anisotropy Enhances Thermoelectric Performance from Sb₂Si₂Te₆ to Sc₂Si₂Te₆** `Journal of the American Chemical Society <https://doi.org/10.1021/jacs.4c01838>`_ 2024
 - K\. Li et al. **Computational Prediction of an Antimony-based n-type Transparent Conducting Oxide: F-doped Sb₂O₅** `Chemistry of Materials <https://doi.org/10.1021/acs.chemmater.3c03257>`_ 2024
 - X\. Wang et al. **Four-electron negative-U vacancy defects in antimony selenide** `Physical Review B <https://journals.aps.org/prb/abstract/10.1103/PhysRevB.108.134102>`_ 2023
 - Y\. Kumagai et al. **Alkali Mono-Pnictides: A New Class of Photovoltaic Materials by Element Mutation** `PRX Energy <http://dx.doi.org/10.1103/PRXEnergy.2.043002>`__ 2023

doped/core.py

@@ -920,12 +920,14 @@ def formation_energy(
                 provided/present in format generated by ``doped`` (see tutorials).
                 (Default: None)
             vbm (float):
-                VBM eigenvalue in the bulk supercell, to use as Fermi level reference
-                point for calculating formation energy. If None (default), will use
-                "vbm" from the calculation_metadata dict attribute if present.
+                VBM eigenvalue to use as Fermi level reference point for calculating
+                formation energy. If ``None`` (default), will use ``"vbm"`` from the
+                ``calculation_metadata`` dict attribute if present -- which corresponds
+                to the VBM of the `bulk supercell` calculation by default, unless
+                ``bulk_band_gap_vr`` is set during defect parsing).
             fermi_level (float):
-                Value corresponding to the electron chemical potential,
-                referenced to the VBM. Default is 0 (i.e. the VBM).
+                Value corresponding to the electron chemical potential, referenced
+                to the VBM eigenvalue. Default is 0 (i.e. the VBM).
 
         Returns:
             Formation energy value (float)
@@ -1108,9 +1110,11 @@ def equilibrium_concentration(
             temperature (float):
                 Temperature in Kelvin at which to calculate the equilibrium concentration.
             vbm (float):
-                VBM eigenvalue in the bulk supercell, to use as Fermi level reference
-                point for calculating formation energy. If None (default), will use
-                "vbm" from the calculation_metadata dict attribute if present.
+                VBM eigenvalue to use as Fermi level reference point for calculating
+                the formation energy. If ``None`` (default), will use ``"vbm"`` from the
+                ``calculation_metadata`` dict attribute if present -- which corresponds
+                to the VBM of the `bulk supercell` calculation by default, unless
+                ``bulk_band_gap_vr`` is set during defect parsing).
             fermi_level (float):
                 Value corresponding to the electron chemical potential,
                 referenced to the VBM. Default is 0 (i.e. the VBM).

doped/generation.py

@@ -1048,7 +1048,7 @@ def __init__(
         interstitial_coords: Optional[list] = None,
         generate_supercell: bool = True,
         charge_state_gen_kwargs: Optional[dict] = None,
-        supercell_gen_kwargs: Optional[dict] = None,
+        supercell_gen_kwargs: Optional[dict[str, Union[int, float, bool]]] = None,
         interstitial_gen_kwargs: Optional[dict] = None,
         target_frac_coords: Optional[list] = None,
         processes: Optional[int] = None,
@@ -1201,12 +1201,19 @@ class (such as ``clustering_tol``, ``stol``, ``min_dist`` etc), or to
         self.charge_state_gen_kwargs = (
             charge_state_gen_kwargs if charge_state_gen_kwargs is not None else {}
         )
-        self.supercell_gen_kwargs = supercell_gen_kwargs if supercell_gen_kwargs is not None else {}
-        self.interstitial_gen_kwargs = (
+        self.supercell_gen_kwargs: dict[str, Union[int, float, bool]] = {
+            "min_image_distance": 10.0,  # same as current pymatgen-analysis-defects `min_length` ( = 10)
+            "min_atoms": 50,  # different from current pymatgen-analysis-defects `min_atoms` ( = 80)
+            "ideal_threshold": 0.1,
+            "force_cubic": False,
+            "force_diagonal": False,
+        }
+        self.supercell_gen_kwargs.update(supercell_gen_kwargs if supercell_gen_kwargs is not None else {})
+        self.interstitial_gen_kwargs: dict[str, Union[int, float, bool]] = (
             interstitial_gen_kwargs if interstitial_gen_kwargs is not None else {}
         )
         self.target_frac_coords = target_frac_coords if target_frac_coords is not None else [0.5, 0.5, 0.5]
-        specified_min_image_distance = self.supercell_gen_kwargs.get("min_image_distance", 10)
+        specified_min_image_distance = self.supercell_gen_kwargs["min_image_distance"]
 
         if len(self.structure) == 1 and not self.generate_supercell:
             # raise error if only one atom in primitive cell and no supercell generated, as vacancy will
@@ -1258,22 +1265,16 @@ class (such as ``clustering_tol``, ``stol``, ``min_dist`` etc), or to
                 with warnings.catch_warnings():
                     warnings.filterwarnings("ignore", message="The 'warn' method is deprecated")
                     supercell_matrix = get_ideal_supercell_matrix(
-                        primitive_structure,
-                        min_atoms=self.supercell_gen_kwargs.get("min_atoms", 50),  # different from current
-                        # pymatgen-analysis-defects default `min_atoms` ( = 80)
-                        min_image_distance=specified_min_image_distance,  # same as current
-                        # pymatgen-analysis-defects default `min_length` ( = 10)
-                        ideal_threshold=self.supercell_gen_kwargs.get("ideal_threshold", 0.1),
-                        force_cubic=self.supercell_gen_kwargs.get("force_cubic", False),
-                        force_diagonal=self.supercell_gen_kwargs.get("force_diagonal", False),
+                        structure=primitive_structure,
                         pbar=pbar,
+                        **self.supercell_gen_kwargs,  # type: ignore
                     )
 
             if not self.generate_supercell or (
                 input_min_image_distance >= specified_min_image_distance
                 and (primitive_structure * supercell_matrix).num_sites
                 >= self.structure.num_sites
-                >= self.supercell_gen_kwargs.get("min_atoms", 0)
+                >= self.supercell_gen_kwargs["min_atoms"]
             ):
                 if input_min_image_distance < 10:
                     # input structure is <10 Å in at least one direction, and generate_supercell=False,
@@ -1285,7 +1286,6 @@ class (such as ``clustering_tol``, ``stol``, ``min_dist`` etc), or to
                         f"using input structure as defect & bulk supercells. Caution advised!"
                     )
 
-                # else input structure is greater than ``min_image_distance`` Å in each direction, and
                 # ``generate_supercell=False`` or input structure has fewer or same number of atoms as
                 # doped supercell, so use input structure: