API
py_sc_fermi.defect_charge_state module
- class py_sc_fermi.defect_charge_state.DefectChargeState(charge: int, degeneracy: int = 1, energy: float | None = None, fixed_concentration: float | None = None)[source]
Bases:
object
Class describing a single charge state (of a
DefectSpecies
).- Parameters:
charge (int) – charge of this
DefectChargeState
degeneracy (int) – degeneracy per unit cell
energy (float) – formation energy at E[Fermi] = 0
fixed_concentration (float) – fixed concentration per unit cell
- as_dict() dict [source]
generate a dictionary representation of the
DefectChargeState
- Returns:
dictionary representation of the
DefectChargeState
- Return type:
dict
- property charge: int
charge of the
DefectChargeState
- Returns:
charge
- Return type:
int
- property degeneracy: int
The degeneracy of the
DefectChargeState
(e.g. spin degeneracy)- Returns:
degeneracy per unit cell
- Return type:
int
- property energy: float | None
formation energy of the
DefectChargeState
at E[vbm] (E[Fermi] = 0)- Returns:
formation energy
- Return type:
Optional[float]
- fix_concentration(concentration: float) None [source]
Fixes the concentration (per unit cell) of this
DefectChargeState
- Parameters:
concentration (float) –
DefectChargeState
concentration per unit cell
- property fixed_concentration: float | None
fixed concentration of this
DefectChargeState
orNone
if the concentration is free to vary.- Returns:
fixed concentration per unit cell
- Return type:
Optional[float]
- classmethod from_dict(dictionary: dict) DefectChargeState [source]
generate a dictionary from a
DefectChargeState
object- Parameters:
dictionary (dict) – dictionary defining
DefectChargeState
. Any fixed concentration given should be provided per-unit cell- Returns:
object described by dictionary
- Return type:
- classmethod from_string(string: str, volume: float | None = None, frozen: bool = False) DefectChargeState [source]
Create a
DefectChargeState
from a given string. This method was envisaged for use as a way to read in defect charge states from an input file for SC-Fermi.If a user does wish to specify a defect charge state using this functionality, the string should be in the form:
charge formation_energy degeneracy
i.e. a defect with charge 2, formation energy of 0.1 eV and degeneracy of 2 would be specified as:
"2 0.1 2"
if the charge state has a fixed concentration, the string should be in the form:
charge concentration
i.e. a defect with charge 2, concentration of 1e21 per cm-3 would be specified as:
"2 1e21"
- Parameters:
string (str) – string representation of the
DefectChargeState
volume (Optional[float], optional) – volume of the unit cell, only if
frozen == True
. Defaults toNone
.frozen (bool, optional) – if
True
the concentration of thisDefectChargeState
cannot change when solving for a self consistent Fermi energy. Defaults toFalse
.
- Raises:
ValueError – if defect concentration is fixed, but
volume == None
- Returns:
relevant
DefectChargeState
object- Return type:
DefectChargeState
- get_concentration(e_fermi: float, temperature: float) float [source]
Calculate the concentration of this
DefectChargeState
at a specified Fermi energy and temperature, per site in the unit cell.- Parameters:
e_fermi (float) – Fermi energy.
temperature (float) – Temperature.
- Returns:
Concentration at the specified Fermi energy and temperature.
- Return type:
float
- get_formation_energy(e_fermi: float) float [source]
get the formation energy of this
DefectChargeState
at a given Fermi energy- Parameters:
e_fermi (float) – Fermi energy at which to calculate the formation energy
- Raises:
ValueError – if
DefectChargeState.energy == None
- Returns:
formation energy of
DefectChargeState
ate_fermi
- Return type:
float
py_sc_fermi.defect_species module
- class py_sc_fermi.defect_species.DefectSpecies(name: str, nsites: int, charge_states: Dict[int, DefectChargeState], fixed_concentration: float | None = None)[source]
Bases:
object
Class for individual defect species.
- Parameters:
name (str) – A unique identifying string for this defect species, e.g.
"V_O"
might be used for an oxygen vacancy.nsites (int) – Number of sites energetically degenerate sites where this defect can form in the unit cell (the site degeneracy).
charge_states (Dict[int, DefectChargeState]) – A dictionary of
DefectChargeState
with their charge as the key, i.e. {charge :DefectChargeState
}
- as_dict() dict [source]
get representation of
DefectSpecies
as a dictionary- Returns:
dictionary representation of
DefectChargeState
- Return type:
dict
- charge_state_concentrations(e_fermi: float, temperature: float) Dict[int, float] [source]
at a given Fermi energy and temperature, calculate the concentrations of the different
DefectChargeStates
of thisDefectSpecies
.- Parameters:
e_fermi (float) – Fermi energy
temperature (float) – temperature
- Returns:
key-value pairs of charge of each
DefectChargeState
and the concentration of theDefectChargeState
with that charge, i.e. {DefectChargeState.charge
: concentration}- Return type:
Dict[int, float]
- property charge_states: Dict[int, DefectChargeState]
Returns: Dict[int, DefectChargeState]: The charge states of this defect species as a dictionary of
{charge (int): DefectChargeState}
key-value pairs
- charge_states_by_formation_energy(e_fermi: float) List[DefectChargeState] [source]
Returns a list of charge states sorted by formation energy at a given Fermi energy.
- Parameters:
e_fermi (float) – Fermi energy
- Returns:
list of
DefectChargeState
objects in thisDefectSpecies
sorted by formation energy ate_fermi
.- Return type:
List[DefectChargeState]
Note
DefectChargeState
objects with fixed-concentration are not included in the returned list, even if their formation energy is specified.
- property charges: List[int]
list of all the charges of the
DefectChargeState
objects that comprise thisDefectSpecies
- Returns:
list of charge states of this
DefectSpecies
- Return type:
List[int]
- defect_charge_contributions(e_fermi: float, temperature: float) Tuple[float, float] [source]
Calculate the defect charge contributions to the total charge of this
DefectSpecies
at a given Fermi energy and temperature.- Parameters:
e_fermi (float) – Fermi energy.
temperature (float) – temperature
- Returns:
charge contributions of the
DefectChargeState
objects that comprise thisDefectSpecies
at the given Fermi energy and temperature.- Return type:
Tuple[float, float]
- fix_concentration(concentration: float) None [source]
fix the concentration of this
DefectSpecies
- Parameters:
concentration (float) – concentration per unit cell
- fixed_conc_charge_states() Dict[int, DefectChargeState] [source]
get
DefectChargeState
objects of thisDefectSpecies
with fixed concentration (i.e those for whichDefectChargeState.fixed_concentration != None
)- Returns:
key-value pairs of charge on fixed concentration
DefectChargeState
objects, and the charge state which is variable, i.e.{DefectChargeState.charge : DefectChargeState}
- Return type:
Dict[int, DefectChargeState]
- property fixed_concentration: float | None
fixed concentration of the
DefectSpecies
.None
if the concentration of this defect is variable.- Returns:
fixed concentration per unit cell of the
DefectSpecies
- Return type:
Optional[float]
- classmethod from_dict(defect_species_dict: dict)[source]
return a
DefectSpecies
object from a dictionary containing the defect species data. Primarily for use defining a fullDefectSystem
from a .yaml file.- Parameters:
defect_species_dict (dict) – dictionary containing the defect species data.
- Raises:
ValueError – if any of the
DefectChargeState
objects specified have no fixed concentration and no formation energy- Returns:
as specified by the provided dictionary
- Return type:
- get_concentration(e_fermi: float, temperature: float) float [source]
Determine the net concentration for this
DefectSpecies
at a specific Fermi energy and temperature.- Parameters:
e_fermi (float) – fermi energy
temperature (float) – temperature
- Returns:
concentration per calculation cell of this
DefectSpecies
- Return type:
float
Note
If this
DefectSpecies
has a set fixed concentration, then this will be returned.
- get_formation_energies(e_fermi: float) Dict[int, float] [source]
Returns a dictionary of formation energies for all
DefectChargeState
objects in thisDefectSpecies
. Formation energies are calculated at E[Fermi] relative to E[VBM].- Parameters:
e_fermi (float) – fermi energy
- Returns:
key-value pairs of charge on
DefectChargeState
objects that comprise thisDefectSpecies
and their formation energy, i.e{DefectChargeState.charge : formation_energy}
- Return type:
Dict[int, float]
Note
Fixed-concentration
DefectChargeState
objects are not included in the returned list, even if their formation energy is specified.
- get_transition_level_and_energy(q1: int, q2: int) Tuple[float, float] [source]
Calculates the Fermi energy and formation energy for the transition level between charge states q1 and q2.
- Parameters:
q1 (int) – charge on first
DefectChargeState
of interestq2 (int) – charge on second
DefectChargeState
of interest
- Returns:
Fermi energy and formation energy of the transition level between
DefectChargeState
objects with charges q1 and q2.- Return type:
Tuple[float, float]
- min_energy_charge_state(e_fermi: float) DefectChargeState [source]
Returns the defect charge state with the minimum energy at a given Fermi energy.
- Parameters:
e_fermi (float) – Fermi Energy
- Returns:
the
DefectChargeState
of thisDefectSpecies
with the lowest energy ate_fermi
.- Return type:
- property name: str
identifying string for this
DefectSpecies
- Returns:
label for
DefectSpecies
- Return type:
str
- property nsites: int
site degeneracy of this
DefectSpecies
in the unit cell.- Returns:
site degeneracy fot
DefectSpecies
- Return type:
int
- tl_profile(efermi_min: float, efermi_max: float) ndarray [source]
get transition level profile for this
DefectSpecies
between a minimum and maximum Fermi energy.- Parameters:
efermi_min (float) – minimum Fermi energy
efermi_max (float) – maximum Fermi energy
- Returns:
transition level profile between efermi_min and efermi_max.
- Return type:
np.ndarray
- variable_conc_charge_states() Dict[int, DefectChargeState] [source]
get
DefectChargeState
objects in thisDefectSpecies
with variable concentration (i.e those withDefectChargeState.fixed_concentration == None
)- Returns:
key-value pairs of charge on variable concentration
DefectChargeState
objects within thisDefectSpecies
, and the charge state which is variable, i.e.{DefectChargeState.charge : DefectChargeState}
- Return type:
Dict[int, DefectChargeState]
py_sc_fermi.defect_system module
- class py_sc_fermi.defect_system.DefectSystem(defect_species: List[DefectSpecies], dos: DOS, volume: float, temperature: float, convergence_tolerance: float = 1e-18, n_trial_steps: int = 1500)[source]
Bases:
object
This class is used to calculate the self consistent Fermi energy for a defective material, observing the condition of charge neutrality and therefore, point defect and carrier concentrations under equilibrium conditions.
- Parameters:
defect_species (List[DefectSpecies]) – List of
DefectSpecies
objects which are present in theDefectSystem
.volume (float) – volume of the unit cell in Angstroms cubed
dos (DOS) – the
DOS
object associated with the unit celltemperature (float) – temperature at which self-consentient Fermi energy will be solved for.
convergence_tolerance (float) – the charge neutrality tolerance for the self-consistent Fermi energy solver. Defaults to
1e-18
.n_trial_steps (int) – the maximum number of steps to take in the self-consistent Fermi energy solver. Defaults to 1500.
- concentration_dict(decomposed: bool = False, per_volume: bool = True) Dict[str, Any] [source]
Returns a dictionary of the properties of the
DefectSystem
object after solving for the self-consistent Fermi energy.- Parameters:
decomposed (bool, optional) – if True, return a dictionary in which the concentration of each
DefectChargeState
is given explicitly, rather than as a sum over allDefectChargeState
objects in the eachDefectSpecies
. Defaults to False.per_volume (bool, optional) – if True, return concentrations in units of cm^-3, else returns concentration per unit cell. Defaults to True.
- Returns:
dictionary specifying the Fermi Energy, hole concentration (
"p0"
), electron concentration ("n0"
), temperature, and the defect concentrations.- Return type:
Dict[str, Any]
- defect_species_by_name(name: str) DefectSpecies [source]
return a
DefectSpecies
contained within theDefectSystem
via its name.- Parameters:
name (str) – name of the
DefectSpecies
to return- Returns:
DefectSpecies
whereDefectSpecies.name == name
- Return type:
- property defect_species_names: List[str]
list of the names of all
DefectSpecies
considered in theDefectSystem
.- Returns:
list of names of
DefectSpecies
objects- Return type:
List[str]
- classmethod from_dict(dictionary: dict) DefectSystem [source]
generate
DefectSystem
from a dictionary- Parameters:
filename (str) – path to yaml file containing the
DefectSystem
datastructure_file (str) – path to file containing volume information. Defaults to an empty string.
dos_file (str) – path to file containing dos information. Defaults to an empty string.
- Returns:
DefectSystem
corresponding to provided yaml file- Return type:
- classmethod from_input_set(input_set: InputSet) DefectSystem [source]
generate
DefectSystem
fromInputSet
- Parameters:
input_set (InputSet) –
InputSet
defining input parameters- Returns:
DefectSystem
corresponding to providedInputSet
- Return type:
- classmethod from_yaml(filename: str, structure_file='', dos_file='') DefectSystem [source]
generate
DefectSystem
via a yaml file.- Parameters:
filename (str) – path to yaml file containing the
DefectSystem
datastructure_file (str) – path to file containing volume information. Defaults to an empty string.
dos_file (str) – path to file containing dos information. Defaults to an empty string.
- Returns:
DefectSystem
corresponding to provided yaml file- Return type:
- get_sc_fermi() Tuple[float, float] [source]
Solve to find Fermi energy in for which the
DefectSystem
is charge neutral- Returns:
Fermi energy, residual
- Return type:
Tuple[float, float]
- Raises:
RuntimeError – if the solver fails does not find a valid solution within
self.dos.emin
andself.dos.emax
Note
The solver will return the Fermi energy either when
self.convergence_tolerance
is satisfied or when the solver has attemptedself.n_trial_steps
. The residual is the the absolute charge density of the solver at the end of the last step. Please ensure the residual is satisfactorily low if convergence is not reached. It may be prudent to investigate the convergence of the solver with respect toself.n_trial_steps
andself.convergence_tolerance
.
- get_transition_levels() Dict[str, List[List]] [source]
Return transition_levels transition levels profiles of all
DefectSpecies
all defects as dictionary of{DefectSpecies.name : [e_fermi, e_formation]}
over the whole density of states energy range.- Returns:
Dictionary giving per-defect transition-level profiles.
- Return type:
Dict[str, List[List]]
- q_tot(e_fermi: float) float [source]
for a given Fermi energy, calculate the net charge density of the
DefectSystem
as the difference between charge contributions from all positive species (including holes) and all negative species (including electrons).- Parameters:
e_fermi (float) – Fermi energy
- Returns:
net charge density of the
DefectSystem
ate_fermi
- Return type:
float
- report() None [source]
print a report in the style of SC-Fermi which summarises key properties of the defect system.
- site_percentages() Dict[str, float] [source]
Returns a dictionary of the DefectSpecies in the DefectSystem which giving the percentage of the sites in the structure that will host that defect.
- Returns:
dictionary specifying the per-DefectSpecies site concentrations.
- Return type:
Dict[str, Any]
- total_defect_charge_contributions(e_fermi: float) Tuple[float, float] [source]
Calculate the charge contributions from each
DefectSpecies
in all charge states to the total charge density- Parameters:
e_fermi (float) – Fermi energy
- Returns:
charge contributions of positive (lhs) and negative (rhs) charge states of all defects
- Return type:
Tuple[float, float]
py_sc_fermi.dos module
- class py_sc_fermi.dos.DOS(dos: ndarray, edos: ndarray, bandgap: float, nelect: int, spin_polarised: bool = False)[source]
Bases:
object
Class for handling density-of-states data and its integration.
- Parameters:
dos (np.ndarray) – density-of-states data.
edos (np.ndarray) – energies associated with density-of-states data.
bandgap (float) – band gap
nelect (int) – number of electrons in density-of-states calculation
spin_polarised (bool) – is the calculated density-of-states spin polarised?
- as_dict() dict [source]
Return a dictionary representation of the DOS object
- Returns:
DOS as dictionary
- Return type:
dict
Note
The defect dictionary will always report the DOS data is not spin polarised, even if the input data was. This is an artefact related to maintaining the ability of py-sc-fermi to read files formatted for the FORTRAN SC-Fermi code. Future versions will consider how the code parses these files such that this is no longer an issue.
- property bandgap: float
bandgap of the density of states data
- Returns:
bandgap
- Return type:
float
- carrier_concentrations(e_fermi: float, temperature: float) Tuple[float, float] [source]
return electron and hole carrier concentrations from the Fermi-Dirac distribution multiplied by the density-of-states at a given Fermi energy and temperature.
- Parameters:
e_fermi (float) – fermi energy
temperature (float) – temperature
- Returns:
concentration of holes, concentration of electrons
- Return type:
Tuple[float, float]
- property dos: ndarray
density-of-states array
- Returns:
density-of-states data
- Return type:
np.ndarray
- property edos: ndarray
energy associated with density-of-states data
- Returns:
energy associated with the density-of-states data
- Return type:
np.ndarray
- emax() float [source]
maximum energy in
self.edos
- Returns:
maximum energy in
self.edos
- Return type:
float
- emin() float [source]
minimum energy in
self.edos
- Returns:
minimum energy in
self.edos
- Return type:
float
- classmethod from_dict(dos_dict: dict) DOS [source]
return a
DOS
object from a dictionary containing the density-of-states data. If the density-of-states data is spin polarised, it should be stored as a list of two arrays, one for each spin. The order is not important.- Parameters:
dos_dict (dict) – dictionary defining the density of states data
- classmethod from_vasprun(path_to_vasprun: str, nelect: int | None = None, bandgap: float | None = None) DOS [source]
Generate DOS object from a VASP vasprun.xml file. As this is parsed using pymatgen, the number of electrons is not contained in the vasprun data and must be passed in. On the other hand, If the bandgap is not passed in, it can be read from the vasprun file.
- Parameters:
path_to_vasprun (str) – path to vasprun file
nelect (int) – number of electrons in vasp calculation associated with the vasprun
bandgap (Optional[float], optional) – bandgap. Defaults to None.
- property nelect: int
number of electrons in density of states calculation with which to normalise the
DOS
with respect to.- Returns:
number of electrons
- Return type:
int
- normalise_dos() None [source]
normalises the density of states w.r.t. number of electrons in the density-of-states unit cell (
self.nelect
)
- property spin_polarised: bool
bool describing whether the density-of-states data is spin-polarised or not
- Returns:
True if the
DOS
is spin-polarised, else False- Return type:
bool
py_sc_fermi.inputs module
- class py_sc_fermi.inputs.InputFermiData(spin_pol, nelect, bandgap, temperature, defect_species)
Bases:
tuple
- bandgap
Alias for field number 2
- defect_species
Alias for field number 4
- nelect
Alias for field number 1
- spin_pol
Alias for field number 0
- temperature
Alias for field number 3
- class py_sc_fermi.inputs.InputSet(dos: py_sc_fermi.dos.DOS, volume: float, defect_species: List[py_sc_fermi.defect_species.DefectSpecies], temperature: float, convergence_tolerance: float = 1e-18, n_trial_steps: int = 1500)[source]
Bases:
object
- convergence_tolerance: float = 1e-18
- defect_species: List[DefectSpecies]
- classmethod from_sc_fermi_inputs(input_file: str, structure_file: str, dos_file: str, n_trial_steps: int = 1000, convergence_tolerance: float = 1e-18, frozen: bool = False) InputSet [source]
Generate an InputSet object from a SC-Fermi -formatted input file.
- Parameters:
input_file (str) – path to file to read
structure_file (str) – path to structure file to read
dos_file (str) – path to dos file to read
n_trial_steps (int, optional) – number of trial steps for py-sc-fermi solver. Defaults to 1000.
convergence_tolerance (float, optional) – convergence tolerance for py-sc-fermi solver. Defaults to 1e-18.
frozen (bool, optional) – True if any defects or defect charge states in in the input file have fixed concentrations. Defaults to False.
- Returns:
full set of inputs for
py-sc-fermi.DefectSystem
.- Return type:
- classmethod from_yaml(input_file: str, structure_file: str = '', dos_file: str = '', fixed_conc_units: str = 'cm^-3')[source]
Generate an InputSet object from a given yaml file
- Parameters:
input_file (str) – path to yaml file to read
structure_file (str) – path to structure file to read
dos_file (str) – path to dos file to read
- Returns:
full set of inputs for
py-sc-fermi.DefectSystem
.- Return type:
Note
Only the
.yaml
file is required. If the structure_file and dos_file are not specified, the.yaml
file must contain the volume and the density-of-states data.
- n_trial_steps: int = 1500
- temperature: float
- volume: float
- py_sc_fermi.inputs.is_yaml(filename: str) bool [source]
True if file is readable as a yaml file
- Parameters:
filename (str) – path to file to check
- Returns:
True
if file is readable yaml, elseFalse
.- Return type:
bool
- py_sc_fermi.inputs.read_dos_data(bandgap: float, nelect: int, filename: str = 'totdos.dat') DOS [source]
read density of states data from an SC-Fermi formatted
totdos.dat
file.- Parameters:
bandgap (float) – bandgap of density-of-states data.
nelect (int) – number of electrons in the density-of-states data
filename (str, optional) – path to
todos.dat
file. Defaults to “totdos.dat”.
- Returns:
py-sc-Fermi
DOS
object- Return type:
- py_sc_fermi.inputs.read_input_fermi(filename: str, volume: float | None = None, frozen: bool = False) InputFermiData [source]
Return all information from a input file correctly formatted to work for SC-Fermi.
- Parameters:
filename (str) – path to
SC-Fermi
-formatted input file.volume (float, optional) – unit cell volume. Only required if there are fixed-concentration defects in input file. Defaults to None.
frozen (bool, optional) – whether there are fixed-concentration defects in the input file. Defaults to False.
- Raises:
ValueError – if the
volume
is not specified, butfrozen == True
ValueError – if fixed-concentration defect does not have any charge-states defined.
- Returns:
input for generating a
DefectSystem
.- Return type:
- py_sc_fermi.inputs.read_volume_from_structure_file(structure_file: str) float [source]
read the volume of a structure defined in a given file.
- Parameters:
structure_file (str) – path to the structure file.
- Raises:
ValueError – if the structure file is not readable by
py-sc-fermi
- Returns:
volume of structure
- Return type:
float