System

pyzentropy.system

class pyzentropy.system.System(configurations, ground_state)

Bases: object

Represents a thermodynamic system composed of multiple configurations.

This class provides methods to calculate system thermodynamic quantities, such as Helmholtz free energies and related properties. In addition to properties dependent on temperature and volume, it can also calculate properties at fixed pressure and generate phase diagrams.

Properties dependent on temperature and volume can be plotted either as a function of temperature or volume. Properties at fixed pressure are plotted as a function of temperature.

Notes

• All array-valued thermodynamic quantities follow the shape (n_temperatures, n_volumes).

• Temperatures are in Kelvin.

• Volumes are in ų.

• Energies are in eV and are extensive with respect to the configuration size (number_of_atoms).

• Entropies and heat capacities are in eV/K and are extensive with respect to the configuration size (number_of_atoms).

• Bulk moduli and pressures are in GPa.

• Current version only supports one common tangent construction for phase diagrams.

Parameters:

• configurations (dict[str, Configuration]) – Dictionary mapping configuration names to Configuration objects.

• ground_state (str) – Name of the ground state configuration.

Raises:

ValueError – If configurations have inconsistent number of atoms, volumes, or temperatures.

configurations

Dictionary mapping configuration names to Configuration objects.

ground_state

Name of the ground state configuration.

number_of_atoms

Number of atoms in the system.

volumes

Volume grid of shape (n_volumes,).

temperatures

Temperature grid of shape (n_temperatures,).

partition_functions

Partition functions \(Z(T, V)\).

helmholtz_energies

Helmholtz free energies \(F(T, V)\).

helmholtz_energies_dV

First volume derivatives \(\partial F / \partial V\).

helmholtz_energies_d2V2

Second volume derivatives \(\partial^2 F / \partial V^2\).

ground_state_helmholtz_energies

Helmholtz free energies of the ground state configuration \(F_{\mathrm{GS}}(T, V)\).

entropies

Entropies \(S(T, V)\).

configurational_entropies

Configurational entropies \(S_{\mathrm{conf}}(T, V)\).

bulk_moduli

Bulk moduli \(B(T, V)\).

heat_capacities

Heat capacities at constant volume \(C_V(T, V)\).

pt_properties

Dictionary storing pressure-temperature dependent properties.

pt_phase_diagram

Pressure-temperature phase diagram data.

vt_phase_diagram

Volume-temperature phase diagram data.

calculate_bulk_moduli()

Calculate the bulk moduli for the system at each temperature and volume \(B(T, V)\).

Raises:

ValueError – If the second derivative of the Helmholtz free energy with respect to volume is not calculated.

Return type:

None

calculate_entropies()

Calculate the configurational entropy \(S_\mathrm{conf}(T, V)\) and total entropy \(S(T, V)\) for the system.

Raises:

ValueError – If probabilities or entropies are missing for any configuration.

Return type:

None

calculate_heat_capacities()

Calculate the heat capacities for the system at each temperature and volume \(C_V(T, V)\).

Raises:

ValueError – If probabilities, heat capacities, or internal energies are missing for any configuration.

Return type:

None

calculate_helmholtz_energies(ground_state_helmholtz_energies)

Calculate the Helmholtz free energies for the system \(F(T, V)\).

Parameters:

ground_state_helmholtz_energies (ndarray) – Reference ground-state Helmholtz free energies \(F_{\mathrm{GS}}(T, V)\) to shift the configuration Helmholtz free energies in the exponential.

Raises:

ValueError – If the system partition functions are not calculated.

Return type:

None

calculate_helmholtz_energies_d2V2()

Calculate the second derivative of the Helmholtz free energies with respect to volume \(\partial^2 F / \partial V^2\).

Raises:

ValueError – If the probabilities, or the Helmholtz energy first and second derivatives are missing for any configuration.

Return type:

None

calculate_helmholtz_energies_dV()

Calculate the first derivative of the Helmholtz energies with respect to volume \(\partial F / \partial V\).

Raises:

ValueError – If the probabilities or Helmholtz energy first derivatives are missing for any configuration.

Return type:

None

calculate_partition_functions()

Calculate the partition function for each configuration using a reference ground-state Helmholtz free energy.

The configuration partition functions \(Z_k(T, V)\) are first computed. Then, the total partition function of the system is then obtained by summing over all configurations: \(Z(T, V) = \sum_k g_k Z_k\).

Return type:

None

calculate_phase_diagrams(dP=0.2, volume_step_size=0.0001, atol=1e-06)

Calculate pressure-temperature and volume-temperature phase diagrams for the system.

Parameters:

• dP (float) – Pressure increment in GPa. Default is 0.2 GPa.

• volume_step_size (float) – Step size for volume when searching for the miscibility gap. Default is 1e-4.

• atol (float) – Absolute tolerance for convergence in the common tangent search. Default is 1e-6.

Raises:

ValueError – If any of the Helmholtz energies or their first derivatives are not calculated, or if probabilities for any configuration are not calculated.

Return type:

None

calculate_pressure_properties(P)

Calculate pressure-dependent properties \(V_0\), \(G_0\), \(S_0\), \(S_{\mathrm{conf}}\), \(B_0\), \(\mathrm{CTE}\), \(\mathrm{LCTE}\), \(C_p\) at a given pressure.

Parameters:

P (float) – Pressure in GPa.

Raises:

ValueError – If any Helmholtz energies or their derivatives are not calculated, or if probabilities for any configuration are not calculated.

Return type:

None

calculate_probabilities()

Calculate the configuration probabilities \(p_k(T, V)\).

Raises:

ValueError – If the system partition function is not calculated.

Return type:

None

plot_pt(type, P=0.0, selected_temperatures=None, width=650, height=600)

Generate a plot for the specified thermodynamic quantity.

Parameters:

• type (str) – The type of plot to generate (e.g., “helmholtz_energy_pv_vs_volume”).

• P (float) – Pressure in GPa for the plot. Default is 0.00 GPa.

• selected_temperatures (ndarray) – Temperatures to highlight in the helmholtz_energy_pv_vs_volume plot.

• width (int) – Width of the plot in pixels.

• height (int) – Height of the plot in pixels.

Returns:

The generated plotly figure.

Return type:

plotly.graph_objects.Figure

Raises:

• ValueError – If properties at P are not calculated.

• ValueError – If the plot type is invalid.

• ValueError – If phase diagram data is not calculated when wanting to plot the phase diagram.

plot_vt(type, selected_temperatures=None, selected_volumes=None, width=650, height=600)

Generate a plot vs. volume or temperature for the specified thermodynamic quantity.

Parameters:

• type (str) – The type of plot to generate (e.g., “helmholtz_energy_vs_volume”).

• selected_temperatures (ndarray) – Temperatures to highlight in the plot.

• selected_volumes (ndarray) – Volumes to highlight in the plot.

• width (int) – Width of the plot in pixels.

• height (int) – Height of the plot in pixels.

Returns:

The generated plotly figure.

Return type:

plotly.graph_objects.Figure

Raises:

• ValueError – If the plot type is invalid.

• ValueError – If the required data for the plot (e.g., Helmholtz energies, probabilities, volumes, pressure, etc.) is missing or not calculated.