Skip to content

Commit

Permalink
Continued README edits
Browse files Browse the repository at this point in the history
  • Loading branch information
attipaci committed Feb 24, 2024
1 parent 4d8d312 commit 5577378
Show file tree
Hide file tree
Showing 2 changed files with 39 additions and 42 deletions.
32 changes: 16 additions & 16 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,8 @@ This is the initial release of the SuperNOVAS library.

### Fixed

- Fixes the [sidereal_time bug](https://aa.usno.navy.mil/software/novas_faq), whereby the `sidereal_time()`
function had an incorrect unit cast. This is a known issue of NOVAS C 3.1.
- Fixes the [sidereal_time bug](https://aa.usno.navy.mil/software/novas_faq), whereby the `sidereal_time()` function
had an incorrect unit cast. This is a known issue of NOVAS C 3.1.

- Fixes the [ephem_close bug](https://aa.usno.navy.mil/software/novas_faq), whereby `ephem_close()` in
`ephem_manager.c` did not reset the `EPHFILE` pointer to NULL. This is a known issue of NOVAS C 3.1.
Expand All @@ -41,21 +41,21 @@ This is the initial release of the SuperNOVAS library.
- Fixes multiple bugs related to using cached values in `cio_basis()` with alternating CIO location reference
systems.

- Fixes bug in `equ2ecl_vec()` and `ecl2equ_vec()` whereby a query with `coord_sys = 2` (GCRS) has overwritten the
- Fixes bug in `equ2ecl_vec()` and `ecl2equ_vec()` whereby a query with `coord_sys = 2` (GCRS) has overwritten the
cached mean obliquity value for `coord_sys = 0` (mean equinox of date). As a result, a subsequent call with
`coord_sys = 0` and the same date as before would return the results GCRS coordinates instead of the
requested mean equinox of date coordinates.
`coord_sys = 0` and the same date as before would return the results GCRS coordinates instead of the requested mean
equinox of date coordinates.

- The use of `fmod()` in NOVAS C 3.1 led to the wrong results when the numerator was negative and the result was
not turned into a proper remainder. This affected the calculation of the mean anomaly in `solsys3.c` (line 261)
and the fundamental arguments calculated in `fund_args()` and `ee_ct()` for dates prior to J2000. Less
critically, it also was the reason `cal_date()` did not work for negative JD values.
- The use of `fmod()` in NOVAS C 3.1 led to the wrong results when the numerator was negative and the result was not
turned into a proper remainder. This affected the calculation of the mean anomaly in `solsys3.c` (line 261) and the
fundamental arguments calculated in `fund_args()` and `ee_ct()` for dates prior to J2000. Less critically, it also
was the reason `cal_date()` did not work for negative JD values.

- Fixes `aberration()` returning NAN vectors if the `ve` argument is 0. It now returns the unmodified input
vector appropriately instead.
- Fixes `aberration()` returning NAN vectors if the `ve` argument is 0. It now returns the unmodified input vector
appropriately instead.

- Fixes unpopulated `az` output value in `equ2hor` at zenith. While any azimuth is acceptable really, it results
in irreproducible behavior. Hence, we set az to 0.0 for zenith to be consistent.
- Fixes unpopulated `az` output value in `equ2hor` at zenith. While any azimuth is acceptable really, it results in
irreproducible behavior. Hence, we set az to 0.0 for zenith to be consistent.

- Fixes potential string overflows and eliminates associated compiler warnings.

Expand Down Expand Up @@ -141,11 +141,11 @@ This is the initial release of the SuperNOVAS library.
invalid (unless the NOVAS C API already defined a different return value for specific cases. If so, the NOVAS C
error code is returned for compatibility).

- All erroneous returns now set `errno` so that users can track the source of the error in the standard C way and
use functions such as `perror()` and `strerror()` to print human-readable error messages.
- All erroneous returns now set `errno` so that users can track the source of the error in the standard C way and use
functions such as `perror()` and `strerror()` to print human-readable error messages.

- Many output values supplied via pointers are set to clearly invalid values in case of erroneous returns, such as
`NAN` so that even if the caller forgets to check the error code, it becomes obvious that the values returned
`NAN` so that even if the caller forgets to check the error code, it becomes obvious that the values returned
should not be used as if they were valid. (No more sneaky silent errors.)

- Many SuperNOVAS functions allow `NULL` arguments, both for optional input values as well as outputs that are not
Expand Down
49 changes: 23 additions & 26 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ The primary goals of SuperNOVAS is to improve on the stock NOVAS C library via:
- Fixing [outstanding issues](#fixed-issues)
- Improved [API documentation](https://smithsonian.github.io/SuperNOVAS.home/apidoc/html/).
- [New features](#added-functionality)
- [Refining the existing API]((#api-changes)) to promote best programing practices.
- [Refining the API]((#api-changes)) to promote best programing practices.
- [Regression testing](https://codecov.io/gh/Smithsonian/SuperNOVAS) and continuous integration on GitHub.

At the same time, SuperNOVAS aims to be fully backward compatible with the intended functionality of the upstream
Expand Down Expand Up @@ -100,16 +100,15 @@ Here are some links to SuperNOVAS related content online:
<a name="compatibility"></a>
## Compatibility with NOVAS C 3.1

SuperNOVAS strives to maintain API compatibility with the upstream NOVAS C 3.1 library, but not binary
compatibility. In practical terms it means that you cannot simply drop-in replace your compiled objects (e.g.
`novas.o`), or the static (e.g. `novas.a`) or shared (e.g. `novas.so`) libraries, from NOVAS C 3.1 with that from
SuperNOVAS. Instead, you will need to (re)compile and or (re)link your application with the SuperNOVAS versions of
these.
SuperNOVAS strives to maintain API compatibility with the upstream NOVAS C 3.1 library, but not binary compatibility.
In practical terms it means that you cannot simply drop-in replace your compiled objects (e.g. `novas.o`), or the
static (e.g. `novas.a`) or shared (e.g. `novas.so`) libraries, from NOVAS C 3.1 with that from SuperNOVAS. Instead,
you will need to (re)compile and or (re)link your application with the SuperNOVAS versions of these.

This is because some function signatures have changed, e.g. to use an `enum` argument instead of the nondescript
`short int` argument of NOVAS C 3.1, or because we added a return value to a function that was declared `void`
in NOVAS C 3.1. We also changed the `object` structure to contain a `long` ID number instead of `short` to
accommodate JPL NAIF codes, and for which 16-bit storage is insufficient.
`short int` argument of NOVAS C 3.1, or because we added a return value to a function that was declared `void` in
NOVAS C 3.1. We also changed the `object` structure to contain a `long` ID number instead of `short` to accommodate
JPL NAIF codes, and for which 16-bit storage is insufficient.

-----------------------------------------------------------------------------

Expand All @@ -119,8 +118,8 @@ accommodate JPL NAIF codes, and for which 16-bit storage is insufficient.
The SuperNOVAS library fixes a number of outstanding issues with NOVAS C 3.1. Here is a list of issues and fixes
provided by SuperNOVAS over the upstream NOVAS C 3.1 code:

- Fixes the [sidereal_time bug](https://aa.usno.navy.mil/software/novas_faq), whereby the `sidereal_time()`
function had an incorrect unit cast. This is a known issue of NOVAS C 3.1.
- Fixes the [sidereal_time bug](https://aa.usno.navy.mil/software/novas_faq), whereby the `sidereal_time()` function
had an incorrect unit cast. This is a known issue of NOVAS C 3.1.

- Fixes the [ephem_close bug](https://aa.usno.navy.mil/software/novas_faq), whereby `ephem_close()` in
`ephem_manager.c` did not reset the `EPHFILE` pointer to NULL. This is a known issue of NOVAS C 3.1.
Expand All @@ -131,10 +130,10 @@ provided by SuperNOVAS over the upstream NOVAS C 3.1 code:
positions, but not for velocities or distances, resulting in incorrect observed radial velocities or apparent
distances being reported for spectroscopic observations or for angular-physical size conversions.

- The use of `fmod()` in NOVAS C 3.1 led to the wrong results when the numerator was negative and the result was
not turned into a proper remainder. This affected the calculation of the mean anomaly in `solsys3.c` (line 261)
and the fundamental arguments calculated in `fund_args()` and `ee_ct()` for dates prior to J2000. Less
critically, it also was the reason `cal_date()` did not work for negative JD values.
- The use of `fmod()` in NOVAS C 3.1 led to the wrong results when the numerator was negative and the result was not
turned into a proper remainder. This affected the calculation of the mean anomaly in `solsys3.c` (line 261) and the
fundamental arguments calculated in `fund_args()` and `ee_ct()` for dates prior to J2000. Less critically, it also
was the reason `cal_date()` did not work for negative JD values.

- Fixes bug in `ira_equinox()` which may return the result for the wrong type of equinox (mean vs. true) if the the
`equinox` argument was changing from 1 to 0, and back to 1 again with the date being held the same. This affected
Expand All @@ -149,14 +148,14 @@ provided by SuperNOVAS over the upstream NOVAS C 3.1 code:

- Fix bug in `equ2ecl_vec()` and `ecl2equ_vec()` whereby a query with `coord_sys = 2` (GCRS) has overwritten the
cached mean obliquity value for `coord_sys = 0` (mean equinox of date). As a result, a subsequent call with
`coord_sys = 0` and the same date as before would return the results GCRS coordinates instead of the
requested mean equinox of date coordinates.
`coord_sys = 0` and the same date as before would return the results GCRS coordinates instead of the requested mean
equinox of date coordinates.

- Fixes `aberration()` returning NaN vectors if the `ve` argument is 0. It now returns the unmodified input
vector appropriately instead.
- Fixes `aberration()` returning NaN vectors if the `ve` argument is 0. It now returns the unmodified input vector
appropriately instead.

- Fixes unpopulated `az` output value in `equ2hor` at zenith. While any azimuth is acceptable really, it results
in irreproducible behavior. Hence, we set az to 0.0 for zenith to be consistent.
- Fixes unpopulated `az` output value in `equ2hor` at zenith. While any azimuth is acceptable really, it results in
irreproducible behavior. Hence, we set az to 0.0 for zenith to be consistent.

- Fixes potential string overflows and eliminates associated compiler warnings.

Expand All @@ -166,11 +165,9 @@ provided by SuperNOVAS over the upstream NOVAS C 3.1 code:
## Building and installation


The SuperNOVAS distribution contains a `Makefile` for GNU make, which is suitable for compiling the library (as well
as local documentation, and tests, etc.) on POSIX systems such as Linux, BSD, MacOS X, or Cygwin or WSL. (At this
point we do not provide a similar native build setup for Windows, but speak up if you would like to add it
yourself!)

The SuperNOVAS distribution contains a GNU `Makefile`, which is suitable for compiling the library (as well as local
documentation, and tests, etc.) on POSIX systems such as Linux, BSD, MacOS X, or Cygwin or WSL. (At this point we do
not provide a similar native build setup for Windows, but speak up if you would like to add it yourself!)

Before compiling the library take a look a `config.mk` and edit it as necessary for your needs, such as:

Expand Down

0 comments on commit 5577378

Please sign in to comment.