Add planetary data with full orbital elements and reference frame notes

docs/planetary_data.md

@@ -0,0 +1,63 @@
+# Planetary Data
+
+## Planets
+
+ ┌──────────┬────────────────┬──────────┬────────┬───────┬───────┬────────┬─────────┬──────────┬─────────┬────────┐
+ │ Body     │ Mass (kg)      │ Radius   │ a      │ e     │ inc   │ Ω      │ ω       │ Period   │ Day     │ M      │
+ │          │                │ (km)     │(AU)    │       │ (°)   │ (°)    │ (°)     │ (days)   │ (hours) │ (°)    │
+ ├──────────┼────────────────┼──────────┼────────┼───────┼───────┼────────┼─────────┼──────────┼─────────┼────────┤
+ │ Venus    │ 4.87×10²⁴      │ 6,052    │ 0.723  │ 0.007 │  3.39 │ 76.68  │  54.92  │ 224.7    │ 2,802.0 │  50.38 │
+ │ Earth    │ 5.97×10²⁴      │ 6,378    │ 1.000  │ 0.017 │  0.00 │  0.00  │ 102.94  │ 365.2    │  24.0   │  −2.47 │
+ │ Mars     │ 6.42×10²³      │ 3,396    │ 1.524  │ 0.093 │  1.85 │ 49.56  │ 286.50  │ 687.0    │  24.7   │  19.39 │
+ │ Jupiter  │ 1.898×10²⁷     │71,492    │ 5.203  │ 0.049 │  1.31 │100.47  │ 274.25  │ 4,331    │   9.9   │  19.67 │
+ │ Saturn   │ 5.68×10²⁶      │60,268    │ 9.537  │ 0.057 │  2.49 │113.66  │ 338.94  │10,747    │  10.7   │ −42.64 │
+ │ Uranus   │ 8.68×10²⁵      │25,559    │19.19   │ 0.046 │  0.77 │ 74.02  │  96.94  │30,589    │  17.2   │ 142.28 │
+ │ Neptune  │ 1.02×10²⁶      │24,764    │30.07   │ 0.010 │  1.77 │131.78  │ 273.18  │59,800    │  16.1   │ −100.08│
+ └──────────┴────────────────┴──────────┴────────┴───────┴───────┴────────┴─────────┴──────────┴─────────┴────────┘
+
+## Moons
+
+ ┌──────────────┬────────────────┬──────────┬──────────┬───────┬───────┬────────┬─────────┬─────────┬───────┐
+ │ Moon         │ Mass (kg)      │ Radius   │ a        │ e     │ inc   │ Ω      │ ω       │ Period  │ M     │
+ │              │                │ (km)     │ (km)     │       │ (°)   │ (°)    │ (°)     │ (days)  │ (°)   │
+ ├──────────────┼────────────────┼──────────┼──────────┼───────┼───────┼────────┼─────────┼─────────┼───────┤
+ │ Moon (Earth) │ 7.35×10²²      │ 1,738    │ 384,400  │ 0.055 │  5.16 │125.08  │ 318.15  │  27.322 │135.27 │
+ │ Io           │ 8.93×10²³      │ 1,822    │ 421,800  │ 0.004 │  0.00 │  0.0   │  49.1   │   1.763 │330.9  │
+ │ Europa       │ 4.80×10²³      │ 1,561    │ 671,100  │ 0.009 │  0.50 │184.0   │  45.0   │   3.525 │345.4  │
+ │ Ganymede     │ 1.48×10²⁴      │ 2,631    │1,070,400 │ 0.001 │  0.20 │ 58.5   │ 198.3   │   7.156 │324.8  │
+ │ Callisto     │ 1.08×10²⁴      │ 2,410    │1,882,700 │ 0.007 │  0.30 │309.1   │  43.8   │  16.690 │ 87.4  │
+ │ Titan        │ 1.35×10²⁴      │ 2,575    │1,221,900 │ 0.029 │  0.30 │ 78.6   │  78.3   │  15.945 │ 11.7  │
+ └──────────────┴────────────────┴──────────┴──────────┴───────┴───────┴────────┴─────────┴─────────┴───────┘
+
+## Reference Frames
+
+Source: https://ssd.jpl.nasa.gov/orbits.html
+
+- **Planets**: All orbital elements are referenced to the **mean ecliptic and equinox of J2000**.
+- **Moons**: The **source data** for moons is referenced to the **Laplace plane** (Jupiter and Saturn's moons) or the **ecliptic** (Earth's Moon). The Laplace plane is a hybrid reference plane between a planet's equator and its orbital plane around the Sun.
+- **Important**: Moon inclination and node values are **not** referenced to the same plane as the planets. Converting to a common frame is required before combining into a single simulation.
+
+### Moon Frame Transformation Plan
+
+Source data provides for each moon: **Tilt** (angle between planet's equator and Laplace plane), **R.A.** and **Dec.** (Laplace plane pole position in ICRF).
+
+Transformation approach using in-engine primitives:
+
+1. Build a rotation matrix from Laplace plane to equatorial plane using the Tilt angle and pole position (R.A., Dec.)
+2. Apply the rotation to the moon's position/velocity vectors via `Mat3 × Vec3`
+3. Reconstruct orbital elements from the rotated Cartesian state using `cartesian_to_orbital_elements()`
+
+This leverages the existing `mat3_rotation_x`, `mat3_rotation_z`, and `mat3_multiply` functions to compose the frame-rotation matrix, then uses the engine's built-in `cartesian_to_orbital_elements()` to extract the new (i, Ω, ω) values in the equatorial frame.
+
+## J2000 Starting Positions
+
+Source: Table 1 from https://ssd.jpl.nasa.gov/orbits.html (valid 1800–2050 AD, no perturbation terms needed).
+
+Mean anomaly at J2000: **M = L − ϖ**, where L is mean longitude and ϖ is longitude of perihelion.
+
+To get the true anomaly ν (which the TOML `orbit.true_anomaly` expects), solve Kepler's equation:
+
+    M = E − e·sin(E)   →   solve for eccentric anomaly E
+    tan(ν/2) = √((1+e)/(1−e)) · tan(E/2)
+
+Once ν is computed for each body, set it as `true_anomaly` in the config. The engine will then propagate from the J2000 snapshot forward.