Skip to content

fit_keplerian_orbit

Fit a single-companion Keplerian RV curve to a velocity time series.
Category Radial velocity
Backend scipy - implemented here on top of scipy primitives
Version 1.1.0
Reads -
Writes extras.keplerian_orbit, metrics.keplerian_period_days, metrics.keplerian_semi_amplitude_kms, metrics.keplerian_rms_kms, metrics.keplerian_reduced_chi_squared

The eccentricity is bound to [0, 0.95]; the argument of periastron ω to [−2π, 2π] (unwrapped, so the solver can cross 0/2π freely ; reduce omega_rad mod 2π downstream). Initial guesses are derived from the data when not supplied (period from the dominant Lomb-Scargle peak if astropy is available, otherwise the user must provide period_initial) ; an explicit 0.0 guess is honoured. The fit is UNWEIGHTED: chi_squared is the plain sum of squared residuals (km/s)², not a χ². When curve.uncertainty is set (finite, > 0) the additive reduced_chi_squared = Σ((v − model)/σ)² / (N − 6) is reported as a goodness-of-fit diagnostic ; the residuals are still not weighted by σ in the optimisation.

Parameters

Parameter Default Required Description
light_curve_key 'rv' - Key into ctx.light_curves for the RV time series.
period_initial None - Initial guess for the orbital period (days). Falls back to a Lomb-Scargle peak when null.
semi_amplitude_initial None - Initial guess for K (km/s). Default: half the peak-to-peak velocity range.
eccentricity_initial 0.1 - Initial guess for e (0..0.95).
omega_initial 0.0 - Initial guess for ω (radians).
t_peri_initial None - Initial guess for time of periastron (same unit as the time axis).
gamma_initial None - Initial systemic velocity guess (km/s). Default: median of the data.
max_nfev 5000 - Maximum function evaluations for the least-squares solver.

Use it

from spectro_kernel import run_algorithm

output = run_algorithm("fit_keplerian_orbit", ctx, {
    "light_curve_key": "rv",
    "period_initial": None,
    "semi_amplitude_initial": None,
    "eccentricity_initial": 0.1,
    "omega_initial": 0.0,
    "t_peri_initial": None,
    "gamma_initial": None,
    "max_nfev": 5000
})

spectro run fit_keplerian_orbit --input spectrum.fits \
  --param light_curve_key=rv \
  --param period_initial=none \
  --param semi_amplitude_initial=none \
  --param eccentricity_initial=0.1 \
  --param omega_initial=0.0 \
  --param t_peri_initial=none \
  --param gamma_initial=none \
  --param max_nfev=5000

{
  "tool": "fit_keplerian_orbit",
  "arguments": {
    "session_id": "<session_id>",
    "params": {
      "light_curve_key": "rv",
      "period_initial": null,
      "semi_amplitude_initial": null,
      "eccentricity_initial": 0.1,
      "omega_initial": 0.0,
      "t_peri_initial": null,
      "gamma_initial": null,
      "max_nfev": 5000
    }
  }
}

Every algorithm is an MCP tool of the same name; describe_algorithm returns this page's metadata as JSON.

References

  • scipy.optimize.least_squares (Trust Region Reflective).
  • Murray & Correia 2010 — Keplerian elements / RV formalism review.
  • cross_correlate_rv - Measure radial velocity by cross-correlation against a template spectrum.
  • measure_radial_velocity - Measure a radial velocity from the Doppler shift of a single line.
  • redshift_lines - Redshift z by per-line Gaussian fits against a list of rest-frame anchors.
  • rv_precision_bouchy - Compute the fundamental photon-noise limit on RV precision (Bouchy 2001).