SofaJpl Fundamental Astronomy DLL for .NET


SofaJpl is a positional astronomy DLL to assist Windows .NET Framework applications with computation of celestial body positions. In my tests, the reduction to apparent place examples in The Astronomical Almanac are duplicated within one digit in the last place. Because it complies with the CLS (Common Language Specification), SofaJpl is equally accessible from all .NET Framework languages. SofaJpl was developed primarily for my personal use, but anyone may use it for free. See the license terms at the bottom of this page.

SofaJpl components:

SofaJpl can convert between time scales TT, UTC, UT1, TDB, TAI, TCG, TCB, GPS, sidereal time, and apparent solar time. The leap second table is a text file and easy to update by hand. There will be no difficulty if leap seconds are discontinued. Available solar system bodies are the planets (including Pluto), Sun, and Moon. In addition to the bright star catalog previously mentioned, catalog parameters for any star may be entered by the user.

SofaJpl computes geometric places of those bodies with respect to the ICRS and the barycenter, heliocenter, geocenter, and topocenter. For the latter two origins, astrometric and apparent place are available too. SofaJpl can convert between any of these coordinate systems: ICRS, J2000 (including frame bias with respect to the ICRS), mean or true equator and equinox, ecliptic and mean or true equinox, celestial intermediate (equator and CIO), terrestrial intermediate (equator and TIO), ITRS (including polar motion), and horizontal (including polar motion and deflection of the vertical).

Download and Installation

SofaJpl 2.1.2 is distributed as a 259 k .zip file. To install, download the file and extract the .zip into any convenient location. By default, when you do "Extract all" the .zip creates a new subdirectory named SofaJpl_2_1_2 within the directory that contains the .zip.. Impact on your system is minimal since there are no changes to the desktop, registry, etc.

I have provided an example program with source code in the C++, C#, and Visual Basic languages to demonstrate SofaJpl. It can be compiled and executed under Microsoft's Visual Studio integrated development environment. I use the free Visual Studio Express 2013 (probably no longer available) to develop and test SofaJpl. (The free version is now called Visual Studio Community.)

The programs create a JPL binary ephemeris from an ASCII ephemeris and a header file. The names of the input and output files are near the beginning of the demonstration program source code and may be changed easily. A page at JPL describes the available ephemerides. From their FTP site, download an ASCII ephemeris applicable to the time of interest. (Be careful with the sign of the year. An m in the filename means minus and a p means plus. For example, ascm2000.406 is for years -2000 through -1001 inclusive, and ascp2000.406 is for years +2000 through +2099 inclusive.) Also download the matching header for the ephemeris, e.g., header.406. The files may be stored in any convenient place.

Recent JPL ephemerides have a table of constants too large for some software. At the download site these ephemerides are available in an alternate version with an abbreviated table of constants. However, these are unnecessary with SofaJpl. Its unique binary file format has a dynamically sized table, so there's no limit to its size.

After downloading the ASCII ephemeris files you are ready to compile and run the C++, C#, or Visual Basic demonstration program. All are identical except for the language. To make the example simple, the program doesn't interact with you. Time, location, and the celestial body are set in the source code. It simply runs the calculations and displays results in a console window.

To deploy (including to your own system) an application which uses SofaJpl, put the three .dll files (from the SofaJpl folder) in the same folder as your executable. If it uses the star catalog, include the two .vot files too. If it uses the Utc or UtcTable class, a leap second table must be on the system but may be located anywhere. A current table is included in the SofaJpl installation. I recommend only one leap second file, shared by all programs, so there's only one file to update when a leap second occurs.

To uninstall SofaJpl, simply delete its directory. This won't affect any applications that use SofaJpl, since they have their own copies of the files.

Current Version, Notes, and Bugs


In Visual Studio, after a reference to SofaJpl has been set up as explained in the demonstration program instructions, click View, Object Browser. Expand the HirosePS . SofaJpl namespace to view the documentation. Expand the SofaClr namespace to view the documentation for the adapters that provide a .NET interface for the IAU SOFA collection. SofaJpl has all the facilities normally needed, but SofaClr is also provided for more direct access to the SOFA routines.

All routines that take a UTC parameter have been excluded from SofaClr.dll. That's due to SOFA's decision to embed the leap second table in executable code, thereby requiring SofaJpl to be rebuilt and re-released every time there's a leap second. Recently the SOFA prohibiton on modification to the code has been relaxed to allow an external leap second table. However, I have not implemented that. Since all SOFA routines that take a UTC parameter have an equivalent that takes UT1 and TT instead, and SofaJpl will convert UTC to the latter two time scales, you still have access to all SOFA capabilities.

In addition, the third DLL in the SofaJpl package, SofaWin32.dll, contains the SOFA collection with nothing omitted. The problem is that this is a Win32 DLL, so "data marshalling" is necessary to call it from a .NET language. This syntax may be seen in my source code for SofaClr.dll. Microsoft has extensive explanations online. For example, see Marshaling Data with Platform Invoke at MSDN.

Of course source code is the ultimate documentation. Here are .zip files with the C# source code for SofaJpl.dll and SofaClr.dll. The source code for SofaWin32.dll is identical to the C code at the SOFA site, except for small changes to compile as C++ under Visual Studio. (None of these files is guaranteed to be synchronized with the latest SofaJpl release.)

JPL Ephemerides

SofaJpl is compatible with DE102, DE200, DE202, DE403, DE405, DE406, DE410, DE413, DE414, DE418, DE421, DE422, DE423, DE430, DE431, and DE432. It will be compatible with subsequent ephemerides unless there are major changes to the ephemeris format. The binary ephemeris format is unique to SofaJpl and incompatible with the JPL format. That's not a factor unless you attempt to use the ephemeris with non-SofaJpl software.

Copyright, License, and Credits

SofaJpl is © 2018 by Paul S. Hirose. There is no fee or registration. However, I must receive credit in a place reasonably obvious to users. You may distribute the files with your product.

SofaJpl makes extensive calls to software routines from the IAU SOFA Collection, copyright © International Astronomical Union Standards of Fundamental Astronomy. Thus the SOFA Software License is applicable.

The star catalog and star designation table are mainly from the SIMBAD database, operated at CDS, Strasbourg, France.

[up one level]

(page last modified 2018-09-09)