org.orekit.data

Class PoissonSeriesParser

java.lang.Object

org.orekit.data.PoissonSeriesParser

public class PoissonSeriesParser
extends Object

Parser for Poisson series files.

A Poisson series is composed of a time polynomial part and a non-polynomial part which consist in summation series. The series terms are harmonic functions (combination of sines and cosines) of polynomial arguments. The polynomial arguments are combinations of luni-solar or planetary elements.

The Poisson series files from IERS have various formats, with or without polynomial part, with or without planetary components, with or without period column, with terms of increasing degrees either in dedicated columns or in successive sections of the file ... This class attempts to read all the commonly found formats, by specifying the columns of interest.

The handling of increasing degrees terms (i.e. sin, cos, t sin, t cos, t^2 sin, t^2 cos ...) is done as follows.

• user must specify pairs of columns to be extracted at each line, in increasing degree order
• negative columns indices correspond to inexistent values that will be replaced by 0.0)
• file may provide section headers to specify a degree, which is added to the current column degree

A file from an old convention, like table 5.1 in IERS conventions 1996, uses separate columns for degree 0 and degree 1, and uses only sine for nutation in longitude and cosine for nutation in obliquity. It reads as follows:

 ∆ψ = Σ (Ai+A'it) sin(ARGUMENT), ∆ε = Σ (Bi+B'it) cos(ARGUMENT)

      MULTIPLIERS OF      PERIOD           LONGITUDE         OBLIQUITY
  l    l'   F    D   Om     days         Ai       A'i       Bi       B'i

  0    0    0    0    1   -6798.4    -171996    -174.2    92025      8.9
  0    0    2   -2    2     182.6     -13187      -1.6     5736     -3.1
  0    0    2    0    2      13.7      -2274      -0.2      977     -0.5
  0    0    0    0    2   -3399.2       2062       0.2     -895      0.5
 

In order to parse the nutation in longitude from the previous table, the following settings should be used:

• totalColumns = 10 (see PoissonSeriesParser(int))
• firstDelaunay = 1 (see withFirstDelaunay(int))
• no calls to withFirstPlanetary(int) as there are no planetary columns in this table
• sinCosColumns = 7, -1 for degree 0 for Ai (see withSinCos(int, int, double, int, double))
• sinCosColumns = 8, -1 for degree 1 for A'i (see withSinCos(int, int, double, int, double))

In order to parse the nutation in obliquity from the previous table, the following settings should be used:

• totalColumns = 10 (see PoissonSeriesParser(int))
• firstDelaunay = 1 (see withFirstDelaunay(int))
• no calls to withFirstPlanetary(int) as there are no planetary columns in this table
• sinCosColumns = -1, 9 for degree 0 for Bi (see withSinCos(int, int, double, int, double))
• sinCosColumns = -1, 10 for degree 1 for B'i (see withSinCos(int, int, double, int, double))

A file from a recent convention, like table 5.3a in IERS conventions 2010, uses only two columns for sin and cos, and separate degrees in successive sections with dedicated headers. It reads as follows:

 ---------------------------------------------------------------------------------------------------

 (unit microarcsecond; cut-off: 0.1 microarcsecond)
 (ARG being for various combination of the fundamental arguments of the nutation theory)

   Sum_i[A_i * sin(ARG) + A"_i * cos(ARG)]

 + Sum_i[A'_i * sin(ARG) + A"'_i * cos(ARG)] * t           (see Chapter 5, Eq. (35))

 The Table below provides the values for A_i and A"_i (j=0) and then A'_i and A"'_i (j=1)

 The expressions for the fundamental arguments appearing in columns 4 to 8 (luni-solar part)
 and in columns 9 to 17 (planetary part) are those of the IERS Conventions 2003

 ----------------------------------------------------------------------------------------------------------
 j = 0  Number of terms = 1320
 ----------------------------------------------------------------------------------------------------------
     i        A_i             A"_i     l    l'   F    D    Om  L_Me L_Ve  L_E L_Ma  L_J L_Sa  L_U L_Ne  p_A
 ----------------------------------------------------------------------------------------------------------
     1   -17206424.18        3338.60    0    0    0    0    1    0    0    0    0    0    0    0    0    0
     2    -1317091.22       -1369.60    0    0    2   -2    2    0    0    0    0    0    0    0    0    0
     3     -227641.81         279.60    0    0    2    0    2    0    0    0    0    0    0    0    0    0
     4      207455.40         -69.80    0    0    0    0    2    0    0    0    0    0    0    0    0    0
     5      147587.70        1181.70    0    1    0    0    0    0    0    0    0    0    0    0    0    0

 ...

  1319          -0.10           0.00    0    0    0    0    0    1    0   -3    0    0    0    0    0   -2
  1320          -0.10           0.00    0    0    0    0    0    0    0    1    0    1   -2    0    0    0

 --------------------------------------------------------------------------------------------------------------
 j = 1  Number of terms = 38
 --------------------------------------------------------------------------------------------------------------
    i          A'_i            A"'_i    l    l'   F    D   Om L_Me L_Ve  L_E L_Ma  L_J L_Sa  L_U L_Ne  p_A
 --------------------------------------------------------------------------------------------------------------
  1321      -17418.82           2.89    0    0    0    0    1    0    0    0    0    0    0    0    0    0
  1322        -363.71          -1.50    0    1    0    0    0    0    0    0    0    0    0    0    0    0
  1323        -163.84           1.20    0    0    2   -2    2    0    0    0    0    0    0    0    0    0
  1324         122.74           0.20    0    1    2   -2    2    0    0    0    0    0    0    0    0    0
 

In order to parse the nutation in longitude from the previous table, the following settings should be used:

• totalColumns = 17 (see PoissonSeriesParser(int))
• firstDelaunay = 4 (see withFirstDelaunay(int))
• firstPlanetary = 9 (see withFirstPlanetary(int))
• sinCosColumns = 2,3 (we specify only degree 0, so when we read section j = 0 we read degree 0, when we read section j = 1 we read degree 1, see withSinCos(int, int, double, int, double) ...)

A file from a recent convention, like table 6.5a in IERS conventions 2010, contains both Doodson arguments (τ, s, h, p, N', ps), Doodson numbers and Delaunay parameters. In this case, the coefficients for the Delaunay parameters must be subtracted from the τ = GMST + π tide parameter, so the signs in the files must be reversed in order to match the Doodson arguments and Doodson numbers. This is done automatically (and consistency is checked) only when the withDoodson(int, int) method is called at parser configuration time. Some other files use the γ = GMST + π tide parameter rather than Doodson τ argument and the coefficients for the Delaunay parameters must be added to the γ parameter, so no sign reversal is performed. In order to avoid ambiguity as the two cases are incompatible with each other, trying to add a configuration for τ by calling withDoodson(int, int) and to also add a configuration for γ by calling withGamma(int) triggers an exception.

The table 6.5a file also contains a column for the waves names (the Darwin's symbol) which may be empty, so it must be identified explicitly by calling withOptionalColumn(int). The 6.5a table reads as follows:

 The in-phase (ip) amplitudes (A₁ δkfR Hf) and the out-of-phase (op) amplitudes (A₁ δkfI Hf)
 of the corrections for frequency dependence of k₂₁⁽⁰⁾, taking the nominal value k₂₁ for the
 diurnal tides as (0.29830 − i 0.00144). Units: 10⁻¹² . The entries for δkfR and δkfI are in
 units of 10⁻⁵. Multipliers of the Doodson arguments identifying the tidal terms are given,
 as also those of the Delaunay variables characterizing the nutations produced by these
 terms.

 Name   deg/hr    Doodson  τ  s  h  p  N' ps   l  l' F  D  Ω  δkfR  δkfI     Amp.    Amp.
                    No.                                       /10−5 /10−5    (ip)    (op)
   2Q₁ 12.85429   125,755  1 -3  0  2   0  0   2  0  2  0  2    -29     3    -0.1     0.0
    σ₁ 12.92714   127,555  1 -3  2  0   0  0   0  0  2  2  2    -30     3    -0.1     0.0
       13.39645   135,645  1 -2  0  1  -1  0   1  0  2  0  1    -45     5    -0.1     0.0
    Q₁ 13.39866   135,655  1 -2  0  1   0  0   1  0  2  0  2    -46     5    -0.7     0.1
    ρ₁ 13.47151   137,455  1 -2  2 -1   0  0  -1  0  2  2  2    -49     5    -0.1     0.0
 

• totalColumns = 18 (see PoissonSeriesParser(int))
• optionalColumn = 1 (see withOptionalColumn(int))
• firstDoodson, Doodson number = 4, 3 (see withDoodson(int, int))
• firstDelaunay = 10 (see withFirstDelaunay(int))
• sinCosColumns = 17, 18, see withSinCos(int, int, double, int, double) ...)

Our parsing algorithm involves adding the section degree from the "j = 0, 1, 2 ..." header to the column degree. A side effect of this algorithm is that it is theoretically possible to mix both formats and have for example degree two term appear as degree 2 column in section j=0 and as degree 1 column in section j=1 and as degree 0 column in section j=2. This case is not expected to be encountered in practice. The real files use either several columns or several sections, but not both at the same time.

Since:

6.1

Author:

Luc Maisonobe

See Also:

SeriesTerm, PolynomialNutation

Constructor Summary

Constructors

Constructor and Description
PoissonSeriesParser(int totalColumns) Build a parser for a Poisson series from an IERS table file.

Method Summary

Modifier and Type	Method and Description
PoissonSeries	parse(InputStream stream, String name) Parse a stream.
PoissonSeriesParser	withDoodson(int firstMultiplierColumn, int numberColumn) Set up columns for Doodson multiplers and Doodson number.
PoissonSeriesParser	withFirstDelaunay(int firstColumn) Set up first column of Delaunay multiplier.
PoissonSeriesParser	withFirstPlanetary(int firstColumn) Set up first column of planetary multiplier.
PoissonSeriesParser	withGamma(int column) Set up column of GMST tide multiplier.
PoissonSeriesParser	withOptionalColumn(int column) Set up optional column.
PoissonSeriesParser	withPolynomialPart(char freeVariable, PolynomialParser.Unit unit) Set up polynomial part parsing.
PoissonSeriesParser	withSinCos(int degree, int sinColumn, double sinFactor, int cosColumn, double cosFactor) Set up columns of the sine and cosine coefficients.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PoissonSeriesParser

public PoissonSeriesParser(int totalColumns)

Build a parser for a Poisson series from an IERS table file.

Parameters:

totalColumns - total number of columns in the non-polynomial sections

Method Detail

withPolynomialPart

public PoissonSeriesParser withPolynomialPart(char freeVariable,
                                              PolynomialParser.Unit unit)

Set up polynomial part parsing.

Parameters:

freeVariable - name of the free variable in the polynomial part

unit - default unit for polynomial, if not explicit within the file

Returns:

a new parser, with polynomial parser updated

withOptionalColumn

public PoissonSeriesParser withOptionalColumn(int column)

Set up optional column.

Optional columns typically appears in tides-related files, as some waves have specific names (χ₁, M₂, ...) and other waves don't have names and hence are replaced by spaces in the corresponding file line.

At most one column may be optional.

Parameters:

column - column of the GMST tide multiplier (counting from 1)

Returns:

a new parser, with updated columns settings

withGamma

public PoissonSeriesParser withGamma(int column)
                              throws OrekitException

Set up column of GMST tide multiplier.

Parameters:

column - column of the GMST tide multiplier (counting from 1)

Returns:

a new parser, with updated columns settings

Throws:

OrekitException - if τ has been configured by a previous call to withDoodson(int, int)

See Also:

withDoodson(int, int)

withDoodson

public PoissonSeriesParser withDoodson(int firstMultiplierColumn,
                                       int numberColumn)
                                throws OrekitException

Set up columns for Doodson multiplers and Doodson number.

Parameters:

firstMultiplierColumn - column of the first Doodson multiplier which corresponds to τ (counting from 1)

numberColumn - column of the Doodson number (counting from 1)

Returns:

a new parser, with updated columns settings

Throws:

OrekitException - if γ has been configured by a previous call to withGamma(int)

See Also:

withGamma(int), withFirstDelaunay(int)

withFirstDelaunay

public PoissonSeriesParser withFirstDelaunay(int firstColumn)

Set up first column of Delaunay multiplier.

Parameters:

firstColumn - column of the first Delaunay multiplier (counting from 1)

Returns:

a new parser, with updated columns settings

withFirstPlanetary

public PoissonSeriesParser withFirstPlanetary(int firstColumn)

Set up first column of planetary multiplier.

Parameters:

firstColumn - column of the first planetary multiplier (counting from 1)

Returns:

a new parser, with updated columns settings

withSinCos

public PoissonSeriesParser withSinCos(int degree,
                                      int sinColumn,
                                      double sinFactor,
                                      int cosColumn,
                                      double cosFactor)

Set up columns of the sine and cosine coefficients.

Parameters:

degree - degree to set up

sinColumn - column of the sine coefficient for t^degree counting from 1 (may be -1 if there are no sine coefficients)

sinFactor - multiplicative factor for the sine coefficient

cosColumn - column of the cosine coefficient for t^degree counting from 1 (may be -1 if there are no cosine coefficients)

cosFactor - multiplicative factor for the cosine coefficient

Returns:

a new parser, with updated columns settings

parse

public PoissonSeries parse(InputStream stream,
                           String name)
                    throws OrekitException

Parse a stream.

Parameters:

stream - stream containing the IERS table

name - name of the resource file (for error messages only)

Returns:

parsed Poisson series

Throws:

OrekitException - if stream is null or the table cannot be parsed