Pes

KB = 0.001987204259 module-attribute

Boltzmann constant in kcal/(mol K).

create_pes(x_data, y_data, bins=30, vmin=0, vmax=10, levels=30, T=None, ax=None, colorbar=True)

Create a potential energy surface (PES) plot using matplotlib.

This function generates a 2D histogram from the input data using the get_2d_hist function, and then creates a contour plot representing either the potential of mean force (PMF) or the negative logarithm of probability.

PARAMETER	DESCRIPTION
x_data	1D array of x-coordinates for the data points. TYPE: ArrayLike
y_data	1D array of y-coordinates for the data points. TYPE: ArrayLike
bins	The bin specification for the 2D histogram. Defaults to 30. If int, the number of bins for both dimensions. If array-like, the bin edges for both dimensions. If (int, int), the number of bins in each dimension. If (array, array), the bin edges in each dimension. TYPE: int | ArrayLike | tuple[int, int] | tuple[ArrayLike, ArrayLike] DEFAULT: 30
vmin	Minimum value for the colorbar. Defaults to 0. TYPE: float DEFAULT: 0
vmax	Maximum value for the colorbar. Defaults to 10. TYPE: float DEFAULT: 10
levels	Number of contour levels. Defaults to 30. TYPE: int DEFAULT: 30
T	Temperature in Kelvin. If provided, the plot represents PMF. If None, it represents -ln(p). Defaults to None. TYPE: float | None DEFAULT: None

RETURNS	DESCRIPTION
Figure	A matplotlib Figure object containing the PES plot.

RAISES	DESCRIPTION
ValueError	If x_data and y_data have different lengths.

Example

>>> import numpy as np
>>> x = np.random.randn(1000)
>>> y = np.random.randn(1000)
>>> fig = create_pes(x, y, bins=20, T=300)
>>> fig.savefig('pes_plot.png')

create_pes_difference(data_x_ref, data_y_ref, data_x, data_y, bins=30, vmin=-10, vmax=10, levels=30, T=None)

Create a difference plot of two potential energy surfaces (PES) using matplotlib.

This function generates 2D histograms from two sets of input data using the get_2d_hist function, calculates their difference, and then creates a contour plot representing either the difference in potential of mean force (ΔPMF) or the difference in negative logarithm of probability.

PARAMETER	DESCRIPTION
data_x_ref	1D array of x-coordinates for the reference data points. TYPE: ArrayLike
data_y_ref	1D array of y-coordinates for the reference data points. TYPE: ArrayLike
data_x	1D array of x-coordinates for the comparison data points. TYPE: ArrayLike
data_y	1D array of y-coordinates for the comparison data points. TYPE: ArrayLike
bins	The bin specification for the 2D histograms. If int, the number of bins for both dimensions. If array-like, the bin edges for both dimensions. If (int, int), the number of bins in each dimension. If (array, array), the bin edges in each dimension. TYPE: int | ArrayLike | tuple[int, int] | tuple[ArrayLike, ArrayLike] DEFAULT: 30
vmin	Minimum value for the colorbar. TYPE: float DEFAULT: -10
vmax	Maximum value for the colorbar. TYPE: float DEFAULT: 10
levels	Number of contour levels. TYPE: int DEFAULT: 30
T	Temperature in Kelvin. If provided, the plot represents ΔPMF. If None, it represents -Δln(p). TYPE: float | None DEFAULT: None

RETURNS	DESCRIPTION
Figure	A matplotlib Figure object containing the PES difference plot.

RAISES	DESCRIPTION
ValueError	If input data arrays have different lengths or are incompatible.

Example

>>> import numpy as np
>>> x_ref = np.random.randn(1000)
>>> y_ref = np.random.randn(1000)
>>> x = np.random.randn(1000)
>>> y = np.random.randn(1000)
>>> fig = create_pes_difference(x_ref, y_ref, x, y, bins=20, T=300)
>>> fig.savefig('pes_difference_plot.png')

Notes

• The function uses a TwoSlopeNorm for coloring, centered at 0.
• The resulting plot uses a diverging colormap (RdBu_r) to highlight differences.
• The masked_difference function should be defined elsewhere to handle the difference calculation between potentially masked arrays.

get_2d_hist(x_data, y_data, bins=13, T=None)

Compute a 2D histogram and calculate the potential of mean force.

This function creates a 2D histogram from the input data and calculates the potential of mean force (PMF) or the negative logarithm of probability, depending on whether a temperature is provided.

PARAMETER	DESCRIPTION
x_data	1D array of x-coordinates for the data points. TYPE: ArrayLike
y_data	1D array of y-coordinates for the data points. Must have the same length as x_data. TYPE: ArrayLike
bins	The bin specification for the 2D histogram. - If int, the number of bins for both dimensions. - If array-like, the bin edges for both dimensions. - If [int, int], the number of bins in each dimension. - If [array, array], the bin edges in each dimension. TYPE: int | ArrayLike | tuple[int, int] | tuple[ArrayLike, ArrayLike] DEFAULT: 13
T	Temperature in Kelvin. If provided, the function calculates the potential of mean force. If None, it calculates \(-ln(p)\) where \(p\) is the probability. TYPE: float | int | None DEFAULT: None

RETURNS	DESCRIPTION
MaskedArray	2D array containing the calculated histogram values. Zero counts are masked. If T is provided, values represent the potential of mean force in energy units \(k_B T\). If T is None, values represent \(-\ln(p)\).
dict[str, tuple[ArrayLike, ArrayLike]]	A dictionary containing information about the bin edges and centers: 'edges': tuple of (x_edges, y_edges) 'centers': tuple of (x_centers, y_centers)

RAISES	DESCRIPTION
ValueError	If x_data and y_data have different lengths.

Notes

• The function uses numpy.histogram2d to create the initial 2D histogram.
• Zero counts in the histogram are masked to avoid log(0) errors.
• The histogram is normalized to represent probabilities.

Example

>>> import numpy as np
>>> x = np.random.randn(1000)
>>> y = np.random.randn(1000)
>>> hist, bins_info = get_2d_hist(x, y, bins=20, T=300)
>>> print(hist.shape)
(20, 20)
>>> print(bins_info.keys())
dict_keys(['edges', 'centers'])

masked_difference(hist_ref, hist)

Compute the difference between two masked histograms with special handling for masked values.

This function calculates the difference between two histograms, taking into account masked values. It handles special cases where data is present in one histogram but not in the other.

PARAMETER	DESCRIPTION
hist_ref	The reference histogram. TYPE: MaskedArray
hist	The histogram to compare against the reference. TYPE: MaskedArray

RETURNS	DESCRIPTION
MaskedArray	The difference between the two histograms, with special handling for masked values: Where both histograms have values, it returns the normal hist - hist_ref difference. Where hist_ref is masked and hist is not, it returns the difference between hist's value and the maximum value in hist. Where hist is masked and hist_ref is not, it returns hist_ref's value.

RAISES	DESCRIPTION
ValueError	If the input arrays have different shapes.

Note

This function assumes that masked values in the histograms represent configurations that were not observed. The special handling of these cases is designed to capture significant changes in the observability of states.