user_guide.txt

---
title: libiers User's Guide
author:
  - name: xanthos
    affiliation: Dionysos Satellite Observatory, National Technical University of Athens
bibliography: doc/document/doris.bib
...

To compile this document into html, use:
```bash
$> pandoc user_guide.txt  [-s] --mathml --citeproc  -o doc/userguide.html 
# or
$> pandoc user_guide.txt [-s] --mathjax --citeproc  -o doc/userguide.html
```

# Introduction
This project contains a number of functions implementing models defined in
[IERS Conventions (2010)](https://www.iers.org/IERS/EN/Publications/TechnicalNotes/tn36.html/) 
as described in [@iers2010].
The International Earth Rotation and Reference Systems Service ([IERS](https://www.iers.org/IERS/EN/Home/home_node.html))
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](https://iers-conventions.obspm.fr/conventions_material.php).

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.

# Installation

Source code is ISO C++17. Compilation should be trivial using any C++ compiler
supporting the c++17 standard (option `-std=c++17` in [gcc](https://gcc.gnu.org/)
and [clang](https://clang.org/)).

## Prerequisites
The C++ library [ggdatetime](https://github.com/xanthospap/ggdatetime) 
is used in the library to handle datetime instances when needed. 
Hence, you should have [ggdatetime](https://github.com/xanthospap/ggdatetime) 
on your system.

The C++ library [ggeodesy](https://github.com/xanthospap/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](https://eigen.tuxfamily.org/index.php?title=Main_Page) 
library. Availability of this library is also mandatory.

## CSPICE
Interaction with planetary ephemeris files (i.e. JPL's published DE), is 
done via the [SPICE Toolkit](https://naif.jpl.nasa.gov/naif/toolkit.html). 
The toolkit is a C library with a corresponding API. 

### Installation

* Download the C library from the [correponding site](https://naif.jpl.nasa.gov/naif/toolkit_C.html) and uncompress.

* Use the script [c2cpp_header.py](script/cppspice/c2cpp_header.py) to tranform 
C header file. Run the script using the cspice `include` folder path as command 
line argument. I.e. if the uncompressed cspice folder is at `/home/work/var/cspice`, 
use `$> c2cpp_header.py /home/work/var/cspice`.

* Run the `makeall.csh` script provided by the distribution (under `cspice` folder). Note 
that the script is in the C-sheel, hence you might need to `$>csh makeall.csh`.

* Copy the [install.sh](script/cppspice/install.sh) script under the `cspicer` folder; 
run it as root, to install the library. Header files will be available at 
`/usr/local/include` and the library at `/usr/local/lib`.

## Compilation / Installation <a name="compilation-installation"></a>

> January 2022:
> From now on, only the [scons](https://scons.org/) build will be supported; 
> support for autotools is dropped.

The project is built via the [cmake](https://cmake.org/) built system:

```bash
$> git clone https://github.com/xanthospap/iers2010.git && cd iers2010
$> # step 1
$> cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=/usr/local/lib
$> # step 2
$> cmake --build build --target all --config=Release -- -j4
$> # step 3
$> cd build && sudo make install
```

### Build Options

#### Build in DEBUG mode

You can easily change to building the DEBUG version, e.g. changing 
Steps (1) and (2) to:
```
$> cmake -S . -B build -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Debug -DCMAKE_PREFIX_PATH=/usr/local/lib
$> cmake --build build --target all --config Debug -- -j4
```

#### Build COST-G Benchmark Test Binaries

Set the `BUILD_COSTG` option on, i.e. `cmake -S . -B build -G "Unix Makefiles" -DBUILD_COSTG=ON -DCMAKE_PREFIX_PATH=/usr/local/lib`. 
The (binary) programs will be placed at `build/costg-benchmark/bin/`

#### Build (Unit) Tests

Set the `BUILD_TESTING` option on, i.e. cmake -S . -B build -G "Unix Makefiles" -DBUILD_TESTING=ON -DCMAKE_PREFIX_PATH=/usr/local/lib`.
This will build the programs placed in the folders `test/unit_tests` and `test/should_not_compile`. 
Additionally, if the SOFA C library [@sofa2021] is available on your platform, then 
the programs placed in `test/sofa` will also be compiled.

# Library Components

## Notes on Dates and Datetimes
This library makes use of [ggdatetime](https://github.com/xanthospap/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 [@sofa2021] functions. 

## Earth Orientation Parameters (EOPs)
The library can parse EOP information from IERS files using the IERS C04/14 
(see [updateC04.txt](https://hpiers.obspm.fr/iers/eop/eopc04_14/updateC04.txt)) and 
IERS C04/20 (see [eopc04.txt](https://hpiers.obspm.fr/iers/eop/eopc04/eopc04.txt)) 
file formats/series. The files can be downloaded from IERS, e.g. 
[eopc04_IAU2000.62-now](https://hpiers.obspm.fr/iers/eop/eopc04_14/eopc04_IAU2000.62-now) 
and [eopc04.1962-now](https://hpiers.obspm.fr/iers/eop/eopc04/eopc04.1962-now).

Normally, EOP information is stored in an `EopSeries` instance, which can hold 
records for multiple epochs (ordered chronologically) and perform basic utilities 
such as interpolation.

Users can choose to "regularize" ΔUT1 and LOD values, i.e. remove zonal tidal 
variations with frequencies ranging from 5 days to 8.6 years from UT1 values 
(result typically denoted UT1R) and LOD (see Chapter 8.1 of [@iers2010] and [@Bradley2016]).

The most important and usual operation an `EopSeries` instance performs, is the 
interpolation of EOP values for an epoch of interest. This can be done with a 
simple call to `EopSeries::interpolate` method. Note that for utmost accuracy 
certain corrections will have to be applied to the resulting interpolated values, 
such as removal of libration and ocean tidal effects (see the example source code).

For a complete example of `EopSeries` usage, see [eop_interpolation.cpp](examples/eop_interpolation.cpp).

## Fundamental and Doodson Arguments

The expressions for the (lunisolar) **fundamental arguments** of nutation or 
**Delaunay variables** are taken from [@iers2010, chap. 5.7.2]. The fundamental 
arguments are:

  * Mean Anomaly of the Moon $F_1$ or $l$,
  * Mean Anomaly of the Sun $F_2$ or $l'$,
  * $L − \Omega$ $F_3$ or $F$,
  * Mean Elongation of the Moon from the Sun $F_4$ or $D$, and
  * Mean Longitude of the Ascending Node of the Moon $F_5$ or $\Omega$

For more information, see the header file [fundarg.hpp](https://github.com/xanthospap/iers2010/blob/cleanup/src/fundarg.hpp). 
Note that strictly speaking, to compute the arguments we should input time in 
TDB; it is usually more convenient though to use TT, which makes no significant 
difference (see [@iers2010, chap. 5.7.1]).

Another set of (astronomic) arguments that is oftenly used, mainly with tidal 
harmonics, are the **Doodson arguments**. These are:

  * $\tau$, Time angle in lunar days reckoned from lower transit,
  * $s$, Moon's mean longitude
  * $h$, Sun's mean longitude
  * $p$, Longitude of Moon's mean perigee
  * $N'$, Negative longitude of Moon's mean node
  * $p_l$ or $p_s$ ,Longitude of Sun's mean perigee

Formulae for computing the Doodson arguments from Delaunay variables, are 
given in [@iers1992, chap. 7, pg. 53-54] and are summarized below:

\begin{align*}
  \tau = \theta _g + \pi - s \\
  s = F + \Omega\\
  h = s - D\\
  p = s - l\\
  N' = - \Omega\\
  p_l = s - D - l'
\end{align*}

where $\theta _g$ is the Greenwich Mean Sidereal Time expressed in angle units.

## Permanent Tide

# Bibliography