Mass balance & solver
CALLIOPE's prognostic equations are four nonlinear elemental mass-conservation constraints, one per solved element (H, C, N, S). This page documents the residual function, the solver strategy, the mass-from-pressure relations, and the convergence criterion of this "buffered" mode, where the oxygen fugacity is an input and oxygen mass is derived. CALLIOPE also offers an authoritative-oxygen mode where the system is closed by adding O as a fifth budget and treating \(\Delta\mathrm{IW}\) as an unknown; the two modes share all the physics functions and differ only in their unknown set.
The conservation system
For each element \(e \in \{\mathrm{H}, \mathrm{C}, \mathrm{N}, \mathrm{S}\}\) the conservation equation reads
where \(\mathbf{p} = (p_\mathrm{H_2O}, p_\mathrm{CO_2}, p_\mathrm{N_2}, p_\mathrm{S_2})\) is the four-vector of primary partial pressures in bar. The seven secondary partial pressures (and \(p_\mathrm{O_2}\)) are not independent variables: they are algebraic functions of \(\mathbf{p}\) via the equilibrium chemistry speciation tree. Oxygen is not conserved; it is set by the \(f_{\mathrm{O}_2}\) buffer and is allowed to leak in or out of the system as the speciation requires.
With a metal reservoir (metal_mass above zero), each of the 4 equations gains the mass of the element in the metal, \(D_e M_\mathrm{metal} w_e^\mathrm{melt}\), with \(D_e\) the partition coefficient on the mass basis and \(w_e^\mathrm{melt}\) the mass fraction in the melt. func adds this term through _core_masses, and _with_metal repeats the solve until \(D_e\) and the metal composition agree. See Metal reservoir.
The four-vector residual function is solve.func (shown here without the metal term):
def func(pin_arr, ddict, mass_target_d):
pin_dict = {'H2O': pin_arr[0], 'CO2': pin_arr[1],
'N2': pin_arr[2], 'S2': pin_arr[3]}
mass_atm_d = atmosphere_mass(pin_dict, ddict)
mass_int_d = dissolved_mass(pin_dict, ddict)
return [mass_atm_d[v] + mass_int_d[v] - mass_target_d[v]
for v in ('H', 'C', 'N', 'S')]
Atmospheric column mass
The relation between a species' surface partial pressure and its column mass follows directly from hydrostatic equilibrium under the assumption of a well-mixed atmosphere. Bower et al. (2019) 1 Equation (2) writes it as
where \(R_p\) is the planetary surface radius, \(\mu_v\) is the species molar mass, \(\bar\mu\) is the atmospheric mean molar mass weighted by partial pressure (atmosphere_mean_molar_mass() in solve.py), and \(g\) is the surface gravity. CALLIOPE stores partial pressures in bar, so the implementation carries the conversion factor \(1.0 \times 10^5\) Pa/bar:
mass_atm_d[key] = value * 1.0e5 / ddict['gravity']
mass_atm_d[key] *= 4.0 * np.pi * ddict['radius'] ** 2.0
mass_atm_d[key] *= molar_mass[key] / mu_atm
The mu_v / mu_atm ratio is the part Bower et al. (2019) 1 Β§4.1.1 emphasises was missing from the pre-2019 mass-balance formulations of Elkins-Tanton (2008) 3, Lebrun et al. (2013) 4, Salvador et al. (2017) 5, and Nikolaou et al. (2019) 6. Without it, multi-species atmospheres receive an unphysical bias in the inferred reservoir partitioning.
After computing per-species column masses, atmosphere_mass() aggregates them into per-element atomic masses by stoichiometric atom-counting:
times \(\mu_\mathrm{H}\), and analogously for C, N, O, and S. The factor-3 in NH\(_3\) and factor-4 in CH\(_4\) are exactly the cases the tests/test_stoichiometry.py::TestAtmosphericStoichiometry tests pin down (e.g. test_NH3_contributes_1_N_not_3 verifies that NH\(_3\) contributes 1 N atom not 3).
Dissolved mass
For each solubility-supported species, dissolved_mass() evaluates the per-species ppmw concentration via the chosen solubility law, then converts to absolute mass via the prefactor
where \(M_\mathrm{mantle}\) is the (molten + solid) silicate mantle mass and \(\Phi_\mathrm{global}\) is the global melt fraction. Setting \(\Phi_\mathrm{global} = 0\) disables solubility entirely; setting \(\Phi_\mathrm{global} = 1\) (fully molten) gives the maximum dissolved-mass contribution.
Like for atmospheric mass, the per-species dissolved masses are aggregated into per-element atomic masses. Note the asymmetry with the atmospheric path: CALLIOPE only includes a subset of species in the dissolved-mass tally (H\(_2\)O, CO\(_2\), CO, CH\(_4\), N\(_2\), S\(_2\)); the remaining species (H\(_2\), NH\(_3\), SO\(_2\), H\(_2\)S, O\(_2\)) are assumed to have negligible solubility, consistent with Bower et al. (2022) 2 Β§2.2.3.
Solver: hybrid Powell + trust-region with Monte-Carlo restart
equilibrium_atmosphere() wraps the residual evaluation in a robust outer loop:
- Initial guess: either the user-supplied
p_guess(if non-None), or a Monte-Carlo draw viaget_initial_pressures()that samples each primary partial pressure log-uniformly in \([10^{-12}, 10^5]\) bar. - Inner solve: alternates between
scipy.optimize.fsolve(default), which uses the MINPACK Powell hybrid algorithm and is the fastest path when the initial guess is in the right basin;scipy.optimize.minimizewithmethod='trust-constr'and bounds \([0, 10^7]\) bar, which is more robust to bad guesses but slower;- the alternation is gated by
opt_solver=True. PROTEUS setsopt_solver=Falseand stays onfsolve.
- Acceptance test: even if the solver flags
success, CALLIOPE re-evaluates the residual. A state is accepted only if every element closes to its own tolerance, \(|r_e| \le \max(r_\text{tol} \cdot m_e^\mathrm{target}, 10\,\mathrm{kg})\), as in the authoritative-O path. This catches the "false convergence" failure mode wherefsolvelands on a stationary point of the residual norm rather than a true zero. A looser scalar mass gate, \(\max_e |r_e| \le r_\text{tol} \cdot \max_e m_e^\mathrm{target} + a_\text{tol} + 10\) kg over the CHNOS elements (with each noble gas held to its own tolerance), decides which refused states may still return through the fallback of step 6. The scalar gate alone does not bound a budget far below the largest one: for H \(10^{12}\) kg, C \(5 \times 10^{19}\) kg, no N and S \(10^{18}\) kg it allows an H residual up to \(5 \times 10^{14}\) kg, 500 times the H budget. - Sign check:
fsolvehas no bounds, so a root can carry a negative primary partial pressure. The species are derived from the primaries before any of them is clipped, so a negative \(p_\mathrm{H_2O}\) gives a negative \(p_\mathrm{H_2}\) that still forms CH\(_4\) and H\(_2\)S (both use \(p_\mathrm{H_2}^2\)), and NH\(_3\) when \(p_\mathrm{N_2}\) is negative too. A negative \(p_\mathrm{CO_2}\), \(p_\mathrm{N_2}\) or \(p_\mathrm{S_2}\) alone forms nothing; this is the usual case for an element with no inventory. CALLIOPE clips the primaries of such a root at zero, re-evaluates the residual and judges the clipped state by the rules of step 3: it is accepted if every element closes, refused if not, and dropped (not even a fallback) if it fails the scalar mass gate. It then reports the clipped state. An inert negative primary moves no mass and changes nothing; dropping the CH\(_4\) and H\(_2\)S of a negative \(p_\mathrm{H_2O}\) removes their H, C and S, which the per-element test sees even when the scalar gate would not. For H \(10^{15}\) kg, C \(5 \times 10^{19}\) kg, N \(10^{17}\) kg and S \(10^{18}\) kg at IW+2 and 1500 K, cold starts reach roots that lose the H, either once clipped or already before, and the solve goes on to a root that keeps it. For a budget far below the others the restarts may not reach the root that keeps it, for example H \(10^{12}\) kg with C \(5 \times 10^{19}\) kg, no N and S \(10^{18}\) kg at the library tolerances (that root has \(p_\mathrm{H_2O} = 1.79 \times 10^{-17}\) bar), or S \(10^{14}\) kg with H \(10^{20}\) kg, C \(5 \times 10^{19}\) kg and no N at \(r_\text{tol} = 10^{-4}\) (\(p_\mathrm{S_2} = 2.507 \times 10^{-17}\) bar); both return through the fallback of step 6 and report the budget as lost. - Restart on rejection: if the inner solver, the acceptance test or a check of step 4 fails, draw a new Monte-Carlo guess and try again, up to
nguesstimes. - Hard failure: if
nguessrestarts all fail, raiseRuntimeError. The PROTEUS wrapper catches this and writes a status code 27 ("outgassing failure") into the run's status file. When an attempt was refused only because an element misses its own tolerance, and its state (clipped, for the sign check) still passes the scalar mass gate of step 3, CALLIOPE keeps it as a fallback. Of several such states it keeps the best: the one with fewer elements over tolerance, then the one with the smaller largest ratio of residual to tolerance. Once a fallback exists, the solve makes at mostFALLBACK_ATTEMPTS(100) more attempts. It then re-solves the fallback for its positive primaries with the zero ones held at zero, and keeps the result if it stays non-negative, passes the scalar mass gate and misses fewer elements (or the same ones by less). A clipped negative-pH2O root misses the S of the H2S it no longer forms; for H \(10^{12}\) kg as in step 4 the re-solve brings S from \(1.59 \times 10^{13}\) kg, above its \(10^{13}\) kg tolerance, to about \(10^3\) kg, and leaves H as the only element lost. If that state closes every element, the solve returns it as an accepted root, withfallbackFalse and no warning. Otherwise it returns the state, setsfallbacktoTruein the returned dictionary and logs a warning that lists each element whose residual is above its tolerance, with that residual, the tolerance and the budget. The warning is given on every such call, so each step of a coupled run that falls back is visible. A fallback can also return a trace budget that is not emptied: for S \(10^{15}\) kg with H \(10^{20}\) kg and C and N \(10^{17}\) kg in a fully molten mantle at 2500 K, IW+0 and the library tolerances, the restarts reach no root that closes S; the returned state misses the S tolerance by an amount that depends on the restart sequence, and the warning names S alone. The limit keeps an unreachable budget from costing every restart: for S \(10^{14}\) kg as in step 4 withnguess = 1000andopt_solver=False, a solve returns after about 100 attempts rather than 1000. It can also return a fallback for a budget that a later attempt would have closed: for H \(10^{15}\) kg as in step 4 at the same settings (\(a_\text{tol} = 10^{16}\) kg), most seeds meet a fallback before the root, and of seeds 0 to 29 the root came more than 100 attempts after the first fallback for 3 of 26 on the Hirschmann buffer and 4 of 22 on O'Neill. Those solves return the fallback with its warning: all their primaries are positive, so the polish leaves them as they are.
Why the Monte-Carlo restart is necessary
The residual function \(\mathbf{r}(\mathbf{p})\) has multiple physically valid roots when the elemental inventory is small enough that some species can be driven to numerical zero, and multiple physically invalid roots that come from the implicit positivity constraints not being explicitly enforced inside fsolve. The Powell hybrid algorithm has no notion of physical bounds and can happily walk off into negative-pressure territory if the initial guess is too far from the basin.
The Monte-Carlo restart and the sign check handle both pathologies. Sweeping log-uniformly over 17 orders of magnitude, the solver lands in the basin of the physically correct root from a starting point close enough that fsolve converges before any negative excursion occurs. Some invalid roots still close the mass balance through CH\(_4\) and H\(_2\)S, and the sign check rejects them: for a low-H, C-rich inventory (H \(10^{19}\) kg, C \(5 \times 10^{19}\) kg, N \(10^{17}\) kg, S \(10^{18}\) kg) at IW+2 and 1500 K, 20 of 100 cold starts (seeds 0 to 99, \(x_\text{tol} = 10^{-6}\), \(r_\text{tol} = 10^{-4}\), \(a_\text{tol} = 10^{16}\) kg) land on a root with a negative \(p_\mathrm{H_2O}\) and a surface pressure of 18.58 bar instead of 24.82 bar with these settings. With a good warm start (PROTEUS pattern), the first attempt succeeds in 99%+ of cases; without one, \(\sim 10\)-50 restarts are typical.
On the iteration caps
The 1500-iteration nsolve cap and the 7500-restart nguess cap in the library defaults are both deliberately loose: they bound the wall-time at \(\sim\)10 seconds per call for most inventories (a conservative ceiling; a trace H budget far below the mass bound can take minutes, see step 4) without cutting off pathological cases that genuinely need more attempts. The PROTEUS wrapper tightens both (\(n_\text{solve} = 3000\), \(n_\text{guess} = 1000\)) because the warm-start strategy makes the long tails irrelevant in normal operation. If you see the wrapper hit nguess = 1000, the upstream physics is broken, not the solver.
Convergence diagnostics
The result dictionary returned by equilibrium_atmosphere() includes H_res, C_res, N_res, S_res (residuals in kg). Their absolute values bound how well the elemental conservation was satisfied; their relative values \(|r_e| / m_e^\mathrm{target}\) should be \(\lesssim 10^{-5}\) for an rtol = 1e-5 solve.
solve.equilibrium_atmosphere also logs the chosen restart count count at DEBUG level. If count > 100 consistently across iterations, the warm-start is failing or the basin is genuinely degenerate; switch on print_result=True and re-run the failing case in isolation to inspect the convergence trajectory.
See also
- Authoritative-oxygen mode for the dual five-residual formulation where O is an input budget and \(\Delta\mathrm{IW}\) is the additional unknown.
- Equilibrium chemistry for the speciation tree that maps \(\mathbf{p}\) to all eleven partial pressures.
- Solubility laws for the form of \(X_i^\mathrm{melt}(p_i)\) in
dissolved_mass(). - Coupling to PROTEUS (theory) for how the wrapper builds
targetandddictfromhf_row. - API reference for
calliope.solve.
-
D. J. Bower, D. Kitzmann, A. S. Wolf, P. Sanan, C. Dorn, A. V. Oza, Linking the evolution of terrestrial interiors and an early outgassed atmosphere to astrophysical observations, Astronomy & Astrophysics, 631, A103, 2019. SciX. ↩↩
-
D. J. Bower, K. Hakim, P. A. Sossi, P. Sanan, Retention of water in terrestrial magma oceans and carbon-rich early atmospheres, The Planetary Science Journal, 3(4), 93, 2022. SciX. ↩
-
L. T. Elkins-Tanton, Linked magma ocean solidification and atmospheric growth for Earth and Mars, Earth and Planetary Science Letters, 271, 181β191, 2008. SciX. ↩
-
T. Lebrun, H. Massol, E. ChassefiΓ¨re, A. Davaille, E. Marcq, P. Sarda, F. Leblanc, G. Brandeis, Thermal evolution of an early magma ocean in interaction with the atmosphere, Journal of Geophysical Research: Planets, 118, 1155β1176, 2013. SciX. ↩
-
A. Salvador, H. Massol, A. Davaille, E. Marcq, P. Sarda, E. ChassefiΓ¨re, The relative influence of H\(_2\)O and CO\(_2\) on the primitive surface conditions and evolution of rocky planets, Journal of Geophysical Research: Planets, 122, 1458β1486, 2017. SciX. ↩
-
A. Nikolaou, N. Katyal, N. Tosi, M. Godolt, J. L. Grenfell, H. Rauer, What factors affect the duration and outgassing of the terrestrial magma ocean?, The Astrophysical Journal, 875, 11, 2019. SciX. ↩