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'.

    'inst' derives the semi-major axis from the flux, while every star-planet
    model, a prescribed track included, starts from orbit.semimajoraxis.
    """
    if (instance.orbit.instellation_method == 'inst') and (
        instance.orbit.star_planet_model is not None
    ):
        raise ValueError(
            "Planet orbital evolution not supported for `instellation_method='inst'`: "
            f'orbit.star_planet_model = {instance.orbit.star_planet_model!r} starts from '
            "orbit.semimajoraxis, so set instellation_method = 'distance'"
        )

def satellite_evolve(instance, attribute, value):
    """Star-planet orbital evolution and the planet-satellite model are mutually exclusive."""
    if (
        instance.orbit.star_planet_model is not None
        and instance.orbit.planet_satellite_model is not None
    ):
        raise ValueError(
            'Planet orbital evolution cannot be used simultaneously with a satellite'
        )

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

def obliqua_requires_perturber(instance, attribute, value):
    """The Obliqua tidal-response module requires an explicit perturber."""
    if instance.orbit.module == 'obliqua' and instance.orbit.perturber is None:
        raise ValueError(
            "orbit.module = 'obliqua' requires orbit.perturber to be explicitly set to "
            "'star' or 'satellite' (it has no default tidal-forcing body to fall back on)"
        )

def sp0d_obliqua_degree_mismatch(instance, attribute, value):
    """sp0d's closed-form is by definition the n=2 Love number. Obliqua can compute
    arbitrary tidal degree(s), block the mismatch.
    """
    if instance.orbit.module == 'obliqua' and instance.orbit.star_planet_model == 'sp0d':
        if instance.orbit.obliqua.n != [2]:
            raise ValueError(
                "orbit.star_planet_model = 'sp0d' requires orbit.obliqua.n == [2]: "
                'set orbit.obliqua.n = [2] to use sp0d with Obliqua, or use'
                "orbit.star_planet_model = 'sp1d' instead."
            )
        log.warning(
            "orbit.star_planet_model = 'sp0d' with orbit.module = 'obliqua': Imk2 is "
            "the mean of Obliqua's per-mode Im(k2) spectrum collapsed to a single "
            'scalar, which discards the eccentricity-dependent mode weighting sp1d '
            'uses directly. This is an approximation, least accurate at high or '
            "rapidly-changing eccentricity. Prefer orbit.star_planet_model = 'sp1d'"
            ' when using Obliqua.'
        )

def orbit_requires_tides(instance, attribute, value):
    """sp1d, ps1d, and ps1d_evec require at least Lovepy, but ideally the Obliqua
    tidal-response module: all three read the full per-mode spectrum in
    ``tides_o``, which ``dummy`` never populates. ``sp0d``/``ps0d`` read the
    scalar ``Imk2`` instead (which ``dummy`` does provide), so they are
    unrestricted here; see "Compatibility between orbit models and tidal
    modules" in docs/Explanations/orbit.md.
    """
    needs_full_spectrum = instance.orbit.star_planet_model == 'sp1d' or (
        instance.orbit.planet_satellite_model in ('ps1d', 'ps1d_evec')
    )
    if needs_full_spectrum and instance.orbit.module not in ('obliqua', 'lovepy'):
        raise ValueError(
            "orbit.star_planet_model = 'sp1d' or orbit.planet_satellite_model = "
            "'ps1d'/'ps1d_evec' requires orbit.module = 'obliqua' or 'lovepy'"
        )

def parameterized_excludes_tides(instance, attribute, value):
    """The parameterized model prescribes the orbit as a closed-form track
    and exchanges no energy with the interior, so no tides module can run
    alongside it; see "Star-planet models" in docs/Explanations/orbit.md.
    """
    if (
        instance.orbit.star_planet_model == 'parameterized'
        and instance.orbit.module is not None
    ):
        raise ValueError(
            "orbit.star_planet_model = 'parameterized' requires orbit.module = 'none' "
            f'(got {instance.orbit.module!r}): a prescribed migration track computes no tides'
        )

def spinless_orbit_keeps_spin_synchronous(instance, attribute, value):
    """sp0d and parameterized evolve no spin, so the planet stays synchronous
    and orbit.axial_period must be unset; see "Star-planet models" in
    docs/Explanations/orbit.md.
    """
    model = instance.orbit.star_planet_model
    if model in ('sp0d', 'parameterized') and instance.orbit.axial_period is not None:
        raise ValueError(
            f'orbit.star_planet_model = {model!r} evolves no spin, so the planet is kept '
            "synchronous with its orbit and requires orbit.axial_period = 'none' "
            f'(got {instance.orbit.axial_period!r})'
        )

def parameterized_high_ecc_inward(instance, attribute, value):
    """The high-eccentricity law circularises at fixed orbital angular momentum,
    which can only shrink the orbit, so its final semi-major axis must not
    exceed the initial one, orbit.semimajoraxis.
    """
    params = instance.orbit.parameterized
    if (
        instance.orbit.star_planet_model == 'parameterized'
        and params.migration == 'high_ecc'
        and params.sma_final is not None
        and params.sma_final > instance.orbit.semimajoraxis
    ):
        raise ValueError(
            'High-eccentricity migration is inward only and requires '
            'orbit.parameterized.sma_final <= orbit.semimajoraxis, got '
            f'semimajoraxis={instance.orbit.semimajoraxis} and sma_final={params.sma_final}'
        )

def parameterized_excludes_accretion(instance, attribute, value):
    """Reject giant impacts with the parameterized star-planet model.

    After the migration epoch the track sets the semi-major axis every step,
    so an impact's new semi-major axis would be lost while its eccentricity
    change persisted; see "Star-planet models" in docs/Explanations/orbit.md.
    """
    if (
        instance.orbit.star_planet_model == 'parameterized'
        and instance.accretion.module is not None
    ):
        raise ValueError(
            "orbit.star_planet_model = 'parameterized' requires accretion.module = 'none' "
            f'(got {instance.accretion.module!r}): the prescribed track overwrites the '
            'semi-major axis an impact sets but keeps its eccentricity change'
        )

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',
        ),
        'morrigan': (
            instance.accretion.module == 'morrigan',
            'morrigan',
            'accretion.module = "morrigan" requires the optional morrigan package, '
            'which runs the giant-impact model. Morrigan is not needed for a '
            'standard PROTEUS run. Install it with: pip install '
            '"fwl-proteus[morrigan]" (or bash tools/get_morrigan.sh for an '
            'editable checkout).',
        ),
    }

    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 check_accretion_interior_compatibility(instance, attribute, value):
    """Reject accretion runs on an interior that cannot apply an impact.

    A giant impact re-melts the mantle and has to be applied at the state the
    timeline places it at. An interior that cannot do both is refused here at
    configuration load rather than at the first impact, which can be many hours
    into a run. SPIDER keeps its state in a restart file written by the external
    binary; the boundary interior never forwards its interior state object to the
    time-stepper, so the step cannot be capped to land on the impact and impacts
    would be applied late by an unbounded amount, or several would collapse onto
    the end of one long step. Furthermore, interior_struct.module == 'spider' is
    refused because SPIDER structure solves do not support non-thermal solves
    during giant impacts.
    """
    if instance.accretion.module is None:
        return

    interior = instance.interior_energetics.module
    reason = _ACCRETION_INCOMPATIBLE_INTERIORS.get(interior)
    if reason is not None:
        raise ValueError(
            "accretion.module = '"
            + str(instance.accretion.module)
            + "' cannot run with interior_energetics.module = '"
            + str(interior)
            + "': a giant impact re-melts the mantle and has to be applied where "
            'the timeline places it, but '
            + reason
            + ". Use interior_energetics.module = 'aragog' (or 'dummy' for a test)."
        )

    struct_module = getattr(getattr(instance, 'interior_struct', None), 'module', None)
    if struct_module == 'spider':
        raise ValueError(
            f"accretion.module = '{instance.accretion.module}' cannot run with "
            "interior_struct.module = 'spider': SPIDER structure solve does not "
            'support non-thermal solves during giant impacts.'
        )

def check_accretion_vapourise_compatibility(instance, attribute, value):
    """Reject accretion runs that also vapourise rock into the atmosphere.

    The two models keep incompatible books on the rock-forming elements. Rock
    vapourisation moves rock mass into the atmosphere without debiting it from
    the interior, which is why those elements are deliberately left out of
    ``M_ele`` and the whole-planet mass. An impact, in contrast, grows the
    planet's rock through the structure solve and conserves the per-element
    volatile budgets across that growth, and it sizes both the atmosphere it
    strips and the volatiles the impactor delivers from those same per-element
    columns. Run together, the vapour column would be stripped and delivered as
    though it were a tracked volatile budget while the mass it stands for is
    accounted nowhere, so the combination is refused at configuration load.
    """
    if instance.accretion.module is not None and instance.outgas.vapourise:
        raise ValueError(
            "accretion.module = '"
            + str(instance.accretion.module)
            + "' cannot run with outgas.vapourise = true: rock vapour adds "
            'rock-forming mass to the atmosphere that the whole-planet mass does '
            'not track, and an impact sizes its atmospheric stripping and volatile '
            'delivery from budgets that do. Disable one of the two.'
        )

def check_accretion_core_stratification_compatibility(instance, attribute, value):
    """Reject accretion runs with a stratified Aragog core_module core.

    An impact refits the core and books the heat of its temperature lift from the
    full-core heat content, while a stratified core evolves only its convecting
    volume, so the booked lift would not be the heat the solver integrates.
    """
    interior = instance.interior_energetics
    if (
        instance.accretion.module is not None
        and interior.module == 'aragog'
        and interior.aragog.core_bc == 'core_module'
        and interior.aragog.core_module.stratification
    ):
        raise ValueError(
            f"accretion.module = '{instance.accretion.module}' cannot run with "
            'interior_energetics.aragog.core_module.stratification = true: the core heat '
            'booked at an impact is the full-core content, while a stratified core evolves '
            'only its convecting volume. Disable one of the two.'
        )

def check_core_module_requirements(instance, attribute, value):
    """Reject an Aragog core_module core that its structure or solver cannot serve.

    The core profile is fitted to the core mass and the central pressure, which only the
    Zalmoxis structure provides, its CMB flux needs the entropy EOS tables, and Aragog
    refuses the resolved shell of a stratified core on Radau. A stratified core cannot be
    carried across a structure update, because Aragog gives no heat content for a
    stratified budget, so it needs a structure that is solved once: no dynamic update and
    no baseline re-solve after the start.
    """
    interior = instance.interior_energetics
    if interior.module != 'aragog' or interior.aragog.core_bc != 'core_module':
        return
    if instance.interior_struct.module != 'zalmoxis':
        raise ValueError(
            "interior_energetics.aragog.core_bc = 'core_module' needs "
            f"interior_struct.module = 'zalmoxis', not '{instance.interior_struct.module}': "
            'the core profile is fitted to the core mass and the central pressure of the '
            'Zalmoxis structure.'
        )
    if interior.const_properties:
        raise ValueError(
            "interior_energetics.aragog.core_bc = 'core_module' needs "
            'interior_energetics.const_properties = false: the CMB flux of the core model '
            'is computed with the entropy EOS tables, which constant properties do not load.'
        )
    if not interior.aragog.core_module.stratification:
        return
    if interior.aragog.solver_method == 'radau':
        raise ValueError(
            'interior_energetics.aragog.core_module.stratification = true needs '
            "interior_energetics.aragog.solver_method = 'cvode' or 'bdf', not 'radau'."
        )
    if (
        instance.interior_struct.zalmoxis.update_interval > 0
        or instance.planet.temperature_mode != 'liquidus_super'
    ):
        raise ValueError(
            'interior_energetics.aragog.core_module.stratification = true needs a structure '
            'that is solved once: interior_struct.zalmoxis.update_interval = 0 and '
            "planet.temperature_mode = 'liquidus_super'. The core is carried across a "
            'structure update with its heat content, which Aragog does not give for a '
            'stratified core.'
        )

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_liquidus_super_needs_tables(instance, attribute, value):
    """Require a P-S table route for ``temperature_mode = "liquidus_super"``.

    The spider and aragog interior modules build the ``liquidus_super``
    initial condition on interior P-S tables, which the interior wrapper
    supplies for the ``"zalmoxis"``, ``"spider"`` and ``"dummy"`` structure
    modules. With no structure module, no table set is provided
    and the initial condition has nothing to solve on.
    """
    if value.temperature_mode != 'liquidus_super':
        return
    if instance.interior_energetics.module not in ('spider', 'aragog'):
        return
    if instance.interior_struct.module is None:
        raise ValueError(
            "planet.temperature_mode = 'liquidus_super' has no valid route with "
            'interior_struct.module = None under interior_energetics.module = '
            f"'{instance.interior_energetics.module}': no P-S table set is provided. "
            "Set interior_struct.module to 'spider', 'dummy' or 'zalmoxis', or "
            'choose another planet.temperature_mode.'
        )

def energetics_needs_a_thermal_mantle_eos(instance, attribute, value):
    """Require a PALEOS or temperature-dependent energetics key for SPIDER or Aragog.

    Under the Zalmoxis structure the energetics read the tables and melting
    curves of the mantle's energetics key; a Seager2007, Chabrier or analytic
    key has none, so the run would read another set as a stand-in.
    """
    from proteus.utils.constants import PALEOS_EOS_PREFIXES, TDEP_EOS_PREFIXES
    from proteus.utils.helper import energetics_eos_key

    struct = instance.interior_struct
    zc = struct.zalmoxis if struct.module == 'zalmoxis' else None
    if value.module not in ('spider', 'aragog') or zc is None:
        return
    key = energetics_eos_key(zc.mantle_eos)
    if not (key or '').startswith(PALEOS_EOS_PREFIXES + TDEP_EOS_PREFIXES):
        raise ValueError(
            f"interior_energetics.module = '{value.module}' with mantle_eos="
            f"'{zc.mantle_eos}' has no energetics tables (energetics key: {key}). "
            'Use a PALEOS, WolfBower2018 or RTPress100TPa mantle EOS, or an MgSiO3 component '
            'of one of them in a mixture.'
        )

def aragog_needs_melting_curves(instance, attribute, value):
    """Require ``interior_struct.melting_dir`` for Aragog without a PALEOS table set.

    Aragog reads a solidus and a liquidus in every mode, from the generated
    PALEOS set or from ``melting_dir``. SPIDER is checked when the run starts
    instead: a resumed run continues on its kept P-S tables, and a
    ``const_properties`` run reads no curves.
    """
    from proteus.utils.helper import generates_paleos_tables

    if value.module != 'aragog' or instance.interior_struct.melting_dir is not None:
        return
    if generates_paleos_tables(instance.interior_struct):
        return
    raise ValueError(
        "interior_energetics.module = 'aragog' needs interior_struct.melting_dir unless Zalmoxis "
        'generates a PALEOS table set (a PALEOS mantle EOS under the Zalmoxis structure; a mixture '
        'follows its MgSiO3 component). The dummy structure requires it with any mantle EOS. '
        'Set melting_dir to a melting curve name (e.g. "Monteux-600").'
    )

def dummy_struct_mantle_eos(instance, attribute, value):
    """Check the mantle EOS that the dummy structure hands to SPIDER or Aragog.

    A mixture with two MgSiO3 sources has no energetics key and is rejected. With a
    PALEOS energetics key the solve uses the PALEOS P-S set and its curves, so a set
    ``melting_dir`` is passed to Aragog but does not change the solve; one warning says so.
    """
    from proteus.utils.constants import PALEOS_REGISTRY_KEYS
    from proteus.utils.helper import energetics_eos_key

    struct = instance.interior_struct
    if struct.module != 'dummy' or struct.zalmoxis is None:
        return
    if value.module not in ('spider', 'aragog'):
        return
    key = energetics_eos_key(struct.zalmoxis.mantle_eos)
    if struct.melting_dir is not None and key in PALEOS_REGISTRY_KEYS:
        log.warning(
            'interior_struct.melting_dir=%r does not change the solve: with module = "dummy" '
            'and the PALEOS mantle EOS %s, %s uses the PALEOS P-S set and its curves.',
            struct.melting_dir,
            struct.zalmoxis.mantle_eos,
            value.module,
        )

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."""
    # `global_miscibility` needs the H2-silicate binodal handoff (Zalmoxis tracker #64),
    # not yet implemented. Reject it for every structure module: only the zalmoxis
    # structure writes the solvus that the main loop and SPIDER read.
    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.'
        )

    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}'"
        )

    # A component is '<source>:<material>' with at most one positive fraction, as Zalmoxis
    # parses it; Zalmoxis divides a mixture's fractions by their sum.
    def _number(token):
        try:
            return float(token)
        except ValueError:
            return None

    layers = [
        ('core_eos', core_eos),
        ('mantle_eos', mantle_eos),
        ('ice_layer_eos', ice_layer_eos),
    ]
    for name, eos_val in (layer for layer in layers if layer[1]):
        for comp in (c.strip() for c in eos_val.split('+')):
            tokens = comp.split(':')
            fraction = _number(tokens[2]) if len(tokens) == 3 else 1.0
            if (
                len(tokens) not in (2, 3)
                or not all(tokens[:2])
                or any(_number(t) is not None for t in tokens[:2])
                or any(ch.isspace() for ch in comp)
                or fraction is None
                or not 0 < fraction < float('inf')
            ):
                raise ValueError(
                    f"`interior_struct.zalmoxis.{name}` component '{comp}' is not "
                    "'<source>:<material>[:<fraction>]' with a positive finite fraction "
                    'and no spaces'
                )

    # 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 scales the derived solidus only for the PALEOS EOS family
    mzf = getattr(instance.zalmoxis, 'mushy_zone_factor', 0.8)
    layer_eos = [core_eos, mantle_eos, ice_layer_eos]
    if mzf < 1.0 and not any(e and e.startswith(PALEOS_EOS_PREFIXES) for e in layer_eos):
        _log.warning(
            'mushy_zone_factor=%.2f has no effect with core EOS %s, mantle EOS %s '
            'and ice layer EOS %s. The mushy zone factor applies only to the PALEOS '
            'EOS family. For WolfBower2018/RTPress100TPa, the mushy zone is defined '
            'by the solidus/liquidus melting curve files.',
            mzf,
            core_eos,
            mantle_eos,
            ice_layer_eos,
        )

    # 2-layer model (no ice layer, non-T-dep mantle): mantle_mass_fraction must be 0
    if ice_layer_eos is None and not mantle_eos.startswith(TDEP_EOS_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).'
            )