analysis#
Analyse set of defect entries
Classes
|
Class to store sets of defect concentrations (output of concentration calculations with DefectsAnalysis). |
|
Class to compute collective properties starting from single calculations of point defects. |
|
Object to store defect concentrations data. |
- class DefectConcentrations(concentrations)[source]#
Bases:
objectClass to store sets of defect concentrations (output of concentration calculations with DefectsAnalysis). List of SingleDefConc objects. Subscriptable like a list.
- Parameters:
concentrations ((list)) – List of SingleDefConc objects.
- property elemental#
Dictionary with element (or element vacancy) as keys and total element concentration as values.
- property elements#
List of element (or vacancies) symbols.
- filter_concentrations(inplace=False, mode='and', exclude=False, names=None, charges=None, indexes=None, function=None, **kwargs)[source]#
Filter concentrations based on different criteria.
- Parameters:
inplace (bool) – If True update the current object, otherwise returns a new DefectConcentrations object. The default is False.
mode (str) – Selection mode. available are ‘and’,’or’. The default is ‘and’.
exclude (bool) – Exclude the entries matching the criteria. The default is False.
names (list) – Names of the defect.
charges (list) – Charges of the defect.
indexes (list) – Indexes of defect in the concentrations list.
function (function) – Specific funtion for more complex criteria. The function must take a SingleDefConc object as argument and return a bool.
**kwargs (dict) – Criteria for selection. They need to be attributes of SingleDefConc.
- Returns:
output_concs – Filtered DefectConcentrations object.
- Return type:
list
- get_element_total(element, vacancy=False)[source]#
Get total concentration of every element (summed also across different species)
- Parameters:
element (str) – Target element.
vacancy (bool) – Weather the target element is a vacancy. The default is False.
- Returns:
eltot – Total concentration of target element.
- Return type:
float
- property names#
List of names of all defect species
- select_concentrations(concentrations=None, mode='and', exclude=False, names=None, charges=None, indexes=None, function=None, **kwargs)[source]#
Select concentrations based on different criteria.
- Parameters:
concentrations (list) – List of SingleDefConc to select from. If None self.concentrations is used. The default is None.
mode (str) – Selection mode. available are ‘and’,’or’. The default is ‘and’.
exclude (bool) – Exclude the entries matching the criteria. The default is False.
names (list) – Names of the defect.
charges (list) – Charges of the defect.
indexes (list) – Indexes of defect in the concentrations list.
function (function) – Specific funtion for more complex criteria. The function must take a SingleDefConc object as argument and return a bool.
**kwargs (dict) – Criteria for selection. They need to be attributes of SingleDefConc.
- Returns:
output_concs – List of SingleDefConc objects.
- Return type:
list
- property stable#
Get concentrations of only stable charge states. List of SingleDefConc objects.
- property total#
conc})
- Type:
Get total concentrations for every defect specie. Format is a dict ({‘name’
- class DefectsAnalysis(entries, band_gap, vbm=0, sort_entries=True)[source]#
Bases:
MSONableClass to compute collective properties starting from single calculations of point defects.
- Parameters:
entries (list) – A list of DefectEntry objects.
band_gap (float) – Band gap of the pristine material in eV.
vbm (float) – Valence band maximum of the pristine material in eV.
- binding_energy(name, fermi_level=0, temperature=0, **eform_kwargs)[source]#
Compute the binding energy for a defect complex as: Eb = Ef(complex) - sum_D Ef(D), where D are the individual defects.
- Parameters:
name (string) – Name of defect complex as assigned in defect entry object
fermi_level (float) – Fermi level in eV.
temperature (float) – Temperature in K. If no custom formation energy is provided, this arg has no effect.
eform_kwargs (dict) – Kwargs to pass to entry.formation_energy.
- Returns:
float
- Return type:
Binding energy in eV.
- carrier_concentrations(bulk_dos, temperature=300, fermi_level=0.0)[source]#
Get intrinsic carrier concentrations by integrating over the density of states given a fixed Fermi level.
- Parameters:
bulk_dos (dict or Dos) –
Density of states to integrate. Can be provided as density of states D(E) or using effective masses.
Format for effective masses is a dict with the following keys:
”m_eff_h” : holes effective mass in units of m_e (electron mass)
”m_eff_e” : electrons effective mass in units of m_h
Format for explicit DOS (dictionary) with the following keys:
’energies’ : list or np.array with energy values
’densities’ : list or np.array with total density values
’structure’ : pymatgen Structure of the material, needed for DOS volume and charge normalization
Alternatively, a pymatgen Dos object (Dos, CompleteDos, or FermiDos).
fermi_level (float) – The Fermi level relative to the VBM in eV.
temperature (float) – The temperature in Kelvin.
- Returns:
h (float) – Absolute value of hole concentration in 1/cm^3
n (float) – Absolute value of electron concentration in 1/cm^3
- charge_transition_levels(energy_range=None, temperature=0, entries=None, get_integers=True, **eform_kwargs)[source]#
Computes charge transition levels for all defect entries.
- Parameters:
energy_range (list or tuple) – Energy range in eV to evaluate the charge transition levels, default to (-0.5, band_gap + 0.5).
temperature (float) – Temperature in K. If no custom formation energy is provided, this arg has no effect.
entries (list) – List of entries to calculate. If None all entries are considered.
get_integers (bool) – Save charges as integers. More convenient for plotting.
eform_kwargs (dict) – Kwargs to pass to entry.formation_energy.
- Returns:
charge_transition_levels – Dictionary with defect name and list of tuples for charge transition levels in eV: {name:[(q1,q2,ctl),(q2,q3,ctl),…}
- Return type:
dict
- property chempots#
Return chemical potential values if they were generated automatically
- defect_concentrations(chemical_potentials, temperature=300, fermi_level=0.0, fixed_concentrations=None, per_unit_volume=True, eform_kwargs={}, **kwargs)[source]#
Compute concentrations of all defects.
For each entry, is possible to set a custom function to compute the defect concentration using set_defect_concentration_function. If that is set, the new function is used instead of the default.
The function args must be the following:
- vbm(float)
Valence band maximum of bulk calculation in eV.
- chemical_potentials(dict)
Chemical potentials of the elements involved in the defect.
- fermi_level(float)
Fermi level in eV (with respect to the VBM).
- temperature(float)
Temperature in Kelvin.
- eform_kwargs(dict)
Kwargs to pass to entry.formation_energy.
- kwargs(dict)
Additional custom kwargs.
It is possible to set custom functions collectively using the set_defect_concentration_functions method in this class. To reset functions to default, use reset_defect_concentration_functions.
If fixed_concentrations is provided the concentration of defect entries are corrected according to the fixed provided values. More details can be found in DOI: 10.26083/tuprints-00024481 .
- Parameters:
chemical_potentials (dict) – Dictionary of chemical potentials ({element: chempot}).
temperature (float) – Temperature in K.
fermi_level (float) – Fermi level in eV relative to valence band maximum.
fixed_concentrations (dict) – Dictionary with fixed concentrations. Keys can be simple element strings (or vacancies of elements in the format ‘Vac_{el}’) if that element needs to be fixed across all defect species, alternatively defect entry names can be used as well to target specific defect entries. The values are the concentrations.
per_unit_volume (bool) – Get concentrations in cm^-3. If False they are per unit cell.
eform_kwargs (dict) – Kwargs to pass to self.formation_energy.
kwargs (dict) – Additional custom kwargs to pass to entry.defect_concentration.
- Returns:
concentrations – DefectConcentrations object, behaves like a list.
- Return type:
- property elements#
List of all the elements involved in exchange of atoms with a reservoir (elements present in entry.delta_atoms for all entries).
- filter_entries(inplace=False, entries=None, mode='and', exclude=False, types=None, elements=None, names=None, function=None, **kwargs)[source]#
Filter entries based on different criteria. Return another DefectsAnalysis object.
- Parameters:
inplace (bool) – Apply changes to current DefectsAnalysis object.
entries (list) – List of defect entries.
mode (str) – Filtering mode, possibilities are: ‘and’ and ‘or’. The default is ‘and’.
exclude (bool) – Exclude the entries satisfying the criteria instead of selecting them. The default is False.
types (list) – Class name of the defect in the entry.
elements (list) – List of symbols of elements that need to belong to the defect specie. If None this criterion is ignored. The default is None.
names (list) – List of entry names.
function (function) – Specific funtion for more complex criteria. The function must take a DefectEntry object as argument and return a bool.
**kwargs (dict) – Properties that the jobs need to satisfy. Keys are referred to attributes/methods of the defect entry. To address more than one condition relative to the same attribute, use lists or tuples (e.g. charge=[0,1]).
- Returns:
defects_analysis – DefectsAnalysis object.
- Return type:
- formation_energies(chemical_potentials=None, fermi_level=0, temperature=0, entries=None, **eform_kwargs)[source]#
Compute formation energies for all defect entries. Returns a dictionary with names of defect entries as keys and a list of tuples (charge,formation_energy) as values.
For each entry, is possible to set a custom function to compute the formation energy using set_formation_energy_function. If that is set, the new function is used instead of the default.
The function args must be the following:
- vbm(float)
Valence band maximum of bulk calculation in eV.
- chemical_potentials(dict)
Chemical potentials of the elements involved in the defect.
- fermi_level(float)
Fermi level in eV (with respect to the VBM).
- temperature(float)
Temperature in Kelvin.
- kwargs(dict)
Additional custom kwargs.
It is possible to set custom functions collectively using the set_formation_energy_functions method in this class. To reset functions to default, use reset_formation_energy_functions.
- Parameters:
chemical_potentials (dict) – Dictionary of chemical potentials ({element: chempot}).
fermi_level (float) – Fermi level in eV relative to valence band maximum.
temperature (float) – Temperature in K. If no custom formation energy is provided, this arg has no effect.
entries (list) – List of defect entries to calculate. If None all entries are considered.
eform_kwargs (dict) – Additional custom kwargs to pass to entry.formation_energy.
- Returns:
formation_energies – Dictionary in the format: {name: [(charge,formation energy)]}.
- Return type:
(dict)
- static from_dataframe(df, band_gap, vbm=0, include_data=True)[source]#
Create DefectsAnalysis object from pandas DataFrame (df). If df has been exported with include_structure=True, DefectEntry objects will be imported including defect and bulk structures.
- Parameters:
df (DataFrame) –
pandas DataFrame. Needs to be in the following format:
rows are defect entries
- non-optional columns are:
name : defect name in the format given by Defect objects.
charge : defect charge
multiplicity : site multiplicity of the defect
energy_diff : difference in energy btw defect and bulk structures
- If the df was not exported from this class, you need to provide also:
- bulk_volumeVolume of the bulk cell in A°3(unit cell or supercell
relative to your multiplicity)
vbm (float) – Valence band maximum of bulk structure in eV.
band_gap (float) – Band gap of bulk structure in eV.
include_data (bool) – Include extra columns in data dictionary in DefectEntry.
- Return type:
DefectsAnalysis object
- classmethod from_dict(d)[source]#
Reconstruct a DefectsAnalysis object from a dict representation created using as_dict().
- Parameters:
d (dict) – Dictionary representation of DefectsAnalysis.
- Return type:
DefectsAnalysis object
- static from_file(filename, band_gap=None, vbm=0, format=None, **kwargs)[source]#
Create DefectsAnalysis object from file. Available formats are: - ‘json’ - ‘pkl’ - ‘csv’
Check docs in from_dataframe function for file formatting requirements.
- static from_json(path_or_string)[source]#
Build DefectsAnalysis object from json file or string.
- Parameters:
path_or_string (str) – If an existing path to a file is given the object is constructed reading the json file. Otherwise it will be read as a string.
- Return type:
DefectsAnalysis object.
- static from_vasp_directories(path_defects, path_bulk, common_path=None, get_charge_correction='kumagai', dielectric_tensor=None, get_multiplicity=False, get_data=True, band_gap=None, vbm=None, initial_structure=False, function=None, function_kwargs={}, computed_entry_kwargs={}, finder_kwargs={}, correction_kwargs={})[source]#
Generate DefectsAnalysis object from VASP directories read with Pymatgen.
- Parameters:
path_defects (str) – Path of VASP defects calculation.
path_bulk (str) – Path of VASP bulk calculation.
common_path (str) – If set, the calculation path needs to contain this string for it to be parsed.
get_charge_correction (str or bool) – Compute charge corrections from VASP directories. To skip corrections set it to False. Methods available are: - “kumagai” : Extended FNV scheme (eFNV). - “freysoldt” : FNV scheme.
dielectric_tensor (int,float 3x1 array or 3x3 array) – Dielectric tensor (or constant). Types accepted are int,float 3x1 array or 3x3 array.
get_multiplicity (bool) – Determine defect multiplicity automatically. Not implemented for interstitials and defect complexes.
get_data (True) – Store path in DefectEntry.data dictionary.
band_gap (float) – Band gap of bulk material. If not provided is determined from bulk VASP directory.
vbm (float) – Valence band maximum of bulk material. If not provided is determined from bulk VASP directory.
initial_structure (bool) – Use initial structure for defect recognition. Useful when relaxations are large and defect_finder struggles to find the right defects.
function (function) – Function to apply to each DefectEntry. Useful to automate custom entry modification.
function_kwargs (dict) – Kwargs to pass to custom function.
computed_entry_kwargs (dict) – Kwargs to pass to Vasprun.get_computed_entry.
finder_kwargs (dict) – Kwargs to pass to defect_finder.
correction_kwargs (dict) – Kwargs to pass to the charge correction methods.
- Return type:
DefectsAnalysis object.
- get_charge_transition_level(name, q1, q2, temperature=0, **eform_kwargs)[source]#
Compute charge transition level.
- Parameters:
name (str) – Defect name in the format given by the Defect object.
q1 (int or float) – Charge state (in units of electron charge).
q2 (int or float) – Charge state (in units of electron charge).
temperature (float) – Temperature in K. If no custom formation energy is provided, this arg has no effect.
eform_kwargs (dict) – Kwargs to pass to entry.formation_energy.
- Returns:
charge_transition_level – Charge transition level in eV.
- Return type:
float
- merge_entries(*args)[source]#
Create a new DefectsAnalysis object merging the defect entries of other objects. The VBM and band gap of all objects need to match for consistency.
- plot_binding_energies(temperature=0, names=None, xlim=None, ylim=None, figsize=(6, 6), fontsize=18, colors=None, format_legend=True, **eform_kwargs)[source]#
Plot binding energies for complex of defects as a function of the fermi level
- Parameters:
temperature (float) – Temperature in K. If no custom formation energy is provided, this arg has no effect.
names (list) – List of strings with names of DefectEntry. If None, all defect complexes are plotted.
xlim (tuple) – Tuple (min,max) giving the range of the x (fermi energy) axis
ylim (tuple) – Tuple (min,max) giving the range for the formation energy axis
figsize (tuple) – Figure size.
fontsize (float) – Font size.
colors (list) – List of colors for line plot.
format_legend (bool) – Bool for getting latex-like legend based on the name of defect entries.
- Return type:
matplotlib.axes.Axes
- plot_brouwer_diagram(bulk_dos, temperature, quench_temperature=None, quenched_species=None, quench_elements=False, fixed_concentrations=None, external_defects=[], reservoirs=None, precursors=None, oxygen_ref=None, pressure_range=(1e-20, 10000000000.0), npoints=50, xtol=1e-20, eform_kwargs={}, dconc_kwargs={}, **kwargs)[source]#
Plot Brouwer diagram (defect concentrations vs oxygen partial pressure). Wrapper function for pynter.defects.thermodynamics.DefectThermodynamics and pynter.defects.plotter. If you need more control use the classes individually.
If quenched_temperature is set, defect concentrations are computed at the initial temperature, and defect quilibrium in solved at quenched_temperature. For the same defect species, the charge state follow the temperature and Fermi level dependency at quench_temperature, the total concentration is kept fix at the initial temperature. If additional fixed_concentrations are provided, the concentration of defect entries are corrected according to the fixed provided values. More details can be found in https://doi.org/10.1103/PhysRevB.106.134101 .
The results of the calculation are stored in the thermodata property.
For the chemical potentials, you must provide either:
reservoirs: Dictionary with oxygen partial pressures as keys and dictionary with chemical potential as values ({pO2:{‘element’:chempot}}), or PressureReservoirs object.
Alternatively: precursors + oxygen_ref:
Dictionary with {formula:energy} for synthesis precursors and oxygen reference chempot at 0 K. If you provide only the formulas, the data is pulled from the Materials Project database. IMPORTANT: Using data from the MP database is useful to get a feeling of the defect behaviour. For more accurate analysis you should always carefully define the chemical potentials.
- Parameters:
bulk_dos (dict or Dos) –
Density of states to integrate. Can be provided as density of states D(E) or using effective masses.
Format for effective masses is a dict with the following keys:
”m_eff_h” : holes effective mass in units of m_e (electron mass)
”m_eff_e” : electrons effective mass in units of m_h
Format for explicit DOS (dictionary) with the following keys:
’energies’ : list or np.array with energy values
’densities’ : list or np.array with total density values
’structure’ : pymatgen Structure of the material, needed for DOS volume and charge normalization
Alternatively, a pymatgen Dos object (Dos, CompleteDos, or FermiDos).
temperature (float) – Temperature in K.
quench_temperature (float) – Value of quenching temperature in K.
quenched_species (list) – List of defect species to quench. If None all defect species are quenched.The default is None.
quench_elements (bool) – If True the total concentrations of elements at high temperature go in the charge neutrality at low temperature. If False the quenched concentrations are the ones of single defect species (e.g. elements are not allowed to equilibrate on different sites).
fixed_concentrations (dict) – Dictionary with fixed concentrations. Keys are defect entry names, values are the concentrations. (ex {‘Vac_Na’:1e20}).
external_defects (list) – List of external defect concentrations (not present in defect entries). Must either be a list of dictionaries with {‘charge’: float, ‘conc’: float} or a list of SingleDefConc objects.
reservoirs (dict or PressureReservoirs) – Dictionary with pO2 (float) as keys and chemical potential dictionary as values ({pO2:{‘element’:mu_element}})
precursors (str, list or dict) – Dictionary with formulas (str) as keys and total energies as values. If a str or list is provided, the dictionary is generated with data from the Materials Project database. Chemical potentials are found from the energies of the precursors and the oxygen chempot value (uses the np.linalg.lstsq function). If the system is underdetermined the minimum-norm solution is found. Chemical potentials are found from the energies of the precursors and the oxygen chempot value (uses the np.linalg.lstsq function). If the system is underdetermined the minimum-norm solution is found.
oxygen_ref (float) – Absolute chempot of oxygen at 0K. If not provided and precursors are set, it is pulled from the Materials Project DB.
pressure_range (tuple) – Range in which to evaluate the partial pressure. Only used if reservoirs are not provided.
npoints (int) – Number of data points to interpolate the partial pressure with.
xtol (float) – Tolerance for bisect (scipy) to solve charge neutrality.
eform_kwargs (dict) – Kwargs to pass to entry.formation_energy.
dconc_kwargs (dict) – Kwargs to pass to entry.defect_concentration.
kwargs (dict) – Kwargs to pass to plot_pO2_vs_concentrations.
- Return type:
matplotlib.axes.Axes
- plot_ctl(entries=None, temperature=0, ylim=None, figsize=(6, 6), fontsize=16, fermi_level=None, format_legend=True, get_integers=True, **eform_kwargs)[source]#
Plotter for the charge transition levels.
- Parameters:
entries (list) – List of entries to calculate. If None all entries are considered.
temperature (float) – Temperature in K. If no custom formation energy is provided, this arg has no effect.
ylim (tuple) – y-axis limits.
figsize (tuple) – Figure size.
fontsize (float) – Font size.
fermi_level (float) – Plot Fermi energy position.
format_legend (bool) – Bool for getting latex-like legend based on the name of defect entries.
get_integers (bool) – Get charge transition levels as integers.
- Return type:
matplotlib.axes.Axes
- plot_doping_diagram(variable_defect_specie, concentration_range, chemical_potentials, bulk_dos, temperature, quench_temperature=None, quenched_species=None, quench_elements=False, fixed_concentrations=None, external_defects=[], npoints=50, xtol=1e-20, eform_kwargs={}, dconc_kwargs={}, **kwargs)[source]#
Calculate defect and carrier concentrations as a function of the concentration of a particular defect species (usually a dopant).
- Parameters:
variable_defect_specie (str) – Name or element of the variable defect species.
concentration_range (tuple or list) – Logaritmic range of the concentration of the variable species in cm^-3 (ex. [1,20]).
chemical_potentials (tuple, list or dict) –
Chemical potentials of the elements, in the format {‘element’:chempot}. Alternatively, provide a list or tuple: the first item is the composition formula, the second item is a condition: “<el>-poor/middle/rich”.
Generated chemical potentials are stored as property (self.chempots).
IMPORTANT: Using data from the MP database is useful to get a feeling of the defect behaviour. For more accurate analysis you should always carefully define the chemical potentials.
Examples:
chemical_potentials = {‘Sr’:value, ‘O’:value}
chemical_potentials = (‘SrO’,’O-rich’)
bulk_dos (dict or Dos) –
Density of states to integrate. Can be provided as density of states D(E) or using effective masses.
Format for effective masses is a dict with the following keys:
”m_eff_h” : holes effective mass in units of m_e (electron mass)
”m_eff_e” : electrons effective mass in units of m_h
Format for explicit DOS (dictionary) with the following keys:
’energies’ : list or np.array with energy values
’densities’ : list or np.array with total density values
’structure’ : pymatgen Structure of the material, needed for DOS volume and charge normalization
Alternatively, a pymatgen Dos object (Dos, CompleteDos, or FermiDos).
temperature (float) – Temperature in K.
fixed_concentrations (dict) – Dictionary with fixed concentrations. Keys are defect entry names in the standard format, values are the concentrations. (ex {‘Vac_Na’:1e20})
external_defects (list) – List of external defect concentrations (not present in defect entries). Must either be a list of dictionaries with {‘charge’: float, ‘conc’: float} or a list of SingleDefConc objects.
xtol (float) – Tolerance for bisect (scipy) to solve charge neutrality.
npoints (int) – Number of points to divide concentration range.
eform_kwargs (dict) – Kwargs to pass to entry.formation_energy.
dconc_kwargs (dict) – Kwargs to pass to entry.defect_concentration.
kwargs (dict) – Kwargs to pass to plot_variable_species_vs_concentrations.
- Return type:
matplotlib.axes.Axes
- plot_formation_energies(chemical_potentials, temperature=0, entries=None, xlim=None, ylim=None, title=None, fermi_level=None, grid=True, figsize=(6, 6), fontsize=12, colors=None, show_legend=True, format_legend=True, axes=None, **eform_kwargs)[source]#
Produce defect Formation energy vs Fermi energy plot.
- Parameters:
chemical_potentials ((str, tuple, list or dict)) –
If a dictionary is provided, either a dict with chemical potentials of the elements chempots={‘element’:chempot} or a dict of chempots dictionaries for multiple subfigures ({label:chempots}).
If a string or tuple are provided, chemical potentials will be generated from the phase diagram data in the Materials Project database. If a string is provided: pass the composition formula of the target material, and chemical potential conditions are automatically generated by checking the stability range of a target element in the phase of interest. If the composition contains oxygen, it is chosen as target, otherwise the last element in the formula is chosen. Multiple subfigure are generated. If a tuple or list is provided, the first item is the composition formula. The second item is either the target element (multiple plots are generated), or a condition: “<el>-poor/middle/rich”, a single figure is generated. Generated chemical potentials are stored as property (self.chempots).
IMPORTANT: Using data from the MP database is useful to get a feeling of the defect behaviour. For more accurate analysis you should always carefully define the chemical potentials.
Examples:
chemical_potentials = {‘Sr’:value, ‘O’:value}
chemical_potentials = {‘A-label’:{‘Sr’:a_value, ‘O’:a_value}, ‘B-label’:{‘Sr’:b_value, ‘O’:b_value}}
chemical_potentials = ‘SrO’
chemical_potentials = (‘SrO’,’O’)
chemical_potentials = (‘SrO’,’O-rich’)
temperature (float) – Temperature in K. If no custom formation energy is provided, this arg has no effect.
entries (list) – List of entries to calculate. If None all entries are considered.
xlim (tuple) – Tuple (min,max) giving the range of the x (fermi energy) axis.
ylim (tuple) – Tuple (min,max) giving the range for the formation energy axis.
title (str) – Title of the figure.
fermi_level (float) – Plot Fermi energy position with a vertical line.
grid (bool) – Show grid.
figsize (float or tuple) – Can be float or tuple for different x and y sizes multiplier to change the figure size.
fontsize (float) – Multiplier to change font size.
show_legend (bool) – Show legend.
format_legend (bool) – Get latex-like legend based on the name of defect entries.
eform_kwargs (dict) – Kwargs to pass to entry.formation_energy.
axes (matplotlib.axes.Axes) – Axis to plot into. If None, a new figure and axis are created. Can be a list if you are passing a dictionary of chemical potentials dictionaries.
- Return type:
matplotlib.axes.Axes
- reset_all_custom_functions(reset_all=True, **kwargs)[source]#
Reset all customized functions to default for selected entries, Pass kwargs to select_entries function to choose which entries to reset. If reset_all is True all entries are reset to default.
- reset_defect_concentration_functions(reset_all=True, **kwargs)[source]#
Reset defect concentration function to default for selected entries, Pass kwargs to select_entries function to choose which entries to reset. If reset_all is True all entries are reset to default.
- reset_formation_energy_functions(reset_all=True, **kwargs)[source]#
Reset formation energy function to default for selected entries, Pass kwargs to select_entries function to choose which entries to reset. If reset_all is True all entries are reset to default.
- select_entries(entries=None, mode='and', exclude=False, types=None, elements=None, names=None, function=None, **kwargs)[source]#
Find entries based on different criteria. Returns a list of DefectEntry objects.
- Parameters:
entries (list) – List of defect entries.
mode (str) – Filtering mode, possibilities are: ‘and’ and ‘or’. The default is ‘and’.
exclude (bool) – Exclude the entries satisfying the criteria instead of selecting them. The default is False.
types (list) – Class name of the defect in the entry.
elements (list) – List of symbols of elements that need to belong to the defect specie. If None this criterion is ignored. The default is None.
names (list) – List of entry names.
function (function) – Specific funtion for more complex criteria. The function must take a DefectEntry object as argument and return a bool.
**kwargs (dict) – Properties that the jobs need to satisfy. Keys are referred to attributes/methods of the defect entry. To address more than one condition relative to the same attribute, use lists or tuples (e.g. charge=[0,1]).
- Returns:
entries – List of DefectEntry objects.
- Return type:
list
- set_defect_concentration_functions(function, **kwargs)[source]#
Customize the function for defect concentration calculations for specific defect entries. Pass kwargs to select_entries function to choose which entries to apply the function to.
- set_formation_energy_functions(function, **kwargs)[source]#
Customize the function for formation energy calculations for specific defect entries. Pass kwargs to select_entries function to choose which entries to apply the function to.
- solve_fermi_level(chemical_potentials, bulk_dos, temperature=300, fixed_concentrations=None, external_defects=[], xtol=1e-20, eform_kwargs={}, dconc_kwargs={})[source]#
Solve charge neutrality and get the value of Fermi level at thermodynamic equilibrium.
- Parameters:
chemical_potentials (tuple, list or dict) –
Chemical potentials of the elements, in the format {‘element’:chempot}. Alternatively, provide a list or tuple: the first item is the composition formula, the second item is a condition: “<el>-poor/middle/rich”.
Generated chemical potentials are stored as property (self.chempots). IMPORTANT: Using data from the MP database is useful to get a feeling of the defect behaviour. For more accurate analysis you should always carefully define the chemical potentials.
Examples:
chemical_potentials = {‘Sr’:value, ‘O’:value}
chemical_potentials = (‘SrO’,’O-rich’)
bulk_dos (dict or Dos) –
Density of states to integrate. Can be provided as density of states D(E) or using effective masses.
Format for effective masses is a dict with the following keys:
”m_eff_h” : holes effective mass in units of m_e (electron mass)
”m_eff_e” : electrons effective mass in units of m_h
band_gap : needs to be provided in arguments
Format for explicit DOS (dictionary) with the following keys:
’energies’ : list or np.array with energy values
’densities’ : list or np.array with total density values
’structure’ : pymatgen Structure of the material, needed for DOS volume and charge normalization
Alternatively, a pymatgen Dos object (Dos, CompleteDos, or FermiDos).
temperature (float) – Temperature in Kelvin.
fixed_concentrations (dict) – Dictionary with fixed concentrations. Keys are defect entry names in the standard format, values are the concentrations (ex {‘Vac_A’:1e20}) . For more info, read the documentation of the defect_concentrations method.
external_defects (list) – List of external defect concentrations (not present in defect entries). Must either be a list of dictionaries with {‘name’: str, ‘charge’: float, ‘conc’: float} or a list of SingleDefConc objects.
xtol (float) – Tolerance for bisect (scipy) to solve charge neutrality.
eform_kwargs (dict) – Kwargs to pass to entry.formation_energy.
dconc_kwargs (dict) – Kwargs to pass to entry.defect_concentration.
- Returns:
fermi_level – Fermi level satisfying charge neutrality.
- Return type:
float
- sort_entries(inplace=False, entries=None, features=['name', 'charge'], reverse=False)[source]#
Sort defect entries with different criteria.
- Parameters:
inplace (bool) – Reset the self.entries attibute with sorted entries. Only works if entries input is not given. The default is False.
entries (list) – List of defect entries to sort. If None self.entries is used. The default is None.
features (list) – List of strings with attribute/method names. The default is [‘name’,’charge’].
reverse (bool) – Reverse order.
- Returns:
entries – List of DefectEntry objects.
- Return type:
list
- stable_charges(chemical_potentials=None, fermi_level=0, temperature=0, entries=None, **eform_kwargs)[source]#
Creating a dictionary with names of single defect entry as keys and as value a tuple (charge,formation_energy) that gives the most stable charge state at the inserted fermi level.
For each entry, is possible to set a custom function to compute the formation energy using set_formation_energy_function. If that is set, the new function is used instead of the default.
The function args must be the following:
- vbm(float)
Valence band maximum of bulk calculation in eV.
- chemical_potentials(dict)
Chemical potentials of the elements involved in the defect.
- fermi_level(float)
Fermi level in eV (with respect to the VBM).
- temperature(float)
Temperature in Kelvin.
- kwargs(dict)
Additional custom kwargs.
It is possible to set custom functions collectively using the set_formation_energy_functions method in this class. To reset functions to default, use reset_formation_energy_functions.
- Parameters:
chemical_potentials (dict) – Dictionary of chemical potentials ({element: chempot})
fermi_level (float) – Fermi level in eV relative to valence band maximum.
temperature (float) – Temperature in K. If no custom formation energy is provided, this arg has no effect.
entries (list) – List of defect entries to calculate. If None all entries are considered.
eform_kwargs (dict) – Additional custom kwargs to pass to entry.formation_energy
- Returns:
stable_charges – Dictionary in the format {name:(stable charge, formation energy)}
- Return type:
dict
- table(entries=None, pretty=False, include_bulk=False, display=[])[source]#
Get DataFrame to display entries.
- Parameters:
entries (list) – Entries to display. If None all entries are displayed. The default is None.
pretty (bool) – Optimize DataFrame for prettier visualization.
include_bulk (bool) – Include bulk composition and space group for each entry in DataFrame.
display (list) – List of strings with defect entry attributes or method results to display.
- Returns:
DataFrame object.
- Return type:
df
- property thermodata#
Result of thermodynamics calculation (plot_brouwer_diagram or plot_doping_diagram functions).
- to_dataframe(entries=None, include_structures=False, include_data=True, properties=[], functions={})[source]#
Export DefectsAnalysis object as DataFrame. Default exported columns are:
“name”
“charge”
“multiplicity”
“energy_diff”
“bulk_volume”
Corrections dict (entry.corrections) are exported as separate columns for each keys in this format “corr_{key}”.
- Parameters:
entries (list) – Entries to export. If None all entries are displayed.
include_structures (bool) – Add full Defect object to DataFrame containing defect and bulk structures. This makes the DataFrame less portable.
include_data (bool) – Include entry.data dictionary.
properties (list) – List of strings with defect entry attributes or methods to include in df.
functions (dict) – Dictionary with column names as keys and functions as values. The function needs to take a DefectEntry as input and the output will be stored in df.
- Returns:
df
DataFrame object.
- to_file(filename, format=None, export_kwargs={}, **kwargs)[source]#
Export DefectsAnalysis object to file.
- Parameters:
filename (str) – Path of file.
format (str) – If not specified the file extension in filename is used. Formats available: - “pkl” : pickle file. Allows to store structures (default). - “json” : DefectsAnalysis object as json file. - “csv” : Does not allow to store structures.
export_kwargs (dict) – Kwargs to pass to file exporting function
kwargs (dict) – Kwargs to pass to to_dataframe function. If not provided, ‘include_strctures’ is to True if chosen format is ‘pkl’, set to False if chosen format is ‘csv’ or ‘excel’.
- to_json(path='', **kwargs)[source]#
Save DefectsAnalysis object as json string or file.
- Parameters:
path (str) – Path to the destination file. If ‘’ the path is set to “self.path/self.name.json”. If None a string is exported.
- Returns:
d – If path is not set a string is returned.
- Return type:
str
- property types#
Defect types in entries