Package org.orekit.data

Class 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:

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

    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:

    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

    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 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 - optional column (counting from 1)
        Returns:
        a new parser, with updated columns settings

      • withGamma

        public PoissonSeriesParser withGamma​(int column)
        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
        See Also:
        withDoodson(int, int)

      • withDoodson

        public PoissonSeriesParser withDoodson​(int firstMultiplierColumn,
                                       int numberColumn)
        Set up columns for Doodson multipliers 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
        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 tdegree 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 tdegree 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)
        Parse a stream.
        Parameters:
        stream - stream containing the IERS table
        name - name of the resource file (for error messages only)
        Returns:
        parsed Poisson series