{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Tutorial 1: introduction to `BenchmarkFunction` class"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "nbsphinx": "hidden"
   },
   "outputs": [],
   "source": [
    "# Set Plotly to render plots as interactive in notebooks (this cell will be hidden: I set \"nbsphinx\": \"hidden\" in the cell metadata)\n",
    "import plotly.io as pio\n",
    "pio.renderers.default = \"notebook\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Benchmark functions are essential for testing optimization algorithms. In this tutorial, you'll learn how to use the `BenchmarkFunction` class, which provides\n",
    "a structured way to define and evaluate benchmark functions for optimization purposes.\n",
    "\n",
    "The `BenchmarkFunction` class allows you to:\n",
    "\n",
    "- Define a (multidimensional) function;\n",
    "- Specify bounds along each dimension;\n",
    "- Evaluate the function at specific points;\n",
    "- Retrieve the optimal value of the function."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As an example, we will consider the *Rastringin* function, which is a popular benchmark for optimization algorithms. It is known to be a multimodal function with many local minima, defined as follows:\n",
    "\n",
    "$$ f(\\mathbf{x}) = 10 \\cdot D + \\sum_{i=1}^{D} \\left( x_i^2 - 10 \\cdot \\cos(2 \\pi x_i) \\right) $$\n",
    "\n",
    "where $x_i \\in [-5.12, 5.12]$ and $D$ is the dimension of the problem.\n",
    "\n",
    "It has global minimum at $f(\\mathbf{x}^*) = 0$ for $\\mathbf{x}^* = (0, 0, \\ldots, 0)$."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A general `BenchmarkFunction` object should be initialized with:\n",
    "\n",
    "- A name for the function (optional);\n",
    "- The function itself (as a callable object);\n",
    "- The bounds for each variable (as a NumPy-array);\n",
    "- The optimal solution (as a NumPy-array)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's see how we can define the *Rastringin* function for $D=5$."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "from beeoptimal.benchmarks import BenchmarkFunction"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "D                = 5\n",
    "name             = f\"Rastringin-{D}d\"\n",
    "function         = lambda x: (10*len(x) + np.sum((x**2 - 10*np.cos(2*np.pi*x))))\n",
    "bounds           = np.array([[-5.12, 5.12]]*D)\n",
    "optimal_solution = np.zeros(D)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "Rastringin2dBenchmark = BenchmarkFunction(\n",
    "    name             = name,\n",
    "    fun              = function,\n",
    "    bounds           = bounds,\n",
    "    optimal_solution = optimal_solution\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "Benchmark:\n",
      " Rastringin-5d\n",
      "\n",
      "Default Bounds:\n",
      " [[-5.12  5.12]\n",
      " [-5.12  5.12]\n",
      " [-5.12  5.12]\n",
      " [-5.12  5.12]\n",
      " [-5.12  5.12]]\n",
      "\n",
      "Optimal Solution:\n",
      " [0. 0. 0. 0. 0.]\n",
      "\n",
      "Optimal Value:\n",
      " 0.0\n"
     ]
    }
   ],
   "source": [
    "print(f\"\\nBenchmark:\\n {Rastringin2dBenchmark.name}\")\n",
    "print(f\"\\nDefault Bounds:\\n {Rastringin2dBenchmark.bounds}\")\n",
    "print(f\"\\nOptimal Solution:\\n {Rastringin2dBenchmark.optimal_solution}\")\n",
    "print(f\"\\nOptimal Value:\\n {Rastringin2dBenchmark.optimal_value}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Given a new point $\\mathbf{x} \\in \\mathbb{R}^{5}$, the function can be evaluated as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Rastringin-5d function evaluated at point x=[ 0.10538191 -4.49508415 -3.52525349  5.09557108  3.70357909] --> f(x)=128.9333795057978\n"
     ]
    }
   ],
   "source": [
    "x   = np.random.uniform(low=Rastringin2dBenchmark.bounds[:,0], high=Rastringin2dBenchmark.bounds[:,1], size=D)\n",
    "f_x = Rastringin2dBenchmark.evaluate(x)\n",
    "\n",
    "print(f\"{Rastringin2dBenchmark.name} function evaluated at point x={x} --> f(x)={f_x}\")"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.12.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}