examples/tutorials/aposmm_tutorial_notebook.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Parallel Optimization with APOSMM\n",
    "\n",
    "This tutorial demonstrates libEnsemble’s capability to identify multiple minima of simulation output using the built-in APOSMM (Asynchronously Parallel Optimization Solver for finding Multiple Minima) ``gen_f``. In this tutorial, we’ll create a simple simulation ``sim_f`` that defines a function with multiple minima, then write a libEnsemble calling script that imports APOSMM and parameterizes it to check for minima over a domain of outputs from our ``sim_f``.\n",
    "\n",
    "Besides libEnsemble and NumPy, SciPy is also a required dependency.\n",
    "\n",
    "## Six-Hump Camel Simulation Function\n",
    "\n",
    "Describing APOSMM’s operations is simpler with a given function on which to depict evaluations. We’ll use the Six-Hump Camel function, known to have six global minima. A sample space of this function, containing all minima, appears below:\n",
    "\n",
    "![6humpcamel](images/basic_6hc.png)\n",
    "\n",
    "*Note: The following ``sim_f`` won't operate stand-alone since it has not yet been parameterized and called by libEnsemble. The full routine should work as expected.*\n",
    "\n",
    "Create a new Python file named ``tutorial_six_hump_camel.py``. This will be our ``sim_f``, incorporating the above function. Write the following:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "\n",
    "def six_hump_camel(H, persis_info, sim_specs, _):\n",
    "    \"\"\"Six-Hump Camel sim_f.\"\"\"\n",
    "\n",
    "    batch = len(H['x'])                            # Num evaluations each sim_f call.\n",
    "    H_o = np.zeros(batch, dtype=sim_specs['out'])  # Define output array H\n",
    "\n",
    "    for i, x in enumerate(H['x']):\n",
    "        H_o['f'][i] = three_hump_camel_func(x)     # Function evaluations placed into H\n",
    "\n",
    "    return H_o, persis_info\n",
    "\n",
    "\n",
    "def six_hump_camel_func(x):\n",
    "    \"\"\" Six-Hump Camel function definition \"\"\"\n",
    "    x1 = x[0]\n",
    "    x2 = x[1]\n",
    "    term1 = (4-2.1*x1**2+(x1**4)/3) * x1**2\n",
    "    term2 = x1*x2\n",
    "    term3 = (-4+4*x2**2) * x2**2\n",
    "\n",
    "    return term1 + term2 + term3"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## APOSMM Operations\n",
    "\n",
    "APOSMM coordinates multiple local optimization runs starting from a collection of sample points. These local optimization runs occur in parallel, and can incorporate a variety of optimization methods, including from NLopt, PETSc/TAO, and SciPy. Some number of uniformly sampled points is returned by APOSMM for simulation evaluations before local optimization runs can occur, if no prior simulation evaluations are provided. User-requested sample points can also be provided to APOSMM:\n",
    "\n",
    "![6hcsampling](images/sampling_6hc.png)\n",
    "\n",
    "Specifically, APOSMM will begin local optimization runs from those points that don’t have better (more minimal) points nearby within a threshold ``r_k``. For the above example, after APOSMM has returned the uniformly sampled points, for simulation evaluations it will likely begin local optimization runs from the user-requested approximate minima. Providing these isn’t required, but can offer performance benefits.\n",
    "\n",
    "Each local optimization run chooses new points and determines if they’re better by passing them back to be evaluated by the simulation routine. If so, new local optimization runs are started from those points. This continues until each run converges to a minimum:\n",
    "\n",
    "![6hclocalopt](images/localopt_6hc.png)\n",
    "\n",
    "Throughout, generated and evaluated points are appended to the History array, with the field ``'local_pt'`` being ``True`` if the point is part of a local optimization run, and ``'local_min'`` being ``True`` if the point has been ruled a local minimum.\n",
    "\n",
    "## APOSMM Persistence\n",
    "\n",
    "The most recent version of APOSMM included with libEnsemble is referred to as Persistent APOSMM. Unlike most other user functions that are initiated and completed by workers multiple times based on allocation, a single worker process initiates APOSMM so that it “persists” and keeps running over the course of the entire libEnsemble routine. APOSMM begins it’s own parallel evaluations and communicates points back and forth with the manager, which are then given to workers and evaluated by simulation routines.\n",
    "\n",
    "In practice, since a single worker becomes “persistent” for APOSMM, users must ensure that enough workers or MPI ranks are initiated to support libEnsemble’s manager, a persistent worker to run APOSMM, and simulation routines. The following:\n",
    "\n",
    "    mpiexec -n 3 python my_aposmm_routine.py\n",
    "    \n",
    "results in only one worker process available to perform simulation routines.\n",
    "\n",
    "## Calling Script\n",
    "\n",
    "Create a new Python file named ``my_first_aposmm.py``. Start by importing NumPy, libEnsemble routines, APOSMM, our ``sim_f``, and a specialized allocation function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "\n",
    "from tutorial_six_hump_camel import six_hump_camel\n",
    "\n",
    "from libensemble.libE import libE\n",
    "from libensemble.gen_funcs.persistent_aposmm import aposmm\n",
    "from libensemble.alloc_funcs.persistent_aposmm_alloc import persistent_aposmm_alloc\n",
    "from libensemble.tools import parse_args, add_unique_random_streams"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This allocation function starts a single Persistent APOSMM routine and provides ``sim_f`` output for points requested by APOSMM. Points can be sampled points or points from local optimization runs.\n",
    "\n",
    "APOSMM supports a wide variety of external optimizers. The following statements set optimizer settings to ``'scipy'`` to indicate to APOSMM which optimization method to use, and help prevent unnecessary imports or package installations:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import libensemble.gen_funcs\n",
    "libensemble.gen_funcs.rc.aposmm_optimizers = 'scipy'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Set up ``nworkers``, ``libE_specs``, ``sim_specs``, ``gen_specs``, and ``alloc_specs``:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "nworkers = 4\n",
    "libE_specs = {'nworkers': 4, 'comms': 'local'}\n",
    "\n",
    "sim_specs = {'sim_f': six_hump_camel, # Simulation function\n",
    "             'in': ['x'],             # Accepts 'x' values\n",
    "             'out': [('f', float)]}   # Returns f(x) values\n",
    "\n",
    "gen_out = [('x', float, 2),           # Produces 'x' values\n",
    "           ('x_on_cube', float, 2),   # 'x' values scaled to unit cube\n",
    "           ('sim_id', int),           # Produces sim_id's for History array indexing\n",
    "           ('local_min', bool),       # Is a point a local minimum?\n",
    "           ('local_pt', bool)]        # Is a point from a local opt run?\n",
    "\n",
    "gen_specs = {'gen_f': aposmm,         # APOSMM generator function\n",
    "             'in': [],\n",
    "             'out': gen_out,          # Output defined like above dict\n",
    "             'user': {'initial_sample_size': 100,  # Random sample 100 points to start\n",
    "                      'localopt_method': 'scipy_Nelder-Mead',\n",
    "                      'opt_return_codes': [0],   # Return code specific to localopt_method\n",
    "                      'max_active_runs': 6,      # Occur in parallel\n",
    "                      'lb': np.array([-2, -1]),  # Lower bound of search domain\n",
    "                      'ub': np.array([2, 1])}    # Upper bound of search domain\n",
    "             }\n",
    "\n",
    "alloc_specs = {'alloc_f': persistent_aposmm_alloc,\n",
    "               'out': [('given_back', bool)], 'user': {}}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "``gen_specs['user']`` fields above that are required for APOSMM are:\n",
    "\n",
    "* ``'lb'`` - Search domain lower bound\n",
    "* ``'ub'`` - Search domain upper bound\n",
    "* ``'localopt_method'`` - Chosen local optimization method\n",
    "* ``'initial_sample_size'`` - Number of uniformly sampled points generated\n",
    "  before local optimization runs.\n",
    "* ``'opt_return_codes'`` - A list of integers that local optimization\n",
    "  methods return when a minimum is detected. SciPy's Nelder-Mead returns 0,\n",
    "  but other methods (not used in this tutorial) return 1.\n",
    "\n",
    "Also note the following:\n",
    "\n",
    "* ``gen_specs['in']`` is empty. For other ``gen_f``'s this defines what\n",
    "  fields to give to the ``gen_f`` when called, but here APOSMM's\n",
    "  ``alloc_f`` defines those fields.\n",
    "* ``'x_on_cube'`` in ``gen_specs['out']``. APOSMM works internally on\n",
    "  ``'x'`` values scaled to the unit cube. To avoid back-and-forth scaling\n",
    "  issues, both types of ``'x'``'s are communicated back, even though the\n",
    "  simulation will likely use ``'x'`` values. (APOSMM performs handshake to\n",
    "  ensure that the ``x_on_cube`` that was given to be evaluated is the same\n",
    "  the one that is given back.)\n",
    "* ``'sim_id'`` in ``gen_specs['out']``. APOSMM produces points in it's\n",
    "  local History array that it will need to update later, and can best\n",
    "  reference those points (and avoid a search) if APOSMM produces the IDs\n",
    "  itself, instead of libEnsemble.\n",
    "\n",
    "Other options and configurations can be found in the APOSMM [API reference](https://libensemble.readthedocs.io/en/master/examples/aposmm.html).\n",
    "\n",
    "Set ``exit_criteria`` so libEnsemble knows when to complete, and ``persis_info`` for random sampling seeding:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "exit_criteria = {'sim_max': 2000}\n",
    "persis_info = add_unique_random_streams({}, nworkers + 1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, add statements to initiate libEnsemble, and quickly check calculated minima:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria, persis_info,\n",
    "                            alloc_specs, libE_specs)\n",
    "\n",
    "print('Minima:', H[np.where(H['local_min'])]['x'])\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Output\n",
    "\n",
    "Please note that one worker will be “persistent” for APOSMM for the duration of the routine.\n",
    "\n",
    "After a couple seconds, the above output should resemble the following:\n",
    "\n",
    "    [0] libensemble.libE (MANAGER_WARNING):\n",
    "    *******************************************************************************\n",
    "    User generator script will be creating sim_id.\n",
    "    Take care to do this sequentially.\n",
    "    Also, any information given back for existing sim_id values will be overwritten!\n",
    "    So everything in gen_specs['out'] should be in gen_specs['in']!\n",
    "    *******************************************************************************\n",
    "\n",
    "\n",
    "    Minima: [[ 0.08993295 -0.71265804]\n",
    "     [ 1.70360676 -0.79614982]\n",
    "     [-1.70368421  0.79606073]\n",
    "     [-0.08988064  0.71270945]\n",
    "     [-1.60699361 -0.56859108]\n",
    "     [ 1.60713962  0.56869567]]\n",
    "     \n",
    "The first section labeled ``MANAGER_WARNING`` is a default libEnsemble warning for generator functions that create ``sim_id``’s, like APOSMM. It does not indicate a failure.\n",
    "\n",
    "The local minima for the Six-Hump Camel simulation function as evaluated by APOSMM with libEnsemble should be listed directly below the warning.\n",
    "\n",
    "Please see the [API reference](https://libensemble.readthedocs.io/en/master/examples/aposmm.html) for more APOSMM configuration options and other information.\n",
    "\n",
    "## Applications\n",
    "\n",
    "APOSMM is not limited to evaluating minima from pure Python simulation functions.\n",
    "Many common libEnsemble use-cases involve using libEnsemble's Executor to launch user\n",
    "applications with parameters requested by APOSMM, then evaluate their output using\n",
    "APOSMM, and repeat until minima are identified. A currently supported example\n",
    "can be found in libEnsemble's [WarpX Scaling Test](https://github.com/Libensemble/libensemble/tree/master/libensemble/tests/scaling_tests/warpx)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "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.6.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}