Skip to content

Core split

core_split

Core and mantle split of a bulk element inventory at one equilibration point.

The metal of mass M_metal equilibrates with a silicate of mass M_silicate at (P_eq, T_eq, dIW). For a mass-basis D_i the silicate mass fraction is w_i = M_i / (M_silicate + D_i M_metal), the core holds D_i M_metal w_i and the mantle M_silicate w_i. D_i depends on the metal and melt composition (interaction terms, mole bases), so the split is a fixed point on the metal composition. The laws come from :func:calliope.metal.get_law by name (:data:DEFAULT_LAWS) or as entries. dIW is the one redox input: a law with an FeO term (the S law) takes the melt FeO mole fraction X_FeO = x'_Fe 10^(dIW/2) of ideal mixing from the metal of the pass, and the melt oxides set only the silicate units of the mole bases.

A law outside its (P, T, dIW) range is evaluated at the given point, not clamped, and flagged with its distance per axis. O and Si are not split: their bulk is the O and Si of the rock, which CALLIOPE does not hold; their metal mass fractions enter as w_fixed. The exchange-K_D split of O and Si is not part of this module.

split_core_mantle(bulk_kg, M_metal, M_silicate, *, dIW, P_eq=P_EQ_GPA, T_eq=T_EQ_K, laws=None, w_fixed=None, oxides=KLB1, nbo_t=2.6)

Split the bulk mass of each element between core and mantle.

Parameters:

Name Type Description Default
bulk_kg dict

Bulk mass [kg] of each element to split, H, C, N or S (or any element of :data:calliope.metal.ELEMENTS with a D law); O and Si are refused.

required
M_metal float

Mass of the equilibrating metal [kg], >= 0; 0 evaluates no law and returns the bulk as mantle.

required
M_silicate float

Mass of the equilibrating silicate [kg], > 0.

required
dIW float

Oxygen fugacity of the equilibrium relative to the iron-wustite buffer [log10].

required
P_eq float

Equilibration pressure [GPa] and temperature [K], > 0.

P_EQ_GPA
T_eq float

Equilibration pressure [GPa] and temperature [K], > 0.

P_EQ_GPA
laws dict or None

Law per element, a name for :func:calliope.metal.get_law or an entry; elements not given take :data:DEFAULT_LAWS.

None
w_fixed dict or None

Metal mass fractions of elements that are not split (O, Si), each in [0, 1) with a sum below 1.

None
oxides dict

Silicate composition in oxide wt%: the silicate units of the mole bases and the melt a callable law gets (the FeO of a law with an FeO term comes from dIW).

KLB1
nbo_t float

NBO/T of the silicate.

2.6

Returns:

Name Type Description
core_kg, mantle_kg : dict

Core and mantle mass [kg] of each element of bulk_kg; their sum is the bulk to 1e-12 relative plus 2 ulp of 0 (asserted).

flags dict

Per element: out_of_range (1 when a distance is not 0) and the distances P_GPa, T_K, dIW of :func:calliope.metal.range_distance. Under 'metal': the mole fractions x_light (all light elements) and x_S over the whole metal, S_over_Fe (moles), and beyond_FeS (1 when the metal holds more S than Fe, past FeS; no clamp). A relaxed split past FeS prefers the root with more iron (see the metal page); root_rule is 1 when that rule replaced the first root, else 0. Per element also D_residual: |w - D w_sil| / w at the returned split, with w = core / M_metal and w_sil = mantle / M_silicate (0 for no core mass).

Raises:

Type Description
ValueError

An input outside its domain (named), O or Si in bulk_kg, a key of laws outside bulk_kg, a D that overflows with M_metal, or a metal with no iron left (naming the split), also when the common relaxed passes do not settle after the per-element passes ran out of iron.

PartitionTableError

A law name that is not held, or a law in laws that is not a D law of its element.

RuntimeError

A metal composition that settles neither in :data:MAX_PASSES plain passes nor in 2 x :data:MAX_RELAXED_PASSES relaxed passes, or a split that breaks the element ledger.

Source code in src/calliope/core_split.py
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
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
367
368
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
395
396
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
def split_core_mantle(
    bulk_kg,
    M_metal,
    M_silicate,
    *,
    dIW,
    P_eq=P_EQ_GPA,
    T_eq=T_EQ_K,
    laws=None,
    w_fixed=None,
    oxides=KLB1,
    nbo_t=2.6,
):
    """Split the bulk mass of each element between core and mantle.

    Parameters
    ----------
    bulk_kg : dict
        Bulk mass [kg] of each element to split, H, C, N or S (or any element of
        :data:`calliope.metal.ELEMENTS` with a D law); O and Si are refused.
    M_metal : float
        Mass of the equilibrating metal [kg], >= 0; 0 evaluates no law and returns the bulk
        as mantle.
    M_silicate : float
        Mass of the equilibrating silicate [kg], > 0.
    dIW : float
        Oxygen fugacity of the equilibrium relative to the iron-wustite buffer [log10].
    P_eq, T_eq : float
        Equilibration pressure [GPa] and temperature [K], > 0.
    laws : dict or None
        Law per element, a name for :func:`calliope.metal.get_law` or an entry; elements
        not given take :data:`DEFAULT_LAWS`.
    w_fixed : dict or None
        Metal mass fractions of elements that are not split (O, Si), each in [0, 1) with a
        sum below 1.
    oxides : dict
        Silicate composition in oxide wt%: the silicate units of the mole bases and the
        melt a callable law gets (the FeO of a law with an FeO term comes from ``dIW``).
    nbo_t : float
        NBO/T of the silicate.

    Returns
    -------
    core_kg, mantle_kg : dict
        Core and mantle mass [kg] of each element of ``bulk_kg``; their sum is the bulk to
        1e-12 relative plus 2 ulp of 0 (asserted).
    flags : dict
        Per element: ``out_of_range`` (1 when a distance is not 0) and the distances
        ``P_GPa``, ``T_K``, ``dIW`` of :func:`calliope.metal.range_distance`. Under
        ``'metal'``: the mole fractions ``x_light`` (all light elements) and ``x_S`` over
        the whole metal, ``S_over_Fe`` (moles), and ``beyond_FeS`` (1 when the metal holds
        more S than Fe, past FeS; no clamp). A relaxed split past FeS prefers the root with
        more iron (see the metal page); ``root_rule`` is 1 when that rule replaced the first
        root, else 0. Per element also ``D_residual``: |w - D w_sil| / w
        at the returned split, with w = core / M_metal and w_sil = mantle / M_silicate (0 for
        no core mass).

    Raises
    ------
    ValueError
        An input outside its domain (named), O or Si in ``bulk_kg``, a key of ``laws``
        outside ``bulk_kg``, a D that overflows with ``M_metal``, or a metal with no iron
        left (naming the split), also when the common relaxed passes do not settle after
        the per-element passes ran out of iron.
    calliope.metal.PartitionTableError
        A law name that is not held, or a law in ``laws`` that is not a D law of its
        element.
    RuntimeError
        A metal composition that settles neither in :data:`MAX_PASSES` plain passes nor in
        2 x :data:`MAX_RELAXED_PASSES` relaxed passes, or a split that breaks the element
        ledger.
    """
    bulk = {}
    for el, m in bulk_kg.items():
        if el in EXCHANGE_ELEMENTS:
            raise ValueError(
                f'{el} is not split: its bulk is the rock {el}, which CALLIOPE does not hold; '
                f'give the metal {el} mass fraction in w_fixed'
            )
        if el not in ELEMENTS:
            raise ValueError(f'bulk element {el!r} has no partition law; known: {ELEMENTS}')
        bulk[el] = _check(f'bulk_kg[{el!r}]', m)
    m_metal = _check('M_metal', M_metal)
    m_sil = _check('M_silicate', M_silicate, positive=True)
    p_eq = _check('P_eq', P_eq, positive=True)
    t_eq = _check('T_eq', T_eq, positive=True)
    d_iw = _check('dIW', dIW, signed=True)
    fixed = {}
    for el, w in (w_fixed or {}).items():
        if el not in ELEMENTS or el in bulk:
            raise ValueError(f'w_fixed: {el!r} must be an element of {ELEMENTS} not in bulk_kg')
        fixed[el] = _check(f'w_fixed[{el!r}]', w)
        if fixed[el] >= 1.0:
            raise ValueError(f'w_fixed[{el!r}] = {w!r} must be below 1')
    if sum(fixed.values()) >= 1.0:
        raise ValueError(f'w_fixed {fixed} leaves no iron in the metal')
    if laws is not None and not isinstance(laws, dict):
        raise ValueError(f'laws must be a dict of element to law, got {laws!r}')
    extra = sorted(set(laws or {}) - set(bulk))
    if extra:
        raise ValueError(f'laws names elements outside bulk_kg: {extra}')
    names, entries = {**DEFAULT_LAWS, **(laws or {})}, {}
    for el in bulk:
        spec = names[el]
        try:
            entries[el] = check_law(get_law(el, spec) if isinstance(spec, str) else spec, el)
        except PartitionTableError as err:
            raise PartitionTableError(f'laws[{el!r}] = {spec!r:.60}: {err}') from err
    start = {**fixed, **dict.fromkeys(bulk, 0.0)}

    def evaluate(w, w_melt):
        d = {}
        for el in bulk:
            try:
                d[el] = mass_D(entries[el], p_eq, t_eq, d_iw, w, w_melt, oxides, nbo_t)
            except ValueError as err:
                raise ValueError(f'split of {el}: {err}') from err
        core, mantle = _masses(bulk, d, m_metal, m_sil)
        g = {el: core[el] / m_metal for el in bulk}
        return core, mantle, g, {el: mantle[el] / m_sil for el in ('H', 'C') if el in bulk}

    root_rule = 0
    if m_metal == 0.0:
        core, mantle, w = dict.fromkeys(bulk, 0.0), dict(bulk), start
    else:
        try:
            core, mantle, w = _plain_fixed_point(evaluate, start, fixed)
        except _Unsettled:
            core, mantle, w, root_rule = _relaxed_fixed_point(evaluate, start, fixed)
    for el, m in bulk.items():
        if not (
            core[el] >= 0.0
            and mantle[el] >= 0.0
            and abs(core[el] + mantle[el] - m) <= LEDGER_RTOL * m + LEDGER_ATOL
        ):
            raise RuntimeError(
                f'{el} ledger of the split fails: core {core[el]!r} + mantle {mantle[el]!r} kg '
                f'against bulk {m!r} kg'
            )
    w_ret = {**fixed, **{el: core[el] / m_metal for el in bulk}} if m_metal else w
    total, n = _metal_moles(w_ret)
    n_s, n_fe = n.get('S', 0.0), (1.0 - sum(w_ret.values())) / _mass('Fe')
    flags = {
        'metal': {
            'x_light': sum(n.values()) / total,
            'x_S': n_s / total,
            'S_over_Fe': n_s / n_fe,
            'beyond_FeS': int(n_s > n_fe),
            'root_rule': root_rule,
        }
    }
    w_melt = {el: mantle[el] / m_sil for el in ('H', 'C') if el in bulk}
    for el, entry in entries.items():
        dist = range_distance(entry, p_eq, t_eq, d_iw)
        flags[el] = {'out_of_range': int(any(v != 0.0 for v in dist.values())), **dist}
        flags[el]['D_residual'] = 0.0
        if core[el] > 0.0:
            d = mass_D(entry, p_eq, t_eq, d_iw, w_ret, w_melt, oxides, nbo_t)
            flags[el]['D_residual'] = (
                abs(core[el] - d * mantle[el] * m_metal / m_sil) / core[el]
            )
        label = names[el] if isinstance(names[el], str) else f'entry ({entry["source"][:40]})'
        ranges = tuple(entry[r] for r in ('P_range_GPa', 'T_range_K', 'dIW_range'))
        key = (el, label, entry['source']) + ranges
        if flags[el]['out_of_range'] and key not in _WARNED:
            _WARNED.add(key)
            shown = {k: round(v, 3) for k, v in dist.items()}
            log.warning(
                f'{el} partition law {label} evaluated outside its range: P_eq {p_eq:g} GPa, '
                f'T_eq {t_eq:g} K, dIW {d_iw:g} (distance {shown})'
            )
    return core, mantle, flags