docs/tutorials/import_export_optimization.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Import and Export of Optimization Problems\n",
    "\n",
    "This notebook demonstrates how an optimization problem setup in **MASSpy** can be exported for use with other optimization solvers. This notebook is based on the [Optlang API documentation](https://optlang.readthedocs.io/en/latest/) and the COBRApy FAQ [How do I generate an LP file from a COBRA model?](https://cobrapy.readthedocs.io/en/stable/faq.html#How-do-I-generate-an-LP-file-from-a-COBRA-model?) \n",
    "\n",
    "<div class=\"alert alert-info\"> \n",
    "Variables, constraints, objectives, and a name (if provided) are imported/exported through this method; however, solver configuration options are not.\n",
    "</div>\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:46.569535Z",
     "iopub.status.busy": "2020-10-20T20:35:46.568634Z",
     "iopub.status.idle": "2020-10-20T20:35:48.987327Z",
     "shell.execute_reply": "2020-10-20T20:35:48.987839Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "['cplex', 'glpk_exact', 'glpk', 'gurobi', 'scipy']\n"
     ]
    }
   ],
   "source": [
    "try:\n",
    "    import simplejson as json\n",
    "except ImportError:\n",
    "    import json\n",
    "    \n",
    "import cobra\n",
    "from optlang import Model as OptModel\n",
    "\n",
    "import mass.test\n",
    "# Print list of available solvers\n",
    "print(list(cobra.util.solver.solvers))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Using Optlang\n",
    "\n",
    "\n",
    "To facilitate the formation of the mathematical optimization problem, **MASSpy** utilizes the [Optlang python package](https://github.com/opencobra/optlang) <cite data-cite=\"JCS17\">(Jensen et al., 2017)</cite>. As stated in the [documentation](https://optlang.readthedocs.io/en/latest/):\n",
    "\n",
    "1. Optlang provides a common interface to a series of optimization tools, so different solver backends can be changed in a transparent way.\n",
    "2. Optlang takes advantage of the symbolic math library [SymPy](https://www.sympy.org) to allow objective functions and constraints to be easily formulated from symbolic expressions of variables. \n",
    "3. Optlang interfaces with all solvers through importable python modules ([read more here](https://optlang.readthedocs.io/en/latest/installation.html#solvers)).\n",
    "\n",
    "\n",
    "The following optimization solvers are supported:\n",
    "\n",
    "* [GLPK](http://www.gnu.org/software/glpk/>) (LP/MILP; via [swiglpk](https://github.com/biosustain/swiglpk>))\n",
    "* [CPLEX](http://www-01.ibm.com/software/commerce/optimization/cplex-optimizer/) (LP/MILP/QP)\n",
    "* [Gurobi](http://www.gurobi.com/) (LP/MILP/QP)\n",
    "\n",
    "However, there are times where it would be preferrable to utilize other solvers and/or change programming environments in the process of setting up and performing optimizations. Fortunately, **Optlang** provides class methods for importing and exporting the optimization problem in both LP and JSON-compatible formats. The examples below demonstrate how the JSON format is utilized with **MASSpy** objects to facilitate the transference of optimization problems.\n",
    "\n",
    "<div class=\"alert alert-warning\"> \n",
    "\n",
    "It is generally NOT recommended to import optimization problems directly into the solvers, as the corresponding <strong>MASSpy</strong> objects are bypassed and therefore do not have any values updated to match the new state of the solver.\n",
    "\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Importing and Exporting with LP files\n",
    "LP formulations of models can be used in conjunction with **Optlang** facilitate the exchange of optimization problems. \n",
    "Note the following:\n",
    "\n",
    "1. Importing and exporting using LP formulations can change variable and constraint identifiers\n",
    "2. LP formulations **do not** work with the ``scipy`` solver interface."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:49.074814Z",
     "iopub.status.busy": "2020-10-20T20:35:49.029696Z",
     "iopub.status.idle": "2020-10-20T20:35:49.147501Z",
     "shell.execute_reply": "2020-10-20T20:35:49.148026Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "-123 <= HEX1 <= 456\n"
     ]
    }
   ],
   "source": [
    "# Start with a fresh model\n",
    "model = mass.test.create_test_model(\"textbook\")\n",
    "# Change the bounds for demonstration purposes\n",
    "model.variables.HEX1.lb, model.variables.HEX1.ub = (-123, 456)\n",
    "print(model.variables[\"HEX1\"])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Exporting an LP file\n",
    "For all solver interfaces in **Optlang**, the ``str`` representation of an ``optlang.interface.Model`` is the LP formulation of the problem.\n",
    "\n",
    "To export the optimization problem into a file:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:49.152851Z",
     "iopub.status.busy": "2020-10-20T20:35:49.152132Z",
     "iopub.status.idle": "2020-10-20T20:35:49.159533Z",
     "shell.execute_reply": "2020-10-20T20:35:49.159046Z"
    }
   },
   "outputs": [],
   "source": [
    "with open(\"problem.lp\", \"w\") as file:\n",
    "    file.write(str(model.solver))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Alternatively, the ``optlang.interface.Model.to_lp()`` method can be used, but note that variable and constraint identifiers may be changed. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Importing an LP file\n",
    "The ``optlang.interface.Model.from_lp()`` method can be used to import an LP formulation of an optimization problem."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:49.165294Z",
     "iopub.status.busy": "2020-10-20T20:35:49.164513Z",
     "iopub.status.idle": "2020-10-20T20:35:49.290182Z",
     "shell.execute_reply": "2020-10-20T20:35:49.290628Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Before: 0 <= HEX1 <= 1000.0\n",
      "After: -123.0 <= HEX1 <= 456.0\n"
     ]
    }
   ],
   "source": [
    "# Use new model to demonstrate how bounds change\n",
    "model = mass.test.create_test_model(\"textbook\")\n",
    "print(\"Before: \" + str(model.variables[\"HEX1\"]))\n",
    "\n",
    "# Load problem from JSON file\n",
    "with open(\"problem.lp\") as file:\n",
    "    model._solver = OptModel.from_lp(file.read())\n",
    "print(\"After: \" + str(model.variables[\"HEX1\"]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Importing and Exporting with JSON files"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:49.378363Z",
     "iopub.status.busy": "2020-10-20T20:35:49.332276Z",
     "iopub.status.idle": "2020-10-20T20:35:49.398561Z",
     "shell.execute_reply": "2020-10-20T20:35:49.399083Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "-654 <= HEX1 <= 321\n"
     ]
    }
   ],
   "source": [
    "# Start with a fresh model\n",
    "model = mass.test.create_test_model(\"textbook\")\n",
    "# Change the bounds for demonstration purposes\n",
    "model.variables.HEX1.lb, model.variables.HEX1.ub = (-654, 321)\n",
    "print(model.variables.HEX1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Exporting using JSON"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Problems formulated in **Optlang** can be exported using the [optlang.interface.Model.to_json](https://optlang.readthedocs.io/en/latest/Model.html#optlang.interface.Model.to_json) class method. First, the ``to_json`` class method exports a JSON compatible ``dict`` containing the variables, constraints, objectives, and an optional name from the ``optlang.interface.Model``. The ``dict`` is then passed to [json.dump](https://docs.python.org/3.7/library/json.html#json.dump) to save the optimization problem as a JSON file.\n",
    "\n",
    "To export the optimization problem into a file:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:49.532660Z",
     "iopub.status.busy": "2020-10-20T20:35:49.514161Z",
     "iopub.status.idle": "2020-10-20T20:35:49.535794Z",
     "shell.execute_reply": "2020-10-20T20:35:49.536318Z"
    }
   },
   "outputs": [],
   "source": [
    "with open(\"problem.json\", \"w\") as file:\n",
    "    json.dump(model.solver.to_json(), file)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Importing using JSON\n",
    "Problems can be imported into **Optlang** using the [optlang.interface.Model.from_json](https://optlang.readthedocs.io/en/latest/Model.html#optlang.interface.Model.from_json) class method. First, a JSON compatible ``dict`` is loaded from a file using the [json.load](https://docs.python.org/3.7/library/json.html#json.load). The ``dict`` is then passed to the ``from_json`` class method to load the variables, constraints, objectives, and an optional name into the ``optlang.interface.Model`` (imported as \"OptModel\" in this example\").\n",
    "\n",
    "To import the optimization problem from a file:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:49.541805Z",
     "iopub.status.busy": "2020-10-20T20:35:49.540981Z",
     "iopub.status.idle": "2020-10-20T20:35:49.681989Z",
     "shell.execute_reply": "2020-10-20T20:35:49.682482Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Before: 0 <= HEX1 <= 1000.0\n",
      "After: -654 <= HEX1 <= 321\n"
     ]
    }
   ],
   "source": [
    "# Use new model to demonstrate how bounds change\n",
    "model = mass.test.create_test_model(\"textbook\")\n",
    "print(\"Before: \" + str(model.variables.HEX1))\n",
    "\n",
    "# Load problem from JSON file\n",
    "with open(\"problem.json\") as file:\n",
    "    model._solver = OptModel.from_json(json.load(file))\n",
    "print(\"After: \" + str(model.variables.HEX1))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Adding a solver interface\n",
    "\n",
    "For an optimization solver that does not currently have an interface, consider [adding a solver interface](https://optlang.readthedocs.io/en/stable/developers.html#add-solver-interface). "
   ]
  }
 ],
 "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.7.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}