docs/tutorials/global_configuration.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Global Configuration\n",
    "\n",
    "This notebook example demonstrates how the global configuration object, the `MassConfiguration`, is used to configure the default behaviors for various **COBRApy** and **MASSpy** methods."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-01-25T18:42:41.468260Z",
     "iopub.status.busy": "2021-01-25T18:42:41.467334Z",
     "iopub.status.idle": "2021-01-25T18:42:43.936077Z",
     "shell.execute_reply": "2021-01-25T18:42:43.936763Z"
    }
   },
   "outputs": [],
   "source": [
    "import cobra\n",
    "\n",
    "import mass\n",
    "from mass.example_data import create_example_model\n",
    "\n",
    "cobra_config = cobra.Configuration()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that changing the global configuration values is the most useful at the beginning of a work session."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The MassConfiguration Object\n",
    "\n",
    "Similar to the `cobra.Configuration` object, the `MassConfiguration` object is a [singleton](https://en.wikipedia.org/wiki/Singleton_pattern), meaning that only one instance can exist and is respected everywhere in **MASSpy**. \n",
    "\n",
    "The `MassConfiguration` is retrieved via the following:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-01-25T18:42:43.941222Z",
     "iopub.status.busy": "2021-01-25T18:42:43.940567Z",
     "iopub.status.idle": "2021-01-25T18:42:43.942719Z",
     "shell.execute_reply": "2021-01-25T18:42:43.943189Z"
    }
   },
   "outputs": [],
   "source": [
    "mass_config = mass.MassConfiguration()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `MassConfiguration` is synchronized with the `cobra.Configuration` singleton object such that a change in one configuration object affects the other."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-01-25T18:42:43.948958Z",
     "iopub.status.busy": "2021-01-25T18:42:43.947679Z",
     "iopub.status.idle": "2021-01-25T18:42:43.952272Z",
     "shell.execute_reply": "2021-01-25T18:42:43.952781Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "cobra configuration before: (-1000.0, 1000.0)\n",
      "cobra configuration after: (-444, 444)\n"
     ]
    }
   ],
   "source": [
    "print(\"cobra configuration before: {0!r}\".format(cobra_config.bounds))\n",
    "# Change bounds using the MassConfiguration object\n",
    "mass_config.bounds = (-444, 444)\n",
    "print(\"cobra configuration after: {0!r}\".format(cobra_config.bounds))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This means that changes only need to be made to the `MassConfiguration` object for workflows that involve both the **COBRApy** and **MASSpy** packages. The shared configuration attributes can be viewed using the `MassConfiguration.shared_state` attribute."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-01-25T18:42:43.959785Z",
     "iopub.status.busy": "2021-01-25T18:42:43.958895Z",
     "iopub.status.idle": "2021-01-25T18:42:43.962139Z",
     "shell.execute_reply": "2021-01-25T18:42:43.962585Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['solver',\n",
       " 'tolerance',\n",
       " 'lower_bound',\n",
       " 'upper_bound',\n",
       " 'processes',\n",
       " 'cache_directory',\n",
       " 'max_cache_size',\n",
       " 'cache_expiration']"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "list(mass_config.shared_state)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Attributes for Model Construction\n",
    "\n",
    "The following attributes of the `MassConfiguration` alter default behaviors for constructing models and importing/exporting models via [SBML](http://sbml.org/Main_Page)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-01-25T18:42:43.966756Z",
     "iopub.status.busy": "2021-01-25T18:42:43.966118Z",
     "iopub.status.idle": "2021-01-25T18:42:43.968189Z",
     "shell.execute_reply": "2021-01-25T18:42:43.968988Z"
    }
   },
   "outputs": [],
   "source": [
    "from mass import MassMetabolite, MassReaction"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### For irreversible reactions\n",
    "\n",
    "When an irreversible reaction is created, the equilibrium constant and reverse rate constant are automatically set based on the `irreversible_Keq` and `irreversible_kr` attributes, respectively."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-01-25T18:42:43.978455Z",
     "iopub.status.busy": "2021-01-25T18:42:43.977433Z",
     "iopub.status.idle": "2021-01-25T18:42:43.988418Z",
     "shell.execute_reply": "2021-01-25T18:42:43.989805Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Irreversible Keq: inf\n",
      "Irreversible kr: 0\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "{'Keq_R1': inf, 'kr_R1': 0}"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mass_config.irreversible_Keq = float(\"inf\")\n",
    "mass_config.irreversible_kr = 0\n",
    "\n",
    "print(\"Irreversible Keq: {0}\".format(mass_config.irreversible_Keq))\n",
    "print(\"Irreversible kr: {0}\".format(mass_config.irreversible_kr))\n",
    "R1 = MassReaction(\"R1\", reversible=False)\n",
    "R1.parameters"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Changing the `irreversible_Keq` and `irreversible_kr` attributes affects newly created `MassReaction` objects."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-01-25T18:42:44.000684Z",
     "iopub.status.busy": "2021-01-25T18:42:43.999681Z",
     "iopub.status.idle": "2021-01-25T18:42:44.006020Z",
     "shell.execute_reply": "2021-01-25T18:42:44.006817Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Irreversible Keq: 10000000.0\n",
      "Irreversible kr: 1e-06\n",
      "\n",
      "{'Keq_R2': 10000000.0, 'kr_R2': 1e-06}\n"
     ]
    }
   ],
   "source": [
    "mass_config.irreversible_Keq = 10e6\n",
    "mass_config.irreversible_kr = 1e-6\n",
    "print(\"Irreversible Keq: {0}\".format(mass_config.irreversible_Keq))\n",
    "print(\"Irreversible kr: {0}\\n\".format(mass_config.irreversible_kr))\n",
    "\n",
    "# Create new reaction\n",
    "R2 = MassReaction(\"R2\", reversible=False)\n",
    "print(R2.parameters)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Existing reactions are not affected."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-01-25T18:42:44.012303Z",
     "iopub.status.busy": "2021-01-25T18:42:44.011133Z",
     "iopub.status.idle": "2021-01-25T18:42:44.014828Z",
     "shell.execute_reply": "2021-01-25T18:42:44.015515Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'Keq_R1': inf, 'kr_R1': 0}\n"
     ]
    }
   ],
   "source": [
    "print(R1.parameters)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### For rate expressions\n",
    "\n",
    "Automatic generation of rate expressions are affected using the `exclude_metabolites_from_rates` and `exclude_compartment_volumes_in_rates` attributes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-01-25T18:42:44.096404Z",
     "iopub.status.busy": "2021-01-25T18:42:44.059150Z",
     "iopub.status.idle": "2021-01-25T18:42:44.212086Z",
     "shell.execute_reply": "2021-01-25T18:42:44.212560Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Set parameter Username\n"
     ]
    }
   ],
   "source": [
    "model = create_example_model(\"textbook\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Excluding metabolites from rates\n",
    "\n",
    "The `exclude_metabolites_from_rates` attribute determines which metabolites to exclude from rate expressions by using a dictionary that contains a metabolite attribute for filtering, and a list of values to be excluded."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-01-25T18:42:44.217915Z",
     "iopub.status.busy": "2021-01-25T18:42:44.216568Z",
     "iopub.status.idle": "2021-01-25T18:42:44.221630Z",
     "shell.execute_reply": "2021-01-25T18:42:44.222149Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'elements': [{'H': 2, 'O': 1}, {'H': 1}]}"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mass_config.exclude_metabolites_from_rates"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The default setting utilizes the `MassMetabolite.elements` attribute for filtering, excluding any metabolite that returns the elements for hydrogen and water."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-01-25T18:42:44.236147Z",
     "iopub.status.busy": "2021-01-25T18:42:44.235388Z",
     "iopub.status.idle": "2021-01-25T18:42:44.238046Z",
     "shell.execute_reply": "2021-01-25T18:42:44.238553Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "kf_ENO*(_2pg_c(t) - pep_c(t)/Keq_ENO)\n"
     ]
    }
   ],
   "source": [
    "ENO = model.reactions.get_by_id(\"ENO\")\n",
    "print(ENO.rate)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `exclude_metabolites_from_rates` attribute can be changed by providing a `dict` that contains a metabolite attribute for filtering and the list of values to be excluded. For example, to exclude \"2pg_c\" by using its `name` attribute as the criteria for exclusion:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-01-25T18:42:44.248500Z",
     "iopub.status.busy": "2021-01-25T18:42:44.247810Z",
     "iopub.status.idle": "2021-01-25T18:42:44.250404Z",
     "shell.execute_reply": "2021-01-25T18:42:44.250891Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "kf_ENO*(1 - h2o_c(t)*pep_c(t)/Keq_ENO)\n"
     ]
    }
   ],
   "source": [
    "mass_config.exclude_metabolites_from_rates = {\"name\": [\"D-Glycerate 2-phosphate\"]}\n",
    "ENO = model.reactions.get_by_id(\"ENO\")\n",
    "print(ENO.rate)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Or, to exclude hydrogen and water by using their identifiers:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-01-25T18:42:44.259507Z",
     "iopub.status.busy": "2021-01-25T18:42:44.258730Z",
     "iopub.status.idle": "2021-01-25T18:42:44.261573Z",
     "shell.execute_reply": "2021-01-25T18:42:44.262058Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "kf_ENO*(_2pg_c(t) - pep_c(t)/Keq_ENO)\n"
     ]
    }
   ],
   "source": [
    "mass_config.exclude_metabolites_from_rates = {\"id\": [\"h_c\", \"h2o_c\"]}\n",
    "ENO = model.reactions.get_by_id(\"ENO\")\n",
    "print(ENO.rate)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Boundary reactions are unaffected by the `exclude_metabolites_from_rates` attribute:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-01-25T18:42:44.282236Z",
     "iopub.status.busy": "2021-01-25T18:42:44.281498Z",
     "iopub.status.idle": "2021-01-25T18:42:44.284173Z",
     "shell.execute_reply": "2021-01-25T18:42:44.284725Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "kf_SK_h_c*(h_c(t) - h_b/Keq_SK_h_c)\n",
      "kf_SK_h2o_c*(h2o_c(t) - h2o_b/Keq_SK_h2o_c)\n"
     ]
    }
   ],
   "source": [
    "for rid in [\"SK_h_c\", \"SK_h2o_c\"]:\n",
    "    reaction = model.reactions.get_by_id(rid)\n",
    "    print(reaction.rate)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Excluding compartments from rates\n",
    "\n",
    "The `exclude_compartment_volumes_in_rates` attribute determines whether compartment volumes are factored into rate expressions. By default, compartment volumes are not included in automatically generated rate expressions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-01-25T18:42:44.296580Z",
     "iopub.status.busy": "2021-01-25T18:42:44.295685Z",
     "iopub.status.idle": "2021-01-25T18:42:44.298617Z",
     "shell.execute_reply": "2021-01-25T18:42:44.299082Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "kf_PGI*(g6p_c(t) - f6p_c(t)/Keq_PGI)\n"
     ]
    }
   ],
   "source": [
    "PGI = model.reactions.get_by_id(\"PGI\")\n",
    "print(PGI.rate)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When the `exclude_compartment_volumes_in_rates` attribute is set as `False`, compartments are included in rate expressions as `volume_CID`, with `CID` referring to the compartment identifier. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-01-25T18:42:44.312610Z",
     "iopub.status.busy": "2021-01-25T18:42:44.311866Z",
     "iopub.status.idle": "2021-01-25T18:42:44.314478Z",
     "shell.execute_reply": "2021-01-25T18:42:44.314972Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "kf_PGI*volume_c*(g6p_c(t) - f6p_c(t)/Keq_PGI)\n"
     ]
    }
   ],
   "source": [
    "mass_config.exclude_compartment_volumes_in_rates = False\n",
    "\n",
    "PGI = model.reactions.get_by_id(\"PGI\")\n",
    "model.custom_parameters[\"volume_c\"] = 1\n",
    "\n",
    "print(PGI.rate)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The compartment volume is currently treated as a custom parameter. This behavior is subject to change in future updates following the release of COBRApy compartment objects. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### For compartments and SBML"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `boundary_compartment` attribute defines the compartment for any external boundary species. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-01-25T18:42:44.320231Z",
     "iopub.status.busy": "2021-01-25T18:42:44.319520Z",
     "iopub.status.idle": "2021-01-25T18:42:44.322969Z",
     "shell.execute_reply": "2021-01-25T18:42:44.323428Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'b': 'boundary'}\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "'x1_b'"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Create a boundary reaction\n",
    "x1_c = MassMetabolite(\"x1_c\", compartment=\"c\")\n",
    "R3 = MassReaction(\"R1\")\n",
    "R3.add_metabolites({x1_c: -1})\n",
    "\n",
    "print(mass_config.boundary_compartment)\n",
    "R3.boundary_metabolite"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `boundary_compartment` can be changed using a `dict` that contains the new compartment identifier and its full name. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-01-25T18:42:44.328010Z",
     "iopub.status.busy": "2021-01-25T18:42:44.327205Z",
     "iopub.status.idle": "2021-01-25T18:42:44.330297Z",
     "shell.execute_reply": "2021-01-25T18:42:44.330864Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'x1_xt'"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mass_config.boundary_compartment = {\"xt\": \"external\"}\n",
    "R3.boundary_metabolite"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Because the `mass.Simulation` object uses the **libRoadRunner** package, a simulator for SBML models, a model cannot be simulated without defining at least one compartment. The `default_compartment` attribute is used to define the compartment of the model when no compartments have been defined."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-01-25T18:42:44.335902Z",
     "iopub.status.busy": "2021-01-25T18:42:44.334926Z",
     "iopub.status.idle": "2021-01-25T18:42:44.337915Z",
     "shell.execute_reply": "2021-01-25T18:42:44.338401Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'compartment': 'default_compartment'}"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mass_config.default_compartment"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As with the `boundary_compartment` attribute, the `default_compartment` attribute can be changed using a `dict`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-01-25T18:42:44.344452Z",
     "iopub.status.busy": "2021-01-25T18:42:44.343631Z",
     "iopub.status.idle": "2021-01-25T18:42:44.346307Z",
     "shell.execute_reply": "2021-01-25T18:42:44.346832Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'def': 'default_compartment'}"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mass_config.default_compartment = {\"def\": \"default_compartment\"}\n",
    "mass_config.default_compartment"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Model creator\n",
    "\n",
    "SBML also allows for a model creator to be defined when exporting models:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-01-25T18:42:44.351669Z",
     "iopub.status.busy": "2021-01-25T18:42:44.350690Z",
     "iopub.status.idle": "2021-01-25T18:42:44.353680Z",
     "shell.execute_reply": "2021-01-25T18:42:44.354401Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'familyName': '', 'givenName': '', 'organization': '', 'email': ''}"
      ]
     },
     "execution_count": 21,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mass_config.model_creator"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `model_creator` attribute of the `MassConfiguration` allows the model creator to be set at the time of export by using a `dict`, with valid keys as \"familyName\", \"givenName\", \"organization\", and \"email\"."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-01-25T18:42:44.359751Z",
     "iopub.status.busy": "2021-01-25T18:42:44.358877Z",
     "iopub.status.idle": "2021-01-25T18:42:44.361627Z",
     "shell.execute_reply": "2021-01-25T18:42:44.362081Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'familyName': 'Smith',\n",
       " 'givenName': 'John',\n",
       " 'organization': 'Systems Biology Research Group @UCSD',\n",
       " 'email': ''}"
      ]
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mass_config.model_creator = {\n",
    "    \"familyName\": \"Smith\",\n",
    "    \"givenName\": \"John\",\n",
    "    \"organization\": \"Systems Biology Research Group @UCSD\"}\n",
    "mass_config.model_creator"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Attributes for Simulation and Analysis\n",
    "\n",
    "The following attributes of the `MassConfiguration` alter default behaviors of various simulation and analytical methods."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-01-25T18:42:44.367551Z",
     "iopub.status.busy": "2021-01-25T18:42:44.366612Z",
     "iopub.status.idle": "2021-01-25T18:42:45.201347Z",
     "shell.execute_reply": "2021-01-25T18:42:45.201844Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Successfully loaded MassModel 'Glycolysis' into RoadRunner.\n"
     ]
    }
   ],
   "source": [
    "from mass import Simulation\n",
    "\n",
    "# Reset configurations before loading model\n",
    "mass_config.boundary_compartment = {\"b\": \"boundary\"}\n",
    "mass_config.exclude_compartment_volumes_in_rates = True\n",
    "\n",
    "model = create_example_model(\"Glycolysis\")\n",
    "sim = Simulation(model, verbose=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Steady state threshold\n",
    "\n",
    "The `MassConfiguration.steady_state_threshold` attribute determines whether a model has reached a steady state using the following criteria:\n",
    "\n",
    "* With simulations (i.e., `strategy=simulate`), the absolute difference between the last two solution points must be less than or equal to the steady state threshold.\n",
    "\n",
    "* With steady state solvers, the sum of squares of the steady state solutions must be less than or equal to the steady state threshold.\n",
    "\n",
    "In general, compared values must be less than or equal to the `steady_state_threshold` attribute to be considered at a steady state."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-01-25T18:42:45.206825Z",
     "iopub.status.busy": "2021-01-25T18:42:45.206178Z",
     "iopub.status.idle": "2021-01-25T18:42:45.673548Z",
     "shell.execute_reply": "2021-01-25T18:42:45.674188Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 24,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mass_config.steady_state_threshold = 1e-20\n",
    "conc_sol, flux_sol = sim.find_steady_state(model, strategy=\"simulate\")\n",
    "bool(conc_sol)  # Empty solution objects return False"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Changing the threshold affects whether solution values are considered to be at steady state:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-01-25T18:42:45.704471Z",
     "iopub.status.busy": "2021-01-25T18:42:45.682459Z",
     "iopub.status.idle": "2021-01-25T18:42:46.269813Z",
     "shell.execute_reply": "2021-01-25T18:42:46.270392Z"
    },
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 25,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mass_config.steady_state_threshold = 1e-6\n",
    "conc_sol, flux_sol = sim.find_steady_state(model, strategy=\"simulate\")\n",
    "bool(conc_sol)  # Filled solution objects return False"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Decimal precision\n",
    "\n",
    "The `MassConfiguration.decimal_precision` attribute is a special attribute used in several `mass` methods. The value of the attribute determines how many digits in rounding after the decimal to preserve.\n",
    "\n",
    "For many methods, the `decimal_precision` attribute will not be applied unless a `decimal_precision` kwarg is set as `True`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-01-25T18:42:46.281674Z",
     "iopub.status.busy": "2021-01-25T18:42:46.280465Z",
     "iopub.status.idle": "2021-01-25T18:42:47.180041Z",
     "shell.execute_reply": "2021-01-25T18:42:47.180766Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1.0000003633303345\n",
      "1.00000036\n"
     ]
    }
   ],
   "source": [
    "# Set decimal precision\n",
    "mass_config.decimal_precision = 8\n",
    "\n",
    "# Will not apply decimal precision to steady state solutions\n",
    "conc_sol, flux_sol = sim.find_steady_state(model, strategy=\"simulate\",\n",
    "                                           decimal_precision=False)\n",
    "print(conc_sol[\"glc__D_c\"])\n",
    "\n",
    "# Will apply decimal precision to steady state solutions\n",
    "conc_sol, flux_sol = sim.find_steady_state(model, strategy=\"simulate\",\n",
    "                                           decimal_precision=True)\n",
    "print(conc_sol[\"glc__D_c\"])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If `MassConfiguration.decimal_precision` is `None`, no rounding will occur."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-01-25T18:42:47.187165Z",
     "iopub.status.busy": "2021-01-25T18:42:47.186402Z",
     "iopub.status.idle": "2021-01-25T18:42:47.595252Z",
     "shell.execute_reply": "2021-01-25T18:42:47.596072Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1.0000003633303345\n"
     ]
    }
   ],
   "source": [
    "mass_config.decimal_precision = None\n",
    "\n",
    "# Will apply decimal precision to steady state solutions\n",
    "conc_sol, flux_sol = sim.find_steady_state(model, strategy=\"simulate\",\n",
    "                                           decimal_precision=True)\n",
    "print(conc_sol[\"glc__D_c\"])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Shared COBRA Attributes\n",
    "\n",
    "The following attributes are those shared with the `cobra.Configuration` object."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Bounds\n",
    "\n",
    "When a reaction is created, its default bound values are determined by the `lower_bound` and `upper_bound` attributes of the `MassConfiguration`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-01-25T18:42:47.603095Z",
     "iopub.status.busy": "2021-01-25T18:42:47.601697Z",
     "iopub.status.idle": "2021-01-25T18:42:47.607096Z",
     "shell.execute_reply": "2021-01-25T18:42:47.607805Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "R4 bounds: (-1000, 1000)\n"
     ]
    }
   ],
   "source": [
    "mass_config.lower_bound = -1000\n",
    "mass_config.upper_bound = 1000\n",
    "R4 = MassReaction(\"R4\")\n",
    "print(\"R4 bounds: {0}\".format(R4.bounds))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Changing the bounds affects newly created reactions, but not existing ones:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-01-25T18:42:47.613348Z",
     "iopub.status.busy": "2021-01-25T18:42:47.612552Z",
     "iopub.status.idle": "2021-01-25T18:42:47.617122Z",
     "shell.execute_reply": "2021-01-25T18:42:47.619046Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "R5 bounds: (-444, 444)\n",
      "R4 bounds: (-1000, 1000)\n"
     ]
    }
   ],
   "source": [
    "mass_config.bounds = (-444, 444)\n",
    "R5 = MassReaction(\"R5\")\n",
    "print(\"R5 bounds: {0}\".format(R5.bounds))\n",
    "print(\"R4 bounds: {0}\".format(R4.bounds))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Solver\n",
    "\n",
    "The default solver and solver tolerance attributes are determined by the `solver` and `tolerance` attributes of the `MassConfiguration`. The `solver` and `tolerance` attributes are utilized by newly instantiated models and `ConcSolver` objects."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-01-25T18:42:47.708805Z",
     "iopub.status.busy": "2021-01-25T18:42:47.660384Z",
     "iopub.status.idle": "2021-01-25T18:42:47.783514Z",
     "shell.execute_reply": "2021-01-25T18:42:47.784453Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Solver <optlang.gurobi_interface.Model object at 0x7fc160f23c70>\n",
      "Tolerance 1e-07\n"
     ]
    }
   ],
   "source": [
    "model = create_example_model(\"textbook\")\n",
    "print(\"Solver {0!r}\".format(model.solver))\n",
    "print(\"Tolerance {0}\".format(model.tolerance))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The default solver can be changed, depending on the solvers installed in the current environment. GLPK is assumed to always be present in the environment.\n",
    "\n",
    "The solver tolerance is similarly set using the `tolerance` attribute."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-01-25T18:42:47.829002Z",
     "iopub.status.busy": "2021-01-25T18:42:47.789940Z",
     "iopub.status.idle": "2021-01-25T18:42:47.905954Z",
     "shell.execute_reply": "2021-01-25T18:42:47.906619Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Solver <optlang.glpk_interface.Model object at 0x7fc149881c40>\n",
      "Tolerance 0.0001\n"
     ]
    }
   ],
   "source": [
    "# Change solver and solver tolerance\n",
    "mass_config.solver = \"glpk\"\n",
    "mass_config.tolerance = 1e-4\n",
    "\n",
    "# Instantiate a new model to observe changes\n",
    "model = create_example_model(\"textbook\")\n",
    "print(\"Solver {0!r}\".format(model.solver))\n",
    "print(\"Tolerance {0}\".format(model.tolerance))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Number of processes\n",
    "\n",
    "The `MassConfiguration.processes` determines the default number of processes used when multiprocessing is possible. The default number corresponds to the number of available cores (hyperthreads)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2021-01-25T18:42:47.913361Z",
     "iopub.status.busy": "2021-01-25T18:42:47.912230Z",
     "iopub.status.idle": "2021-01-25T18:42:47.916811Z",
     "shell.execute_reply": "2021-01-25T18:42:47.917867Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "15"
      ]
     },
     "execution_count": 32,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mass_config.processes"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.9.15"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}