Read JPL ephemeris files. More...

#include <ctype.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "aephem.h"

Macros
#define	AE_JPL_MAXLINE 128
	The maximum number of characters for input.

#define	AE_JPL_TTL_MAXLINE 86
	The maximum length of TTL input. More...

#define	AE_SWOP_MACRO(A, B, TMP) {TMP = A; A = B; B = TMP;}
	A macro for swopping a block.

#define	AE_JPL_DATA_GROUP 1070
	The group number for JPL ASCII data.

#define	AE_JPL_GROUP_WORD "GROUP"
	The keyword for a new ASCII group.

Functions
void	ae_jpl_init_common_start (struct ae_jpl_handle_t *jh)
	Initialisation common to binary and ASCII at the beginning of the function. More...

void	ae_jpl_init_common_end (struct ae_jpl_handle_t *jh)
	Initialisation common to binary and ASCII at the end of the function. More...

int	ae_jpl_ascii_find_group (FILE *fp, int group_num)
	Find a group header. More...

int	ae_jpl_close_wrap (struct ae_jpl_handle_t *jh, int ret_code)
	An internal wrapper for closing a JPL file. More...

int	ae_jpl_get_block (struct ae_jpl_handle_t *jh, int block_num)
	Get a data block from a JPL file. More...

int	ae_jpl_read_ascii_block (struct ae_jpl_handle_t *jh, int block_num)
	Read a block of data coefficients from a JPL ASCII ephemeris file. More...

int	ae_jpl_read_bin_block (struct ae_jpl_handle_t *jh, int block_num)
	Read a JPL Ephemeris data block in binary format. More...

int	ae_jpl_cheby (struct ae_jpl_handle_t jh, int obj_num, double block_time, int n_coord, double pv)
	Interpolate at a point using Chebyshev coefficients. More...

int	ae_jpl_read_ascii_float (FILE fp, double val)
	Read the next floating point number from an ASCII file. More...

void	ae_swop_32_bit_val (void *ptr)
	Byte-swop a 32-bit value in-place. More...

void	ae_swop_64_bit_val (void *ptr, int n)
	Byte-swop a list of 64-bit values in-place. More...

int	ae_jpl_init (const char path, struct ae_jpl_handle_t jh)
	Initialise to use a JPL ephemeris file. More...

int	ae_jpl_init_ascii (const char path, const char header_path, int search_dates, struct ae_jpl_handle_t *jh)
	Read a JPL ephemeris ASCII header. More...

int	ae_jpl_init_bin (const char path, struct ae_jpl_handle_t jh)
	Read a JPL Ephemeris header in binary format. More...

void	ae_jpl_close (struct ae_jpl_handle_t *jh)
	Finish with a JPL handle. More...

double	ae_jpl_get_const_val (const struct ae_jpl_handle_t jh, const char const_name)
	Get the value of a constant defined in the JPL ephemeris header. More...

int	ae_jpl_get_coords (struct ae_jpl_handle_t *jh, double jd_tt, int obj_num, double r[], double v[], char is_planetary)
	Get object positions from a JPL ephemeris file. More...

Detailed Description

Read JPL ephemeris files.

Macro Definition Documentation

#define AE_JPL_TTL_MAXLINE 86

The maximum length of TTL input.

Function Documentation

int ae_jpl_ascii_find_group	(	FILE *	fp,
		int	group_num
	)

Find a group header.

This function searches for the group from the beginning of the file, until it either finds the requested group, or it reaches the data record group (AE_JPL_DATA_GROUP). In the latter case, the function fails. Otherwise, it returns successfully with the file synced to the beginning of the group.

Group header lines are 12 characters long, of the form "GROUP NNNN". We allow more flexibility and only require that they be of the form "%s %d".

Parameters

fp	The file pointer to read.
group_num	The group number to search for.

Returns: 0 on success; otherwise a negative error code from ae_retcode_t.

References AE_JPL_DATA_GROUP, AE_JPL_GROUP_WORD, AE_JPL_MAXLINE, AE_RET_BAD_JPL_HEADER_GROUP, and AE_RET_UNEXPECTED_EOF.

Referenced by ae_jpl_init_ascii().

int ae_jpl_cheby	(	struct ae_jpl_handle_t *	jh,
		int	obj_num,
		double	block_time,
		int	n_coord,
		double *	pv
	)

Interpolate at a point using Chebyshev coefficients.

Parameters

jh	A handle initialised with ae_jpl_init().
obj_num	The object index.
block_time	The time, in days, from the beginning of the block at which to interpolate.
n_coord	The number of coordinates for each of position and velocity.
*pv	Array for returning position (first three indices) and velocity (last three indices).

Returns: 0 on success; on failure, a negative error code from ae_retcode_t.

References AE_RET_BAD_JPL_CHEBY_TIME, AE_RET_UNDER_CONSTRUCTION, ae_jpl_handle_t::block, ae_jpl_handle_t::ipt, ae_jpl_handle_t::last_x, ae_jpl_handle_t::max_cheby, ae_jpl_handle_t::pc, ae_jpl_handle_t::step, and ae_jpl_handle_t::vc.

Referenced by ae_jpl_get_coords().

void ae_jpl_close ( struct ae_jpl_handle_t * jh )

Finish with a JPL handle.

Closes any open file pointers and frees any allocated arrays.

Parameters

jh	A JPL handle.

References ae_jpl_close_wrap().

int ae_jpl_close_wrap	(	struct ae_jpl_handle_t *	jh,
		int	ret_code
	)

An internal wrapper for closing a JPL file.

Not designed to be called by the user.

Parameters

jh	The handle to be closed.
ret_code	The value this function should return.

Returns: Always returns ret_code.

References ae_jpl_handle_t::block, ae_jpl_handle_t::const_name, ae_jpl_handle_t::const_val, ae_jpl_handle_t::fp, ae_jpl_handle_t::n_const, ae_jpl_handle_t::pc, and ae_jpl_handle_t::vc.

Referenced by ae_jpl_close(), ae_jpl_init_ascii(), and ae_jpl_init_bin().

int ae_jpl_get_block	(	struct ae_jpl_handle_t *	jh,
		int	block_num
	)

Get a data block from a JPL file.

Reads, as appropriate, either from a binary or ASCII file and caches result. If requested block_num is already cached, then no read is done.

Parameters

jh	The handle for this file. (The function ae_jpl_init() should be called first.)
block_num	The data block number, starting at 0.

Returns: The number of coefficients in the block, or 0 on EOF. If there is an error, a negative error code from ae_retcode_t is returned.

References ae_jpl_read_ascii_block(), ae_jpl_read_bin_block(), ae_jpl_handle_t::is_bin, and ae_jpl_handle_t::last_block_num.

Referenced by ae_jpl_get_coords().

double ae_jpl_get_const_val	(	const struct ae_jpl_handle_t *	jh,
		const char *	const_name
	)

Get the value of a constant defined in the JPL ephemeris header.

Parameters

jh	An initialised JPL handle.
const_name	The name of the constant, as it appears in the header.

Returns: The constant value; 0 if the constant name does not exist.

References AE_JPL_CONST_LEN, ae_jpl_handle_t::const_name, ae_jpl_handle_t::const_val, and ae_jpl_handle_t::n_const.

Referenced by ae_jpl_init_ascii().

int ae_jpl_get_coords	(	struct ae_jpl_handle_t *	jh,
		double	jd_tt,
		int	obj_num,
		double	r[],
		double	v[],
		char	is_planetary
	)

Get object positions from a JPL ephemeris file.

Parameters

jh	A handle initialised by ae_jpl_init().
jd_tt	The Julian date in TT.
obj_num	The object for which to get coordinates. If a planetary ephemeris file is being used, one can use the predefined ae_ss_bodies_t constants for clarity.
r	For returning the rectangular position coordinates, in AU; for nutations and librations, units are seconds of arc.
v	For returning the rectangular velocity, in AU per day (or seconds of arc per day for nutations or librations) Set to NULL if you do not require this information (though setting to NULL does not make this routine faster).
is_planetary	If 0, assume these are not planetary ephemerides and barycentric coordinates are returned. Otherwise, it will be assumed that a Solar System ephemeris file is being used and that the object numbers are as in ae_ss_bodies_t; heliocentric coordinates will be returned.

Returns: 0 on success; on failure, a negative code from ae_retcode_t.

References AE_AU, ae_jpl_cheby(), ae_jpl_get_block(), AE_N_SS_BODIES_JPL, AE_RET_BAD_JPL_DATE, AE_RET_BAD_OBJ_INDEX, AE_RTS, AE_SS_EARTH, AE_SS_EMBARY, AE_SS_LIBRATION, AE_SS_MOON, AE_SS_MOON_EMB, AE_SS_NUTATION, AE_SS_SSBARY, AE_SS_SUN, ae_jpl_handle_t::block, ae_jpl_handle_t::em_ratio, ae_jpl_handle_t::end, ae_jpl_handle_t::start, ae_jpl_handle_t::step, ae_jpl_handle_t::sun_pv, and ae_jpl_handle_t::sun_pv_t.

Referenced by ae_geocentric_from_jpl(), and ae_light_t_jpl().

int ae_jpl_init	(	const char *	path,
		struct ae_jpl_handle_t *	jh
	)

Initialise to use a JPL ephemeris file.

This function opens the file, determines whether it is binary or ASCII, and parses the header information. This information is stored in the handle jh and is passed to subsequent JPL function calls.

If the ephemeris is in ASCII format and has a separate header file, use ae_jpl_init_ascii() instead.

If you know the format of the ephemeris file, you can use ae_jpl_init_bin() or ae_jpl_init_ascii() directly.

Parameters

path	The location of the ephemeris file.
jh	For returning an initialised handle.

Returns: 0 on success; otherwise, a negative code from ae_retcode_t; this assuming that it is a binary file, which is the last format attempted.

References ae_jpl_init_ascii(), ae_jpl_init_bin(), ae_jpl_handle_t::fp, and ae_jpl_handle_t::is_bin.

int ae_jpl_init_ascii	(	const char *	path,
		const char *	header_path,
		int	search_dates,
		struct ae_jpl_handle_t *	jh
	)

Read a JPL ephemeris ASCII header.

Parameters

path	The location of the ephemeris file.
header_path	Set to NULL, unless the header file is separate (as it might be an ASCII ephermeris).
search_dates	Since JPL often splits its ASCII ephermerides into multiple files, the date range specified in the header might not correspond to the file being used. To search through the file to get the dates, set this to 1 (recommended). To trust the header, set to 0.
jh	For returning an initialised handle, on success.

Returns: 0 on success; on error, a negative error code from ae_retcode_t.

References AE_AU, AE_E_M_RAT, ae_jpl_ascii_find_group(), ae_jpl_close_wrap(), AE_JPL_CONST_LEN, AE_JPL_DATA_GROUP, ae_jpl_get_const_val(), ae_jpl_init_common_end(), ae_jpl_init_common_start(), AE_JPL_MAXLINE, ae_jpl_read_ascii_float(), AE_RET_BAD_JPL_CORRUPT, AE_RET_BAD_JPL_HEADER, AE_RET_BAD_JPL_HEADER_KSIZE, AE_RET_BAD_JPL_HEADER_NUM, AE_RET_BAD_JPL_HEADER_RANGE, AE_RET_BAD_PATH, AE_RET_UNEXPECTED_EOF, ae_jpl_handle_t::ascii_start, ae_jpl_handle_t::au, ae_jpl_handle_t::const_name, ae_jpl_handle_t::const_val, ae_jpl_handle_t::em_ratio, ae_jpl_handle_t::end, ae_jpl_handle_t::ephemeris_version, ae_jpl_handle_t::fp, ae_jpl_handle_t::ipt, ae_jpl_handle_t::is_bin, ae_jpl_handle_t::n_coeff, ae_jpl_handle_t::n_const, ae_jpl_handle_t::rec_size, ae_jpl_handle_t::start, and ae_jpl_handle_t::step.

Referenced by ae_jpl_init().

int ae_jpl_init_bin	(	const char *	path,
		struct ae_jpl_handle_t *	jh
	)

Read a JPL Ephemeris header in binary format.

Parameters

path	The location of the ephemeris file.
jh	For returning an initialised handle, on success.

Returns: 0 on success; otherwise a negative error code from ae_retcode_t.

References ae_jpl_close_wrap(), AE_JPL_CONST_LEN, AE_JPL_HEAD_SIZE, ae_jpl_init_common_end(), ae_jpl_init_common_start(), AE_RET_BAD_JPL_HEADER, AE_RET_BAD_PATH, AE_RET_UNEXPECTED_EOF, ae_swop_32_bit_val(), ae_swop_64_bit_val(), ae_jpl_handle_t::au, ae_jpl_handle_t::const_name, ae_jpl_handle_t::const_val, ae_jpl_handle_t::em_ratio, ae_jpl_handle_t::end, ae_jpl_handle_t::ephemeris_version, ae_jpl_handle_t::fp, ae_jpl_handle_t::ipt, ae_jpl_handle_t::is_bin, ae_jpl_handle_t::n_coeff, ae_jpl_handle_t::n_const, ae_jpl_handle_t::rec_size, ae_jpl_handle_t::start, ae_jpl_handle_t::step, and ae_jpl_handle_t::swop.

Referenced by ae_jpl_init().

void ae_jpl_init_common_end ( struct ae_jpl_handle_t * jh )

Initialisation common to binary and ASCII at the end of the function.

Parameters

jh	The JPL handle.

References ae_jpl_handle_t::ascii_len_block, ae_jpl_handle_t::block, ae_jpl_handle_t::ipt, ae_jpl_handle_t::last_block_num, ae_jpl_handle_t::last_x, ae_jpl_handle_t::max_cheby, ae_jpl_handle_t::pc, ae_jpl_handle_t::rec_size, ae_jpl_handle_t::sun_pv_t, and ae_jpl_handle_t::vc.

Referenced by ae_jpl_init_ascii(), and ae_jpl_init_bin().

void ae_jpl_init_common_start ( struct ae_jpl_handle_t * jh )

Initialisation common to binary and ASCII at the beginning of the function.

Parameters

jh	The JPL handle.

References ae_jpl_handle_t::block, ae_jpl_handle_t::const_name, ae_jpl_handle_t::const_val, ae_jpl_handle_t::fp, ae_jpl_handle_t::max_cheby, ae_jpl_handle_t::n_const, ae_jpl_handle_t::pc, and ae_jpl_handle_t::vc.

Referenced by ae_jpl_init_ascii(), and ae_jpl_init_bin().

int ae_jpl_read_ascii_block	(	struct ae_jpl_handle_t *	jh,
		int	block_num
	)

Read a block of data coefficients from a JPL ASCII ephemeris file.

Parameters

jh	The handle for this file. (The function ae_jpl_init() should be called first.)
block_num	The block number to read. Even though in ASCII files the block numbers start at unity, `block_num` should be counted from 0, for compatibility with ae_jpl_read_bin_block(). This function will add one to the passed block number.

Returns: 0 on success; otherwise, a negative error code from ae_retcode_t is returned.

References AE_JPL_MAXLINE, ae_jpl_read_ascii_float(), AE_RET_BAD_JPL_BLOCK, AE_RET_BAD_JPL_CORRUPT, AE_RET_UNEXPECTED_EOF, ae_jpl_handle_t::ascii_len_block, ae_jpl_handle_t::ascii_start, ae_jpl_handle_t::block, ae_jpl_handle_t::fp, and ae_jpl_handle_t::n_coeff.

Referenced by ae_jpl_get_block().

int ae_jpl_read_ascii_float	(	FILE *	fp,
		double *	val
	)

Read the next floating point number from an ASCII file.

Annoyingly, the JPL files use 'D' instead of 'E' for their scientific notation. This means that we need to fiddle around a bit to change 'D' to 'E'.

This function assumes that file stream is currently at the number to be read. After it returns, the file stream will have advanced past the number.

Parameters

fp	The file stream.
val	For returning the value.

Returns: 0 on success; otherwise, a negative error code from ae_retcode_t is returned.

References AE_RET_BAD_JPL_BLOCK, AE_RET_BAD_JPL_FLOAT, and AE_RET_UNEXPECTED_EOF.

Referenced by ae_jpl_init_ascii(), and ae_jpl_read_ascii_block().

int ae_jpl_read_bin_block	(	struct ae_jpl_handle_t *	jh,
		int	block_num
	)

Read a JPL Ephemeris data block in binary format.

The block number ranges from 0 on up (starting at first data block, after the 2 header blocks).

Parameters

jh	The handle for this file. (The function ae_jpl_init() should be called first.)
block_num	The data block number, starting at 0.

Returns: On success, 0. If there is an error, a negative error code from ae_retcode_t is returned.

References AE_RET_READ_ERROR, AE_RET_UNEXPECTED_EOF, ae_swop_64_bit_val(), ae_jpl_handle_t::block, ae_jpl_handle_t::fp, ae_jpl_handle_t::last_block_num, ae_jpl_handle_t::n_coeff, ae_jpl_handle_t::rec_size, and ae_jpl_handle_t::swop.

Referenced by ae_jpl_get_block().

void ae_swop_32_bit_val ( void * ptr )

Byte-swop a 32-bit value in-place.

Parameters

ptr	The 32-bit value to be swopped.

References AE_SWOP_MACRO.

Referenced by ae_jpl_init_bin().

void ae_swop_64_bit_val	(	void *	ptr,
		int	n
	)

Byte-swop a list of 64-bit values in-place.

Parameters

ptr	The 64-bit values to be swopped.
n	The number of values in `ptr`.

References AE_SWOP_MACRO.

Referenced by ae_jpl_init_bin(), and ae_jpl_read_bin_block().

Macros

Functions

Detailed Description

Macro Definition Documentation

Function Documentation