{
 "cells": [
  {
   "cell_type": "markdown",
   "source": [
    "This notebook may be found [here](https://github.com/nicolaipalm/paref/blob/main/docs/notebooks/getting_started.ipynb)."
   ],
   "metadata": {
    "collapsed": false
   },
   "id": "a1aefe0a1d477d96"
  },
  {
   "cell_type": "markdown",
   "source": [
    "## The blackbox function Interface"
   ],
   "metadata": {
    "collapsed": false
   },
   "id": "f16b40bf18c74b85"
  },
  {
   "cell_type": "markdown",
   "source": [
    "Prior to any MOO, the blackbox function needs to be implemented in Paref's ``BlackboxFunction`` interface. \n",
    "This always includes the following methods and properties:\n",
    "\n",
    "- ``__call__``: The blackbox function f relation of design (x) and target (f(x))\n",
    "- ``dimension_design_space`` property: The dimension of the design space\n",
    "- ``dimension_target_space`` property: The dimension of the target space\n",
    "- ``design_space`` property: The bounds of the design space (lowerbounds, upperbounds) as instance of the Bounds class\n",
    "\n",
    "Everything else, from storing each evaluation and calculating the Pareto front to saving and loading the evaluations, is handled by the Blackbox function interface."
   ],
   "metadata": {
    "collapsed": false
   },
   "id": "75073efb79cd5e9c"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "from paref.interfaces.moo_algorithms.blackbox_function import BlackboxFunction\n",
    "from paref.blackbox_functions.design_space.bounds import Bounds\n",
    "\n",
    "class TestBlackboxFunction(BlackboxFunction):  # Implement the blackbox function interface\n",
    "    def __call__(self, x) -> np.ndarray:\n",
    "        return np.array([x[0],x[0] ** 2 + x[1]])  # The blackbox function f relation of design (x) and target (f(x))\n",
    "\n",
    "    @property\n",
    "    def dimension_design_space(self) -> int:  # The dimension of the design space\n",
    "        return 2\n",
    "\n",
    "    @property\n",
    "    def dimension_target_space(self) -> int:  # The dimension of the target space\n",
    "        return 2\n",
    "\n",
    "    @property\n",
    "    def design_space(\n",
    "            self) -> Bounds:  # The bounds of the design space (lower bounds, upper bounds) as instance of the Bounds class\n",
    "        return Bounds(lower_bounds=-1 * np.ones(2), upper_bounds=np.ones(2))\n",
    "\n",
    "\n",
    "bbf = TestBlackboxFunction()  # Initialize the blackbox function"
   ],
   "metadata": {
    "collapsed": false
   },
   "id": "9fafd7c96a1e6cae"
  },
  {
   "cell_type": "markdown",
   "source": [
    "In our case, we can calculate the true Pareto front and we make use of that knowledge to visualize (and validate) our results:"
   ],
   "metadata": {
    "collapsed": false
   },
   "id": "68f0125bedceb68c"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "[bbf(np.array([i,-1])) for i in np.linspace(-1,0,100)]\n",
    "real_pf = bbf.y\n",
    "bbf.clear_evaluations()"
   ],
   "metadata": {
    "collapsed": false
   },
   "id": "5b11ac7fc242601e"
  },
  {
   "cell_type": "markdown",
   "source": [
    "## Exploring the target space"
   ],
   "metadata": {
    "collapsed": false
   },
   "id": "9a2260d3de3197d4"
  },
  {
   "cell_type": "markdown",
   "source": [
    "An initial exploration of the target space is almost always required prior to any MOO algorithm. The ``BlackboxFunction`` interface includes a (in some sense) optimal initial sampling: the Latin Hypercube Sampling (LHC). "
   ],
   "metadata": {
    "collapsed": false
   },
   "id": "3dc5be089e23c6e4"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "bbf.perform_lhc(n=20)  # Perform a latin hypercube sampling (i.e. exploration) of the target space with n=20 samples"
   ],
   "metadata": {
    "collapsed": false
   },
   "id": "31217b1ce673c16c"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "plt.plot(real_pf.T[0], real_pf.T[1], '--', label='real pareto front')\n",
    "plt.scatter(bbf.y.T[0], bbf.y.T[1], label='LHC samples')\n",
    "plt.legend()"
   ],
   "metadata": {
    "collapsed": false
   },
   "id": "321309856fae1464"
  },
  {
   "cell_type": "markdown",
   "source": [
    "The Pareto front of the evaluations (20 samples obtained by the LHC) can be accessed via the blackbox function's ``pareto_front`` property:"
   ],
   "metadata": {
    "collapsed": false,
    "ExecuteTime": {
     "end_time": "2024-02-24T14:55:02.390893Z",
     "start_time": "2024-02-24T14:54:58.468459Z"
    }
   },
   "id": "56acaeed73c49a7b"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "bbf.pareto_front"
   ],
   "metadata": {
    "collapsed": false
   },
   "id": "ccc37efb0ea16ba6"
  },
  {
   "cell_type": "markdown",
   "source": [
    "## Paref's Info class"
   ],
   "metadata": {
    "collapsed": false,
    "ExecuteTime": {
     "end_time": "2024-02-24T14:55:02.391023Z",
     "start_time": "2024-02-24T14:54:58.472224Z"
    }
   },
   "id": "dab50081f289b950"
  },
  {
   "cell_type": "markdown",
   "source": [
    "It is often helpful to have a look at (an estimate of) the Pareto front prior to any MOO algorithm in order to guide the search process. We are interested in the shape and dimension of the Pareto front, the minima in components and if the target space is explored sufficiently. Those information (and more) are provided by the ``Info`` class."
   ],
   "metadata": {
    "collapsed": false
   },
   "id": "c7202a1cf87c94db"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "from paref.express.info import Info\n",
    "\n",
    "info = Info(blackbox_function=bbf)"
   ],
   "metadata": {
    "collapsed": false
   },
   "id": "bad3a56012751200"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "info.suggestion_pareto_points"
   ],
   "metadata": {
    "collapsed": false
   },
   "id": "cc64d862bbe43ab0"
  },
  {
   "cell_type": "markdown",
   "source": [
    "## Paref Express"
   ],
   "metadata": {
    "collapsed": false,
    "ExecuteTime": {
     "start_time": "2024-02-24T14:54:58.476232Z"
    }
   },
   "id": "cee73ce83c9af48b"
  },
  {
   "cell_type": "markdown",
   "source": [
    "Paref provides a low level MOO class including the most frequently used MOO algorithms - Paref Express. \n",
    "For example, it provides a good initial algorithm for further more tailored MOO: The ``minimal_search`` algorithm.\n",
    " This MOO targets Pareto points which have the property of being 1. minimal in some component and 2. a best 'real' trade-off between the objectives. "
   ],
   "metadata": {
    "collapsed": false,
    "ExecuteTime": {
     "start_time": "2024-02-24T14:55:50.213935Z"
    }
   },
   "id": "38832336b445211"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "from paref.express.express_search import ExpressSearch\n",
    "\n",
    "moo = ExpressSearch(blackbox_function=bbf)  # Create an instance of the Paref Express class\n",
    "moo.minimal_search(max_evaluations=3)  # Perform the minimal search of the target space"
   ],
   "metadata": {
    "collapsed": false
   },
   "id": "d165c8f8fc06ac66"
  },
  {
   "cell_type": "markdown",
   "source": [
    "We access the so found Pareto points via the ``edge_points`` and ``max_point`` property:"
   ],
   "metadata": {
    "collapsed": false
   },
   "id": "a3d60b20fadaddb7"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "print(\"Pareto points minimal in some component: \\n\", moo.edge_points,\n",
    "      \"\\n Best real trade-off: \\n\", moo.max_point)"
   ],
   "metadata": {
    "collapsed": false
   },
   "id": "85de4d1d38792370"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "plt.plot(real_pf.T[0], real_pf.T[1], '--', label='real pareto front')\n",
    "plt.scatter(bbf.y.T[0], bbf.y.T[1], label='LHC samples')\n",
    "plt.scatter(moo.edge_points.T[0], moo.edge_points.T[1], label='edge points')\n",
    "plt.scatter(moo.max_point.T[0], moo.max_point.T[1], label='best real trade-off')\n",
    "plt.legend()"
   ],
   "metadata": {
    "collapsed": false
   },
   "id": "83e4f038d08732d8"
  },
  {
   "cell_type": "markdown",
   "source": [
    "From here, you can continue with more tailored MOO algorithms. Have a look at a [full use-case](./main_example.ipynb) of Paref or check out the other [MOO algorithms](../description/moo-algorithms.md)."
   ],
   "metadata": {
    "collapsed": false
   },
   "id": "ec4b00edfe493ef4"
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}