Units

The units adopted throughout DME Component Libraries are the International System (SI) of units. Specifically, the subset of the SI base and derived units identified in the following table are used and should be assumed unless explicitly stated otherwise.

Many of the types in the class library do not impose any specific units of measure when using them. For example, the Cartesian coordinate type can be used to represent the components of position of an object in meters, feet, or astronomical units. It can also be used to represent the components of velocity or acceleration, in which case the units would be a ratio of a distance unit to a time unit raised to the appropriate power. For this reason, some of the types in the class library do not indicate any required units of measure when defining them or when accessing their information. Most of the types in the agi.foundation.coordinates package fall into this category.

// Use the DE440 as the source of the ratio of kilometers per astronomical unit (AU).
JplDE440 jpl = new JplDE440(new File(dataPath, "plneph.440").getPath());
double ratio = jpl.getKilometersPerAstronomicalUnit();
// Cartesian position in AU.
Cartesian positionInAstronomicalUnits = new Cartesian(1.0, 0.0, 0.0);
// Cartesian position in kilometers.
Cartesian positionInKilometers = Cartesian.multiply(ratio, positionInAstronomicalUnits);

Some types in the class library, when used in isolation, can operate in terms of an arbitrary set of units (metric, English, etc.). These types do, at a minimum, require that the information provided to them use a consistent set of units and will typically produce information which conforms to those units. Most of the types in the agi.foundation.numericalmethods package fall into this category. As an example, the TwoBodyPropagator class can be configured with the gravitational parameter of the principal gravitational body around which an orbiting body travels and a set of initial conditions consisting of the position and velocity of the orbiting body at an identified epoch. This class requires that the units used to express the gravitational parameter be consistent with the units used to express the position and velocity. Furthermore, when retrieving the motion of the orbiting body at some desired epoch, the position and velocity produced by the propagator will be in the units corresponding to those used in expressing the gravitational parameter and the initial conditions with which it was configured.

// Use the WGS84 values for the equatorial radius and gravitational parameter of the Earth (which are in SI units).
double R = WorldGeodeticSystem1984.SemimajorAxis; // meters
double mu = WorldGeodeticSystem1984.GravitationalParameter; // meters cubed per second squared

// Set up a 2-body propagator for a circular, equatorial orbit at 300 kilometers altitude.
double r = R + 300000.0; // meters
double v = Math.sqrt(mu / r); // meters per second

JulianDate epoch = TimeConstants.J2000;
ReferenceFrame frame = CentralBodiesFacet.getFromContext().getEarth().getInertialFrame();
Cartesian position = UnitCartesian.multiply(r, UnitCartesian.getUnitX());
Cartesian velocity = UnitCartesian.multiply(v, UnitCartesian.getUnitY());

Motion1<Cartesian> motion = new Motion1<>(position, velocity);

TwoBodyPropagator propagator = new TwoBodyPropagator(epoch, frame, motion, mu);

// Determine the position (which will be in meters) 1 hour later.
JulianDate oneHourLater = epoch.addSeconds(TimeConstants.SecondsPerHour);
Cartesian positionInMeters = propagator.getEvaluator().evaluate(oneHourLater);

// Now set up the same propagation in terms of Earth radii rather than meters.
mu = mu / (R * R * R); // Earth radii cubed per second squared;
position = Cartesian.divide(position, R); // Earth radii
velocity = Cartesian.divide(velocity, R); // Earth radii per second;

motion = new Motion1<>(position, velocity);

propagator = new TwoBodyPropagator(epoch, frame, motion, mu);

// Determine the position (which will be in Earth radii) 1 hour later.
Cartesian positionInEarthRadii = propagator.getEvaluator().evaluate(oneHourLater);