API user guide
The purpose of this page is to present the main points to consider for developers who would like to use JEphem as an astro library in their programs.
The non astro part is not considered here. More details can be found in other pages of this trail.

Independance of the astro API

JEphem was developped to be used in two different ways :
  • as an autonom application (including the user interface and its different mechanims, like internationalization, preferences...) ;
  • as an astro library, includable in other programs.


  • The astro library consists of classes of jephem.astro.* packages. Classes of these package must remain independant from the rest of JEphem classes. Because of this exigence, higher level classes (like jephem.tools.Ephemeris), which use preferences or internationalization, had to be put in an other package.
    So to use JEphem only as a library, one should use only the package jephem.astro.

    Setting the files

    Including tig package

    Before using JEphem, one must include tig.jar in the classpath (cf download area). It contains generic classes, whose code has been separated from JEphem to be reusable.

    Only a few classes from tig package are used by astro classes :
  • All classes of package tig.maths
  • class tig.GeneralConstants
  • class Formats
  • Some test methods (which are commented but still present in JEphem's code) also use class tig.Strings.


  • Non-astro classes use amost all the calsses of tig library.

    Having the data files

    Some classes (VSOP87, ELP82) need data files to perform the computations.
    These files are located in JEphem directory/data/astro.
    Classes needing data have a static method setDataPath(), which must be called before using the class.

    Ordering a computation

    Before trying to use JEphem, you can have a quick look at the ephemeris trail, and in particular the pages class organization and Putting all together.

    Computing the coordinates for one date

    Build a jephem.astro.AstroContext and call its method calcBodyCoords().
    The coordinates can then be retrieved from the AstroContext's bodies.

    Here is code example to perform such a task :

    import jephem.astro.AstroContext;
    import jephem.astro.Body;
    import jephem.astro.SolarSystemConstants;
    import jephem.astro.SolarSystem;
    import jephem.astro.spacetime.SpaceConstants;
    import jephem.astro.spacetime.UnitConstants;
    
    public class testJEphem implements SolarSystemConstants, UnitConstants, SpaceConstants{
      
      public static void main(String[] args){
    
        // Build the AstroContext
        int[] bodyIndexes = {SUN, MOON, MERCURY, VENUS, MARS, JUPITER, SATURN, URANUS, NEPTUNE, PLUTO};
        double jd = 245897.52;
        AstroContext ac = new AstroContext(jd, bodyIndexes);
    
        // Prepare the variables
        int frame = GEOCENTRIC_ECLIPTIC;
        int sphereCart = SPHERICAL;
        double precision = 1.0;
        int[] units = {DISTANCE_UNIT_AU, ANGULAR_UNIT_DEG, ANGULAR_UNIT_DEG,
                       LINEAR_SPEED_UNIT_AU_PER_D, ANGULAR_SPEED_UNIT_DEG_PER_DAY, ANGULAR_SPEED_UNIT_DEG_PER_DAY};
        boolean velocities = true;
    
        // order the computation    
        ac.calcBodyCoord(frame, 
                         sphereCart, 
                         precision,
                         velocities,
                         units);
    
       // Display the coordinates
       Body[] bodies = ac.getBodies();
       Body curBody;
       int coordGroup = Space.getCoordGroup(frame, sphereCart);
       String[] coordLabels = Space.getCoordLabels(coordGroup);
       int[] units;
       for(int i = 0; i < bodies.length; i++){
         curBody = bodies[i];
         System.out.println(curBody.getName() + " : ");
         units = curBody.getPositionUnits();
         for(j = 0; j < 3; j++){
           System.out.println("  " + coordLabels[j] + " : " + curBody.getCoord(j) + "  " + Units.getUnitLabel(units[j]));
         }
         if(velocities){
           units = curBody.getVelocityUnits();
           for(int j = 0; j < 3; j++){
             System.out.println("  d(" + coordLabels[j] + ")/dt : " +  curBody.getCoord(j+3) + "  " + Units.getUnitLabel(units[j]));
            }
          }
        }// end for i
    
      }// end main()
      
    }// end class
    


    Result of the execution :

    to do
    
  • 'bodies' is an array of integers containing constants of SolarSystemConstants.java, representing bodies of the solar system. It indicates which bodies will be considered by the AstroContext.


  • Depending on 'precision' and its bodies, the AstroContext will call low-level classes to perform the computations.

    If precision can't be handled by the specified theories, a ComputationException is stored in the concerned Body.

    Computing the coordinates for several dates

    Use jephem.tools.Ephemeris.

    Exception handling

  • The classes from packages under jephem.astro throw only AstroExceptions and IllegalArgumentExceptions.
  • In the case of jephem.astro.solarsystem.ComputationExceptions, they are stored in the bodies, and can be used by client calsses.
  • These exceptions must be caught by client classes. In the case of JEphem GUI, they are sent to jephem.util.Debug.