Md/obliqua

[MarijnJ0]

Description

The PR introduces the Obliqua tidal module into PROTEUS, along with three compatible orbital dynamics models. The implementation adds:

• Obliqua tides option, allowing for multiphase tidal calculation in 1D for the primary (planet).
• Obliqua tides lookup tables, allowing the user to provide pregenerated lookup tables/interior data files, and extract/obtain associated full Love number spectra.
• Star-Planet orbital model with spin-orbit dynamics and eccentricity evolution (planet-only).
• Planet-Satellite orbital model with SO+e for both primary and perturber.
• Planet-Satellite orbital model with SO+e for both primary and perturber + evection resonance.
• For these orbit models, a hansen.py file is added, which computes a complete lookup table. This removes any overhead away from the solver, and speeds up the integration.
• The orbit models (bare ODEs) are all evolved through a shared time stepping function, which ensures proper convergence and can be tweaked in the config.
• Time stepping is handled using three clocks: PROTEUS clock, set overall coarse time stepping; solver clock, handles the model integration with event detection for ER; storage clock, controls what time steps/data is saved to disk.
• Angular momentum conservation holds, and additional changes in the planet's gyration parameter are smoothly cancelled by AM conserving changes in the spin.
• New plotting scripts are added to track the Love number evolution, the orbit (primary+perturber), and the ER.

I added Obliquato the docs and also changed some of the phrasing in the docs, specifically things like:

• 'Obliqua evolves the orbit' --> 'Obliqua models tides, PROTEUS internally evolves the orbit.'
• 'Lovepy is multi-phase' --> 'Lovepy is solid-phase'

I tried keeping to the 500 line file limit, but this was not possible for the satellite.py file.

I added basic unit and smoke tests, and one particular case that recreates figure 4 in Canup & Rufu (2020). This takes a little while to run, but is a strong model validation test.

Issues

Obliqua should still be added to PROTEUS doctor (issue #670)

Closes #578, #484, #743, #801

Directly related #843

Validation of changes

The unit tests pass on my machine: Ubuntu 24.04 LTS (noble) with Python 3.12.11

I also have some example output from the ER capture in PROTEUS. Basic orbital dynamics has been tested, and AM remains conserved even at the 1e9 yr mark.

Checklist

• I have followed the contributing guidelines
• My code follows the style guidelines of this project
• I have performed a self-review of my code
• My changes generate no new warnings or errors
• I have checked that the tests still pass on my computer
• I have updated the docs, as appropriate
• I have added tests for these changes, as appropriate
• I have checked that all dependencies have been updated, as required

@timlichtenberg @nichollsh

[nichollsh]

@MarijnJ0 please can you updated the pinned AGNI version in the PROTEUS pyproject.toml file to 1c4baad046c52ec2205508062fbcb962bce15375? Thanks.

[timlichtenberg]

Blocking issue in the inline comment: four shipped config files no longer load on this branch. Let's get those migrated before merge, otherwise looks good.

[timlichtenberg]

Re-checked after the latest commit. The four config files that failed to load under the 3.0 schema now parse correctly, and both integration tests that were affected pass, including the zalmoxis test that was previously silently skipping instead of running. That resolves the blocking issue from the last review.

I also looked at the open thread on wrapper.py:296 about the Time<=1 seeding gate, since it's still unresolved and touches the same orbit code path. In the dummy integration test's actual output, semimajorax and eccentricity are seeded to nonzero values at Time=0 and evolve smoothly through the run, so the gate is not being skipped for this config. Not blocking on my end; leaving the thread for whoever raised it to close.

Approving.

[MarijnJ0]

Ok perfect, I went through the final open threads, they seem to be resolved. Now merging this into main!!

[nichollsh]

Fantastic work! Exciting to see this merged.