kepler.hpp File Reference

The two-body problem, which is the only gravitational system anyone can solve exactly. More...

#include "orrery/core/particle_data.hpp"
#include "orrery/core/types.hpp"

Go to the source code of this file.

Classes
struct	orrery::initial_conditions::KeplerParameters
	A bound two-body orbit, described by its elements. More...

Functions
core::ParticleData	orrery::initial_conditions::make_kepler_orbit (const KeplerParameters &parameters)
	Two particles at periapsis, in the centre-of-mass frame at rest.
core::Real	orrery::initial_conditions::kepler_period (const KeplerParameters &parameters)
	The orbital period, from Kepler's third law.
core::Real	orrery::initial_conditions::kepler_energy (const KeplerParameters &parameters)
	The total energy, -G m1 m2 / 2a.
core::Real	orrery::initial_conditions::kepler_angular_momentum (const KeplerParameters &parameters)
	The magnitude of the total angular momentum, mu sqrt(G M a (1 - e^2)), where mu is the reduced mass and M the total.
core::Real	orrery::initial_conditions::kepler_periapsis_distance (const KeplerParameters &parameters)
	The separation at periapsis, a(1 - e), which is where the generated configuration starts.

Detailed Description

The two-body problem, which is the only gravitational system anyone can solve exactly.

Two point masses on a bound orbit trace ellipses about their common centre of mass, with a period, an energy and an angular momentum that follow from the orbital elements in closed form. That makes this configuration the project's primary validation instrument. A solver that gets the acceleration wrong, an integrator that loses energy, a tree approximation that opens too many cells: each shows up here as a departure from a number that is known rather than from an earlier run of the same code.

The configuration is placed at periapsis, where the velocity is exactly perpendicular to the separation. That is the one point on the orbit whose state can be written down without solving Kepler's equation, so the starting state carries no iterative error into a measurement that will later be quoted to the last bit.

The analytic quantities are exposed alongside the generator, and they are what the tests compare against. Deriving them inside the test instead would mean the test and the code under test could be wrong together.

Function Documentation

make_kepler_orbit()

core::ParticleData orrery::initial_conditions::make_kepler_orbit ( const KeplerParameters & parameters )

nodiscard

Two particles at periapsis, in the centre-of-mass frame at rest.

The heavier body is not distinguished from the lighter one: particle 0 carries primary_mass and particle 1 carries secondary_mass, whatever their sizes.

Throws std::invalid_argument if either mass is not positive, if the semi-major axis is not positive, or if the eccentricity is outside [0, 1). Initial conditions are a setup boundary, which is where the conventions in section 4 of the implementation plan permit exceptions, and a configuration that cannot be built should say so at the point of the mistake rather than hand back particles that quietly encode it.

kepler_period()

core::Real orrery::initial_conditions::kepler_period ( const KeplerParameters & parameters )

nodiscard

The orbital period, from Kepler's third law.

2 pi sqrt(a^3 / G(m1 + m2)). Independent of eccentricity, which is itself one of the results worth demonstrating.

kepler_energy()

core::Real orrery::initial_conditions::kepler_energy ( const KeplerParameters & parameters )

nodiscard

The total energy, -G m1 m2 / 2a.

Kinetic and potential together, in the centre-of-mass frame. It depends only on the semi-major axis, so measuring it is how a test recovers the semi-major axis from a state and checks the period that follows from it.

kepler_angular_momentum()

core::Real orrery::initial_conditions::kepler_angular_momentum ( const KeplerParameters & parameters )

nodiscard

The magnitude of the total angular momentum, mu sqrt(G M a (1 - e^2)), where mu is the reduced mass and M the total.

Unlike the energy this does depend on the eccentricity, so the two together determine the orbit and a test that checks both has checked the shape of the orbit and not only its size.