{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# OPTaaS Constraints\n",
    "\n",
    "### <span style=\"color:red\">Note:</span> To run this notebook, you need an API Key. You can get one <a href=\"mailto:info@mindfoundry.ai\">here</a>.\n",
    "\n",
    "Constraints allow you to specify relationships between the parameters you want to optimize, or just constrain the values that a parameter can take. \n",
    "\n",
    "For example, you may want an optional parameter to always be enabled if another parameter is set to `TRUE`, or you may want an IntParameter to be between 0 and 10, but never 3.\n",
    "\n",
    "Each constraint is a string containing an expression written in a Javascript-like syntax, e.g. `'( #x >= #y ) || ( #x == 5 )'`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Referencing parameters\n",
    "Make sure you specify an `id` when creating a parameter that you want to use in a constraint. You can then reference it with a `#` followed by the id."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [],
   "source": [
    "library(optaas.client)\n",
    "\n",
    "x <- IntParameter(\"int_x\", id=\"x\", minimum=0, maximum=20)\n",
    "y <- IntParameter(\"int_y\", id=\"y\", minimum=0, maximum=20)\n",
    "\n",
    "x_smaller_than_y <- '#x < #y'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Numeric operators\n",
    "The following operators can be used in the same way as R: `< <= > >= == != + - * **`.\n",
    "\n",
    "`'( #x + #y ) == 25'`\n",
    "\n",
    "Don’t forget to leave a space between a parameter reference and an operator or bracket!\n",
    "\n",
    "Use `/` for division, `//` for integer (floor) division, and `%` for modulus.\n",
    "\n",
    "`'#y // 2 > #x'`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Logical operators\n",
    "Use `||` for `OR` and `&&` for `AND` (as in Javascript):\n",
    "\n",
    "`'#x < 3 || (#x > 5 && #y >= 7)'`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Conditional constraints\n",
    "You can use `if ... then ...` to define a conditional constraint:\n",
    "\n",
    "`'if #x < 3 then #y != 2'`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Optional parameters\n",
    "Use `is_present` and `is_absent` to create constraints based on whether an optional parameter is present in a configuration.\n",
    "\n",
    "Please note: if a parameter z is absent, for any value/expression X, `#z == X` will always evaluate to false and `#z != X` will always evaluate to true."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [],
   "source": [
    "z <- FloatParameter(\"float_z\", id=\"z\", minimum=0, maximum=1, optional=TRUE)\n",
    "\n",
    "z_larger_than_x <- 'if #z is_present then #z >= #x'\n",
    "z_absent <- 'if ( #x == 0 ) && ( #y == 0 ) then #z is_absent'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Choices\n",
    "You can use `is_present` and `is_absent` with parameters that are part of a choice."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [],
   "source": [
    "choice <- ChoiceParameter(\"choice_xy\", choices=list(x, y), id=\"xy\", default=y)\n",
    "\n",
    "if_x_present_then_z_is_small <- 'if #x is_present then #z < 0.1'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also use `==` and `!=` with choices:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "if_x_chosen_then_z_is_small <- 'if #xy == #x then #z < 0.4'\n",
    "if_z_big_then_x_not_chosen <- 'if #z > 0.9 then #xy != #x'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Categoricals\n",
    "You can use `==`, `!=`, `is_present` and `is_absent` with categoricals as well."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [],
   "source": [
    "abc <- CategoricalParameter('cat', values=list('a', 'b', 'c'), id='abc')\n",
    "\n",
    "if_b_then_x_is_0 <- 'if #abc == \"b\" then #x == 0'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Use them when creating a Task\n",
    "All generated configurations will obey the constraints."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[1] \"cat=a, choice_xy=list(int_y = 10), float_z=0.5\"\n",
      "[1] \"cat=a, choice_xy=list(int_y = 18), float_z=0.902627569044657\"\n",
      "[1] \"cat=c, choice_xy=list(int_y = 0), float_z=0.827720867024436\"\n",
      "[1] \"cat=c, choice_xy=list(int_x = 20), float_z=0.0222977344632128\"\n",
      "[1] \"cat=a, choice_xy=list(int_y = 15), float_z=0.188179531038473\"\n",
      "[1] \"cat=a, choice_xy=list(int_y = 5), float_z=0.181160629976\"\n",
      "[1] \"cat=a, choice_xy=list(int_x = 12), float_z=0.162485311634153\"\n",
      "[1] \"cat=c, choice_xy=list(int_x = 2), float_z=0.197240339464683\"\n",
      "[1] \"cat=a, choice_xy=list(int_y = 13), float_z=0.151935017118846\"\n",
      "[1] \"cat=c, choice_xy=list(int_y = 11), float_z=0.477303071059494\"\n",
      "[1] \"cat=a, choice_xy=list(int_x = 3), float_z=0.201273990324097\"\n",
      "[1] \"cat=a, choice_xy=list(int_x = 14), float_z=0.22243546751149\"\n",
      "[1] \"cat=c, choice_xy=list(int_y = 10), float_z=0.58467633766694\"\n",
      "[1] \"cat=a, choice_xy=list(int_y = 7), float_z=0.461023725568998\"\n",
      "[1] \"cat=c, choice_xy=list(int_x = 1), float_z=0.115643814806002\"\n",
      "[1] \"cat=b, choice_xy=list(int_x = 0), float_z=0.350506911704727\"\n",
      "[1] \"cat=a, choice_xy=list(int_y = 4), float_z=0.872235733126264\"\n",
      "[1] \"cat=a, choice_xy=list(int_y = 3), float_z=0.968979748575969\"\n",
      "[1] \"cat=c, choice_xy=list(int_y = 6), float_z=0.40612734790686\"\n",
      "[1] \"cat=c, choice_xy=list(int_x = 12), float_z=0.0341755517006327\"\n"
     ]
    }
   ],
   "source": [
    "client <- OPTaaSClient$new(\"https://optaas.mindfoundry.ai\", \"Your OPTaaS API Key\")\n",
    "\n",
    "task <- client$create_task(\n",
    "    title=\"My Task With Constraints\",\n",
    "    parameters=list(choice, z, abc),\n",
    "    constraints=list(\n",
    "        if_x_chosen_then_z_is_small,\n",
    "        if_z_big_then_x_not_chosen,\n",
    "        if_b_then_x_is_0\n",
    "    )\n",
    ")\n",
    "\n",
    "for (i in 1:20) {\n",
    "    config_values <- task$generate_configuration()$values\n",
    "    print(paste(names(config_values), config_values, sep = \"=\", collapse = \", \"))\n",
    "}"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "R",
   "language": "R",
   "name": "ir"
  },
  "language_info": {
   "codemirror_mode": "r",
   "file_extension": ".r",
   "mimetype": "text/x-r-source",
   "name": "R",
   "pygments_lexer": "r",
   "version": "3.4.1"
  },
  "nav_menu": {},
  "toc": {
   "navigate_menu": true,
   "number_sections": false,
   "sideBar": true,
   "threshold": 6,
   "toc_cell": false,
   "toc_section_display": "block",
   "toc_window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}