Editing SimTX API/Satellites (section)

== Orbit model ==
Every satellite uses the model <code>simtx-j2-v1</code>: mean Keplerian elements with the secular rates caused by the Earth's oblateness (J2), and nothing else. There are no short-period terms, no drag and no decay; a satellite stays in its orbit until its owner deorbits it.

=== Elements and constants ===
The [[SimTX API/Data types#OrbitalElements|OrbitalElements]] are the mean semi-major axis ''a'', eccentricity ''e'', inclination ''i'', right ascension of the ascending node Ω, argument of perigee ω and mean anomaly ''M''<sub>0</sub>, all at the epoch.

<syntaxhighlight lang="text">
μ    = 398600.4418 km³/s²       gravitational parameter
J2   = 1.08262668e-3
R_J2 = 6378.137 km               reference radius for J2
R    = 6371.0 km                 sphere for heights, latitude, longitude and look angles
</syntaxhighlight>

=== Secular rates ===
<syntaxhighlight lang="text">
n0 = √(μ / a³)          p = a (1 − e²)          η = √(1 − e²)          k = 1.5 J2 (R_J2 / p)²

dΩ/dt = −k n0 cos i
dω/dt =  ½ k n0 (5 cos² i − 1)
dM/dt =  n0 (1 + ½ k η (3 cos² i − 1))          period = 2π / (dM/dt)
</syntaxhighlight>

The three angles grow linearly with Δt = t − epoch.

=== Position and velocity ===
# Solve Kepler's equation ''M'' = ''E'' − ''e'' sin ''E'' by Newton's method, starting from ''E''<sub>0</sub> = ''M'' + ''e'' sin ''M'' (or π when ''e'' > 0.8), to |Δ''E''| < 10<sup>−14</sup> in at most 16 iterations.
# The perifocal position is ''r'' = (''a'' (cos ''E'' − ''e''), ''a'' η sin ''E'', 0).
# Rotate it by R3(Ω) R1(''i'') R3(ω) into the model's inertial frame. The model has no precession or nutation.
# The velocity is the derivative of the perifocal position with d''E''/dt = (d''M''/dt) / (1 − ''e'' cos ''E''), rotated the same way, plus (dΩ/dt) ẑ × ''r'' plus (dω/dt) ĥ × ''r'', where ĥ is the orbit normal.

=== Earth-fixed coordinates ===
The inertial frame is turned into Earth-fixed (ECEF) coordinates by the Earth Rotation Angle, using UTC as UT1:

<syntaxhighlight lang="text">
θ    = 2π (frac(Du) + 0.7790572732640 + 0.00273781191135448 Du),    Du = JD(UTC) − 2451545.0
r_ecef = R3(θ) r
v_ecef = R3(θ) v − ω_E × r_ecef,                                      ω_E = 2π × 1.00273781191135448 / 86400 rad/s
</syntaxhighlight>

Latitude, longitude and height are taken on the 6,371 km sphere, which is also the frame of [[SimTX API/Packets/EphemerisResponse|EphemerisSample]] <code>x</code>, <code>y</code> and <code>z</code>.

=== Look angles and Doppler ===
Look angles are computed in the observer's topocentric east-north-up frame on the sphere: azimuth from north through east, and '''geometric''' elevation (refraction is left to the propagation model). The range rate is positive when the satellite recedes, and the Doppler shift is −''f'' × (range rate) / ''c''.

=== Attitude ===
The [[SimTX API/Data types#Attitude|Attitude]] decides where a satellite's antennas point. It is defined against the orbiting (LVLH) frame built from the inertial position ''r'' and velocity ''v'':
* z<sub>L</sub> = −r̂ (nadir), y<sub>L</sub> = −ĥ (ĥ = ''r'' × ''v'' normalised), x<sub>L</sub> = y<sub>L</sub> × z<sub>L</sub> (along-track; the velocity direction on circular orbits).

{| class="wikitable"
! Mode !! Body axes
|-
| <code>nadir</code> (yaw) || The LVLH frame rotated by the yaw angle about z<sub>b</sub>. No mode set means nadir with yaw 0.
|-
| <code>inertial</code> (α, δ, roll) || z<sub>b</sub> = (cos δ cos α, cos δ sin α, sin δ) in the inertial frame. At roll 0, x<sub>b</sub> = (−sin α, cos α, 0), towards increasing right ascension, and y<sub>b</sub> = z<sub>b</sub> × x<sub>b</sub>, towards the celestial north pole. Roll rotates about z<sub>b</sub>.
|-
| <code>spin</code> (axis, rpm, φ<sub>0</sub>) || z<sub>b</sub> along the named axis: <code>ORBIT_NORMAL</code> z = +ĥ, x = along-track, y = nadir; <code>NADIR</code> z = −r̂, x = along-track, y = −ĥ; <code>VELOCITY</code> z = along-track, x = nadir, y = +ĥ. The body then turns about z<sub>b</sub> by φ = φ<sub>0</sub> + 2π (rpm / 60) Δt, relative to the orbiting frame.
|}

A rotation by ψ about z<sub>b</sub> maps x to cos ψ x + sin ψ y and y to −sin ψ x + cos ψ y. Every axis is finally rotated into Earth-fixed coordinates by R3(θ). Antenna boresight is the body +z axis for <code>HELIX</code>, <code>TURNSTILE</code>, <code>MONOPOLE</code> and NEC decks; Yagi booms (+y in the template) are mapped to +z.

=== Validation ===
The account service accepts an orbit only when:
* the model is <code>simtx-j2-v1</code>;
* the perigee ''a'' (1 − ''e'') − ''R'' is at least 200 km and the apogee ''a'' (1 + ''e'') − ''R'' at most 40,000 km above the 6,371 km sphere, which limits ''e'' to about 0.752;
* 0 ≤ ''e'' < 1, 0 ≤ ''i'' ≤ 180°, all angles finite;
* a spin rate, if any, is 0 to 60 rpm.

=== Accuracy ===
An implementation that agrees with the server to 1 cm in position, 10<sup>−5</sup> m/s in velocity and 0.01 Hz in Doppler at 437.8 MHz, over intervals of up to ten years, draws satellites where the server simulates them.