Module relative 

Root-level shortcut for satellite-relative frames and CW propagation.

use sidereon::astro::state::CartesianState;
use sidereon::relative;

let chief = CartesianState::new(0.0, [7000.0, 0.0, 0.0], [0.0, 7.546049108166282, 0.0]);
let deputy = CartesianState::new(
    0.0,
    [7001.0, 0.2, 0.1],
    [0.001, 7.546549108166282, 0.0002],
);

let rel = relative::relative_state(&chief, &deputy).unwrap();
let rebuilt = relative::absolute_from_relative(&chief, &rel).unwrap();

assert!((rebuilt.position_km - deputy.position_km).norm() < 1.0e-9);
assert!((rebuilt.velocity_km_s - deputy.velocity_km_s).norm() < 1.0e-12);

Satellite-relative RSW, RTN, RIC, LVLH frames and Clohessy-Wiltshire motion.

The RSW, RTN, RIC, and LVLH names all use the same right-handed chief triad in this module. The first axis is radial and points outward from the central body. The third axis is the positive orbit normal, along r x v. The second axis is W x R, the transverse in-plane direction. For an eccentric orbit this transverse axis is not exactly the velocity direction.

LVLH is pinned to the same axes: x radial outward, y transverse in-plane, and z positive orbit normal. This is the frame used by the Clohessy-Wiltshire state-transition matrix below. The nadir-pointing LVLH convention with z = -R, x = S, and y = -W is not used here.

Relative states are carried in CartesianState. For relative-returning APIs, position_km is the deputy position relative to the chief expressed in the rotating chief frame, and velocity_km_s is the relative velocity seen by that rotating frame. The epoch is copied as documented on each function.

The rotating-frame rate used by the state transforms is the osculating two-body RSW rate [0, 0, |r x v| / |r|^2]. This is exact for unperturbed Keplerian motion and is consistent with the inverse transform and the Clohessy-Wiltshire model. Perturbed chiefs can have additional basis-vector rate terms that are outside this API.

The Clohessy-Wiltshire equations linearize relative motion about a circular chief orbit. They are appropriate for short arcs and separations small relative to the chief orbit radius. Error grows for eccentric chiefs, hundreds-of-kilometers separations in LEO, and long arcs where J2, drag, solar radiation pressure, or third-body effects dominate. Eccentric-chief models such as Tschauner-Hempel or Yamanaka-Ankersen are future work.

References: W. H. Clohessy and R. S. Wiltshire, “Terminal Guidance System for Satellite Rendezvous,” Journal of the Aerospace Sciences, 27(9), pp. 653-658, 1960, DOI 10.2514/8.8704. G. W. Hill, “Researches in the Lunar Theory,” American Journal of Mathematics, 1(1), pp. 5-26, 1878, DOI 10.2307/2369430. D. A. Vallado, “Fundamentals of Astrodynamics and Applications,” 4th ed., 2013, Section 6.7 “Clohessy-Wiltshire”.

Functions

absolute_from_relative

Convert a chief-relative state in the chief frame back to absolute ECI.

cw_propagate

Propagate a relative state with the Clohessy-Wiltshire equations.

cw_stm

Build the Clohessy-Wiltshire state-transition matrix.

lvlh_to_inertial_rotation

Return the chief LVLH-to-inertial rotation.

mean_motion_circular

Mean motion for a circular Earth orbit of radius_km.

mean_motion_from_state

Mean motion from the semi-major axis of an osculating Earth orbit.

relative_state

Express an absolute deputy state relative to a chief in the chief frame.

ric_to_inertial_rotation

Return the chief RIC-to-inertial rotation.

rsw_to_inertial_rotation

Return the chief RSW-to-inertial rotation.

rtn_to_inertial_rotation

Return the chief RTN-to-inertial rotation.