{
"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",
" Declared water fraction / 1 | \n",
" Discovered water fraction / 1 | \n",
" Declared amount / mol | \n",
"
\n",
" \n",
" \n",
" \n",
" | 0 | \n",
" 0.994375 | \n",
" 0.994375 | \n",
" 0.285318 | \n",
"
\n",
" \n",
" | 1 | \n",
" 0.442556 | \n",
" 0.442556 | \n",
" 0.714682 | \n",
"
\n",
" \n",
"
\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",
" Temperature / K | \n",
" Pressure / Pa | \n",
" Phase amounts / mol | \n",
" Mole fractions / 1 | \n",
" Phase densities / mol m^-3 | \n",
" Maximum classified residual / 1 | \n",
" Linear solver | \n",
"
\n",
" \n",
" \n",
" \n",
" | Declared | \n",
" 293.15 | \n",
" 100000.0 | \n",
" [0.2853182931107769, 0.7146817068892232] | \n",
" [0.9943748683039002, 0.005625131696099895, 0.4425559753585558, 0.5574440246414442] | \n",
" [54198.3600462764, 16912.29929663858] | \n",
" 2.073248e-14 | \n",
" | \n",
"
\n",
" \n",
" | Discovered | \n",
" 293.15 | \n",
" 100000.0 | \n",
" [0.7146817068892205, 0.28531829311077944] | \n",
" [0.44255597535855395, 0.557444024641446, 0.9943748683038998, 0.005625131696100154] | \n",
" [16912.299296638528, 54198.360046276364] | \n",
" 1.704286e-14 | \n",
" | \n",
"
\n",
" \n",
"
\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",
" Component | \n",
" Component balance error / mol | \n",
"
\n",
" \n",
" \n",
" \n",
" | 0 | \n",
" water | \n",
" -1.110223e-16 | \n",
"
\n",
" \n",
" | 1 | \n",
" isobutanol | \n",
" 0.000000e+00 | \n",
"
\n",
" \n",
"
\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",
" Trials / 1 | \n",
" Unresolved trials / 1 | \n",
" Completed | \n",
" Message | \n",
"
\n",
" \n",
" \n",
" \n",
" | 0 | \n",
" 7 | \n",
" 0 | \n",
" True | \n",
" no witness in the recorded trial set; unresolved trials 0 | \n",
"
\n",
" \n",
"
\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",
" Trial evidence | \n",
"
\n",
" \n",
" \n",
" \n",
" | 0 | \n",
" no_resolved_descent | \n",
"
\n",
" \n",
" | 1 | \n",
" no_resolved_descent | \n",
"
\n",
" \n",
" | 2 | \n",
" no_resolved_descent | \n",
"
\n",
" \n",
" | 3 | \n",
" no_resolved_descent | \n",
"
\n",
" \n",
" | 4 | \n",
" no_resolved_descent | \n",
"
\n",
" \n",
" | 5 | \n",
" no_resolved_descent | \n",
"
\n",
" \n",
" | 6 | \n",
" no_resolved_descent | \n",
"
\n",
" \n",
"
\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",
" Full: water fraction / 1 | \n",
" Fast: water fraction / 1 | \n",
" Full: amount / mol | \n",
" Fast: amount / mol | \n",
"
\n",
" \n",
" \n",
" \n",
" | 0 | \n",
" 0.442556 | \n",
" 0.442556 | \n",
" 0.714682 | \n",
" 0.714682 | \n",
"
\n",
" \n",
" | 1 | \n",
" 0.994375 | \n",
" 0.994375 | \n",
" 0.285318 | \n",
" 0.285318 | \n",
"
\n",
" \n",
"
\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",
" Full | \n",
" Fast | \n",
"
\n",
" \n",
" \n",
" \n",
" | Helmholtz evaluations | \n",
" 1096.0 | \n",
" 197.0 | \n",
"
\n",
" \n",
" | Density-root evaluations | \n",
" 829.0 | \n",
" 133.0 | \n",
"
\n",
" \n",
" | Tangent-plane iterations | \n",
" 95.0 | \n",
" 7.0 | \n",
"
\n",
" \n",
"
\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",
" Unsearched in fast mode | \n",
"
\n",
" \n",
" \n",
" \n",
" | 0 | \n",
" removed-phase starts and retries | \n",
"
\n",
" \n",
" | 1 | \n",
" alternative descending additions | \n",
"
\n",
" \n",
" | 2 | \n",
" post-flash stability | \n",
"
\n",
" \n",
" | 3 | \n",
" three-or-more-phase topologies | \n",
"
\n",
" \n",
" | 4 | \n",
" Liquid/0,1,/positive-neutral-base | \n",
"
\n",
" \n",
" | 5 | \n",
" Liquid/0,1,/near-pure-1 | \n",
"
\n",
" \n",
" | 6 | \n",
" Vapor/0,1,/positive-neutral-base | \n",
"
\n",
" \n",
" | 7 | \n",
" Vapor/0,1,/near-pure-0 | \n",
"
\n",
" \n",
" | 8 | \n",
" Vapor/0,1,/near-pure-1 | \n",
"
\n",
" \n",
" | 9 | \n",
" Vapor/0,1,/ideal-gas | \n",
"
\n",
" \n",
"
\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
}