docs: move the VLE physics equations to the example page; fix a grammar slip

docs/index.md

@@ -9,7 +9,7 @@ knowledge is encoded through priors on the GP hyperparameters; new data is chose
 maximizing the predictive differential entropy of the resulting hierarchical
 posterior, so *hyperparameter uncertainty* -- not just predictive variance -- drives
 data acquisition. Many other adaptive sampling methods in literature use the GP's predictive variance 
-and ignore uncertainty in the hyperparameters themselves, which (we argue) matters most exactly when data is scarce.
+and ignore uncertainty in the hyperparameters themselves, which (we argue) matters most exactly when data are scarce.
 BITS for GAPS addresses this limitation.
 
 ```{admonition} Reference

docs/theory.md

@@ -231,36 +231,10 @@ grid) and {func}`bits_for_gaps.mixture.predict_grid_2D` (full-grid GP posterior
 samples for plotting). Both raise a clear error outside $d=2$ rather than silently
 producing something wrong.
 
-## The example: extended Raoult's law and Gibbs-Duhem
+## Where the example's own physics lives
 
-{doc}`vle_example` walks through the paper's H2O-PrOH case study end to end; two
-equations from the paper's phase-equilibrium model are worth stating explicitly
-since they're implemented directly (not through `bits_for_gaps` itself, which never
-sees the underlying VLE physics -- only the black-box PrOH activity coefficient it
-designs experiments for).
-
-Extended Raoult's law relates each vapor-phase partial pressure to the liquid
-composition, activity coefficient, and pure-component vapor pressure
-(`phase_diagram.eqm_residual`, `phase_diagram.dew_point_vapor_fraction`):
-
-$$z_b^{(v)} P = z_b^{(\ell)}\, \gamma_b\, P_b^* \tag{10}$$
-
-The GP surrogate models only $\gamma_{\mathrm{PrOH}}(z, T)$; the water coefficient is
-*derived* from it via the binary Gibbs-Duhem relation
-($z_1\, \mathrm{d}\ln\gamma_1 + z_2\, \mathrm{d}\ln\gamma_2 = 0$), integrated from a
-dilute reference state (`gibbs_duhem.gamma_water_from_gamma_proh`):
-
-$$\ln \gamma_2(z_1) = -\int_{\ln\gamma_1(0)}^{\ln\gamma_1(z_1)}
-\frac{z_1}{1 - z_1}\, \mathrm{d}\ln\gamma_1 \tag{11}$$
-
-The McCabe-Thiele column solver's stage balances and condenser/reboiler closures
-(`distillation.solve_column`) are given in full in **SI-4** ("Binary Distillation
-Model and Solution Procedure"); at constant molar overflow, the top/bottom closures
-are:
-
-$$L_0 = R D, \qquad V_1 = L_0 + D, \qquad L_n = V_{n+1} + W, \qquad
-x_D = x_0, \qquad x_W = x_n$$
-
-with the vapor-liquid equilibrium relation $y_i = \phi(x_i)$ on each stage $i$
-supplied by `equilibrium.make_equilibrium_function` (a cubic interpolant of the
-Eq (10) equilibrium curve).
+The paper's VLE case study layers its own thermodynamics on top of this method --
+extended Raoult's law, the Gibbs-Duhem relation, and the McCabe-Thiele column model
+(Eqs (10)-(11) and SI-4). Those equations are stated on the {doc}`vle_example` page
+rather than here, because `bits_for_gaps` never sees them: the package only ever sees
+the black-box activity coefficient it is designing experiments for.

docs/vle_example.md

@@ -32,6 +32,38 @@ repo and following the linked README.
    solver, given the phase diagram's liquid-vapor equilibrium curve and a column
    specification (feed composition, reflux ratio, product purities).
 
+## The governing equations
+
+Three equations from the paper's phase-equilibrium model are implemented directly
+here, outside `bits_for_gaps` itself -- the package never sees the underlying VLE
+physics, only the black-box PrOH activity coefficient it designs experiments for.
+
+Extended Raoult's law relates each vapor-phase partial pressure to the liquid
+composition, activity coefficient, and pure-component vapor pressure
+(`phase_diagram.eqm_residual`, `phase_diagram.dew_point_vapor_fraction`):
+
+$$z_b^{(v)} P = z_b^{(\ell)}\, \gamma_b\, P_b^* \tag{10}$$
+
+The GP surrogate models only $\gamma_{\mathrm{PrOH}}(z, T)$; the water coefficient is
+*derived* from it via the binary Gibbs-Duhem relation
+($z_1\, \mathrm{d}\ln\gamma_1 + z_2\, \mathrm{d}\ln\gamma_2 = 0$), integrated from a
+dilute reference state (`gibbs_duhem.gamma_water_from_gamma_proh`):
+
+$$\ln \gamma_2(z_1) = -\int_{\ln\gamma_1(0)}^{\ln\gamma_1(z_1)}
+\frac{z_1}{1 - z_1}\, \mathrm{d}\ln\gamma_1 \tag{11}$$
+
+The McCabe-Thiele column solver's stage balances and condenser/reboiler closures
+(`distillation.solve_column`) are given in full in **SI-4** ("Binary Distillation
+Model and Solution Procedure"); at constant molar overflow, the top/bottom closures
+are:
+
+$$L_0 = R D, \qquad V_1 = L_0 + D, \qquad L_n = V_{n+1} + W, \qquad
+x_D = x_0, \qquad x_W = x_n$$
+
+with the vapor-liquid equilibrium relation $y_i = \phi(x_i)$ on each stage $i$
+supplied by `equilibrium.make_equilibrium_function` (a cubic interpolant of the
+Eq (10) equilibrium curve).
+
 ## Wiring it to `bits_for_gaps`
 
 `run_case_study.py` ties the pieces together: a Latin-hypercube initial design over