Surface boundary conditions
How does the entropy solver close the heat flow at the top of the mantle?
The setting outer_boundary_condition in [boundary_conditions] picks the mode. The entropy solver implements 3 modes: 1, 4 and 5. The parser also accepts mode 2, for which the NumPy path applies no surface condition (the surface face carries the flux of the gradient copied from the cell below) and the JAX path reads outer_boundary_value as a flux, so do not use it; mode 3 is refused. Modes 1 and 4 set the heat flux through the surface. Mode 5 sets the temperature at the surface, and the heat flux then follows from the temperature difference between the surface and the top cell. The other surface values (outer_boundary_value, emissivity, equilibrium_temperature, param_utbl) are inputs of these modes.
The three modes
outer_boundary_condition |
What it sets | outer_boundary_value |
Typical use |
|---|---|---|---|
| 1 | Grey-body flux \(F = \varepsilon \sigma (T_\mathrm{top}^4 - T_\mathrm{eq}^4)\) from the temperature of the surface node | not used | standalone runs with a simple atmosphere |
| 4 | The surface flux itself | flux [W/mยฒ] | PROTEUS coupling: the atmosphere module gives the flux |
| 5 | The surface temperature | temperature [K] | benchmarks with a fixed surface temperature, such as stagnant-lid scaling cases |
Here \(\varepsilon\) is the emissivity, \(\sigma\) the Stefan-Boltzmann constant, \(T_\mathrm{top}\) the temperature of the surface node and \(T_\mathrm{eq}\) the equilibrium temperature. With subgrid_lid = true (mode 1 only), a crust thinner than the top cell sits on the surface and the grey body radiates from the crust surface; see Surface lid. The UTBL parameterisation only acts in mode 1, and the lid refuses it. PROTEUS uses mode 4 (or mode 1); it does not use mode 5.
Prescribed surface temperature (mode 5)
The solver works with the specific entropy \(S\) [J/kg/K], not with the temperature \(T\) [K]. Mode 5 must therefore turn a prescribed temperature into an entropy and an entropy gradient at the surface node.
Short answer. At setup the solver finds the entropy \(S_s\) at which the equation of state (EOS) gives the prescribed temperature \(T_s\) at the surface pressure. At every call it gives the surface node this entropy, and it sets the entropy gradient at the node so that the temperature gradient is the difference between \(T_s\) and the top cell temperature over half a cell. The conductive flux through the surface is then exactly the half-cell conduction, and the convective flux uses the same gradient. Gravitational separation and chemical mixing carry no flux through the surface.
The surface entropy
The mantle grid has cell centres (the staggered nodes, where the solver keeps \(S\)) and cell faces (the basic nodes, where the fluxes are). The surface is the last basic node. Its pressure is \(P_s\) [Pa]. The solver solves \(T(P_s, S_s) = T_s\) for \(S_s\):
- with EOS tables, by a root search over the entropy range of the tables on the phase evaluator of the surface node, so that the value includes the property smoothing near the solidus and liquidus (
matprop_smooth_width). On the test tables a smoothing width of 0.2 moves the root by up to 72 J/kg/K from the unsmoothed table value (at 1130 K, scanned from 330 to 2999 K); - in the constant-properties mode, from the closed form \(S_s = S_\mathrm{ref} + c_p \ln(T_s / T_\mathrm{ref})\), with \(T_\mathrm{ref}\) [K] and \(S_\mathrm{ref}\) [J/kg/K] the reference temperature and entropy of that mode (
const_T_ref,const_S_ref).
The surface gradient
The mantle has \(N\) cells, numbered from 0 at the bottom. The centre of the top cell, number \(N-1\), has the temperature \(T_{N-1}\) [K]. It lies half a cell below the surface, at the distance \(\Delta r / 2\), with \(\Delta r\) [m] the width of the top cell. The temperature gradient across this half cell is
The solver needs an entropy gradient, not a temperature gradient. The two are related by the thermodynamic identity \((\partial T / \partial S)_P = T / c_p\), where \(c_p\) is the heat capacity [J/kg/K]:
So the solver sets the entropy gradient at the surface node to
The second term is the adiabatic gradient. \(T\) and \(c_p\) are taken at the surface node, whose temperature is \(T_s\). The heat capacity here has the same floor of 100 J/kg/K as the conductive flux, so the identity holds term by term.
The surface flux
The conductive flux is \(F_\mathrm{cond} = -k\,\partial T/\partial r\), with \(k\) the thermal conductivity [W/m/K]. With the gradient above it becomes
positive outward when the mantle is warmer than the surface. The convective flux of the mixing-length theory, \(\rho T \kappa_h (-\partial S / \partial r)\) with \(\rho\) the density [kg/mยณ] and \(\kappa_h\) the eddy diffusivity [mยฒ/s], uses the same entropy gradient. Mode 5 needs a mixing length of 0 at the surface node, as mixing_length_profile = 'nearest_boundary' gives: the convective flux there is then 0, as at a wall where the eddy velocity vanishes. With 'constant' the mixing length is a fixed share of the mantle depth everywhere (mixing_length_constant_fraction, 0.25 by default), and the surface face would carry an eddy flux, driven by the steep half-cell gradient, at a wall where none can pass; a negative eddy_diffusivity_thermal does the same, because it sets \(\kappa_h\) at every node, the surface node too. Mode 5 refuses both, and an eddy_diffusivity_thermal that is NaN or infinite. It accepts 'constant' with mixing_length_constant_fraction = 0, which gives a mixing length of 0 at every node. The floor of the eddy diffusivity (kappah_floor) lets molten cells mix below the convective threshold; it does not act at a surface held at its temperature.
Why the solver does not use an entropy difference
A simpler rule would take the entropy gradient as \((S_s - S_{N-1}) / (\Delta r / 2)\). Entropy is not linear in temperature, so this rule gives the wrong flux. With constant \(c_p\) it replaces \(T_{N-1} - T_s\) by \(T_s \ln(T_{N-1}/T_s)\). For a top cell at 380 K below a surface at 273 K, that is 90.3 K instead of 107 K, a flux 16 % too low.
The half-cell distance
The solver takes \(\Delta r / 2 = \Delta\xi / (2\, \mathrm{d}\xi/\mathrm{d}r)\), where \(\Delta\xi\) is the spacing of the top cell in the mesh coordinate \(\xi\) and \(\mathrm{d}\xi/\mathrm{d}r\) its derivative at the surface. On a mesh that is uniform in radius (mass_coordinates = false) this equals the distance from the top cell centre to the surface. On a mass-coordinate mesh the two differ: on a 19-cell Earth mantle the half cell is 91,797 m and the geometric distance 91,376 m, 0.46 % apart. The solver uses the first value on both meshes.
Limits
outer_boundary_valuemust be a positive finite number in kelvin. A string, a TOMLtrue, NaN, an infinity, zero or a negative value stops the setup with aValueError.- A temperature outside the range the phase evaluator reaches at the surface pressure stops the setup with a
ValueErrorthat gives the range and the smoothing width; the solver does not clamp it to the table edge. With smoothing this range can be narrower than the tables: at a width of 0.5 the test tables start at 363 K instead of 320 K. - With a smoothing width above 0, the smoothed temperature jumps where the melt fraction is 0.5. On the test tables, at the surface pressure of the test mesh (0 Pa), the jump is about 391 K ร exp(โ1/width): 2.6 K at a width of 0.2 (from 1633.8 to 1636.4 K), 0.5 K at 0.15, 0.02 K at 0.1, 0.006 K at 0.09, 2.4 ร 10โปโด K at 0.07, 8 ร 10โปโท K at 0.05, and about 2 ร 10โปยนยฒ K, the rounding level, at 0.03. No entropy gives a temperature inside the jump. For such a temperature the setup finds the entropy at the jump and accepts it when the nearer end of the jump lies within 10โปโน of the prescribed temperature: a temperature in the middle of the jump is accepted up to a width of about 0.054, one a quarter of the way in up to about 0.056. Above that width the setup stops with a
ValueError. A temperature at either end of the jump is accepted at every width. - These settings stop the setup with a
ValueError:param_utbl = true: the UTBL correction belongs to the grey-body flux.core_bc = 'gradient': the gradient core keeps its own surface gradient.energy.conduction = false: without conduction the prescribed temperature sets no flux.- a mixing length that is not 0 at the surface node, as with
mixing_length_profile = 'constant'and a fraction other than 0, and aneddy_diffusivity_thermalthat is negative, NaN or infinite: each puts an eddy flux on the surface face.
- On the JAX path,
BoundaryParamsrefusesparam_utbl = truewith type 5.solve_entropyand the JAX CVODE factory refuse conduction off, a mixing length that is not 0 at the surface node, aneddy_diffusivity_thermalthat is negative, NaN or infinite, and anS_surfwhose temperature at the surface pressure is more than 10โปโถ (relative) offouter_bc_value. The JAX right-hand sides (dSdt,dSdt_energy_balance,dSdt_core_module) andstep_powersdo not check these. The setup ofEntropySolverrefuses the conduction, mixing-length and eddy settings first. A factory that builds a stale pair ofS_surfandouter_bc_valueraises an error, which stopsEntropySolver.solve. - A caller can change
outer_boundary_valuebetween calls; the next call of the NumPy right-hand side, and the nextsolve, invert the surface entropy again. - The EOS floor (
eos_floor_marginabove 0, see Solver method tuning) watches the top cell in place of the surface node, which mode 5 holds at \(S_s\). - Every call of the NumPy right-hand side checks that the surface node is at \(T_s\) to a relative 10โปโถ and raises a
RuntimeErrorif it is not. - The JAX right-hand side takes the surface entropy and the half cell as
S_surfandsurf_dr_halfofBoundaryParamswithouter_bc_type = 5, and applies the same gradient, with the temperature of the surface node atS_surfin place of \(T_s\).S_surfalone sets the surface temperature: the right-hand side does not readouter_bc_value, so a new temperature needs a newS_surf.solve_entropyand the factory refuse a staleouter_bc_value; a direct call of the right-hand side does not.EntropySolver.surface_temperature_bcgives the surface entropy, the surface temperature (outer_bc_value) and the half cell; buildBoundaryParamsagain after a change ofouter_boundary_value.BoundaryParamsrefuses type 5 without a finiteS_surfand a positive finiteouter_bc_valueandsurf_dr_half.
Where this is checked. Surface boundary compares mode 5 with a steady heated shell, a cooling half space, and a grid-convergence study with convection, notes the comparison on the stored states of the stagnant-lid benchmarks, and the tutorial repeats the half-space case step by step.