From b5c0839a24b42c08034612cfd850aec2d076feed Mon Sep 17 00:00:00 2001 From: "Nigel L. E. Hew" <77617652+nhew1994@users.noreply.github.com> Date: Fri, 9 Jan 2026 16:04:28 -0500 Subject: [PATCH 01/66] Fix module reference in thermal_electronic documentation --- docs/api/dfttk.thermal_electronic.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/api/dfttk.thermal_electronic.rst b/docs/api/dfttk.thermal_electronic.rst index fd1a2fd..42e6b48 100644 --- a/docs/api/dfttk.thermal_electronic.rst +++ b/docs/api/dfttk.thermal_electronic.rst @@ -6,10 +6,10 @@ dfttk.thermal_electronic :undoc-members: :show-inheritance: -functions ---------- +thermal_electronic +------------------ -.. automodule:: dfttk.thermal_electronic.functions +.. automodule:: dfttk.thermal_electronic.thermal_electronic :members: :undoc-members: :show-inheritance: From 662917db1e1a39fef8a21600789c048a6ad52404 Mon Sep 17 00:00:00 2001 From: "Nigel L. E. Hew" <77617652+nhew1994@users.noreply.github.com> Date: Fri, 9 Jan 2026 16:23:00 -0500 Subject: [PATCH 02/66] Update docstring for thermal electronic class attributes --- .../thermal_electronic/thermal_electronic.py | 36 +++++++++---------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index 31fdf78..6b859dd 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -45,24 +45,24 @@ class ThermalElectronic: Class for reading or setting electron DOS data, calculating thermal electronic properties, and generating plots. Attributes: - path (str): path to the directory containing electronic DOS data. - number_of_atoms (int): number of atoms corresponding to the structures used in the electron DOS calculations. - nelect (int): number of electrons corresponding to the electron DOS data. - volumes (np.ndarray): array of volumes for each structure (n_volumes,). - energies_list (list[np.ndarray]): list of arrays of energy minus Fermi energy values for each volume. - dos_list (list[np.ndarray]): list of arrays of DOS values for each volume. - temperatures (np.ndarray): array of temperatures in K (n_temperatures,). - helmholtz_energies (np.ndarray): Helmholtz free energies (eV) (n_temperatures, n_volumes). - internal_energies (np.ndarray): internal energies (eV) (n_temperatures, n_volumes). - entropies (np.ndarray): entropies (eV/K) (n_temperatures, n_volumes). - heat_capacities (np.ndarray): heat capacities (eV/K) (n_temperatures, n_volumes). - volumes_fit (np.ndarray): volumes used for polynomial fits (n_volumes_fit,). - helmholtz_energies_fit (np.ndarray): fitted Helmholtz free energies (n_temperatures, n_volumes_fit). - entropies_fit (np.ndarray): fitted entropies (n_temperatures, n_volumes_fit). - heat_capacities_fit (np.ndarray): fitted heat capacities (n_temperatures, n_volumes_fit). - helmholtz_energies_poly_coeffs (np.ndarray): polynomial coefficients for Helmholtz energy fits (n_temperatures, order + 1). - entropies_poly_coeffs (np.ndarray): polynomial coefficients for entropy fits (n_temperatures, order + 1). - heat_capacities_poly_coeffs (np.ndarray): polynomial coefficients for heat capacity fits (n_temperatures, order + 1). + path (str): path to the directory containing electronic DOS data. + number_of_atoms (int): number of atoms corresponding to the structures used in the electron DOS calculations. + nelect (int): number of electrons corresponding to the electron DOS data. + volumes (np.ndarray): array of volumes for each structure (n_volumes,). + energies_list (list[np.ndarray]): list of arrays of energy minus Fermi energy values for each volume. + dos_list (list[np.ndarray]): list of arrays of DOS values for each volume. + temperatures (np.ndarray): array of temperatures in K (n_temperatures,). + helmholtz_energies (np.ndarray): Helmholtz free energies (eV) (n_temperatures, n_volumes). + internal_energies (np.ndarray): internal energies (eV) (n_temperatures, n_volumes). + entropies (np.ndarray): entropies (eV/K) (n_temperatures, n_volumes). + heat_capacities (np.ndarray): heat capacities (eV/K) (n_temperatures, n_volumes). + volumes_fit (np.ndarray): volumes used for polynomial fits (n_volumes_fit,). + helmholtz_energies_fit (np.ndarray): fitted Helmholtz free energies (n_temperatures, n_volumes_fit). + entropies_fit (np.ndarray): fitted entropies (n_temperatures, n_volumes_fit). + heat_capacities_fit (np.ndarray): fitted heat capacities (n_temperatures, n_volumes_fit). + helmholtz_energies_poly_coeffs (np.ndarray): polynomial coefficients for Helmholtz energy fits (n_temperatures, order + 1). + entropies_poly_coeffs (np.ndarray): polynomial coefficients for entropy fits (n_temperatures, order + 1). + heat_capacities_poly_coeffs (np.ndarray): polynomial coefficients for heat capacity fits (n_temperatures, order + 1). """ def __init__(self): From 99dcc55b8baa4a9aad007499809d00cd1574c2ba Mon Sep 17 00:00:00 2001 From: "Nigel L. E. Hew" <77617652+nhew1994@users.noreply.github.com> Date: Fri, 9 Jan 2026 16:30:51 -0500 Subject: [PATCH 03/66] Refine docstring for ThermalElectronic class Updated class docstring for ThermalElectronic to improve clarity and structure. --- .../thermal_electronic/thermal_electronic.py | 29 +++++++++---------- 1 file changed, 13 insertions(+), 16 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index 6b859dd..7fa8ce9 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -1,18 +1,3 @@ -""" -ThermalElectronic ------------------ -A class for reading or setting electron DOS data, calculating thermal electronic properties, and generating plots. - -Typical usage: - 1. Load electron 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, heat capacity) - using `process()` and `fit()`. - 3. Visualize results with the provided plotting methods. - -Additional intermediate methods are available for calculating chemical potential, fitting DOS, computing the Fermi-Dirac distribution, etc. -""" - # Standard Library Imports import os import warnings @@ -42,20 +27,32 @@ # TODO: Update methods in other modules to reflect all updates made here! class ThermalElectronic: """ - Class for reading or setting electron DOS data, calculating thermal electronic properties, and generating plots. + A class for reading or setting electron DOS data, calculating thermal electronic properties, and generating plots. + + Typical usage: + 1. Load electron 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, heat capacity) + using `process()` and `fit()`. + 3. Visualize results with the provided plotting methods. + + Additional intermediate methods are available for calculating chemical potential, fitting DOS, computing the Fermi-Dirac distribution, etc. Attributes: path (str): path to the directory containing electronic DOS data. number_of_atoms (int): number of atoms corresponding to the structures used in the electron DOS calculations. nelect (int): number of electrons corresponding to the electron DOS data. + volumes (np.ndarray): array of volumes for each structure (n_volumes,). energies_list (list[np.ndarray]): list of arrays of energy minus Fermi energy values for each volume. dos_list (list[np.ndarray]): list of arrays of DOS values for each volume. + temperatures (np.ndarray): array of temperatures in K (n_temperatures,). helmholtz_energies (np.ndarray): Helmholtz free energies (eV) (n_temperatures, n_volumes). internal_energies (np.ndarray): internal energies (eV) (n_temperatures, n_volumes). entropies (np.ndarray): entropies (eV/K) (n_temperatures, n_volumes). heat_capacities (np.ndarray): heat capacities (eV/K) (n_temperatures, n_volumes). + volumes_fit (np.ndarray): volumes used for polynomial fits (n_volumes_fit,). helmholtz_energies_fit (np.ndarray): fitted Helmholtz free energies (n_temperatures, n_volumes_fit). entropies_fit (np.ndarray): fitted entropies (n_temperatures, n_volumes_fit). From 5675c99543e2028b7ed656d6e0418b0a5794220b Mon Sep 17 00:00:00 2001 From: "Nigel L. E. Hew" <77617652+nhew1994@users.noreply.github.com> Date: Fri, 9 Jan 2026 16:36:12 -0500 Subject: [PATCH 04/66] Set autodoc member order to source code order --- docs/conf.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 3372381..05ae785 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -30,6 +30,9 @@ ] autosummary_generate = True +# Make autodoc list members in the order they appear in the source code +autodoc_member_order = 'bysource' + # Jupyter Notebook configuration nb_execution_mode = "off" nb_execution_cache_path = "../temp/jupyter_cache" From 4c0cc82d9a1e172bb47f7480f25006d481a4747e Mon Sep 17 00:00:00 2001 From: "Nigel L. E. Hew" <77617652+nhew1994@users.noreply.github.com> Date: Fri, 9 Jan 2026 16:42:06 -0500 Subject: [PATCH 05/66] Fix formatting of attributes section in docstring --- dfttk/thermal_electronic/thermal_electronic.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index 7fa8ce9..e6d8dc2 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -38,7 +38,7 @@ class ThermalElectronic: Additional intermediate methods are available for calculating chemical potential, fitting DOS, computing the Fermi-Dirac distribution, etc. - Attributes: + **Attributes** path (str): path to the directory containing electronic DOS data. number_of_atoms (int): number of atoms corresponding to the structures used in the electron DOS calculations. nelect (int): number of electrons corresponding to the electron DOS data. From bc6c0eea64d4cb589ca799c5c08a6ebbba9f7742 Mon Sep 17 00:00:00 2001 From: "Nigel L. E. Hew" <77617652+nhew1994@users.noreply.github.com> Date: Fri, 9 Jan 2026 16:46:49 -0500 Subject: [PATCH 06/66] Fix formatting of attributes section in docstring --- dfttk/thermal_electronic/thermal_electronic.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index e6d8dc2..d6b5b84 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -38,7 +38,8 @@ class ThermalElectronic: Additional intermediate methods are available for calculating chemical potential, fitting DOS, computing the Fermi-Dirac distribution, etc. - **Attributes** + Attributes + ---------- path (str): path to the directory containing electronic DOS data. number_of_atoms (int): number of atoms corresponding to the structures used in the electron DOS calculations. nelect (int): number of electrons corresponding to the electron DOS data. From 1c10f88c43c0a84dcb5f94b7cd25bc49316fa2ff Mon Sep 17 00:00:00 2001 From: "Nigel L. E. Hew" <77617652+nhew1994@users.noreply.github.com> Date: Fri, 9 Jan 2026 16:47:29 -0500 Subject: [PATCH 07/66] Remove members directive from thermal_electronic docs --- docs/api/dfttk.thermal_electronic.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/api/dfttk.thermal_electronic.rst b/docs/api/dfttk.thermal_electronic.rst index 42e6b48..f7d0e2e 100644 --- a/docs/api/dfttk.thermal_electronic.rst +++ b/docs/api/dfttk.thermal_electronic.rst @@ -2,7 +2,6 @@ dfttk.thermal_electronic ======================== .. automodule:: dfttk.thermal_electronic - :members: :undoc-members: :show-inheritance: @@ -10,7 +9,6 @@ thermal_electronic ------------------ .. automodule:: dfttk.thermal_electronic.thermal_electronic - :members: :undoc-members: :show-inheritance: @@ -18,6 +16,5 @@ thermal_electronic_data ----------------------- .. automodule:: dfttk.thermal_electronic.thermal_electronic_data - :members: :undoc-members: :show-inheritance: From f0f2f7eb06a2447d3ee6fabcb2eaf1215b5039ee Mon Sep 17 00:00:00 2001 From: "Nigel L. E. Hew" <77617652+nhew1994@users.noreply.github.com> Date: Fri, 9 Jan 2026 16:56:50 -0500 Subject: [PATCH 08/66] Update documentation for ThermalElectronic classes --- docs/api/dfttk.thermal_electronic.rst | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/api/dfttk.thermal_electronic.rst b/docs/api/dfttk.thermal_electronic.rst index f7d0e2e..2972e5a 100644 --- a/docs/api/dfttk.thermal_electronic.rst +++ b/docs/api/dfttk.thermal_electronic.rst @@ -5,16 +5,17 @@ dfttk.thermal_electronic :undoc-members: :show-inheritance: -thermal_electronic ------------------- +ThermalElectronic Class +---------------------- -.. automodule:: dfttk.thermal_electronic.thermal_electronic +.. autoclass:: dfttk.thermal_electronic.thermal_electronic.ThermalElectronic + :members: :undoc-members: :show-inheritance: -thermal_electronic_data ------------------------ +ThermalElectronicClass +------------------------------ -.. automodule:: dfttk.thermal_electronic.thermal_electronic_data +.. autoclass:: dfttk.thermal_electronic.thermal_electronic_data.ThermalElectronicData :undoc-members: :show-inheritance: From 7738109afa3528a0fb4378c300cbeff5a8e551c7 Mon Sep 17 00:00:00 2001 From: "Nigel L. E. Hew" <77617652+nhew1994@users.noreply.github.com> Date: Fri, 9 Jan 2026 16:57:37 -0500 Subject: [PATCH 09/66] Fix headings for ThermalElectronic documentation --- docs/api/dfttk.thermal_electronic.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/api/dfttk.thermal_electronic.rst b/docs/api/dfttk.thermal_electronic.rst index 2972e5a..3b965b8 100644 --- a/docs/api/dfttk.thermal_electronic.rst +++ b/docs/api/dfttk.thermal_electronic.rst @@ -5,16 +5,16 @@ dfttk.thermal_electronic :undoc-members: :show-inheritance: -ThermalElectronic Class ----------------------- +ThermalElectronic +----------------- .. autoclass:: dfttk.thermal_electronic.thermal_electronic.ThermalElectronic :members: :undoc-members: :show-inheritance: -ThermalElectronicClass ------------------------------- +ThermalElectronicData +--------------------- .. autoclass:: dfttk.thermal_electronic.thermal_electronic_data.ThermalElectronicData :undoc-members: From 6542dd5904b536d9e96f5166b053b6b662067c06 Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Fri, 9 Jan 2026 19:07:14 -0500 Subject: [PATCH 10/66] MAINT: update ThermalElectronic docstrings --- .../thermal_electronic/thermal_electronic.py | 106 ++++++++++++------ 1 file changed, 71 insertions(+), 35 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index d6b5b84..7a57608 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -27,47 +27,83 @@ # TODO: Update methods in other modules to reflect all updates made here! class ThermalElectronic: """ - A class for reading or setting electron DOS data, calculating thermal electronic properties, and generating plots. + A class for reading or setting electronic density-of-states (DOS) data, + calculating thermal electronic properties, and generating plots. Typical usage: - 1. Load electron 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, heat capacity) - using `process()` and `fit()`. + 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 chemical potential, fitting DOS, computing the Fermi-Dirac distribution, etc. - - Attributes - ---------- - path (str): path to the directory containing electronic DOS data. - number_of_atoms (int): number of atoms corresponding to the structures used in the electron DOS calculations. - nelect (int): number of electrons corresponding to the electron DOS data. - - volumes (np.ndarray): array of volumes for each structure (n_volumes,). - energies_list (list[np.ndarray]): list of arrays of energy minus Fermi energy values for each volume. - dos_list (list[np.ndarray]): list of arrays of DOS values for each volume. - - temperatures (np.ndarray): array of temperatures in K (n_temperatures,). - helmholtz_energies (np.ndarray): Helmholtz free energies (eV) (n_temperatures, n_volumes). - internal_energies (np.ndarray): internal energies (eV) (n_temperatures, n_volumes). - entropies (np.ndarray): entropies (eV/K) (n_temperatures, n_volumes). - heat_capacities (np.ndarray): heat capacities (eV/K) (n_temperatures, n_volumes). - - volumes_fit (np.ndarray): volumes used for polynomial fits (n_volumes_fit,). - helmholtz_energies_fit (np.ndarray): fitted Helmholtz free energies (n_temperatures, n_volumes_fit). - entropies_fit (np.ndarray): fitted entropies (n_temperatures, n_volumes_fit). - heat_capacities_fit (np.ndarray): fitted heat capacities (n_temperatures, n_volumes_fit). - helmholtz_energies_poly_coeffs (np.ndarray): polynomial coefficients for Helmholtz energy fits (n_temperatures, order + 1). - entropies_poly_coeffs (np.ndarray): polynomial coefficients for entropy fits (n_temperatures, order + 1). - heat_capacities_poly_coeffs (np.ndarray): polynomial coefficients for heat capacity fits (n_temperatures, order + 1). + + Additional intermediate methods are available for calculating the chemical + potential, fitting the DOS, computing the Fermi-Dirac distribution, and + related quantities. + + Attributes: + path (str): + Path to the directory containing electronic DOS data. + number_of_atoms (int): + Number of atoms corresponding to the structures used in the + electronic DOS calculations. + nelect (int): + Total number of electrons corresponding to the electronic DOS data. + + volumes (np.ndarray): + Array of volumes for each structure, shape (n_volumes,), in ų. + energies_list (list[np.ndarray]): + List of arrays of electronic energies referenced to the Fermi level + (E - E_F) for each volume, in eV. + dos_list (list[np.ndarray]): + List of arrays of electronic DOS values for each volume, in states/eV. + + temperatures (np.ndarray): + Array of temperatures, shape (n_temperatures,), in K. + helmholtz_energies (np.ndarray): + Helmholtz free energy as a function of temperature and volume, + shape (n_temperatures, n_volumes), in eV. + internal_energies (np.ndarray): + Internal energy as a function of temperature and volume, + shape (n_temperatures, n_volumes), in eV. + entropies (np.ndarray): + Entropy as a function of temperature and volume, + shape (n_temperatures, n_volumes), in eV/K. + heat_capacities (np.ndarray): + Heat capacity as a function of temperature and volume, + shape (n_temperatures, n_volumes), in eV/K. + + volumes_fit (np.ndarray): + Volumes used for polynomial fits, + shape (n_volumes_fit,), in ų. + helmholtz_energies_fit (np.ndarray): + Polynomial-fitted Helmholtz free energies as a function of + temperature and fitted volume, + shape (n_temperatures, n_volumes_fit), in eV. + entropies_fit (np.ndarray): + Polynomial-fitted entropies as a function of temperature and + fitted volume, + shape (n_temperatures, n_volumes_fit), in eV/K. + heat_capacities_fit (np.ndarray): + 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 (np.ndarray): + Polynomial coefficients for Helmholtz free energy fits as a + function of volume, + shape (n_temperatures, order + 1). + entropies_poly_coeffs (np.ndarray): + Polynomial coefficients for entropy fits as a function of volume, + shape (n_temperatures, order + 1). + heat_capacities_poly_coeffs (np.ndarray): + Polynomial coefficients for heat capacity fits as a function of + volume, + shape (n_temperatures, order + 1). """ def __init__(self): - """ - Initializes the ThermalElectronic class with default attributes set to None. - """ - self.path = None self.number_of_atoms = None self.nelect = None From 2e0840ad7759546578ea83fdd2ea8ee5d5a0c1f0 Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Fri, 9 Jan 2026 19:11:06 -0500 Subject: [PATCH 11/66] MAINT: update ThermalElectronic docstrings --- dfttk/thermal_electronic/thermal_electronic.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index 7a57608..5561973 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -34,9 +34,11 @@ class ThermalElectronic: 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 From 896b963aeede1803643e4748110eb9c90bd136e9 Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Fri, 9 Jan 2026 19:17:30 -0500 Subject: [PATCH 12/66] MAINT: update ThermalElectronic docstrings --- .../thermal_electronic/thermal_electronic.py | 49 ++++++++----------- 1 file changed, 21 insertions(+), 28 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index 5561973..d4da238 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -31,14 +31,13 @@ class ThermalElectronic: 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 @@ -46,19 +45,15 @@ class ThermalElectronic: related quantities. Attributes: - path (str): - Path to the directory containing electronic DOS data. - number_of_atoms (int): - Number of atoms corresponding to the structures used in the - electronic DOS calculations. - nelect (int): - Total number of electrons corresponding to the electronic DOS data. + path (str): Path to the directory containing electronic DOS data. + number_of_atoms (int): Number of atoms used in the DOS calculations. + nelect (int): Total number of electrons in the DOS data. volumes (np.ndarray): Array of volumes for each structure, shape (n_volumes,), in ų. energies_list (list[np.ndarray]): List of arrays of electronic energies referenced to the Fermi level - (E - E_F) for each volume, in eV. + (:math:`E - E_F`) for each volume, in eV. dos_list (list[np.ndarray]): List of arrays of electronic DOS values for each volume, in states/eV. @@ -78,31 +73,26 @@ class ThermalElectronic: shape (n_temperatures, n_volumes), in eV/K. volumes_fit (np.ndarray): - Volumes used for polynomial fits, - shape (n_volumes_fit,), in ų. + Volumes used for polynomial fits, shape (n_volumes_fit,), in ų. helmholtz_energies_fit (np.ndarray): Polynomial-fitted Helmholtz free energies as a function of - temperature and fitted volume, - shape (n_temperatures, n_volumes_fit), in eV. + temperature and fitted volume, shape (n_temperatures, n_volumes_fit), in eV. entropies_fit (np.ndarray): Polynomial-fitted entropies as a function of temperature and - fitted volume, - shape (n_temperatures, n_volumes_fit), in eV/K. + fitted volume, shape (n_temperatures, n_volumes_fit), in eV/K. heat_capacities_fit (np.ndarray): - Polynomial-fitted heat capacities as a function of temperature - and fitted volume, - shape (n_temperatures, n_volumes_fit), in eV/K. + 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 (np.ndarray): - Polynomial coefficients for Helmholtz free energy fits as a - function of volume, - shape (n_temperatures, order + 1). + Polynomial coefficients for Helmholtz free energy fits as a function + of volume, shape (n_temperatures, order + 1). entropies_poly_coeffs (np.ndarray): Polynomial coefficients for entropy fits as a function of volume, shape (n_temperatures, order + 1). heat_capacities_poly_coeffs (np.ndarray): Polynomial coefficients for heat capacity fits as a function of - volume, - shape (n_temperatures, order + 1). + volume, shape (n_temperatures, order + 1). """ def __init__(self): @@ -129,14 +119,17 @@ def __init__(self): def _get_elec_folders(self, path: str, folder_prefix: str = "elec") -> list[str]: """ - Get the list of folders with prefix in the specified path, sorted in natural order. + Get the list of folders with the specified prefix in the given path, + sorted in natural order. Args: - path (str): path to the directory containing the folders. - folder_prefix (str, optional): prefix of the folders to search for. Defaults to "elec". + path (str): Path to the directory containing the folders. + folder_prefix (str, optional): Prefix of the folders to search for. + Defaults to ``"elec"``. Returns: - list[str]: list of folder names with prefix sorted in natural order. + list[str]: List of folder names with the given prefix, sorted in + natural order. """ return natsorted([f for f in os.listdir(path) if f.startswith(folder_prefix)]) From f0c6348812957206fb48d35cafd869c981221614 Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Fri, 9 Jan 2026 19:30:24 -0500 Subject: [PATCH 13/66] MAINT: update ThermalElectronic docstrings --- .../thermal_electronic/thermal_electronic.py | 133 ++++++++++++------ 1 file changed, 92 insertions(+), 41 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index d4da238..869798d 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -30,8 +30,8 @@ class ThermalElectronic: A class for reading or setting electronic density-of-states (DOS) data, calculating thermal electronic properties, and generating plots. - Typical usage: - + 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()`. @@ -140,19 +140,30 @@ def read_total_electron_dos( vasprun_name: str = "vasprun.xml.elec_dos", selected_volumes: np.ndarray = None, ) -> None: - """Reads the total electron DOS data from the VASP calculations for different volumes. + """ + Reads the total electron DOS data from VASP calculations for different volumes. Args: - path (str): path to the directory containing the specific folders containing the CONTCAR and vasprun.xml files. - folder_prefix (str, optional): prefix of the electronic folders. Defaults to "elec". - contcar_name (str, optional): name of the CONTCAR file. Defaults to "CONTCAR.elec_dos". - vasprun_name (str, optional): name of the vasprun.xml file. Defaults to "vasprun.xml.elec_dos". - selected_volumes (np.ndarray, optional): list of selected volumes to keep the electron DOS data. Defaults to None. + path (str): + Path to the directory containing the specific folders with + CONTCAR and vasprun.xml files. + folder_prefix (str, optional): + Prefix of the electronic folders. Defaults to ``"elec"``. + contcar_name (str, optional): + Name of the CONTCAR file. Defaults to ``"CONTCAR.elec_dos"``. + vasprun_name (str, optional): + Name of the vasprun.xml file. Defaults to ``"vasprun.xml.elec_dos"``. + selected_volumes (np.ndarray, optional): + List of selected volumes to keep the electron DOS data. Defaults + to None. Raises: - 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. + 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. """ self.path = path @@ -262,16 +273,23 @@ def set_total_electron_dos( energies_list: list[np.ndarray], dos_list: list[np.ndarray], ) -> None: - """Set the total electron DOS directly. + """ + Set the total electron DOS directly. Args: - number_of_atoms (int): number of atoms corresponding to the DOS data. - volumes (np.ndarray): 1D array of volumes. - energies_list (list[np.ndarray]): list of 1D arrays of energy minus Fermi energy values for each volume. - dos_list (list[np.ndarray]): list of 1D arrays of DOS values for each volume. + number_of_atoms (int): + Number of atoms corresponding to the DOS data. + volumes (np.ndarray): + 1D array of volumes, shape (n_volumes,), in ų. + energies_list (list[np.ndarray]): + List of 1D arrays of energies referenced to the Fermi level + (:math:`E - E_F`) for each volume, in eV. + dos_list (list[np.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. + ValueError: + Lengths of volumes, energies_list, and dos_list must be the same. """ self.number_of_atoms = number_of_atoms @@ -290,15 +308,22 @@ def process( self, temperatures: np.ndarray, ) -> None: - """Calculates the thermal electronic contributions to Helmholtz free energy, internal energy, entropy, and heat capacity. + """ + Calculates the thermal electronic contributions to Helmholtz free energy, + internal energy, entropy, and heat capacity. Args: - volumes_fit (np.ndarray): 1D array of volumes to fit the properties to. - temperatures (np.ndarray): 1D array of temperatures in K. - order (int): order of the polynomial fit. Defaults to 1 (linear fit). + volumes_fit (np.ndarray): + 1D array of volumes used for fitting the properties, shape + (n_volumes_fit,), in ų. + temperatures (np.ndarray): + 1D array of temperatures in K, shape (n_temperatures,). + order (int): + Order of the polynomial fit. Defaults to 1 (linear fit). Raises: - ValueError: If DOS data is not found. + ValueError: + If DOS data is not found. """ self.temperatures = temperatures @@ -306,7 +331,8 @@ def process( # If dos_list is None, raise an error if self.dos_list is None: raise ValueError( - "DOS data not found. Please read or set the total electron DOS first using read_total_electron_dos() or set_total_electron_dos()." + "DOS data not found. Please read or set the total electron DOS first " + "using `read_total_electron_dos()` or `set_total_electron_dos()`." ) # Initialize lists to store data @@ -348,14 +374,20 @@ def fit( volumes_fit: np.ndarray, order: int = 1, ) -> None: - """Fits the Helmholtz free energy, entropy, and heat capacity vs. volume for various fixed temperatures. + """ + Fits the Helmholtz free energy, entropy, and heat capacity as a function + of volume for various fixed temperatures. Args: - volumes_fit (np.ndarray): 1D array of volumes to fit the properties to. - order (int): order of the polynomial fit. Defaults to 1 (linear fit). + volumes_fit (np.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: If thermodynamic properties have not been calculated. + ValueError: + Thermodynamic properties have not been calculated. """ # If helmholtz_energies is None, raise an error @@ -419,19 +451,25 @@ def fit( self.heat_capacities_poly_coeffs = np.array(heat_capacities_poly_coeffs) def plot_total_dos(self): - """Plots the total electron DOS for different volumes. + """ + Plots the total electron DOS for different volumes. Raises: - ValueError: If DOS data is not found. + 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: - go.Figure: Plotly figure object. + go.Figure: + Plotly figure object containing the total electron DOS curves for + the different volumes. """ # If dos_list is None, raise an error if self.dos_list is None: raise ValueError( - "DOS data not found. Please read or set the total electron DOS first using read_total_electron_dos() or set_total_electron_dos()." + "DOS data not found. Please read or set the total electron DOS first " + "using `read_total_electron_dos()` or `set_total_electron_dos()`." ) fig = go.Figure() @@ -454,25 +492,36 @@ def plot_total_dos(self): return fig def plot_vt(self, type: str, selected_temperatures: np.ndarray = None) -> go.Figure: - """Plots thermal electronic properties vs. temperature or volume. + """ + Plots thermal electronic properties as a function of temperature or volume. Args: - type (str): Must be one of '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 (np.ndarray, optional): Selected temperatures for volume plots. Defaults to None. + 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 (np.ndarray, optional): + Selected temperatures to use for volume plots, shape + (n_selected_temperatures,). Defaults to None. Raises: - ValueError: If thermodynamic properties have not been calculated. - ValueError: If the type argument is not one of the allowed values. + ValueError: + Thermodynamic properties have not been calculated. + ValueError: + The `type` argument is not one of the allowed values. Returns: - go.Figure: Plotly figure object. + go.Figure: + Plotly figure object containing the requested thermal electronic + property curves. """ # If helmholtz_energies is None, raise an error if self.helmholtz_energies is None: raise ValueError( - "Thermodynamic properties not yet calculated. Please call process() first." + "Thermodynamic properties not yet calculated. " + "Please call `process()` first." ) type_map = { @@ -504,8 +553,10 @@ def plot_vt(self, type: str, selected_temperatures: np.ndarray = None) -> go.Fig if type not in type_map: raise ValueError( - "type must be one of 'helmholtz_energy_vs_temperature', 'entropy_vs_temperature', 'heat_capacity_vs_temperature', " - "'helmholtz_energy_vs_volume', 'entropy_vs_volume', or 'heat_capacity_vs_volume'" + "type must be one of " + "`'helmholtz_energy_vs_temperature'`, `'entropy_vs_temperature'`, " + "`'heat_capacity_vs_temperature'`, `'helmholtz_energy_vs_volume'`, " + "`'entropy_vs_volume'`, or `'heat_capacity_vs_volume'`." ) if "vs_temperature" in type: From 9190b7120740ff647ab1a91a9fd99fb5ac0099a3 Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Fri, 9 Jan 2026 19:34:02 -0500 Subject: [PATCH 14/66] MAINT: update ThermalElectronic docstrings --- dfttk/thermal_electronic/thermal_electronic.py | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index 869798d..574ae4a 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -30,15 +30,15 @@ class ThermalElectronic: 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. + Typical usage: + + #. 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()`. + #. Compute thermal electronic contributions (Helmholtz free energy, + internal energy, entropy, and heat capacity) using `process()` and + `fit()`. + #. 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 From 8d61d5426cfba5a5f1a8c13478411d8082785c4f Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Fri, 9 Jan 2026 19:36:47 -0500 Subject: [PATCH 15/66] MAINT: update ThermalElectronic docstrings --- dfttk/thermal_electronic/thermal_electronic.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index 574ae4a..751629a 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -469,7 +469,7 @@ def plot_total_dos(self): if self.dos_list is None: raise ValueError( "DOS data not found. Please read or set the total electron DOS first " - "using `read_total_electron_dos()` or `set_total_electron_dos()`." + "using read_total_electron_dos() or set_total_electron_dos()." ) fig = go.Figure() @@ -521,7 +521,7 @@ def plot_vt(self, type: str, selected_temperatures: np.ndarray = None) -> go.Fig if self.helmholtz_energies is None: raise ValueError( "Thermodynamic properties not yet calculated. " - "Please call `process()` first." + "Please call process() first." ) type_map = { @@ -554,9 +554,9 @@ def plot_vt(self, type: str, selected_temperatures: np.ndarray = None) -> go.Fig if type not in type_map: raise ValueError( "type must be one of " - "`'helmholtz_energy_vs_temperature'`, `'entropy_vs_temperature'`, " - "`'heat_capacity_vs_temperature'`, `'helmholtz_energy_vs_volume'`, " - "`'entropy_vs_volume'`, or `'heat_capacity_vs_volume'`." + "'helmholtz_energy_vs_temperature', 'entropy_vs_temperature', " + "'heat_capacity_vs_temperature', 'helmholtz_energy_vs_volume', " + "'entropy_vs_volume', or 'heat_capacity_vs_volume'." ) if "vs_temperature" in type: From 5bf04e1a5018c0f2318f13d719a70e544b30e3b0 Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Fri, 9 Jan 2026 19:42:21 -0500 Subject: [PATCH 16/66] MAINT: update ThermalElectronic docstrings --- dfttk/thermal_electronic/thermal_electronic.py | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index 751629a..268511f 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -32,13 +32,13 @@ class ThermalElectronic: Typical usage: - #. 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()`. - #. Compute thermal electronic contributions (Helmholtz free energy, - internal energy, entropy, and heat capacity) using `process()` and - `fit()`. - #. Visualize results with the provided plotting methods. +#. 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()`. +#. Compute thermal electronic contributions (Helmholtz free energy, +internal energy, entropy, and heat capacity) using `process()` and +`fit()`. +#. 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 From af551bdd8f31b6f26168420f138ecb9eba247909 Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Fri, 9 Jan 2026 19:46:30 -0500 Subject: [PATCH 17/66] MAINT: update ThermalElectronic docstrings --- dfttk/thermal_electronic/thermal_electronic.py | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index 268511f..a803fa0 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -32,13 +32,13 @@ class ThermalElectronic: Typical usage: -#. 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()`. -#. Compute thermal electronic contributions (Helmholtz free energy, -internal energy, entropy, and heat capacity) using `process()` and -`fit()`. -#. Visualize results with the provided plotting methods. + * 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()`. + * Compute thermal electronic contributions (Helmholtz free energy, + internal energy, entropy, and heat capacity) using `process()` and + `fit()`. + * 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 From afa290adedd414a2f0b351a578b7a62cb8e41fa1 Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Fri, 9 Jan 2026 19:53:34 -0500 Subject: [PATCH 18/66] MAINT: update ThermalElectronic docstrings --- .../thermal_electronic/thermal_electronic.py | 46 +++++++++++-------- 1 file changed, 26 insertions(+), 20 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index a803fa0..0f64264 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -32,13 +32,12 @@ class ThermalElectronic: Typical usage: - * Load electronic DOS data from VASP calculations for multiple volumes + 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()`. - * Compute thermal electronic contributions (Helmholtz free energy, - internal energy, entropy, and heat capacity) using `process()` and - `fit()`. - * Visualize results with the provided plotting methods. + `set_total_electron_dos()`.\n + 2. Compute thermal electronic contributions (Helmholtz free energy, + internal energy, entropy, and heat capacity) using `process()` and `fit()`.\n + 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 @@ -644,23 +643,28 @@ def calculate_chemical_potential( electron_tol: float = 0.5, ) -> float: """ - Calculates the chemical potential at a given electronic DOS, temperature, and volume - such that the number of electrons is equal to that at 0 K (within a specified tolerance). - Note that at the moment this method assumes that the energies are given with respect to the Fermi energy. + 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. Args: - energies (np.ndarray): energy values for the electron DOS. - dos (np.ndarray): electron DOS values. - temperature (float): temperature in K. - chemical_potential_range (np.ndarray, optional): range to search for the chemical potential. - electron_tol (float, optional): tolerance for electron number matching. Defaults to 0.5. + energies (np.ndarray): Energy values for the electron DOS. + dos (np.ndarray): Electron DOS values. + temperature (float): Temperature in K. + chemical_potential_range (np.ndarray, optional): Range to search for the + chemical potential. Defaults to None. + electron_tol (float, optional): Tolerance for electron number matching. + Defaults to 0.5. Raises: - ValueError: If temperature < 0 K. - ValueError: If the chemical potential cannot be found within the specified range. + ValueError: If `temperature < 0 K`. + ValueError: If the chemical potential cannot be found within the specified + range. Returns: - float: chemical potential at a given electronic DOS, temperature, and volume. + float: Chemical potential at the given electronic DOS, temperature, and + volume. """ if temperature < 0: @@ -673,8 +677,9 @@ def calculate_chemical_potential( if self.nelect is not None: if abs(num_electrons_0K - self.nelect) > electron_tol: - warnings.warn( - f"Warning: The number of electrons at 0 K ({num_electrons_0K}) does not match the expected number of electrons ({self.nelect}) within the specified tolerance." + warnings.warn( + f"Warning: The number of electrons at 0 K ({num_electrons_0K}) does not match the expected number of " + f"electrons ({self.nelect}) within the specified tolerance." " Consider increasing NEDOS.", UserWarning, ) @@ -706,7 +711,8 @@ def electron_difference(chemical_potential): ) except ValueError as e: print( - f"Warning: The chemical potential could not be found within the range {chemical_potential_range[0]} to {chemical_potential_range[1]} eV." + f"Warning: The chemical potential could not be found within the range " + f"{chemical_potential_range[0]} to {chemical_potential_range[1]} eV." " Consider increasing the chemical_potential_range." ) chemical_potential = chemical_potential_range[1] From 72cd898e6f35730bead9894307236caf28d923dc Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Fri, 9 Jan 2026 19:59:13 -0500 Subject: [PATCH 19/66] MAINT: update ThermalElectronic docstrings --- .../thermal_electronic/thermal_electronic.py | 40 +++++++++++-------- 1 file changed, 23 insertions(+), 17 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index 0f64264..dd61620 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -449,7 +449,7 @@ def fit( self.entropies_poly_coeffs = np.array(entropies_poly_coeffs) self.heat_capacities_poly_coeffs = np.array(heat_capacities_poly_coeffs) - def plot_total_dos(self): + def plot_total_dos(self)-> go.Figure: """ Plots the total electron DOS for different volumes. @@ -726,16 +726,17 @@ def fit_electron_dos( energy_range: np.ndarray, resolution: float, ) -> tuple[np.ndarray, np.ndarray]: - """Fits the electron DOS with a spline. + """ + Fits the electron DOS with a spline. Args: - energies (np.ndarray): energy values for the electron DOS. - dos (np.ndarray): electron DOS values. - energy_range (np.ndarray): energy range to fit the electron DOS. - resolution (float): energy resolution for the spline. + energies (np.ndarray): Energy values for the electron DOS, in eV. + dos (np.ndarray): Electron DOS values, in states/eV. + energy_range (np.ndarray): Energy range to fit the electron DOS, in eV. + resolution (float): Energy resolution for the spline, in eV. Returns: - tuple[np.ndarray, np.ndarray]: fitted energy and DOS values. + tuple[np.ndarray, np.ndarray]: Fitted energy and DOS values. """ # Filter the energy and dos values within the energy range @@ -758,22 +759,27 @@ def fermi_dirac_distribution( chemical_potential: float, temperature: float, plot: bool = False, - ): - """Calculates the Fermi-Dirac distribution function given by the formula: - f(E, mu, T) = 1 / (1 + exp((E - mu) / (k_B T))) + )-> np.ndarray | tuple[np.ndarray, go.Figure]: + """ + Calculates the Fermi-Dirac distribution function + + .. math:: + + f(E, \mu, T) = \frac{1}{1 + \exp\left(\frac{E - \mu}{k_B T}\right)} Args: - energies (np.ndarray): energy values for the electron DOS. - chemical_potential (float): chemical potential for a given volume and temperature. - temperature (float): temperature in K. - plot (bool, optional): plots the Fermi-Dirac distribution function vs. energy for a - given temperature and chemical potential. Defaults to False. + energies (np.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, optional): If True, plots the Fermi-Dirac distribution function vs. energy + for the given temperature and chemical potential. Defaults to False. Raises: - ValueError: Temperature cannot be less than 0 K. + ValueError: If `temperature < 0 K`. Returns: - np.ndarray or (np.ndarray, go.Figure): Fermi-Dirac distribution function values, and optionally the plotly figure if plot=True. + np.ndarray or (np.ndarray, go.Figure): Fermi-Dirac distribution function values, and + optionally the Plotly figure if `plot=True`. """ chemical_potential = float(chemical_potential) From aff98cf6ffacec8dd24745c184038efc7c417e8a Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Fri, 9 Jan 2026 20:06:44 -0500 Subject: [PATCH 20/66] MAINT: update ThermalElectronic docstrings --- .../thermal_electronic/thermal_electronic.py | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index dd61620..ce40e3e 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -459,9 +459,8 @@ def plot_total_dos(self)-> go.Figure: using `read_total_electron_dos()` or `set_total_electron_dos()`. Returns: - go.Figure: - Plotly figure object containing the total electron DOS curves for - the different volumes. + go.Figure: Plotly figure object containing the total electron DOS curves for + the different volumes. """ # If dos_list is None, raise an error @@ -810,14 +809,16 @@ def plot_fermi_dirac_distribution( chemical_potential: float, temperature: float, ) -> go.Figure: - """Plots the Fermi-Dirac distribution function vs. energy for a given temperature and - chemical potential. + """ + Plots the Fermi-Dirac distribution function versus energy for a given + temperature and chemical potential. Args: - energy (np.ndarray): energy values for the electron DOS. - fermi_dist (np.ndarray): Fermi-Dirac distribution function values. - chemical_potential (float): chemical potential for a given volume and temperature. - temperature (float): temperature in K. + energy (np.ndarray): Energy values for the electron DOS, in eV. + fermi_dist (np.ndarray): Fermi-Dirac distribution function values. + chemical_potential (float): Chemical potential for a given volume and + temperature, in eV. + temperature (float): Temperature in K. """ fig = go.Figure() From aad98e0d5f8dd56ffec1226959f7b4e72156bd43 Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Fri, 9 Jan 2026 20:46:47 -0500 Subject: [PATCH 21/66] MAINT: update ThermalElectronic docstrings --- dfttk/thermal_electronic/thermal_electronic.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index ce40e3e..a67e543 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -459,8 +459,9 @@ def plot_total_dos(self)-> go.Figure: using `read_total_electron_dos()` or `set_total_electron_dos()`. Returns: - go.Figure: Plotly figure object containing the total electron DOS curves for - the different volumes. + go.Figure: + Plotly figure object containing the total electron DOS curves for + the different volumes. """ # If dos_list is None, raise an error @@ -662,8 +663,7 @@ def calculate_chemical_potential( range. Returns: - float: Chemical potential at the given electronic DOS, temperature, and - volume. + float: Chemical potential at the given electronic DOS, temperature, and volume. """ if temperature < 0: From 8580bd0381271f31081577bcdf20a86503b54202 Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Fri, 9 Jan 2026 20:48:56 -0500 Subject: [PATCH 22/66] MAINT: update ThermalElectronic doctrings --- dfttk/thermal_electronic/thermal_electronic.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index a67e543..71f32d9 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -459,8 +459,7 @@ def plot_total_dos(self)-> go.Figure: using `read_total_electron_dos()` or `set_total_electron_dos()`. Returns: - go.Figure: - Plotly figure object containing the total electron DOS curves for + go.Figure: Plotly figure object containing the total electron DOS curves for the different volumes. """ From 8b731a7e8f63791bfec57cc061115b79ccf9915d Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Fri, 9 Jan 2026 20:49:28 -0500 Subject: [PATCH 23/66] MAINT: update ThermalElectronic docstrings --- dfttk/thermal_electronic/thermal_electronic.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index 71f32d9..a67e543 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -459,7 +459,8 @@ def plot_total_dos(self)-> go.Figure: using `read_total_electron_dos()` or `set_total_electron_dos()`. Returns: - go.Figure: Plotly figure object containing the total electron DOS curves for + go.Figure: + Plotly figure object containing the total electron DOS curves for the different volumes. """ From f4a16df99accbab149b03cf06b758428e67eb088 Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Fri, 9 Jan 2026 20:54:32 -0500 Subject: [PATCH 24/66] MAINT: update ThermalElectronic docstrings --- dfttk/thermal_electronic/thermal_electronic.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index a67e543..102a2f6 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -662,8 +662,9 @@ def calculate_chemical_potential( ValueError: If the chemical potential cannot be found within the specified range. - Returns: - float: Chemical potential at the given electronic DOS, temperature, and volume. + Returns: + float: + Chemical potential at the given electronic DOS, temperature, and volume. """ if temperature < 0: From d76a22a01559f5c76763f02866b432be77eafd89 Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Fri, 9 Jan 2026 21:00:03 -0500 Subject: [PATCH 25/66] MAINT: update ThermalElectronic docstrings --- dfttk/thermal_electronic/thermal_electronic.py | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index 102a2f6..a67e543 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -662,9 +662,8 @@ def calculate_chemical_potential( ValueError: If the chemical potential cannot be found within the specified range. - Returns: - float: - Chemical potential at the given electronic DOS, temperature, and volume. + Returns: + float: Chemical potential at the given electronic DOS, temperature, and volume. """ if temperature < 0: From 0c6beaa77237f8bb988e465abde79071c98754f5 Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Fri, 9 Jan 2026 21:12:21 -0500 Subject: [PATCH 26/66] MAINT: update ThermalElectronic docstrings --- .../thermal_electronic/thermal_electronic.py | 24 +++++++------------ 1 file changed, 8 insertions(+), 16 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index a67e543..e251745 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -143,26 +143,18 @@ def read_total_electron_dos( Reads the total electron DOS data from VASP calculations for different volumes. Args: - path (str): - Path to the directory containing the specific folders with + path (str): Path to the directory containing the specific folders with CONTCAR and vasprun.xml files. - folder_prefix (str, optional): - Prefix of the electronic folders. Defaults to ``"elec"``. - contcar_name (str, optional): - Name of the CONTCAR file. Defaults to ``"CONTCAR.elec_dos"``. - vasprun_name (str, optional): - Name of the vasprun.xml file. Defaults to ``"vasprun.xml.elec_dos"``. - selected_volumes (np.ndarray, optional): - List of selected volumes to keep the electron DOS data. Defaults + folder_prefix (str, optional): Prefix of the electronic folders. Defaults to ``"elec"``. + contcar_name (str, optional): Name of the CONTCAR file. Defaults to ``"CONTCAR.elec_dos"``. + vasprun_name (str, optional): Name of the vasprun.xml file. Defaults to ``"vasprun.xml.elec_dos"``. + selected_volumes (np.ndarray, optional): List of selected volumes to keep the electron DOS data. Defaults to None. Raises: - 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. + 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. """ self.path = path From 77a06754a333b26bba05d4936f2faf262a78cb32 Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Fri, 9 Jan 2026 21:16:23 -0500 Subject: [PATCH 27/66] MAINT: update conf.py --- docs/conf.py | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 05ae785..5e88933 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -18,8 +18,6 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration extensions = ['sphinx.ext.linkcode', - 'sphinx.ext.duration', - 'sphinx.ext.coverage', 'sphinx.ext.napoleon', "sphinx.ext.autodoc", "sphinx.ext.autosummary", @@ -29,8 +27,6 @@ 'sphinx_rtd_size' ] autosummary_generate = True - -# Make autodoc list members in the order they appear in the source code autodoc_member_order = 'bysource' # Jupyter Notebook configuration From d72ade336fe720be05f4feb5bb2d27e55e631c55 Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Fri, 9 Jan 2026 21:25:13 -0500 Subject: [PATCH 28/66] MAINT: update conf.py --- docs/conf.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 5e88933..1a123f7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -47,6 +47,9 @@ html_theme = "sphinx_rtd_theme" html_static_path = ['_static'] +html_css_files = [ + 'custom.css', +] sphinx_rtd_size_width = "70%" html_context = { From 9295fe2396ab578d0ffd49f71f2cbab1f3a78e43 Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Fri, 9 Jan 2026 21:30:51 -0500 Subject: [PATCH 29/66] MAINT: update conf.py --- docs/conf.py | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 1a123f7..8bfeff3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -40,16 +40,19 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] # -- Options for napoleon ---------------------------------------------------- -napoleon_use_param = True +napoleon_google_docstring = True +napoleon_numpy_docstring = False +napoleon_use_param = False +napoleon_use_rtype = True +napoleon_include_private_with_doc = False +napoleon_include_special_with_doc = True +napoleon_preprocess_types = True # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output html_theme = "sphinx_rtd_theme" html_static_path = ['_static'] -html_css_files = [ - 'custom.css', -] sphinx_rtd_size_width = "70%" html_context = { From 2be982a9b281ae697f3ddf73a928c95362e3c5b5 Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Fri, 9 Jan 2026 21:34:42 -0500 Subject: [PATCH 30/66] MAINT: update conf.py --- docs/conf.py | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 8bfeff3..42ed99e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -41,12 +41,19 @@ # -- Options for napoleon ---------------------------------------------------- napoleon_google_docstring = True -napoleon_numpy_docstring = False -napoleon_use_param = False -napoleon_use_rtype = True +napoleon_numpy_docstring = True +napoleon_include_init_with_doc = False napoleon_include_private_with_doc = False napoleon_include_special_with_doc = True -napoleon_preprocess_types = True +napoleon_use_admonition_for_examples = False +napoleon_use_admonition_for_notes = False +napoleon_use_admonition_for_references = False +napoleon_use_ivar = False +napoleon_use_param = True +napoleon_use_rtype = True +napoleon_preprocess_types = False +napoleon_type_aliases = None +napoleon_attr_annotations = True # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output From b87cf09556abbf40b25114a59f79b8bd435374af Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Fri, 9 Jan 2026 21:37:22 -0500 Subject: [PATCH 31/66] MAINT: update ThermalElectronic docstrings --- .../thermal_electronic/thermal_electronic.py | 28 +++++++++++-------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index e251745..d55ce03 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -143,18 +143,26 @@ def read_total_electron_dos( Reads the total electron DOS data from VASP calculations for different volumes. Args: - path (str): Path to the directory containing the specific folders with + path (str): + Path to the directory containing the specific folders with CONTCAR and vasprun.xml files. - folder_prefix (str, optional): Prefix of the electronic folders. Defaults to ``"elec"``. - contcar_name (str, optional): Name of the CONTCAR file. Defaults to ``"CONTCAR.elec_dos"``. - vasprun_name (str, optional): Name of the vasprun.xml file. Defaults to ``"vasprun.xml.elec_dos"``. - selected_volumes (np.ndarray, optional): List of selected volumes to keep the electron DOS data. Defaults + folder_prefix (str, optional): + Prefix of the electronic folders. Defaults to ``"elec"``. + contcar_name (str, optional): + Name of the CONTCAR file. Defaults to ``"CONTCAR.elec_dos"``. + vasprun_name (str, optional): + Name of the vasprun.xml file. Defaults to ``"vasprun.xml.elec_dos"``. + selected_volumes (np.ndarray, optional): + List of selected volumes to keep the electron DOS data. Defaults to None. Raises: - 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. + 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. """ self.path = path @@ -754,9 +762,7 @@ def fermi_dirac_distribution( """ Calculates the Fermi-Dirac distribution function - .. math:: - - f(E, \mu, T) = \frac{1}{1 + \exp\left(\frac{E - \mu}{k_B T}\right)} + f(E, mu, T) given by :math:`f(E, \mu, T) = \frac{1}{1 + \exp\left(\frac{E - \mu}{k_B T}\right)}`. Args: energies (np.ndarray): Energy values for the electron DOS, in eV. From cacc0e37ef492d53c360e8cb01c82442340eae05 Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Fri, 9 Jan 2026 21:43:24 -0500 Subject: [PATCH 32/66] MAINT: update ThermalElectronic docstrings --- dfttk/thermal_electronic/thermal_electronic.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index d55ce03..ca661f2 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -817,6 +817,10 @@ def plot_fermi_dirac_distribution( chemical_potential (float): Chemical potential for a given volume and temperature, in eV. temperature (float): Temperature in K. + + Returns: + go.Figure: Plotly figure object containing the Fermi-Dirac distribution + function curve. """ fig = go.Figure() From 21db71efccf681d9a88903510b308d2cef9cd7e0 Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Fri, 9 Jan 2026 21:46:17 -0500 Subject: [PATCH 33/66] MAINT: update ThermalElectronic docstrings --- dfttk/thermal_electronic/thermal_electronic.py | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index ca661f2..eda6eb9 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -760,9 +760,8 @@ def fermi_dirac_distribution( plot: bool = False, )-> np.ndarray | tuple[np.ndarray, go.Figure]: """ - Calculates the Fermi-Dirac distribution function - - f(E, mu, T) given by :math:`f(E, \mu, T) = \frac{1}{1 + \exp\left(\frac{E - \mu}{k_B T}\right)}`. + Calculates the Fermi-Dirac distribution function f(E, mu, T) + given by :math:`f(E, \mu, T) = \frac{1}{1 + \exp\left(\frac{E - \mu}{k_B T}\right)}`. Args: energies (np.ndarray): Energy values for the electron DOS, in eV. From 603dd58435625c7b77f9eeb33531df5a15a0e019 Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Fri, 9 Jan 2026 21:54:50 -0500 Subject: [PATCH 34/66] MAINT: update ThermalElectronic docstrings --- dfttk/thermal_electronic/thermal_electronic.py | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index eda6eb9..3a96721 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -760,22 +760,27 @@ def fermi_dirac_distribution( plot: bool = False, )-> np.ndarray | tuple[np.ndarray, go.Figure]: """ - Calculates the Fermi-Dirac distribution function f(E, mu, T) - given by :math:`f(E, \mu, T) = \frac{1}{1 + \exp\left(\frac{E - \mu}{k_B T}\right)}`. + Calculates the Fermi-Dirac distribution function. + + The function is given by: + + .. math:: + + f(E, \\mu, T) = \\frac{1}{1 + \\exp\\left(\\frac{E - \\mu}{k_B T}\\right)} Args: energies (np.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, optional): If True, plots the Fermi-Dirac distribution function vs. energy - for the given temperature and chemical potential. Defaults to False. + plot (bool, optional): 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`. Returns: - np.ndarray or (np.ndarray, go.Figure): Fermi-Dirac distribution function values, and - optionally the Plotly figure if `plot=True`. + np.ndarray or (np.ndarray, go.Figure): Fermi-Dirac distribution function values, + and optionally the Plotly figure if `plot=True`. """ chemical_potential = float(chemical_potential) From c000accc2de6d95b549efa84a43a2dd0ea4f38f3 Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Fri, 9 Jan 2026 22:09:40 -0500 Subject: [PATCH 35/66] MAINT: update ThermalElectronic docstrings --- .../thermal_electronic/thermal_electronic.py | 179 ++++++++++-------- 1 file changed, 103 insertions(+), 76 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index 3a96721..e1aff06 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -449,7 +449,7 @@ def fit( self.entropies_poly_coeffs = np.array(entropies_poly_coeffs) self.heat_capacities_poly_coeffs = np.array(heat_capacities_poly_coeffs) - def plot_total_dos(self)-> go.Figure: + def plot_total_dos(self) -> go.Figure: """ Plots the total electron DOS for different volumes. @@ -496,7 +496,7 @@ def plot_vt(self, type: str, selected_temperatures: np.ndarray = None) -> go.Fig Args: type (str): - Must be one of the following values: + 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'``. @@ -676,7 +676,7 @@ def calculate_chemical_potential( if self.nelect is not None: if abs(num_electrons_0K - self.nelect) > electron_tol: - warnings.warn( + warnings.warn( f"Warning: The number of electrons at 0 K ({num_electrons_0K}) does not match the expected number of " f"electrons ({self.nelect}) within the specified tolerance." " Consider increasing NEDOS.", @@ -758,7 +758,7 @@ def fermi_dirac_distribution( chemical_potential: float, temperature: float, plot: bool = False, - )-> np.ndarray | tuple[np.ndarray, go.Figure]: + ) -> np.ndarray | tuple[np.ndarray, go.Figure]: """ Calculates the Fermi-Dirac distribution function. @@ -779,8 +779,8 @@ def fermi_dirac_distribution( ValueError: If `temperature < 0 K`. Returns: - np.ndarray or (np.ndarray, go.Figure): Fermi-Dirac distribution function values, - and optionally the Plotly figure if `plot=True`. + np.ndarray or (np.ndarray, go.Figure): + Fermi-Dirac distribution function values, and optionally the Plotly figure if `plot=True`. """ chemical_potential = float(chemical_potential) @@ -821,10 +821,10 @@ def plot_fermi_dirac_distribution( chemical_potential (float): Chemical potential for a given volume and temperature, in eV. temperature (float): Temperature in K. - + Returns: - go.Figure: Plotly figure object containing the Fermi-Dirac distribution - function curve. + go.Figure: + Plotly figure object containing the Fermi-Dirac distribution function curve. """ fig = go.Figure() @@ -847,20 +847,25 @@ def calculate_num_electrons( chemical_potential: float, temperature: float, ) -> float: - """Calculates the number of electrons for a given electronic DOS, chemical potential, and temperature using the formula: - N = ∫ DOS(E) * f(E, mu, T) dE + """ + Calculates the number of electrons for a given electronic DOS, chemical potential, + and temperature. + + .. math:: + + N = \\int \\mathrm{DOS}(E) \\, f(E, \\mu, T) \\, dE Args: - energies (np.ndarray): energy values for the electron DOS. - dos (np.ndarray): electron DOS values. - chemical_potential (float): chemical potential for a given volume and temperature. - temperature (float): temperature in K. + energies (np.ndarray): Energy values for the electron DOS, in eV. + dos (np.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: Temperature cannot be less than 0 K. + ValueError: If `temperature < 0 K`. Returns: - float: number of electrons. + float: Number of electrons. """ chemical_potential = float(chemical_potential) @@ -886,24 +891,30 @@ def calculate_internal_energies( plot: bool = False, plot_temperature: float = None, ) -> np.ndarray: - """Calculates the thermal electronic contribution to the internal energy for a given volume using the formula: - U_el(T, V) = ∫ DOS(E) * f(E, mu, T) * E dE - ∫_(E go.Figure: - """Plots the integrands vs energy of the internal energy equation. + """ + Plots the integrands versus energy of the internal energy equation. Args: - energies (np.ndarray): energy values for the electron DOS. - integrand_1 (np.ndarray): integrand 1 from the internal energy equation. - filtered_energies (np.ndarray): filtered energy values for the electron DOS (where E < mu). - integrand_2 (np.ndarray): integrand 2 from the internal energy equation. - plot_temperature (float): temperature in K. + energies (np.ndarray): Energy values for the electron DOS, in eV. + integrand_1 (np.ndarray): First integrand from the internal energy equation. + filtered_energies (np.ndarray): Filtered energy values where E < mu, in eV. + integrand_2 (np.ndarray): Second integrand from the internal energy equation. + plot_temperature (float): Temperature at which the integrand is plotted, in K. Returns: - go.Figure: Plotly figure object. + go.Figure: Plotly figure object containing the integrand curves. """ plot_temperature = float(plot_temperature) @@ -1054,25 +1066,30 @@ def calculate_entropies( plot: bool = False, plot_temperature: float = None, ) -> np.ndarray: - """Calculates the thermal electronic contribution to the entropy for a given volume using the formula: - S_el(T, V) = -k_B ∫ DOS(E) * [f(E, mu, T) * ln(f(E, mu, T)) + (1 - f(E, mu, T)) * ln(1 - f(E, mu, T))] dE + """ + Calculates the thermal electronic contribution to the entropy for a given volume using the formula: + + .. math:: + + S_\mathrm{el}(T, V) = -k_B \int \mathrm{DOS}(E) \left[ f(E, \mu, T) \ln f(E, \mu, T) + + (1 - f(E, \mu, T)) \ln (1 - f(E, \mu, T)) \right] \, dE Args: - energies (np.ndarray): energy values for the electron DOS. - dos (np.ndarray): electron DOS values. - temperatures (np.ndarray): temperatures in K. - energies_fit_range (np.ndarray, optional): energy range to fit the electron DOS. Defaults to np.array([-2, 2]). - resolution (float, optional): energy resolution for the spline. Defaults to 0.0001. - plot (bool, optional): plots the integrand vs energy of the entropy equation. Defaults to False. - plot_temperature (float, optional): temperature to plot the integrand vs energy of the entropy equation. Defaults to None. + energies (np.ndarray): Energy values for the electron DOS, in eV. + dos (np.ndarray): Electron DOS values, in states/eV. + temperatures (np.ndarray): Temperatures in K. + energies_fit_range (np.ndarray, optional): Energy range to fit the electron DOS, in eV. Defaults to np.array([-2, 2]). + resolution (float, optional): Energy resolution for the spline, in eV. Defaults to 0.0001. + plot (bool, optional): If True, plots the integrand vs. energy of the entropy equation. Defaults to False. + plot_temperature (float, optional): 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. + 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`. Returns: - np.ndarray: entropy values. + np.ndarray: Entropy values as a function of temperature, in eV/K. """ # If there are negative temperatures, raise an error @@ -1163,15 +1180,16 @@ def calculate_entropies( def plot_entropy_integral( energies: np.ndarray, integrand: np.ndarray, plot_temperature: float ) -> go.Figure: - """Plots the integrand vs energy of the entropy equation. + """ + Plots the integrand vs. energy of the entropy equation. Args: - energies (np.ndarray): energy values for the electron DOS. - integrand (np.ndarray): integrand from the entropy equation. - plot_temperature (float): temperature in K. + energies (np.ndarray): Energy values for the electron DOS, in eV. + integrand (np.ndarray): Integrand from the entropy equation. + plot_temperature (float): Temperature in K. Returns: - go.Figure: Plotly figure object. + go.Figure: Plotly figure object showing the integrand as a function of energy. """ plot_temperature = float(plot_temperature) @@ -1203,26 +1221,32 @@ def calculate_heat_capacities( plot=False, plot_temperature: float = None, ) -> np.array: - """Calculates the thermal electronic contribution to the heat capacity for a given volume using the formula: - Cv_el(T, V) = ∫ DOS(E) * f(E, mu, T) * (1 - f(E, mu, T)) * (E - mu)**2 / (k_B T**2) dE + """ + Calculates the thermal electronic contribution to the heat capacity for a given volume using the formula: + + .. math:: + + C_{V,el}(T, V) = \int \mathrm{DOS}(E) \, f(E, \mu, T) \, + \left[ 1 - f(E, \mu, T) \right] \frac{(E - \mu)^2}{k_B T^2} \, dE Args: - energies (np.ndarray): energy values for the electron DOS. - dos (np.ndarray): electron DOS values. - temperatures (np.ndarray): temperatures in K. - energies_fit_range (np.ndarray, optional): energy range to fit the electron DOS. Defaults to np.array([-2, 2]). - resolution (float, optional): energy resolution for the spline. Defaults to 0.0001. - plot (bool, optional): plots the integrand vs energy of the heat capacity equation. Defaults to False. - plot_temperature (float, optional): temperature to plot the integrand vs energy of the heat capacity equation. Defaults to None. + energies (np.ndarray): Energy values for the electron DOS, in eV. + dos (np.ndarray): Electron DOS values, in states/eV. + temperatures (np.ndarray): Temperatures in K. + energies_fit_range (np.ndarray, optional): Energy range to fit the electron DOS. Defaults to np.array([-2, 2]) eV. + resolution (float, optional): Energy resolution for the spline. Defaults to 0.0001 eV. + plot (bool, optional): If True, plots the integrand vs. energy of the heat capacity equation. Defaults to False. + plot_temperature (float, optional): 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. + 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`. Returns: - np.array: heat capacity values. + np.ndarray: Heat capacity values in eV/K. """ + # If there are negative temperatures, raise an error if np.any(temperatures < 0): raise ValueError("Temperatures cannot be less than 0 K") @@ -1307,15 +1331,16 @@ def calculate_heat_capacities( def plot_heat_capacity_integral( energies: np.ndarray, integrand: np.ndarray, plot_temperature: float ) -> go.Figure: - """Plots the integrand vs energy of the heat capacity equation. + """ + Plots the integrand vs. energy of the heat capacity equation. Args: - energies (np.ndarray): energy values for the electron DOS. - integrand (np.ndarray): integrand from the heat capacity equation. - plot_temperature (float): temperature in K. + energies (np.ndarray): Energy values for the electron DOS, in eV. + integrand (np.ndarray): Integrand from the heat capacity equation. + plot_temperature (float): Temperature in K. Returns: - go.Figure: Plotly figure object. + go.Figure: Plotly figure object containing the integrand vs. energy curve for the specified temperature. """ plot_temperature = float(plot_temperature) @@ -1341,16 +1366,18 @@ def calculate_helmholtz_energies( entropies: np.ndarray, temperatures: np.ndarray, ) -> np.ndarray: - """Calculates the thermal electronic contribution to the Helmholtz free energy for a given volume using the formula: - F_el(T, V) = U_el(T, V) - T * S_el(T, V) + """ + Calculates the thermal electronic contribution to the Helmholtz free energy for a given volume using the formula + + :math:`F_\mathrm{el}(T, V) = U_\mathrm{el}(T, V) - T \, S_\mathrm{el}(T, V)` Args: - internal_energies (np.ndarray): internal energy values. - entropies (np.ndarray): entropy values. - temperatures (np.ndarray): temperatures in K. + internal_energies (np.ndarray): Internal energy values, in eV. + entropies (np.ndarray): Entropy values, in eV/K. + temperatures (np.ndarray): Temperatures in K. Returns: - np.ndarray: Helmholtz free energy values. + np.ndarray: Helmholtz free energy values, in eV. """ helmholtz_energies = internal_energies - temperatures * entropies From d2d441ff2a71d73fc662a7464100d7e6e580d358 Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Fri, 9 Jan 2026 22:17:04 -0500 Subject: [PATCH 36/66] MAINT: update ThermalElectronic docstrings --- dfttk/thermal_electronic/thermal_electronic.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index e1aff06..eeeb031 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -1369,7 +1369,9 @@ def calculate_helmholtz_energies( """ Calculates the thermal electronic contribution to the Helmholtz free energy for a given volume using the formula - :math:`F_\mathrm{el}(T, V) = U_\mathrm{el}(T, V) - T \, S_\mathrm{el}(T, V)` + .. math:: + + F_\mathrm{el}(T, V) = U_\mathrm{el}(T, V) - T \, S_\mathrm{el}(T, V) Args: internal_energies (np.ndarray): Internal energy values, in eV. From 1e6f0fc347d4b50735bca361d8f15de4d2753b8f Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Fri, 9 Jan 2026 22:20:38 -0500 Subject: [PATCH 37/66] MAINT: update ThermalElectronic docstrings --- dfttk/thermal_electronic/thermal_electronic.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index eeeb031..1af1799 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -896,8 +896,9 @@ def calculate_internal_energies( .. math:: - U_{el}(T, V) = \\int \\mathrm{DOS}(E) \\, f(E, \\mu, T) \\, E \\, dE - - \\int_{E<\\mu} \\mathrm{DOS}(E) \\, E \\, dE + U_\mathrm{el}(T, V) = + \int \mathrm{DOS}(E) \, f(E, \mu, T) \, E \, dE + - \int_{0}^{\mu} \mathrm{DOS}(E) \, E \, dE Args: energies (np.ndarray): Energy values from the electron DOS, in eV. From 3953552900508ed1aa0475b96d89be02b462babf Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Fri, 9 Jan 2026 22:32:03 -0500 Subject: [PATCH 38/66] MAINT: update ThermalElectronic docstrings --- dfttk/thermal_electronic/thermal_electronic.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index 1af1799..106890c 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -898,7 +898,7 @@ def calculate_internal_energies( U_\mathrm{el}(T, V) = \int \mathrm{DOS}(E) \, f(E, \mu, T) \, E \, dE - - \int_{0}^{\mu} \mathrm{DOS}(E) \, E \, dE + - \int^{\mu} \mathrm{DOS}(E) \, E \, dE Args: energies (np.ndarray): Energy values from the electron DOS, in eV. From 500d8dd6d1396eb0d2ae550ac4523582fad54836 Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Fri, 9 Jan 2026 23:02:01 -0500 Subject: [PATCH 39/66] MAINT: update ThermalElectronic docstrings --- dfttk/thermal_electronic/thermal_electronic.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index 106890c..d5d6efc 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -853,7 +853,7 @@ def calculate_num_electrons( .. math:: - N = \\int \\mathrm{DOS}(E) \\, f(E, \\mu, T) \\, dE + N = \int_{-\infty}^{\infty} \mathrm{DOS}(E) \, f(E, \mu, T) \, dE Args: energies (np.ndarray): Energy values for the electron DOS, in eV. @@ -897,8 +897,8 @@ def calculate_internal_energies( .. math:: U_\mathrm{el}(T, V) = - \int \mathrm{DOS}(E) \, f(E, \mu, T) \, E \, dE - - \int^{\mu} \mathrm{DOS}(E) \, E \, dE + \int_{-\infty}^{\infty} \mathrm{DOS}(E) \, f(E, \mu, T) \, E \, dE + - \int_{-\infty}^{E_F} \mathrm{DOS}(E) \, E \, dE Args: energies (np.ndarray): Energy values from the electron DOS, in eV. @@ -953,8 +953,8 @@ def calculate_internal_energies( integrand_1_list.append(integrand_1) integral_1 = np.trapz(integrand_1, energies_fit) - # Evaluate the second integral from -infinity to the chemical potential - mask = energies_fit < chemical_potential + # Evaluate the second integral from -infinity to the Fermi energy (shifted to 0 eV) + mask = energies_fit < 0 filtered_energies = energies_fit[mask] filtered_energies_list.append(filtered_energies) filtered_dos = dos_fit[mask] From 57cdd25eb90a9302c0f0b5bea1dd1416e5e41286 Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Fri, 9 Jan 2026 23:04:13 -0500 Subject: [PATCH 40/66] MAINT: update ThermalElectronic docstrings --- dfttk/thermal_electronic/thermal_electronic.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index d5d6efc..3780a91 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -1072,8 +1072,9 @@ def calculate_entropies( .. math:: - S_\mathrm{el}(T, V) = -k_B \int \mathrm{DOS}(E) \left[ f(E, \mu, T) \ln f(E, \mu, T) + - (1 - f(E, \mu, T)) \ln (1 - f(E, \mu, T)) \right] \, dE + S_\mathrm{el}(T, V) = - k_B \int_{-\infty}^{\infty} \mathrm{DOS}(E) \left[ + f(E, \mu, T) \ln f(E, \mu, T) + (1 - f(E, \mu, T)) \ln (1 - f(E, \mu, T)) + \right] \, dE Args: energies (np.ndarray): Energy values for the electron DOS, in eV. @@ -1227,7 +1228,7 @@ def calculate_heat_capacities( .. math:: - C_{V,el}(T, V) = \int \mathrm{DOS}(E) \, f(E, \mu, T) \, + C_{V,el}(T, V) = \int_{-\infty}^{\infty} \mathrm{DOS}(E) \, f(E, \mu, T) \, \left[ 1 - f(E, \mu, T) \right] \frac{(E - \mu)^2}{k_B T^2} \, dE Args: From 73ad9fb8de5ee36b30a8373e650d90eca3af92cc Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Fri, 9 Jan 2026 23:11:03 -0500 Subject: [PATCH 41/66] MAINT: update ThermalElectronic docstrings --- dfttk/thermal_electronic/thermal_electronic.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index 3780a91..9a13c0b 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -1072,9 +1072,9 @@ def calculate_entropies( .. math:: - S_\mathrm{el}(T, V) = - k_B \int_{-\infty}^{\infty} \mathrm{DOS}(E) \left[ - f(E, \mu, T) \ln f(E, \mu, T) + (1 - f(E, \mu, T)) \ln (1 - f(E, \mu, T)) - \right] \, dE + S_\mathrm{el}(T, V) = - k_B \int_{-\infty}^{\infty} \mathrm{DOS}(E) \, + \bigl[ f(E, \mu, T) \ln f(E, \mu, T) + + (1 - f(E, \mu, T)) \ln (1 - f(E, \mu, T)) \bigr] \, dE Args: energies (np.ndarray): Energy values for the electron DOS, in eV. @@ -1229,7 +1229,7 @@ def calculate_heat_capacities( .. math:: C_{V,el}(T, V) = \int_{-\infty}^{\infty} \mathrm{DOS}(E) \, f(E, \mu, T) \, - \left[ 1 - f(E, \mu, T) \right] \frac{(E - \mu)^2}{k_B T^2} \, dE + \bigl[ 1 - f(E, \mu, T) \bigr] \frac{(E - \mu)^2}{k_B T^2} Args: energies (np.ndarray): Energy values for the electron DOS, in eV. From 46f45770f4ebe8c989e81dc5411ab9e0914bc261 Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Fri, 9 Jan 2026 23:17:37 -0500 Subject: [PATCH 42/66] FIX: fix tests for ThemalElectronic --- tests/test_thermal_electronic.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/tests/test_thermal_electronic.py b/tests/test_thermal_electronic.py index 8fd67fd..545330f 100644 --- a/tests/test_thermal_electronic.py +++ b/tests/test_thermal_electronic.py @@ -103,7 +103,8 @@ def test_process(cached_dos_data): thermal_electronic = ThermalElectronic() # Process without setting the DOS (should raise an error) - with pytest.raises(ValueError, match=re.escape("DOS data not found. Please read or set the total electron DOS first using read_total_electron_dos() or set_total_electron_dos().")): + with pytest.raises(ValueError, match=re.escape("DOS data not found. Please read or set the total electron DOS first " + "using read_total_electron_dos() or set_total_electron_dos().")): thermal_electronic.process(temperatures=temperatures) # Now set the DOS and process From 719c098b7f547c30f54e658aa3181b73dbb3a037 Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Fri, 9 Jan 2026 23:21:05 -0500 Subject: [PATCH 43/66] MAINT: update ThermalElectronic docstrings --- dfttk/thermal_electronic/thermal_electronic.py | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index 9a13c0b..f7a6bea 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -331,7 +331,7 @@ def process( if self.dos_list is None: raise ValueError( "DOS data not found. Please read or set the total electron DOS first " - "using `read_total_electron_dos()` or `set_total_electron_dos()`." + "using read_total_electron_dos() or set_total_electron_dos()." ) # Initialize lists to store data @@ -1228,8 +1228,7 @@ def calculate_heat_capacities( .. math:: - C_{V,el}(T, V) = \int_{-\infty}^{\infty} \mathrm{DOS}(E) \, f(E, \mu, T) \, - \bigl[ 1 - f(E, \mu, T) \bigr] \frac{(E - \mu)^2}{k_B T^2} + C_{V,\mathrm{el}}(T, V) = \int_{-\infty}^{\infty} \mathrm{DOS}(E) \, f(E, \mu, T) \, \bigl[ 1 - f(E, \mu, T) \bigr] \frac{(E - \mu)^2}{k_B T^2} \, dE Args: energies (np.ndarray): Energy values for the electron DOS, in eV. From 97340bcb0df0f937d938594bdb470c023609d193 Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Fri, 9 Jan 2026 23:32:23 -0500 Subject: [PATCH 44/66] MAINT: update ThermalElectronic docstrings --- dfttk/thermal_electronic/thermal_electronic.py | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index f7a6bea..efa2ae7 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -1072,9 +1072,9 @@ def calculate_entropies( .. math:: - S_\mathrm{el}(T, V) = - k_B \int_{-\infty}^{\infty} \mathrm{DOS}(E) \, - \bigl[ f(E, \mu, T) \ln f(E, \mu, T) - + (1 - f(E, \mu, T)) \ln (1 - f(E, \mu, T)) \bigr] \, dE + S_\mathrm{el}(T, V) = - k_B \int_{-\infty}^{\infty} \mathrm{DOS}(E) \, + \bigl[ f(E, \mu, T) \ln f(E, \mu, T) + + (1 - f(E, \mu, T)) \ln (1 - f(E, \mu, T)) \bigr] \, dE Args: energies (np.ndarray): Energy values for the electron DOS, in eV. @@ -1222,13 +1222,15 @@ def calculate_heat_capacities( resolution: float = 0.0001, plot=False, plot_temperature: float = None, - ) -> np.array: + ) -> np.ndarray: + """ Calculates the thermal electronic contribution to the heat capacity for a given volume using the formula: .. math:: - C_{V,\mathrm{el}}(T, V) = \int_{-\infty}^{\infty} \mathrm{DOS}(E) \, f(E, \mu, T) \, \bigl[ 1 - f(E, \mu, T) \bigr] \frac{(E - \mu)^2}{k_B T^2} \, dE + C_{V,\mathrm{el}}(T, V) = \int_{-\infty}^{\infty} \mathrm{DOS}(E) \, f(E, \mu, T) \, + \bigl[ 1 - f(E, \mu, T) \bigr] \frac{(E - \mu)^2}{k_B T^2} \, dE Args: energies (np.ndarray): Energy values for the electron DOS, in eV. From 3222d56ec7c203f67387c3451856f319e11cac5d Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Fri, 9 Jan 2026 23:42:19 -0500 Subject: [PATCH 45/66] MAINT: update ThermalElectronic docstrings --- dfttk/thermal_electronic/thermal_electronic.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index efa2ae7..afb8cd5 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -1067,14 +1067,14 @@ def calculate_entropies( plot: bool = False, plot_temperature: float = None, ) -> np.ndarray: + """ Calculates the thermal electronic contribution to the entropy for a given volume using the formula: .. math:: - S_\mathrm{el}(T, V) = - k_B \int_{-\infty}^{\infty} \mathrm{DOS}(E) \, - \bigl[ f(E, \mu, T) \ln f(E, \mu, T) - + (1 - f(E, \mu, T)) \ln (1 - f(E, \mu, T)) \bigr] \, dE + S_\mathrm{el}(T, V) = - k_B \int_{-\infty}^{\infty} \mathrm{DOS}(E) + \left[ f \ln f + (1 - f) \ln (1 - f) \right] dE Args: energies (np.ndarray): Energy values for the electron DOS, in eV. From a270e0ff694a33f07049ea67f42280e5dcd124e7 Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Fri, 9 Jan 2026 23:45:29 -0500 Subject: [PATCH 46/66] MAINT: update ThermalElectronic docstrings --- dfttk/thermal_electronic/thermal_electronic.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index afb8cd5..1f2b49a 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -1229,8 +1229,8 @@ def calculate_heat_capacities( .. math:: - C_{V,\mathrm{el}}(T, V) = \int_{-\infty}^{\infty} \mathrm{DOS}(E) \, f(E, \mu, T) \, - \bigl[ 1 - f(E, \mu, T) \bigr] \frac{(E - \mu)^2}{k_B T^2} \, dE + C_{V,\mathrm{el}}(T, V) = \int_{-\infty}^{\infty} \mathrm{DOS}(E) \, f \, + \bigl[ 1 - f \bigr] \frac{(E - \mu)^2}{k_B T^2} \, dE Args: energies (np.ndarray): Energy values for the electron DOS, in eV. From c5bf3c33a600764c0ce5822d9352ba95568b2ccb Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Fri, 9 Jan 2026 23:50:59 -0500 Subject: [PATCH 47/66] MAINT: update ThermalElectronic docstrings --- dfttk/thermal_electronic/thermal_electronic.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index 1f2b49a..e152358 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -1073,8 +1073,8 @@ def calculate_entropies( .. math:: - S_\mathrm{el}(T, V) = - k_B \int_{-\infty}^{\infty} \mathrm{DOS}(E) - \left[ f \ln f + (1 - f) \ln (1 - f) \right] dE + S_\\mathrm{el}(T, V) = - k_B \\int_{-\\infty}^{\\infty} \\mathrm{DOS}(E) + \\left[ f \\ln f + (1 - f) \\ln (1 - f) \\right] dE Args: energies (np.ndarray): Energy values for the electron DOS, in eV. From a15b1a577aef509121731e39f433039359c89032 Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Fri, 9 Jan 2026 23:55:27 -0500 Subject: [PATCH 48/66] MAINT: update ThermalElectronic docs --- dfttk/thermal_electronic/thermal_electronic.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index e152358..2643ab8 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -1073,8 +1073,8 @@ def calculate_entropies( .. math:: - S_\\mathrm{el}(T, V) = - k_B \\int_{-\\infty}^{\\infty} \\mathrm{DOS}(E) - \\left[ f \\ln f + (1 - f) \\ln (1 - f) \\right] dE + S_\mathrm{el}(T, V) = - k_B \int_{-\infty}^{\infty} \mathrm{DOS}(E) + [f \ln f + (1 - f) \ln (1 - f)] dE Args: energies (np.ndarray): Energy values for the electron DOS, in eV. From f0dd0089f0207b25d358a75889eb013eea4432d5 Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Sat, 10 Jan 2026 00:02:23 -0500 Subject: [PATCH 49/66] test --- dfttk/thermal_electronic/thermal_electronic.py | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index 2643ab8..4b5715e 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -1067,14 +1067,13 @@ def calculate_entropies( plot: bool = False, plot_temperature: float = None, ) -> np.ndarray: - + #S_\mathrm{el}(T, V) = - k_B \int_{-\infty}^{\infty} \mathrm{DOS}(E) [f \ln f + (1 - f) \ln (1 - f)] dE """ Calculates the thermal electronic contribution to the entropy for a given volume using the formula: .. math:: - S_\mathrm{el}(T, V) = - k_B \int_{-\infty}^{\infty} \mathrm{DOS}(E) - [f \ln f + (1 - f) \ln (1 - f)] dE + S_\mathrm{el}(T, V) Args: energies (np.ndarray): Energy values for the electron DOS, in eV. From a31aa20861b626d3d7940850d22dfbf4ac81ea00 Mon Sep 17 00:00:00 2001 From: "Nigel L. E. Hew" <77617652+nhew1994@users.noreply.github.com> Date: Sat, 10 Jan 2026 07:55:35 -0500 Subject: [PATCH 50/66] Fix formula formatting in thermal electronic entropy docstring Corrected the formatting of the entropy formula in the docstring. --- dfttk/thermal_electronic/thermal_electronic.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index 4b5715e..76490c7 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -1073,7 +1073,7 @@ def calculate_entropies( .. math:: - S_\mathrm{el}(T, V) + S_\mathrm{el}(T, V) = - k_B \int_{-\infty}^{\infty} \mathrm{DOS}(E)\, dE Args: energies (np.ndarray): Energy values for the electron DOS, in eV. From 7cb8a2bd422dc8c33122609e66d83dd9d6b654e8 Mon Sep 17 00:00:00 2001 From: "Nigel L. E. Hew" <77617652+nhew1994@users.noreply.github.com> Date: Sat, 10 Jan 2026 08:11:40 -0500 Subject: [PATCH 51/66] Fix LaTeX syntax in thermal electronic calculations Updated formulas for clarity and fixed LaTeX syntax in comments and docstrings. --- dfttk/thermal_electronic/thermal_electronic.py | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index 76490c7..912e463 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -1067,13 +1067,14 @@ def calculate_entropies( plot: bool = False, plot_temperature: float = None, ) -> np.ndarray: - #S_\mathrm{el}(T, V) = - k_B \int_{-\infty}^{\infty} \mathrm{DOS}(E) [f \ln f + (1 - f) \ln (1 - f)] dE + #TODO: fix the formula for readthedocs: + #S_\mathrm{el}(T, V) = - k_B \int_{-\infty}^{\infty} \mathrm{DOS}(E) \left[ f \ln f + (1 - f) \ln (1 - f) \right] \, dE """ - Calculates the thermal electronic contribution to the entropy for a given volume using the formula: + Calculates the thermal electronic contribution to the entropy for a given volume using the formula .. math:: - S_\mathrm{el}(T, V) = - k_B \int_{-\infty}^{\infty} \mathrm{DOS}(E)\, dE + S_\mathrm{el}(T, V) = - k_B \int_{-\infty}^{\infty} \mathrm{DOS}(E)\, dE. Args: energies (np.ndarray): Energy values for the electron DOS, in eV. @@ -1222,14 +1223,14 @@ def calculate_heat_capacities( plot=False, plot_temperature: float = None, ) -> np.ndarray: - + #TODO: fix the formula for readthedocs: """ - Calculates the thermal electronic contribution to the heat capacity for a given volume using the formula: + Calculates the thermal electronic contribution to the heat capacity for a given volume using the formula .. math:: C_{V,\mathrm{el}}(T, V) = \int_{-\infty}^{\infty} \mathrm{DOS}(E) \, f \, - \bigl[ 1 - f \bigr] \frac{(E - \mu)^2}{k_B T^2} \, dE + \bigl[ 1 - f \bigr] \frac{(E - \mu)^2}{k_B T^2} \, dE. Args: energies (np.ndarray): Energy values for the electron DOS, in eV. @@ -1373,7 +1374,7 @@ def calculate_helmholtz_energies( .. math:: - F_\mathrm{el}(T, V) = U_\mathrm{el}(T, V) - T \, S_\mathrm{el}(T, V) + F_\mathrm{el}(T, V) = U_\mathrm{el}(T, V) - T \, S_\mathrm{el}(T, V). Args: internal_energies (np.ndarray): Internal energy values, in eV. From eeaac56e8c566f851049fc483dc2a8485e8f9550 Mon Sep 17 00:00:00 2001 From: "Nigel L. E. Hew" <77617652+nhew1994@users.noreply.github.com> Date: Sat, 10 Jan 2026 08:20:46 -0500 Subject: [PATCH 52/66] Revise entropy formula in thermal_electronic.py Updated the formula for thermal electronic entropy calculation to include the Fermi-Dirac distribution. --- dfttk/thermal_electronic/thermal_electronic.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index 912e463..c49efed 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -1074,7 +1074,7 @@ def calculate_entropies( .. math:: - S_\mathrm{el}(T, V) = - k_B \int_{-\infty}^{\infty} \mathrm{DOS}(E)\, dE. + S_\mathrm{el}(T, V) = - k_B \int_{-\infty}^{\infty} \mathrm{DOS}(E) \left[ f \ln f + (1 - f) \ln (1 - f) \right]\, dE. Args: energies (np.ndarray): Energy values for the electron DOS, in eV. From f5f354641e8cb7601b005ec4e755c24ceaf5e7b5 Mon Sep 17 00:00:00 2001 From: "Nigel L. E. Hew" <77617652+nhew1994@users.noreply.github.com> Date: Sat, 10 Jan 2026 08:24:11 -0500 Subject: [PATCH 53/66] Fix formatting of heat capacity formula in docstring --- dfttk/thermal_electronic/thermal_electronic.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index c49efed..c4863d2 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -1229,8 +1229,7 @@ def calculate_heat_capacities( .. math:: - C_{V,\mathrm{el}}(T, V) = \int_{-\infty}^{\infty} \mathrm{DOS}(E) \, f \, - \bigl[ 1 - f \bigr] \frac{(E - \mu)^2}{k_B T^2} \, dE. + C_{v,\mathrm{el}}(T, V) = \int_{-\infty}^{\infty} \mathrm{DOS}(E) \, f \, \left(1 - f \right) \frac{(E - \mu)^2}{k_B T^2} \, dE. Args: energies (np.ndarray): Energy values for the electron DOS, in eV. From ce2f73942f3fd4d3892ed6be5b0b8e601cbc62fc Mon Sep 17 00:00:00 2001 From: "Nigel L. E. Hew" <77617652+nhew1994@users.noreply.github.com> Date: Sat, 10 Jan 2026 08:40:21 -0500 Subject: [PATCH 54/66] Refactor docstrings --- dfttk/thermal_electronic/thermal_electronic.py | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index c4863d2..0fd71ee 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -1073,8 +1073,12 @@ def calculate_entropies( Calculates the thermal electronic contribution to the entropy for a given volume using the formula .. math:: - - S_\mathrm{el}(T, V) = - k_B \int_{-\infty}^{\infty} \mathrm{DOS}(E) \left[ f \ln f + (1 - f) \ln (1 - f) \right]\, dE. + + S_\mathrm{el}(T, V) = + - k_B \int_{-\infty}^{\infty} \mathrm{DOS}(E) + \left[ + f \ln f + (1 - f) \ln (1 - f) + \right]\, dE. Args: energies (np.ndarray): Energy values for the electron DOS, in eV. @@ -1228,8 +1232,11 @@ def calculate_heat_capacities( Calculates the thermal electronic contribution to the heat capacity for a given volume using the formula .. math:: - - C_{v,\mathrm{el}}(T, V) = \int_{-\infty}^{\infty} \mathrm{DOS}(E) \, f \, \left(1 - f \right) \frac{(E - \mu)^2}{k_B T^2} \, dE. + + C_{v,\mathrm{el}}(T, V) = + \int_{-\infty}^{\infty} \mathrm{DOS}(E) \, f \, + \left( 1 - f \right) + \frac{(E - \mu)^2}{k_B T^2} \, dE. Args: energies (np.ndarray): Energy values for the electron DOS, in eV. From 97cadf35b9ec9499293e02eb2a06370114f31933 Mon Sep 17 00:00:00 2001 From: "Nigel L. E. Hew" <77617652+nhew1994@users.noreply.github.com> Date: Sat, 10 Jan 2026 08:50:50 -0500 Subject: [PATCH 55/66] Remove redundant TODO comments for documentation --- dfttk/thermal_electronic/thermal_electronic.py | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index 0fd71ee..98ac1f9 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -1067,8 +1067,7 @@ def calculate_entropies( plot: bool = False, plot_temperature: float = None, ) -> np.ndarray: - #TODO: fix the formula for readthedocs: - #S_\mathrm{el}(T, V) = - k_B \int_{-\infty}^{\infty} \mathrm{DOS}(E) \left[ f \ln f + (1 - f) \ln (1 - f) \right] \, dE + #TODO: fix the formula for readthedocs """ Calculates the thermal electronic contribution to the entropy for a given volume using the formula @@ -1227,7 +1226,7 @@ def calculate_heat_capacities( plot=False, plot_temperature: float = None, ) -> np.ndarray: - #TODO: fix the formula for readthedocs: + #TODO: fix the formula for readthedocs """ Calculates the thermal electronic contribution to the heat capacity for a given volume using the formula From 140abb816d2786ca09a72455eeae65a09d7c8357 Mon Sep 17 00:00:00 2001 From: "Nigel L. E. Hew" <77617652+nhew1994@users.noreply.github.com> Date: Sat, 10 Jan 2026 09:05:04 -0500 Subject: [PATCH 56/66] Remove mathematical formulas from docstrings Removed mathematical formulas from docstrings for various functions related to thermal electronic calculations. --- .../thermal_electronic/thermal_electronic.py | 43 ++----------------- 1 file changed, 3 insertions(+), 40 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index 98ac1f9..b724357 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -762,12 +762,6 @@ def fermi_dirac_distribution( """ Calculates the Fermi-Dirac distribution function. - The function is given by: - - .. math:: - - f(E, \\mu, T) = \\frac{1}{1 + \\exp\\left(\\frac{E - \\mu}{k_B T}\\right)} - Args: energies (np.ndarray): Energy values for the electron DOS, in eV. chemical_potential (float): Chemical potential for a given volume and temperature, in eV. @@ -851,10 +845,6 @@ def calculate_num_electrons( Calculates the number of electrons for a given electronic DOS, chemical potential, and temperature. - .. math:: - - N = \int_{-\infty}^{\infty} \mathrm{DOS}(E) \, f(E, \mu, T) \, dE - Args: energies (np.ndarray): Energy values for the electron DOS, in eV. dos (np.ndarray): Electron DOS values, in states/eV. @@ -894,12 +884,6 @@ def calculate_internal_energies( """ Calculates the thermal electronic contribution to the internal energy for a given volume. - .. math:: - - U_\mathrm{el}(T, V) = - \int_{-\infty}^{\infty} \mathrm{DOS}(E) \, f(E, \mu, T) \, E \, dE - - \int_{-\infty}^{E_F} \mathrm{DOS}(E) \, E \, dE - Args: energies (np.ndarray): Energy values from the electron DOS, in eV. dos (np.ndarray): Electron DOS values, in states/eV. @@ -1067,17 +1051,8 @@ def calculate_entropies( plot: bool = False, plot_temperature: float = None, ) -> np.ndarray: - #TODO: fix the formula for readthedocs """ - Calculates the thermal electronic contribution to the entropy for a given volume using the formula - - .. math:: - - S_\mathrm{el}(T, V) = - - k_B \int_{-\infty}^{\infty} \mathrm{DOS}(E) - \left[ - f \ln f + (1 - f) \ln (1 - f) - \right]\, dE. + Calculates the thermal electronic contribution to the entropy for a given volume. Args: energies (np.ndarray): Energy values for the electron DOS, in eV. @@ -1226,16 +1201,8 @@ def calculate_heat_capacities( plot=False, plot_temperature: float = None, ) -> np.ndarray: - #TODO: fix the formula for readthedocs """ - Calculates the thermal electronic contribution to the heat capacity for a given volume using the formula - - .. math:: - - C_{v,\mathrm{el}}(T, V) = - \int_{-\infty}^{\infty} \mathrm{DOS}(E) \, f \, - \left( 1 - f \right) - \frac{(E - \mu)^2}{k_B T^2} \, dE. + Calculates the thermal electronic contribution to the heat capacity for a given volume. Args: energies (np.ndarray): Energy values for the electron DOS, in eV. @@ -1375,11 +1342,7 @@ def calculate_helmholtz_energies( temperatures: np.ndarray, ) -> np.ndarray: """ - Calculates the thermal electronic contribution to the Helmholtz free energy for a given volume using the formula - - .. math:: - - F_\mathrm{el}(T, V) = U_\mathrm{el}(T, V) - T \, S_\mathrm{el}(T, V). + Calculates the thermal electronic contribution to the Helmholtz free energy for a given volume. Args: internal_energies (np.ndarray): Internal energy values, in eV. From a95f2547ddcac9a65c3f20528cfa21c3681e0ab1 Mon Sep 17 00:00:00 2001 From: "Nigel L. E. Hew" <77617652+nhew1994@users.noreply.github.com> Date: Sat, 10 Jan 2026 09:11:40 -0500 Subject: [PATCH 57/66] Refactor usage instructions in thermal_electronic.py Removed redundant bullet points from usage instructions. --- dfttk/thermal_electronic/thermal_electronic.py | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index b724357..c40a5d3 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -30,14 +30,12 @@ class ThermalElectronic: 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()`.\n - 2. Compute thermal electronic contributions (Helmholtz free energy, - internal energy, entropy, and heat capacity) using `process()` and `fit()`.\n - 3. Visualize results with the provided plotting methods. + 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 From 02d8753fc23558c018ce521ff30900b5b01bac67 Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Sat, 10 Jan 2026 09:37:12 -0500 Subject: [PATCH 58/66] FIX: fix return types in ThermalElectronic --- .../thermal_electronic/thermal_electronic.py | 21 +++++++++++-------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index c40a5d3..d1060b5 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -771,7 +771,7 @@ def fermi_dirac_distribution( ValueError: If `temperature < 0 K`. Returns: - np.ndarray or (np.ndarray, go.Figure): + np.ndarray or tuple[np.ndarray, go.Figure]: Fermi-Dirac distribution function values, and optionally the Plotly figure if `plot=True`. """ @@ -878,7 +878,7 @@ def calculate_internal_energies( resolution: float = 0.001, plot: bool = False, plot_temperature: float = None, - ) -> np.ndarray: + ) -> np.ndarray | tuple[np.ndarray, go.Figure, go.Figure]: """ Calculates the thermal electronic contribution to the internal energy for a given volume. @@ -897,7 +897,8 @@ def calculate_internal_energies( ValueError: If `plot_temperature` is not in `temperatures` when `plot=True`. Returns: - np.ndarray: Internal energy values, in eV. + np.ndarray or tuple[np.ndarray, go.Figure, go.Figure]: Internal energy values, in eV and + optionally the Plotly figures if `plot=True`. """ # If there are negative temperatures, raise an error @@ -994,7 +995,7 @@ def plot_internal_energy_integral( filtered_energies: np.ndarray, integrand_2: np.ndarray, plot_temperature: float, - ) -> go.Figure: + ) -> tuple[go.Figure, go.Figure]: """ Plots the integrands versus energy of the internal energy equation. @@ -1006,7 +1007,7 @@ def plot_internal_energy_integral( plot_temperature (float): Temperature at which the integrand is plotted, in K. Returns: - go.Figure: Plotly figure object containing the integrand curves. + tuple[go.Figure, go.Figure]: Plotly figure objects containing the integrand curves. """ plot_temperature = float(plot_temperature) @@ -1048,7 +1049,7 @@ def calculate_entropies( resolution: float = 0.0001, plot: bool = False, plot_temperature: float = None, - ) -> np.ndarray: + ) -> np.ndarray | tuple[np.ndarray, go.Figure]: """ Calculates the thermal electronic contribution to the entropy for a given volume. @@ -1067,7 +1068,8 @@ def calculate_entropies( ValueError: If plot_temperature is not in `temperatures` when `plot=True`. Returns: - np.ndarray: Entropy values as a function of temperature, in eV/K. + np.ndarray | tuple[np.ndarray, go.Figure]: Entropy values as a function of temperature, in eV/K + and optionally the Plotly figure if `plot=True`. """ # If there are negative temperatures, raise an error @@ -1198,7 +1200,7 @@ def calculate_heat_capacities( resolution: float = 0.0001, plot=False, plot_temperature: float = None, - ) -> np.ndarray: + ) -> np.ndarray | tuple[np.ndarray, go.Figure]: """ Calculates the thermal electronic contribution to the heat capacity for a given volume. @@ -1217,7 +1219,8 @@ def calculate_heat_capacities( ValueError: If plot_temperature is not in `temperatures` when `plot=True`. Returns: - np.ndarray: Heat capacity values in eV/K. + np.ndarray | tuple[np.ndarray, go.Figure]: Heat capacity values in eV/K + and optionally the Plotly figure if `plot=True`. """ # If there are negative temperatures, raise an error From f58a1ab71f694911d2546d229602526c613c72b7 Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Sat, 10 Jan 2026 09:52:38 -0500 Subject: [PATCH 59/66] MAINT: update ThermalElectronic docstrings --- dfttk/thermal_electronic/thermal_electronic.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index d1060b5..1a0a30c 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -771,7 +771,7 @@ def fermi_dirac_distribution( ValueError: If `temperature < 0 K`. Returns: - np.ndarray or tuple[np.ndarray, go.Figure]: + np.ndarray | tuple[np.ndarray, go.Figure]: Fermi-Dirac distribution function values, and optionally the Plotly figure if `plot=True`. """ @@ -897,7 +897,7 @@ def calculate_internal_energies( ValueError: If `plot_temperature` is not in `temperatures` when `plot=True`. Returns: - np.ndarray or tuple[np.ndarray, go.Figure, go.Figure]: Internal energy values, in eV and + np.ndarray | tuple[np.ndarray, go.Figure, go.Figure]: Internal energy values, in eV and optionally the Plotly figures if `plot=True`. """ From 7ca5c7bb8441fbf17c9139b5f8165d097a33b598 Mon Sep 17 00:00:00 2001 From: "Nigel L. E. Hew" <77617652+nhew1994@users.noreply.github.com> Date: Sat, 10 Jan 2026 11:30:54 -0500 Subject: [PATCH 60/66] Update docs/api/dfttk.thermal_electronic.rst Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/api/dfttk.thermal_electronic.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/api/dfttk.thermal_electronic.rst b/docs/api/dfttk.thermal_electronic.rst index 3b965b8..2851a8d 100644 --- a/docs/api/dfttk.thermal_electronic.rst +++ b/docs/api/dfttk.thermal_electronic.rst @@ -17,5 +17,6 @@ ThermalElectronicData --------------------- .. autoclass:: dfttk.thermal_electronic.thermal_electronic_data.ThermalElectronicData + :members: :undoc-members: :show-inheritance: From c0a1077c655617ff6cc1055d4ba94d9df26dbb5d Mon Sep 17 00:00:00 2001 From: "Nigel L. E. Hew" <77617652+nhew1994@users.noreply.github.com> Date: Sat, 10 Jan 2026 11:33:50 -0500 Subject: [PATCH 61/66] Update dfttk/thermal_electronic/thermal_electronic.py Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- dfttk/thermal_electronic/thermal_electronic.py | 5 ----- 1 file changed, 5 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index 1a0a30c..d7ce029 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -310,13 +310,8 @@ def process( internal energy, entropy, and heat capacity. Args: - volumes_fit (np.ndarray): - 1D array of volumes used for fitting the properties, shape - (n_volumes_fit,), in ų. temperatures (np.ndarray): 1D array of temperatures in K, shape (n_temperatures,). - order (int): - Order of the polynomial fit. Defaults to 1 (linear fit). Raises: ValueError: From 6ff0c1fbbdf9f4179b92531569575fd47ca0a4da Mon Sep 17 00:00:00 2001 From: "Nigel L. E. Hew" <77617652+nhew1994@users.noreply.github.com> Date: Sat, 10 Jan 2026 11:42:51 -0500 Subject: [PATCH 62/66] Update dfttk/thermal_electronic/thermal_electronic.py Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- dfttk/thermal_electronic/thermal_electronic.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index d7ce029..36b30b6 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -1193,7 +1193,7 @@ def calculate_heat_capacities( temperatures: np.ndarray, energies_fit_range: np.ndarray = np.array([-2, 2]), resolution: float = 0.0001, - plot=False, + plot: bool = False, plot_temperature: float = None, ) -> np.ndarray | tuple[np.ndarray, go.Figure]: """ From 7d3329cefe422134c59a342b3b944c5d2ad31485 Mon Sep 17 00:00:00 2001 From: "Nigel L. E. Hew" <77617652+nhew1994@users.noreply.github.com> Date: Sat, 10 Jan 2026 11:45:16 -0500 Subject: [PATCH 63/66] Update dfttk/thermal_electronic/thermal_electronic.py Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- dfttk/thermal_electronic/thermal_electronic.py | 2 -- 1 file changed, 2 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index 36b30b6..db27fa4 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -146,8 +146,6 @@ def read_total_electron_dos( CONTCAR and vasprun.xml files. folder_prefix (str, optional): Prefix of the electronic folders. Defaults to ``"elec"``. - contcar_name (str, optional): - Name of the CONTCAR file. Defaults to ``"CONTCAR.elec_dos"``. vasprun_name (str, optional): Name of the vasprun.xml file. Defaults to ``"vasprun.xml.elec_dos"``. selected_volumes (np.ndarray, optional): From 7b79956bedbf057863be696ce6f959f1d448148d Mon Sep 17 00:00:00 2001 From: nhew1994 Date: Sat, 10 Jan 2026 11:53:24 -0500 Subject: [PATCH 64/66] MAINT: update ThermalElectronic docstrings --- .../thermal_electronic/thermal_electronic.py | 81 ++++++++----------- 1 file changed, 32 insertions(+), 49 deletions(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index db27fa4..bdbfd0a 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -141,24 +141,16 @@ def read_total_electron_dos( Reads the total electron DOS data from VASP calculations for different volumes. Args: - path (str): - Path to the directory containing the specific folders with - CONTCAR and vasprun.xml files. - folder_prefix (str, optional): - Prefix of the electronic folders. Defaults to ``"elec"``. - vasprun_name (str, optional): - Name of the vasprun.xml file. Defaults to ``"vasprun.xml.elec_dos"``. - selected_volumes (np.ndarray, optional): - List of selected volumes to keep the electron DOS data. Defaults - to None. + path (str): Path to the directory containing the specific folders with + vasprun.xml files. + folder_prefix (str, optional): Prefix of the electronic folders. Defaults to ``"elec"``. + vasprun_name (str, optional): Name of the vasprun.xml file. Defaults to ``"vasprun.xml.elec_dos"``. + selected_volumes (np.ndarray, optional): List of selected volumes to keep the electron DOS data. Defaults to None. Raises: - 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. + 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. """ self.path = path @@ -272,19 +264,14 @@ def set_total_electron_dos( Set the total electron DOS directly. Args: - number_of_atoms (int): - Number of atoms corresponding to the DOS data. - volumes (np.ndarray): - 1D array of volumes, shape (n_volumes,), in ų. - energies_list (list[np.ndarray]): - List of 1D arrays of energies referenced to the Fermi level + number_of_atoms (int): Number of atoms corresponding to the DOS data. + volumes (np.ndarray): 1D array of volumes, shape (n_volumes,), in ų. + energies_list (list[np.ndarray]): List of 1D arrays of energies referenced to the Fermi level (:math:`E - E_F`) for each volume, in eV. - dos_list (list[np.ndarray]): - List of 1D arrays of DOS values for each volume, in states/eV. + dos_list (list[np.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. + ValueError: Lengths of volumes, energies_list, and dos_list must be the same. """ self.number_of_atoms = number_of_atoms @@ -308,12 +295,10 @@ def process( internal energy, entropy, and heat capacity. Args: - temperatures (np.ndarray): - 1D array of temperatures in K, shape (n_temperatures,). + temperatures (np.ndarray): 1D array of temperatures in K, shape (n_temperatures,). Raises: - ValueError: - If DOS data is not found. + ValueError: If DOS data is not found. """ self.temperatures = temperatures @@ -369,15 +354,12 @@ def fit( of volume for various fixed temperatures. Args: - volumes_fit (np.ndarray): - 1D array of volumes used for fitting the properties, shape + volumes_fit (np.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). + order (int): Order of the polynomial fit. Defaults to 1 (linear fit). Raises: - ValueError: - Thermodynamic properties have not been calculated. + ValueError: Thermodynamic properties have not been calculated. """ # If helmholtz_energies is None, raise an error @@ -445,8 +427,7 @@ def plot_total_dos(self) -> go.Figure: Plots the total electron DOS for different volumes. Raises: - ValueError: - DOS data not found. Please read or set the total electron DOS first + 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: @@ -496,10 +477,8 @@ def plot_vt(self, type: str, selected_temperatures: np.ndarray = None) -> go.Fig (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. + ValueError: Thermodynamic properties have not been calculated. + ValueError: The `type` argument is not one of the allowed values. Returns: go.Figure: @@ -890,8 +869,9 @@ def calculate_internal_energies( ValueError: If `plot_temperature` is not in `temperatures` when `plot=True`. Returns: - np.ndarray | tuple[np.ndarray, go.Figure, go.Figure]: Internal energy values, in eV and - optionally the Plotly figures if `plot=True`. + np.ndarray | tuple[np.ndarray, go.Figure, go.Figure]: + Internal energy values, in eV + and optionally the Plotly figures if `plot=True`. """ # If there are negative temperatures, raise an error @@ -1000,7 +980,8 @@ def plot_internal_energy_integral( plot_temperature (float): Temperature at which the integrand is plotted, in K. Returns: - tuple[go.Figure, go.Figure]: Plotly figure objects containing the integrand curves. + tuple[go.Figure, go.Figure]: + Plotly figure objects containing the integrand curves. """ plot_temperature = float(plot_temperature) @@ -1061,8 +1042,9 @@ def calculate_entropies( ValueError: If plot_temperature is not in `temperatures` when `plot=True`. Returns: - np.ndarray | tuple[np.ndarray, go.Figure]: Entropy values as a function of temperature, in eV/K - and optionally the Plotly figure if `plot=True`. + np.ndarray | tuple[np.ndarray, go.Figure]: + Entropy values as a function of temperature, in eV/K + and optionally the Plotly figure if `plot=True`. """ # If there are negative temperatures, raise an error @@ -1212,8 +1194,9 @@ def calculate_heat_capacities( ValueError: If plot_temperature is not in `temperatures` when `plot=True`. Returns: - np.ndarray | tuple[np.ndarray, go.Figure]: Heat capacity values in eV/K - and optionally the Plotly figure if `plot=True`. + np.ndarray | tuple[np.ndarray, go.Figure]: + Heat capacity values in eV/K + and optionally the Plotly figure if `plot=True`. """ # If there are negative temperatures, raise an error From e766d15c8333d68c8c816fad99a1a58232fe328d Mon Sep 17 00:00:00 2001 From: "Nigel L. E. Hew" <77617652+nhew1994@users.noreply.github.com> Date: Sat, 10 Jan 2026 12:00:36 -0500 Subject: [PATCH 65/66] Update dfttk/thermal_electronic/thermal_electronic.py Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- dfttk/thermal_electronic/thermal_electronic.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index bdbfd0a..a5e7ea5 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -623,7 +623,7 @@ def calculate_chemical_potential( dos (np.ndarray): Electron DOS values. temperature (float): Temperature in K. chemical_potential_range (np.ndarray, optional): Range to search for the - chemical potential. Defaults to None. + chemical potential. Defaults to np.array([-0.1, 0.1]). electron_tol (float, optional): Tolerance for electron number matching. Defaults to 0.5. From 1f44f43a94a1aa004a0868a62cffe9efa50c64b1 Mon Sep 17 00:00:00 2001 From: "Nigel L. E. Hew" <77617652+nhew1994@users.noreply.github.com> Date: Sat, 10 Jan 2026 12:00:54 -0500 Subject: [PATCH 66/66] Update dfttk/thermal_electronic/thermal_electronic.py Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- dfttk/thermal_electronic/thermal_electronic.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dfttk/thermal_electronic/thermal_electronic.py b/dfttk/thermal_electronic/thermal_electronic.py index a5e7ea5..df7a115 100644 --- a/dfttk/thermal_electronic/thermal_electronic.py +++ b/dfttk/thermal_electronic/thermal_electronic.py @@ -780,7 +780,7 @@ def plot_fermi_dirac_distribution( temperature and chemical potential. Args: - energy (np.ndarray): Energy values for the electron DOS, in eV. + energies (np.ndarray): Energy values for the electron DOS, in eV. fermi_dist (np.ndarray): Fermi-Dirac distribution function values. chemical_potential (float): Chemical potential for a given volume and temperature, in eV.