spino.pipeline.phase_kepler module

Keplerian planetary radial velocity

Line-of-sight radial velocity of a transiting planet, in the stellar rest frame, valid for eccentric orbits.

The circular approximation K_p·sin(2π·φ) used elsewhere in the pipeline is exact only for e = 0. For an eccentric orbit both the amplitude and, more importantly, the shape of the curve change: around the transit the offset term e·cos ω_p and the modified slope dominate the error, which can reach tens of km/s for well-known cases (GJ 3470 b, GJ 436 b, HAT-P-11 b).

Angle convention, matching phase_scheduler.compute_transit_geometry: NEA pl_orblper is the argument of periastron of the planet, and Winn (2010, arXiv:1001.2010) uses ω_star = ω_p + 180°. The transit occurs at true anomaly ν_tr = π/2 − ω_star, which anchors the time of periastron to the transit ephemeris T0.

With that anchoring, planet_rv_kms reduces identically to K_p·sin(2π·φ) when e = 0, with the same sign as the rest of the pipeline (redshift just after transit).

spino.pipeline.phase_kepler.solve_kepler_E(M, ecc)

Solve Kepler’s equation M = E − e·sin E for the eccentric anomaly.

Newton-Raphson, vectorised over M. The starting guess is Danby’s E0 = M + 0.85·e·sign(sin M), which converges for every eccentricity below 1 without the stalling that a bare E0 = M shows near periastron at high e.

Parameters:

• M (array_like) – Mean anomaly [rad], any range.

• ecc (float) – Eccentricity, 0 <= e < 1.

Returns:

Eccentric anomaly [rad].

Return type:

ndarray

spino.pipeline.phase_kepler.time_of_periastron(t0_bjd, period, ecc, omega_p_deg)

Time of periastron passage [same units as t0_bjd], derived from the transit ephemeris.

The transit happens at ν_tr = π/2 − ω_star with ω_star = ω_p + 180°, so t_peri = T0 − P·M_tr/(2π).

spino.pipeline.phase_kepler.true_anomaly(t_bjd, t0_bjd, period, ecc, omega_p_deg)

True anomaly [rad] of the planet at times t_bjd, with the orbit anchored so that t = T0 is mid-transit.

spino.pipeline.phase_kepler.planet_rv_kms(t_bjd, t0_bjd, period, ecc, omega_p_deg, kp_kms)

Planetary radial velocity in the stellar rest frame [km/s].

V_p(t) = K_p · [cos(ν(t) + ω_p) + e·cos ω_p]

kp_kms must already carry the eccentricity correction (K_p / sqrt(1 − e²), see kp_eccentric). For e = 0 this returns K_p·sin(2π·φ) exactly.

spino.pipeline.phase_kepler.kp_eccentric(kp_kms, ecc)

Planetary semi-amplitude corrected for eccentricity, K_p / sqrt(1−e²).

Returns None when kp_kms is missing, and kp_kms unchanged for a circular orbit.

spino.pipeline.phase_kepler.omega_envelope(t_bjd, t0_bjd, period, ecc, kp_kms, n_omega=360)

Pointwise range of the planetary RV trace over all possible ω.

Used when the catalogue gives an eccentricity but no argument of periastron: rather than silently picking a value, the pipeline shows how wide the prediction can be.

Returns:

v_lo/v_hi are arrays shaped like t_bjd; omega_grid is the ω sampling in degrees.

Return type:

(v_lo, v_hi, omega_grid)

spino.pipeline.phase_kepler.orbit_solution(t_bjd, t0_bjd, period, ecc, omega_p_deg, kp_kms, n_omega=360)

Pick the orbital treatment for a target and evaluate every trace the plot needs.

Three branches:

circular

e missing or below ECC_MIN. Identical to the pipeline’s historical behaviour.

keplerian

e and ω both known. The adopted trace is the Keplerian one.

envelope

e known, ω missing. There is no preferred trace, so the adopted curve stays circular and the plot shows the band spanned by every possible ω around it. This is what makes the size of the unknown visible rather than hidden behind an arbitrary default.

Returns:

Keys mode, v_adopted, v_circ, v_lo, v_hi, ecc, omega_used, kp_circ, kp_ecc, max_dev_circ. None when K_p is unavailable, since nothing can be predicted then.

Return type:

dict | None

spino.pipeline.phase_kepler.describe_orbit_solution(sol)

One-line run-log summary of which orbital treatment was applied.

Return type:

str