wrapper.py Validation¶

What this page checks¶

This page checks 2 steps of the star wrapper, src/proteus/star/wrapper.py: the equilibrium temperature of the planet and the orbital distance that sets the stellar flux at the planet. Validation means that a test runs the code on a case with a known right answer and checks the result within a stated tolerance. If this part of the code is wrong, every run gets the wrong stellar flux at the planet or the wrong equilibrium temperature. Each case below says why the check exists, what it tests, how we know the right answer and why it matters. A box "Test details" ends each case.

Reference-pinned tests¶

Equilibrium temperature of an Earth-like planet¶

Why this check exists. The equilibrium temperature is the fourth root of an energy balance. A wrong root, for example a cube root or a fifth root, gives a wrong temperature without an error message.

What it tests. update_equilibrium_temperature computes \(T_\mathrm{eqm} = ((1 - A)\, S\, f / \sigma)^{1/4}\), with \(S\) the stellar flux at the planet, \(A\) the albedo of the planet, \(f\) the factor s0_factor and \(\sigma\) the Stefan-Boltzmann constant. At \(S\) = 1361 W/m\(^2\), \(A\) = 0.3 and \(f\) = 0.25, the area ratio of the disk that catches the starlight, \(\pi R^2\), to the sphere that emits, \(4 \pi R^2\), the test expects about 254 K. A cube root would give about 1613 K and a fifth root about 84 K; the test checks that the result is more than 50 K away from both.

How we know the right answer. The value follows from the Stefan-Boltzmann law for a planet in radiative balance. The test checks the closed form to relative 1e-12, with \(\sigma\) from the code, and the value 254 K to within 2 K, which catches a \(\sigma\) about 2.2 % too small or 4.2 % too large.

Why it matters. update_stellar_quantities calls it in the stellar step of the main loop and writes T_eqm to the helpfile, the table runtime_helpfile.csv with one row of model quantities per time step.

How to read the plot. The x-axis is the stellar flux at the planet and the y-axis the equilibrium temperature on a log scale. The planet has an albedo of 0.3 and the disk-averaging factor s0_factor = 0.25. The line is update_equilibrium_temperature, and the squares are the closed form with the 1/4 power (context). The dashed and dotted lines are the cube-root and fifth-root forms that the test rejects. The filled circle is the asserted code value at 1361 W/m\(^2\), and the hollow diamond the 254 K pin; the test allows 2 K. A pass means that the circle sits on the line and in the diamond, far from the 2 rejected forms.

Orbit-averaged distance for the stellar flux¶

Why this check exists. On an eccentric orbit the distance to the star changes, and the stellar flux goes as \(1/r^2\). An average of the wrong quantity, such as the mean distance, gives a wrong flux without an error message.

What it tests. flux_weighted_distance returns the distance that gives the orbit-averaged flux. Averaging \(1/r^2\) over one orbit gives \(1 / (a^2 \sqrt{1 - e^2})\), with \(a\) the semi-major axis and \(e\) the eccentricity. So the distance with that flux is \(a (1 - e^2)^{1/4}\), which is \(0.774597\, a\) at \(e = 0.8\). The test also checks that the result is positive and shorter than \(a\).

How we know the right answer. The orbit average of the inverse-square law is an analytical result. The time-averaged separation \(a (1 + e^2 / 2)\), which hf_row['separation'] holds, gives \(1.32\, a\) at \(e = 0.8\) instead. The 2 distances give fluxes that differ by a factor of 2.904, which the test checks.

Why it matters. update_instellation uses this distance for the bolometric flux, and, with the stellar tracks of Spada et al. (2013) in MORS, for the XUV (X-ray and extreme-ultraviolet) flux too. The source docstring notes that the time-averaged separation remains the right quantity for the orbit plots and the Roche-limit checks, so both distances are in use. The Roche limit is the distance inside which the tides of one body pull apart a second body held together only by its own gravity.

How to read the plot. The x-axis is the eccentricity \(e\) and the y-axis the distance over the semi-major axis. The line is flux_weighted_distance, and the squares are \((1 - e^2)^{1/4}\) (context). The dashed line is the time-averaged separation \(1 + e^2/2\), which the test rejects. The filled circle is the asserted code value at \(e\) = 0.8, 0.774597. A pass means that the circle sits on the line, below 1 and far from the dashed line.

Last verified¶

2026-09-29