3d Visualizations of optimization problems

docs/source/how_to/how_to_slice_plot_3d.ipynb

@@ -0,0 +1,342 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "0",
+   "metadata": {},
+   "source": [
+    "# Visualizing Objective Functions with `slice_plot_3d`\n",
+    "\n",
+    "In optimization, understanding the shape of your objective function is a key step toward choosing the right algorithm.\n",
+    "\n",
+    "This notebook introduces the `slice_plot_3d` tool, which provides flexible ways to visualize:\n",
+    "- Single-parameter sensitivity through **univariate slice plots**,\n",
+    "- Pairwise interactions through **contour** or **surface plots**,\n",
+    "- Full parameter relationships through **subplot grids**.\n",
+    "\n",
+    "We will progress from basic to advanced usage, learning how to create clean and insightful plots easily.\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1",
+   "metadata": {},
+   "source": [
+    "## Univariate slice Plot\n",
+    "\n",
+    "We start with a **univariate slice plot**.\n",
+    "This plots the function along each parameter individually to the function value,\n",
+    "while fixing others at their current values. This provides a clean view of how sensitive the function is to each parameter separately. We use the **Sphere function**, which sums the squares of each input.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import numpy as np\n",
+    "\n",
+    "import optimagic as om"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Define the Sphere function\n",
+    "def sphere(params):\n",
+    "    x = np.array(list(params.values()))\n",
+    "    return np.sum(x**2)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "params = {\"alpha\": 0, \"beta\": 0, \"gamma\": 0, \"delta\": 0}\n",
+    "bounds = om.Bounds(\n",
+    "    lower={name: -5 for name in params},\n",
+    "    upper={name: i + 2 for i, name in enumerate(params)},\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "5",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fig = om.sandbox.slice_plot_3d(\n",
+    "    func=sphere,\n",
+    "    params=params,\n",
+    "    bounds=bounds,\n",
+    ")\n",
+    "fig.show(renderer=\"png\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6",
+   "metadata": {},
+   "source": [
+    "## Univariate slice plot with selected parameters\n",
+    "\n",
+    "In many situations, we are interested in exploring only specific parameters.\n",
+    "Using the `selector` argument, we can restrict the univariate plots to\n",
+    "chosen parameters — here, we select `\"alpha\"` and `\"beta\"`.\n",
+    "\n",
+    "This focuses our visualization on dimensions of interest."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fig = om.sandbox.slice_plot_3d(\n",
+    "    func=sphere,\n",
+    "    params=params,\n",
+    "    bounds=bounds,\n",
+    "    selector=lambda p: [p[\"alpha\"], p[\"beta\"]],\n",
+    "    projection=\"univariate\",\n",
+    ")\n",
+    "fig.show(renderer=\"png\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8",
+   "metadata": {},
+   "source": [
+    "## 3D Surface Plot for Two Parameters\n",
+    "\n",
+    "To better understand interaction between parameters,\n",
+    "we can switch to a **3D surface plot**.\n",
+    "\n",
+    "Surface plots reveal valleys, ridges, and general landscape shapes clearly.\n",
+    "Here, we vary `\"alpha\"` and `\"beta\"` simultaneously and plot the resulting surface."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fig = om.sandbox.slice_plot_3d(\n",
+    "    func=sphere,\n",
+    "    params=params,\n",
+    "    bounds=bounds,\n",
+    "    selector=lambda p: [p[\"alpha\"], p[\"beta\"]],\n",
+    "    projection=\"surface\",\n",
+    "    n_gridpoints=30,\n",
+    ")\n",
+    "fig.show(renderer=\"png\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "10",
+   "metadata": {},
+   "source": [
+    "## 2D Contour Plot for Two Parameters\n",
+    "\n",
+    "Contour plots offer a 2D view with iso-function-value curves.\n",
+    "\n",
+    "They are especially useful for:\n",
+    "- Finding basins or valleys.\n",
+    "- Visualizing optimization paths.\n",
+    "- Detecting steep or flat regions easily.\n",
+    "\n",
+    "Again, we use `\"alpha\"` and `\"beta\"` to generate the plot."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "11",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fig = om.sandbox.slice_plot_3d(\n",
+    "    func=sphere,\n",
+    "    params=params,\n",
+    "    bounds=bounds,\n",
+    "    selector=lambda p: [p[\"alpha\"], p[\"beta\"]],\n",
+    "    projection=\"contour\",\n",
+    "    n_gridpoints=30,\n",
+    ")\n",
+    "fig.show(renderer=\"png\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "12",
+   "metadata": {},
+   "source": [
+    "## Grid View for Multiple Parameters\n",
+    "When selecting more than two parameters, the slice_plot_3d function automatically constructs a grid-based visualization to analyze both individual and pairwise parameter effects.\n",
+    "\n",
+    "- **Diagonal** cells display 1D univariate slice plots, representing the isolated\n",
+    "effect of each parameter on the function output.\n",
+    "- **Off-diagonal** cells visualize pairwise interactions between parameters using\n",
+    "either 3D surface or contour plots.\n",
+    "\n",
+    "\n",
+    "### Single projection type\n",
+    "##### (eg: `projection: \"surface\"`)\n",
+    "\n",
+    "By default, when a single projection type is specified (e.g., \"surface\" or \"contour\"), the following behavior is applied:\n",
+    "\n",
+    "- The **lower triangle** of the grid (i.e., plots below the diagonal) displays the\n",
+    "specified projection type.\n",
+    "- The **upper triangle** remains empty to avoid redundancy.\n",
+    "\n",
+    "This allows for a quick and uncluttered visualization of pairwise parameter interactions."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "13",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fig = om.sandbox.slice_plot_3d(\n",
+    "    func=sphere,\n",
+    "    params=params,\n",
+    "    bounds=bounds,\n",
+    "    projection=\"surface\",\n",
+    "    n_gridpoints=20,\n",
+    ")\n",
+    "fig.show(renderer=\"png\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "14",
+   "metadata": {},
+   "source": [
+    "### Multiple projection types\n",
+    "##### (eg: `projection: {\"lower\": \"surface\", \"upper\": \"contour\"}`)\n",
+    "\n",
+    "For enhanced flexibility, slice_plot_3d also supports customizing projection types independently for the upper and lower halves of the grid. This is done by passing a dictionary to the projection argument:\n",
+    "\n",
+    "- The **\"lower\"** key controls the projection type for plots below the diagonal.\n",
+    "- The **\"upper\"** key controls the projection type for plots above the diagonal.\n",
+    "\n",
+    "For example, setting \"lower\" to \"surface\" and \"upper\" to \"contour\" enables simultaneous display of both 3D and 2D representations, maximizing interpretability."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "15",
+   "metadata": {
+    "jupyter": {
+     "is_executing": true
+    }
+   },
+   "outputs": [],
+   "source": [
+    "fig = om.sandbox.slice_plot_3d(\n",
+    "    func=sphere,\n",
+    "    params=params,\n",
+    "    bounds=bounds,\n",
+    "    projection={\"lower\": \"surface\", \"upper\": \"contour\"},\n",
+    "    n_gridpoints=20,\n",
+    ")\n",
+    "fig.show(renderer=\"png\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "16",
+   "metadata": {},
+   "source": [
+    "This **dual-projection** layout is particularly useful when analyzing high-dimensional\n",
+    "functions, as it provides both detailed surface representations and compact contour visualizations in a single coherent grid."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "17",
+   "metadata": {},
+   "source": [
+    "## Full Customization of the Visualization\n",
+    "\n",
+    "`s‍lice_plot_3d` allows fine control over plot styling:\n",
+    "\n",
+    "- `layout_kwargs` adjusts figure size, titles, background themes.\n",
+    "- `plot_kwargs` controls color maps, marker options, and plot styles.\n",
+    "- `make_subplot_kwargs` configures grid spacing, axis sharing, and more.\n",
+    "\n",
+    "Here, we demonstrate a fully customized plot combining all these features."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "18",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fig = om.sandbox.slice_plot_3d(\n",
+    "    func=sphere,\n",
+    "    params=params,\n",
+    "    bounds=bounds,\n",
+    "    selector=lambda p: [p[\"alpha\"], p[\"beta\"], p[\"gamma\"]],\n",
+    "    projection=\"surface\",\n",
+    "    n_gridpoints=40,\n",
+    "    layout_kwargs={\n",
+    "        \"width\": 800,\n",
+    "        \"height\": 800,\n",
+    "        \"title\": {\"text\": \"Customized Sphere Function Visualization\"},\n",
+    "        \"template\": \"plotly_dark\",\n",
+    "    },\n",
+    "    make_subplot_kwargs={\n",
+    "        \"horizontal_spacing\": 0.1,\n",
+    "        \"vertical_spacing\": 0.1,\n",
+    "    },\n",
+    "    plot_kwargs={\n",
+    "        \"surface_plot\": {\"colorscale\": \"Viridis\", \"opacity\": 0.7},\n",
+    "    },\n",
+    ")\n",
+    "fig.show(renderer=\"png\")"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.17"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

src/optimagic/__init__.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from optimagic import constraints, mark, timing, utilities
+from optimagic import constraints, mark, sandbox, timing, utilities
 from optimagic.algorithms import algos
 from optimagic.benchmarking.benchmark_reports import (
     convergence_report,
@@ -103,4 +103,5 @@
     "__version__",
     "algos",
     "timing",
+    "sandbox",
 ]

src/optimagic/sandbox.py

@@ -0,0 +1,3 @@
+from optimagic.visualization.slice_plot_3d import slice_plot_3d
+
+__all__ = ["slice_plot_3d"]