Official release for #330

Another version bump to test a new npm package deployment. This should resolve warnings in npm publish, thanks to fixes in #330.

npm - Include types in package.json

This is an attempt to resolve a known problem in Astronomy Engine's npm package.
Added the TypeScript types file astronomy.d.ts as a type export from package.json.
See #329.

Rise/set search for observers above the ground

Rise/set times for observers above the ground

This release of Astronomy Engine supports searching for rise and set events of celestial bodies when the observer is a significant height above ground level, for example in a balloon or airplane. This causes the apparent horizon to dip below the observer's horizontal plane, which affects the timing of rise/set events. There is now an additional parameter to the SearchRiseSet functions called metersAboveGround. The observer parameter's height field is still the number of meters above mean sea level, but metersAboveGround tells how high the observer is with respect to an idealized flat ground level.

Atmosphere model

As part of this new capability, I had to calculate relative air densities at different elevations above mean sea level. This was needed for calculating refraction of light rays from the horizon toward the observer. As a by-product of this work, there is a new function Atmosphere that implements the U.S. Standard Atmosphere model of 1976. Atmosphere provides idealized air temperature, pressure, and density as a function of elevation.

Support for extreme year values, string helpers for C#.

Extreme year values

When converting Gregorian calendar dates to day values and back, I have been using an algorithm by Fliegel and Van Flandern that was published in October 1968. It is a wonderful formula because it doesn't use any conditional logic to handle all the leap year rules. Rather, it uses simple integer arithmetic to work in an almost magic way.

However, I recently discovered a few problems for extreme year values, especially years before 4317 BC, the Julian Day epoch. These caused the formulas to fail due to quirks of negative numbers in the calculations. I also had concerns about using 32-bit integers to do the calculations.

So I decided to write unit tests that require year values to work over a nearly 2-million year span: the range of years from −999999 to +999999. I did this for all languages except JavaScript, where I don't use Fliegel / Van Flandern formulas because the built-in type Date effortlessly supports years from −199999 to +199999:

> new Date('+199999-01-01T00:00:00Z')
+199999-01-01T00:00:00.000Z
> new Date('-199999-01-01T00:00:00Z')
-199999-01-01T00:00:00.000Z

Then I worked until I got all the tests to pass. This work mainly consisted of

• Adjusting Fliegel / Van Flandern to avoid negative values over the wider year range.
• In other parts of the code, handling Python's different idea of integer division when numbers are negative. In Python, 10 // 3 == 3, but -10 // 3 == -4.
• In C, casting a floating point number to an integer causes it to be rounded toward zero, when I needed it to be rounded down, whether positive or negative. So I had to change (long)x to (long)floor(x).

Now all the languages except JavaScript have consistent logic for handling calendar dates that passes all the tests.

String helpers for C#

In the C# version of Astronomy Engine, I added ToString methods for the types AstroVector, StateVector, and Observer. These are not only helpful for easy printing of values, but are handy while using the debugger. Just hover your mouse over a variable and you can see what's in it!

I added TryParse functions for AstroTime and AstroVector to parse the string representations back into a time or vector.

Python type hints

This release adds type hints to the Python version of Astronomy Engine.

Type hints provide better documentation to developers about all the function parameter types and return values. They also enable static type-checking of the Python code using the mypy tool. The automated test suite now requires passing mypy --strict when each change is pushed to GitHub. This extra step will help maintain a high standard of code quality for future development. The intention is to prevent bugs before they happen, both inside Astronomy Engine and in code that uses it.

Many thanks to @ris-tlp for volunteering to help in this effort!

Hour Angle

This release of Astronomy Engine includes a new function HourAngle. It calculates the hour angle of a solar system body for a given geographic location at a given time.

This release also includes demo programs to calculate true solar time from the Sun's hour angle.

True ecliptic coordinates of date

True ecliptic coordinates of date

This release changes the Ecliptic functions to return true ecliptic coordinates of date instead of coordinates referenced to the mean equinox of J2000. This matters because ecliptic coordinates are often significant for physical phenomena such as eclipses, transits, lunar phases, etc.

So-called "true" coordinates correct for the following 3 variables in the orientation system:

• Large scale precession of the Earth's axis. This is a gyrating movement over a period of approximately 26000 years.
• Small scale nutation of the Earth's axis. This small wobbling movement has a primary periodic component of 18.6 years.
• Obliquity drift. This is a slow change of the angle between the Earth's orbital plane and the Earth's equatorial plane. Currently the angle between the planes is decreasing at a rate of 47 arcseconds per century.

By changing the Ecliptic functions to correct for these 3 variables, the results are a better fit for calculating phenomena that depend on them.

Support for calculating mean ecliptic coordinates in the J2000 system (represented by the three-letter code ECL) still exists in the form of rotation matrix functions:

• Rotation_ECL_EQD
• Rotation_ECL_EQJ
• Rotation_ECL_EQD
• Rotation_ECL_EQJ
• Rotation_ECL_HOR
• Rotation_HOR_ECL

New rotation matrix functions have been added to support true ecliptic coordinates of date, with the newly added three-letter code ECT:

• Rotation_ECT_EQD
• Rotation_ECT_EQJ
• Rotation_EQD_ECT
• Rotation_EQJ_ECT

Better documentation of coordinate systems

The API documentation has been updated to clearly specify whether equatorial coordinates or ecliptic coordinates are referenced to the true equinox (corrected for both precession and nutation) or the mean equinox (corrected for precession only).

More efficient nutation

Many calculations in Astronomy Engine require calculating nutation, as mentioned above. The nutation formula was excessively slow in earlier versions. It was using the full 77-term trigonometric series IAU2000B. This has been truncated to a 5-term series, and optimized via loop unrolling, across all 5 supported programming languages. The result is still accurate within 2 arcseconds while running more than 15 times as fast.

User-defined stars

Now you can define up to eight custom points in space that have a fixed heliocentric right ascension, declination, and distance. These are called user-defined stars, although they don't literally have to be stars. They can be any object that is more than one light-year away from the Sun.

To create a user-defined star, call the function for your language:

• C/C++: Astronomy_DefineStar.
• C#: Astronomy.DefineStar
• TypeScript/JavaScript: DefineStar
• Python: DefineStar
• Kotlin/Java: defineStar

Once you have associated a custom star with a Body value, you can pass that value to functions like SearchRiseSet, GeoVector, etc.

Fixed rise/set and altitude searches for polar regions

The functions for searching for rise/set events did not always work reliably in polar regions. It was possible to miss a sunrise, moonset, etc., within the arctic and antarctic circles. Geographic locations near the Earth's north pole or south pole have some unusual and counterintuitive properties regarding rise/set of celestial bodies.

For example, if you are standing on the north pole, the Sun rises only once per year (near the March equinox), and sets only once per year (near the September equinox). The Earth's rotation causes the Sun to move in circles all the way around the sky, but it Sun only moves toward or away from the horizon due to seasonal changes in its declination. At the poles, the Earth's rotation has absolutely no effect on how high/low the Sun appears to be in the sky.

As an observer moves away from the poles and towards the equator, the Earth's rotation starts to have more effect on the rise/set behavior of observed celestial bodies. The timing of rise/set becomes a combination of the observer's latitude, the rotation of the Earth, and the body's right ascension and declination.

This leads to some other interesting behavior. At latitude 85°N, there are times where the Moon will rise, stay partially visible for about 20 minutes, then set again. This brief appearance of the Moon was being skipped by Astronomy Engine. Now Astronomy Engine will find any such rapid rise-then-set or set-then-rise sequence that lasts for longer than 1 second.

In this release of Astronomy Engine, the rise/set logic has been completely overhauled to work reliably in all cases. I added new test data from the US Naval Observatory to cover cases in polar regions. Those test all pass now.

Expose planet orbital periods

This release adds a new function PlanetOrbitalPeriod that returns the average number of days it takes a planet to orbit the Sun. This number should be considered an approximation. First of all, the Sun is wobbling around the Solar System Barycenter because of gravitational pull from the major planets Jupiter, Saturn, Uranus, and Neptune. Therefore, the concept of the exact moment a planet finishes one orbit "around the Sun" is vague. Secondly, the planets are all pulling on each other, so their orbits do not have a fixed shape. This adds to the vagueness of the orbital period. However, some applications may benefit from this rough concept of orbital period.