I added unit tests for the new interpolation functions.
This required making the functions public and documenting them.
Limited the interpolator's maximum time span to 8 days,
to keep the measured error reasonably small.
Optimize the C search algorithm by using quadratic
interpolation of the nutation angles `psi` end `eps`
when the scalar function has calculated them for
the bracketing times.
SearchPerformance times went from 36.955 seconds
down to 32.659 seconds.
This is the first step toward an optimization idea I want to try.
Pass times to the callback functions by address, so if they
happen to calculate earth tilt and/or sidereal time, Search
can interpolate new values in between.
Backported fixes to the Seasons functions in
C, C#, Python, and JavaScript. They were failing
to find equinoxes and/or solstices for distant
year values.
Also brought over some other minor code cleanup.
There were a few more places where C# code called
Search() but did not check for a search failure.
Throw InternalError exceptions if these ever occur,
because these particular searches should always succeed.
Added an InternalError class to explicitly indicate
that an exception occurs due to an internal assertion
failure inside Astronomy Engine. Any InternalError
should be considered a bug in Astronomy Engine, not
a bug in calling code.
Upon reviewing the code for searching moon phases,
I discovered that there was inconsistent behavior
in SearchMoonPhase. It was sometimes returning null,
other times throwing an exception. Because the caller
passes in `limitDays`, it makes sense to simply
return `null` in any case where the search fails.
This is to support callers that intentionally want
to find whether or not a moon phase occurs in a given
small window of time.
Updated internal callers of SearchMoonPhase to throw
an InternalError when they know they should always
find an event.
Internal function FindSeasonChange did not check to
make sure SearchSunLongitude succeeded. There is no
known case where this failure happens, but if it did,
a null AstroTime would have been stored in SeasonsInfo.
It is better to fail early with an explicit InternalError.
Other miscellaneous C# code cleanup.
In the Python code, I found a couple of `raise Error`
that needed to be changed to `raise InternalError`.
While working on the Kotlin implementation, I have
found a few documentation mistakes in the other language
implementations. These have been accumulating in the
`kotlin` branch. I migrated these changes back into
the released code for now, because I don't want to wait
until Kotlin is ready.
Defined consistent __repr__ methods for
Astronomy Engine Python classes.
Each string representation is reversible:
eval(repr(x)) -> x
The main goal is to facilitate interactive
debugging and experimentation for developers
working directly in the Python interpreter.
Fixed documentation mistakes in the following classes:
IlluminationInfo
LunarEclipseInfo
Generate astronomy.py directly in the package directory.
I realized it doesn't make sense to generate it in the
parent directory and then copy it; just generate it where
it will end up anyway.
Updated documentation so people know they can just do
pip install astronomy-engine
to install Astronomy Engine in their Python project.
Removed the GitHub Actions status badge because it is redundant with
the checkmark/X indicator.
Now that private symbols are no longer exported, I had to
fix a couple of places where the unit tests still accessed them.
I realized that the way I structured the pip package
in version 2.0.15 made the private symbols (those whose
names begin with an underscore) to be visible by the importer.
I reworked the package structure so this no longer happens.
This is now fixed in:
https://pypi.org/project/astronomy-engine/2.0.16/
The pip package was broken!
I violated ancient software development wisdom:
"If you haven't tested it, it doesn't work."
It is now working in:
https://pypi.org/project/astronomy-engine/2.0.15/
Version 2.0.15 of Astronomy Engine for Python (pip)
and Node.js (npm) add support for the new SiderealTime
function. This was previously an internal function,
but now it is exposed for outside callers.
There was already an internal function for calculating
Greenwich Apparent Sidereal Time (GAST). By request,
I have exposed this function for outside users.
Added a minimal unit test to verify the function is
callable and returns the correct result for one case.
This function is already exhaustively tested by unit
tests that verify other functions that already called
this function when it was internal, so minimal testing
is sufficient in this case.
The way I was publishing the Python package was annoying.
I found a better way to authenticate myself to pypi.org,
but I needed to test it. This required bumping the version
numbers of the packages. There is no difference between
2.0.12 and 2.0.13.
Added the following new functions to all 4 languages:
MassProduct: find the GM product for all Solar System bodies.
LagrangePoint: calculate L1..L5 state vectors for a pair of bodies.
LagrangePointFast: calculate L1..L5 state vectors given
state vectors and GM products of a pair of bodies.
In languages that support it, using hypot(x,y) is a little
easier to read than sqrt(x*x + y*y). Some documentation
(e.g. the man page for the C function) leads me to believe
hypot might also be better behaved than sqrt in some cases.
The JavaScript Math.hypot() is especially nice because it works
for any number of dimensions, so I can use it in 2D and 3D cases.
C only allows 2D usage, as does Python 3.7. Python 3.8 added
support for any number of dimensions, but I don't want to break
compatibility with Python 3.7 just yet. Therefore, in C and Python,
I am only using hypot for 2D cases.
C# does not appear to have any kind of hypot function,
so no changes were made to the C# code.
Thanks to https://github.com/ebraminio for this suggestion.
There is no function double.IsFinite() in .NET Framework.
Reworked the sanity check in Astronomy.Pivot so the C# code
builds in these older .NET platforms.
My custom Markdown documentation generator for C had
a bug when emitting the listing of a #define.
It is not valid to try to hyperlink to other symbols,
because the Markdown syntax gets listed literally inside
the context of a C code block.
In most cases, people calculating Lagrange points will just
want to pass in the bodies and not have to worry about calculating
their state vectors and masses.
Renamed Astronomy_LagrangePoint to Astronomy_LagrangePointFast.
Added new function Astronomy_LagrangePoint that accepts body enum
values instead of state vectors and masses. It knows to optimize
the precision of the calculation by calling GeoMoonState for the
Earth/Moon case.
It is conceptually simpler to take cross products to
generate 3 coordinate axes (essentially a rotation matrix)
that represent radial, tangential, and normal directions
with respect to the major and minor bodies.
Now correctly calculating L4 and L5 positions, but
there is a large error in their velocity vectors.
Refactored ctest.c LagrangeTest() to be a lot easier
to understand and modify. A new function VerifyStateLagrange()
allows passing test parameters in a more function-oriented way.
Confirmed that L4 and L5 always lie in the same plane with
the position vector and velocity vector.
Use the formulas I already had to calculate first
approximations for L1, L2, L3 distances.
Then use Newton's Method to home in on the positions
where centrifugal acceleration balances with net
gravitational acceleration.
I realized there was a small mistake in how I was
calculating the distance scaling factor for L1 and L2.
It was relative to the distance between the minor body
and the barycenter, not the minor body and the major body.
This significantly improves the accuracy for Earth/Moon
Lagrange points, but still has more error compared
to JPL Horizons than I currently understand.
The Microsoft C compiler is oddly picky about declaring a const variable.
Apparently it cannot do math with other const variables in its
initializer expression, unlike other C compilers.
So I had to change MOON_GM from a const to a #define.
The Lagrange point calculation is still not finished,
but L1 and L2 are working. L3 is probably correct, but there
is no test data for it.
I replaced the test data with new JPL Horizons output that
is centered on the primary body instead of the Solar System Barycenter.
This allows Astronomy_LagrangePoint() to be agnostic about
the coordinate systems of the state vectors handed to it.
I still need to get L4 and L5 calculations to match JPL Horizons
data, but it is not yet clear how to do that.
Python and npm package version: 2.0.11.
Finished implementing new functions across all
supported languages:
EclipticGeoMoon
Calculate the Moon's ecliptic geocentric position
in angular coordinates. The ecliptic longitude is
measured with respect to the mean equinox of date.
SearchMoonNode
NextMoonNode
A pair of functions to search for consecutive occurrences
of the Moon's center passing through the ecliptic plane.
Implemented a pair of C functions for finding a series of
Moon nodes:
Astronomy_SearchMoonNode
Astronomy_NextMoonNode
Finished the C unit test "moon_nodes" that verifies
my calculations against Fred Espenak's test data.
This is a thin wrapper function for the internal
function CalcMoon, which has already been extensively
validated. It will enable outside users to search
for ascending and descending nodes of the Moon,
or to calculate ecliptic spherical coordinates for the Moon
for any other useful purpose.
Changed the documentation for the GeoMoon and GeoMoonState
functions to make it explicit that they calculate coordinates
oriented with respect to the Earth's J2000 equator (EQJ).
This is because I will soon add ecliptic (ECL) counterparts
for the GeoMoon function, to more directly search for ascending
and descending nodes of the Moon.
See this discussion:
https://github.com/cosinekitty/astronomy/issues/150
For the case of calculating a map, where each pixel
on the map represents a different location on the Earth,
it is more efficient to factor out expensive calculation
of sidereal times, assuming the entire map represents
some phenomenon at a single moment in time.
For example, to determine whether the Moon is visible
at different places on the Earth, the following
functions can be calculated across thousands of
different (lat, lon) geographic coordinates around
the world:
ObserverVector
Rotation_EQD_HOR
Before iterating over the map pixels, a program
can call GeoMoon, then convert EQJ coordinates to EQD.
Then by passing the same time value in a loop to
ObserverVector and Rotation_EQD_HOR, the program
can calculate a vector from the observer to the Moon
in EQD coordinates, then convert EQD to HOR.
The z-coordinate of the horizontal coordinates
determines whether the Moon is above or below the
observer's horizon at that point on the Earth.
This calculation pattern performed redundant
sidereal time calculations for each pixel on the map.
I changed the code for all 4 languages to cache
sidereal time so that it only needs to be calculated
once.
In the C version of Astronomy Engine, this resulted
in a speedup factor of about 2.3 in the above use case.
(See the function MapPerformanceTest in generate/ctest.c.)
Reduce the number of redundant Earth nutation calculations
by passing astro_time_t values as pointers in more functions.
Nutation values can then be cached in the time parameter
and passed to other functions that can then avoid calculating
the same nutation again.
Nutation is an expensive calculation, so reducing this overhead
can dramatically speed up certain use cases.
This was only needed in C, because this is the only language
in which times are passed by value. In Python, C#, and JavaScript,
times are objects that are already passed by reference, and
they already benefit from this nutation recyling approach.
The following functions have had their parameters changed.
This is a breaking change, but in every case, the caller
usually just needs to change `time` to `&time`.
Astronomy_Rotation_EQD_EQJ
Astronomy_Rotation_EQD_ECL
Astronomy_Rotation_EQD_HOR
Astronomy_Rotation_EQJ_EQD
Astronomy_Rotation_EQJ_HOR
Astronomy_Rotation_ECL_EQD
Astronomy_Rotation_ECL_HOR
Astronomy_Rotation_HOR_EQD
Astronomy_Rotation_HOR_EQJ
Astronomy_Rotation_HOR_ECL
Astronomy_RotationAxis
Astronomy_VectorObserver
Thanks to ebrominio, I was able to create a pip
package for Astronomy Engine. See:
https://pypi.org/project/astronomy-engine/1.0.1/
I will probably need to go back and keep the version
numbers in sync with the matching npm package.
The code generator was creating slightly different numeric
values for the Pluto state tables and the Jupiter rotation matrix.
I decreased the output precision by one decimal digit.
This should allow the code generator to produce identical
source code on both Linux and macOS.
More work getting MacOS build process to work.
Avoid excessive number of floating point digits of
output in the demo tests, so that insignificant
floating point variations don't cause unit test failures.
