dfttk.thermal_electronic

ThermalElectronic

class dfttk.thermal_electronic.thermal_electronic.ThermalElectronic

Bases: object

A class for reading or setting electronic density-of-states (DOS) data, calculating thermal electronic properties, and generating plots.

Typical usage: (1) Load electronic DOS data from VASP calculations for multiple volumes using read_total_electron_dos(), or provide DOS data directly with set_total_electron_dos(); (2) Compute thermal electronic contributions (Helmholtz free energy, internal energy, entropy, and heat capacity) using process() and fit(); (3) Visualize results with the provided plotting methods.

Additional intermediate methods are available for calculating the chemical potential, fitting the DOS, computing the Fermi-Dirac distribution, and related quantities.

path

Path to the directory containing electronic DOS data.

number_of_atoms

Number of atoms used in the DOS calculations.

nelect

Total number of electrons in the DOS data.

volumes

Array of volumes for each structure, shape (n_volumes,), in ų.

energies_list

List of arrays of electronic energies referenced to the Fermi level (\(E - E_F\)) for each volume, in eV.

dos_list

List of arrays of electronic DOS values for each volume, in states/eV.

temperatures

Array of temperatures, shape (n_temperatures,), in K.

helmholtz_energies

Helmholtz free energy as a function of temperature and volume, shape (n_temperatures, n_volumes), in eV.

internal_energies

Internal energy as a function of temperature and volume, shape (n_temperatures, n_volumes), in eV.

entropies

Entropy as a function of temperature and volume, shape (n_temperatures, n_volumes), in eV/K.

heat_capacities

Heat capacity as a function of temperature and volume, shape (n_temperatures, n_volumes), in eV/K.

volumes_fit

Volumes used for polynomial fits, shape (n_volumes_fit,), in ų.

helmholtz_energies_fit

Polynomial-fitted Helmholtz free energies as a function of temperature and fitted volume, shape (n_temperatures, n_volumes_fit), in eV.

entropies_fit

Polynomial-fitted entropies as a function of temperature and fitted volume, shape (n_temperatures, n_volumes_fit), in eV/K.

heat_capacities_fit

Polynomial-fitted heat capacities as a function of temperature and fitted volume, shape (n_temperatures, n_volumes_fit), in eV/K.

helmholtz_energies_poly_coeffs

Polynomial coefficients for Helmholtz free energy fits as a function of volume, shape (n_temperatures, order + 1).

entropies_poly_coeffs

Polynomial coefficients for entropy fits as a function of volume, shape (n_temperatures, order + 1).

heat_capacities_poly_coeffs

Polynomial coefficients for heat capacity fits as a function of volume, shape (n_temperatures, order + 1).

read_total_electron_dos(path, folder_prefix='elec', vasprun_name='vasprun.xml.elec_dos', selected_volumes=None, selected_folders=None)

Reads the total electron DOS data from VASP calculations for different volumes.

Parameters:

• path (str) – Path to the directory containing the specific folders with vasprun.xml files.

• folder_prefix (str) – Prefix of the electronic folders. Defaults to "elec".

• vasprun_name (str) – Name of the vasprun.xml file. Defaults to "vasprun.xml.elec_dos".

• selected_volumes (ndarray | None) – Array of volumes to process. Defaults to None.

• selected_folders (list[str] | None) – List of selected folders to keep the electron DOS data. Defaults to None.

Raises:

• ValueError – If both selected_volumes and selected_folders are provided, as they are mutually exclusive.

• ValueError – If selected volumes are not found.

• ValueError – If the number of atoms is not the same for all volumes.

• ValueError – If the number of electrons is not the same for all volumes.

Return type:

None

set_total_electron_dos(number_of_atoms, volumes, energies_list, dos_list)

Set the total electron DOS directly.

Parameters:

• number_of_atoms (int) – Number of atoms corresponding to the DOS data.

• volumes (ndarray) – 1D array of volumes, shape (n_volumes,), in ų.

• energies_list (list[ndarray]) – List of 1D arrays of energies referenced to the Fermi level (\(E - E_F\)) for each volume, in eV.

• dos_list (list[ndarray]) – List of 1D arrays of DOS values for each volume, in states/eV.

Raises:

ValueError – Lengths of volumes, energies_list, and dos_list must be the same.

Return type:

None

process(temperatures)

Calculates the thermal electronic contributions to Helmholtz free energy, internal energy, entropy, and heat capacity.

Parameters:

temperatures (ndarray) – 1D array of temperatures in K, shape (n_temperatures,).

Raises:

ValueError – If DOS data is not found.

Return type:

None

fit(volumes_fit, order=1)

Fits the Helmholtz free energy, entropy, and heat capacity as a function of volume for various fixed temperatures.

Parameters:

• volumes_fit (ndarray) – 1D array of volumes used for fitting the properties, shape (n_volumes_fit,), in ų.

• order (int) – Order of the polynomial fit. Defaults to 1 (linear fit).

Raises:

ValueError – Thermodynamic properties have not been calculated.

Return type:

None

plot_total_dos()

Plots the total electron DOS for different volumes.

Raises:

ValueError – DOS data not found. Please read or set the total electron DOS first using read_total_electron_dos() or set_total_electron_dos().

Returns: Plotly figure object containing the total electron DOS curves for

the different volumes.

Return type:

Figure

plot_vt(type, selected_temperatures=None)

Plots thermal electronic properties as a function of temperature or volume.

Parameters:

• type (str) – Must be one of the following values: 'helmholtz_energy_vs_temperature', 'entropy_vs_temperature', 'heat_capacity_vs_temperature', 'helmholtz_energy_vs_volume', 'entropy_vs_volume', or 'heat_capacity_vs_volume'.

• selected_temperatures (ndarray | None) – Selected temperatures to use for volume plots, shape (n_selected_temperatures,). Defaults to None.

Raises:

• ValueError – Thermodynamic properties have not been calculated.

• ValueError – The type argument is not one of the allowed values.

Return type:

Figure

Returns: Plotly figure object containing the requested thermal electronic

property curves.

calculate_chemical_potential(energies, dos, temperature, chemical_potential_range=None, electron_tol=0.05)

Calculates the chemical potential at a given electronic DOS, temperature, and volume such that the number of electrons matches that at 0 K (within a specified tolerance). Note that this method currently assumes that the energies are given with respect to the Fermi energy.

Parameters:

• energies (ndarray) – Energy values for the electron DOS.

• dos (ndarray) – Electron DOS values.

• temperature (float) – Temperature in K.

• chemical_potential_range (ndarray | None) – Optional range to search for the chemical potential in eV. Defaults to None, which uses [-0.1, 0.1] eV.

• electron_tol (float) – Tolerance for electron number matching. Defaults to 0.05.

Raises:

• ValueError – If temperature < 0 K.

• ValueError – If the chemical potential cannot be found within the specified range.

Return type:

float

Returns: Chemical potential at the given electronic DOS, temperature, and volume.

static fit_electron_dos(energies, dos, energy_range, resolution)

Fits the electron DOS with a spline.

Parameters:

• energies (ndarray) – Energy values for the electron DOS, in eV.

• dos (ndarray) – Electron DOS values, in states/eV.

• energy_range (ndarray) – Energy range to fit the electron DOS, in eV.

• resolution (float) – Energy resolution for the spline, in eV.

Return type:

tuple[ndarray, ndarray]

Returns: Fitted energy and DOS values.

static fermi_dirac_distribution(energies, chemical_potential, temperature, plot=False)

Calculates the Fermi-Dirac distribution function.

Parameters:

• energies (ndarray) – Energy values for the electron DOS, in eV.

• chemical_potential (float) – Chemical potential for a given volume and temperature, in eV.

• temperature (float) – Temperature in K.

• plot (bool) – If True, plots the Fermi-Dirac distribution function vs. energy for the given temperature and chemical potential. Defaults to False.

Raises:

ValueError – If temperature < 0 K.

Return type:

ndarray | tuple[ndarray, Figure]

Returns: Fermi-Dirac distribution function values, and optionally the Plotly figure if plot=True.

static plot_fermi_dirac_distribution(energies, fermi_dist, chemical_potential, temperature)

Plots the Fermi-Dirac distribution function versus energy for a given temperature and chemical potential.

Parameters:

• energies (ndarray) – Energy values for the electron DOS, in eV.

• fermi_dist (ndarray) – Fermi-Dirac distribution function values.

• chemical_potential (float) – Chemical potential for a given volume and temperature, in eV.

• temperature (float) – Temperature in K.

Return type:

Figure

Returns: Plotly figure object containing the Fermi-Dirac distribution function curve.

static calculate_num_electrons(energies, dos, chemical_potential, temperature)

Calculates the number of electrons for a given electronic DOS, chemical potential, and temperature.

Parameters:

• energies (ndarray) – Energy values for the electron DOS, in eV.

• dos (ndarray) – Electron DOS values, in states/eV.

• chemical_potential (float) – Chemical potential for a given volume and temperature, in eV.

• temperature (float) – Temperature in K.

Raises:

ValueError – If temperature < 0 K.

Return type:

float

Returns: Number of electrons.

calculate_internal_energies(energies, dos, temperatures, resolution=0.001, plot=False, plot_temperature=None)

Calculates the thermal electronic contribution to the internal energy for a given volume.

Parameters:

• energies (ndarray) – Energy values from the electron DOS, in eV.

• dos (ndarray) – Electron DOS values, in states/eV.

• temperatures (ndarray) – Temperatures in K.

• resolution (float) – Energy resolution for the spline, in eV. Defaults to 0.001.

• plot (bool) – If True, plots the integrand vs. energy. Defaults to False.

• plot_temperature (float) – Temperature to plot the integrand, in K. Required if plot=True. Defaults to None.

Raises:

• ValueError – If any temperature is negative.

• ValueError – If plot_temperature is provided when plot=False or missing when plot=True.

• ValueError – If plot_temperature is not in temperatures when plot=True.

Return type:

ndarray | tuple[ndarray, Figure, Figure]

Returns: Internal energy values, in eV and optionally the Plotly figures if plot=True.

static plot_internal_energy_integral(energies, integrand_1, filtered_energies, integrand_2, plot_temperature)

Plots the integrands versus energy of the internal energy equation.

Parameters:

• energies (ndarray) – Energy values for the electron DOS, in eV.

• integrand_1 (ndarray) – First integrand from the internal energy equation.

• filtered_energies (ndarray) – Filtered energy values where E < mu, in eV.

• integrand_2 (ndarray) – Second integrand from the internal energy equation.

• plot_temperature (float) – Temperature at which the integrand is plotted, in K.

Return type:

tuple[Figure, Figure]

Returns: Plotly figure objects containing the integrand curves.

calculate_entropies(energies, dos, temperatures, energies_fit_range=array([-2, 2]), resolution=0.0001, plot=False, plot_temperature=None)

Calculates the thermal electronic contribution to the entropy for a given volume.

Parameters:

• energies (ndarray) – Energy values for the electron DOS, in eV.

• dos (ndarray) – Electron DOS values, in states/eV.

• temperatures (ndarray) – Temperatures in K.

• energies_fit_range (ndarray) – Energy range to fit the electron DOS, in eV. Defaults to np.array([-2, 2]).

• resolution (float) – Energy resolution for the spline, in eV. Defaults to 0.0001.

• plot (bool) – If True, plots the integrand vs. energy of the entropy equation. Defaults to False.

• plot_temperature (float | None) – Temperature to plot the integrand vs. energy. Defaults to None.

Raises:

• ValueError – If there are negative temperatures.

• ValueError – If plot_temperature is provided when plot=False or not provided when plot=True.

• ValueError – If plot_temperature is not in temperatures when plot=True.

Return type:

ndarray | tuple[ndarray, Figure]

Returns: Entropy values as a function of temperature, in eV/K

and optionally the Plotly figure if plot=True.

static plot_entropy_integral(energies, integrand, plot_temperature)

Plots the integrand vs. energy of the entropy equation.

Parameters:

• energies (ndarray) – Energy values for the electron DOS, in eV.

• integrand (ndarray) – Integrand from the entropy equation.

• plot_temperature (float) – Temperature in K.

Return type:

Figure

Returns: Plotly figure object showing the integrand as a function of energy.

calculate_heat_capacities(energies, dos, temperatures, energies_fit_range=array([-2, 2]), resolution=0.0001, plot=False, plot_temperature=None)

Calculates the thermal electronic contribution to the heat capacity for a given volume.

Parameters:

• energies (ndarray) – Energy values for the electron DOS, in eV.

• dos (ndarray) – Electron DOS values, in states/eV.

• temperatures (ndarray) – Temperatures in K.

• energies_fit_range (ndarray) – Energy range to fit the electron DOS. Defaults to np.array([-2, 2]) eV.

• resolution (float) – Energy resolution for the spline. Defaults to 0.0001 eV.

• plot (bool) – If True, plots the integrand vs. energy of the heat capacity equation. Defaults to False.

• plot_temperature (float | None) – Temperature to plot the integrand. Defaults to None.

Raises:

• ValueError – If there are negative temperatures.

• ValueError – If plot_temperature is provided when plot=False or not provided when plot=True.

• ValueError – If plot_temperature is not in temperatures when plot=True.

Return type:

ndarray | tuple[ndarray, Figure]

Returns: Heat capacity values in eV/K and optionally the Plotly figure if plot=True.

static plot_heat_capacity_integral(energies, integrand, plot_temperature)

Plots the integrand vs. energy of the heat capacity equation.

Parameters:

• energies (ndarray) – Energy values for the electron DOS, in eV.

• integrand (ndarray) – Integrand from the heat capacity equation.

• plot_temperature (float) – Temperature in K.

Return type:

Figure

Returns: Plotly figure object containing the integrand vs. energy curve for the

specified temperature.

static calculate_helmholtz_energies(internal_energies, entropies, temperatures)

Calculates the thermal electronic contribution to the Helmholtz free energy for a given volume.

Parameters:

• internal_energies (ndarray) – Internal energy values, in eV.

• entropies (ndarray) – Entropy values, in eV/K.

• temperatures (ndarray) – Temperatures in K.

Return type:

ndarray

Returns: Helmholtz free energy values, in eV.

ThermalElectronicData

class dfttk.thermal_electronic.thermal_electronic_data.ThermalElectronicData(path)

Bases: object

A convenience class used by the Configuration class.

Uses the ThermalElectronic class to process thermal electronic data from a set of VASP calculations at different volumes and generate plots. It also includes a built-in method to store the VASP input files used for the electron DOS calculations.

Parameters:

path (str) – Path to the directory containing the electron DOS VASP calculations.

path

Path to the directory containing electronic DOS data.

incars

List of INCAR objects for each volume.

kpoints

List of KPOINTS objects for each volume.

potcar

POTCAR object.

structures

Relaxed structures for each volume.

number_of_atoms

Number of atoms used in the DOS calculations.

volumes

Array of volumes for each structure, shape (n_volumes,), in ų.

temperatures

Array of temperatures, shape (n_temperatures,), in K.

helmholtz_energies

Helmholtz free energy as a function of temperature and volume, shape (n_temperatures, n_volumes), in eV.

internal_energies

Internal energy as a function of temperature and volume, shape (n_temperatures, n_volumes), in eV.

entropies

Entropy as a function of temperature and volume, shape (n_temperatures, n_volumes), in eV/K.

heat_capacities

Heat capacity as a function of temperature and volume, shape (n_temperatures, n_volumes), in eV/K.

volumes_fit

Volumes used for polynomial fits, shape (n_volumes_fit,), in ų.

helmholtz_energies_fit

Polynomial-fitted Helmholtz free energies as a function of temperature and fitted volume, shape (n_temperatures, n_volumes_fit), in eV.

entropies_fit

Polynomial-fitted entropies as a function of temperature and fitted volume, shape (n_temperatures, n_volumes_fit), in eV/K.

heat_capacities_fit

Polynomial-fitted heat capacities as a function of temperature and fitted volume, shape (n_temperatures, n_volumes_fit), in eV/K.

helmholtz_energies_poly_coeffs

Polynomial coefficients for Helmholtz free energy fits as a function of volume, shape (n_temperatures, order + 1).

entropies_poly_coeffs

Polynomial coefficients for entropy fits as a function of volume, shape (n_temperatures, order + 1).

heat_capacities_poly_coeffs

Polynomial coefficients for heat capacity fits as a function of volume, shape (n_temperatures, order + 1).

_helmholtz_energies_fit_to_db

Reformatted helmholtz_energies_poly_coeffs for database export.

_entropies_fit_to_db

Reformatted entropies_poly_coeffs for database export.

_heat_capacities_fit_to_db

Reformatted heat_capacities_poly_coeffs for database export.

get_vasp_data(incar_keys=['elec_dos'], incar_names=['INCAR.elec_dos'], kpoints_keys=['elec_dos'], kpoints_names=['KPOINTS.elec_dos'], contcar_name='CONTCAR.elec_dos', selected_volumes=None, selected_folders=None, folder_prefix='elec')

Get relevant VASP data from the specified path and folders and store them in the class attributes.

Parameters:

• incar_keys (list[str]) – List of INCAR keys for dictionary keys. Defaults to [“elec_dos”].

• incar_names (list[str]) – List of INCAR files to read. Defaults to [“INCAR.elec_dos”].

• kpoints_keys (list[str]) – List of KPOINTS keys for dictionary keys. Defaults to [“elec_dos”].

• kpoints_names (list[str]) – List of KPOINTS files to read. Defaults to [“KPOINTS.elec_dos”].

• contcar_name (str) – Name of the CONTCAR file to read. Defaults to “CONTCAR.elec_dos”.

• selected_volumes (ndarray | None) – NumPy array of selected volumes to keep the electron DOS data, or None to keep all volumes. Defaults to None.

• selected_folders (list[str] | None) – List of selected folders to keep the electron DOS data. Defaults to None.

• folder_prefix (str) – Prefix of the electronic folders. Defaults to "elec".

Raises:

ValueError – If both selected_volumes and selected_folders are provided, as they are mutually exclusive.

Return type:

None

get_thermal_electronic_data(volumes_fit, temperatures, order=1, folder_prefix='elec', vasprun_name='vasprun.xml.elec_dos', selected_volumes=None, selected_folders=None)

Calls the ThermalElectronic class to read the total electron DOS data, compute the thermodynamic properties, and generate plots.

Parameters:

• volumes_fit (ndarray) – Volumes used for polynomial fits, shape (n_volumes_fit,), in ų.

• temperatures (ndarray) – Array of temperatures, shape (n_temperatures,), in K.

• order (int) – Order of the polynomial fit. Defaults to 1 (linear fit).

• folder_prefix (str) – Prefix of the electronic folders. Defaults to "elec".

• vasprun_name (str) – Name of the vasprun.xml file. Defaults to "vasprun.xml.elec_dos".

• selected_volumes (ndarray | None) – Array of volumes to process. Defaults to None.

• selected_folders (list[str] | None) – List of selected folders to keep the electron DOS data. Defaults to None.

plot_total_dos()

Plots the total electron DOS for different volumes.

Return type:

Figure

Returns: Plotly figure object containing the total electron DOS curves for

the different volumes.

plot_vt(type, selected_temperatures=None)

Plots thermal electronic properties as a function of temperature or volume.

Parameters:

• type (str) – Must be one of the following values: 'helmholtz_energy_vs_temperature', 'entropy_vs_temperature', 'heat_capacity_vs_temperature', 'helmholtz_energy_vs_volume', 'entropy_vs_volume', or 'heat_capacity_vs_volume'.

• selected_temperatures (ndarray) – Selected temperatures to use for volume plots, shape (n_selected_temperatures,). Defaults to None.

Return type:

Figure

Returns: Plotly figure object containing the requested thermal electronic

property curves.