Md/obliqua

.github/actions/setup-proteus/action.yml

@@ -16,7 +16,7 @@ inputs:
   julia-version:
     description: Julia version
     required: false
-    default: '1.12.6'
+    default: '1.13.0'
   install-editable-submodules:
     description: >
       Whether to clone MORS / aragog / JANUS / CALLIOPE / ZEPHYRUS / Zalmoxis

.github/workflows/ci-nightly.yml

@@ -262,6 +262,13 @@ jobs:
             os: ubuntu-latest
             files: >-
               tests/integration/test_slow_agni_aragog.py
+          # ---- shard: orbit-evection (pure orbit.satellite physics,
+          # no real submodule needed; Linux-only, ~25-40 min) ----
+          - shard: orbit-evection
+            tier: extended
+            os: ubuntu-latest
+            files: >-
+              tests/integration/test_slow_orbit_evection_ctl.py
           # ---- shard: grid (dummy-backend parameter grid; a single
           # module-scoped fixture runs the whole grid, ~27 min. Linux-only
           # extended because it needs no macOS parity) ----

.gitignore

@@ -86,6 +86,13 @@ lovepy
 Lovepy
 LOVEPY
 LovePy
+obliqua
+Obliqua
+OBLIQUA
+Obliqua_data
+platon
+Platon
+PLATON
 /prt
 petitradtrans
 petitRADTRANS

docs/Explanations/code_architecture.md

@@ -12,7 +12,7 @@ coupled planetary evolution simulation:
 - [`atmos_chem/`](https://github.com/FormingWorlds/PROTEUS/tree/main/src/proteus/atmos_chem): atmospheric photochemistry (VULCAN, dummy)
 - [`escape/`](https://github.com/FormingWorlds/PROTEUS/tree/main/src/proteus/escape): atmospheric mass loss (ZEPHYRUS, dummy)
 - [`outgas/`](https://github.com/FormingWorlds/PROTEUS/tree/main/src/proteus/outgas): volatile partitioning (CALLIOPE, atmodeller, dummy)
-- [`orbit/`](https://github.com/FormingWorlds/PROTEUS/tree/main/src/proteus/orbit): orbital evolution and tides (Obliqua/LovePy, dummy)
+- [`orbit/`](https://github.com/FormingWorlds/PROTEUS/tree/main/src/proteus/orbit): tidal response (Obliqua/LovePy, dummy) and orbital evolution (native)
 - [`star/`](https://github.com/FormingWorlds/PROTEUS/tree/main/src/proteus/star): stellar evolution and spectra (MORS, dummy)
 
 Most modules follow a common pattern: a `wrapper.py` defining the dispatch

docs/Explanations/dummy_modules.md

@@ -139,7 +139,7 @@ from Kepler's third law. A configurable tidal heating amplitude
 (`H_tide`) is applied to mantle layers where the melt fraction exceeds
 a threshold (`Phi_tide`), providing a simple parameterised heat source
 for testing the interior module's response to tidal power without
-running the full LovePy viscoelastic solver.
+running the full LovePy or Obliqua viscoelastic solvers.
 
 ---
 

docs/Explanations/model.md

@@ -45,7 +45,8 @@ atmosphere), enabling hierarchical model intercomparison.
 | Star | [MORS](https://proteus-framework.org/MORS/), dummy | Stellar evolution and spectrum |
 | Escape | [ZEPHYRUS](https://github.com/FormingWorlds/ZEPHYRUS), dummy | Atmospheric escape |
 | Outgassing | [CALLIOPE](https://proteus-framework.org/CALLIOPE/), [atmodeller](https://github.com/djbower/atmodeller), dummy | Volatile exchange between interior and atmosphere |
-| Orbit | [Obliqua](https://github.com/FormingWorlds/Obliqua), dummy | Orbital evolution and tidal heating |
+| Tides | [Obliqua](https://proteus-framework.org/Obliqua), [Lovepy](https://github.com/nichollsh/LovePy), dummy | Tidal response of the planet (Love numbers, heating) |
+| Orbit | PROTEUS (internal) | Orbital evolution (semi-major axis, eccentricity, spin) |
 | Observations | [petitRADTRANS](https://petitradtrans.readthedocs.io/), none | Synthetic transit and eclipse spectra |
 
 Each module is maintained in its own repository and can be used as a standalone package outside of PROTEUS. The following sections describe each module's physical role and how PROTEUS couples to it.
@@ -189,11 +190,17 @@ Some notable consequences of step 3:
 
 `utils.coupler.assert_mass_conservation` therefore checks two things separately. `M_atm <= M_planet` is enforced under `outgas.vapourise = false`. `M_vol_atm` equals the sum of the per-species atmospheric masses; rock vapour is excluded from `M_vol_atm` by definition.
 
-## Orbital evolution: Obliqua
+## Tidal evolution: Obliqua, Lovepy
 
-**[Obliqua](https://github.com/FormingWorlds/Obliqua)** (Julia) evolves the orbital semi-major axis and eccentricity under the influence of tidal dissipation. The tidal response of the planet is computed from its interior structure and rheology using a viscoelastic love-number solver (LovePy). Tidal heating power is distributed radially across the mantle and fed back into the interior energy equation. Obliqua also computes the spin-orbit evolution and checks for dynamical stability (Roche limit, Hill sphere).
+**[Obliqua](https://proteus-framework.org/Obliqua)** (Julia) computes the multi-phase tidal response of the planet. The tidal love-numbers of the planet is computed from its interior structure and rheology using various viscoelastic rheological models. Tidal heating power is distributed radially across the mantle and fed back into the interior energy equation. The model is valid for arbitrary eccentricity and spin-orbit misalignment, as it models arbitrary tidal degrees and modes.
 
-Config section: `[orbit]`. Reference: [Star and orbit configuration](../Reference/config/star_orbit.md).
+**[Lovepy](https://github.com/nichollsh/LovePy)** (Julia) computes the solid-only tidal response of the planet using a Maxwell rheology. Tidal heating power is distributed radially across the mantle and fed back into the interior energy equation. It assumes spin-orbit synchronisation and a small eccentricity, as only the dominant degree-2 tidal modes are considered.
+
+## Orbital evolution: PROTEUS (internal)
+
+**[Orbital evolution](https://github.com/FormingWorlds/PROTEUS/tree/main/src/proteus/orbit)** (Python) computes the time evolution of the independent orbital parameters (semi-major axis, eccentricity, spin, apsidal precession) under the influence of tidal dissipation in both the primary and the perturbing body. The model combines spin-orbit dynamics with eccentricity evolution, based on a vectorial approach expressed in Hansen coefficients. The model allows for angular momentum draining through the evection resonance, but conserves it in all other cases.
+
+Config section: `[orbit]`. Reference: [Star and orbit configuration](../Reference/config/star_orbit.md). For the full set of star-planet and planet-satellite models (sp0d/sp1d/ps0d/ps1d/ps1d_evec), the evection resonance, and the satellite Love-number lookup workflow, see [Orbital dynamics and tides](orbit.md).
 
 ## Synthetic observations: petitRADTRANS
 
@@ -240,7 +247,7 @@ architecture and for quick parameter exploration.
 | Star | Fixed effective temperature and luminosity; Planck-function spectrum at a user-specified $T_\mathrm{eff}$ |
 | Escape | Constant bulk mass loss rate (user-specified kg/s), distributed proportionally across elements |
 | Outgassing | Melt-fraction-dependent volatile partitioning with fixed stoichiometry, no equilibrium chemistry |
-| Orbit | Fixed semi-major axis and eccentricity; configurable parameterised tidal heating |
+| Orbit & Tides | Fixed semi-major axis and eccentricity; configurable parameterised tidal heating |
 
 The [Quick start tutorial](../Tutorials/quick_start_dummy.md) runs PROTEUS
 with all modules set to dummy.