Problem and setup
An MLP predicts three concentrations whose sum differs from the known feed. Compare ordinary training, a soft sum penalty, post-training projection, and training through a projection layer. The conserved sum is 1.2 mol/L in the hand example. Equality, nonnegativity, and individual steady-state balances are separate checks.
Extract the lab ZIP, keeping requirements.txt, the notebook, Python scripts, and supplied models together. These exercises were checked with Python 3.12. Use that folder as the working directory and run the commands below, or execute the notebook cells in order. Downloading the notebook alone can omit required scripts or model files.
python -m pip install -r requirements.txt
python guided_lab.py
guided_lab.py executes the calculations below in order and checks key values with assertions. Files in guided-results/ belong to your new run; compare them with the supplied reference results. For Jupyter, select a kernel from the same Python environment. For ModuleNotFoundError, check that requirements were installed in that environment. For missing local files, check the working directory.
1. Spread the excess equally
The raw sum is 0.70+0.45+0.25=1.40, exceeding feed by 0.20. In physical Euclidean distance, the smallest total squared correction subtracts 0.20/3 from every component. The sum then loses exactly 0.20.
from pathlib import Path
import numpy as np
import torch
import week04_lab as lab
raw = torch.tensor([[.70,.45,.25]], dtype=torch.float64, requires_grad=True)
feed = torch.tensor([[1.20]], dtype=torch.float64)
excess = raw.sum(-1, keepdim=True)-feed
corrected = lab.project(raw, feed)
print("sum excess, correction per component:", excess.item(), excess.item()/3)
print("projected:", corrected.detach().numpy())
np.testing.assert_allclose(corrected.detach(), [[19/30,23/60,11/60]])
np.testing.assert_allclose(corrected.detach().sum(1), [1.2])
The corrected vector is about [0.633333,0.383333,0.183333]. Equal physical corrections are generally unequal after dividing by different output scales, which is why project operates after conversion back to mol/L.
2. Trace one upstream gradient
The first corrected output is rawA−(rawA+rawB+rawC−feed)/3. Its derivatives with respect to raw A/B/C are 2/3,−1/3,−1/3. Increasing B makes the common correction larger and therefore reduces the corrected A.
corrected[0,0].backward()
print("raw gradient:", raw.grad.numpy())
np.testing.assert_allclose(raw.grad, [[2/3,-1/3,-1/3]])
checks = lab.mathematical_checks()
print("projection checks:", checks)
The gradient sums to zero: a common increase in all raw components is removed by projection. mathematical_checks also tests multiple independent equality rows, the analytic Jacobian, scaling, and inconsistent constraints.
3. Find what equality does not control
Start from [0.02,0.90,0.50]. Its excess is 0.22, so subtracting 0.22/3 makes A negative. Clamping the negative component to zero adds mass without reducing another component. This is a concrete reason to inspect more than the sum residual.
negative = lab.project(torch.tensor([[.02,.9,.5]], dtype=torch.float64), feed)
clamped = negative.clamp(min=0)
print("projected, minimum, clamped sum:", negative.tolist(), negative.min().item(), clamped.sum().item())
assert negative.min() < 0 and clamped.sum() > feed.item()
x = torch.tensor([[330.,5.,1.2]], dtype=torch.float64)
truth = lab.reference(x)
print("reference species balances:", lab.residuals(x, truth).tolist())
print("projected species balances:", lab.residuals(x, corrected.detach()).tolist())
A becomes −0.053333 mol/L and the clamped sum becomes 1.253333 mol/L. An exact sum alone also leaves individual reaction balances unconstrained. Compare all three residuals with the reference residuals near zero.
4. Run the controlled comparison
Keep the 900/300/300 split, initialization, batch order, and minimum-validation-MSE selection fixed. The soft loss adds lambda times squared sum error; post-projection changes an already trained model, whereas hard training backpropagates through project. Test metrics use physical units.
report = lab.run(Path("guided-results"), epochs=600, seed=404)
for mode, metrics in report["test"].items():
print(mode, "RMSE", metrics["rmse_all_mol_L"], "sum max", metrics["sum_max_mol_L"],
"minimum", metrics["minimum_mol_L"], "species residual RMS", metrics["species_residual_rms_mol_L_min"])
assert report["protocol"]["rows"] == [900,300,300]
A method can improve the sum while leaving concentration error or species residuals. Explain each column before ranking methods; this single seed does not establish a general ranking. For a new lambda comparison use run(…, soft_lambda=value, evaluate_test=False), compare training[“soft”][“validation_mse”], then evaluate test once after selection. Reconstruct one reported RMSE from saved rows as a follow-up.
Result figure
After running, open guided-results/comparison.png and relate it to the errors computed above.
What to report
Record the inputs, outputs, units and fixed conditions; your hand prediction; intermediate computed values; and final metrics with interpretation. Before changing one setting, predict the direction of its effect, then revise that explanation after execution. Record the environment and seed.