Configuration file¶

def spada_zephyrus(instance, attribute, value):
    """ZEPHYRUS escape requires the MORS star module with the Spada evolution tracks."""
    if (instance.escape.module == 'zephyrus') and not (
        (instance.star.module == 'mors') and (instance.star.mors.tracks == 'spada')
    ):
        raise ValueError('ZEPHYRUS must be used with MORS and the Spada evolution tracks')

def instmethod_dummy(instance, attribute, value):
    """Instellation method 'inst' is only available with the dummy star module."""
    if (instance.orbit.instellation_method == 'inst') and not (instance.star.module == 'dummy'):
        raise ValueError("Instellation method can only be 'inst' when star.module=dummy ")

def instmethod_evolve(instance, attribute, value):
    """Orbital evolution cannot be combined with instellation method 'inst'."""
    if (instance.orbit.instellation_method == 'inst') and instance.orbit.evolve:
        raise ValueError(
            "Planet orbital evolution not supported for `instellation_method='inst'`"
        )

def satellite_evolve(instance, attribute, value):
    """Planetary orbital evolution and the satellite model are mutually exclusive."""
    if instance.orbit.satellite and instance.orbit.evolve:
        raise ValueError(
            'Planet orbital evolution cannot be used simultaneously with a satellite'
        )

def tides_enabled_orbit(instance, attribute, value):
    """Interior tidal heating requires an orbit module to be enabled."""
    if (instance.interior_energetics.heat_tidal) and (instance.orbit.module is None):
        raise ValueError('Interior tidal heating requires an orbit module to be enabled')

def check_module_dependencies(instance, attribute, value):
    """Check that required external packages are importable for the selected modules."""
    import importlib

    checks = {
        'calliope': (
            instance.outgas.module == 'calliope',
            'calliope',
            'outgas.module = "calliope" requires the calliope package. '
            'Install with: git clone git@github.com:FormingWorlds/CALLIOPE && pip install -e CALLIOPE/.',
        ),
        'atmodeller': (
            instance.outgas.module == 'atmodeller',
            'atmodeller',
            'outgas.module = "atmodeller" requires the optional atmodeller package '
            '(GPL-3.0 licensed). The standard outgassing backend is calliope and '
            'needs no extra install. '
            'Install atmodeller with: pip install "fwl-proteus[atmodeller]" '
            '(or pip install "atmodeller>=1.0.0").',
        ),
        'vulcan': (
            instance.atmos_chem.module == 'vulcan',
            'vulcan',
            'atmos_chem.module = "vulcan" requires the optional VULCAN package '
            '(GPL-3.0 licensed). VULCAN is not needed for a standard PROTEUS run. '
            'Install it with: pip install "fwl-proteus[vulcan]" '
            '(or bash tools/get_vulcan.sh for an editable checkout).',
        ),
        'boreas': (
            instance.escape.module == 'boreas',
            'boreas',
            'escape.module = "boreas" requires the optional boreas package. '
            'Install it with: bash tools/get_boreas.sh',
        ),
    }

    for name, (needed, pkg, msg) in checks.items():
        if needed:
            try:
                importlib.import_module(pkg)
            except ImportError as e:
                raise ImportError(f'{msg}\n  Original error: {e}') from e

def boreas_requires_atmosphere(instance, attribute, value):
    """BOREAS escape requires a radiative atmosphere (not dummy)."""
    if (instance.escape.module == 'boreas') and (instance.atmos_clim.module == 'dummy'):
        raise ValueError(
            'escape.module = "boreas" requires a radiative atmosphere model (agni or janus), '
            'not atmos_clim.module = "dummy". BOREAS needs per-level T/P/composition profiles.'
        )

def observe_resolved_atmosphere(instance, attribute, value):
    """Synthetic observations require a spatially resolved atmosphere (not dummy)."""
    if (instance.observe.module is not None) and (instance.atmos_clim.module == 'dummy'):
        raise ValueError('Observational synthesis requires that atmos_clim != dummy')

def janus_escape_atmosphere(instance, attribute, value):
    """ZEPHYRUS escape with JANUS requires the escape stop criterion to be enabled."""
    if (
        (instance.escape.module == 'zephyrus')
        and (instance.atmos_clim.module == 'janus')
        and (not instance.params.stop.escape.enabled)
    ):
        raise ValueError(
            'When using escape.zephyrus with JANUS, params.stop.escape must be True.'
        )

def planet_mass_valid(instance, attribute, value):
    """Validate that mass_tot is within range."""
    mass_tot = instance.planet.mass_tot
    if mass_tot <= 0:
        raise ValueError('The total planet mass must be > 0')
    if mass_tot > 20:
        raise ValueError('The total planet mass must be < 20 M_earth')

def planet_oxygen_mode_explicit(instance, attribute, value):
    """Validate O_mode in planet.elements.

    Whole-planet oxygen accounting requires every config to declare how
    the IC O budget is interpreted. Valid modes: 'ic_chemistry' (default,
    defer to CALLIOPE equilibrium), 'ppmw', 'kg', 'FeO_mantle_wt_pct'.
    """
    # O_mode is now validated by the attrs in_() validator on the field
    # itself. This function remains as a hook for cross-field checks
    # (e.g. fO2_source compatibility) that reference O_mode.
    pass

def planet_fO2_source_compat(instance, attribute, value):
    """Validate planet.fO2_source against O_mode, volatile_mode, and
    against availability.

    Rejection rules:

    1. ``fO2_source = "from_mantle_redox"`` is a reserved enum value for
       the radial Fe3+/Fe2+ fO2 framework (issue #653, Schaefer et al.
       2024). The runtime path for it does not exist yet; reject the
       config so users do not silently fall through to the default behaviour.

    2. ``fO2_source = "from_O_budget"`` requires the O budget to be
       authoritative. ``O_mode = "ic_chemistry"`` defers the O inventory
       to the chemistry solver, so there is nothing to invert against.
       Require a concrete O budget
       ("ppmw" / "kg" / "FeO_mantle_wt_pct") instead.

    3. ``fO2_source = "from_O_budget"`` requires the volatile budget to
       be set element-wise. ``volatile_mode = "gas_prs"`` supplies
       partial pressures directly and makes ``planet.elements.O_mode``
       inoperative, so there is nothing to invert against. Switch
       ``volatile_mode`` to ``"elements"`` or pick a different fO2_source.

    4. ``fO2_source = "from_O_budget"`` requires an outgassing backend
       with an authoritative-O implementation: CALLIOPE
       (``equilibrium_atmosphere_authoritative_O``) and atmodeller
       (native mass-constraint API) both qualify; the ``dummy`` backend
       does not. The runtime dispatch echoes this rejection too, but
       failing at config-load saves the user from burning interior IC
       and structure setup before hitting the wall.

    ``fO2_source = "user_constant"`` (default) accepts every O_mode and
    every volatile_mode.

    Warning rule:

    - ``fO2_source = "from_O_budget"`` with a non-default
      ``outgas.fO2_shift_IW`` emits a UserWarning. With this source the
      buffer offset is *derived*, so a user-supplied value is silently
      ignored. The warning surfaces the misconfiguration without
      blocking the run.
    """
    fO2_source = instance.planet.fO2_source
    O_mode = instance.planet.elements.O_mode
    volatile_mode = instance.planet.volatile_mode

    if fO2_source == 'from_mantle_redox':
        raise ValueError(
            'planet.fO2_source = "from_mantle_redox" is reserved for the '
            'radial Fe3+/Fe2+ tracking framework (issue #653) and is not '
            'yet wired into the runtime. Use "user_constant" (fO2 '
            'buffered by outgas.fO2_shift_IW) or "from_O_budget" '
            '(authoritative O budget, fO2 derived) instead.'
        )

    if fO2_source == 'from_O_budget' and O_mode == 'ic_chemistry':
        raise ValueError(
            'planet.fO2_source = "from_O_budget" requires an authoritative '
            'O budget but planet.elements.O_mode = "ic_chemistry" defers '
            'the O inventory to the chemistry solver. Pick an explicit O '
            'budget mode ("ppmw", "kg", or "FeO_mantle_wt_pct") or switch '
            'fO2_source back to "user_constant".'
        )

    if fO2_source == 'from_O_budget' and volatile_mode == 'gas_prs':
        raise ValueError(
            'planet.fO2_source = "from_O_budget" requires '
            'planet.volatile_mode = "elements" so the O inventory is '
            'derived from planet.elements.O_budget. Under '
            'volatile_mode = "gas_prs" the user supplies partial '
            'pressures directly and the element budgets are inert, so '
            'there is no O target to invert against. Either switch '
            'volatile_mode to "elements" or set fO2_source back to '
            '"user_constant".'
        )

    if fO2_source == 'from_O_budget':
        outgas_module = getattr(instance.outgas, 'module', None)
        if outgas_module == 'dummy':
            raise ValueError(
                'planet.fO2_source = "from_O_budget" requires an '
                'outgassing backend with an authoritative-O '
                'implementation. outgas.module = "dummy" has no '
                'chemistry to invert against. Switch outgas.module to '
                '"calliope" or '
                '"atmodeller", or set fO2_source back to '
                '"user_constant".'
            )

    if fO2_source == 'from_O_budget':
        import warnings

        fO2_shift_IW = getattr(instance.outgas, 'fO2_shift_IW', None)
        if fO2_shift_IW is not None and fO2_shift_IW != 0.0:
            warnings.warn(
                'outgas.fO2_shift_IW = %.3f is set but '
                'planet.fO2_source = "from_O_budget" derives the buffer '
                'offset from the O budget. The configured value is used '
                'only as the solver initial fO2 guess, not as the buffered '
                'offset.' % fO2_shift_IW,
                UserWarning,
                stacklevel=2,
            )

def boundary_requires_fixed_surface_state(instance, attribute, value):
    """Boundary backend assumes a fixed surface state coupling."""
    if (instance.interior_energetics.module == 'boundary') and (
        instance.atmos_clim.surf_state != 'fixed'
    ):
        raise ValueError(
            "Must set atmos_clim.surf_state='fixed' when interior_energetics.module='boundary'"
        )

def max_bigger_than_min(instance, attribute, value):
    """The maximum must exceed the minimum on the same section."""
    if value <= instance.minimum:
        raise ValueError("'maximum' has to be bigger than 'minimum'.")

def valid_mors(instance, attribute, value):
    """Validate MORS settings: positive age, spectrum-source requirements, and rotation
    set by exactly one of percentile or period."""
    if instance.module != 'mors':
        return

    if (instance.mors.age_now is None) or (instance.mors.age_now <= 0):
        raise ValueError('mors.age_now must be > 0')
    src = instance.mors.spectrum_source

    # star_name required for solar and muscles spectra (not for phoenix)
    if instance.mors.star_name is None and src in ('solar', 'muscles'):
        raise ValueError('Must provide mors.star_name for spectrum_source=%s' % src)
    if src == 'phoenix':
        if instance.mors.phoenix_alpha is None or instance.mors.phoenix_FeH is None:
            raise ValueError(
                'mors.phoenix_alpha and mors.phoenix_FeH must be set when using PHOENIX spectra'
            )

    set_pcntle = instance.mors.rot_pcntle is not None
    set_period = instance.mors.rot_period is not None

    if set_pcntle and set_period:
        raise ValueError('Stellar rotation must be set by percentile or period, not both')
    if (not set_pcntle) and (not set_period):
        raise ValueError('Stellar rotation must be set either by percentile or period')

    if set_pcntle and not (0 <= instance.mors.rot_pcntle <= 100):
        raise ValueError('Rotation percentile must be >=0 and <=100')

    if set_period and (instance.mors.rot_period <= 0):
        raise ValueError('Rotation period must be greater than zero')

def valid_bol_scale_start(instance, attribute, value):
    """A bolometric scaling other than 1 requires bol_scale_start and a positive duration."""
    if instance.bol_scale == 1.0:
        return
    if value is None:
        raise ValueError('star.bol_scale_start must be set when star.bol_scale != 1.0')
    if instance.bol_scale_duration <= 0.0:
        raise ValueError('star.bol_scale_duration must be > 0 when star.bol_scale != 1.0')

def valid_stardummy(instance, attribute, value):
    """Dummy star requires a consistent radius specification and a valid Teff."""
    if instance.module != 'dummy':
        return

    if instance.dummy.calculate_radius:
        if instance.dummy.radius is not None:
            raise ValueError("Star radius must be 'none' when calculate_radius is True")

    else:
        if (instance.dummy.radius is None) or (instance.dummy.radius <= 0):
            raise ValueError('Star radius MUST be set >0 when calculate_radius is False')

    if (instance.dummy.Teff is None) or (instance.dummy.Teff < 1):
        raise ValueError('star.dummy.Teff must be >0 K')

def valid_zalmoxis(instance, attribute, value):
    """Validate Zalmoxis EOS format strings and reject unsupported miscibility options."""
    if instance.module == 'spider':
        return

    core_eos = instance.zalmoxis.core_eos
    mantle_eos = instance.zalmoxis.mantle_eos
    ice_layer_eos = instance.zalmoxis.ice_layer_eos
    mantle_mass_fraction = instance.zalmoxis.mantle_mass_fraction

    # EOS format validation: must be "<source>:<material>"
    for name, eos_val in [('core_eos', core_eos), ('mantle_eos', mantle_eos)]:
        if ':' not in eos_val:
            raise ValueError(
                f"`interior_struct.zalmoxis.{name}` must be in '<source>:<material>' format, "
                f"got '{eos_val}'"
            )
    if ice_layer_eos is not None and ':' not in ice_layer_eos:
        raise ValueError(
            f"`interior_struct.zalmoxis.ice_layer_eos` must be 'none' or '<source>:<material>' format, "
            f"got '{ice_layer_eos}'"
        )

    # Phase-aware volatile mixing (`dry_mantle = false`) is supported: the
    # pinned Zalmoxis release evaluates a per-shell volatile profile in the
    # mantle density. Binodal-aware miscibility (`global_miscibility`)
    # additionally requires the H2-silicate binodal handoff on the Zalmoxis
    # side (Zalmoxis tracker #64), which is not yet implemented, so it stays
    # gated on its own merits rather than on the pin.
    if getattr(instance.zalmoxis, 'global_miscibility', False):
        raise ValueError(
            '`interior_struct.zalmoxis.global_miscibility = true` is not yet usable: '
            'it requires the H2-silicate binodal handoff on the Zalmoxis side '
            '(Zalmoxis tracker #64), which the pinned release does not implement. '
            'Use `dry_mantle = false` for phase-aware H2O mixing without miscibility.'
        )

    # WolfBower2018 EOS is limited to 1 TPa. For planets > 2 M_earth,
    # CMB pressure exceeds this and Zalmoxis will fail to converge.
    import logging as _logging

    _log = _logging.getLogger('fwl.' + __name__)
    # mushy_zone_factor only applies to PALEOS unified tables
    mzf = getattr(instance.zalmoxis, 'mushy_zone_factor', 0.8)
    if mzf < 1.0 and not mantle_eos.startswith('PALEOS:'):
        _log.warning(
            'mushy_zone_factor=%.2f has no effect with mantle EOS %s. '
            'The mushy zone factor only applies to PALEOS unified tables. '
            'For WolfBower2018/RTPress100TPa, the mushy zone is defined by '
            'the solidus/liquidus melting curve files.',
            mzf,
            mantle_eos,
        )

    # 2-layer model (no ice layer, non-T-dep mantle): mantle_mass_fraction must be 0
    _TDEP_PREFIXES = ('WolfBower2018', 'RTPress100TPa')
    if ice_layer_eos is None and not mantle_eos.startswith(_TDEP_PREFIXES):
        if mantle_mass_fraction != 0:
            raise ValueError(
                '`interior_struct.zalmoxis.mantle_mass_fraction` must be 0 for a 2-layer model '
                'without T-dependent mantle EOS (only core + mantle are modeled).'
            )

    # 3-layer model (with ice layer): mass fractions must not exceed 75%
    if ice_layer_eos is not None:
        cmf = instance.core_frac if instance.core_frac_mode == 'mass' else 0.325
        if cmf + mantle_mass_fraction > 0.75:
            raise ValueError(
                '`core_frac` and `zalmoxis.mantle_mass_fraction` '
                'must add up to <= 75% for a 3-layer model (Seager 2007).'
            )

def valid_spider(instance, attribute, value):
    """SPIDER requires at least one energy transport term to be enabled."""
    if instance.module != 'spider':
        return

    # at least one energy term enabled
    if not (
        instance.trans_conduction
        or instance.trans_convection
        or instance.trans_mixing
        or instance.trans_grav_sep
    ):
        raise ValueError('Must enable at least one energy transport term in SPIDER')

def valid_interiorboundary(instance, attribute, value):
    """Validate Boundary backend's solidus/liquidus ordering.

    Only fires when ``module == 'boundary'``; otherwise the subclass is
    constructed with defaults and never exercised.
    """
    if instance.module != 'boundary':
        return

    tsol = instance.boundary.T_solidus
    tliq = instance.boundary.T_liquidus
    if tliq <= tsol:
        raise ValueError(f'Boundary liquidus ({tliq}K) must be greater than solidus ({tsol}K)')

def valid_aragog(instance, attribute, value):
    """Aragog requires at least one energy transport term to be enabled."""
    if instance.module != 'aragog':
        return

    # at least one energy term enabled (uses top-level interior fields)
    if not (
        instance.trans_conduction
        or instance.trans_convection
        or instance.trans_mixing
        or instance.trans_grav_sep
    ):
        raise ValueError('Must enable at least one energy transport term in Aragog')

def valid_interiordummy(instance, attribute, value):
    """Dummy interior requires the liquidus to sit above the solidus."""
    if instance.module != 'dummy':
        return

    pass  # dummy uses planet.tsurf_init for initial temperature

    tliq = instance.dummy.mantle_tliq
    tsol = instance.dummy.mantle_tsol
    if tliq <= tsol:
        raise ValueError(f'Dummy liquidus ({tliq}K) must be greater than solidus ({tsol}K)')

def warn_if_dummy(instance, attribute, value):
    """Reject enabling this option when the dummy atmos_clim module is selected."""
    if (instance.module == 'dummy') and value:
        raise ValueError(f'Dummy atmos_clim module is incompatible with {attribute.name}=True')

def valid_rayleigh(instance, attribute, value):
    """Reject Rayleigh scattering with the dummy module or AGNI in grey-gas mode."""
    if not value:
        return

    if instance.module == 'dummy':
        raise ValueError('Dummy atmos_clim is incompatible with Rayleigh scattering')

    if instance.module == 'agni' and (str(instance.agni.spectral_file).lower() == 'greygas'):
        raise ValueError('AGNI grey gas is incompatible with Rayleigh scattering')

def valid_aerosols_enabled(instance, attribute, value):
    """Aerosol scattering needs band-resolved RT.

    Reuses the dummy guard from ``warn_if_dummy`` and rejects the
    AGNI grey-gas combination: grey gas has no spectral bands, so a
    Mie-scattering aerosol library is either silently ignored or
    crashes on the Julia side. The check fires only when aerosols
    are enabled (``value is True``).
    """
    if not value:
        return

    if instance.module == 'dummy':
        raise ValueError(f'Dummy atmos_clim module is incompatible with {attribute.name}=True')

    if instance.module == 'agni' and (str(instance.agni.spectral_file).lower() == 'greygas'):
        raise ValueError(
            'AGNI grey gas is incompatible with aerosols (band-resolved Mie '
            'scattering requires a real spectral file)'
        )

def valid_agni(instance, attribute, value):
    """Validate AGNI settings: pressure ordering, surface-state support, rainout, spectral file."""
    if instance.module != 'agni':
        return

    # ensure psurf_thresh is greater than p_top, to avoid upside-down atmosphere in transparent mode
    if instance.p_top > instance.agni.psurf_thresh:
        raise ValueError('Must set `p_top` to be less than `agni.psurf_thresh`')

    # ensure p_obs is greater than p_top
    if instance.p_top > instance.p_obs:
        raise ValueError('Must set `p_top` to be less than `p_obs`')

    # agni does not support mixed_layer surface state
    if instance.surf_state == 'mixed_layer':
        raise ValueError(
            "AGNI does not support `surf_state='mixed_layer'`. Use 'fixed' or 'skin'."
        )

    # agni must solve_energy=true if surf_state=skin
    if (not instance.agni.solve_energy) and (instance.surf_state == 'skin'):
        raise ValueError("Must set `agni.solve_energy=true` if using `surf_state='skin'`")

    if instance.agni.latent_heat and not instance.agni.rainout:
        raise ValueError(
            '`atmos_clim.agni`: Must set `rainout=true` if setting `latent_heat=true`'
        )

    # set spectral files?
    if instance.agni.spectral_file is not None:
        if instance.agni.spectral_file.lower() == 'greygas':
            # grey gas: no SOCRATES spectral file needed
            pass
        elif not os.path.isfile(instance.agni.spectral_file):
            raise FileNotFoundError(
                f'AGNI spectral file not found at specified path: {instance.agni.spectral_file}'
            )
    else:
        # provided by group and bands at parent level
        if not instance.spectral_group:
            raise ValueError('Must set atmos_clim.spectral_group')
        if not instance.spectral_bands:
            raise ValueError('Must set atmos_clim.spectral_bands')

    # fastchem installed?
    if instance.agni.chemistry == 'eq':
        FC_DIR = os.environ.get('FC_DIR')
        if FC_DIR:
            if not os.path.isdir(FC_DIR):
                raise FileNotFoundError(f'Fastchem not found at FC_DIR={FC_DIR}')
        else:
            raise EnvironmentError(
                'Chemistry is enabled but environment variable `FC_DIR` is not set'
            )

def valid_janus(instance, attribute, value):
    """Validate JANUS settings: spectral file selection and temperature-bound ordering."""
    if instance.module != 'janus':
        return

    # set spectral files?
    if not instance.spectral_group:
        raise ValueError('Must set atmos_clim.spectral_group')
    if not instance.spectral_bands:
        raise ValueError('Must set atmos_clim.spectral_bands')

    # tmp_maximum must exceed tmp_minimum
    if instance.janus.tmp_maximum <= instance.tmp_minimum:
        raise ValueError("'janus.tmp_maximum' has to be bigger than 'tmp_minimum'.")