Obscuration for solar and lunar eclipses

This release provides a new field obscuration in the data structures for lunar eclipses, global solar eclipses, and local solar eclipses. Obscuration is a floating point number that ranges from 0 to 1.

In a solar eclipse, obscuration is the fraction of the Sun's apparent disc area that is blocked from view by the Moon, as seen by the observer on the Earth. In a "global" solar eclipse calculation, the observer's location is given as the ideal location for the maximum eclipse. In a "local" solar eclipse calculation, the caller supplies the desired geographic location for the observer. The value of obscuration is 1 for a total eclipse, and somewhere between 0 and 1 for a partial or annular eclipse.

In a lunar eclipse, obscuration is the fraction of the Moon's apparent disc area that is covered by the Earth's umbra. The value is 1 for a total eclipse, and somewhere between 0 and 1 for a partial eclipse. The obscuration is 0 for penumbral lunar eclipses, because the Earth's umbra does not fall upon the Moon during them. Penumbral eclipses are very difficult to observe because they are faint and subtle, so no separate obscuration metric is reported for them.

Support calendar years outside 0000..9999.

Astronomy Engine now supports times outside the years 0000..9999, and supports formatting those times as ISO 8601 text. Times within the year range 0000..9999 are still formatted like this:

2022-10-06T22:37:45.891Z

Based on ISO 8601, and following the convention Node.js uses, dates outside the range 0000..9999 are now formatted with a leading prefix of - or +, followed by a 6-digit integer like

-001234-12-25T14:37:57.450Z
+043752-10-30T09:30:18.256Z

Reverse chronological search: moon phase and altitude

The following functions now allow searching backward or forward in time by passing in a negative or positive value for their limitDays parameter:

• SearchMoonPhase
• SearchRiseSet
• SearchAltitude

The following function has added a new integer parameter direction that can be passed a positive value to search forward in time, or a negative value to search backward in time:

• SearchHourAngle

To preserve backward compatibility, the C version of this function has been renamed SearchHourAngleEx, and SearchHourAngle is now a macro that expands to the equivalent call to SearchHourAngleEx with the extra argument +1.

In the other languages, which all support default parameter values, the direction parameter has a default value of +1, which preserves the original behavior of searching forward in time.

There were also minor fixes to SearchRiseSet and SearchAltitude where limitDays was not always strictly limiting the range of the search. Now, any time an altitude event is found that goes beyond limitDays, the search will fail as specified by the documentation.

Miscellaneous fixes to code and documentation.

What's Changed

• Resolve cyclic dependency of Body.vsopModel by @ebraminio in #242
• Prevent use of gcc "fast math" optimization in the C version, because it breaks things! See #245.
• Various minor fixes to Python documentation.
• Bump shell-quote from 1.7.2 to 1.7.3 in /generate by @dependabot in #232

Full Changelog: v2.1.2...v2.1.3

Generic light travel time correction

This release adds new functions CorrectLightTravel and BackdatePosition for enhanced ability to calculate apparent times and position vectors that are corrected for the amount of time it takes for light to travel from an observed body to an observer.

Added gravity simulator

The new gravity simulator feature allows defining an arbitrary list of small bodies such as asteroids, comets, or coasting spacecraft. The caller provides the position vectors and velocity vectors of the bodies at an initial time. Then the gravity simulator can step through small time increments and update the positions and velocities of the bodies as they are affected by the gravitational pull of the Sun and planets.

Support for Kotlin, Java, JVM

This is our first official release of Astronomy Engine that includes support for Kotlin and Java for the JVM. There are also a few minor enhancements and improvements in the other supported languages.

Special thanks to: @ebraminio, who helped me get the build environment set up, taught me lots of cool stuff about the Kotlin language, and provided numerous code reviews and extremely helpful feedback the whole time. His help made this project much faster and greatly improved the quality of the work.