[Epic] Integrate the MultiPhaseVessel architecture

[andres9403]

Goal

Integrate the MultiPhaseVesselRefactor branch into master via an author-led
rebase, with enough evidence that the change is safe for the physical models.

Why this needs an epic

Verified 2026-07-31: the branch is 47 commits ahead and 263 behind master, with
merge base d6eaf85 dated 2024-05-17 (~2.2 years). It changes 25 files,
~5,925 additions / 1,122 deletions, and adds zero test files. It has no PR.
It rewrites Phases.py (+344/-838), Streams.py, MixedPhases.py, and adds
MultiPhaseVessel.py (+1,601), Mechanisms.py, IntegratorBackends.py,
DataClasses.py, Classifier.py.

The textual conflict surface is currently small (6 files: .gitignore,
Commons.py, Drying_Model.py, Kinetics.py, Phases.py, requirements.txt)
because the crystallizer/reactor/kinetics fixes are still unmerged in open PRs.
Every PR that lands after a rebase forces another rebase.

The risk is semantic, not textual: Phases.py diverged only 9 lines on master,
yet the branch deletes 838 lines of it written against 2024 semantics. Git will
merge that cleanly and silently drop the reasoning behind #18 / PR #100.

Acceptance gates

• G1 Hygiene - no _old/_refactor/Tester.py/.vscode files; root __init__.py restored
• G2 Architecture - written decision on MultiPhaseVessel vs StateLayout (State vectors rely on memorized positional order across unit operations — introduce a single source of truth (StateLayout) #118); Units-and-basis correctness strategy: canonical registry, boundary validation, and balance tests (not Pint in the core) #133 units/basis reconciled
• G3 Sync - rebased on a master no more than 7 days old; CI green
• G4 API compatibility - explicit list of public-API, state-shape, and stream-semantics changes, with migration notes
• G5 Scientific regression - numerical before/after for at least one crystallizer, one reactor, and one flowsheet, with documented tolerances
• G6 Tests - unit tests for MultiPhaseVessel, MixedPhases, DataClasses
• G7 Fix preservation - every merged fix touching rewritten files re-verified, Critical: [Phases] VaporPhase mass-basis enthalpy weights latent heat by mole fraction #18 / PR Fix VaporPhase mass-basis latent heat weighting #100 explicitly
• G8 Docs - migration guide and updated examples; docs build green
• G9 Post-merge - full suite green; 1.0.0b1 tagged; documentation builds for the tag

Sequence

1. Preserve the tip: tag archive/mpv-refactor-20260731 at 435971ca6471d1ffbed9f25c641ceba7a0ada46e before any rebase
2. Drain the open PR queue first (Fix semibatch reactor energy flow term #102, Fix crystallizer energy balance units and jacket paths #106, Fix reactor mode crash paths #107, Fix reversible reaction Jacobian #114, Fix BatchCryst concentration Jacobian sign #115, Replace bare except clauses with specific exceptions #126, Publish reproducible PharmaPy documentation #131, Make optional Assimulo imports lazy #135)
3. Freeze refactors (not fixes) on Phases/Streams/MixedPhases/Crystallizers/Kinetics/ThermoModule
4. Author rebases, excluding non-production artifacts
5. Split into a reviewable PR stack
6. Post-merge stabilization

Decision deadline

End of Month 3. If a rebased PR satisfying G1+G3 is not open by then, fall back
to staged extraction: cherry-pick the reactive-crystallization work (commits 1-37,
2024-03 to 2026-04) and re-plan the architecture natively.

Blocked until decided: #118, #142, #143, #144, #145, #133, #12, #10.

Effort

8-14 FTE-weeks of maintainer review, verification, and integration. The branch
author's implementation effort is tracked separately.

[andres9403]

Opening this for decision

Three questions need answers before work can be sequenced around this epic. All
three have a decision deadline of end of Month 3 (2026-09-30), after which
the fallback in the issue body applies.

1. Rebase commitment and timeline — @ZacharyHillman18

The branch is 47 commits ahead and 263 behind, with merge base d6eaf85 dated
2024-05-17. Reading the commit history, it looks like two distinct programs:
commits 1-37 (2024-03 to 2026-04) are reactive-crystallizer modelling, and only
commits 38-47 (2026-07-10 onward) are the MultiPhaseVessel/Phases/Streams
rewrite.

• Can you commit to rebasing onto current master, dropping the
  _old/_refactor/Tester.py/.vscode files, and adding tests?
• What is a realistic date, and what support would help?
• How long will you be available afterwards to answer design questions and
  respond to review?

The tip is preserved at tag archive/mpv-refactor-20260731, so nothing is lost
whatever we decide.

Please do not rebase yet. Eight PRs are open against master and five of
them touch files this branch rewrites (Kinetics.py, Crystallizers.py,
Reactors.py, Commons.py). If they merge after a rebase, you would have to
rebase again. Draining that queue first is on the Month-2 plan (#154).

2. Architecture: this branch or StateLayout (#118)? — @bernalde @andres9403

Both solve the same problem: state ordering should not be memorised positionally.
#118 has six sub-issues and a detailed design; this branch has a 1,601-line
MultiPhaseVessel.py. We cannot fund both. One should supersede the other,
and it should be written down before either proceeds.

#142, #143, #144, #145, #133, #12 and #10 are all held pending this decision.

3. Does this refactor set the next version number?

This is a breaking architecture change to Phases, Streams, and
MixedPhases, so it is the natural trigger for a major version.

There is currently a conflict: #146 records a decision dated 2026-07-31 that the
first PyPI release is 3.0.0, and release.yml plus the pypi environment
tag policy are already built around that. The milestones on this repository are
currently named 1.0.0a1 / 1.0.0b1 / 1.0.0 / 1.1.0.

Whichever we choose, this epic should land in the milestone that carries the
breaking change, and the release notes need to state the version's provenance
explicitly — the repository has a historical v.1.0.0 tag and no v2 tag, while
a published paper describes "PharmaPy 2.0" whose code is not in this
distribution.

What is not in question

The acceptance gates in the issue body (G1-G9) apply regardless of the answers
above. The one worth flagging early is G5: the branch currently adds zero
test files across ~5,925 changed lines, and it rewrites Phases.py from a
2024 base. Phases.py has only diverged by 9 lines on master since then, so
git will merge it cleanly and silently discard the reasoning behind #18 / PR
#100. A clean merge is not evidence of a safe merge.

#149 exists to write mass- and energy-closure tests against master before
this lands, so G5 has something objective to check against.