.plot#

The .plot namespace provides visualization methods directly on test function instances via the func.plot.surface(), func.plot.contour() pattern.

PlotAccessor (built-in test functions)#

Accessor object returned by func.plot on built-in test functions.

class PlotAccessor(func: BaseTestFunction)[source]#

Bases: object

Namespace for plot methods on test functions.

Provides IDE-discoverable plotting methods with runtime validation based on the function’s dimensions and characteristics.

This class implements the Accessor Pattern (similar to pandas DataFrame.plot) to provide a clean namespace for visualization methods without polluting the test function’s interface.

Parameters:

func (BaseTestFunction) – The test function to visualize.

Examples

>>> from surfaces.test_functions import SphereFunction, AckleyFunction

# Basic usage - all defaults >>> func = AckleyFunction() # 2D function >>> fig = func.plot.surface() >>> fig = func.plot.contour()

# N-dimensional function with explicit dimensions >>> func = SphereFunction(n_dim=5) >>> fig = func.plot.surface(params={“x0”: …, “x2”: …})

# Custom ranges and fixed values >>> fig = func.plot.surface(params={ … “x0”: (-2, 2), … “x2”: (-1, 1), … “x1”: 0.0, … “x3”: 0.5, … “x4”: -1.0 … })

with_history(history: List[Dict[str, Any]]) → PlotAccessor[source]#

Attach optimization history for convergence plots.

Parameters:

history (list of dict) – List of evaluation records, each containing parameters and ‘score’.

Returns:

Self, for method chaining.

Return type:

PlotAccessor

Examples

>>> func = SphereFunction(n_dim=2)
>>> # ... run optimization, collect history ...
>>> fig = func.plot.with_history(history).convergence()
surface(params: Dict[str, Any] | None = None, resolution: int = 50, **kwargs: Any)[source]#

3D surface plot of the objective landscape.

Creates an interactive 3D surface visualization showing how the objective function value changes across two dimensions.

Parameters:

  • params (dict, optional) –

    Dimension configuration. For each dimension: - Tuple (min, max): Plot this dimension with given range - List/array: Plot this dimension with these values - range(): Plot with explicit discrete values - Single value: Fix this dimension at this value - Ellipsis (…): Plot with all defaults - Not specified: Fixed at default value

    Exactly 2 dimensions must have range/list/ellipsis values.

  • resolution (int, default=50) – Number of points per axis when using tuple ranges.

  • **kwargs – Additional arguments passed to the underlying plot function (e.g., colorscale, title).

Returns:

Interactive 3D surface plot.

Return type:

plotly.graph_objects.Figure

Raises:

ValueError – If not exactly 2 dimensions are configured for plotting.

Examples

>>> func = AckleyFunction()  # 2D
>>> fig = func.plot.surface()

>>> func = SphereFunction(n_dim=5)
>>> fig = func.plot.surface(params={"x0": ..., "x2": ...})
>>> fig = func.plot.surface(params={
...     "x0": (-2, 2),
...     "x2": (-1, 1),
...     "x1": 0.0
... })
contour(params: Dict[str, Any] | None = None, resolution: int = 50, **kwargs: Any)[source]#

2D contour plot with isolines of equal objective value.

Creates a 2D visualization with contour lines showing regions of equal objective function value.

Parameters:

  • params (dict, optional) – Dimension configuration. See surface() for details. Exactly 2 dimensions must be configured for plotting.

  • resolution (int, default=50) – Number of points per axis when using tuple ranges.

  • **kwargs – Additional arguments passed to the underlying plot function.

Returns:

Interactive contour plot.

Return type:

plotly.graph_objects.Figure

Examples

>>> func = AckleyFunction()
>>> fig = func.plot.contour()
>>> fig = func.plot.contour(params={"x0": (-2, 2), "x1": (-2, 2)})
heatmap(params: Dict[str, Any] | None = None, resolution: int = 50, **kwargs: Any)[source]#

2D heatmap showing objective values as colors.

Creates a color-coded grid visualization of objective function values.

Parameters:

  • params (dict, optional) – Dimension configuration. See surface() for details. Exactly 2 dimensions must be configured for plotting.

  • resolution (int, default=50) – Number of points per axis when using tuple ranges.

  • **kwargs – Additional arguments passed to the underlying plot function.

Returns:

Interactive heatmap plot.

Return type:

plotly.graph_objects.Figure

Examples

>>> func = AckleyFunction()
>>> fig = func.plot.heatmap()
multi_slice(params: Dict[str, Any] | None = None, resolution: int = 50, **kwargs: Any)[source]#

1D slices through each dimension.

Creates multiple 1D plots, one for each dimension, showing how the objective changes along that dimension while others are fixed.

Parameters:

  • params (dict, optional) –

    Dimension configuration. For slice plots: - Tuple (min, max): Range for this dimension’s slice - Single value: Fix this dimension (not shown in plots) - Ellipsis (…): Use defaults for this dimension

    All dimensions are sliced by default. To exclude a dimension from the plots, fix it with a single value.

  • resolution (int, default=50) – Number of points per slice.

  • **kwargs – Additional arguments passed to the underlying plot function.

Returns:

Figure with subplots for each dimension.

Return type:

plotly.graph_objects.Figure

Examples

>>> func = SphereFunction(n_dim=5)
>>> fig = func.plot.multi_slice()  # Shows all 5 dimensions
>>> fig = func.plot.multi_slice(params={"x0": (-2, 2)})  # Custom range for x0
>>> fig = func.plot.multi_slice(params={"x2": 0.0})  # Fix x2, show only 4 dims
fitness_distribution(params: Dict[str, Any] | None = None, n_samples: int = 1000, **kwargs: Any)[source]#

Histogram of objective values from random sampling.

Samples random points from the search space and shows the distribution of objective function values.

Parameters:

  • params (dict, optional) – Dimension configuration to restrict sampling region.

  • n_samples (int, default=1000) – Number of random samples to draw.

  • **kwargs – Additional arguments passed to the underlying plot function.

Returns:

Histogram of sampled objective values.

Return type:

plotly.graph_objects.Figure

Examples

>>> func = SphereFunction(n_dim=5)
>>> fig = func.plot.fitness_distribution()
convergence(history: List[Dict[str, Any]] | None = None, **kwargs: Any)[source]#

Best-so-far objective value vs evaluation number.

Shows optimization progress over time by plotting the best objective value found at each evaluation.

Parameters:

  • history (list of dict, optional) – Evaluation history. If not provided, uses history attached via with_history() or the function’s search_data.

  • **kwargs – Additional arguments passed to the underlying plot function.

Returns:

Line plot of convergence.

Return type:

plotly.graph_objects.Figure

Raises:

ValueError – If no history data is available.

Examples

>>> func = SphereFunction(n_dim=2)
>>> # After optimization:
>>> fig = func.plot.convergence()  # Uses func.search_data

>>> # Or with explicit history:
>>> fig = func.plot.convergence(history=my_history)

>>> # Or via chaining:
>>> fig = func.plot.with_history(my_history).convergence()
latex(params: Dict[str, Any] | None = None, output_path: str | None = None, **kwargs: Any)[source]#

Publication-quality LaTeX/PDF with pgfplots surface and formula.

Generates a LaTeX document with a 3D surface plot using pgfplots and the function’s mathematical formula.

Parameters:

  • params (dict, optional) – Dimension configuration. See surface() for details. Exactly 2 dimensions must be configured for plotting.

  • output_path (str, optional) – Path for the output PDF file.

  • **kwargs – Additional arguments passed to the underlying plot function.

Returns:

Path to the generated PDF file.

Return type:

str

Raises:

ValueError – If the function doesn’t have a latex_formula attribute. If not exactly 2 dimensions are configured for plotting.

Examples

>>> func = AckleyFunction()
>>> pdf_path = func.plot.latex()
>>> pdf_path = func.plot.latex(output_path="my_plot.pdf")
available() → List[str][source]#

List plot types available for this function.

Returns:

Names of plots compatible with this function.

Return type:

list of str

Examples

>>> func = SphereFunction(n_dim=2)
>>> func.plot.available()
['surface', 'contour', 'heatmap', 'multi_slice', 'fitness_distribution', 'latex']

>>> func = SphereFunction(n_dim=5)
>>> func.plot.available()
['multi_slice', 'fitness_distribution']

PlotNamespace (custom test functions)#

Accessor object returned by func.plot on CustomTestFunction.

class PlotNamespace(func: CustomTestFunction)[source]#

Bases: object

Visualization tools for optimization results.

This namespace provides methods for visualizing the optimization history, parameter importance, and optimization landscape.

Parameters:

func (CustomTestFunction) – The parent function to visualize.

Examples

>>> func.plot.history()
>>> func.plot.contour("x", "y")
>>> func.plot.importance()
history(show_best: bool = True, log_scale: bool = False, figsize: Tuple[int, int] = (10, 6), ax=None)[source]#

Plot optimization history.

Shows score values over evaluation number, optionally with running best overlay.

Parameters:

  • show_best (bool, default=True) – Show running best as overlay line.

  • log_scale (bool, default=False) – Use logarithmic scale for y-axis.

  • figsize (tuple, default=(10, 6)) – Figure size in inches.

  • ax (matplotlib.axes.Axes, optional) – Axes to plot on. Creates new figure if None.

Returns:

The axes with the plot.

Return type:

matplotlib.axes.Axes

Examples

>>> func.plot.history()
>>> func.plot.history(log_scale=True, show_best=True)
importance(method: str = 'variance', figsize: Tuple[int, int] = (8, 5), ax=None)[source]#

Plot parameter importance as bar chart.

Parameters:

  • method (str, default="variance") – Importance calculation method.

  • figsize (tuple, default=(8, 5)) – Figure size in inches.

  • ax (matplotlib.axes.Axes, optional) – Axes to plot on.

Returns:

The axes with the plot.

Return type:

matplotlib.axes.Axes

Examples

>>> func.plot.importance()
contour(param_x: str, param_y: str, resolution: int = 50, show_points: bool = True, show_best: bool = True, figsize: Tuple[int, int] = (10, 8), ax=None)[source]#

Plot 2D contour/heatmap of the optimization landscape.

Uses interpolation of collected data points to create a continuous surface visualization.

Parameters:

  • param_x (str) – Parameter name for x-axis.

  • param_y (str) – Parameter name for y-axis.

  • resolution (int, default=50) – Grid resolution for interpolation.

  • show_points (bool, default=True) – Show evaluation points as scatter.

  • show_best (bool, default=True) – Highlight the best point.

  • figsize (tuple, default=(10, 8)) – Figure size in inches.

  • ax (matplotlib.axes.Axes, optional) – Axes to plot on.

Returns:

The axes with the plot.

Return type:

matplotlib.axes.Axes

Examples

>>> func.plot.contour("learning_rate", "n_estimators")
parallel_coordinates(top_k: int | None = None, figsize: Tuple[int, int] = (12, 6), ax=None)[source]#

Plot parallel coordinates for high-dimensional visualization.

Parameters:

  • top_k (int, optional) – Only show top k evaluations. Shows all if None.

  • figsize (tuple, default=(12, 6)) – Figure size in inches.

  • ax (matplotlib.axes.Axes, optional) – Axes to plot on.

Returns:

The axes with the plot.

Return type:

matplotlib.axes.Axes

Examples

>>> func.plot.parallel_coordinates(top_k=50)