Ephemeris trail
Introduction
Generalities
VSOP87
Build VSOP87
Truncating VSOP87
Testing VSOP87
Pluto99
ELP82
Class organization
Reference frames
CoordTransfo
Handling frames
Handling precision
Units
Handling time
Putting all together
Swiss Ephemeris
Units
To display ephemeris, the program gives coordinates of position or velocity vectors.
To express these coordinates, we need units.
So the program must identify units. This is done with constants of class jephem.astro.spacetime.UnitConstants. Related methods can be found in class jephem.astro.spacetime.Units

Units

The program handles linear distances and angular measures, and their derivates with respect to time.
Among all the possible units to express these quantities, here is what the first version of the program recognizes :
distance velocity
linear m
km
ua
m/s
km/h
km/d
au/d
angular arcsec
deg
rad
arcsec/s
arcsec/d
deg/s
deg/d
rad/d
Notations :
arcsec : arc second
deg : degree
h : hour
km : kilometer
m : meter
rad : radian
s : second (for time)
au : astronomical unit
This classification was used to name the constants of UnitsConstants. So constants to designate units are named :
  • DISTANCE_UNIT_XXX, (ex : DISTANCE_UNIT_KM)
  • LINEAR_SPEED_UNIT_XXX,
  • ANGULAR_UNIT_XXX and
  • ANGULAR_SPEED_UNIT_XXX.


  • Note : in a flexible program, it should be possible to specify velocity units with two characteristics
    - The distance unit
    - The time unit
    If this becomes useful, it could be implemented in future versions.

    Class UnitConstants also holds constants to designate unit type (units can be 'angular' units, 'distance' units etc..) :
  • TYPE_DISTANCE
  • TYPE_LINEAR_SPEED
  • TYPE_ANGULAR
  • TYPE_ANGULAR_SPEED


  • Several methods need an array of integers to express the units. This is for example the case of AstroContext.calcBodyCoords(). The notion of unit group was developped to conveniently express particular groups of commonly used units.
    Example : the code
    int[] units = new int[]{DISTANCE_UNIT_AU, DISTANCE_UNIT_AU, DISTANCE_UNIT_AU};
    can be replaced by :
    int[] units = UNITGROUP_AU_AU_AU;

    See Units' javadoc page for more details.

    Role of units in the API

  • Instances of class Body need to store the units used to express their coordinates. This is done with two arrays of 3 integers that can be accessed through Body's methods :
    - public int[] getPositionUnits()
    - public int[] getVelocityUnits()
    - public void setPositionUnits(int[] posUnits)
    - public void setVelocityUnits(int[] posUnits)
  • It is planetary theories' responsability to first fill the positionUnits and velocityUnits of bodies.
  • These units are eventually changed by methods that perform coordinate transformation (like sphereToCart() and cartToSphere() in class Body).
  • They are used by higer level class (like Ephemeris) which display the coordinates.
  • Units API

    Apart from holding constants, Units provides these methods :
  • public static double[] convertUnits(double[] coords, int[] units1, int[] units2), to convert coordinates between a set of units to an other.
  • public static String getUnitLabel(int unit), to get the english name of a unit.
  • public static String getUnitLabels(int unitType), to get the english names of all units of a certain type.


  • Note : Higher level classes, like jephem.astro.tools.Ephemeris don't use the two last methods, because they use labels stored in ressource files.
    I put labels here to permit the astro API to work independently from other classes (cf Keeping astro classes independent for details).

    Units is an abstract class. All its fields and methods are static.