docs/_dev/in_dev__nomenclature_of_fokl_to_pyomo.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# FoKL-to-Pyomo\n",
    "\n",
    "```python\n",
    "from FoKL.fokl_to_pyomo import fokl_to_pyomo\n",
    "m = fokl_to_pyomo(...)\n",
    "```\n",
    "\n",
    "## Nomenclature\n",
    "\n",
    "The following is the automatically generated nomenclature, which is encountered when calling \n",
    "```python\n",
    "m.pprint()\n",
    "```\n",
    "\n",
    "### List of Pyomo Components\n",
    "\n",
    "\\# starts at 0, increasing for each new GP.\n",
    "\n",
    "| Set | Index | Description |\n",
    "|---|---|---|\n",
    "| GP#_scenarios | ```range(model.draws)``` | index of draw |\n",
    "| GP#_j |  | index of input variable (i.e., column index of ```model.inputs```) |\n",
    "| GP#_k | index of terms in FoKL equation |\n",
    "\n",
    "<br>\n",
    "\n",
    "| Var | Index | Description |\n",
    "|---|---|\n",
    "| *yvar* for *yvar* in *yvars* | output variables; one per GP |\n",
    "| *xvar* for *xvar* in *xvars* | input variables; truescale if corresponding ```truescale``` is True, else normalized (without '_normalized' appended) |\n",
    "| *xvars*_normalized | used in FoKL equation instead of *xvars* if corresponding ```truescale``` is ```True``` |\n",
    "| GP#_b | ```nmodel.betas``` |\n",
    "\n",
    "<br>\n",
    "\n",
    "| Constraint | Index | Description |\n",
    "|---|---|\n",
    "| GP#_normalize | indexed over GP#_j if corresponding ```truescale``` is ```True```; defines normalization equation according to ```model.minmax``` |\n",
    "| GP#_constr | indexed over GP#_scenarios; *yvars* == GP#_expr |\n",
    "\n",
    "<br>\n",
    "\n",
    "| Expression | Index | Description |\n",
    "|---|---|\n",
    "| GP#_basis | basis function |\n",
    "| GP#_expr | FoKL equation |"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "| Math | Definition |\n",
    "|---|---|\n",
    "|  |  |\n",
    "\n",
    "<br>\n",
    "\n",
    "| Component | Type | Index | Definition |\n",
    "|---|---|---|---|\n",
    "| GP#_b | Var | [GP#_scenarios, GP#_k] | $\\beta_{draw,k}$ |\n",
    "| GP#_k | Set | ```range(model.betas.shape[1])``` | term in FoKL equation (including beta0) |\n",
    "| \n",
    "\n",
    "\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Desired Pyomo values are:\n",
    "\n",
    "- GP#_mean\n",
    "- GP#_stdev"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "User provides:\n",
    "- ```xvars```\n",
    "- ```yvars```\n",
    "\n",
    "Pyomo creates:\n",
    "\n",
    "| Component | Type |\n",
    "|---|---|\n",
    "| ```GP#_{xvar}_norm for xvar in xvars[#]``` | ```pyo.Var()``` |\n",
    "| ```GP#_{yvars[#]}_draw``` | ```pyo.Var(draws)``` |\n",
    "| ```GP#_basis``` | ```pyo.Expression([n, j])``` |\n",
    "\n",
    "where\n",
    "- $n \\equiv$ order of basis function $\\mathcal{B}_{n+1}$\n",
    "- $j \\equiv$ index of input variable\n",
    " \n",
    "\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "## Method\n",
    "\n",
    "User provides:\n",
    "- ```xvars```\n",
    "- ```yvars```\n",
    "\n",
    "```python\n",
    "ig = 0  # index of GP; increases if GP already exists\n",
    "\n",
    "for im in range():  # index of model\n",
    "\n",
    "    while m.find_component(f\"GP{igp}_expr\") is not None:\n",
    "        igp += 1\n",
    "\n",
    "    m = add_gp_to_pyomo(m, igp, xvars[im], yvars[im])\n",
    "\n",
    "```\n"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}