Skip to content

aragog.surface_lid

The aragog.surface_lid module holds the sub-grid surface lid: a conductive crust thinner than the top cell, carried as its thickness and its energy per area, with the temperature profile of the one-phase Stefan problem. The functions are pure; the solver evaluates the material properties and calls them in every right-hand side when subgrid_lid is on.

Name Role
shape Slopes at the top and the base and the mean of the profile \(f_s\) for the shape parameter \(s\).
surface_state Surface temperature, surface flux and base conduction of a lid under a grey-body surface.
fixed_surface_state The same for a fixed surface temperature.
effective_thickness Thickness of the linear lid with the same surface gradient.
convective_base_flux Boundary-layer flux of the melt under the lid at the critical Rayleigh number.
stefan_rate Growth rate of the lid base, with the growth stop and the melt-back stop.
existence_weight Weight of the lid from the thickness of a steady crust.
lid_rates Rates of the two lid states, the surface loss and the flux out of the melt.

For the physics, see Surface lid.

surface_lid

Sub-grid conductive lid at the surface of the top cell.

A crust thinner than the top cell cannot be resolved by the mesh. The lid model carries it as two states per unit area: the thickness delta [m] and the energy E_lid [J/m^2]. The temperature profile across the lid is taken from the similarity family of the one-phase Stefan problem (Neumann solution),

T(z) = T_s + (T_b - T_s) f_s(z / delta),
f_s(x) = erf(sqrt(s) x) / erf(sqrt(s))        (s > 0),
         x                                    (s = 0),
         erfi(sqrt(-s) x) / erfi(sqrt(-s))    (s < 0),

with the shape parameter s and the surface temperature T_s fixed by the lid energy, E_lid = delta int_0^1 H(T(x)) dx with H the heat content per volume of the lid material (:class:LidEnthalpy), and by the grey-body balance at the surface. The family holds the Neumann growth exactly (s = lambda^2) and reduces to the linear profile in steady state. Material joins the lid at its base by the Stefan condition (W(S_f) - W(S_b)) d(delta)/dt = q_b - F_b, where q_b is the conduction into the lid at its base, F_b the flux the fluid below delivers and W(S) = int rho T dS the heat content per volume at the top-cell pressure, at the fluid entropy S_f and the lid-base entropy S_b. The reported heat content of the mesh uses this measure; the lid holds it as a function of temperature, the same measure wherever the temperature rises with entropy (not inside a band of constant temperature below the solidus).

The functions here are pure: the solver evaluates the material properties, passes them in and assembles the rates. All quantities are SI (K, m, W/m^2, J/kg, J/m^2, J/m^3, kg/m^3, s).

References

Turcotte, D. L. and Schubert, G. (2014), Geodynamics, 3rd ed., Cambridge University Press: section 4.18, the Stefan problem (eqs. 4.136 and 4.141, pp. 197-198), and section 4.15, the cooling of a half-space (eq. 4.116, p. 189).

ConstantProperties(T_ref, S_ref, rho, cp) dataclass

The entropy-EOS calls of the lid for a constant-property column (phase_mixed.const_properties): T = T_ref exp((S - S_ref) / cp) [K] with constant density [kg/m^3] and heat capacity [J/kg/K], and no melt. The pressure is not used.

LidEnthalpy(H, rho, data=()) dataclass

Heat content per volume H(T) [J/m^3] and density rho(T) [kg/m^3] of the lid material at the top-cell pressure, both vectorised in T [K].

first_knot property

Lowest temperature [K] of the table behind H; -inf for constant properties.

linear(rho, cp, T_b, h_b) classmethod

Constant properties: H(T) = rho (h_b + cp (T - T_b)).

Source code in src/aragog/surface_lid.py
192
193
194
195
196
197
198
199
@classmethod
def linear(cls, rho: float, cp: float, T_b: float, h_b: float) -> LidEnthalpy:
    """Constant properties: ``H(T) = rho (h_b + cp (T - T_b))``."""
    return cls(
        H=lambda T: rho * (h_b + cp * (np.asarray(T, dtype=float) - T_b)),
        rho=lambda T: np.full(np.shape(T), rho),
        data=('linear', rho, cp, T_b, h_b),
    )

profile_density(s, T_s, T_b)

Mean density [kg/m^3] of a lid with shape s from T_s to T_b.

Source code in src/aragog/surface_lid.py
228
229
230
231
def profile_density(self, s: float, T_s: float, T_b: float) -> float:
    """Mean density [kg/m^3] of a lid with shape ``s`` from ``T_s`` to ``T_b``."""
    x, w = profile_nodes(s)
    return float(np.dot(w, self.rho(T_s + (T_b - T_s) * profile(s, x))))

profile_heat(s, T_s, T_b)

Mean heat content [J/m^3] of a lid with shape s from T_s to T_b.

Source code in src/aragog/surface_lid.py
223
224
225
226
def profile_heat(self, s: float, T_s: float, T_b: float) -> float:
    """Mean heat content [J/m^3] of a lid with shape ``s`` from ``T_s`` to ``T_b``."""
    x, w = profile_nodes(s)
    return float(np.dot(w, self.H(T_s + (T_b - T_s) * profile(s, x))))

table(T, H, rho) classmethod

From a table on increasing T: monotone cubic H, linear rho, both continued outside the table with the end slopes of H and constant rho.

Source code in src/aragog/surface_lid.py
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
@classmethod
def table(cls, T: npt.ArrayLike, H: npt.ArrayLike, rho: npt.ArrayLike) -> LidEnthalpy:
    """From a table on increasing ``T``: monotone cubic ``H``, linear ``rho``, both
    continued outside the table with the end slopes of ``H`` and constant ``rho``."""
    from scipy.interpolate import PchipInterpolator

    T, H, rho = (np.asarray(v, dtype=float) for v in (T, H, rho))
    spline = PchipInterpolator(T, H, extrapolate=False)
    slope = spline.derivative()
    lo, hi = (T[0], H[0], float(slope(T[0]))), (T[-1], H[-1], float(slope(T[-1])))

    def H_of(t):
        t = np.asarray(t, dtype=float)
        inside = np.clip(t, lo[0], hi[0])
        return np.where(
            t < lo[0],
            lo[1] + lo[2] * (t - lo[0]),
            np.where(t > hi[0], hi[1] + hi[2] * (t - hi[0]), spline(inside)),
        )

    return cls(H=H_of, rho=lambda t: np.interp(t, T, rho), data=('table', T, H, rho))

LidRates(ddelta, dE, F_top, F_fluid, w, stop, H_lid) dataclass

Rates and fluxes of the lid at one state.

Attributes:

Name Type Description
ddelta float

d(delta)/dt [m/s].

dE float

dE_lid/dt [W/m^2], internal heating of the lid included.

F_top float

Flux the planet loses at the surface [W/m^2].

F_fluid float

Flux out of the fluid at the top of the top cell [W/m^2], from energy conservation.

w float

Lid weight [0, 1].

stop float

Factor of the growth or melt-back stop [0, 1].

H_lid float

Internal heating of the lid [W/m^2].

LidSurface(T_s, F_s, q_b, s, clipped, T_m) dataclass

Surface solution of the lid at one state.

Attributes:

Name Type Description
T_s float

Surface temperature [K].

F_s float

Surface flux [W/m^2], positive out of the planet.

q_b float

Conduction into the lid at its base [W/m^2], positive upward.

s float

Shape parameter of the profile [-].

clipped int

0 when the root lies inside the shape bounds; +1 when the lid energy is too high for any profile (s at its upper bound), -1 when it is too low (s at its lower bound).

T_m float

Mean temperature of the profile [K].

convective_base_flux(dT, k, rho, cp, alpha, g, eta, ra_crit)

Boundary-layer flux [W/m^2] of a fluid dT [K] hotter than the lid base.

q = k dT^(4/3) (alpha rho g / (Ra_crit kappa eta))^(1/3) with kappa = k / (rho cp): the flux of a boundary layer at the critical Rayleigh number. Zero for dT <= 0.

Source code in src/aragog/surface_lid.py
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
def convective_base_flux(
    dT: float,
    k: float,
    rho: float,
    cp: float,
    alpha: float,
    g: float,
    eta: float,
    ra_crit: float,
) -> float:
    """Boundary-layer flux [W/m^2] of a fluid ``dT`` [K] hotter than the lid base.

    ``q = k dT^(4/3) (alpha rho g / (Ra_crit kappa eta))^(1/3)`` with ``kappa = k / (rho cp)``:
    the flux of a boundary layer at the critical Rayleigh number. Zero for ``dT <= 0``.
    """
    if dT <= 0.0:
        return 0.0
    kappa = k / (rho * cp)
    return k * dT ** (4.0 / 3.0) * (alpha * rho * g / (ra_crit * kappa * eta)) ** (1.0 / 3.0)

effective_thickness(delta, s)

Thickness [m] of the linear lid with the surface gradient of a lid of thickness delta and shape s: delta / f'(0). NaN at the lower shape bound, where f'(0) is 0.

Source code in src/aragog/surface_lid.py
234
235
236
237
238
def effective_thickness(delta: float, s: float) -> float:
    """Thickness [m] of the linear lid with the surface gradient of a lid of thickness ``delta``
    and shape ``s``: ``delta / f'(0)``. NaN at the lower shape bound, where ``f'(0)`` is 0."""
    slope = shape(s)[0]
    return delta / slope if slope > 0.0 else float('nan')

existence_weight(F_b, T_b, k, emissivity, T_eq, delta_on, T_surf=None)

Weight [0, 1] of the lid from the quasi-steady crust thickness.

A crust in steady state carries F_b by conduction, delta_eq = k (T_b - T_s) / F_b, with grey(T_s) = F_b, or T_s = T_surf [K] at a fixed surface temperature. The lid acts where delta_eq exceeds delta_on: w = (1 + tanh(log10(delta_eq / delta_on) / LID_EXIST_WIDTH)) / 2, set to 0 below LID_WEIGHT_FLOOR. A fluid that delivers over the grey flux at T_b, or a base not hotter than T_surf, carries no lid.

Source code in src/aragog/surface_lid.py
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
def existence_weight(
    F_b: float,
    T_b: float,
    k: float,
    emissivity: float,
    T_eq: float,
    delta_on: float,
    T_surf: float | None = None,
) -> float:
    """Weight [0, 1] of the lid from the quasi-steady crust thickness.

    A crust in steady state carries ``F_b`` by conduction, ``delta_eq = k (T_b - T_s) / F_b``,
    with ``grey(T_s) = F_b``, or ``T_s = T_surf`` [K] at a fixed surface temperature. The lid
    acts where ``delta_eq`` exceeds ``delta_on``:
    ``w = (1 + tanh(log10(delta_eq / delta_on) / LID_EXIST_WIDTH)) / 2``, set to 0 below
    ``LID_WEIGHT_FLOOR``. A fluid that delivers over the grey flux at ``T_b``, or a base not
    hotter than ``T_surf``, carries no lid.
    """
    if T_surf is not None and T_b <= T_surf:
        return 0.0
    if F_b <= 0.0:
        return 1.0
    if T_surf is not None:
        T_s = T_surf
    else:
        F_rad = grey_flux(T_b, emissivity, T_eq)
        if F_rad <= 0.0 or F_b >= F_rad:
            return 0.0
        T_s = (F_b / (emissivity * Stefan_Boltzmann) + T_eq**4) ** 0.25
    d_eq = k * (T_b - T_s) / F_b
    w = 0.5 * (1.0 + np.tanh(np.log10(d_eq / delta_on) / LID_EXIST_WIDTH))
    return float(w) if w > LID_WEIGHT_FLOOR else 0.0

fixed_surface_state(delta, E, T_b, k, T_s, delta_floor, hv)

Lid with a fixed surface temperature T_s [K]: the shape follows from Q(s) = E / delta at that surface temperature, held inside the shape bounds.

Parameters and the result as :func:surface_state.

Source code in src/aragog/surface_lid.py
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
def fixed_surface_state(
    delta: float,
    E: float,
    T_b: float,
    k: float,
    T_s: float,
    delta_floor: float,
    hv: LidEnthalpy,
) -> LidSurface:
    """Lid with a fixed surface temperature ``T_s`` [K]: the shape follows from
    ``Q(s) = E / delta`` at that surface temperature, held inside the shape bounds.

    Parameters and the result as :func:`surface_state`.
    """
    d = float(np.hypot(delta, delta_floor))
    q = E / max(delta, delta_floor)
    s, clipped = _shape_of_energy(q, lambda v: hv.profile_heat(v, T_s, T_b))
    return _surface(s, T_s, T_b, k, d, clipped)

floor_flux(phi_integral, h_top, delta)

Steady flux [W/m^2] of the eddy-diffusivity floor from the fluid to the lid base.

F = Phi / (0.5 (h_top - delta)), with Phi(S) = int_{S_sol}^{S} rho T kappa_floor f(phi) dS' [W/m], the Kirchhoff integral of the floor over entropy (f its melt-fraction weight), across half of the fluid part of the top cell. Lengths in m.

Source code in src/aragog/surface_lid.py
494
495
496
497
498
499
500
501
502
def floor_flux(phi_integral: float, h_top: float, delta: float) -> float:
    """Steady flux [W/m^2] of the eddy-diffusivity floor from the fluid to the lid base.

    ``F = Phi / (0.5 (h_top - delta))``, with
    ``Phi(S) = int_{S_sol}^{S} rho T kappa_floor f(phi) dS'`` [W/m], the Kirchhoff integral of
    the floor over entropy (``f`` its melt-fraction weight), across half of the fluid part of
    the top cell. Lengths in m.
    """
    return phi_integral / (0.5 * max(h_top - delta, 1.0e-3))

floor_weight(S_f, S_sol)

Weight [0, 1] of the base flux above the top-cell floor of the mush base.

The quintic ramp in x = (S_f - S_sol - LID_FLOOR_GAP) / LID_FLOOR_WIDTH, entropies in J/kg/K: 0 at and below the floor S_sol + LID_FLOOR_GAP, 1 from LID_FLOOR_WIDTH above it, and C2 at both ends.

Source code in src/aragog/surface_lid.py
483
484
485
486
487
488
489
490
491
def floor_weight(S_f: float, S_sol: float) -> float:
    """Weight [0, 1] of the base flux above the top-cell floor of the mush base.

    The quintic ramp in ``x = (S_f - S_sol - LID_FLOOR_GAP) / LID_FLOOR_WIDTH``, entropies in
    J/kg/K: 0 at and below the floor ``S_sol + LID_FLOOR_GAP``, 1 from ``LID_FLOOR_WIDTH`` above
    it, and C2 at both ends.
    """
    x = min(max((S_f - S_sol - LID_FLOOR_GAP) / LID_FLOOR_WIDTH, 0.0), 1.0)
    return x * x * x * (x * (6.0 * x - 15.0) + 10.0)

flux_surface_state(delta, E, T_b, k, F_atm, delta_floor, hv)

Lid under a prescribed surface flux F_atm [W/m^2]: for a shape s the conduction k (T_b - T_s) f'(0) / d = F_atm fixes the surface temperature, at least 1 K, and with it the lid heat content, so Q(s) = E / delta gives the shape. At 1 K the lid carries less than F_atm. The surface stays LID_DT_MIN below T_b, so that the profile keeps a temperature drop; :func:flux_weight gives such a lid no weight for F_atm <= 0.

Parameters and the result as :func:surface_state, with F_atm for the grey body.

Source code in src/aragog/surface_lid.py
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
def flux_surface_state(
    delta: float,
    E: float,
    T_b: float,
    k: float,
    F_atm: float,
    delta_floor: float,
    hv: LidEnthalpy,
) -> LidSurface:
    """Lid under a prescribed surface flux ``F_atm`` [W/m^2]: for a shape ``s`` the conduction
    ``k (T_b - T_s) f'(0) / d = F_atm`` fixes the surface temperature, at least 1 K, and with it
    the lid heat content, so ``Q(s) = E / delta`` gives the shape. At 1 K the lid carries less
    than ``F_atm``. The surface stays ``LID_DT_MIN`` below ``T_b``, so that the profile keeps a
    temperature drop; :func:`flux_weight` gives such a lid no weight for ``F_atm <= 0``.

    Parameters and the result as :func:`surface_state`, with ``F_atm`` for the grey body.
    """
    d = float(np.hypot(delta, delta_floor))
    q = E / max(delta, delta_floor)

    def T_s_of(v):
        T_s = T_b - max(F_atm, 0.0) * d / (k * max(shape(v)[0], 1.0e-30))
        return min(max(T_s, LID_T_S_MIN), T_b - LID_DT_MIN)

    s, clipped = _shape_of_energy(q, lambda v: hv.profile_heat(v, T_s_of(v), T_b))
    return _surface(s, T_s_of(s), T_b, k, d, clipped)

flux_weight(F_b, T_b, T_s, k, emissivity, T_eq, delta_on)

Weight [0, 1] of the lid under the surface T_s of the atmosphere.

It is :func:existence_weight of the steady crust under that surface, delta_eq = k (T_b - T_s) / F_b: 0 for T_s at or above T_b, 1 for F_b <= 0. For F_b > 0 the weight falls to 0 as T_s rises to T_b, so the lid has no step at the onset; for F_b <= 0 it steps from 1 to 0 at T_s = T_b.

Source code in src/aragog/surface_lid.py
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
def flux_weight(
    F_b: float,
    T_b: float,
    T_s: float,
    k: float,
    emissivity: float,
    T_eq: float,
    delta_on: float,
) -> float:
    """Weight [0, 1] of the lid under the surface ``T_s`` of the atmosphere.

    It is :func:`existence_weight` of the steady crust under that surface,
    ``delta_eq = k (T_b - T_s) / F_b``: 0 for ``T_s`` at or above ``T_b``, 1 for ``F_b <= 0``.
    For ``F_b > 0`` the weight falls to 0 as ``T_s`` rises to ``T_b``, so the lid has no step at
    the onset; for ``F_b <= 0`` it steps from 1 to 0 at ``T_s = T_b``.
    """
    return existence_weight(F_b, T_b, k, emissivity, T_eq, delta_on, T_surf=T_s)

grey_flux(T_s, emissivity, T_eq)

Grey-body flux [W/m^2] of a surface at T_s [K] against T_eq [K].

Source code in src/aragog/surface_lid.py
262
263
264
def grey_flux(T_s: float, emissivity: float, T_eq: float) -> float:
    """Grey-body flux [W/m^2] of a surface at ``T_s`` [K] against ``T_eq`` [K]."""
    return emissivity * Stefan_Boltzmann * (max(T_s, 0.0) ** 4 - T_eq**4)

grey_surface_temperature(f0, d, T_b, k, emissivity, T_eq)

Surface temperature [K] where grey(T_s) = k (T_b - T_s) f0 / d.

Newton from T_b: the residual is convex and increasing in T_s and non-negative at T_b, so the iterates fall monotonically to the root. T_b when T_b <= T_eq.

Source code in src/aragog/surface_lid.py
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
def grey_surface_temperature(
    f0: float, d: float, T_b: float, k: float, emissivity: float, T_eq: float
) -> float:
    """Surface temperature [K] where ``grey(T_s) = k (T_b - T_s) f0 / d``.

    Newton from ``T_b``: the residual is convex and increasing in ``T_s`` and non-negative at
    ``T_b``, so the iterates fall monotonically to the root. ``T_b`` when ``T_b <= T_eq``.
    """
    if T_b <= T_eq:
        return T_b
    c = k * f0 / d
    T = T_b
    for _ in range(100):
        g = grey_flux(T, emissivity, T_eq) - c * (T_b - T)
        step = g / (4.0 * emissivity * Stefan_Boltzmann * T**3 + c)
        T -= step
        if abs(step) <= 1e-13 * T:
            break
    return max(T, T_eq)

lid_rates(*, delta, E_lid, surf, F_b, F_grid, w, rho, H_f, T_b, H_b, hv, h_top, delta_lo, heating)

Assemble the lid rates and the fluid flux at one state.

Fluid of heat content H_f [J/m^3] per volume joins the lid at T_b with heat content H_b [J/m^3] per volume, so the Stefan rate releases H_f - H_b per volume; rho is the density at the lid base, which scales the floor of that jump. The lid acts with weight w; the hidden part 1 - w relaxes to the phantom lid (thickness delta_lo, linear profile) over LID_TAU_HIDDEN, and the surface then sees the grid flux F_grid. The fluid flux follows from the conservation of the energy of the fluid and the lid: F_fluid = F_top + dE - H_lid - H_f d(delta)/dt. Exact for any w and any stop.

Parameters:

Name Type Description Default
heating float

Internal heating per mass [W/kg] of the top cell, applied to the lid mass.

required
Source code in src/aragog/surface_lid.py
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
def lid_rates(
    *,
    delta: float,
    E_lid: float,
    surf: LidSurface,
    F_b: float,
    F_grid: float,
    w: float,
    rho: float,
    H_f: float,
    T_b: float,
    H_b: float,
    hv: LidEnthalpy,
    h_top: float,
    delta_lo: float,
    heating: float,
) -> LidRates:
    """Assemble the lid rates and the fluid flux at one state.

    Fluid of heat content ``H_f`` [J/m^3] per volume joins the lid at ``T_b`` with heat content
    ``H_b`` [J/m^3] per volume, so the Stefan rate releases ``H_f - H_b`` per volume; ``rho`` is
    the density at the lid base, which scales the floor of that jump. The lid acts with weight
    ``w``; the hidden part ``1 - w`` relaxes to the phantom lid (thickness ``delta_lo``, linear
    profile) over ``LID_TAU_HIDDEN``, and the surface then sees the grid flux ``F_grid``. The
    fluid flux follows from the conservation of the energy of the fluid and the lid:
    ``F_fluid = F_top + dE - H_lid - H_f d(delta)/dt``. Exact for any ``w`` and any stop.

    Parameters
    ----------
    heating : float
        Internal heating per mass [W/kg] of the top cell, applied to the lid mass.
    """
    r, stop = stefan_rate(surf.q_b, F_b, rho, (H_f - H_b) / rho, delta, h_top, delta_lo)
    E_ph = delta_lo * hv.profile_heat(0.0, surf.T_s, T_b)
    relax = (1.0 - w) / LID_TAU_HIDDEN
    ddelta = w * r - relax * (delta - delta_lo)
    H_lid = heating * delta * hv.profile_density(surf.s, surf.T_s, T_b)
    dE = w * (surf.q_b - surf.F_s + H_b * r) - relax * (E_lid - E_ph) + H_lid
    F_top = w * surf.F_s + (1.0 - w) * F_grid
    F_fluid = F_top + dE - H_lid - H_f * ddelta
    return LidRates(
        ddelta=ddelta, dE=dE, F_top=F_top, F_fluid=F_fluid, w=w, stop=stop, H_lid=H_lid
    )

linear_lid_surface(delta, T_b, k, emissivity, T_eq)

Surface temperature [K] of a steady lid: grey(T_s) = k (T_b - T_s) / delta.

Source code in src/aragog/surface_lid.py
451
452
453
454
455
456
457
458
459
def linear_lid_surface(
    delta: float, T_b: float, k: float, emissivity: float, T_eq: float
) -> float:
    """Surface temperature [K] of a steady lid: ``grey(T_s) = k (T_b - T_s) / delta``."""
    if T_b <= T_eq:
        return T_b
    return brentq(
        lambda T: grey_flux(T, emissivity, T_eq) - k * (T_b - T) / delta, T_eq, T_b, xtol=1e-12
    )

mush_base_flux(phi_integral, h_top, delta, F_in, g, q_conv)

Flux [W/m^2] from the mush into the lid base: the floor flux plus the boundary-layer flux q_conv, blended by the floor weight g to the flux from below F_in, given per unit area of the top face of the cell, so that g = 0 holds the fluid entropy.

Source code in src/aragog/surface_lid.py
505
506
507
508
509
510
511
def mush_base_flux(
    phi_integral: float, h_top: float, delta: float, F_in: float, g: float, q_conv: float
) -> float:
    """Flux [W/m^2] from the mush into the lid base: the floor flux plus the boundary-layer
    flux ``q_conv``, blended by the floor weight ``g`` to the flux from below ``F_in``, given
    per unit area of the top face of the cell, so that ``g = 0`` holds the fluid entropy."""
    return F_in + g * (floor_flux(phi_integral, h_top, delta) + q_conv - F_in)

profile(s, x)

The similarity profile f_s(x) on [0, 1] (series below |s| = 1e-6).

Source code in src/aragog/surface_lid.py
113
114
115
116
117
118
119
120
121
122
def profile(s: float, x: npt.ArrayLike) -> npt.NDArray:
    """The similarity profile f_s(x) on [0, 1] (series below ``|s| = 1e-6``)."""
    x = np.asarray(x, dtype=float)
    if abs(s) < _S_SERIES:
        return x + s * x * (1.0 - x * x) / 3.0
    if s > 0.0:
        mu = np.sqrt(s)
        return erf(mu * x) / erf(mu)
    nu = np.sqrt(-s)
    return np.exp(s * (1.0 - x * x)) * dawsn(nu * x) / dawsn(nu)

profile_nodes(s)

Quadrature nodes and weights on [0, 1] for integrals over the profile f_s.

Two segments split at c(s), which follows the steep part of the profile: min(1/2, 6 / sqrt(s)) for s > 0 (erf layer at the surface) and 1 - min(1/2, 15 / |s|) for s < 0 (exponential layer at the base); c is continuous in s. Each segment holds PROFILE_PANELS 16-point Gauss-Legendre panels: the table enthalpy has kinks at the EOS nodes, so the panels, not the order, set the error (about 3e-6 relative at worst on the test tables).

Source code in src/aragog/surface_lid.py
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
def profile_nodes(s: float) -> tuple[npt.NDArray, npt.NDArray]:
    """Quadrature nodes and weights on [0, 1] for integrals over the profile f_s.

    Two segments split at ``c(s)``, which follows the steep part of the profile:
    ``min(1/2, 6 / sqrt(s))`` for ``s > 0`` (erf layer at the surface) and
    ``1 - min(1/2, 15 / |s|)`` for ``s < 0`` (exponential layer at the base); ``c`` is
    continuous in ``s``. Each segment holds ``PROFILE_PANELS`` 16-point Gauss-Legendre panels:
    the table enthalpy has kinks at the EOS nodes, so the panels, not the order, set the error
    (about 3e-6 relative at worst on the test tables).
    """
    g, w = _GL16
    if s > 0.0:
        c = min(0.5, 6.0 / np.sqrt(s))
    elif s < 0.0:
        c = 1.0 - min(0.5, -15.0 / s)
    else:
        c = 0.5
    edges = np.concatenate(
        [np.linspace(0.0, c, PROFILE_PANELS + 1), np.linspace(c, 1.0, PROFILE_PANELS + 1)[1:]]
    )
    half = 0.5 * np.diff(edges)[:, None]
    x = (edges[:-1, None] + half * (g + 1.0)).ravel()
    return x, (half * w).ravel()

robin_surface_state(delta, E, T_b, k, C, Fp, T_held, delta_floor, hv)

Lid under the Robin flux C + Fp (T_s - T_held): for a shape s the conduction k (T_b - T_s) f'(0) / d equals that flux, which fixes the surface temperature (in the bounds of :func:flux_surface_state), and Q(s) = E / delta gives the shape. C is the cap [W/m^2], Fp the slope of the atmosphere flux [W/m^2/K] and T_held the held surface [K]. Fp = 0 is :func:flux_surface_state at C.

Parameters and the result as :func:surface_state.

Source code in src/aragog/surface_lid.py
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
def robin_surface_state(
    delta: float,
    E: float,
    T_b: float,
    k: float,
    C: float,
    Fp: float,
    T_held: float,
    delta_floor: float,
    hv: LidEnthalpy,
) -> LidSurface:
    """Lid under the Robin flux ``C + Fp (T_s - T_held)``: for a shape ``s`` the conduction
    ``k (T_b - T_s) f'(0) / d`` equals that flux, which fixes the surface temperature (in the
    bounds of :func:`flux_surface_state`), and ``Q(s) = E / delta`` gives the shape. ``C`` is the
    cap [W/m^2], ``Fp`` the slope of the atmosphere flux [W/m^2/K] and ``T_held`` the held surface
    [K]. ``Fp = 0`` is :func:`flux_surface_state` at ``C``.

    Parameters and the result as :func:`surface_state`.
    """
    if Fp == 0.0:
        return flux_surface_state(delta, E, T_b, k, C, delta_floor, hv)
    d = float(np.hypot(delta, delta_floor))
    q = E / max(delta, delta_floor)

    def T_s_of(v):
        # T_s = T_held + (G (T_b - T_held) - C) / (G + Fp), G = k f'(0) / d: no overflow at a large Fp
        G = k * max(shape(v)[0], 1.0e-30) / d
        T_s = T_held + (G * (T_b - T_held) - C) / (G + Fp)
        return min(max(T_s, LID_T_S_MIN), T_b - LID_DT_MIN)

    s, clipped = _shape_of_energy(q, lambda v: hv.profile_heat(v, T_s_of(v), T_b))
    return _surface(s, T_s_of(s), T_b, k, d, clipped)

shape(s)

Slopes at the top and the base, and the mean, of the similarity profile f_s.

Parameters:

Name Type Description Default
s float

Shape parameter [-]; s > 0 for a growing lid, s < 0 for a thinning lid.

required

Returns:

Type Description
tuple of float

(f'(0), f'(1), m): the dimensionless surface and base slopes and the mean of f on [0, 1]. s = 0 gives (1, 1, 1/2).

Source code in src/aragog/surface_lid.py
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
def shape(s: float) -> tuple[float, float, float]:
    """Slopes at the top and the base, and the mean, of the similarity profile f_s.

    Parameters
    ----------
    s : float
        Shape parameter [-]; ``s > 0`` for a growing lid, ``s < 0`` for a thinning lid.

    Returns
    -------
    tuple of float
        ``(f'(0), f'(1), m)``: the dimensionless surface and base slopes and the mean of f on
        [0, 1]. ``s = 0`` gives ``(1, 1, 1/2)``.
    """
    s = float(s)
    if abs(s) < _S_SERIES:
        return 1.0 + s / 3.0, 1.0 - 2.0 * s / 3.0, 0.5 + s / 12.0
    if s > 0.0:
        mu = np.sqrt(s)
        g = mu * np.sqrt(np.pi) * erf(mu)
        return 2.0 * s / g, 2.0 * s * np.exp(-s) / g, 1.0 + np.expm1(-s) / g
    nu = np.sqrt(-s)
    dw = dawsn(nu)
    return nu * np.exp(s) / dw, nu / dw, 1.0 + np.expm1(s) / (2.0 * nu * dw)

stefan_rate(q_b, F_b, rho, dh, delta, h_top, delta_lo)

Base growth rate [m/s] of the lid and the factor of the stop that acts.

r = (q_b - F_b) / (rho max(dh, LID_DH_MIN)). Growth stops linearly over [LID_CAP_FRAC - LID_CAP_WIDTH, LID_CAP_FRAC] h_top; melt-back stops linearly over [delta_lo, 2 delta_lo].

Returns:

Type Description
tuple of float

(r, factor): the rate after the stop and the stop factor in [0, 1].

Source code in src/aragog/surface_lid.py
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
def stefan_rate(
    q_b: float, F_b: float, rho: float, dh: float, delta: float, h_top: float, delta_lo: float
) -> tuple[float, float]:
    """Base growth rate [m/s] of the lid and the factor of the stop that acts.

    ``r = (q_b - F_b) / (rho max(dh, LID_DH_MIN))``. Growth stops linearly over
    ``[LID_CAP_FRAC - LID_CAP_WIDTH, LID_CAP_FRAC] h_top``; melt-back stops linearly over
    ``[delta_lo, 2 delta_lo]``.

    Returns
    -------
    tuple of float
        ``(r, factor)``: the rate after the stop and the stop factor in [0, 1].
    """
    r = (q_b - F_b) / (rho * max(dh, LID_DH_MIN))
    if r > 0.0:
        f = float(np.clip((LID_CAP_FRAC - delta / h_top) / LID_CAP_WIDTH, 0.0, 1.0))
    elif r < 0.0:
        f = float(np.clip((delta - delta_lo) / delta_lo, 0.0, 1.0))
    else:
        f = 1.0
    return r * f, f

surface_state(delta, E, T_b, k, emissivity, T_eq, delta_floor, hv)

Solve the grey-body surface of a lid with energy E [J/m^2].

For a shape s the grey-body balance grey(T_s) = k (T_b - T_s) f'(0) / d fixes the surface temperature, and with it the lid heat content Q(s) = int_0^1 H(T(x)) dx. Q rises with s, so Q(s) = E / delta has one root in the shape bounds.

Parameters:

Name Type Description Default
delta float

Lid thickness [m].

required
E float

Lid energy [J/m^2].

required
T_b float

Lid-base temperature [K].

required
k float

Lid thermal conductivity [W/m/K].

required
emissivity float

Surface emissivity [-].

required
T_eq float

Equilibrium temperature of the radiation balance [K].

required
delta_floor float

Conduction floor [m]: the flux uses hypot(delta, delta_floor); the heat content per volume uses max(delta, delta_floor).

required
hv LidEnthalpy

Heat content and density of the lid material.

required

Returns:

Type Description
LidSurface
Source code in src/aragog/surface_lid.py
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
def surface_state(
    delta: float,
    E: float,
    T_b: float,
    k: float,
    emissivity: float,
    T_eq: float,
    delta_floor: float,
    hv: LidEnthalpy,
) -> LidSurface:
    """Solve the grey-body surface of a lid with energy ``E`` [J/m^2].

    For a shape ``s`` the grey-body balance ``grey(T_s) = k (T_b - T_s) f'(0) / d`` fixes the
    surface temperature, and with it the lid heat content ``Q(s) = int_0^1 H(T(x)) dx``. ``Q``
    rises with ``s``, so ``Q(s) = E / delta`` has one root in the shape bounds.

    Parameters
    ----------
    delta : float
        Lid thickness [m].
    E : float
        Lid energy [J/m^2].
    T_b : float
        Lid-base temperature [K].
    k : float
        Lid thermal conductivity [W/m/K].
    emissivity : float
        Surface emissivity [-].
    T_eq : float
        Equilibrium temperature of the radiation balance [K].
    delta_floor : float
        Conduction floor [m]: the flux uses ``hypot(delta, delta_floor)``; the heat content
        per volume uses ``max(delta, delta_floor)``.
    hv : LidEnthalpy
        Heat content and density of the lid material.

    Returns
    -------
    LidSurface
    """
    d = float(np.hypot(delta, delta_floor))
    q = E / max(delta, delta_floor)

    def T_s_of(v):
        return grey_surface_temperature(shape(v)[0], d, T_b, k, emissivity, T_eq)

    s, clipped = _shape_of_energy(q, lambda v: hv.profile_heat(v, T_s_of(v), T_b))
    return _surface(s, T_s_of(s), T_b, k, d, clipped)