Contribution to OLI documentation efforts

tutorials/incorporating_oli_calculations.ipynb

@@ -0,0 +1,323 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "scrolled": true,
+    "slideshow": {
+     "slide_type": "slide"
+    }
+   },
+   "source": [
+    "\n",
+    "# Incorporating OLI Calculations with WaterTAP\n",
+    "\n",
+    "#### Contact: Paul Vecchiarelli ([email protected])\n",
+    "\n",
+    "This tutorial will demonstrate basic usage of OLI Cloud calls using our custom API tools."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "slideshow": {
+     "slide_type": "slide"
+    }
+   },
+   "source": [
+    "## Rationale\n",
+    "\n",
+    " - Simulations for realistic water sources are mathematically complex: \n",
+    " > $ Interactions \\ge Cations * Anions$\n",
+    " - OLI improves WaterTAP approximations and offloads computational resources"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "slideshow": {
+     "slide_type": "slide"
+    }
+   },
+   "source": [
+    "## Required OLI API Inputs\n",
+    "\n",
+    "\n",
+    " - State variables (solute concentrations, temperature, pressure), which can beextracted from a state block\n",
+    " \n",
+    " - Login credentials\n",
+    " \n",
+    " - A chemistry (*.dbs) file\n",
+    "     - establishes state variables, phases, etc. to be considered in flash calls"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "slideshow": {
+     "slide_type": "slide"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "# used to specify state/convert variables\n",
+    "from pyomo.environ import units as pyunits\n",
+    "\n",
+    "# used to build survey lists\n",
+    "from numpy import linspace\n",
+    "\n",
+    "# used to execute OLI Cloud functions\n",
+    "from watertap.tools.oli_api.flash import Flash\n",
+    "from watertap.tools.oli_api.credentials import CredentialManager\n",
+    "from watertap.tools.oli_api.client import OLIApi"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "slideshow": {
+     "slide_type": "slide"
+    }
+   },
+   "source": [
+    "# 1. Specify State Variables.\n",
+    "\n",
+    "- This data is used to construct inputs to OLI Cloud"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "slideshow": {
+     "slide_type": "subslide"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "source_water = {\n",
+    "    \"temperature\": 298.15,\n",
+    "    \"pressure\": 101325,\n",
+    "    \"components\": {\n",
+    "        \"Cl_-\": 870,\n",
+    "        \"Na_+\": 739,\n",
+    "        \"SO4_2-\": 1011,\n",
+    "        \"Mg_2+\": 90,\n",
+    "        \"Ca_2+\": 258,\n",
+    "        \"K_+\": 9,\n",
+    "        \"HCO3_-\": 385,\n",
+    "        \"SiO2\": 30,\n",
+    "    },\n",
+    "    \"units\": {\n",
+    "        \"temperature\": pyunits.K,\n",
+    "        \"pressure\": pyunits.Pa,\n",
+    "        \"components\": pyunits.mg / pyunits.L,\n",
+    "    },\n",
+    "}"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "slideshow": {
+     "slide_type": "slide"
+    }
+   },
+   "source": [
+    "# 2. Initialize Flash Instance.\n",
+    "\n",
+    " - We will run most of our methods with this class"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "f = Flash()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "slideshow": {
+     "slide_type": "slide"
+    }
+   },
+   "source": [
+    "# 3. Get Survey Parameters.\n",
+    "\n",
+    " - In this example, we will generate a temperature sweep survey"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "scrolled": true,
+    "slideshow": {
+     "slide_type": "subslide"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "survey_conditions = {\n",
+    "    \"Temperature\": linspace(273, 373, 6),\n",
+    "    \"SO4_2-\": linspace(1e2, 1e3, 10),\n",
+    "    \"Ca_2+\": linspace(1e2, 1e3, 10),\n",
+    "}\n",
+    "\n",
+    "survey = f.build_survey(\n",
+    "    survey_conditions,\n",
+    "    get_oli_names=True,\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "slideshow": {
+     "slide_type": "slide"
+    }
+   },
+   "source": [
+    "# 4. Login to OLI Cloud.\n",
+    "\n",
+    "- The following code demonstrates an OLI Cloud login:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "slideshow": {
+     "slide_type": "fragment"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "try:\n",
+    "    credential_manager = CredentialManager(\n",
+    "        username=\"\",\n",
+    "        password=\"\",\n",
+    "        root_url=\"\",\n",
+    "        auth_url=\"\",\n",
+    "        access_keys=[],\n",
+    "    )\n",
+    "except (OSError, ConnectionError) as e:\n",
+    "    print(e)\n",
+    "    credential_manager = None"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "slideshow": {
+     "slide_type": "slide"
+    }
+   },
+   "source": [
+    "# 5. Create *.dbs File and 6. Get Output"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "scrolled": false,
+    "slideshow": {
+     "slide_type": "fragment"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "if credential_manager:\n",
+    "    with OLIApi(credential_manager) as oliapi:\n",
+    "        dbs_file_id = oliapi.get_dbs_file_id(\n",
+    "            chemistry_source=source_water[\"components\"],\n",
+    "            phases=[\"liquid1\", \"solid\"],\n",
+    "            model_name=\"tutorial_model\",\n",
+    "        )\n",
+    "\n",
+    "        water_analysis_base_case = f.build_flash_calculation_input(\n",
+    "            flash_method=\"wateranalysis\",\n",
+    "            state_vars=source_water,                                                       \n",
+    "        )\n",
+    "\n",
+    "        water_analysis_composition_survey = f.run_flash(\n",
+    "            flash_method=\"wateranalysis\",\n",
+    "            oliapi_instance=oliapi,\n",
+    "            dbs_file_id=dbs_file_id,\n",
+    "            initial_input=water_analysis_base_case,\n",
+    "            survey=survey,\n",
+    "            file_name=\"wateranalysis_composition_survey_temperature\",\n",
+    "        )"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "slideshow": {
+     "slide_type": "slide"
+    }
+   },
+   "source": [
+    "# 7. Extract Filtered Output\n",
+    "\n",
+    " - OLI's output is robust, so WaterTAP enables printing selected results:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "slideshow": {
+     "slide_type": "subslide"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "properties = [\n",
+    "    \"prescalingTendencies\",\n",
+    "    \"entropy\",\n",
+    "    \"gibbsFreeEnergy\",\n",
+    "    \"selfDiffusivities\",\n",
+    "    \"molecularConcentration\",\n",
+    "    \"kValuesMBased\",\n",
+    "]\n",
+    "\n",
+    "if credential_manager:\n",
+    "    extracted_properties = f.extract_properties(\n",
+    "        water_analysis_composition_survey,\n",
+    "        properties,\n",
+    "        filter_zero=True,\n",
+    "        file_name=\"properties\",\n",
+    "    )"
+   ]
+  }
+ ],
+ "metadata": {
+  "celltoolbar": "Slideshow",
+  "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.8.16"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}