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)

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

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:

float | None

fix_concentration(concentration: float) → None

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 or None if the concentration is free to vary.

Returns:

fixed concentration per unit cell

Return type:

float | None

classmethod from_dict(dictionary: dict) → DefectChargeState

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:

DefectChargeState

classmethod from_string(string: str, volume: float | None = None, frozen: bool = False) → DefectChargeState

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 (float | None, optional) – volume of the unit cell, only if frozen == True. Defaults to None.

• frozen (bool, optional) – if True the concentration of this DefectChargeState cannot change when solving for a self consistent Fermi energy. Defaults to False.

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

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

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 at e_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)

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

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]

Calculate the concentrations of the different charge states.

At a given Fermi energy and temperature, calculate the concentrations of the different DefectChargeStates of this DefectSpecies.

If the species has a fixed total concentration, the variable charge state concentrations are distributed according to their Boltzmann weights using a numerically stable logsumexp calculation.

Parameters:

• e_fermi (float) – Fermi energy

• temperature (float) – temperature

Returns:

key-value pairs of charge of each DefectChargeState and the concentration of the DefectChargeState with that charge, i.e. {DefectChargeState.charge: concentration}

Return type:

dict[int, float]

Raises:

ValueError – If fixed charge state concentrations exceed the total species concentration.

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]

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 this DefectSpecies sorted by formation energy at e_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 this DefectSpecies

Returns:

list of charge states of this DefectSpecies

Return type:

list[int]

defect_charge_contributions(e_fermi: float, temperature: float) → tuple[float, float]

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 this DefectSpecies at the given Fermi energy and temperature.

Return type:

tuple[float, float]

fix_concentration(concentration: float) → None

fix the concentration of this DefectSpecies

Parameters:

concentration (float) – concentration per unit cell

fixed_conc_charge_states() → dict[int, DefectChargeState]

get DefectChargeState objects of this DefectSpecies with fixed concentration (i.e those for which DefectChargeState.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:

float | None

classmethod from_dict(defect_species_dict: dict)

return a DefectSpecies object from a dictionary containing the defect species data. Primarily for use defining a full DefectSystem 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:

DefectChargeState

get_concentration(e_fermi: float, temperature: float) → float

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]

Returns a dictionary of formation energies for all DefectChargeState objects in this DefectSpecies. 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 this DefectSpecies 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]

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 interest

• q2 (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

Returns the defect charge state with the minimum energy at a given Fermi energy.

Parameters:

e_fermi (float) – Fermi Energy

Returns:

the DefectChargeState of this DefectSpecies with the lowest energy at e_fermi.

Return type:

DefectChargeState

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

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]

get DefectChargeState objects in this DefectSpecies with variable concentration (i.e those with DefectChargeState.fixed_concentration == None)

Returns:

key-value pairs of charge on variable concentration DefectChargeState objects within this DefectSpecies, 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 | None = None, n_trial_steps: int | None = None)

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 the DefectSystem.

• volume (float) – volume of the unit cell in Angstroms cubed

• dos (DOS) – the DOS object associated with the unit cell

• temperature (float) – temperature at which self-consistent Fermi energy will be solved for.

• convergence_tolerance (float, optional) – Tolerance for the Fermi energy convergence in eV. If not specified, uses scipy’s default.

• n_trial_steps (int, optional) – Deprecated. Previously set the maximum number of solver iterations. The solver now uses Brent’s method which converges reliably without this parameter.

as_dict() → dict

Returns:

_description_

Return type:

dict

concentration_dict(decomposed: bool = False, per_volume: bool = True) → dict[str, Any]

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 all DefectChargeState objects in the each DefectSpecies. 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

return a DefectSpecies contained within the DefectSystem via its name.

Parameters:

name (str) – name of the DefectSpecies to return

Returns:

DefectSpecies where DefectSpecies.name == name

Return type:

DefectSpecies

property defect_species_names: list[str]

list of the names of all DefectSpecies considered in the DefectSystem.

Returns:

list of names of DefectSpecies objects

Return type:

list[str]

classmethod from_dict(dictionary: dict) → DefectSystem

Generate a DefectSystem from a dictionary.

Parameters:

dictionary (dict) – Dictionary containing the DefectSystem data.

Returns:

DefectSystem corresponding to the provided dictionary.

Return type:

DefectSystem

classmethod from_input_set(input_set: InputSet) → DefectSystem

generate DefectSystem from InputSet

Parameters:

input_set (InputSet) – InputSet defining input parameters

Returns:

DefectSystem corresponding to provided InputSet

Return type:

DefectSystem

classmethod from_yaml(filename: str, structure_file='', dos_file='') → DefectSystem

generate DefectSystem via a yaml file.

Parameters:

• filename (str) – path to yaml file containing the DefectSystem data

• structure_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:

DefectSystem

get_sc_fermi() → tuple[float, float]

Calculate the self-consistent Fermi energy.

Finds the Fermi energy at which charge neutrality is achieved, using Brent’s method for root finding.

Returns:

The self-consistent Fermi energy and the absolute residual charge density at that energy.

Return type:

tuple[float, float]

Raises:

RuntimeError – If no solution is found within the DOS energy range.

get_transition_levels() → dict[str, list[list]]

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

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 at e_fermi

Return type:

float

report() → None

print a report in the style of SC-Fermi which summarises key properties of the defect system.

site_percentages() → dict[str, float]

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]

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)

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

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]

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

maximum energy in self.edos

Returns:

maximum energy in self.edos

Return type:

float

emin() → float

minimum energy in self.edos

Returns:

minimum energy in self.edos

Return type:

float

classmethod from_dict(dos_dict: dict) → DOS

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

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 (float | None, 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

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

sum_dos() → ndarray

Returns:

integrated density-of-states up to mid-gap, or up to

the grid point closest to the VBM if that sits above mid-gap (narrow-gap case).

Return type:

np.ndarray

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 | None = None, n_trial_steps: int | None = None)

Bases: object

convergence_tolerance: float | None = None

defect_species: list[DefectSpecies]

dos: DOS

classmethod from_sc_fermi_inputs(input_file: str, structure_file: str, dos_file: str, n_trial_steps: int | None = None, convergence_tolerance: float | None = None, frozen: bool = False) → InputSet

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) – Deprecated. Maximum solver iterations. If not specified, uses scipy’s default.

• convergence_tolerance (float, optional) – Tolerance for Fermi energy convergence in eV. If not specified, uses scipy’s default.

• 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:

InputSet

classmethod from_yaml(input_file: str, structure_file: str = '', dos_file: str = '', fixed_conc_units: str = 'cm^-3')

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:

InputSet

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 | None = None

temperature: float

volume: float

py_sc_fermi.inputs.is_yaml(filename: str) → bool

True if file is readable as a yaml file

Parameters:

filename (str) – path to file to check

Returns:

True if file is readable yaml, else False.

Return type:

bool

py_sc_fermi.inputs.read_dos_data(bandgap: float, nelect: int, filename: str = 'totdos.dat') → DOS

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:

DOS

py_sc_fermi.inputs.read_input_fermi(filename: str, volume: float | None = None, frozen: bool = False) → InputFermiData

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, but frozen == True

• ValueError – if fixed-concentration defect does not have any charge-states defined.

Returns:

input for generating a DefectSystem.

Return type:

InputFermiData

py_sc_fermi.inputs.read_volume_from_structure_file(structure_file: str) → float

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

py_sc_fermi.inputs.volume_from_structure(structure_file: str) → float

get volume of any structure file readable by pymatgen

Parameters:

structure_file (str) – path to file defining structure

Returns:

volume of structure

Return type:

float

py_sc_fermi.inputs.volume_from_unitcell(filename: str) → float

Get volume in A^3 from unitcell.dat file-type used in SC-Fermi

Parameters:

filename (str) – path to unitcell.dat file

Returns:

volume in A^3

Return type:

float

Module contents