libiers10++

C++ library implementing the IERS 2010 standards.

Table of Contents

1. Introduction
2. Prerequisites
3. Compilation / Installation
4. Data Files
5. BLQ format files
6. Status of the Library (or translated routines)
7. Available functions/models not part of the IERS 2010 Conventions
8. Test Cases & FORTRAN vs C++ implementations
9. Test Programs (optional read)
10. How to use the library
11. Documentation & Library API (TODO)
12. TODO
13. Bugs & Maintanance

Introduction

This project contains a number of functions implementing models defined in IERS Conventions (2010) as described in ¹. The International Earth Rotation and Reference Systems Service (IERS) publishes the Conventions along with relevant documents, model implementations and respective test cases; the latter two are available in the FORTRAN programming language at the IERS website.

This repository is an effort to translate the algorithms in the C++ programming language with (as much as possible) minor modifications. Note that the software found at this website is routinely updated.

Prerequisites

The C++ library ggdatetime is used in the library to handle datetime instances when needed. Hence, you should have ggdatetime on your system.

The C++ library ggeodesy is used to handle basic geodesy when needed. Again, you should have the library installed (on your system) to successefuly compile this library.

Vector/Matrix operations are implemented using the eigen3 library. Availability of this library is also mandatory.

Compilation / Installation

January 2022: From now on, only the scons build will be supported; support for autotools is dropped.

The project is built via the scons built system:

$> git clone https://github.com/xanthospap/iers2010.git && cd iers2010
$> scons
$> sudo scons install

Test Programs

To compile the test utilities, use the make-test switch (i.e. scons make-test=1). Note that the SOFA ² library is needed to compile and run the tests.

Library Components

Notes on Dates and Datetimes

This library makes use of ggdatetime for handling dates and datetime instances. By default, this means that we are (mostly) handling datetimes in the so-called Modified Julian Date format, instead of the Julian Date format used throughout most of the SOFA ² functions.

Astronomy Functionality and Celestial Frames

The library contains a list of functions for basic astronomical computations, especially related to computations involved in transforming from/to the Geocentric Celestial Reference Frame (GCRF). Declerations can be found in the header files iau.hpp and fundarg.hpp.

There are a number of ways to transform between (geocentric) inertial and earth-fixed frames; in this library, we target the so called "CIO-based" transformation, based on the IAU 200/2006 model (see ² and ¹), as this is the recommended approach as described in the IERS2010 standards.

Tests and Compliance with IAU/SOFA

Once you have compiled the test-suite, you can use the script run_sofa_checks.py to check the compliance with respect to the IAU SOFA library (e.g. run_sofa_checks.py --progs-dir test/sofa_unit_tests/). This will run a number of checks and provide discrepancies (w.r.t. SOFA) for all functions/parameters common to both libraries. Explicit results can be found in this table.

Checking Descripancies

Descripancies for angular parameters are usually checked in units of arcseconds. Descripancies for rotation matrices (.e.g. $R_A$ and $R_B$) are obtained by the axis-angle of the combined matrix as: $\theta = arccos(\frac{(R_A^T R_B) -1}{2})$ again transformed in arcseconds.

Result Key-Points

• Discrepancies between the SOFA implementation and libiers2010 for one day of GRACE orbit are presented in ??. They ammount up to $\approx 1\times10^{-4} mm$ for the $X$ and $Y$ components and $\approx 2\times10^{-6} mm$ for $Z$. See results here

• The accuracy of the transformation is presented in presented in ??. It is $\approx 5\times10^{-6} mm$ for each of the $X$, $Y$ and $Z$ components.(Note that this is checked again using one day of GRACE orbit, and performing the circular transformation ICRF->ITRF->ICRF). See results here

Tests and Compliance with IERS Implementation

Once you have compiled the test-suite, you can use the script run_fortran_checks.py to check the compliance of the current library against the FORTRAN subroutines distributed by the IERS. Example run:

$>./run_fortran_checks.py --for-dir fortran_impl/ \
    --cpp-dir test/fortran_unit_tests/ \
    --verbose

To run these unit tests however, you will need to have downloaded the IERS-distributed source code accompanying the standards. Explicit results can be found in this table.

Computation of GMST

In this implementation computation of GMST is performed using the IAU2006 model, i.e. using both UT1 and TT (see Sec. 5.5.7, ERA based expressions for Greenwich Sidereal Time). Contrary to this, some IERS-distributed FORTRAN subroutines use an older model for GMST (i.e. FCNNUT, PMSDNUT2).

References

Acknowledgement

Software Routines from the IAU SOFA Collection were used. Copyright © International Astronomical Union Standards of Fundamental Astronomy (http://www.iausofa.org)

Results

Discrepancies w.r.t IERS/FORTRAN

subroutine/function	discrepancies
fcnnut	dX=+0.0e+00 dY=+0.0e+00 dsX=+0.0e+00 dsY=+8.1e+02 [μasec]

Discrepancies w.r.t IAU/SOFA

function	argument	num tests	num fails	max error	param. type	status
nut00a	dpsi	100000	49547	-1e-09	Angle	FAILED
nut00a	deps	100000	48587	-5e-10	Angle	FAILED
pom00		100000	0	+0e+00	RotMatrix	OK
s00		100000	0	+0e+00	Angle	OK
pn00a	dpsi	100000	49608	-1e-09	Angle	FAILED
pn00a	deps	100000	48552	-5e-10	Angle	FAILED
pn00a	epsa	100000	0	+0e+00	Angle	OK
pn00a	rb	100000	0	+0e+00	RotMatrix	OK
pn00a	rp	100000	17847	+8e+00	RotMatrix	FAILED
pn00a	rbp	100000	20450	+8e+00	RotMatrix	FAILED
pn00a	rn	100000	54116	+6e+00	RotMatrix	FAILED
pn00a	rbpn	100000	36303	+9e+00	RotMatrix	FAILED
ter2cel	dX	2880	0	-1e-04	linear	-
ter2cel	dY	2880	0	-1e-04	linear	-
ter2cel	dZ	2880	0	-2e-06	linear	-
ter2cel	ds	2880	0	+2e-04	linear	-
ter2cel	dR	2880	0	+7e-03	RotMatrix	-
num06a		100000	43065	+6e+00	RotMatrix	FAILED
bi00	dpsibi	100000	0	+0e+00	Angle	OK
bi00	depsbi	100000	0	+0e+00	Angle	OK
bi00	dra	100000	0	+0e+00	Angle	OK
c2ixys		1000000	0	+0e+00	RotMatrix	OK
pnm06a		100000	44426	+8e+00	RotMatrix	FAILED
bp00	rb	100000	0	+0e+00	RotMatrix	OK
bp00	rp	100000	17721	+8e+00	RotMatrix	FAILED
bp00	rbp	100000	20152	+8e+00	RotMatrix	FAILED
fapa03	fapa03	100000	0	+0e+00	Angle	OK
fane03	fane03	100000	0	+0e+00	Angle	OK
faur03	faur03	100000	0	+0e+00	Angle	OK
fasa03	fasa03	100000	0	+0e+00	Angle	OK
faju03	faju03	100000	0	+0e+00	Angle	OK
fama03	fama03	100000	0	+0e+00	Angle	OK
fae03	fae03	100000	0	+0e+00	Angle	OK
fave03	fave03	100000	0	+0e+00	Angle	OK
fame03	fame03	100000	0	+0e+00	Angle	OK
faom03	faom03	100000	0	+0e+00	Angle	OK
fad03	fad03	100000	0	+0e+00	Angle	OK
faf03	faf03	100000	0	+0e+00	Angle	OK
falp03	falp03	100000	0	+0e+00	Angle	OK
fal03	fal03	100000	0	+0e+00	Angle	OK
fw2m		100000	0	+0e+00	Angle	OK
ee06a	ee06a	100000	62476	+2e-07	Angle	FAILED
gmst06	gmst06	100000	52212	+1e-05	Angle	FAILED
gmst00	gmst00	100000	51991	+1e-05	Angle	FAILED
gst06a	gst06a	100000	51979	+1e-05	Angle	FAILED
obl06	obl06	100000	1	+2e-08	Angle	FAILED
obl80	obl80	100000	1	+2e-08	Angle	FAILED
ee00	ee00	100000	0	+0e+00	Angle	OK
eect00	eect00	100000	25533	+2e-14	Angle	FAILED
sp00	sp00	100000	7928	+5e-18	Angle	FAILED
era00		100000	52066	+1e-05	Angle	FAILED
xy06	xp	10000	1598	-6e-10	Angle	FAILED
xy06	yp	10000	3298	-5e-10	Angle	FAILED
nut06a	dpsi	10000	4987	+1e-09	Angle	FAILED
nut06a	deps	10000	4914	-5e-10	Angle	FAILED
c2i06a		10000	5422	+6e+00	RotMatrix	FAILED
pn00	rb	10000	0	+0e+00	RotMatrix	OK
pn00	rp	10000	1751	+8e+00	RotMatrix	FAILED
pn00	rbp	10000	2003	+8e+00	RotMatrix	FAILED
pn00	rn	10000	0	+0e+00	RotMatrix	OK
pn00	rbpn	10000	482	+8e+00	RotMatrix	FAILED
pn00	epsa	10000	0	+0e+00	Angle	OK
numat		10000	0	+0e+00	RotMatrix	OK
pr00	dpsipr	10000	587	-2e-14	Angle	FAILED
pr00	depspr	10000	116	+3e-15	Angle	FAILED
pfw06	gamb	10000	906	-1e-12	Angle	FAILED
pfw06	phib	10000	0	+0e+00	Angle	OK
pfw06	psib	10000	838	+5e-10	Angle	FAILED
pfw06	epsa	10000	0	+0e+00	Angle	OK
pn06	rb	10000	10000	+6e+00	RotMatrix	FAILED
pn06	rp	10000	9999	+9e+00	RotMatrix	FAILED
pn06	rbp	10000	3810	+6e+00	RotMatrix	FAILED
pn06	rn	10000	1277	+9e+00	RotMatrix	FAILED
pn06	rbpn	10000	1359	+6e+00	RotMatrix	FAILED
pn06	epsa	10000	0	+0e+00	Angle	OK
p06e	eps0	100000	0	+0e+00	Angle	OK
p06e	psia	100000	8588	-7e-10	Angle	FAILED
p06e	oma	100000	0	+0e+00	Angle	OK
p06e	bpa	100000	7070	-7e-13	Angle	FAILED
p06e	bqa	100000	8407	+6e-12	Angle	FAILED
p06e	pia	100000	8483	-6e-12	Angle	FAILED
p06e	bpia	100000	0	+0e+00	Angle	OK
p06e	epsa	100000	0	+0e+00	Angle	OK
p06e	chia	100000	8714	-1e-12	Angle	FAILED
p06e	za	100000	7992	-3e-10	Angle	FAILED
p06e	zetaa	100000	8095	-4e-10	Angle	FAILED
p06e	thetaa	100000	6445	+2e-10	Angle	FAILED
p06e	pa	100000	8622	+7e-10	Angle	FAILED
p06e	gam	100000	8926	-1e-12	Angle	FAILED
p06e	phi	100000	0	+0e+00	Angle	OK
p06e	psi	100000	8470	+7e-10	Angle	FAILED
c2t06a		10000	6647	+8e+00	RotMatrix	FAILED
xys06a	xp	10000	2023	+6e-10	Angle	FAILED
xys06a	yp	10000	2484	+2e-08	Angle	FAILED
xys06a	s	10000	4417	-3e-11	Angle	FAILED
xys00a	xp	10000	2429	+6e-10	Angle	FAILED
xys00a	yp	10000	446	+2e-08	Angle	FAILED
xys00a	s	10000	3396	-3e-11	Angle	FAILED
s06		100000	0	+0e+00	Angle	OK
internal_ter2cel	dX	2880	0	-4e-06	linear	-
internal_ter2cel	dY	2880	0	-4e-06	linear	-
internal_ter2cel	dZ	2880	0	+4e-06	linear	-
internal_ter2cel	ds	2880	0	+5e-06	linear	-
internal_ter2celIau	dX	2880	0	-4e-06	linear	-
internal_ter2celIau	dY	2880	0	+5e-06	linear	-
internal_ter2celIau	dZ	2880	0	-3e-06	linear	-
internal_ter2celIau	ds	2880	0	+5e-06	linear	-

Footnotes

1. Gérard Petit and Brian J. Luzum, editors. IERS Conventions (2010), volume 36 of IERS Technical Note, 2010. International Earth Rotation and Reference Systems Service (IERS), International Earth Rotation and Reference Systems Service (IERS). ↩ ↩²

2. International Astronomical Union, Standards of Fundamental Astronomy (SOFA) software tools collection, available at [https://www.iausofa.org/] ↩ ↩² ↩³