{ "cells": [ { "cell_type": "markdown", "id": "cell-00", "metadata": {}, "source": [ "# Water–isobutanol phase discovery\n", "\n", "**Evidence: numerical verification.** Compare declared liquid phases with native phase discovery.\n", "\n", "\n", "The canonical input is the neutral water/isobutanol subset of\n", "`khudaida-2026-figure-2-electrolyte-lle/7`, at 293.15 K and 100,000 Pa.\n", "Khudaida et al. (2026), Tables 2, 5–7\n", "([paper](https://doi.org/10.1021/acs.jced.5c00780)), and the packet's cited\n", "association rules own the inputs. Version 7 retains the Wolbach–Sandler\n", "unlike association size factor. The feed is 0.6 mol water + 0.4 mol isobutanol.\n" ] }, { "cell_type": "markdown", "id": "cell-01", "metadata": {}, "source": [ "## Read the inputs\n", "\n", "Use a repository checkout with the environment described in the installation\n", "guide. The wheel alone does not contain these data. All density, association,\n", "equilibrium and parameter-fit iterations below run in the native Engine.\n" ] }, { "cell_type": "code", "execution_count": 1, "id": "cell-02", "metadata": { "execution": { "iopub.execute_input": "2026-11-02T22:38:00.020456Z", "iopub.status.busy": "2026-11-02T22:38:00.020367Z", "iopub.status.idle": "2026-11-02T22:38:00.233442Z", "shell.execute_reply": "2026-11-02T22:38:00.232993Z" } }, "outputs": [], "source": [ "from pathlib import Path\n", "import pandas as pd\n", "from IPython.display import display\n", "from epcsaft import (\n", " Parameters,\n", " Mixture,\n", ")\n", "from epcsaft import equilibrium as eq\n", "\n", "pd.set_option(\"display.max_columns\", None)\n", "pd.set_option(\"display.max_colwidth\", None)\n", "\n", "ROOT = next(\n", " folder\n", " for folder in (Path.cwd(), *Path.cwd().parents)\n", " if (folder / \"ARCHITECTURE.yaml\").is_file()\n", ")\n", "PACKETS = ROOT / \"data\" / \"packets\"\n", "\n", "\n", "def equilibrium_values(declared_state):\n", " \"\"\"Keep the returned physical state and the equation residuals together.\"\"\"\n", " assert declared_state.success, declared_state.message\n", " assert declared_state.requested_tolerance_met\n", " assert declared_state.classified_residuals\n", " residual = max(map(abs, declared_state.classified_residuals), default=0)\n", " assert residual <= 1e-10\n", " return dict(\n", " temperature_K=declared_state.temperature,\n", " pressure_Pa=declared_state.pressure,\n", " amounts_mol=declared_state.amounts,\n", " mole_fractions=declared_state.mole_fractions,\n", " molar_densities_mol_m3=declared_state.molar_densities,\n", " residual=residual,\n", " linear_solver=declared_state.linear_solver,\n", " )\n" ] }, { "cell_type": "markdown", "id": "cell-03", "metadata": {}, "source": [ "## Declare a split, then allow discovery\n", "\n", "The two liquid guesses are (0.999, 0.001) and (0.3, 0.7).\n", "`Discover` delegates finite phase trials to the Engine. Match phases by water\n", "fraction, since returned phase ordinals need not match. Require endpoint\n", "agreement within 10⁻⁹, component closure within 10⁻¹⁰ mol, and classified\n", "equation residuals at most 10⁻¹⁰. Keep the tangent-plane trial evidence visible.\n" ] }, { "cell_type": "code", "execution_count": 2, "id": "cell-04", "metadata": { "execution": { "iopub.execute_input": "2026-11-02T22:38:00.234675Z", "iopub.status.busy": "2026-11-02T22:38:00.234543Z", "iopub.status.idle": "2026-11-02T22:38:00.261368Z", "shell.execute_reply": "2026-11-02T22:38:00.260767Z" } }, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
Declared water fraction / 1Discovered water fraction / 1Declared amount / mol
00.9943750.9943750.285318
10.4425560.4425560.714682
\n", "
" ], "text/plain": [ " Declared water fraction / 1 Discovered water fraction / 1 \\\n", "0 0.994375 0.994375 \n", "1 0.442556 0.442556 \n", "\n", " Declared amount / mol \n", "0 0.285318 \n", "1 0.714682 " ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "model = Mixture(\n", " Parameters.from_json(\n", " PACKETS / \"khudaida-2026-figure-2-electrolyte-lle/7/parameters/parameters.json\",\n", " components=[\"water\", \"isobutanol\"],\n", " )\n", ")\n", "feed = eq.Amounts({\"water\": 0.6, \"isobutanol\": 0.4})\n", "problem = eq.Problem(\n", " T=293.15,\n", " P=100000.0,\n", " feed=feed,\n", " phases=[\n", " eq.Phase(\"Lw\", kind=\"liquid\", composition_guess=(0.999, 0.001)),\n", " eq.Phase(\"Lo\", kind=\"liquid\", composition_guess=(0.3, 0.7)),\n", " ],\n", ")\n", "declared_state = eq.solve_equilibrium(model, problem)\n", "report = eq.stability_test(eq.compile_problem(model, problem), declared_state)\n", "discovered_state = eq.solve_equilibrium(\n", " model, eq.Problem(T=293.15, P=100000.0, feed=feed, phases=eq.Discover())\n", ")\n", "assert (\n", " max(\n", " (\n", " abs(a - b)\n", " for a, b in zip(\n", " sorted(declared_state.mole_fractions[::2]),\n", " sorted(discovered_state.mole_fractions[::2]),\n", " )\n", " )\n", " )\n", " < 1e-09\n", ")\n", "values = dict(\n", " declared=equilibrium_values(declared_state),\n", " discovered=equilibrium_values(discovered_state),\n", " trials=len(report.trials),\n", " message=report.message,\n", " completed=report.completed,\n", ")\n", "for solved in (declared_state, discovered_state):\n", " balances = [\n", " sum((solved.amounts[j] * solved.mole_fractions[2 * j + i] for j in range(2)))\n", " - amount\n", " for i, amount in enumerate((0.6, 0.4))\n", " ]\n", " assert max(map(abs, balances)) <= 1e-10\n", " equilibrium_values(solved)\n", "values[\"component_balance_mol\"] = balances\n", "values[\"unresolved_trials\"] = sum(\n", " (\"unresolved\" in trial.evidence.lower() for trial in report.trials)\n", ")\n", "values[\"trial_evidence\"] = [trial.evidence for trial in report.trials]\n", "assert report.completed and values[\"unresolved_trials\"] == 0\n", "display(\n", " pd.DataFrame(\n", " {\n", " \"Declared water fraction / 1\": declared_state.mole_fractions[::2],\n", " \"Discovered water fraction / 1\": sorted(\n", " discovered_state.mole_fractions[::2], reverse=True\n", " ),\n", " \"Declared amount / mol\": declared_state.amounts,\n", " }\n", " )\n", ")\n", "declared_order = sorted(\n", " range(2), key=lambda phase: declared_state.mole_fractions[2 * phase]\n", ")\n", "discovered_order = sorted(\n", " range(2), key=lambda phase: discovered_state.mole_fractions[2 * phase]\n", ")\n", "for declared, discovered in zip(declared_order, discovered_order):\n", " assert (\n", " abs(declared_state.amounts[declared] - discovered_state.amounts[discovered])\n", " < 1e-09\n", " )\n", " assert (\n", " max(\n", " (\n", " abs(\n", " declared_state.mole_fractions[2 * declared + i]\n", " - discovered_state.mole_fractions[2 * discovered + i]\n", " )\n", " for i in range(2)\n", " )\n", " )\n", " < 1e-09\n", " )\n" ] }, { "cell_type": "code", "execution_count": 3, "id": "cell-06", "metadata": { "execution": { "iopub.execute_input": "2026-11-02T22:38:00.262472Z", "iopub.status.busy": "2026-11-02T22:38:00.262343Z", "iopub.status.idle": "2026-11-02T22:38:00.275867Z", "shell.execute_reply": "2026-11-02T22:38:00.275336Z" } }, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
Temperature / KPressure / PaPhase amounts / molMole fractions / 1Phase densities / mol m^-3Maximum classified residual / 1Linear solver
Declared293.15100000.0[0.2853182931107769, 0.7146817068892232][0.9943748683039002, 0.005625131696099895, 0.4425559753585558, 0.5574440246414442][54198.3600462764, 16912.29929663858]2.073248e-14
Discovered293.15100000.0[0.7146817068892205, 0.28531829311077944][0.44255597535855395, 0.557444024641446, 0.9943748683038998, 0.005625131696100154][16912.299296638528, 54198.360046276364]1.704286e-14
\n", "
" ], "text/plain": [ " Temperature / K Pressure / Pa \\\n", "Declared 293.15 100000.0 \n", "Discovered 293.15 100000.0 \n", "\n", " Phase amounts / mol \\\n", "Declared [0.2853182931107769, 0.7146817068892232] \n", "Discovered [0.7146817068892205, 0.28531829311077944] \n", "\n", " Mole fractions / 1 \\\n", "Declared [0.9943748683039002, 0.005625131696099895, 0.4425559753585558, 0.5574440246414442] \n", "Discovered [0.44255597535855395, 0.557444024641446, 0.9943748683038998, 0.005625131696100154] \n", "\n", " Phase densities / mol m^-3 \\\n", "Declared [54198.3600462764, 16912.29929663858] \n", "Discovered [16912.299296638528, 54198.360046276364] \n", "\n", " Maximum classified residual / 1 Linear solver \n", "Declared 2.073248e-14 \n", "Discovered 1.704286e-14 " ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
ComponentComponent balance error / mol
0water-1.110223e-16
1isobutanol0.000000e+00
\n", "
" ], "text/plain": [ " Component Component balance error / mol\n", "0 water -1.110223e-16\n", "1 isobutanol 0.000000e+00" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
Trials / 1Unresolved trials / 1CompletedMessage
070Trueno witness in the recorded trial set; unresolved trials 0
\n", "
" ], "text/plain": [ " Trials / 1 Unresolved trials / 1 Completed \\\n", "0 7 0 True \n", "\n", " Message \n", "0 no witness in the recorded trial set; unresolved trials 0 " ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
Trial evidence
0no_resolved_descent
1no_resolved_descent
2no_resolved_descent
3no_resolved_descent
4no_resolved_descent
5no_resolved_descent
6no_resolved_descent
\n", "
" ], "text/plain": [ " Trial evidence\n", "0 no_resolved_descent\n", "1 no_resolved_descent\n", "2 no_resolved_descent\n", "3 no_resolved_descent\n", "4 no_resolved_descent\n", "5 no_resolved_descent\n", "6 no_resolved_descent" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "display(pd.DataFrame(\n", " [values[\"declared\"], values[\"discovered\"]], index=[\"Declared\", \"Discovered\"]\n", ").rename(columns={\n", " \"temperature_K\": \"Temperature / K\",\n", " \"pressure_Pa\": \"Pressure / Pa\",\n", " \"amounts_mol\": \"Phase amounts / mol\",\n", " \"mole_fractions\": \"Mole fractions / 1\",\n", " \"molar_densities_mol_m3\": \"Phase densities / mol m^-3\",\n", " \"residual\": \"Maximum classified residual / 1\",\n", " \"linear_solver\": \"Linear solver\",\n", " }))\n", "display(pd.DataFrame({\n", " \"Component\": [\"water\", \"isobutanol\"],\n", " \"Component balance error / mol\": values[\"component_balance_mol\"],\n", "}))\n", "display(pd.DataFrame([{\n", " \"Trials / 1\": values[\"trials\"],\n", " \"Unresolved trials / 1\": values[\"unresolved_trials\"],\n", " \"Completed\": values[\"completed\"],\n", " \"Message\": values[\"message\"],\n", "}]))\n", "display(pd.DataFrame({\"Trial evidence\": values[\"trial_evidence\"]}))\n" ] }, { "cell_type": "markdown", "id": "cell-fast-md", "metadata": {}, "source": [ "## Fast discovery\n", "\n", "`Discover(mode=\"fast\")` runs a smaller tangent-plane search: it stops at the\n", "first resolved split and solves one two-phase declaration, without a final\n", "stability search. Require the same agreement with full discovery as above:\n", "phase amounts and compositions within 10⁻⁹. The record lists the parts of the\n", "full search that the fast mode leaves unsearched, and the native work counts." ] }, { "cell_type": "code", "execution_count": 4, "id": "cell-fast-code", "metadata": { "execution": { "iopub.execute_input": "2026-11-02T22:38:00.277172Z", "iopub.status.busy": "2026-11-02T22:38:00.277013Z", "iopub.status.idle": "2026-11-02T22:38:00.289520Z", "shell.execute_reply": "2026-11-02T22:38:00.288986Z" } }, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
Full: water fraction / 1Fast: water fraction / 1Full: amount / molFast: amount / mol
00.4425560.4425560.7146820.714682
10.9943750.9943750.2853180.285318
\n", "
" ], "text/plain": [ " Full: water fraction / 1 Fast: water fraction / 1 Full: amount / mol \\\n", "0 0.442556 0.442556 0.714682 \n", "1 0.994375 0.994375 0.285318 \n", "\n", " Fast: amount / mol \n", "0 0.714682 \n", "1 0.285318 " ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
FullFast
Helmholtz evaluations1096.0197.0
Density-root evaluations829.0133.0
Tangent-plane iterations95.07.0
\n", "
" ], "text/plain": [ " Full Fast\n", "Helmholtz evaluations 1096.0 197.0\n", "Density-root evaluations 829.0 133.0\n", "Tangent-plane iterations 95.0 7.0" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
Unsearched in fast mode
0removed-phase starts and retries
1alternative descending additions
2post-flash stability
3three-or-more-phase topologies
4Liquid/0,1,/positive-neutral-base
5Liquid/0,1,/near-pure-1
6Vapor/0,1,/positive-neutral-base
7Vapor/0,1,/near-pure-0
8Vapor/0,1,/near-pure-1
9Vapor/0,1,/ideal-gas
\n", "
" ], "text/plain": [ " Unsearched in fast mode\n", "0 removed-phase starts and retries\n", "1 alternative descending additions\n", "2 post-flash stability\n", "3 three-or-more-phase topologies\n", "4 Liquid/0,1,/positive-neutral-base\n", "5 Liquid/0,1,/near-pure-1\n", "6 Vapor/0,1,/positive-neutral-base\n", "7 Vapor/0,1,/near-pure-0\n", "8 Vapor/0,1,/near-pure-1\n", "9 Vapor/0,1,/ideal-gas" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "fast_state = eq.solve_equilibrium(\n", " model,\n", " eq.Problem(T=293.15, P=100000.0, feed=feed, phases=eq.Discover(mode=\"fast\")),\n", ")\n", "equilibrium_values(fast_state)\n", "fast_order = sorted(range(2), key=lambda phase: fast_state.mole_fractions[2 * phase])\n", "for full, fast in zip(discovered_order, fast_order):\n", " assert abs(discovered_state.amounts[full] - fast_state.amounts[fast]) < 1e-09\n", " assert max(\n", " abs(discovered_state.mole_fractions[2 * full + i] - fast_state.mole_fractions[2 * fast + i])\n", " for i in range(2)\n", " ) < 1e-09\n", "display(pd.DataFrame({\n", " \"Full: water fraction / 1\": [discovered_state.mole_fractions[2 * j] for j in discovered_order],\n", " \"Fast: water fraction / 1\": [fast_state.mole_fractions[2 * j] for j in fast_order],\n", " \"Full: amount / mol\": [discovered_state.amounts[j] for j in discovered_order],\n", " \"Fast: amount / mol\": [fast_state.amounts[j] for j in fast_order],\n", "}))\n", "work = [\"energy_evaluations\", \"root_evaluations\", \"trial_tangent_plane_iterations\"]\n", "display(pd.DataFrame(\n", " {mode: [state.discovery.work.get(name, 0) for name in work]\n", " for mode, state in ((\"Full\", discovered_state), (\"Fast\", fast_state))},\n", " index=[\"Helmholtz evaluations\", \"Density-root evaluations\", \"Tangent-plane iterations\"],\n", "))\n", "display(pd.DataFrame({\"Unsearched in fast mode\": fast_state.discovery.unsearched}))" ] }, { "cell_type": "markdown", "id": "cell-05", "metadata": {}, "source": [ "## Meaning and limits\n", "\n", "\n", "No witness found in a finite trial set is finite-search evidence. It is not\n", "a global stability certificate. This neutral subset does not compare measured\n", "salt-containing tie-lines, and no experimental uncertainty is estimated here.\n", "\n", "Fast mode returned a locally admitted two-phase state that matches full\n", "discovery within the stated tolerance. Fast mode does not test the returned\n", "split for stability after the flash, so its stability is unsearched here.\n" ] } ], "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.13.14" } }, "nbformat": 4, "nbformat_minor": 5 }