.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.