stochkin.fes¶

Free-energy surface loading, interpolation, and plotting.

stochkin.fes¶

Free-energy surface (FES) loading, interpolation, and plotting.

This module provides tools for working with free-energy surfaces obtained from enhanced-sampling simulations (e.g. PLUMED metadynamics or umbrella sampling).

Loading

load_plumed_fes_2d() / load_plumed_fes_1d() – read PLUMED-style .dat files into NumPy arrays.
load_plumed_scalar_field_2d() / load_diffusion_scalar_2d_from_plumed() – generic scalar-field loaders (e.g. position-dependent diffusion).

Interpolating potential objects

FESPotential – picklable 2D interpolating potential potential(x) -> (U, F) from a regular grid. Supports spline (SciPy RectBivariateSpline) and bilinear (pure NumPy) modes.
FESPotential1D – 1D analogue using numpy.interp + finite-difference forces.
make_fes_potential_from_grid() / make_fes_potential_from_plumed() – convenience constructors.

Plotting

plot_fes_colormap() – filled-contour colormap of a 2D FES.

stochkin.fes.load_plumed_fes_2d(filename, x_col=0, y_col=1, fes_col=2, subtract_min=True, verbose=True)[source]¶

Load a 2D free-energy surface from a PLUMED-style .dat file.

The file is expected to have at least three numeric columns (x, y, F(x,y)) with #-comment lines.

Parameters:

filename (str) – Path to the text file.
x_col (int) – Zero-based column indices.
y_col (int) – Zero-based column indices.
fes_col (int) – Zero-based column indices.
subtract_min (bool) – If True, shift so that \(\min F = 0\).
verbose (bool) – Print grid dimensions.

Returns:

x_grid, y_grid (ndarray) – Sorted 1D coordinate arrays.
fes_grid (ndarray, shape (nx, ny)) – Free-energy values on the regular grid (may contain NaN for incomplete grids).

stochkin.fes.load_plumed_scalar_field_2d(filename, x_col=0, y_col=1, field_col=2, verbose=True)[source]¶

Load a generic 2D scalar field f(x,y) from a PLUMED-style .dat file.

This is a thin wrapper around load_plumed_fes_2d that does NOT subtract the minimum and just renames the last column.

Parameters:

filename (str) – Path to the text file.
x_col (int) – Column indices (0-based) for x, y and f(x,y).
y_col (int) – Column indices (0-based) for x, y and f(x,y).
field_col (int) – Column indices (0-based) for x, y and f(x,y).
verbose (bool) – If True, prints basic info about the grid.

Returns:

x_grid, y_grid (1D arrays) – Grid coordinates.
field_grid (2D array, shape (nx, ny)) – Scalar field values on the (x_grid, y_grid) mesh.

stochkin.fes.load_diffusion_scalar_2d_from_plumed(filename, x_col=0, y_col=1, D_col=2, verbose=True)[source]¶

Convenience wrapper for a position-dependent scalar diffusion coefficient D(x,y) stored in a PLUMED-like table.

Parameters:

filename (str) – Path to the text file.
x_col (int) – Column indices (0-based) for x, y and D(x,y).
y_col (int) – Column indices (0-based) for x, y and D(x,y).
D_col (int) – Column indices (0-based) for x, y and D(x,y).
verbose (bool) – If True, prints basic info about the grid.

Returns:

x_grid, y_grid (1D arrays)
D_grid (2D array, shape (nx, ny))

stochkin.fes.load_plumed_fes_1d(filename, x_col=0, fes_col=1, subtract_min=True, verbose=True)[source]¶

Load a 1D free energy surface from a PLUMED-style .dat file.

Assumes at least two numeric columns (x, F(x)) and that lines starting with '#' are comments.

Parameters:

filename (str or path-like) – Path to the PLUMED .dat file.
x_col (int) – Column index for the coordinate (default 0).
fes_col (int) – Column index for the free energy (default 1).
subtract_min (bool) – If True, shift so the global minimum is zero.
verbose (bool) – Print a summary after loading.

Returns:

x_grid (ndarray, shape (n,)) – Sorted coordinate values.
fes_grid (ndarray, shape (n,)) – Corresponding free-energy values.

class stochkin.fes.FESPotential(x_grid, y_grid, fes_grid, method='spline', kx=3, ky=3, s=0.0, extrapolate=False, auto_bilinear_npoints=100000, uniform_tol=1e-10)[source]¶

Bases: object

Picklable 2D free-energy-surface potential.

Given a regular (x_grid, y_grid, fes_grid) mesh, this class builds an interpolating potential callable:

U, F = potential(np.array([x, y]))

where F = −∇U is the 2D force vector.

Two interpolation back-ends are supported:

``’spline’`` – scipy.interpolate.RectBivariateSpline (high accuracy, requires SciPy).
``’bilinear’`` – pure-NumPy bilinear interpolation with pre-computed gradient grids (faster for large grids, no SciPy needed).
``’auto’`` (default) – selects spline for small grids and bilinear for grids with ≥ auto_bilinear_npoints points.

The object is designed to be picklable for multiprocessing: the SciPy spline is dropped during pickle and rebuilt on unpickle.

Parameters:

x_grid (array_like) – Sorted 1D coordinate arrays.
y_grid (array_like) – Sorted 1D coordinate arrays.
fes_grid (array_like, shape (len(x_grid), len(y_grid))) – Free-energy values on the regular mesh.
method ({'spline', 'bilinear', 'auto'}) – Interpolation back-end.
kx (int) – Spline degrees (default 3).
ky (int) – Spline degrees (default 3).
s (float) – Spline smoothing factor (default 0).
extrapolate (bool) – If False (default), positions outside the grid are clamped.
auto_bilinear_npoints (int) – Grid-size threshold for the 'auto' selector.
uniform_tol (float) – Tolerance for detecting uniform grid spacing.

evaluate_U_on_grid(xs, ys)[source]¶

Evaluate U(x,y) on a tensor-product grid (vectorized).

This avoids calling __call__ in Python loops and is used to speed up basin detection / coarse scans.

Parameters:

xs (array_like) – 1D coordinate arrays.
ys (array_like) – 1D coordinate arrays.

Returns:

Return type:

ndarray, shape (len(xs), len(ys))

coarse_subsample(nx, ny, xlim=None, ylim=None)[source]¶

Fast coarse subsampling of the underlying grid (no interpolation).

Useful for basin detection where you only need U on a coarse grid.

Returns:: xs, ys, U – xs has length nx, ys has length ny, U shape (nx, ny).
Return type:: (ndarray, ndarray, ndarray)

plot(levels=50, cmap='viridis', title=None)[source]¶: Plot the underlying FES grid as a colormap.

plot_interpolated(nx=200, ny=200, levels=50, cmap='viridis', title=None)[source]¶

class stochkin.fes.FESPotential1D(x_grid, fes_grid)[source]¶

Bases: object

Picklable 1D free-energy-surface potential.

Interpolates U(x) via numpy.interp and computes the force \(F = -dU/dx\) via a symmetric finite-difference stencil.

The callable interface is compatible with the BAOAB integrator:

U, F = potential(np.array([x]))   # F.shape == (1,)

Parameters:

x_grid (array_like) – Strictly increasing 1D coordinate array.
fes_grid (array_like) – Free-energy values (same shape as x_grid).

plot(ax=None, xlabel='x', ylabel='F(x)', title='1D FES')[source]¶: Quick 1D line plot of the underlying FES.

stochkin.fes.make_fes_potential_from_grid(x_grid, y_grid, fes_grid, method='auto', kx=3, ky=3, s=0.0, extrapolate=False)[source]¶

Build a picklable FESPotential from grid arrays.

Parameters:

x_grid (array_like) – 1D coordinate arrays.
y_grid (array_like) – 1D coordinate arrays.
fes_grid (array_like, shape (nx, ny)) – Free-energy values.
method ({'spline', 'bilinear', 'auto'}) – Interpolation back-end.
kx (int) – Spline degrees.
ky (int) – Spline degrees.
s (float) – Smoothing.
extrapolate (bool) – Allow extrapolation outside the grid.

Return type:

FESPotential

stochkin.fes.make_fes_potential_from_plumed(filename, x_col=0, y_col=1, fes_col=2, subtract_min=True, method='auto', kx=3, ky=3, s=0.0, extrapolate=False, verbose=True, plot=True, plot_nx=200, plot_ny=200, plot_levels=50, cmap='viridis')[source]¶

Build a FESPotential directly from a PLUMED FES file.

Combines load_plumed_fes_2d() and make_fes_potential_from_grid() in a single call. Optionally plots the interpolated FES on a refined grid.

Parameters:

filename (str) – Path to the PLUMED .dat file.
x_col (int) – Column indices.
y_col (int) – Column indices.
fes_col (int) – Column indices.
subtract_min (bool) – Shift FES minimum to zero.
method (str) – Interpolation back-end.
kx (int) – Spline degrees.
ky (int) – Spline degrees.
s (float) – Smoothing.
extrapolate (bool) – Allow extrapolation.
verbose (bool) – Print grid info.
plot (bool) – Show a diagnostic colormap.
plot_nx (int) – Refined grid size for plotting.
plot_ny (int) – Refined grid size for plotting.
plot_levels (int) – Contour levels.
cmap (str) – Matplotlib colormap.

Return type:

FESPotential

stochkin.fes.make_fes_potential_from_plumed_1d(filename, x_col=0, fes_col=1, subtract_min=True, verbose=True)[source]¶

Build a FESPotential1D from a PLUMED 1D FES file.

Parameters:

filename (str) – Path to the PLUMED .dat file.
x_col (int) – Column indices.
fes_col (int) – Column indices.
subtract_min (bool) – Shift FES minimum to zero.
verbose (bool) – Print grid info.

Return type:

FESPotential1D

stochkin.fes.plot_fes_colormap(x_grid, y_grid, fes_grid, levels=50, cmap='viridis', title=None)[source]¶

Plot a 2D FES as a filled-contour colormap.

Parameters:

x_grid (array_like) – 1D coordinate arrays.
y_grid (array_like) – 1D coordinate arrays.
fes_grid (array_like, shape (nx, ny)) – Free-energy values (NaNs are masked).
levels (int) – Number of contour levels.
cmap (str) – Matplotlib colormap name.
title (str or None) – Figure title.