Add is_shallow convenience function and test

Author: kavanase

doped/utils/eigenvalues.py

@@ -736,3 +736,22 @@ def _get_pot_diff_from_entry(defect_entry: DefectEntry):
         emp.plt.savefig(filename, bbox_inches="tight", transparent=True, backend=_get_backend(filename))
 
     return bes, fig
+
+
+def is_shallow(defect_entry: DefectEntry, default: bool = False) -> bool:
+    """
+    Return whether a ``DefectEntry`` is determined to be a shallow (perturbed
+    host) state, based on ``pydefect`` eigenvalue analysis.
+
+    Args:
+        defect_entry (DefectEntry):
+            ``doped`` ``DefectEntry`` object.
+        default (bool):
+            Default value to return if the eigenvalue analysis fails
+            (e.g. if eigenvalue data is not present).
+            Default is ``False``.
+    """
+    try:
+        return defect_entry.get_eigenvalue_analysis(plot=False).is_shallow
+    except Exception:
+        return default

tests/test_analysis.py

@@ -28,7 +28,7 @@
 )
 from doped.core import _orientational_degeneracy_warning
 from doped.generation import DefectsGenerator, get_defect_name_from_defect, get_defect_name_from_entry
-from doped.utils.eigenvalues import get_eigenvalue_analysis
+from doped.utils.eigenvalues import get_eigenvalue_analysis, is_shallow
 from doped.utils.parsing import (
     Vasprun,
     get_defect_type_and_composition_diff,
@@ -2913,6 +2913,7 @@ def _compare_band_edge_states_dicts(d1, d2, orb_diff_tol: float = 0.1):
         assert not any(
             [bes.has_donor_phs, bes.has_occupied_localized_state, bes.has_unoccupied_localized_state]
         )
+        assert is_shallow(dp.defect_dict["v_Cu_0"])
 
         print("Testing v_Cu_0 with plot = False")
         bes2 = dp.defect_dict["v_Cu_0"].get_eigenvalue_analysis(