Single file access functions

This group of functions works on a single ephemeris file at a given instant. They use an internal global variable to store information about the current opened ephemeris file.

They are provided to have a similar interface of the fortran PLEPH function, supplied with the JPL ephemeris files. So the following call to PLEPH

PLEPH(46550D0, 3, 12, PV)

could be replaced by

calceph_sopen("ephemerisfile.dat")
calceph_scompute(46550D0, 0, 3, 12, PV)
calceph_sclose()

While the function PLEPH could access only one file in a program, these functions could access on multiple files in a program but not at same time. To access multiple files at a same time, the functions listed in the section Multiple file access functions must be used.

When an error occurs, these functions execute error handlers according to the behavior defined by the function calceph_seterrorhandler().

The python interface does not provide these functions, the listed in the section Multiple file access functions must be used.

Time notes

The function calceph_scompute() only accepts a date expressed in the same timescale as the ephemeris files, which can be retrieved using the function calceph_sgettimescale(). Ephemeris files are generally expressed using the timescale TDB. If a date, expressed in the TT (Terrestrial Time) timescale, is supplied to this function, calceph_scompute() will return an erroneous position of the order of several tens of meters for the planets. If a date, expressed in the Coordinated Universal Time (UTC), is supplied to this function, calceph_scompute() will return a very large erroneous position over several thousand kilometers for the planets.

Thread notes

If the standard I/O functions such as fread are not reentrant then the CALCEPH I/O functions using them will not be reentrant either.

If the library was configured with the option --enable-thread=yes, these functions use an internal global variable per thread. Each thread could access to different ephemeris file and compute ephemeris data at same time. But each thread must call the function calceph_sopen() to open ephemeris file even if all threads work on the same file.

If the library was configured with the default option --enable-thread=no, these functions use an internal global variable per process and are not thread-safe. If multiple threads are used in the process and call the function calceph_scompute() at the same time, the caller thread must surround the call to this function with locking primitives, such as pthread_lock/pthread_unlock if POSIX Pthreads are used.

Usage

The following examples, that can be found in the directory examples of the library sources, show the typical usage of this group of functions.

The example in Fortran 2003 language is f2003single.f.

USE, INTRINSIC :: ISO_C_BINDING
use calceph
implicit none
integer res
real(8) AU, EMRAT, GM_Mer
real(8) jd0
real(8) dt
real(8) PV(6)
integer j
real(8) valueconstant
character(len=CALCEPH_MAX_CONSTANTNAME) nameconstant

jd0 = 2442457
dt = 0.5E0
! open the ephemeris file
res = calceph_sopen("example1.dat"//C_NULL_CHAR)
if (res.eq.1) then
  write (*,*) "The ephemeris is already opened"
  ! print the values of AU, EMRAT and GM_Mer
  if (calceph_sgetconstant("AU"//C_NULL_CHAR, AU).eq.1) then
      write (*,*) "AU=", AU
  endif
  if (calceph_sgetconstant("EMRAT"//C_NULL_CHAR,EMRAT).eq.1) then
      write (*,*) "EMRAT=", EMRAT
  endif
  if (calceph_sgetconstant("GM_Mer"//C_NULL_CHAR,GM_Mer).eq.1) then
      write (*,*) "GM_Mer=", GM_Mer
  endif

  ! compute and print the coordinates
  ! the geocentric moon coordinates
  res = calceph_scompute(jd0, dt, 10, 3, PV)
  call printcoord(PV,"geocentric coordinates of the Moon")
  ! the value TT-TDB
  if (calceph_scompute(jd0, dt, 16, 0, PV).eq.1) then
    write (*,*) "TT-TDB = ", PV(1)
  endif
  ! the heliocentric coordinates of Mars
  res = calceph_scompute(jd0, dt, 4, 11, PV)
  call printcoord(PV,"heliocentric coordinates of Mars")


  ! print the whole list of the constants
  write (*,*) "list of constants"
  do j=1, calceph_sgetconstantcount()
    res = calceph_sgetconstantindex(j,nameconstant, valueconstant)
    write (*,*) nameconstant,"=",valueconstant
  enddo


  ! close the ephemeris file
  call calceph_sclose
  write (*,*) "The ephemeris is already closed"
else
  write (*,*) "The ephemeris can't be opened"
endif

Functions