Md/docs refs

[MarijnJ0]

Description

Adds a new legacy mode for backwards comaptibility in PROTEUS, Obliqua effectively acts as Lovepy.

Adds a Love number cap, specifically, when in PROTEUS dt is large and we encounter an interior seismic resonance, the Lovenumbers can inflate. This causes rapid orbital migration which is not resolved with the given dt. One work around is to limit the Lovenumbers, this way the response is averaged out across the larger timestep. Using cap_LN with enforce_ec ensures the heating profiles are scaled properly to conserve energy.

I also added small fix to the solid1d and solid1d_mush models, these now get even closer to the *_relax models.

Finally, I added some tweaks to the docs, following the latest changes to the numerical implementation.

Tests still pass, no new issues.

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

Relevant people

@nichollsh @timlichtenberg

[Copilot]

🟡 Changes recommended

Love-number interpolation can bypass the cap, and end-to-end coverage for legacy and capped paths is missing.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds LovePy-compatible legacy spectrum support, Love-number capping, solver boundary fixes, and related test/documentation updates.

Changes:

• Adds legacy spectrum handling and optional cap_LN.
• Corrects solid and mush core initialization.
• Updates tests, configuration, and numerical documentation.

File summaries

File	Description
test/test.toml	Documents cap_LN.
test/test_obliqua.jl	Adds cap tests and updates regressions.
src/solid1d.jl	Fixes CMB basis initialization.
src/solid1d_mush.jl	Applies the CMB correction to mush models.
src/Obliqua.jl	Implements legacy spectra and Love-number capping.
res/config/all_options.toml	Documents new configuration options.
docs/src/reference/tidal-potentials.md	Updates tidal normalization documentation.
docs/src/reference/surface-loading.md	Revises surface boundary conditions.
docs/src/reference/solid/solid1d.md	Updates shooting-method documentation.
docs/src/reference/solid/solid1d_relax.md	Updates relaxation documentation.
docs/src/reference/solid/solid1d_mush.md	Updates porous shooting documentation.
docs/src/reference/solid/solid1d_mush_relax.md	Documents mush interfaces.
docs/src/reference/solid/solid1d_equil_relax.md	Documents equilibrium relaxation.
docs/src/reference/solid/solid0d.md	Documents zero-dimensional Love numbers.
docs/src/reference/solid-phase.md	Revises matrices and core options.
docs/src/reference/rheology.md	Updates rheology formulas.
docs/src/reference/liquid-phase.md	Documents dynamic dissipation profiles.
docs/src/reference/index.md	Refreshes reference navigation.
docs/src/reference/forcing-frequency.md	Updates forcing-frequency documentation.
docs/src/reference/configuration-file.md	Expands configuration reference.
docs/src/how-to-guides/config_file.md	Updates configuration guidance.

Review details

Suppressed comments (9)

docs/src/reference/forcing-frequency.md:18

• The Hansen integral shown here does not match either the implementation or the stated coefficient $X_k^{-(n+1),m}$: the spin/orbital symbols are constants in the displayed integrand, and the integration variable is also written as the orbital frequency. Hansen.get_hansen integrates over mean anomaly $M$ using $(r(M)/a)^{-(n+1)}e^{im f(M)-ikM}$. Please correct the equation so the reference gives the actual $k$-mode definition.

```math
|X^{-(n+1), m}_k(e) |= \bigg|
\frac{1}{2\pi} \int_0^{2\pi}
\left(\frac{r}{a}\right)^n
e^{im\Omega - ikn_{\mathrm{orb}}}\,dn_{\mathrm{orb}} \bigg| \geq 0.001,

docs/src/reference/liquid-phase.md:95

• The claim that the three budgets always sum to E_total is not true when E_total < E_inf: the implementation clips the friction budget to zero and sets the drag budget to max(E_inf - E_sbd, 0), so the profile integrates to E_inf (when the baseline exceeds the hand-off component), not E_total. That case can occur for the documented drag parameters; either fix/validate the budget allocation or qualify this equation.

The `dynamic_interp` profile (the default `sigma_R_prf`) replaces the single depth-dependent shape function above with a composite of three physically distinct contributions, each assigned its own share of the total dissipated power so that the three shares sum exactly back to the total:

$$P(z) = P_{\mathrm{sbd}}(z) + P_{\mathrm{drag}}(z) + P_{\mathrm{fric}}(z), \qquad
\int P\,dV = E_{\mathrm{sbd}} + E_{\mathrm{drag}} + E_{\mathrm{fric}} = E_{\mathrm{total}}.$$

docs/src/reference/solid-phase.md:184

• The braces around -\rho_0\omega^2 make this read as a grouped factor multiplied by the preceding term, but the implementation adds the inertial contribution separately (A[Y[3],Y[1]] -= \omega^2\rho). Use an explicit subtraction so the documented motion matrix matches the code.

\dfrac{4}{r}\!\left( \dfrac{3\kappa\mu}{r\beta} - \rho_{0}g \right) { - \rho_0 \omega^2} &

docs/src/reference/solid-phase.md:189

• As in the preceding entry, { -\rho_0\omega^2} is placed directly after the elastic term, which documents multiplication rather than the separate inertial subtraction implemented in get_A! (A[Y[4],Y[2]] -= \omega^2\rho). Replace the braces with an explicit -.

\dfrac{2\mu}{r^{2}}\!\left[\ell(\ell+1)\!\left(1+\dfrac{\lambda}{\beta}\right)-1\right] { - \rho_0 \omega^2} &

docs/src/reference/solid/solid1d_mush.md:24

• The displayed differential equation uses d y/dr = A y - f, whose zero-width integration gives y^+ + f = y^-, but the next equation uses y^+ - f = y^- and the following line supplies a positive pressure source. These signs are inconsistent, so the interface derivation does not describe the stated convention; align the equation/source sign and the source vector.

$$\frac{d\pmb{y}_{n,m}(r)}{dr} = \pmb{A}_n (r) \pmb{y}_{n,m}(r) - \pmb{f}_{n,m}(r)$$

We impose continuity across an infinitesimally thin layer ($\Delta r = 0$) where $\pmb\Pi_n(r_{i}) = \pmb{1}$. We allow $\pmb{y}_{n,m}(r_i^+)$ to be an $8 \times 1$ vector and $\pmb{y}_{n,m}(r_i^-)$ to be $6 \times 1$. To preserve continuity while introducing pore pressure, we include a source term $\pmb{f}_{n,m}(r_i^+)$:

$$\begin{pmatrix} \pmb{1}_{(8\times8)} \end{pmatrix} \pmb{y}_{n,m}(r_i^+) - \pmb{f}_{n,m}(r_i^+) = \begin{pmatrix} \pmb{1}_{(8\times6)} \\ \pmb{0}_{(2\times6)} \end{pmatrix} \pmb{y}_{n,m}(r_i^-)$$

docs/src/reference/solid/solid1d_mush_relax.md:96

• These bullets say whole rows are zeroed, but the implementation only clears Cn[Y[7],Y[7]] and Dnp[Y[7],Y[7]]/Dnp[Y[8],Y[8]]; the other entries in those rows remain. Please describe the diagonal entries, or change the implementation if full-row removal is intended.

  the pore-pressure row of $\pmb C_n$ is zeroed, since the solid side has
  no pore pressure to enforce continuity on.
* **Mush $\to$ solid** (leaving a porous layer from below): both the
  pore-pressure and Darcy-flux rows of $\pmb D_{n+1}$ are zeroed, since
  the solid side above has neither degree of freedom.

docs/src/reference/tidal-potentials.md:47

• Capitalize These after the preceding sentence so the paragraph uses a complete sentence boundary.

In addition to the heating rates, `Obliqua` returns the complex tidal Love numbers $k_n(\sigma)$ and their corresponding forcing frequencies $\sigma$. these are required for calculating tidal torques and the long-term orbital evolution of the system.

src/Obliqua.jl:847

• This caps each segment's tidal/load Love numbers, but the returned knms_total is assembled afterward by summing those segments (and mush interpolation can add to a previously capped segment). A multi-segment body can therefore still return a global Love number above the configured bound, while enforce_ec only rescales each segment against its capped local value. Apply the cap and corresponding energy rescaling at the assembled global level, or explicitly document that cap_LN is only a per-segment limit.

                # Cap this mode's tidal/load Love number before the enforce_ec block
                if cap_LN
                    knms_T[iss, iseg] = cap_lovenumber(knms_T[iss, iseg], n_i)
                    knms_L[iss, iseg] = cap_lovenumber(knms_L[iss, iseg], n_i)

test/test_obliqua.jl:33

• These tests only exercise the clamp helper. No test invokes run_tides with spectrum = "legacy" or cap_LN = true, so the new mode construction, global cap behavior, and interaction with enforce_ec/mush interpolation remain unverified. Add a small integration case using the existing configuration-backed tidal test setup.

    @testset "cap_lovenumber" begin
        # n=2: fluid limit 3/(2*(2-1)) = 1.5, so re_max=4.5, im_max=3.0
        @testset "n=2 bounds" begin

• Files reviewed: 21/21 changed files
• Comments generated: 5
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.84%. Comparing base (570161b) to head (e5a6a22).

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #32      +/-   ##
==========================================
+ Coverage   82.62%   82.84%   +0.21%     
==========================================
  Files          14       14              
  Lines        3051     3077      +26     
==========================================
+ Hits         2521     2549      +28     
+ Misses        530      528       -2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[nichollsh]

Thanks for this @MarijnJ0. I've built the updated documentation and run the tests - both pass and display as expected/described.

I don't have any other suggestions for this PR and it looks good to me. The tutorials and description are really useful!

[nichollsh]

I've merged this PR so that we can move onto FormingWorlds/PROTEUS#859 with the correct Obliqua version pinned to PROTEUS.

[MarijnJ0]

Perfect, thanks Harrison!