Support per-node material types for multi-material equations of state

[timlichtenberg]

Problem

SPIDER currently assigns a single equation of state (EOS) globally for the entire mantle. When reading an external mesh file, the file provides radius, pressure, density, and gravitational acceleration at each node — but does not carry information about which EOS table applies at each depth. SPIDER uses its global material assignment (SPIDER_MANTLE_MATERIAL_PARAMS and similar options) uniformly across all nodes.

This is a significant limitation for realistic planetary interiors, where different depths may have different compositions:

• Compositional layering: A bridgmanite-dominated lower mantle may have different thermodynamic properties than an olivine-rich upper mantle. Post-perovskite transitions at ultra-high pressures (>120 GPa) introduce yet another material phase.
• Core-mantle transition zone: The region near the core-mantle boundary may contain a mix of iron alloy and silicate, with different EOS from either pure endmember.
• Volatile-bearing layers: If the mantle contains significant water or carbon, the EOS of hydrous/carbonated phases differs from the dry silicate tables currently used.
• Ice layers (super-Earths): For planets with significant water mantles, high-pressure ice phases (ice VII, ice X) require entirely different EOS tables from silicate phases.

Current state

• The external mesh file format (# nb ns header, then r P rho g per node) has no field for material type.
• parameters.c handles EOS selection globally through options like -SPIDER_MANTLE_MATERIAL_PARAMS.
• The interpolation code in interp.c uses a single Interp2d structure per material phase (solid, melt, mixed), indexed globally.
• The mixing-length convection model in matprop.c evaluates thermal expansion, heat capacity, and other properties from these global interpolation tables.

Proposed approach

1. Extend the external mesh file format to include an optional integer material index per node (backward-compatible: if absent, assume the current global assignment):

   # nb ns [nmaterials]
   r P rho g [material_id]
   

2. Per-material EOS tables: Allow loading multiple sets of EOS tables. Each material_id maps to a set of (solid, melt, mixed) interpolation tables. The Interp2d structures would become arrays indexed by material.

3. Node-level EOS evaluation: In matprop.c (and wherever EOS lookups happen), use the node's material_id to select the correct interpolation table instead of the global one.

4. Zalmoxis integration: Zalmoxis already supports per-layer material assignment (core vs mantle). Extending this to multiple mantle layers and passing the material index through PROTEUS's mesh interpolation would close the loop.

Complexity and priority

This is a significant refactor touching the core data structures (Ctx, Interp2d, EOS evaluation throughout matprop.c). It also requires extending the Zalmoxis output and PROTEUS mesh interpolation. Estimated effort: weeks of development plus validation.

This is a high priority for scientific realism — the single-material assumption is the largest remaining physical limitation of the SPIDER-Zalmoxis coupling. Without it, compositional stratification during magma ocean solidification (e.g., dense FeO-rich cumulates sinking, forming a basal magma ocean) cannot be captured.