`chemparseplot.plot.chemgp`¶

ChemGP visualization functions.

Mixed plotnine (for 1D line charts) and matplotlib (for 2D contour surfaces) plotting functions for GP-based optimization convergence, surfaces, and diagnostics.

Surface plots use matplotlib contourf with the RUHI colormap, matching the Julia CairoMakie originals. Line charts use plotnine for ggplot2 grammar.

Added in version 1.4.0.

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.

chemparseplot.plot.chemgp¶

Module Contents¶

Functions¶

Data¶

API¶

`chemparseplot.plot.chemgp`¶