docs/examples/edb/simple_acid_example.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "dda68344",
   "metadata": {},
   "source": [
    "# Carbonic Acid Example\n",
    "\n",
    "**STEPS**\n",
    "\n",
    "1. Connect to database\n",
    "2. Create a base 'thermo' config for liquid only system with FpcTP state variables \n",
    "3. Add all components for carbonic acid problem to the base 'thermo' config\n",
    "4. Create a base 'reaction' config \n",
    "5. Find and add reactions to 'reaction' config based on the component list \n",
    "6. Build an IDAES model from the database generated configs\n",
    "7. Check the IDAES model for errors\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c8399ebe",
   "metadata": {},
   "source": [
    "## 1. Connect to database"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "2cf31fff",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "connecting to mongodb://localhost:27017\n"
     ]
    }
   ],
   "source": [
    "from watertap.edb import ElectrolyteDB\n",
    "print(\"connecting to \" + str(ElectrolyteDB.DEFAULT_URL))\n",
    "db = ElectrolyteDB()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1adaa00f",
   "metadata": {},
   "source": [
    "## 2. Create base 'thermo' config\n",
    "\n",
    "Here, we grab the \"thermo_Liq_FpcTP\" base, which will likely be the most common for simple acid systems."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "5b094df1",
   "metadata": {},
   "outputs": [],
   "source": [
    "thermo_base = db.get_base(\"thermo_Liq_FpcTP\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bc97beb4",
   "metadata": {},
   "source": [
    "## 3. Add components to 'thermo' base\n",
    "\n",
    "In this case, we know that our system is water + carbonic acid, which will produce the follow species."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "b9afce75",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Adding CO3_2-\n",
      "Adding H2CO3\n",
      "Adding HCO3_-\n",
      "Adding H_+\n",
      "Adding OH_-\n",
      "Adding H2O\n"
     ]
    }
   ],
   "source": [
    "comp_list = [\"H2O\", \"H_+\", \"OH_-\", \"H2CO3\", \"HCO3_-\", \"CO3_2-\"]\n",
    "comps = db.get_components(component_names=comp_list)\n",
    "for comp_obj in comps:\n",
    "    print(\"Adding \" + str(comp_obj.name) + \"\" )\n",
    "    thermo_base.add(comp_obj)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f0660cea",
   "metadata": {},
   "source": [
    "## 4. Create base 'reaction' config\n",
    "\n",
    "Unlike in the prior example, here we are going to place all reactions in a separate configuration dictionary and declare those reactions as equilibrium. This is likely the most common way to handle reactions in WaterTAP. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "0f31ac56",
   "metadata": {},
   "outputs": [],
   "source": [
    "react_base = db.get_base(\"reaction\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "750e5055",
   "metadata": {},
   "source": [
    "## 5. Find and add reactions to 'reaction' base\n",
    "\n",
    "The reactions that should be found include 'H2O_Kw', 'H2CO3_Ka1', and 'H2CO3_Ka2'. These are the deprotonation reactions of the acids in the system. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "91b91b1d",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Found reaction: H2CO3_Ka2\n",
      "Found reaction: H2CO3_Ka1\n",
      "Found reaction: H2O_Kw\n"
     ]
    }
   ],
   "source": [
    "react_obj = db.get_reactions(component_names=comp_list)\n",
    "for r in react_obj:\n",
    "    print(\"Found reaction: \" + str(r.name))\n",
    "    react_base.add(r)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bb0e6146",
   "metadata": {},
   "source": [
    "## 6. Build an IDAES model\n",
    "\n",
    "After we have grabbed all necessary information from the database, the formatted configuration dictionaries can be obtained from the 'base' objects we created in steps 2 & 4. The configurations are accessible via *_base.idaes_config. Passing those configuration dictionaries to the IDAES objects (GenericParameterBlock and GenericReactionParameterBlock) allows us to build the IDAES model. In this case, we build an EquilibriumReactor model from those property blocks. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "84e64a0b",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Import specific pyomo objects\n",
    "from pyomo.environ import (\n",
    "    ConcreteModel,\n",
    ")\n",
    "# Import the idaes objects for Generic Properties and Reactions\n",
    "from idaes.generic_models.properties.core.generic.generic_property import (\n",
    "    GenericParameterBlock,\n",
    ")\n",
    "from idaes.generic_models.properties.core.generic.generic_reaction import (\n",
    "    GenericReactionParameterBlock,\n",
    ")\n",
    "\n",
    "# Import the idaes object for the EquilibriumReactor unit model\n",
    "from idaes.generic_models.unit_models.equilibrium_reactor import EquilibriumReactor\n",
    "\n",
    "# Import the core idaes objects for Flowsheets and types of balances\n",
    "from idaes.core import FlowsheetBlock\n",
    "\n",
    "thermo_config = thermo_base.idaes_config\n",
    "reaction_config = react_base.idaes_config\n",
    "\n",
    "model = ConcreteModel()\n",
    "model.fs = FlowsheetBlock(default={\"dynamic\": False})\n",
    "model.fs.thermo_params = GenericParameterBlock(default=thermo_config)\n",
    "model.fs.rxn_params = GenericReactionParameterBlock(\n",
    "            default={\"property_package\": model.fs.thermo_params, **reaction_config}\n",
    "        )\n",
    "\n",
    "model.fs.unit = EquilibriumReactor(\n",
    "        default={\n",
    "            \"property_package\": model.fs.thermo_params,\n",
    "            \"reaction_package\": model.fs.rxn_params,\n",
    "            \"has_rate_reactions\": False,\n",
    "            \"has_equilibrium_reactions\": True,\n",
    "            \"has_heat_transfer\": False,\n",
    "            \"has_heat_of_reaction\": False,\n",
    "            \"has_pressure_change\": False,\n",
    "        }\n",
    "    )"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f14c6800",
   "metadata": {},
   "source": [
    "## 7. Check IDAES model for errors\n",
    "\n",
    "In this last step, we probe the created model to make sure everything is ok. We first check to make sure that the units of the model are consistent, then we can check the degrees of freedom. In this particular case, we expect 8 degrees of freedom. \n",
    "\n",
    "The number of degrees of freedom will be problem dependent. In this case, our degrees stem from (1) pressure, (2) temperature, and (3-8) the individual species-phase pairs: \n",
    "\n",
    "(3) (H2O , Liq) \n",
    "\n",
    "(4) (H_+ , Liq) \n",
    "\n",
    "(5) (OH_- , Liq) \n",
    "\n",
    "(6) (H2CO3 , Liq) \n",
    "\n",
    "(7) (HCO3_- , Liq) \n",
    "\n",
    "(8) (CO3_2- , Liq) "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "ddeb7943",
   "metadata": {},
   "outputs": [],
   "source": [
    "from pyomo.util.check_units import assert_units_consistent\n",
    "from idaes.core.util.model_statistics import (\n",
    "    degrees_of_freedom,\n",
    ")\n",
    "\n",
    "assert_units_consistent(model)\n",
    "assert degrees_of_freedom(model) == 8"
   ]
  }
 ],
 "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.8.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}