Loading...
Searching...
No Matches
util.c File Reference

Various commonly used routines used throughout the SuperNOVAS library. More...

## Macros

#define | DEFAULT_ERROR_HANDLER default_error_handler
| Prints debug error messages to stderr.

## Functions

double | d_light (const double *pos_src, const double *pos_body)
| Returns the difference in light-time, for a star, between the barycenter of the solar system and the observer (or the geocenter) (Usage A).
PROTECTED void | novas_debug (enum novas_debug_mode mode)
| Enables or disables reporting errors and traces to the standard error stream.
int | novas_equ_offset_by (double ra, double dec, double direction, double distance, double *restrict out_ra, double *restrict out_dec)
| Calculates offset equatorial coordinates at some distance away from the input coordinates along a great circle which crosses the input position at the specified position angle.
double | novas_equ_sep (double ra1, double dec1, double ra2, double dec2)
| Returns the angular separation of two equatorial locations on a sphere.
enum novas_debug_mode | novas_get_debug_mode ()
| Returns the current, thread-local, mode for reporting errors encountered (and traces).
double | novas_norm_ang (double angle)
| Returns the normalized angle in the [0:2π) range.
int | novas_offset_by (double lon, double lat, double direction, double distance, double *restrict out_lon, double *restrict out_lat)
| Calculates offset spherical coordinates at some distance away from the input coordinates along a great circle which crosses the input position at the specified direction.
int | novas_print_dms (double degrees, enum novas_separator_type sep, int decimals, char *restrict buf, int len)
| Prints an angle in degrees as [-]ddd:mm:ss[.S...] into the specified buffer, with up to nanosecond precision.
int | novas_print_hms (double hours, enum novas_separator_type sep, int decimals, char *restrict buf, int len)
| Prints a time in hours as hh:mm:ss[.S...] into the specified buffer, with up to nanosecond precision.
double | novas_sep (double lon1, double lat1, double lon2, double lat2)
| Returns the angular separation of two locations on a sphere.
novas_error_handler | novas_set_error_handler (novas_error_handler handler)
| Replaces the trace / error message handler.
double | novas_vlen (const double *restrict v)
| (for internal use only) Calculates the length of a 3-vector
int | radec2vector (double ra, double dec, double dist, double *restrict pos)
| Converts equatorial spherical coordinates to a vector (equatorial rectangular coordinates).
int | spin (double angle, const double *in, double *out)
| Transforms a vector from one coordinate system to another with same origin and axes rotated about the z-axis.
short | vector2radec (const double *restrict pos, double *restrict ra, double *restrict dec)
| Converts a vector in equatorial rectangular coordinates to equatorial spherical coordinates.

## Variables

int | novas_inv_max_iter = 100
| Maximum number of iterations for convergent inverse calculations.

## Detailed Description

Various commonly used routines used throughout the SuperNOVAS library.

Date
  Created on Mar 6, 2025

Author
  G. Kaplan, Attila Kovacs, and Kiran Shila

## Macro Definition Documentation

## DEFAULT_ERROR_HANDLER

#define DEFAULT_ERROR_HANDLER default_error_handler

Prints debug error messages to stderr.

Referenced by novas_set_error_handler().

## Function Documentation

## d_light()

double d_light | ( | const double * | pos_src,
|  | const double * | pos_body )

Returns the difference in light-time, for a star, between the barycenter of the solar system and the observer (or the geocenter) (Usage A).

Alternatively (Usage B), this function returns the light-time from the observer (or the geocenter) to a point on a light ray that is closest to a specific solar system body. For this purpose, 'pos_src' is the position vector toward observed object, with respect to origin at observer (or the geocenter); 'pos_body' is the position vector of solar system body, with respect to origin at observer (or the geocenter), components in AU; and the returned value is the light time to point on line defined by 'pos' that is closest to solar system body (positive if light passes body before hitting observer, i.e., if 'pos_body' is within 90 degrees of 'pos_src').

NOTES:

1. This function is called by novas_geom_posvel(), novas_sky_pos(), or place()

Parameters

  pos_src | Position vector towards observed object, with respect to the SSB (Usage A), or relative to the observer / geocenter (Usage B).
  pos_body | [AU] Position of observer relative to SSB (Usage A), or position of intermediate solar-system body with respect to the observer / geocenter (Usage B).

Returns
  [day] Difference in light time to observer, either relative to SSB (Usage A) or relative intermediate solar-system body (Usage B); or else NAN if either of the input arguments is NULL.

See also
  novas_sky_pos(), novas_geom_posvel()

References novas_vlen().

Referenced by grav_planets(), novas_geom_posvel(), and place().

## novas_equ_offset_by()

int novas_equ_offset_by | ( | double | ra,
|  | double | dec,
|  | double | direction,
|  | double | distance,
|  | double *restrict | out_ra,
|  | double *restrict | out_dec )

Calculates offset equatorial coordinates at some distance away from the input coordinates along a great circle which crosses the input position at the specified position angle.

Parameters

  | ra | [h] reference point right ascension (R.A.)
  | dec | [deg] reference point declination
  | direction | [deg] direction (measured East of North).
  | distance | [deg] offset distance on great circle
  [out] | out_ra | [h] right ascension (R.A.) at offset position in [0:24) range. It may be NULL if not needed.
  [out] | out_dec | [deg] declination at offset position in [-&pi/2:π/2] range. It may be NULL if not needed.

Returns
  0 if successful, or else -1 if very close to the pole, and right ascension (R.A.) at the offset position is requested, or if the input declination is outside of the [-90:90] range.

Since
  1.7

Author
  Attila Kovacs

See also
  novas_offset_by(), novas_equ_sep()

References novas_offset_by().

## novas_equ_sep()

double novas_equ_sep | ( | double | ra1,
|  | double | dec1,
|  | double | ra2,
|  | double | dec2 )

Returns the angular separation of two equatorial locations on a sphere.

Parameters

  ra1 | [h] right ascension of first location
  dec1 | [deg] declination of first location
  ra2 | [h] right ascension of second location
  dec2 | [deg] declination of second location

Returns
  [deg] the angular separation of the two locations.

Since
  1.3

Author
  Attila Kovacs

See also
  novas_sep(), novas_sun_angle(), novas_moon_angle()
  novas_equ_offset_by()

References novas_sep().

Referenced by novas_object_sep().

## novas_norm_ang()

double novas_norm_ang | ( | double | angle | ) |

Returns the normalized angle in the [0:2π) range.

Parameters

  angle | [rad] an angle in radians.

Returns
  [rad] the normalized angle in the [0:2π) range.

Since
  1.0

Author
  Attila Kovacs

References TWOPI.

Referenced by fund_args().

## novas_offset_by()

int novas_offset_by | ( | double | lon,
|  | double | lat,
|  | double | direction,
|  | double | distance,
|  | double *restrict | out_lon,
|  | double *restrict | out_lat )

Calculates offset spherical coordinates at some distance away from the input coordinates along a great circle which crosses the input position at the specified direction.

Based on the astropy offset_by() implementation.

Parameters

  | lon | [deg] reference point longitude
  | lat | [deg] reference point latitude
  | direction | [deg] direction (measured East of North).
  | distance | [deg] offset distance on great circle
  [out] | out_lon | [deg] longitude at offset position in [-π:π) range. It may be NULL if not needed.
  [out] | out_lat | [deg] latitude at offset position in [-&pi/2:π/2] range. It may be NULL if not needed.

Returns
  0 if successful, or else -1 if very close to the pole, and longitude at the offset position is requested, or if the input latitude is outside of the [-90:90] range.

Since
  1.7

Author
  Attila Kovacs

See also
  novas_equ_offset_by(), novas_sep()
  https://docs.astropy.org/en/stable/_modules/astropy/coordinates/angles/utils.html#offset_at

Referenced by novas_equ_offset_by(), supernovas::Ecliptic::offset(), supernovas::Equatorial::offset(), supernovas::Galactic::offset(), and supernovas::Horizontal::offset().

## novas_print_dms()

int novas_print_dms | ( | double | degrees,
|  | enum novas_separator_type | sep,
|  | int | decimals,
|  | char *restrict | buf,
|  | int | len )

Prints an angle in degrees as [-]ddd:mm:ss[.S...] into the specified buffer, with up to nanosecond precision.

The degrees component is always printed as 4 characters (up to 3 digits plus optional negative sign), so the output is always aligned. If positive values are expected to be explicitly signed also, the caller may simply put the '+' sign into the leading byte.

NaN and infinite values, are printed as their standard floating-point representations.

Parameters

  | degrees | [deg] angle value
  | sep | Type of separators to use between or after components. If the separator value is outside of the enum range, it will default to using colons.
  | decimals | Requested number of decimal places to print for the seconds [0:9].
  [out] | buf | String buffer in which to print DMS string, represented in the [-180:180) degree range.
  | len | Maximum number of bytes that may be written into the output buffer, including termination.

Returns
  The number of characters actually printed in the buffer, excluding termination, or else -1 if the input buffer is NULL or the length is less than 1 (errno will be set to EINVAL).

Since
  1.3

Author
  Attila Kovacs

See also
  novas_parse_dms(), novas_print_hms()

References NOVAS_SEP_COLONS, NOVAS_SEP_SPACES, NOVAS_SEP_UNITS, and NOVAS_SEP_UNITS_AND_SPACES.

Referenced by supernovas::Angle::to_string().

## novas_print_hms()

int novas_print_hms | ( | double | hours,
|  | enum novas_separator_type | sep,
|  | int | decimals,
|  | char *restrict | buf,
|  | int | len )

Prints a time in hours as hh:mm:ss[.S...] into the specified buffer, with up to nanosecond precision.

NaN and infinite values, are printed as their standard floating-point representations.

Parameters

  | hours | [h] time value
  | sep | Type of separators to use between or after components. If the separator value is outside of the enum range, it will default to using colons.
  | decimals | Requested number of decimal places to print for the seconds [0:9].
  [out] | buf | String buffer in which to print HMS string, represented in the [0:24) hour range.
  | len | Maximum number of bytes that may be written into the output buffer, including termination.

Returns
  The number of characters actually printed in the buffer, excluding termination, or else -1 if the input buffer is NULL or the length is less than 1 (errno will be set to EINVAL).

Since
  1.3

Author
  Attila Kovacs

See also
  novas_parse_hms(), novas_print_dms(), novas_timestamp()

References NOVAS_SEP_COLONS, NOVAS_SEP_SPACES, NOVAS_SEP_UNITS, and NOVAS_SEP_UNITS_AND_SPACES.

Referenced by supernovas::TimeAngle::to_string().

## novas_sep()

double novas_sep | ( | double | lon1,
|  | double | lat1,
|  | double | lon2,
|  | double | lat2 )

Returns the angular separation of two locations on a sphere.

It uses the Vincenty formula for accurate results across all locations on the sphere.

NOTES:

1. Prior to version 1.5, this function used the law of cosines, which is imprecise for nearby locations
2. In version 1.5, this function used the haversine formula, albeit with an error in the implementation. The haversine formula is accurate for nearby locations, but has rounding errors for antipodal locations.
3. From version 1.5.1, this function uses the Vincenty formula, which is accurate for all locations on the sphere.

REFERENCES:

1. Vincenty, Thaddeus. "Direct and Inverse Solutions of Geodesics on the Ellipsoid with Application of Nested Equations", Survey Review. 23 (176), Directorate of Overseas Surveys, doi:10.1179/sre.1975.23.176.88.

Parameters

  lon1 | [deg] longitude of first location
  lat1 | [deg] latitude of first location
  lon2 | [deg] longitude of second location
  lat2 | [deg] latitude of second location

Returns
  [deg] the angular separation of the two locations.

Since
  1.3

Author
  Attila Kovacs

See also
  novas_equ_sep(), novas_sun_angle(), novas_moon_angle()
  novas_offset_by()

Referenced by supernovas::Spherical::distance_to(), and novas_equ_sep().

## novas_vlen()

double novas_vlen | ( | const double *restrict | v | ) |

(for internal use only) Calculates the length of a 3-vector

Parameters

  v | Pointer to a 3-component (x, y, z) vector. The argument cannot be NULL

Returns
  the length of the vector

Since
  1.0

Author
  Attila Kovacs

See also
  novas_vdot(), novas_vdist()

Referenced by aberration(), supernovas::Vector::abs(), bary2obs(), cio_basis(), d_light(), grav_planets(), grav_undo_planets(), grav_vec(), limb_angle(), novas_approx_sky_pos(), novas_clock_skew(), novas_geom_to_app(), novas_helio_dist(), novas_moon_elp_sky_pos_fp(), novas_sky_pos(), novas_solar_illum(), place(), rad_vel2(), and transform_cat().

## radec2vector()

int radec2vector | ( | double | ra,
|  | double | dec,
|  | double | dist,
|  | double *restrict | pos )

Converts equatorial spherical coordinates to a vector (equatorial rectangular coordinates).

Parameters

  | ra | [h] Right ascension (hours).
  | dec | [deg] Declination (degrees).
  | dist | [AU] Distance (AU)
  [out] | pos | [AU] Position 3-vector, equatorial rectangular coordinates (AU).

Returns
  0 if successful, or -1 if the vector argument is NULL.

See also
  vector2radec(), starvectors()

Referenced by earth_sun_calc(), gcrs2equ(), novas_app_to_geom(), novas_app_to_hor(), novas_lsr_to_ssb_vel(), novas_ssb_to_lsr_vel(), starvectors(), supernovas::Horizontal::to_apparent(), supernovas::Equatorial::to_system(), and transform_cat().

## spin()

int spin | ( | double | angle,
|  | const double * | in,
|  | double * | out )

Transforms a vector from one coordinate system to another with same origin and axes rotated about the z-axis.

REFERENCES:

1. Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.

Parameters

  | angle | [deg] Angle of coordinate system rotation, positive counterclockwise when viewed from +z, in degrees.
  | in | Input position vector.
  [out] | out | Position vector expressed in new coordinate system rotated about z by 'angle'. It can be the same vector as the input.

Returns
  0 if successful, or -1 if the output vector is NULL.

References TWOPI.

Referenced by cel2ter(), cirs_to_tod(), novas_app_to_geom(), novas_app_to_hor(), novas_hor_to_app(), place(), ter2cel(), and tod_to_cirs().

## vector2radec()

short vector2radec | ( | const double *restrict | pos,
|  | double *restrict | ra,
|  | double *restrict | dec )

Converts a vector in equatorial rectangular coordinates to equatorial spherical coordinates.

REFERENCES:

1. Kaplan, G. H. et. al. (1989). Astron. Journ. 97, 1197-1210.

Parameters

  | pos | Position 3-vector, equatorial rectangular coordinates.
  [out] | ra | [h] Right ascension in hours [0:24] or NAN if the position vector is NULL or a null-vector. It may be NULL if not required.
  [out] | dec | [deg] Declination in degrees [-90:90] or NAN if the position vector is NULL or a null-vector. It may be NULL if not required.

Returns
  0 if successful, -1 of any of the arguments are NULL, or 1 if all input components are 0 so 'ra' and 'dec' are indeterminate, or else 2 if both x and y are zero, but z is nonzero, and so 'ra' is indeterminate.

See also
  radec2vector()

Referenced by gcrs2equ(), mean_star(), novas_geom_to_app(), novas_hor_to_app(), novas_moon_elp_sky_pos_fp(), novas_moon_phase(), novas_transform_sky_pos(), novas_uvw(), place(), supernovas::AstrometricPosition::to_equatorial(), supernovas::Apparent::to_horizontal(), and supernovas::Equatorial::to_system().

## Variable Documentation

## novas_inv_max_iter

int novas_inv_max_iter = 100

Maximum number of iterations for convergent inverse calculations.

Most iterative inverse functions should normally converge in a handful of iterations. In some pathological cases more iterations may be required. This variable sets an absolute maximum for the number of iterations in order to avoid runaway (zombie) behaviour. If inverse functions fail to converge, they will return a value indicating an error, and errno should be set to ECANCELED.

Since
  1.1

Referenced by grav_undo_planets(), light_time2(), mean_star(), novas_inv_refract(), novas_next_moon_phase(), and refract_astro().