In order for the various models and algorithms in the class library to function properly when used together, it is necessary to adopt some fundamental set of units of measure that can be used for exchanging information between the different APIs.
The units adopted throughout STK Components 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.
Unit of Measure
SI Unit Type
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 DE405 as the source of the ratio of kilometers per astronomicial unit (AU). JplDE405 jpl = new JplDE405(new File(dataPath, "plneph.405").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);