Introducing the ephcom2 Software Project

The ephcom2 software empowers users to manipulate and interpolate JPL ephemerides in a convenient way. These ephemerides represent mankind's best knowledge of the positions and velocities of all major bodies of the solar system over epoch ranges of centuries (short ephemerides) and millennia (long ephemerides).

The ephcom2 software project is a major revival of the ephcom1 software which was last released under the LGPL by Paul Hardy in May 2004 at the ephemeris.com website. The ephcom2 software includes an important uninitialized variable bug fix that substantially increases the reliability and numerical precision of its results compared to ephcom1. Extensive comparisons of ephcom2 test results with similar results from the JPL Fortran code (distributed at ftp://ssd.jpl.nasa.gov/pub/eph/planets/fortran/) show ephcom2 has the same reliability and numerical precision as the JPL Fortran code. The ephcom2 software has a CMake-based build and test system; is cross-platform in nature (i.e., it builds and gives good test results on both Linux and Windows, and probably will do the same on Mac OS X although that has not been tested yet); has both a C and Fortran API; is licensed under the LGPL; and is a subproject of the Time Ephemerides Project. All bugs for ephcom2 should be reported to Alan W. Irwin.

What is Configured by the ephcom2 Build System

The purpose of the CMake-based ephcom2 build system is to configure certain targets (tasks) and the dependencies between those targets for a subsequent "make" step to run. The ephcom2 build system configures the build and install of the gnulliver and ephcom libraries, the ephcom applications, the Fortran 77 bindings of the ephcom library, and the binary form of the JPL ephemerides. The ephcom2 build system also configures both external and internal tests of those builds and installs. The gnulliver library does all the necessary byte swapping so binary ephemeris results are stored in big-endian order regardless of platform. The ephcom library reads and writes ascii and binary ephemerides and interpolates binary ephemeris results. The ephcom applications (ephcom_asc2eph, ephcom_concatenate.sh, ephcom_eph2asc, ephcom_eph2eph, ephcom_ephcmp, ephcom_ephcoeff, ephcom_headcmp, ephcom_testeph, and ephcom_vtransit) are convenient utilities for manipulating and testing ephemerides. The Fortran 77 bindings for the ephcom library include the traditional Fortran routines const, pleph, and dpleph to allow the user to switch seamlessly from the JPL Fortran code to ephcom2. The Fortran bindings also include the improved Fortran routines const1, pleph1, and dpleph1 which allow the users to use an arbitrary filename for the binary ephemeris (as opposed to the fixed "JPLEPH" filename used by const, pleph, and dpleph of these bindings and also by the JPL Fortran subroutines of the same name). The improved versions of the Fortran routines also include a returned status code in the argument list.

Users of ephcom2 have a wide choice of which JPL ascii ephemerides to use as a source of data for generation and testing of binary ephemerides by the build system. The JPL ascii data are available in subdirectories named de* (e.g., de423) which must be downloaded separately in either compressed or uncompressed form. The user specifies the directory that contains the downloaded de* subdirectories when the cmake command is run.

After the cmake command is run, running the "make help" command lists all configured targets by name. The most important of those target names are documented here. The "jpl_binary_${de_dir}" target, where ${de_dir} denotes the short name (e.g., de423) for each located de* subdirectory, builds the appropriate binary ephemeris using ephcom_concatenate.sh to concatenate the required (compressed or uncompressed) ascii files to form a complete JPL ascii ephemeris on the fly which ephcom_asc2eph transforms into binary form. The default (or "all") target builds all the software and depends on all the different "jpl_binary_${de_dir}" targets. The "install" target depends on "all" and installs all the software and the binary ephemerides that have been built by "all". The "test_external_${de_dir)" target depends on "jpl_binary_${de_dir}" and compares (using ephcom_testeph) interpolated results determined from the binary ephemeris created by that target with results stored in the testpo.* test file that is externally supplied by JPL. The test_internal_${de_dir) target depends on "jpl_binary_${de_dir}" and transforms the binary ephemeris created by that target to ascii form (using ephcom_eph2asc) and then back to binary form again (using ephcom_asc2eph) to check for consistency in the results (using ephcom_headcmp and ephcom_ephcmp). Additional notable configured targets are "test_external" which depends on the individual "test_external_${de_dir}" targets, "test_internal" which depends on the individual "test_internal_${de_dir}" targets, and "test_everything" which depends on both the "test_external" and "test_internal" targets.

Building and Testing ephcom2

Here are the steps for a complete build, test, and install of ephcom2. All steps should be done for every platform unless a step is identified as being applicable to just a specific platform.

(1) Install CMake-2.8.5 by building and installing from a source distribution or installing from a binary distribution. That version of CMake is the minimum version of CMake that is acceptable for the ephcom2 build system.

(1a) For Microsoft Windows or Wine platforms install MinGW/MSYS using the automatic installer.

(2) Download one or more of the JPL ascii ephemerides (including header.*, testpo.*, and asc[mp]*.* files collected in a separate de* directory for each JPL ephemeris) from http://sourceforge.net/projects/timeephem/files/Compressed Ascii JPL Ephemerides/ or ftp://ssd.jpl.nasa.gov/pub/eph/planets/ascii.

(3) Download the ephcom2 software.

(4a) On Linux (and probably on Mac OS X) build and test that software using the following commands:

	  mkdir build_dir
          cd build_dir
	  cmake \
	  -DCMAKE_INSTALL_PREFIX=/path/to/ephcom2/install/prefix/directory \
	  -DJPL_ASCII_DIR:PATH=/path/to/parent/directory/of/de*/subdirectories \
	  /path/to/head/of/ephcom2/source/tree >& cmake.out 
          make VERBOSE=1 -j8 test_everything >& test_everything.out
	

Notes: I recommend the -j8 option above for parallel build efficiency. This allows your computer to be efficient for the large variety of i/o-dominated and cpu-dominated tasks generated by the test_everything target. If you download just the shortest JPL ascii ephemeris (de423), the test_everything target should take about a minute to complete and should only consume ~350MB. However, if you download a wide variety of JPL ascii ephemerides, then the test_everything target will take about an hour to complete and will consume something like 20GB. These estimates of resources consumed by the tests drop substantially (typically by a factor of 5) if you replace the test_everything target with the test_external target. However, the text_external target is not as thorough as the test_everything target.

(4b) On MinGW/MSYS/Microsoft Windows or MinGW/MSYS/Wine platforms do all the commands mentioned in (4a) using MSYS bash but with the following modifications: (i) Put the absolute pathname of build_dir/dll on your PATH before running the cmake step. (ii) Add the -G "MSYS Makefiles" option to the cmake command.

(5) Check that all went well with those series of tests:

          find . -name '*.out' |xargs grep -i warn
          find . -name '*.out' |xargs grep -i err
          find . -name '*.out' |xargs grep -i diff |grep -v 'jpl value'
        

The only warnings that are acceptable are warnings about minor inconsistencies in the JPL ascii ephemerides that have been corrected before the result was converted to binary form. No error messages are acceptable. The last of the commands above will find lots of differences, but they should be zero for the identity_*cmp.out files which compare the first generated binary ephemeris and the second one produced by the transform of that first one to ascii and back to binary. Non-zero but small differences are to be expected for cross_*cmp.out files which compare different historically released versions of the same JPL ascii ephemeris that have been rounded in slightly different ways.

(6) Install the ephcom2 software and the JPL binary ephemerides that are created as a dependency of that install using the following command:

	  make -j8 install >& make_install.out
	

(7a) On Linux (and probably on Mac OS X) test that installation with the CMake-based test system for the installed version of ephcom2:

          mkdir install_build_dir
          cd install_build_dir
          cmake /path/to/ephcom2/install/prefix/directory/share/ephcom \
          >& cmake.out
          make -j8 test_everything >& test_everything.out
	

(7b) On MinGW/MSYS/Microsoft Windows or MinGW/MSYS/Wine platforms do all the commands mentioned in (7a) using MSYS bash but with the following modifications: (i) Replace the absolute pathname of build_dir/dll on your PATH that you used for step (4b) with /path/to/ephcom2/install/prefix/directory/bin before running the cmake step. (ii) Add the -G "MSYS Makefiles" option to the cmake command.

(8) Check that all went well with those series of tests for the installed version of ephcom2:

          find . -name '*.out' |xargs grep -i warn
          find . -name '*.out' |xargs grep -i err
          find . -name '*.out' |xargs grep -i diff |grep -v 'jpl value'
        

Status of Platform Testing for ephcom2

Linux

I built and tested the ephcom2 software with the above procedure on my Debian Squeeze Linux system. No issues were found. This system was the primary platform used for development of ephcom2. More testing of ephcom2 on additional Linux platforms is requested.

Mac OS X

Although ephcom2 should work on this (and other) Unix platforms, testing is requested for this platform.

MinGW/MSYS/Wine

I built and tested the ephcom2 software using the above procedure for the latest MinGW/MSYS (i.e., the version that is obtained with the mingw-get-inst-20110802 automatic installer and which corresponds to gcc version 4.5.2) and patched version of wine-1.3.26. No issues were found. The patch for wine-1.3.26 is located here and improves the internal numerical precision of the scanf family of routines from roughly 7 (!) decimal digits (32-bit floating point) to the 19-digit (80-bit floating-point) numerical precision of the corresponding printf family of routines. This patch is absolutely essential because ephcom2 relies on numerically precise double precision (64-bit floating point) i/o which is impossible with unpatched Wine. This system was the primary platform used for testing ephcom2 on Windows systems. Note that version 1.3.27 of Wine is to be avoided because of a showstopper bug that makes it incompatible with packages (such as CMake) which include their own versions of standard Windows libraries. That bug should be fixed for the forthcoming 1.3.28 release, but I currently cannot recommend any release of Wine later than 1.3.26 until the above patch to (greatly) improve the numerical precision of the scanf family of routines is incorporated into Wine releases.

MinGW/MSYS/Microsoft Windows

Arjen Markus kindly supplemented my comprehensive MinGW/MSYS/Wine platform testing on his Microsoft platform (Windows XP, SP3) using a version of MinGW/MSYS installed in early 2010 which corresponds to a gcc version of 4.5.0. This testing consisted of the above build-tree tests for just DE423. MinGW/MSYS testing of ephcom2 on additional Microsoft Windows platforms is requested.

Using the Installed Version of ephcom2

The ephcom2 install step installs the ephcom2 C libraries, C applications, Fortran interface libraries, and the binary form of all ephemerides created by the build system. Thus, ephcom2 installation gives you everything you need to access mankind's best knowledge of the positions and velocities of all major bodies of the solar system over epoch ranges of centuries (short ephemerides) and millennia (long ephemerides) from C or Fortran.

C users of the installed ephcom2 software package can build and link their own applications as follows:

          INSTALL_DIR=/path/to/ephcom2/install/prefix/directory
          gcc -I$INSTALL_DIR/include/ephcom -Wl,-rpath -Wl,$INSTALL_DIR/lib \
          -L$INSTALL_DIR/lib -lephcom -lgnulliver -lm \
           application.c -o application
	

using the ephcom2 C API.

For example, this method works to build and link the ephcom1 applications (although the equivalent ephcom2 applications are preferred since they have some bug fixes applied).

Fortran users of the installed ephcom2 software package can build and link their own applications as follows:

          INSTALL_DIR=/path/to/ephcom2/install/prefix/directory
          gfortran -Wl,-rpath -Wl,$INSTALL_DIR/lib -L$INSTALL_DIR/lib \
          -lephcomf -lephcomfc -lephcom -lgnulliver -lm \
          application.f -o application
        

using the ephcom2 Fortran 77 API.

For example, this method works to build and link the main program part of the testeph.f Fortran code (the part which calls const and pleph) that is distributed with the JPL Fortran software at ftp://ssd.jpl.nasa.gov/pub/eph/planets/fortran/.

News

The JPL ephemeris data have been updated

The JPL planetary ephemerides represent some of mankind's best knowledge of the positions and velocities... Read more (5 Feb 2013)

te_gen-2.0.0 results have been released

This file release (http://sourceforge.net/projects/timeephem/files/Time%20Ephemerides/) contains... Read more (18 Jan 2013)

te_gen-2.0.0 has been released

The te_gen-2.0.0 software package that allows users to generate time ephemerides from planetary... Read more (15 Jan 2013)

ephcom-3.0.0 has been released

The ephcom-3.0.0 software package that gives users convenient access to planetary and time ephemerides... Read more (12 Jan 2013)

ephcom-2.0.2 has been released

The ephcom-2.0.2 software package that gives users convenient access to the JPL ephemerides,... Read more (14 Sep 2011)

ephcom-2.0.1 has been released

ephcom-2.0.1, a software package that gives users convenient access to the JPL ephemerides, has been... Read more (24 Aug 2011)

The JPL ephemeris data have been released

The JPL ephemerides represent mankind's best knowledge of the positions and velocities of all major... Read more (23 Aug 2011)

Resources

Source Code