mlcolvar.utils.fes.compute_fes

class mlcolvar.utils.fes.compute_fes(X, temp=None, fes_units='kJ/mol', kbt=None, num_samples=200, bounds=None, bandwidth=0.01, kernel='gaussian', weights=None, scale_by=None, blocks=1, fes_to_zero=None, plot=False, plot_color='fessa6', plot_max_fes=None, plot_error_style='fill_between', plot_levels=None, ax=None, backend=None, eps=None)[source]

Bases:

Compute the Free Energy Surface using a kernel density estimation (KDE) along the given variables. See notes below.

Parameters

tempfloat, optional

Temperature (in Kelvin). Required if kbt is not provided.

fes_unitsstr, optional

Units of the FES if using temp, by default “kJ/mol”.

kbtfloat, optional

Thermal energy in the same units as the FES. Required if temp is not provided.

num_samplesint, optional

Number of grid points per dimension for FES evaluation, by default 200.

boundslist of tuples, optional

List of (min, max) for each dimension. If None, computed from data range.

bandwidthfloat, optional

Bandwidth for the kernel density estimation, by default 0.01.

kernelstr, optional

Kernel type for the KDE. Supported values depend on the backend, by default “gaussian”.

weightsarray-like, optional

Weights associated with the data points, shape (n_samples,).

scale_bystr or list, optional

Standardize each variable before KDE. Use “std” to scale by standard deviation, “range” for range normalization, or provide a list of scaling factors.

blocksint, optional

Number of data blocks to use for uncertainty estimation. Default is 1 (no error estimate).

fes_to_zeroint or tuple, optional

Index (or multi-index) in the grid where FES is shifted to zero. If None, minimum value is subtracted.

plotbool, optional

Whether to plot the FES (only for 1D or 2D).

plot_colorstr, optional

Color for 1D FES plot, default “fessa6”.

plot_max_fesfloat, optional

Maximum FES value to plot. Higher values will be masked.

plot_error_stylestr, optional

Style for plotting 1D uncertainty: “fill_between”, “errorbar”, or None.

plot_levelslist or int, optional

Contour levels for 2D FES plots. Passed to matplotlib.contourf.

axmatplotlib.axes.Axes, optional

Axis object to plot into. If None, a new figure is created.

backendstr, optional

Backend to use for KDE: “KDEpy” or “sklearn”. If None, use the best available.

epsfloat, optional

Regularization added to the KDE estimate before taking the log to avoid log(0). If None, auto-tuned.

Returns:

  • fes (ndarray) – Free energy surface evaluated on the grid. Shape is (num_samples,) in 1D and (num_samples, num_samples) in 2D.

  • grid (ndarray or list of ndarrays) – Grid coordinates corresponding to the FES values. A single array in 1D, list of arrays in 2D.

  • bounds (list of tuples) – Bounds used for each variable, after optional rescaling.

  • error (ndarray or None) – Standard error estimate from block averaging (only if blocks > 1). Same shape as fes.

Notes

  • The KDE can be computed using either KDEpy (recommended for speed in 2D) or scikit-learn. Use backend=”KDEpy” or backend=”sklearn” to specify.

  • Either temp or kbt must be provided (not both). If using temp, ensure fes_units is set correctly.

  • If scale_by is used, input variables are rescaled before KDE. This means that if using scale_by='range' a bandwidth of 0.01 corresponds to a 1/100 of the range of values assumed by the variable.

  • If blocks > 1, the function performs block averaging to estimate uncertainty [1].

  • The FES is computed on a regular grid; the grid ordering is consistent with numpy.meshgrid(…, indexing=’xy’), so no manual transpose is needed for plotting.

References

[1] Invernizzi, Piaggi, and Parrinello, Phys. Rev. X 10, 041034 (2020)

__init__(**kwargs)