Orbital Mechanics Angles in Julia

Orbital Mechanics Angles in Julia

I am getting into orbital dynamics. Julia is a language that more people are picking up, and I like how its syntax reads close to the equations. So I decided to port a Python orbital dynamics library to Julia. Over the next weeks I will explain what each function does, how it works, and write the port. This post starts with the angles, because they are the easiest way in.

By the end you will know the six angles that describe an orbit, what each one measures, and how three of them turn a position in the orbit’s own plane into a position in space. I include working Julia for each step and checks you can run by hand.

Six angles, two jobs

Six numbers fix the shape and orientation of an orbit and the position of a body on it. They split into two jobs.

Three angles place the body along its orbit. They are the mean anomaly M, the eccentric anomaly E and the true anomaly f. Each is an angle measured from the point of closest approach, called periapsis, and each answers the same question with a different geometry.

Three angles tilt the orbit in space. They are the inclination i, the right ascension of the ascending node Ω (often called RAAN) and the argument of periapsis ω. Together with the semi-major axis a and the eccentricity e, they fix the orbit completely.

Three anomalies for one position

The mean anomaly M grows steadily with time. It is the angle a body would have if it moved around a circle at constant speed with the same period. It is M = n(t − tp), where n is the mean motion, tp is the time of periapsis and t is the time you ask about. The mean motion is the square root of μ divided by a cubed, where μ is the gravitational parameter of the central body.

The eccentric anomaly E comes from drawing a circle around the orbit’s ellipse and projecting the body onto it. Kepler’s equation links the two: M = E − e sin E. You can compute M from the time directly, but you have to solve that equation numerically to get E. That is a separate piece of work, and I cover it in Orbital Mechanics in Julia: Solving Kepler’s Equation.

The true anomaly f is the angle you would measure at the central body, from periapsis to the body. It is the one that gives position. The relation from E to f is:

tan(f/2) = sqrt((1 + e) / (1 − e)) · tan(E/2)

In Julia, I write it with atan2 so the result stays well behaved near E = π:

true_anomaly(E, e) = 2atan(sqrt(1 + e) * sin(E / 2), sqrt(1 - e) * cos(E / 2))

Julia’s two-argument atan takes the sine-like term first and the cosine-like term second, so the quadrant comes out right without a branch.

Checks you can do by hand

A function you cannot check is a guess. These three hold by algebra, and they are the tests I run first. They are expected values, not captured output.

At E = 0 the body is at periapsis, so true_anomaly(0, e) should be 0 for any e. At E = π it is at apoapsis, so true_anomaly(π, e) should be π. With e = 0 the orbit is a circle, so f should equal E exactly. Floating point can leave a difference near 1e-16 at E = π, because sin(π/2) is exactly 1 but cos(π/2) is about 6e-17. That is the size of error to expect, so compare with a tolerance and not with ==.

From the orbit plane to space

The true anomaly and the distance r give a position in the orbit’s own plane, called the perifocal frame. Its x axis points to periapsis and its z axis is perpendicular to the plane. The distance is:

r = a(1 − e²) / (1 + e cos f)

and the position in that frame is (r cos f, r sin f, 0).

To move that vector into the inertial frame, apply three rotations. Rotate by ω about z, which turns periapsis to its place in the orbit plane. Rotate by i about x, which tilts the plane. Rotate by Ω about z, which turns the line of nodes to its place in space. In Julia:

rot3(θ) = [cos(θ) -sin(θ) 0; sin(θ) cos(θ) 0; 0 0 1]
rot1(θ) = [1 0 0; 0 cos(θ) -sin(θ); 0 sin(θ) cos(θ)]

function perifocal_position(a, e, f)
    r = a * (1 - e^2) / (1 + e * cos(f))
    [r * cos(f), r * sin(f), 0.0]
end

inertial_position(a, e, f, Ω, i, ω) =
    rot3(Ω) * rot1(i) * rot3(ω) * perifocal_position(a, e, f)

The order matters. The matrices are applied right to left, so ω goes first and Ω goes last. Swapping them gives a different orbit that looks plausible, which is the worst kind of bug.

Two checks for the rotations

Take a circular orbit with a = 1, e = 0 and f = 0, so the body sits at (1, 0, 0) in the perifocal frame. With i = 0 and Ω = 0, set ω = 90°. Expected value: the inertial position is (0, 1, 0), up to rounding near 6e-17 in the first component. The argument of periapsis turned the whole orbit a quarter turn about z.

Now take the same circle with f = 90° so the body sits at (0, 1, 0) in the perifocal frame. Set Ω = 0, ω = 0 and i = 90°. Expected value: the inertial position is (0, 0, 1), up to rounding. A polar orbit puts a body at the position 90° around its orbit directly above the reference plane.

Both results are analytic and I have not captured a run of either. Run them against your own port and treat a mismatch as a bug in the rotation order or the sign convention.

Angles in degrees and radians

The textbooks mix both. Julia’s trigonometric functions take radians, and deg2rad and rad2deg convert. I keep all internal state in radians and convert at the edges, when I read an element set or print a result. Mixing the units inside a function is the second most common bug I expect in an orbit port. The first is the rotation order above.

Where the angles come from

The Kepler angles are explained on the Kepler’s equation page, and the other angles used in the Julia code are explained in Session 3: Satellite Orbits. For a textbook treatment, read the orbit chapters of Curtis, Orbital Mechanics for Engineering Students, and Vallado, Fundamentals of Astrodynamics and Applications.

What comes next

The next post solves Kepler’s equation properly, with a Newton iteration that converges for high eccentricities. After that I will start on the functions that convert between an orbit’s elements and a position and velocity vector, since the code above already holds half of that.

Subscribe to Just another Geek

Don’t miss out on the latest issues. Sign up now to get access to the library of members-only issues.
jamie@example.com
Subscribe