Added functions for v1.3

CHANGELOG.md

@@ -7,6 +7,63 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [Unreleased]
+
+Upcoming feature release, expected around 1 May 2025.
+
+### Added
+
+ - New `novas_hms_hours(const char *str)` and `novas_dms_degrees(const char *str)` convenience functions to make it 
+   easier to parse HMS or DMS based time/angle values, returning the result in units of hours or degrees, 
+   appropriately for use in SuperNOVAS.
+
+ - New `novas_frame_lst()` convenience function to readily return the Local (apparent) Sidereal Time for a given 
+   Earth-based observing frame.
+
+ - New `novas_rises_above()` and `novas_sets_below()` functions to return the date/time a source rises above or sets
+   below a specific elevation on a given date. (Useful for Earth-based observers only).
+
+ - New `novas_helio_dist()` function to calculate the heliocentric distance of a Solar-system body on a given date. 
+   The `novas_solar_power()` function can be used to estimate the incident Solar power on a Solar-system body, while
+   `novas_solar_illum()` can be used to calculate the fraction of a spherical body that is illuminated by the Sun seen
+   from the observer location.
+
+ - New `novas_hpa()` and `novas_epa()` functions to calculate the parallactic angle (a.k.a. vertical position angle) 
+   for a given location on sky, using the local horizontal coordinates, or else the equatorial position, respectively. 
+   The parallactic angle (PA) can be useful to convert local Cartesian offsets (e.g. from a flat image or detector 
+   array) between the local horizontal and equatorial orientations, e.g. via the newly added `novas_h2e_offset()` or 
+   `novas_e2j_offset()` functions. The conversion between offsets and absolute coordinates usually requires a WCS
+   projections, such as described in Calabretta & Greisen 2002.
+
+ - New `novas_sep()`, `novas_equ_sep()`, and `novas_object_sep()` functions can be used to calculate the precise 
+   apparent distance between to spherical or equatorial locations, or between two sources, respectively. 
+   `novas_sun_angle()` and `novas_moon_angle()` can be used to calculate the apparent angular distance of sources from 
+   the Sun and Moon, respectively.
+
+ - New `novas_observable` and `novas_track` data structures to provide second order Taylor series expansion of the 
+   apparent horizontal or equatorial positions, distances and redshifts for sources. They can be calculated with the 
+   newly added `novas_hor_track()` or `novas_equ_track()` functions. Such tracking values, including rates and 
+   accelerations can be directly useful for controlling telescope drives in horizontal or equatorial mounts to track 
+   sources (hence the name). You can also obtain instantaneous projected (extrapolated) positions from the tracking 
+   parameters via `novas_track_pos()` at low computational cost.
+
+ - New `novas_xyz_to_uvw()` function to convert ITRS Earth locations (absolute or differential) to equatorial projections
+   along a line of sight in the direction of a source. Such projections are oft used in interferometry.
+
+ - #114: New `novas_lsr_to_ssb_vel()` can be used to convert velocity vectors referenced to the LSR to Solar-System 
+   Barycentric velocities. (The new function is used by `place()`, and `novas_geom_posvel()` internally.)
+
+### Changed
+
+ - #114: Velocities returned by `novas_geom_posvel()` and radial velocity measures returned in `sky_pos` (e.g. by 
+   `novas_sky_pos()` or `place()`) were not observer-based velocities for catalog sources. Instead, they were 
+   referenced to the LSR frame, with corrections for observer motion about the SSB, but not for the motion of the SSB 
+   in the LSR frame. As such, the radial velocities for catalog sources did not provide the expected spectroscopic
+   relation between observed and rest wavelengths i.e., _f_<sub>obs</sub> = (1 + _rv_ / _c_) _f_<sub>rest</sub>. This 
+   is a NOVAS C issue, which affected prior SuperNOVAS releases also.
+
+
+
 ## [1.2.0] - 2025-01-15
 
 Feature release. New easy to use adapter modules for CALCEPH or the NAIF CSPICE Toolkit to provide precise positions 

Makefile

@@ -88,6 +88,8 @@ solsys: $(SOLSYS_TARGETS)
 all: distro static test coverage analyze
 
 # Run regression tests
+export
+
 .PHONY: test
 test:
 	$(MAKE) -C test run

README.md

@@ -33,7 +33,7 @@ SuperNOVAS is entirely free to use without licensing restrictions.  Its source c
 standard, and hence should be suitable for old and new platforms alike. It is light-weight and easy to use, with full 
 support for the IAU 2000/2006 standards for sub-microarcsecond position calculations.
 
-This document has been updated for the `v1.2` and later releases.
+This document has been updated for the `v1.3` and later releases.
 
 
 ## Table of Contents
@@ -150,6 +150,9 @@ provided by SuperNOVAS over the upstream NOVAS C 3.1 code:
  - [__v1.1__] The NOVAS C 3.1 implementation of `rad_vel()` has a number of issues that produce inaccurate results. 
    The errors are typically at or below the tens of m/s level for objects not moving at relativistic speeds.
 
+ - [__v1.3__] The radial velocity measure returned in `sky_pos.rv` for catalog sources was not expressed relative the 
+   observer. As such, it did not provide an observable spectroscopic measure for catalog sources. This issue affected 
+   NOVAS C 3.1 and prior SuperNOVAS releases alike.
 
 -----------------------------------------------------------------------------
 

include/novas.h

@@ -62,10 +62,10 @@
 #define SUPERNOVAS_MAJOR_VERSION  1
 
 /// API minor version
-#define SUPERNOVAS_MINOR_VERSION  2
+#define SUPERNOVAS_MINOR_VERSION  3
 
 /// Integer sub version of the release
-#define SUPERNOVAS_PATCHLEVEL     1
+#define SUPERNOVAS_PATCHLEVEL     0
 
 /// Additional release information in version, e.g. "-1", or "-rc1", or empty string "" for releases.
 #define SUPERNOVAS_RELEASE_STRING "-devel"
@@ -181,6 +181,12 @@
 /// [s] TT - TAI time offset
 #define NOVAS_TAI_TO_TT           32.184
 
+/// [W/m<sup>2</sup>] The Solar Constant i.e., typical incident Solar power on Earth.
+/// The value of 1367 Wm<sup>−2</sup> was adopted by the World Radiation Center
+/// (Gueymard, 2004).
+/// @since 1.3
+#define NOVAS_SOLAR_CONSTANT      1367.0
+
 
 #if !COMPAT
 // If we are not in the strict compatibility mode, where constants are defined
@@ -1015,13 +1021,16 @@ typedef struct {
  *
  * @sa place()
  * @sa SKY_POS_INIT
+ * @sa novas_z_lsr()
  */
 typedef struct {
   double r_hat[3];  ///< unit vector toward object (dimensionless)
   double ra;        ///< [h] apparent, topocentric, or astrometric right ascension (hours)
   double dec;       ///< [deg] apparent, topocentric, or astrometric declination (degrees)
   double dis;       ///< [AU] true (geometric, Euclidian) distance to solar system body or 0.0 for star (AU)
-  double rv;        ///< [km/s] radial velocity (km/s)
+  double rv;        ///< [km/s] radial velocity (km/s). As of SuperNOVAS v1.3, this is always a proper
+                    ///< observer-based spectroscopic velocity measure, which relates the observed wavelength
+                    ///< to the rest wavelength as &lambda;<sub>obs</sub> = (1 + rv / c) &lambda;<sub>rest</sub>.
 } sky_pos;
 
 /**
@@ -1156,6 +1165,7 @@ typedef struct {
   novas_matrix nutation;          ///< nutation matrix (Lieske 1977 method)
   novas_matrix gcrs_to_cirs;      ///< GCRS to CIRS conversion matrix
   novas_planet_bundle planets;    ///< Planet positions and velocities (ICRS)
+  // TODO [v2] add ra_cio
 } novas_frame;
 
 /**
@@ -1178,6 +1188,7 @@ typedef struct {
   novas_matrix matrix;                      ///< Transformation matrix elements
 } novas_transform;
 
+
 /**
  * The type of elevation value for which to calculate a refraction.
  *
@@ -1259,6 +1270,38 @@ extern int grav_bodies_full_accuracy;
  */
 typedef double (*RefractionModel)(double jd_tt, const on_surface *loc, enum novas_refraction_type type, double el);
 
+/**
+ * Spherical and spectral coordinate set.
+ *
+ * @since 1.3
+ * @author Attila Kovacs
+ *
+ * @sa novas_track
+ */
+typedef struct {
+  double lon;           ///< [deg] apparent longitude coordinate in coordinate system
+  double lat;           ///< [deg] apparent latitude coordinate in coordinate system
+  double dist;          ///< [AU] apparent distance to source from observer
+  double z;             ///< redshift
+} novas_observable;
+
+/**
+ * The spherical and spectral tracking position of a source, and its first and second time derivatives. As such,
+ * it may be useful for telescope drive control (position, velocity, and acceleration), or else for fast
+ * extrapolation of momentary positions without a full, and costly, recalculation of the positions at high
+ * rate over a suitable short period.
+ *
+ * @since 1.3
+ * @author Attila Kovacs
+ */
+typedef struct {
+  novas_timespec time;     ///< The astronomical time for which the track is calculated.
+  novas_observable pos;    ///< [deg,AU,1] Apparent source position
+  novas_observable rate;   ///< [deg/s,AU/s,1/s] Apparent position rate of change
+  novas_observable accel;  ///< [deg/s<sup>2</sup>,AU/s<sup>2</sup>,1/s<sup>2</sup>] Apparent position acceleration.
+} novas_track;
+
+
 
 short app_star(double jd_tt, const cat_entry *star, enum novas_accuracy accuracy, double *ra, double *dec);
 
@@ -1651,8 +1694,48 @@ int gcrs_to_mod(double jd_tdb, const double *in, double *out);
 
 int mod_to_gcrs(double jd_tdb, const double *in, double *out);
 
-// <================= END of SuperNOVAS API =====================>
 
+// ---------------------- Added in 1.3.0 -------------------------
+int novas_lsr_to_ssb_vel(const double *vLSR, double unit, double *vSSB);
+
+double novas_hms_hours(const char *hms);
+
+double novas_dms_degrees(const char *dms);
+
+double novas_hpa(double az, double el, double lat);
+
+double novas_epa(double ha, double dec, double lat);
+
+int novas_h2e_offset(double daz, double del, double pa, double *dra, double *ddec);
+
+int novas_e2h_offset(double dra, double ddec, double pa, double *daz, double *del);
+
+double novas_sep(double lon1, double lat1, double lon2, double lat2);
+
+double novas_equ_sep(double ra1, double dec1, double ra2, double dec2);
+
+int novas_xyz_to_uvw(const double *xyz, double ha, double dec, double *uvw);
+
+double novas_frame_lst(const novas_frame *frame);
+
+double novas_rises_above(double el, const object *source, const novas_frame *frame, RefractionModel ref_model);
+
+double novas_sets_below(double el, const object *source, const novas_frame *frame, RefractionModel ref_model);
+
+double novas_object_sep(const object *source1, const object *source2, const novas_frame *frame);
+
+double novas_sun_angle(const object *source, const novas_frame *frame);
+
+double novas_moon_angle(const object *source, const novas_frame *frame);
+
+int novas_equ_track(const object *source, const novas_frame *frame, double dt, novas_track *track);
+
+int novas_hor_track(const object *source, const novas_frame *frame, RefractionModel ref_model, novas_track *track);
+
+int novas_track_pos(const novas_track *track, const novas_timespec *time, double *lon, double *lat, double *dist, double *z);
+
+
+// <================= END of SuperNOVAS API =====================>
 
 
 #include <solarsystem.h>
@@ -1736,6 +1819,8 @@ int novas_error(int ret, int en, const char *from, const char *desc, ...);
     return __ret; \
 }
 
+double novas_add_beta(double beta1, double beta2);
+
 double novas_vlen(const double *v);
 double novas_vdist(const double *v1, const double *v2);
 double novas_vdot(const double *v1, const double *v2);

include/solarsystem.h

@@ -361,6 +361,16 @@ long novas_to_naif_planet(enum novas_planet id);
 
 long novas_to_dexxx_planet(enum novas_planet id);
 
+
+// Added in v1.3 --------------------------------->
+
+double novas_helio_dist(double jd_tdb, const object *source, double *rate);
+
+double novas_solar_power(double jd_tdb, const object *source);
+
+double novas_solar_illum(const object *source, const novas_frame *frame);
+
+
 /// \cond PRIVATE