Skip to content

API overview

This is the auto-generated API reference for CALLIOPE's public interface. For the underlying physics, see the model overview; for the package layout in detail, see code architecture.

Module overview

src/calliope/
├── __init__.py          # version string only
├── constants.py         # molar masses, element list, plotting colours
├── oxygen_fugacity.py   # OxygenFugacity (IW buffer parameterisations)
├── chemistry.py         # ModifiedKeq (six redox couples)
├── solubility.py        # Solubility{H2O,CO2,CO,CH4,N2,S2}
├── solve.py             # equilibrium_atmosphere() and supporting functions
├── metal.py             # partition file reader, partition laws, named laws, metal reservoir masses
├── core_split.py        # split_core_mantle() core and mantle split of a bulk inventory
└── structure.py         # calculate_mantle_mass() simple core/mantle split

API reference

Solver

  • calliope.solve - two public entry points:

    • equilibrium_atmosphere() (buffered mode): takes \(\Delta\mathrm{IW}\) as input and solves the four-residual H/C/N/S mass-balance system.
    • equilibrium_atmosphere_authoritative_O() (authoritative-O mode): takes a five-element target including O and solves a five-residual system with \(\Delta\mathrm{IW}\) as the additional unknown. See Authoritative-oxygen mode for the augmented mass balance.

    Plus supporting functions: the residual functions func / func_authoritative_O, the L2-norm objectives obj / obj_authoritative_O, the speciation tree get_partial_pressures, the column-mass aggregation atmosphere_mass, the dissolved-mass aggregation dissolved_mass, the cold-start guess generators get_initial_pressures / get_initial_pressures_with_fO2, and the elemental-target builders get_target_from_params / get_target_from_pressures.

Chemistry

  • calliope.chemistry - ModifiedKeq class with eight model methods (schaefer_C, schaefer_H, schaefer_CH4, janaf_CO, janaf_H2, janaf_SO2, janaf_H2S, janaf_NH3) returning the modified equilibrium constant \(G_\mathrm{eq}(T, f_{\mathrm{O}_2})\).

Solubility

  • calliope.solubility - Solubility base class plus six concrete subclasses with multiple alternative compositions per species. Returns dissolved-volatile concentration in ppmw given partial pressure (and, where relevant, \(T_\mathrm{magma}\), \(p_\mathrm{tot}\), \(\Delta\mathrm{IW}\)).

Oxygen fugacity

  • calliope.oxygen_fugacity - OxygenFugacity class with three model methods (hirschmann default, fischer, oneill). Returns \(\log_{10} f_{\mathrm{O}_2}^\mathrm{IW}(T) + \Delta\mathrm{IW}\).

Metal and core split

  • calliope.metal - partition file reader, the partition laws, named laws (get_law, register_law) and the metal reservoir masses.
  • calliope.core_split - split_core_mantle(), the core and mantle split of a bulk inventory at one equilibration point.

Structure

  • calliope.structure - calculate_mantle_mass(radius, mass, core_frac) simple Earth-density core/mantle split. Provided for standalone runs; PROTEUS does not call it and passes the mantle mass of its interior steps (code architecture).

Constants

  • calliope.constants - Static reference values: planetary masses and radii, ocean-of-H scale, molar masses, the eleven-species volatile_species list, the five-element element_list, and the PROTEUS-shared plotting colour scheme dict_colors.

What is not in the public API

CALLIOPE intentionally has a flat module structure with no underscore-prefixed sub-packages or private submodules. Every function or class declared in the modules above is part of the public API. The exception is solve.func and solve.obj (the residual and objective functions passed to scipy.optimize); these are public for testing and inspection purposes but should not be called directly outside of an equilibrium_atmosphere flow because they assume the input dict is in a particular state (e.g. zero-clipped, IW-shifted, included-flagged).