chemparseplot.plot.chemgp

Module Contents

Functions

_ensure_ruhi_cmap	Ensure the ruhi_diverging colormap is registered.
_setup	Common setup for matplotlib plots.
plot_convergence_curve	Log-scale convergence: oracle calls vs force, colored by method.
plot_rff_quality	Two-panel plot of energy and gradient MAE vs RFF dimension.
plot_hyperparameter_sensitivity	3x3 grid of 1D GP slices with confidence bands.
plot_trust_region	Trust region illustration with confidence band, boundary markers, and hypothetical bad step + oracle fallback.
plot_fps_projection	PCA scatter of FPS-selected (teal) vs pruned (grey) points.
plot_energy_profile	NEB energy profile: image index vs relative energy, colored by method.
plot_surface_contour	2D filled contour with optional path and point overlays.
plot_gp_progression	Faceted contour panels showing GP mean at different training sizes.
plot_nll_landscape	NLL contour in (log sigma^2, log theta) space.
plot_variance_overlay	Energy surface with hatched high-variance regions.
safe_plot	Decorator for graceful error handling in plot generation.
detect_clamp	Detect energy clamping preset from filename.
save_plot	Save a plotnine ggplot or matplotlib Figure to file.

Data

log
_METHOD_PALETTE
_JOST_THEME
_STROKE
_CLAMP_PRESETS

API

chemparseplot.plot.chemgp.log

‘getLogger(…)’

chemparseplot.plot.chemgp._METHOD_PALETTE

None

chemparseplot.plot.chemgp._JOST_THEME

None

chemparseplot.plot.chemgp._STROKE

None

chemparseplot.plot.chemgp._ensure_ruhi_cmap()

Ensure the ruhi_diverging colormap is registered.

chemparseplot.plot.chemgp._setup()

Common setup for matplotlib plots.

chemparseplot.plot.chemgp.plot_convergence_curve(df: pandas.DataFrame, x: str = 'oracle_calls', y: str = 'max_fatom', color: str = 'method', log_y: bool = True, conv_tol: float | dict | None = None, width: float = 3.2, height: float = 2.5) → plotnine.ggplot

Log-scale convergence: oracle calls vs force, colored by method.

Parameters

df : pandas.DataFrame Long-form table with at least columns x, y, and color. x : str Column for the horizontal axis (default "oracle_calls"). y : str Column for the vertical axis. Auto-selects LaTeX label for ci_force, max_fatom, max_force, force_norm. color : str Column used to color lines by method. log_y : bool Apply log10 scale to the y axis. conv_tol : float or dict or None Single float draws one horizontal line. Dict mapping method name to threshold draws per-method dashed lines in matching colors. width, height : float Figure size in inches.

Returns

plotnine.ggplot A ggplot object. Call .save() or assign to render.

Examples

import pandas as pd cols = {“oracle_calls”: [1, 2, 3], “max_fatom”: [1.0, 0.5, 0.1]} cols[“method”] = [“GP”] * 3 df = pd.DataFrame(cols) fig = plot_convergence_curve(df, conv_tol=0.2)

.. versionadded:: 1.4.0

chemparseplot.plot.chemgp.plot_rff_quality(df: pandas.DataFrame, exact_e_mae: float, exact_g_mae: float, width: float = 3.2, height: float = 2.5) → plotnine.ggplot

Two-panel plot of energy and gradient MAE vs RFF dimension.

Parameters

df : pandas.DataFrame Table with columns d_rff, energy_mae, gradient_mae. exact_e_mae : float Exact GP energy MAE baseline (drawn as dashed horizontal line). exact_g_mae : float Exact GP gradient MAE baseline. width, height : float Figure size in inches.

Returns

plotnine.ggplot Two-facet plot: Energy MAE and Gradient MAE vs D_rff.

Examples

import pandas as pd cols = {“d_rff”: [50, 100, 200], “energy_mae”: [0.5, 0.2, 0.1]} cols[“gradient_mae”] = [1.0, 0.4, 0.2] df = pd.DataFrame(cols) fig = plot_rff_quality(df, exact_e_mae=0.05, exact_g_mae=0.1)

.. versionadded:: 1.4.0

chemparseplot.plot.chemgp.plot_hyperparameter_sensitivity(x_slice: numpy.ndarray, y_true: numpy.ndarray, panels: dict[str, dict], width: float = 10.5, height: float = 9.0) → matplotlib.pyplot.Figure

3x3 grid of 1D GP slices with confidence bands.

Columns correspond to lengthscale values, rows to signal variance. Each panel shows the true surface (dashed), GP mean (teal), and a +/- 2 sigma confidence band (sky).

Parameters

x_slice : numpy.ndarray Shared x coordinates for all panels. y_true : numpy.ndarray True surface values at x_slice. panels : dict[str, dict] {"gp_ls1_sv1": {"E_pred": array, "E_std": array}, ...} for each of the 9 panels. Keys follow the pattern gp_ls{col}_sv{row} with col, row in 1..3. width, height : float Figure size in inches.

Returns

matplotlib.figure.Figure The 3x3 figure with a shared legend below the grid.

Examples

import numpy as np x = np.linspace(-2, 2, 50) panels = {“gp_ls1_sv1”: {“E_pred”: np.sin(x), “E_std”: np.full_like(x, 0.1)}} fig = plot_hyperparameter_sensitivity(x, np.sin(x), panels)

.. versionadded:: 1.4.0

chemparseplot.plot.chemgp.plot_trust_region(x_slice: numpy.ndarray, e_true: numpy.ndarray, e_pred: numpy.ndarray, e_std: numpy.ndarray, in_trust: numpy.ndarray, train_x: numpy.ndarray | None = None, width: float = 7.0, height: float = 5.0) → matplotlib.pyplot.Figure

Trust region illustration with confidence band, boundary markers, and hypothetical bad step + oracle fallback.

Shows the GP mean, +/- 2 sigma band, true surface, trust boundary (magenta dotted), a bad GP step (coral X) outside the trust region, and the oracle fallback (teal star) at the true energy.

Parameters

x_slice : numpy.ndarray X coordinates along the 1D slice. e_true : numpy.ndarray True energy values. e_pred : numpy.ndarray GP predicted energy values. e_std : numpy.ndarray GP standard deviation. in_trust : numpy.ndarray Boolean mask (1.0 for in trust, 0.0 for outside). train_x : numpy.ndarray or None X coordinates of training points (projected to true surface). width, height : float Figure size in inches.

Returns

matplotlib.figure.Figure Single-axis figure with trust region annotations.

Examples

import numpy as np x = np.linspace(-2, 2, 100) trust = (np.abs(x) < 1).astype(float) fig = plot_trust_region(x, np.sin(x), np.sin(x) * 0.9, np.full(100, 0.1), trust)

.. versionadded:: 1.4.0

chemparseplot.plot.chemgp.plot_fps_projection(selected_pc1, selected_pc2, pruned_pc1, pruned_pc2, width: float = 3.2, height: float = 2.5) → plotnine.ggplot

PCA scatter of FPS-selected (teal) vs pruned (grey) points.

Parameters

selected_pc1, selected_pc2 : array-like PCA coordinates of the selected (retained) subset. pruned_pc1, pruned_pc2 : array-like PCA coordinates of the pruned (discarded) points. width, height : float Figure size in inches.

Returns

plotnine.ggplot Scatter plot with two groups colored by selection status.

Examples

import numpy as np fig = plot_fps_projection([0, 1, 2], [0, 1, 0], [0.5, 1.5], [0.3, 0.8])

.. versionadded:: 1.4.0

chemparseplot.plot.chemgp.plot_energy_profile(df: pandas.DataFrame, x: str = 'image', y: str = 'energy', color: str = 'method', width: float = 3.2, height: float = 2.5) → plotnine.ggplot

NEB energy profile: image index vs relative energy, colored by method.

Parameters

df : pandas.DataFrame Long-form table with columns x, y, and color. x : str Column for horizontal axis (default "image"). y : str Column for vertical axis (default "energy"). color : str Column used to color lines by method. width, height : float Figure size in inches.

Returns

plotnine.ggplot Line + point plot of NEB energy profile.

Examples

import pandas as pd cols = {“image”: [0, 1, 2], “energy”: [0.0, 0.5, 0.0], “method”: [“NEB”] * 3} df = pd.DataFrame(cols) fig = plot_energy_profile(df)

.. versionadded:: 1.4.0

chemparseplot.plot.chemgp.plot_surface_contour(grid_x, grid_y, grid_z, paths: dict[str, tuple] | None = None, points: dict[str, tuple] | None = None, clamp_lo: float | None = None, clamp_hi: float | None = None, levels: int | numpy.ndarray | None = None, contour_step: float | None = None, _point_style: str = 'star', width: float = 7.0, height: float = 5.0) → matplotlib.pyplot.Figure

2D filled contour with optional path and point overlays.

Matches the Julia CairoMakie style: RUHI colormap, black contour lines, white NEB path, coral image circles, numbered images, sunshine star endpoints (or circle+label for minima/saddles).

Parameters

grid_x, grid_y, grid_z : array-like 2D meshgrid arrays for the surface. paths : dict or None {label: (xs, ys)} paths to overlay as lines. points : dict or None {label: (xs, ys)} scatter points to overlay. For “minima”/”saddles” keys, uses circle/x markers with labels. For “endpoints”, uses star markers. clamp_lo, clamp_hi : float or None Value clamping for z data. levels : int or array or None Explicit contour levels. If None, uses 25 levels over clamped range. contour_step : float or None Step size for black contour lines. If None, auto-computed. point_style : str Default point style: “star” or “labeled”. width, height : float Figure size in inches.

Returns

matplotlib.figure.Figure Contour figure with optional overlays.

Examples

import numpy as np x = np.linspace(-2, 2, 50) X, Y = np.meshgrid(x, x) Z = np.sin(X) * np.cos(Y) fig = plot_surface_contour(X, Y, Z, clamp_lo=-1, clamp_hi=1)

.. versionadded:: 1.4.0

chemparseplot.plot.chemgp.plot_gp_progression(grids: dict[int, dict], _true_energy, x_range, y_range, clamp_lo: float = -200.0, clamp_hi: float = 50.0, n_cols: int = 2, width: float = 10.0, height: float = 8.0) → matplotlib.pyplot.Figure

Faceted contour panels showing GP mean at different training sizes.

Matches Julia: clamped energy, RUHI colormap, black contour lines, training points as black dots.

Parameters

grids : dict {n_train: {"gp_mean": 2d_array, "train_x": array, "train_y": array}}. true_energy : array-like 2D array of the true energy surface. x_range, y_range : array-like 1D coordinate arrays for the grid. clamp_lo, clamp_hi : float Energy clamping range. n_cols : int Number of columns in the panel layout. width, height : float Figure size in inches.

Returns

matplotlib.figure.Figure Multi-panel contour figure with shared colorbar.

Examples

import numpy as np x = np.linspace(-2, 2, 40) X, Y = np.meshgrid(x, x) gp_mean = np.sin(X) * np.cos(Y) grids = {5: {“gp_mean”: gp_mean, “train_x”: [0, 1], “train_y”: [0, 1]}} fig = plot_gp_progression(grids, gp_mean, x, x)

.. versionadded:: 1.4.0

chemparseplot.plot.chemgp.plot_nll_landscape(grid_x, grid_y, grid_nll, grid_grad_norm=None, optimum: tuple[float, float] | None = None, width: float = 7.0, height: float = 5.0) → matplotlib.pyplot.Figure

NLL contour in (log sigma^2, log theta) space.

Matches Julia: reversed RUHI colormap (low NLL = warm), quantile-clipped, gradient norm dashed overlay.

Parameters

grid_x, grid_y : array-like 2D meshgrid of log sigma^2 and log theta values. grid_nll : array-like 2D array of NLL values. grid_grad_norm : array-like or None 2D array of gradient norm values (dashed contour overlay). optimum : tuple or None (log_sigma2, log_theta) of the MAP optimum to mark. width, height : float Figure size in inches.

Returns

matplotlib.figure.Figure NLL contour with optional gradient norm overlay and optimum marker.

Examples

import numpy as np x = np.linspace(-3, 3, 25) X, Y = np.meshgrid(x, x) nll = (X - 0.5)**2 + (Y + 1)**2 fig = plot_nll_landscape(X, Y, nll, optimum=(0.5, -1.0))

.. versionadded:: 1.4.0

chemparseplot.plot.chemgp.plot_variance_overlay(grid_x, grid_y, grid_energy, grid_variance, train_points: tuple | None = None, stationary: dict | None = None, clamp_lo: float = -200.0, clamp_hi: float = 50.0, width: float = 7.0, height: float = 5.0) → matplotlib.pyplot.Figure

Energy surface with hatched high-variance regions.

Matches Julia: clamped energy contourf as base, diagonal hatching for high-variance regions, magenta boundary contour, labeled stationary points.

Parameters

grid_x, grid_y : array-like 2D meshgrid arrays. grid_energy : array-like 2D array of energy values (shown as contourf). grid_variance : array-like 2D array of variance values (hatching + boundary). train_points : tuple or None (xs, ys) of training data locations. stationary : dict or None {"min0": (x,y), "saddle0": (x,y), ...} labeled stationary points. clamp_lo, clamp_hi : float Energy clamping range for display. width, height : float Figure size in inches.

Returns

matplotlib.figure.Figure Energy contour with hatched high-variance overlay and legend.

Examples

import numpy as np x = np.linspace(-2, 2, 40) X, Y = np.meshgrid(x, x) E = np.sin(X) * np.cos(Y) * 100 V = np.exp(-X2 - Y2) fig = plot_variance_overlay(X, Y, E, V, clamp_lo=-100, clamp_hi=50)

.. versionadded:: 1.4.0

chemparseplot.plot.chemgp.safe_plot(func)

Decorator for graceful error handling in plot generation.

Catches common errors and logs helpful messages.

chemparseplot.plot.chemgp._CLAMP_PRESETS

None

chemparseplot.plot.chemgp.detect_clamp(filename: str)

Detect energy clamping preset from filename.

Returns

tuple (clamp_lo, clamp_hi, contour_step) or (None, None, None)

chemparseplot.plot.chemgp.save_plot(fig, output, dpi=300)

Save a plotnine ggplot or matplotlib Figure to file.

Parameters

fig A matplotlib Figure or plotnine ggplot object. output : pathlib.Path Output file path. dpi : int Resolution in dots per inch.