Voir la source de User Manual 3.3 Frames configuration



== Introduction ==
=== Scope ===
Frames configuration defines the models and data to use for each frame transformation.
Several frames configurations are already available in PATRIUS (IERS 2003, IERS 2010, STELA? etc.) but the user may define its own convention.

=== Javadoc ===
{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
|Orekit
|[{{JavaDoc3.3}}/org/orekit/frames/configuration/package-summary.html Package org.orekit.frames.configuration]
|-
|Orekit
|[{{JavaDoc3.3}}/org/orekit/frames/configuration/eop/package-summary.html Package org.orekit.frames.configuration.eop]
|-
|Orekit
|[{{JavaDoc3.3}}/org/orekit/frames/configuration/tides/package-summary.html Package org.orekit.frames.configuration.tides]
|-
|Orekit
|[{{JavaDoc3.3}}/org/orekit/frames/configuration/libration/package-summary.html Package org.orekit.frames.configuration.libration]
|-
|Orekit
|[{{JavaDoc3.3}}/org/orekit/frames/configuration/precessionnutation/package-summary.html Package org.orekit.frames.configuration.precessionnutation]
|}

=== Links ===
* [http://www.iers.org/IERS/EN/Home/home_node.html IERS website]
* [http://www.iers.org/IERS/EN/Publications/TechnicalNotes/tn36.html IERS 2010 Conventions]
* [http://www.iers.org/IERS/EN/Publications/TechnicalNotes/tn32.html IERS 2003 Conventions]

== Features Description ==

=== The Frames Configuration ===
In PATRIUS, a Frames configuration is defined as a set of models that are used to compute transformations between different frames. As of now, these models define the transformations between the frames defined by the IERS (see [http://www.iers.org/IERS/EN/Publications/TechnicalNotes/tn36.html/ IERS TN36 Ch. 5]). Thus, the configuration holds all the models required to transform a position or a velocity from the International Terrestrial Reference System (ITRS) and the Geocentric Celestial Reference System (GCRS) and vice versa.

When no configuration is created by the user, PATRIUS uses the IERS 2010 convention. The library also allows the user to create configurations by setting up the adequate models.

The FramesConfigurationFactory contains public static instances of standard configurations, amongst which the configuration following the IERS 2010 conventions.

==== The default configuration (IERS2010) ====

The default configuration (IERS2010) is convenient for most applications. In this case, no operation pertaining to frames configurations needs to be undertaken. At the first call requiring frames, the [{{JavaDoc3.3}}/org/orekit/frames/FramesFactory.html FramesFactory] will create the default configuration and use it accordingly.

The code snippet below is valid as long as the user has NOT passed a custom configuration to the FramesFactory.

<syntaxhighlight lang="java">
/* 
/* Example of frame transformations using IERS2010 convention
/*/
// instance of ITRF with the default configuration (IERS2010)
final Frame itrf = FramesFactory.getITRF();
// instance of GCRF with the default configuration (IERS2010)
final Frame gcrf = FramesFactory.getGCRF();
// transformation relating ITRS to GCRS at currentDate (supposed as already defined)
final Transform itrfTransform = itrf.getTransformTo(gcrf, currentDate);
// transformed currentPV (supposed as already defined)
final PVCoordinates Vtransformed = itrfTransform.transformPVCoordinates(currentPV);
// ...
</syntaxhighlight>

The default IERS 2010 configuration is as follows  :

* IERS 2010 tidal correction model
* IERS 2010 libration correction model
* IERS 2010 S' model
* account of EOP UT1-UTC and pole corrections
* IERS 2010 precession and nutation (interpolated computation) with nutation correction to ''X'' and ''Y'' and account of angular derivatives.

==== Creating a customised configuration ====

PATRIUS allows creating customized configurations to define the intermediate transformations relating ITRS to TIRS, TIRS to CIRS and CIRS to GCRS.

===== Transformation relating ITRS to TIRS =====

Based on polar motion, it can be expressed as:
<math>W(t)=R3(-s').R2(xp).R1(yp)</math>,
where ''xp'' and ''yp'' are the polar coordinates of the Celestial Intermediate Pole (CIP) in the ITRS and ''s''' is called the "Terrestrial Intermediate Origin locator". 

'''The user can define the following parameters:''' 

* polar motion (yes/no),
* interpolation method  for ''xp'' and ''yp'' (linear or Lagrange 4),
* account of ocean tidal effect ''(dx,dy),,ocean tides,,'' in polar motion (IERS2010, IERS2003 or no effect),
* account of libration effect ''(dx,dy),,libration,,'' in polar motion (IERS2010 or no effect),
* account of the quantity ''s''' (IERS2010, IERS2003 or no effect). 

To create a polar motion model with chosen parameters, PATRIUS provides the constructor '''PolarMotion''' (see [{{JavaDoc3.3}}/org/orekit/frames/configuration/PolarMotion.html PolarMotion javadoc] for the description of the above parameters).

===== Transformation relating TIRS to CIRS =====

Based on the rotation of the Earth around the axis of the CIP, it can be expressed as:
<math>R(t)=R3(-ERA)</math>,
where ''ERA'' is the Earth Rotation Angle between the CIO and the TIO.

'''The user can define the following parameters:''' 

* account of ''UT1-UTC'' (yes or no),
* interpolation method for ''UT1-UTC'' (linear or Lagrange 4),
* account of ocean tidal effect ''dUT1,,ocean tides,,'' in ''UT1'' (IERS2010, IERS2003 or no effect),
* account of libration effect ''dUT1,,libration,,'' in ''UT1'' (IERS2010 or no effect). '''Note that this effect is not yet implemented. It is negligible in current practical applications due to its very small size'''.

To create a diurnal rotation model with chosen parameters, PATRIUS provides the constructor '''DiurnalRotation''' (see [{{JavaDoc3.3}}/org/orekit/frames/configuration/DiurnalRotation.html DiurnalRotation javadoc] for the description of the above parameters).

===== Transformation relating CIRS to GCRS =====

Based on the celestial motion of the CIP, it can be expressed as:
<math>Q(t)=R3(-E).R2(-d).R3(E).R3(s)</math>,
''E'' and ''d'' being such that the coordinates of the CIP in the GCRS are:
<math>X=sin d cos E</math>, <math>Y=sin d sin E</math>, <math>Z=cos d</math> and ''s'' being a quantity called "CIO locator". ''X'',''Y'' and ''s'' can be given by developments as function of time, based on the '''IAU 2006 precession''' and '''IAU 2000A_R06 nutation'''. The IAU series are given in the ''tab5.2a'' file (X model), in the ''tab5.2b'' file (Y model) and in the ''tab5.2d'' file (s model).  

'''The user can define the following parameters:''' 

* account of precession and nutation model (IERS2010, IERS2003 or no effect),
* interpolation method for ''X'', ''Y'' and ''s'' (Neville method or direct computation),
* nutation corrections to the ''X'' and ''Y'' coordinates reported by the IERS as "celestial pole offsets" (yes or no),
* interpolation method for the corrections (linear or Lagrange 4),
* account of non constant rotation (yes or no) to compute properly the velocity

To create a precession nutation model with chosen parameters, PATRIUS provides the constructor '''PrecessionNutation''' (see [{{JavaDoc3.3}}/org/orekit/frames/configuration/PrecessionNutation.html PrecessionNutation javadoc] for the description of the above parameters).

===== Example of frame configuration =====

The example describes how to create a frame configuration defined by the following parameters:

* polar motion with IERS2003 corrections (ocean tidal effect, no libration effect and account of quantity ''s'''),
* account of ''UT1-UTC'' with IERS2003 corrections (ocean tidal effect),
* account of precession and nutation (direct or interpolated computation) with nutation correction to ''X'' and ''Y'' and account of angular derivatives.

PATRIUS offers a configuration factory to make the creation easier. Several methods are available to set-up the configuration with the user parameters.

<syntaxhighlight lang="java">
        // Configurations builder
        final FramesConfigurationBuilder builder = new FramesConfigurationBuilder();

        // Tides and libration
        final TidalCorrectionModel tides = TidalCorrectionModelFactory.TIDE_IERS2003_INTERPOLATED;
        final LibrationCorrectionModel lib = LibrationCorrectionModelFactory.NO_LIBRATION;

        // Polar Motion
        final PolarMotion defaultPolarMotion = new PolarMotion(true, tides, lib, SPrimeModelFactory.SP_IERS2003);

        // Diurnal rotation
        final DiurnalRotation defaultDiurnalRotation = new DiurnalRotation(tides, lib);

        // Precession Nutation
        final PrecessionNutation precNut = new PrecessionNutation(
                true, PrecessionNutationModelFactory.PN_IERS2003_INTERPOLATED_NON_CONSTANT);

        builder.setDiurnalRotation(defaultDiurnalRotation);
        builder.setPolarMotion(defaultPolarMotion);
        builder.setPrecessionNutation(precNut);
        builder.setEOP2000History(EOPHistoryFactory.getEOP2000History(EOPInterpolators.LAGRANGE4));

        final FramesConfiguration config = builder.getConfiguration();
        // and pass it to the frames factory
        FramesFactory.setConfiguration(config);
 
        // Get the frames
        final Frame itrf = FramesFactory.getITRF();
        final Frame gcrf = FramesFactory.getGCRF();
</syntaxhighlight>

===== Using specific EOP history files / data =====

Earth Orientation Parameters (EOP) files provide angular corrections that account for short-period variations of Earths' [http://www.iers.org/nn_10828/IERS/EN/Service/Glossary/cip.html Celestial Intermediate Pole]. The corresponding data is used to compute the transformation from the TIRF to the ITRF frame. The amplitudes of the corrections are given in [[FDY_FRAME_Home#HPolarmotion Polar Motion]]. IN PATRIUS, the [{{JavaDoc3.3}}/org/orekit/frames/configuration/eop/EOPHistory.html EOPHistory] interface represents EOP data. It has two implementations : [{{JavaDoc3.3}}/org/orekit/frames/configuration/eop/EOP1980History.html EOP1980History] and [{{JavaDoc3.3}}/org/orekit/frames/configuration/eop/EOP2000History.html EOP2000History]. These classes differ because the EOP definition and representation has changed, according to the IERS conventions. Both remain available in PATRIUS.


EOP data can be retrieved in two ways in PATRIUS:

*'''By providing your own history:'''

For the 2000 EOP paradigm, the user may manually create an EOP history with EOP entries. In order to do so, the user must create an instance of EOPHistory and feed it with EOP entries :

<syntaxhighlight lang="java">
        // create EOP list- use a 1 day gap
        final List<EOP2000Entry> list = new ArrayList<EOP2000Entry>();
        list.add(entry1);
        list.add(entry2);
        list.add(entry3);
        ...
        list.add(entryN);

        // Create EOP history object- make sure to have enough entries around the dates of interpolation
        final EOP2000History eop2000History = new EOP2000History(EOPInterpolators.LAGRANGE4);

        // Fill history
        EOP2000History.fillHistory(list, eop2000History);
</syntaxhighlight>

Also, the user may create an empty EOPHistory object and populate it using a Java InputStream (usually, a file). with the adequate loader (see [{{JavaDoc3.3}}/org/orekit/frames/configuration/eop/package-summary.html eop package]) :

<syntaxhighlight lang="java">
        final InputStream is = new FileInputStream("eopdatafile");
        // Empty EOP history object-  choice of interpolator
        final EOP2000History eop2000History = new EOP2000History(EOPInterpolators.LAGRANGE4);
        // EOP08C04FilesLoader reads the input stream and fills the history object
        EOP08C04FilesLoader.fillHistory(eop2000History, is);
</syntaxhighlight>

Of course, in this case, the file has to be in the proper format for the EOP08C04FilesLoader (see its [{{JavaDoc3.3}}/org/orekit/frames/configuration/eop/EOP08C04FilesLoader.html javadoc] for information).

For the 1980 EOP paradigm, the user must proceed in a similar fashion by manually creating an [{{JavaDoc3.3}}/org/orekit/frames/configuration/eop/EOP1980HistoryLoader.html EOP1980HistoryLoader] instance and feeding it to the EOPHistoryFactory.

*'''By automatically loading data using default EOP loaders:'''

<syntaxhighlight lang="java">
final EOP2000History eop2000History = EOPHistoryFactory.getEOP2000History(EOPInterpolators.LAGRANGE4);
</syntaxhighlight>
This previous line of code returns an EOP 2000 history filled up with found data. Found data includes (in order of data reading):
* IERS Rapid data and prediction files
* EOP05C05 files
* IERS bulletin B files
Warning: providing overlapping data may results in some erratic results since some dates will have several EOP data.


Finally the EOP history is provided to the frame configuration builder:
<syntaxhighlight lang="java">
        FramesConfigurationBuilder builder = new FramesConfigurationBuilder(config);
        builder.setEOP2000History(eop2000History);
        FramesFactory.setConfiguration(builder.getConfiguration());
</syntaxhighlight>


'''Note 1''': for the users and applications that do not require any EOP data, utility classes that return zero for all EOP corrections have been implemented. These classes possess validity intervals that span 100 years (1950 through 2050) for the EOP 1980 paradigm and infinity (-infinity through +infinity) for the EOP 2000 paradigm. This means that any application using these classes can request EOP data over these intervals.

* For the 1980 EOP paradigm, a loader class has been implemented : [{{JavaDoc3.3}}/org/orekit/frames/configuration/eop/NoEOP1980HistoryLoader.html NoEOP1980HistoryLoader]. The user need only to create an instance of that class and feed it the [{{JavaDoc3.3}}/org/orekit/frames/configuration/eop/EOPHistoryFactory.html EOPHistoryFactory] in order for all transformations to use zero for EOP corrections (only 1980). This done thanks to the following instruction : <code>EOPHistoryFactory.addEOP1980HistoryLoader(new NoEOP1980HistoryLoader())</code>. This loader then feeds an internal instance of EOP1980History, that the users does not manipulate directly.

* For the 2000 EOP paradigm, a utility class, [{{JavaDoc3.3}}/org/orekit/frames/configuration/eop/NoEOP2000History.html NoEOP2000History], was created and represents an EOP history with no corrections (or more precisely 0.0). It has an infinite time interval of validity, from PAST_INFINITY to FUTURE_INFINITY.

'''Note 2''': Note that most EOP providers are valid on data-provided timespan. The class <code>EOP2000HistoryConstantOutsideInterval</code> circumvents that limitation by returning boundaries values when requested date is out of data range.

===== Note on the internal representation of EOP Data =====

As of 2.1, EOP data sets have been modified to store the value of UT1-TAI instead of UT1-UTC. Additionally, new constructors that allow creating EOPEntry instances from UT1-TAI data have been added. The frames tranformations have thus become independent of the UTC-TAI.history file, provided that the user provides a correctly calculated UT1-TAI. Please refer to the [{{JavaDoc3.3}}/org/orekit/frames/configuration/eop/EOPEntry.html javadoc] for more information.

It should be noted that UT1 is defined with respect to UTC. Consequently, the only way to correctly compute UT1-TAI is per UT1-TAI = UT1-UTC + UTC-TAI.

==== Available models ====

As of now, available models include :

* IERS 2003 and 2010 Precession Nutation models,
* IERS 2010 S' Model,
* IERS 2003 and 2010 Tidal corrections models,
* IERS 2010 Libration correction model (without UT1-UTC correction).

==== Amplitudes of different effects ====

This section provides some useful information about the different effect of each transformation. The distances are given at one terrestrial radius. These data come from the document "''DCT/SB/OR/2010-12497", issue 1.3, 2010/11/23''".

===== Polar motion =====

* ''(xp,yp),,IERS,,'' < 1'' (30m)
* ''(dx,dy),,ocean tides,,'' < 0.002'' (6cm)
* ''(dx,dy),,libration,,'' < 0.00003 '' (1mm)
* ''s''' < 0.00005 '' per century

===== Diurnal rotation =====

* ''UT1-UTC,,IERS,,'' < 1 sec. (460m)
* ''UT1-UTC,,ocean tides,,'' < 33E-6 sec. (1.5cm)
* ''UT1-UTC,,libration,,'' < 4E-6 sec. (2mm)

===== Celestial motion of the CIP =====

* ''(X,Y),,IAU2000/2006,,'' < 11'' (340m)
* ''(dX,dY),,IERS,,'' < 0.001'' (3cm)

==== Validation of IERS2010 implementation ====

PATRIUS implementation of IERS2010 convention has been validated with reference software routines from ''SOFA'', ''ZOOM'', and other routines available in IERS website (like ''interp.f'' routine for EOP data interpolation). 

The first level of validation allows to compare the values for each intermediate transformation:

* comparison of ''xp'', ''yp'' and ''s''' for the transformation relating ITRS to TIRS,
* comparison of ''UT1-UTC'' for the transformation relating TIRS to CIRS,
* comparison of ''X'', ''Y'', ''s'' and ''dX'', ''dY'', ''ds'' for the transformation relating CIRS to GCRS.

The second level of validation allows to compare the rotation matrices (''Q(t)'', ''R(t)'', ''W(t)'') by computing angular deviations with the reference.

Several configurations are used to take into account the different effects. Tests have been done for short and long period.

The following graphs represent angular deviations (in log scale) for the following transformations: ITRS to GCRS in dark green, ITRS to TIRS in red, TIRS to CIRS in blue-green and CIRS to GCRS in violet. The first one is related to a short period (10 days), the second one is related to a long period (40 years). The blue line is the validation threshold of '''0.1E-3 arcseconds'''. The deviations computed for all transformations are smaller than 0.1E-3 arcseconds.

[[File:global.png|center]]

[[File:globals.png|center]]

As a consequence, some deviations are observed on position and velocity of points used in the context of this validation. The points are taken on LEO and GEO orbits, and also on the terrestrial crust. To give the user some indication, the magnitude of errors is between 1E-4 and 1E-5 m.
 
For more details, please refer to the validation report "''SIRIUS-SVS-DV-10108-THA, issue 1.0, 2012/07/23''".

== Getting Started ==
{{specialInclusion prefix=$theme_sub section="GettingStarted"/}}

== Contents ==
=== Interfaces ===
'''Interfaces used within the Frames configurations'''

{| class="wikitable"
|-
! scope="col"| Interface
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''FramesConfiguration'''
|Interface providing the basic services for frame configurations.
|[{{JavaDoc3.3}}/org/orekit/frames/configuration/FramesConfiguration.html ...]
|-
|'''EOPHistory'''
|Interface for retrieving Earth Orientation Parameters history throughout a large time range.
|[{{JavaDoc3.3}}/org/orekit/frames/configuration/eop/EOPHistory.html ...]
|-
|'''LibrationCorrectionModel'''
|This interface provides the pole corrections as well as the ut1-utc corrections due to libration.
|[{{JavaDoc3.3}}/org/orekit/frames/configuration/libration/LibrationCorrectionModel.html ...]
|-
|'''PrecessionNutationModel'''
|This interface provides the Celestial Intermediate Pole motion (CIP) in the GCRS, those coordinates are used for the GCRF to CIRF transformation.
|[{{JavaDoc3.3}}/org/orekit/frames/configuration/precessionnutation/PrecessionNutationModel.html ...]
|-
|'''SPrimeModel'''
|This interface provides the s' correction (used for the following transformation : TIRF -> ITRF).
|[{{JavaDoc3.3}}/org/orekit/frames/configuration/sp/SPrimeModel.html ...]
|-
|'''TidalCorrectionModel'''
|This interface provides the pole corrections as well as the ut1-utc corrections due to tidal effects.
|[{{JavaDoc3.3}}/org/orekit/frames/configuration/tides/TidalCorrectionModel.html ...]
|}

=== Classes ===

The classes are mentioned according to their packages for better visibility. Note : The aforementioned EOP2000History class is to be used with the PATRIUS IERS Frames Configuration.

{| class="wikitable"
|-
! scope="col"| General 
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''FramesConfigurationBuilder'''
|Frame configuration builder utility, to assist the user in creating a FramesConfiguration.
|[{{JavaDoc3.3}}/org/orekit/frames/configuration/FramesConfigurationBuilder.html ...]
|-
|'''FramesConfigurationFactory'''
|Frames configuration factory. Contains useful configurations.
|[{{JavaDoc3.3}}/org/orekit/frames/configuration/FramesConfigurationFactory.html ...]
|}

{| class="wikitable"
|-
! scope="col"| Models container classes
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''DiurnalRotation'''
|This class contains the different ut1-utc corrections (libration, tidal effects).
|[{{JavaDoc3.3}}/org/orekit/frames/configuration/DiurnalRotation.html ...]
|-
|'''PolarMotion'''
|This class contains the different polar motion corrections (libration, tidal effects, sp correction).
|[{{JavaDoc3.3}}/org/orekit/frames/configuration/PolarMotion.html ...]
|-
|'''PrecessionNutation'''
|This class contains the precession nutation model used within the FramesConfigurationImplementation class.
|[{{JavaDoc3.3}}/org/orekit/frames/configuration/PrecessionNutation.html ...]
|}

{| class="wikitable"
|-
! scope="col"| Libration models classes
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''IERS2010LibrationCorrection'''
|This class computes the diurnal lunisolar effect. It is a java translation of the fortran subroutine PM_GRAVI (provided by CNES and from IERS conventions, see chapter 5, tables 5.1a and 5.2a).
|[{{JavaDoc3.3}}/org/orekit/frames/configuration/libration/IERS2010LibrationCorrection.html ...]
|-
|'''NoLibrationCorrection'''
|This class ignores the libration effects.
|[{{JavaDoc3.3}}/org/orekit/frames/configuration/libration/NoLibrationCorrection.html ...]
|}

{| class="wikitable"
|-
! scope="col"| Precession Nutation models classes
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''PrecessionNutationConvention'''
|IERS Precession Nutation enumerate. Each enumerate provides data file locations.
|[{{JavaDoc3.3}}/org/orekit/frames/configuration/precessionnutation/PrecessionNutationConvention.html ...]
|-
|'''IERS20032010PrecessionNutation'''
|Compute the precession nutation correction according to the new IAU-2000 model.
|[{{JavaDoc3.3}}/org/orekit/frames/configuration/precessionnutation/IERS20032010PrecessionNutation.html ...]
|}

{| class="wikitable"
|-
! scope="col"| S' models classes
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''IERS2010SPCorrection'''
|Compute s' correction (IERS 2010 model).
|[{{JavaDoc3.3}}/org/orekit/frames/configuration/sp/IERS2010SPCorrection.html ...]
|-
|'''NoSpCorrection'''
|This class ignores the quantity s'.
|[{{JavaDoc3.3}}/org/orekit/frames/configuration/sp/NoSpCorrection.html ...]
|}

{| class="wikitable"
|-
! scope="col"| Tidal correction models classes
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''IERS2010TidalCorrection'''
|Compute tidal correction of the pole motion.
|[{{JavaDoc3.3}}/org/orekit/frames/configuration/tides/IERS2010TidalCorrection.html ...]
|-
|'''IERS2003TidalCorrection'''
|Compute tidal correction of the pole motion.
|[{{JavaDoc3.3}}/org/orekit/frames/configuration/tides/IERS2003TidalCorrection.html ...]
|-
|'''NoTidalCorrection'''
|This class ignores the tidal effects.
|[{{JavaDoc3.3}}/org/orekit/frames/configuration/tides/NoTidalCorrection.html ...]
|}

{| class="wikitable"
|-
! scope="col"| EOP classes
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''EOP2000History'''
|	This class holds Earth Orientation Parameters (IAU2000) data throughout a large time range.
|[{{JavaDoc3.3}}/org/orekit/frames/configuration/eop/EOP2000History.html ...]
|-
|'''EOP2000HistoryConstantOutsideInterval'''
|	This class extends the EOP2000History but returns boundaries values when date is out of data range.
|[{{JavaDoc3.3}}/org/orekit/frames/configuration/eop/EOP2000HistoryConstantOutsideInterval.html ...]
|}

[[Category:User_Manual_3.3_Flight_Dynamics]]