Fetch reference data through fwl-io and require the tables each run reads

docs/Explanations/dummy_modules.md

@@ -41,8 +41,11 @@ Earth-like mineralogy and variable iron content.
 
 The dummy structure module provides all the radial profiles that SPIDER and
 Aragog need as boundary conditions without running a hydrostatic
-equilibrium solver or loading EOS tables. When paired with the dummy
-energetics module, the entire interior is analytically specified.
+equilibrium solver or loading EOS tables. SPIDER and Aragog then read their
+P-S tables from FWL_DATA or the SPIDER lookup data and the melting curves
+named by `interior_struct.melting_dir`; the dummy structure never uses PALEOS
+tables. When paired with the dummy energetics module, the entire interior is
+analytically specified.
 
 ### Interior energetics: dummy (`interior_energetics.module = 'dummy'`)
 

docs/How-to/doctor.md

@@ -41,8 +41,8 @@ non-empty:
 
 | Check | Fix command |
 |-------|-------------|
-| `FWL_DATA/spectral_files` | `proteus get spectral` |
-| `FWL_DATA/stellar_spectra` | `proteus get stellar` |
+| `FWL_DATA/atmos_clim/spectral_files` | `proteus get spectral` |
+| `FWL_DATA/star/spectra` | `proteus get stellar` |
 
 ### Package versions
 
@@ -84,8 +84,8 @@ Environment
   [ok] julia: 1.13.0
 
 Reference data
-  [ok] FWL_DATA/spectral_files: present
-  [ok] FWL_DATA/stellar_spectra: present
+  [ok] FWL_DATA/atmos_clim/spectral_files: present
+  [ok] FWL_DATA/star/spectra: present
 
 Package versions
   [ok] fwl-proteus: 25.10.15 [editable @ PROTEUS -> a1b2c3d]

docs/How-to/usage_initial_conditions.md

@@ -117,16 +117,29 @@ liquidus at the binding depth.
     the interior solver uses for its melt fraction. Where those tables come
     from depends on the structure module:
 
-    - `"zalmoxis"` and `"dummy"` with a PALEOS mantle
-      (`interior_struct.zalmoxis.mantle_eos`, default `"PALEOS:MgSiO3"`) whose
-      table files are present: Zalmoxis generates the tables from that EOS,
-      with a liquidus derived from the PALEOS (Fei et al. 2021) curve.
-      `interior_struct.melting_dir` is not used, and Zalmoxis must be
-      installed.
-    - `"spider"`, or `"zalmoxis"` and `"dummy"` when no PALEOS table set is
-      generated: the tables come from FWL_DATA or the SPIDER lookup data, and
-      when `interior_struct.melting_dir` is set PROTEUS derives
-      `liquidus_P-S.dat` from that P-T curve.
+    - `"zalmoxis"` with a PALEOS mantle EOS (`interior_struct.zalmoxis.mantle_eos`,
+      default `"PALEOS:MgSiO3"`): Zalmoxis generates the tables from that EOS,
+      with a liquidus derived from the PALEOS (Fei et al. 2021) curve, and
+      Aragog builds its phase-property tables from PALEOS too.
+      `interior_struct.melting_dir` is not used. A mixture (a `+` in
+      `mantle_eos`) follows its MgSiO$_3$ component, so a mixture with
+      `PALEOS:MgSiO3` gets the tables of a `PALEOS:MgSiO3` mantle; a PALEOS
+      mixture without an MgSiO$_3$ component gets the MgSiO$_3$ two-phase
+      tables of its PALEOS family.
+    - `"spider"` and `"dummy"`, or `"zalmoxis"` when no PALEOS table set is
+      generated, which includes a mixture whose MgSiO$_3$ component is not
+      PALEOS (for example `"WolfBower2018:MgSiO3:0.9+PALEOS:H2O:0.1"`): the
+      tables come from FWL_DATA (SPIDER also falls back to its own lookup
+      data), Aragog also takes its phase-property files from that Wolf & Bower
+      (2018) set or `interior_struct.eos_dir`, `interior_struct.melting_dir`
+      must be set (the run stops when it is unset, except for
+      `interior_energetics.module = "spider"` with `const_properties = true`),
+      and PROTEUS derives `liquidus_P-S.dat` from that P-T curve.
+
+    Aragog takes its thermodynamics and melt fraction from the P-S tables. With
+    `"zalmoxis"`, which gives the core-mantle boundary pressure, Aragog logs a
+    warning when that pressure is above the highest pressure of the P-S table
+    set in use (about 1 TPa for the fetched Wolf & Bower (2018) set).
 
     With `"zalmoxis"`, the structure solve also anchors its temperature profile
     on a P-T adiabat that is `delta_T_super` above the P-T liquidus, while the
@@ -188,13 +201,6 @@ liquidus at the binding depth.
       which pressures the adiabat samples in that band, so the edge, and the
       cap with it, can shift with the core-mantle boundary pressure.
 
-    With `"dummy"` and PALEOS-generated tables there is no anchor, so a large
-    `delta_T_super` can land in those filled cells. The two adiabats differ
-    slightly: for 1 Earth mass at `delta_T_super = 500` K (core-mantle
-    boundary at 103 GPa), the
-    P-T anchor evaluated on the P-S tables has a smallest margin of 472 K
-    above their liquidus, against 500 K for the initial entropy.
-
     The superheat is checked exactly at every pressure where the margin can
     change slope: the table pressure nodes, the liquidus-file nodes, and the
     pressures where the liquidus entropy crosses a table entropy node.

docs/Reference/config/atmosphere.md

@@ -88,7 +88,7 @@ interior heat flux. The `fastchem_*` parameters apply when
 
 | Parameter | Type | Default | Description |
 |---|---|---|---|
-| `surf_material` | str | `"greybody"` | Surface scattering material file. Set to 'greybody' to use surf_greyalbedo. |
+| `surf_material` | str | `"greybody"` | Surface scattering material: the file name of a Hammond et al. (2024) spectrum, e.g. 'lunarmarebasalt.dat', or 'greybody' to use surf_greyalbedo. |
 | `surf_roughness` | float | `0.001` | Characteristic surface roughness scale \[metres\]. Must be > 0. |
 | `surf_windspeed` | float | `2.0` | Characteristic surface wind speed \[m/s\]. Must be > 0. |
 

docs/Reference/config/config_schema.json

@@ -4977,7 +4977,7 @@
       "default": "none",
       "choices": null,
       "bounds": null,
-      "description": "Melting curve folder name in FWL_DATA, for the SPIDER structure module.",
+      "description": "Melting curve name in FWL_DATA. Required for the SPIDER structure module and for any run without a PALEOS table set; not read with module = 'zalmoxis' and a single PALEOS mantle EOS.",
       "doc_source": "attributes",
       "group_order": 0,
       "group_position": 0,
@@ -7741,7 +7741,7 @@
       "default": "\"greybody\"",
       "choices": null,
       "bounds": null,
-      "description": "Surface scattering material file. Set to 'greybody' to use surf_greyalbedo.",
+      "description": "Surface scattering material: the file name of a Hammond et al. (2024) spectrum, e.g. 'lunarmarebasalt.dat', or 'greybody' to use surf_greyalbedo.",
       "doc_source": "attributes",
       "group_order": 1,
       "group_position": 0,
@@ -10964,6 +10964,17 @@
       ],
       "doc": "Reject enabling this option when the dummy atmos_clim module is selected."
     },
+    {
+      "validator": "aragog_needs_melting_curves",
+      "module": "_config.py",
+      "attached_to": [
+        "interior_energetics"
+      ],
+      "touches": [
+        "interior_struct.melting_dir"
+      ],
+      "doc": "Require ``interior_struct.melting_dir`` for Aragog without a PALEOS table set."
+    },
     {
       "validator": "boreas_requires_atmosphere",
       "module": "_config.py",
@@ -11026,6 +11037,17 @@
       ],
       "doc": "Check that required external packages are importable for the selected modules."
     },
+    {
+      "validator": "energetics_needs_a_thermal_mantle_eos",
+      "module": "_config.py",
+      "attached_to": [
+        "interior_energetics"
+      ],
+      "touches": [
+        "interior_struct"
+      ],
+      "doc": "Require a PALEOS or temperature-dependent energetics key for SPIDER or Aragog."
+    },
     {
       "validator": "instmethod_dummy",
       "module": "_config.py",

docs/Reference/config/interior.md

@@ -26,7 +26,7 @@ with an equation of state (EOS).
 | `module` | str or none | `"zalmoxis"` | Module for solving the planet's interior structure. Choices: `none`, `"dummy"`, `"spider"`, `"zalmoxis"`. |
 | `core_density` | float or str | `"self"` | Density of the planet's core \[kg m-3\]. Set to 'self' for self-consistent calculation by Zalmoxis (requires module = 'zalmoxis'). |
 | `core_heatcap` | float or str | `"self"` | Specific heat capacity of the planet's core \[J kg-1 K-1\]. Set to 'self' for self-consistent calculation by Zalmoxis (requires module = 'zalmoxis'). |
-| `melting_dir` | str or none | `none` | Melting curve folder name in FWL_DATA, for the SPIDER structure module. |
+| `melting_dir` | str or none | `none` | Melting curve name in FWL_DATA. Required for the SPIDER structure module and for any run without a PALEOS table set; not read with module = 'zalmoxis' and a single PALEOS mantle EOS. |
 | `eos_dir` | str or none | `none` | EOS folder name in FWL_DATA, for the SPIDER structure module. |
 <!-- END GENERATED: config-table [interior_struct] -->
 
@@ -117,8 +117,7 @@ belong to the experimental binodal-aware mode.
 The MgSiO$_3$ mantle EOS resolves through two distinct paths depending on the `<source>` prefix of `mantle_eos`.
 
 With `mantle_eos = "PALEOS:MgSiO3"` (the default), the hydrostatic structure solve uses the PALEOS *unified* MgSiO$_3$ table for the density profile.
-The phase-specific property surfaces used by Aragog (density, heat capacity, thermal expansion, adiabatic gradient) and the pressure-entropy lookup tables are built from the PALEOS *two-phase* solid and liquid tables shipped with Zalmoxis when those tables are present, which keeps the properties well resolved across the melting-curve discontinuity that a single unified table interpolates through.
-If the two-phase tables are not available, the property surfaces are built from the unified table alone, and the entropy near the melting curve is less reliable.
+The phase-specific property surfaces used by Aragog (density, heat capacity, thermal expansion, adiabatic gradient) and the pressure-entropy lookup tables are built from the PALEOS *two-phase* solid and liquid tables, which keeps the properties well resolved across the melting-curve discontinuity that a single unified table interpolates through.
 The liquidus is the analytic PALEOS curve (Belonoshko et al. 2005 below 2.55 GPa, Fei et al. 2021 above, in Simon-Glatzel form), and the solidus is derived as $T_\mathrm{sol}(P) = f\,T_\mathrm{liq}(P)$ with $f$ the `mushy_zone_factor` (default 0.8).
 The default is the constant solidus-to-liquidus ratio ($\approx 0.809$) of the Stixrude (2014)[^cite-stixrude2014] MgSiO$_3$ melting parametrization, applied to the PALEOS liquidus instead of the Stixrude liquidus.
 The derived solidus is therefore a constant depression of the PALEOS liquidus, not the Stixrude solidus curve: its absolute value lies well above the Stixrude solidus at low to moderate pressure (about 2900 K against 1700 K at 20 GPa, and about 10% higher at 140 GPa) and below it above roughly 200 GPa.
@@ -127,6 +126,16 @@ The melt fraction then follows from the lever rule between this solidus and liqu
 With `mantle_eos = "PALEOS-2phase:MgSiO3"`, the SPIDER/Aragog entropy tables use the separate solid and liquid PALEOS tables, which supply the latent-heat entropy gap across the melting curve directly rather than through a single interpolated unified table.
 Their phase boundaries follow the same construction as the unified case: the liquidus is the analytic PALEOS curve, and the solidus is derived as $T_\mathrm{sol}(P) = f\,T_\mathrm{liq}(P)$ with $f$ the `mushy_zone_factor`.
 
+A run with a PALEOS EOS requires the table of each PALEOS layer, with the MgSiO$_3$ unified table only when a layer is `PALEOS:MgSiO3`. A mantle with a PALEOS component also requires the MgSiO$_3$ two-phase solid and liquid pair: the high-resolution pair for `PALEOS-2phase:MgSiO3-highres`, and the PALEOS-API cache for the PALEOS-API family.
+When one is missing, the run stops before the first solve with an error that names each missing file and the command that fetches them, `proteus get interiordata --config-path <config.toml>`; it does not fall back to another table set.
+With `dry_mantle = false` it also requires the tables of the dissolved volatiles (`PALEOS:H2O` and `Chabrier:H`).
+A resumed SPIDER run that keeps its pressure-entropy tables needs only the tables of its layers. With `temperature_mode = "liquidus_super"` it also needs the two-phase pair that its anchor reads. An Aragog resume always needs the two-phase pair, which it reads when the mesh changes.
+A mixture mantle (a `+` in `mantle_eos`) takes its melting curves, in the structure and in the energetics, and its SPIDER or Aragog tables from its MgSiO$_3$ component: with `PALEOS:MgSiO3` it gets exactly the curves and tables of a `PALEOS:MgSiO3` mantle, and with `WolfBower2018:MgSiO3` the `eos_dir` P-S tables (by default Wolf and Bower 2018) and the `melting_dir` curves. The other components enter only the structure density.
+A PALEOS mantle with no MgSiO$_3$ component (for example `mantle_eos = "PALEOS:H2O"`, `"PALEOS:iron"`, or a mixture of the two) uses the density of its own material in the structure, while the PALEOS MgSiO$_3$ melting curves and the two-phase MgSiO$_3$ tables of its PALEOS family stand in for the energetics.
+With SPIDER or Aragog, the energetics must follow a PALEOS, `WolfBower2018` or `RTPress100TPa` EOS; a mantle whose energetics would follow a Seager2007, Chabrier or analytic EOS is rejected when the configuration loads.
+`temperature_mode = "liquidus_super"` solves the initial adiabat on the MgSiO$_3$ two-phase tables for every mantle, so those tables are required at the start of the run.
+The run logs one warning that names the cases that apply at the start of each run segment, so a resumed run logs it again.
+
 !!! note "`mushy_zone_factor` and the two-phase structure solve"
     In a PROTEUS-coupled run, `load_zalmoxis_solidus_liquidus_functions` builds the `mushy_zone_factor * liquidus` solidus described above and passes it into the Zalmoxis structure solve. The same curve pair sets the SPIDER/Aragog table boundaries, the adiabatic gradient in the mushy zone, and the two-phase density (`PALEOS-2phase`, `PALEOS-API-2phase`), so `mushy_zone_factor` acts consistently in the tables and in the structure.
     A standalone Zalmoxis run uses its own `rock_solidus` and `rock_liquidus` keys (Stixrude 2014 by default). With those defaults a two-phase mantle does not depend on `mushy_zone_factor`; with no unified PALEOS layer elsewhere (for example a `Seager2007:iron` core), a value below 1.0 is rejected at validation. A unified PALEOS layer such as a `PALEOS:iron` core does honor the factor in its own density, so validation accepts it, but it does not change the two-phase mantle. Setting `rock_liquidus = "PALEOS-liquidus"` selects the PALEOS liquidus and derives the solidus as `mushy_zone_factor * liquidus`, as in the coupled case.
@@ -384,7 +393,9 @@ with prescribed solidus and liquidus and parameterised convective heat transport
 <!-- Generated by tools/generate_config_reference.py; edit src/proteus/config/, not this table -->
 Cross-field constraints enforced when the config file loads:
 
+- Require ``interior_struct.melting_dir`` for Aragog without a PALEOS table set.
 - Boundary backend assumes a fixed surface state coupling.
+- Require a PALEOS or temperature-dependent energetics key for SPIDER or Aragog.
 - Interior tidal heating requires an tides module to be enabled.
 - Aragog requires at least one energy transport term to be enabled.
 - Validate Boundary backend's solidus/liquidus ordering.