Thermochemistry tools

aithermo.py module

API reference

class pyphyschemtools.aithermo.aiThermo(folder_path=None, color_scales=None)[source]

Bases: object

A class to handle thermodynamic surface stability analysis and visualization within the tools4pyPhysChem framework. Initialize the aiThermo object.

Parameters:

  • folder_path (str or Path) – Path to the working directory.

  • color_scales (list, optional) – List of plotly-compatible color scales.

ListOfStableSurfaceCompositions(vib)[source]

Identify and list the relevant thermodynamic data files for the current analysis.

This method scans the working directory for data files matching specific naming conventions (TPcoverage or TPcoveragevib). It cross-references these with a local configuration file ‘ListOfStableSurfaces.dat’ to extract surface names and legend labels.

Parameters:

vib (bool) – If True, filters for files including vibrational corrections (prefixed with vib_). If False, looks for standard thermodynamic data.

Returns:

A triplet containing: - file_paths (list of str): Absolute or relative paths to the .dat files. - names (list of str): Internal identifiers for each surface phase. - legends (list of str): LaTeX-formatted or plain text labels for graphical legends.

Return type:

tuple

Notes

  • The lists are returned in reverse order to ensure correct layering during 3D plotting.

  • Relies on ‘ListOfStableSurfaces.dat’ existing in the folder_path.

plot_palette(angle=0, save_png=None)[source]

Visualize the 1D color palette used for surface identification.

This method generates a horizontal bar of colors corresponding to the different surface phases defined in the instance. Each color is labeled with its numerical index, allowing for quick cross-referencing between the palette and the 3D surface plot.

Parameters:

  • angle (int, optional) – Rotation angle of the x-axis tick labels (indices). Defaults to 0.

  • save_png (str, optional) – Filename (including .png extension) to save the palette image to the working directory. Defaults to None (display only).

Returns:

Displays the plot using matplotlib.pyplot.show().

Return type:

None

Notes

  • Requires ‘seaborn’ for the palplot generation.

  • If ‘save_png’ is provided, the image is saved with a resolution of 300 DPI and a transparent background.

plot_surface(saveFig=None, vib=True, texLegend=False, xLegend=0.5, yLegend=0.4)[source]

Generate an interactive 3D thermodynamic stability map using Plotly.

This method visualizes multiple Gibbs free energy surfaces as a function of Temperature (X) and Pressure (Y). It automatically handles log-scale transformations for the pressure axis and projects reference experimental conditions and phase boundaries onto the plot.

Parameters:

  • saveFig (str, optional) – The filename (without extension) to export the resulting plot as a PNG image. Defaults to None (no save).

  • vib (bool) – Whether to use vibration-corrected data. Defaults to True.

  • texLegend (bool) – If True, uses LaTeX legends extracted from the configuration file. Defaults to False.

  • xLegend (float) – Horizontal position of the legend box (0 to 1). Defaults to 0.5.

  • yLegend (float) – Vertical position of the legend box (0 to 1). Defaults to 0.4.

Returns:

An interactive widget containing

the 3D surfaces, experimental markers, and reference lines.

Return type:

plotly.graph_objects.FigureWidget

Workflow:

  1. Scans data files and parses Temperature/Pressure/Energy grids.

  2. Traces individual 3D surfaces with mapped color scales.

  3. Calculates and plots intersection boundaries between surface phases.

  4. Overlays experimental markers (e.g., specific T/P conditions).

  5. Optionally exports and crops the resulting image using Pillow.