OLI API Flash update

tutorials/incorporating_oli_calculations.ipynb

@@ -83,7 +83,8 @@
    "source": [
     "# 1. Specify State Variables.\n",
     "\n",
-    "- This data is used to construct inputs to OLI Cloud"
+    "- This data is used to construct inputs to OLI Cloud\n",
+    "- Same basic information is required by Water Analysis and Isothermal flashes (temperature, pressure, solutes)"
    ]
   },
   {
@@ -96,18 +97,12 @@
    },
    "outputs": [],
    "source": [
-    "source_water = {\n",
+    "state_vars = {\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",
+    "        \"Na_+\": 1e3,\n",
+    "        \"Cl_-\": 1e3\n",
     "    },\n",
     "    \"units\": {\n",
     "        \"temperature\": pyunits.K,\n",
@@ -163,18 +158,26 @@
    },
    "outputs": [],
    "source": [
-    "survey_conditions = {\n",
-    "    \"Temperature\": linspace(273, 373, 10),\n",
-    "    \"SO4_2-\": linspace(0, 1e3, 10),\n",
-    "    \"Ca_2+\": linspace(0, 1e3, 10),\n",
-    "}\n",
-    "\n",
+    "# a survey will sweep through one or more variables simultaneously\n",
     "survey = f.build_survey(\n",
-    "    survey_conditions,\n",
+    "    {\"Na_+\": linspace(0, 1e5, 10)},\n",
     "    get_oli_names=True,\n",
+    "    file_name=\"test_survey\",\n",
     ")"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# individual sample points can be accessed to see what will be modified\n",
+    "samples = range(0,10,2)\n",
+    "survey_points = f.get_survey_sample_conditions(survey, samples)\n",
+    "f.write_output(survey_points, \"test_survey_points\")"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {
@@ -199,12 +202,15 @@
    "outputs": [],
    "source": [
     "try:\n",
+    "    # credentials are entered here\n",
+    "    # up to 5 access keys per user can be generated\n",
+    "    # CredentialManager can save login information and access keys\n",
     "    credential_manager = CredentialManager(\n",
-    "        username=\"\",\n",
-    "        password=\"\",\n",
-    "        root_url=\"\",\n",
-    "        auth_url=\"\",\n",
-    "        access_keys=[],\n",
+    "        username=\"\", # requires password, root_url, and auth_url\n",
+    "        password=\"\", # required with username login only\n",
+    "        root_url=\"\", # required with username and access key login\n",
+    "        auth_url=\"\", # required with username login only\n",
+    "        access_keys=[], # only requires root_url\n",
     "    )\n",
     "except (OSError, ConnectionError) as e:\n",
     "    print(e)\n",
@@ -234,44 +240,70 @@
    "outputs": [],
    "source": [
     "if credential_manager:\n",
+    "    # OLIApi is used as a context manager\n",
     "    with OLIApi(credential_manager) as oliapi:\n",
     "        # create a new DBS file\n",
+    "        # alternative thermo_frameworks and private_databanks are available\n",
     "        dbs_file_id = oliapi.get_dbs_file_id(\n",
-    "            chemistry_source=source_water[\"components\"],\n",
-    "            phases=[\"liquid1\", \"solid\"],\n",
+    "            state_vars[\"components\"],\n",
+    "            thermo_framework=\"MSE (H3O+ ion)\",\n",
+    "            private_databanks=[\"XSC\"],\n",
+    "            phases=[\"liquid1\", \"solid\"], # liquid2 (non-aqueous) and vapor phases can also be investigated\n",
+    "            model_name=\"test\",\n",
     "        )\n",
     "        \n",
-    "        # create water analysis inputs\n",
-    "        water_analysis_input = f.build_flash_calculation_input(\n",
+    "        # get a summary of the DBS file\n",
+    "        file_summary = oliapi.get_dbs_file_summary(dbs_file_id)\n",
+    "        \n",
+    "        # save chemistry information\n",
+    "        chemistry_info = file_summary[\"chemistry_info\"]\n",
+    "        f.write_output(chemistry_info[\"result\"], \"chemistry_info\")\n",
+    "        \n",
+    "        # create water analysis input\n",
+    "        # Water Analysis uses true species for inputs, i.e., IONS\n",
+    "        stream_input = f.build_flash_calculation_input(\n",
     "            \"wateranalysis\",\n",
     "            state_vars,\n",
-    "        )\n",
-    "    \n",
-    "        # create water analysis case\n",
-    "        water_analysis_base_case = f.run_flash(\n",
+    "            file_name=\"test_water_analysis_input\",\n",
+    "        )    \n",
+    "        # run Water Analysis flash calculation survey as specified        \n",
+    "        stream_output = f.run_flash(\n",
     "            \"wateranalysis\",\n",
     "            oliapi,\n",
     "            dbs_file_id,\n",
-    "            water_analysis_input,\n",
-    "            file_name=\"water_analysis_singlepoint\"\n",
+    "            stream_input,\n",
+    "            survey,\n",
+    "            file_name=\"test_water_analysis_survey_output\"\n",
     "        )\n",
+    "        # The output of Water Analysis gives apparent species\n",
+    "        # i.e., SALTS, COMPLEXES (MgO, CaO, etc.)\n",
     "        \n",
-    "        # create apparent composition from water analysis output\n",
-    "        water_analysis_apparent_composition = f.build_flash_calculation_input(\n",
+    "        # Other flash calculations use apparent species for inputs\n",
+    "        # get_inflows extracts Water Analysis outputs to use with Isothermal flash\n",
+    "        # these apparent species can be saved to a file and reloaded as needed\n",
+    "        isothermal_inflows = f.get_inflows(\n",
+    "            stream_output,\n",
+    "            file_name=\"isothermal_inflows\",\n",
+    "        )\n",
+    "        isothermal_input = f.build_flash_calculation_input(\n",
     "            \"isothermal\",\n",
-    "            state_vars,\n",
-    "            water_analysis_base_case[0],\n",
+    "            isothermal_inflows,\n",
+    "            file_name=f\"isothermal_input\",\n",
     "        )\n",
-    "        \n",
-    "        # run isothermal flash for the survey parameters\n",
-    "        isothermal_survey_result = f.run_flash(\n",
+    "        # specify a new survey to compare apparent species\n",
+    "        isothermal_survey = f.build_survey(\n",
+    "            {\"NaCl\": linspace(0, 1e6, 10)},\n",
+    "            get_oli_names=True,\n",
+    "            file_name=\"test_isothermal_survey\",\n",
+    "        )\n",
+    "        isothermal_output = f.run_flash(\n",
     "            \"isothermal\",\n",
     "            oliapi,\n",
     "            dbs_file_id,\n",
-    "            water_analysis_apparent_composition,\n",
-    "            survey,\n",
-    "            \"isothermal_composition_survey\",\n",
-    "        )"
+    "            isothermal_inflows,\n",
+    "            isothermal_survey,\n",
+    "        file_name=f\"{method}_output\",\n",
+    "    )\n"
    ]
   },
   {
@@ -297,22 +329,23 @@
    },
    "outputs": [],
    "source": [
-    "# extract properties from raw oli output\n",
-    "properties = [\n",
-    "    \"prescalingTendencies\",\n",
-    "    \"entropy\",\n",
-    "    \"gibbsFreeEnergy\",\n",
-    "    \"selfDiffusivities\",\n",
-    "    \"molecularConcentration\",\n",
-    "    \"kValuesMBased\",\n",
-    "]\n",
     "if credential_manager:\n",
-    "    extracted_properties = f.extract_properties(\n",
-    "        isothermal_survey_result,\n",
-    "        properties,\n",
-    "        filter_zero=True,\n",
-    "        file_name=\"properties\",\n",
-    "    )"
+    "    # extract properties from OLI flash survey output\n",
+    "    properties = [\n",
+    "        \"prescalingTendencies\",\n",
+    "        \"molecularConcentration\",\n",
+    "    ]\n",
+    "    # data can be saved as a JSON file for further review and analysis\n",
+    "    water_analysis_extract = f.extract_properties(\n",
+    "        stream_output,\n",
+    "        properties=properties,\n",
+    "        file_name=\"water_analysis_extract\",\n",
+    "    )\n",
+    "    isothermal_extract = f.extract_properties(\n",
+    "    isothermal_output,\n",
+    "    properties=properties,\n",
+    "    file_name=\"isothermal_extract\",\n",
+    ")"
    ]
   }
  ],