Partition-law hook and strong-partition limit for phase-aware volatiles

[maraattia]

Description

Closes #65.

Adds a configurable partition-law hook upstream of VolatileProfile and ships the strong-partition limit as the first physical rule wired through it. The hook maps a bulk interior mass fraction $X_i$ and a partition rule into the $(w_\mathrm{liquid}, w_\mathrm{solid})$ pair that VolatileProfile already consumes, so dissolved volatiles can live in the silicate melt instead of being smeared uniformly across the mantle. The new path is opt-in: a new config key partition_rule defaults to "uniform", which reproduces the existing single-EOS-string mantle behavior byte-for-byte, so every existing config keeps running unchanged. Setting partition_rule = "strong" activates the new path.

What landed, by commit:

• e9c9938 — partition-law hook signature and the partition_rule config key, registered in config.py with default "uniform" and valid values ("uniform", "strong", "D_const", "solubility"). The "D_const" and "solubility" rules raise NotImplementedError; they are the documented extension points for the next issues.
• f40799f — strong-partition physics wired end-to-end: apply_partition_rule returns numerical values ($w_\mathrm{solid} = 0$, $w_\mathrm{liquid} = X_i / \phi_\mathrm{avg}$), build_partition_profile constructs a VolatileProfile from a mantle LayerMixture, calculate_mixed_density and its batch variant gained an optional volatile_profile kwarg for per-shell phi-aware blending, and solver.solve_strong_partition is the outer self-consistency loop on $\phi_\mathrm{avg}$. Dispatch happens in output.post_processing.
• 09bf448, c28c5d2 — the $\phi_\mathrm{avg}$ floor that keeps $w_\mathrm{liquid} \le 1$ is derived internally from $X_\mathrm{bulk}$ as $\mathrm{safety} \times \sum X_\mathrm{bulk}$ rather than passed as a kwarg; below the floor the rule falls back to uniform spread. The safety factor is a numerical margin ($1.01$), not a user-tunable knob.
• df22c9c — docs/Explanations/mixing.md documents the hook, the strong-partition rule, and where future partition rules plug in.
• 850501d — registers outer_solver and wall_timeout as [IterativeProcess] config keys and adds partition_rule, outer_solver, wall_timeout, relative_tolerance, and absolute_tolerance to the tools/grids/run_grid parameter map. The Newton outer solver already existed from refactor Interior refactor: JAX path, Newton outer, robustness hardening #59 but those keys were not TOML-settable; exposing them is what made the strong-partition validation deterministic.
• bd24597 — removes the strong-partition validation grid from the repo; it is a validation artifact, not a shipped input.

Key touchpoints: src/zalmoxis/mixing.py (hook, VolatileProfile blend, build_partition_profile), src/zalmoxis/solver.py (solve_strong_partition), src/zalmoxis/output.py (dispatch), src/zalmoxis/config.py (partition_rule registration), src/zalmoxis/structure_model.py, and input/default.toml (the single-fraction EOS strings stay as the uniform path; the strong path is opt-in).

Out of scope, tracked separately on #64: the $\mathrm{H_2}$ melt-partition / binodal-miscibility handoff, physically motivated partition coefficients and solubility laws, and the PROTEUS-side wrapper changes.

Validation of changes

Test configuration: Linux (kernel 6.8), Python 3.12, conda proteus environment.

Automated tests (all green locally):

• Unit tier (@pytest.mark.unit): tests/test_mixing.py, tests/test_config_validation.py, and tests/test_config_loaders.py cover strong-partition mass conservation against the mantle integral, the fully-molten and fully-solid limits, the ill-conditioned thin-melt-shell fallback, the partition_rule = "uniform" byte-for-byte no-regression against the current code path, and config validation accepting both rule names while rejecting unknown values.
• Smoke tier: tests/test_solve_strong_partition.py::TestSolveStrongPartitionSmoke runs a single 1 $M_\oplus$ full-solver case at 10% $\mathrm{H_2O}$ on partition_rule = "strong" end-to-end and converges the outer $\phi_\mathrm{avg}$ loop.

Standalone grid validation (closed 2026-05-26, Newton-tier verdict): a 96-cell grid spanning 1–10 $M_\oplus$ × {0, 5, 10, 20}% $\mathrm{H_2O}$ × {2000, 3000, 4000} K was run with the Newton outer solver (relative_tolerance = 1e-9, wall_timeout = 1200). All 96 cells converged tightly, with mantle mass-conservation error at most $7.1 \times 10^{-5}$ (90th percentile $3.7 \times 10^{-5}$). All 12 dry-pair null cells ($X_{\mathrm{H_2O}} = 0$, where the strong path short-circuits to the uniform path) reproduce $R_\mathrm{strong} = R_\mathrm{uniform}$ to machine precision. In the active-subset cells where the strong rule cleared the $\phi$ floor, $|R_\mathrm{strong} - R_\mathrm{uniform}| \le 1.06 \times 10^{-6}$ $R_\oplus$, and the $X_{\mathrm{H_2O}}$ and $T_\mathrm{surf}$ monotonicity checks pass at the $10^{-4}$ $R_\oplus$ tolerance.

The grid was run with the earlier floor $\phi_\mathrm{floor} = 1.2 \sum X$. The subsequent reduction to the shipped $1.01 \sum X$ was checked directly: only the $X_{\mathrm{H_2O}} = 0.20$ column had cells in the affected band ($1.01 X \le \phi_\mathrm{avg} < 1.2 X$), and rerunning the two candidates ($M = 5$ $M_\oplus$ / $T_\mathrm{surf} = 3000$ K and $M = 10$ $M_\oplus$ / $T_\mathrm{surf} = 4000$ K) leaves both bit-identical between the uniform and strong paths, since their self-consistent strong melt fraction settles below the $1.01$ floor. The floor reduction flips no cell, so the active subset, the published $\Delta R$ table, and every conclusion above carry over unchanged.

Conclusion: the strong-partition implementation is verified correct, namely deterministic, mass-conserving, monotonic, and stable at low melt fraction. The partition law's signal does not live in the structural radius at the present EOS fidelity (the volume-additive density closure is approximately linear in volatile mass fraction); its impact is expected to surface in the chemistry coupling (surface speciation and melt-driven outgassing), not in $R(M)$. This motivates the coupled-evolution direction rather than indicating a problem with the path.

The figures come from a focused follow-up I ran to check that this small signal is intrinsic, not an artifact of where the validation grid happened to sample. I first worked out analytically where the strong-partition radius signal should be largest. At fixed total water mass, moving water into the melt changes the planet volume in proportion to the mantle-mass-weighted covariance between the melt fraction $\phi(r)$ and the water–silicate specific-volume contrast, multiplied by a suppression factor that excludes vapor-phase water from the structural mixing. A nonzero signal therefore requires three conditions to hold in the same shells at once: a genuine melt-fraction gradient (a partially molten mantle, neither fully molten nor fully solid), water that is condensed rather than vapor (denser than the suppression-gate threshold), and water that is genuinely lighter than silicate at the local pressure. That argument, referred to as the heuristic below, predicts the signal is maximized for a low-mass planet (lower mantle pressures keep condensed water lighter relative to silicate), a partial-melt surface temperature (a real melt gradient rather than a uniformly molten mantle), and the largest water fraction that still clears the activation floor. That corner of parameter space is what the optimal region refers to; the two figures below probe it directly, and both confirm the signal stays far below any practical threshold there.

The two figures attached to this PR, from the optimal-region investigation, show why the radius signal is intrinsically small rather than merely under-sampled. The figure above traces the best active in-grid case (1 $M_\oplus$, $T_\mathrm{surf} = 2000$ K, $X_{\mathrm{H_2O}} = 0.20$). Across a single outer shell the water density jumps from vapor (about 0.1 kg m⁻³, one near-massless shell, below the 322 kg m⁻³ suppression gate) to condensed (about 470 kg m⁻³), then tracks within roughly 30% of silicate down to the core-mantle boundary where both exceed 12000 kg m⁻³, while the melt fraction falls from 1 at the surface to about 0.22 at depth. The mass-weighted signal contribution (bottom panel) is therefore confined to a thin shell at $P < 5$ GPa, where water has just condensed above the gate yet is still lighter than silicate, and it collapses to zero by about 10 GPa. There is essentially no mantle mass that is simultaneously molten, condensed, and volumetrically distinct from silicate, so concentrating water in the melt rearranges almost nothing the radius integral can see.

The figure above confirms this is not a sampling accident. Sweeping the three levers the heuristic identifies (planet mass 0.3 vs 1.0 $M_\oplus$, surface temperature 2000 vs 2500 K, suppression gate 322 vs 50 kg m⁻³) at fixed $X_{\mathrm{H_2O}} = 0.20$ leaves every configuration at $|R_\mathrm{strong} - R_\mathrm{uniform}| \le 2.3 \times 10^{-7}$ $R_\oplus$, at or below the integrator-noise floor and at least three orders of magnitude under the $10^{-3}$ $R_\oplus$ modeling bar. The fully molten 0.3 $M_\oplus$ / 2500 K cells collapse to about $10^{-10}$ $R_\oplus$ because the strong rule reproduces uniform once $\phi(r) = 1$ everywhere, and relaxing the gate from 322 to 50 kg m⁻³ changes nothing, since the vapor-to-condensed transition is a near-discontinuity in this EOS and the density window the relaxed gate would rescue holds no mantle mass. The actionable consequence is that a measurable melt-localized-volatile radius signature needs a treatment that keeps dissolved water volumetrically distinct from silicate at mantle conditions (an explicit low-density hydrous-melt phase or a partial-molar-volume model), which is exactly what the deferred D_const and solubility rules are positioned to carry.

Checklist

• I have followed the contributing guidelines
• My code follows the style guidelines of this project
• I have performed a self-review of my code
• My changes generate no new warnings or errors
• I have checked that the tests still pass on my computer
• I have updated the docs, as appropriate
• I have added tests for these changes, as appropriate
• I have checked that all dependencies have been updated, as required

@timlichtenberg

[Copilot]

Pull request overview

This PR adds an opt-in partition-law interface upstream of VolatileProfile so mantle volatiles can be distributed between melt and solid phases as a function of melt fraction, and wires in the “strong partition” limit as the first implemented physical rule. It keeps backward compatibility by defaulting partition_rule to "uniform" (preserving the existing uniform mantle-fraction behavior).

Changes:

• Introduces partition_rule config plumbing ("uniform" default) and dispatch in output.post_processing to route "strong" to a dedicated outer solver loop.
• Implements phi-aware mantle blending by threading an optional volatile_profile into density mixing and the structure solve; adds solve_strong_partition() to converge self-consistent mantle-averaged melt fraction.
• Adds unit + smoke tests for the partition hook, strong-partition outer loop behavior, and config loading/validation; updates docs to explain the new interface and rule set.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tools/grids/run_grid.py	Exposes new config keys in grid runner parameter mapping.
tests/test_solve_strong_partition.py	Adds unit tests for the outer phi_avg loop and a PALEOS-gated smoke test.
tests/test_mixing.py	Adds unit coverage for partition hook, mantle inventory splitting, and profile builder.
tests/test_config_validation.py	Validates partition_rule accepted values and errors.
tests/test_config_loaders.py	Ensures loader defaults partition_rule to "uniform" and round-trips "strong".
src/zalmoxis/structure_model.py	Threads volatile_profile into ODE RHS and forces numpy fallback when JAX can’t support it.
src/zalmoxis/solver.py	Adds strong-partition outer loop and uses volatile_profile in density iteration paths.
src/zalmoxis/output.py	Dispatches solves based on partition_rule.
src/zalmoxis/mixing.py	Adds partition hook + builder and applies profile-driven per-shell fractions in mixing.
src/zalmoxis/config.py	Registers/loads partition_rule and additional iterative-process keys.
input/default.toml	Documents the new partition_rule option (opt-in).
docs/Explanations/mixing.md	Explains the partition-law hook, strong-partition rule, and extension points.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.