Patrius - Contributions [fr]

User Manual 4.17 Data management system

2025-12-12T15:24:33Z

Admin tsn :

== Introduction ==
=== Scope ===
The scope of this chapter is to present data management. This section presents the three modules of the data management system originally provided by Orekit :

* how does the data management system work?
* how to set it up?
* how to use it?
* how to add data to what already exists?
* what are the pros and cons of this system?

=== Javadoc ===
The data objects are available in the packages :
{| class="wikitable"
! scope="col" |Library
! scope="col" |Javadoc
|-
|Patrius
|[https://patrius.cnes.fr/images/upload/JavaDocs/V4.17/fr/cnes/sirius/patrius/data/package-summary.html Package fr.cnes.sirius.patrius.data]
|}

=== Links ===
None as of now.

=== Useful Documents ===
None as of now.

=== Package Overview ===
The data loading process is organized through three main objects.

The <code>DataProvider</code> classes handle data sources. Each one of them has a particular type of source it can browse. The <code>DirectoryCrawler</code> performs a bottom-first search in a directory tree. The <code>ZipJarCrawler</code> works alike, but inside a compressed file. The <code>ClassPathCrawler</code> handles a list of data files and/or compressed files that are in the classpath (it can not search recursively like the <code>DirectoryCrawler</code> though). Finally, the <code>NetworkCrawler</code> works like the <code>ClassPathCrawler</code>, although in its case, it has a list of URLs instead of files. There is no limit to the number of DataProviders a program can use at once.

The Providers are listed and put to work through the <code>DataProvidersManager</code> singleton. This is the single point of access to the data management system. It contains a list of Providers that are queried every time a user needs data.

The various crawlers provide streams to the <code>DataLoader</code>. From these streams, the DataLoaders can reconstruct data that was stored in files (either compressed or not), even if some files come from different sources. These streams effectively separate the machine world from the program world, because they hide the former to the latter. Therefore, parsing data from a new format only means creating a loader, and being able to read another kind of file means creating a <code>DataProvider</code>. Note that the DataLoaders usually serve as a facade for the higher layers of the program.

== Features Description ==

=== Data providers (<code>DataProvidersManager</code>) ===

==== Default provider ====
The data management system can use a system-wide property, <code>orekit.data.path</code>, as an entry point for default data. This default data must be file-based (either a file system entry point or a java resource) and either a directory or a zip/jar file.
Setting a default provider is not mandatory, and must be done explicitly by :

* setting a value to <code>orekit.data.path</code>,
* calling <code>addDefaultProviders</code> method on the data provider manager,
* calling <code>addProvider(DataProvider)</code> method to add a provider.

==== Using the data management system ====
The data management system main operation is through the <code>feed</code> method. This method takes a <code>DataLoader</code>, and a regexp string matching the name of files the <code>DataLoader</code> is able to process. In this method call :

* the <code>DataProviders</code> list is traversed in the priority order.
* the first <code>DataProvider</code> providing a file matching the regexp is the one (and only) used to feed the <code>DataLoader</code>.

=== File formats ===
Patrius can read a variety of files:
* '''Static potential files'''
These files contains static potential coefficients up to a certain order and degree and are used to compute Earth (or any other body) static potential perturbation.

* '''Variable potential files'''
Theses files contains variable potential coefficients up to a certain order and degree and are used to compute Earth (or any other body) variable potential perturbation.

* '''Geomagnetic coefficients files'''
These files contains geomagnetic coefficients and are used to compute Earth (or any other body) geomagnetic field.

* '''Ionospheric coefficients files'''
These files contains ionospheric data and are used to compute Earth ionospheric correction.

* '''Solar activity files'''
These files contains solar flux and geomagnetic coefficients are used to get solar activity in order to compute drag perturbation.

* '''Earth Orientation Parameters files'''
These files contains earth orientation parameters (polar motion, LOD, etc.) used in frames transformation.

* '''TAI-UTC shift files'''
These files contains TAI-TUC shift.

* '''Orbital data files'''
These files are used to store orbital ephemeris

* '''Third body ephemeris files'''
These files are used to store third-body orbital ephemeris (Sun, Moon, etc.)

The following sections describe all file readable in PATRIUS. When the file format is not described anywhere, a short description is detailed below the tab.

==== Static Potential ====

Static potential coefficients files contains potential coefficients up to a certain order and degree. 
Warning: at very high order and degree (> 100), some numerical quality issues can appear and results may be degraded.

{| class="wikitable"
|-
! scope="col"| Data type
! scope="col"| Data provider
! scope="col"| Format
! scope="col"| Reader
|-
|'''GRGS'''
|Not direct link. This link provides GRGC potential coefficients [https://grace.obs-mip.fr/variable-models-grace-lageos/formats/spherical-harmonics-coefficients-format-grace/]
|[https://grace.obs-mip.fr/variable-models-grace-lageos/formats/]
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/potential/GRGSFormatReader.html GRGSFormatReader]
|-
|'''EGM'''
|[http://earth-info.nga.mil/GandG/wgs84/gravitymod/egm2008/first_release.html]
|See below
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/potential/EGMFormatReader.html EGMFormatReader]
|-
|'''ICGEM'''
|[http://icgem.gfz-potsdam.de/tom_longtime]
|[https://icgem.gfz.de/files/6defd9f87a64b16ec96bd657a74d0292ae3447cc7418da5104441102d8cb2b58.pdf]
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/potential/ICGEMFormatReader.html ICGEMFormatReader]
|-
|'''SHM'''
|Not provided (not used any more, replaced by ICGEM format)
|See below
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/potential/SHMFormatReader.html SHMFormatReader]
|}

'''EGM file format''' (''Column text file'')

Column index: 
1:Degree of coefficients 
2:Order of coefficients 
3:Tesseral-sectorial cosinus coefficient 
4:Tesseral-sectorial sinus coefficient 
5:Sigma applied to the cosinus 
6:Sigma applied to the sinus

[[File:EGM.png|center]]

'''SHM file format''' (''Column text file'')

Column index: 
2:Degree of coefficients 
3:Order of coefficients 
4:Tesseral-sectorial cosinus coefficient 
5:Tesseral-sectorial sinus coefficient 

[[File:SHM.png|center]]

==== Variable Potential ====

Variable potential coefficients files contains potential coefficients up to a certain order and degree. 
Warning: at very high order and degree (> 100), some numerical quality issues can appear and results may be degraded.

FES2004 is used to model oceanic tides.

{| class="wikitable"
|-
! scope="col"| Data type
! scope="col"| Data provider
! scope="col"| Format
! scope="col"| Reader
|-
|'''GRGSRL02'''
|[https://grace.obs-mip.fr/variable-models-grace-lageos/formats/spherical-harmonics-coefficients-format-grace/]
|[https://grace.obs-mip.fr/variable-models-grace-lageos/formats/]
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/variations/coefficients/GRGSRL02FormatReader.html GRGSRL02FormatReader]
|-
|'''FES2004'''
|[https://www.aviso.altimetry.fr/en/data/products/auxiliary-products/global-tide-fes.html]
|See below
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/tides/coefficients/FES2004FormatReader.html FES2004FormatReader]
|}

'''FES2004 file format''' (''Column text file'')

Column index: 
1:Doodson number 
2:Darwin number 
3:Degree of coefficients 
4:Order of coefficients 
5:Sinus coefficient positif 
6:Cosinus coefficient positif 
7:Sinus coefficient negatif 
8:Cosinus coefficient negatif 
9:Positif coefficient 
10:Epsilon positif 
11:Negatif coefficient 
12:Negatif epsilon

[[File:FES2004.png|center]]

==== Geomagnetic coefficients ====

Geomagnetic coefficients fiels contains geomagnetic coefficients up to a certain order and degree.

{| class="wikitable"
|-
! scope="col"| Data type
! scope="col"| Data provider
! scope="col"| Format
! scope="col"| Reader
|-
|'''COF'''
|IGCRF data: [https://www.ngdc.noaa.gov/IAGA/vmod/igrf.html] WMM data: [https://www.ngdc.noaa.gov/geomag/WMM/soft.shtml]
|See below
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/models/earth/COFFileFormatReader.html COFFileFormatReader]
|}

'''COF file format''' (''Column text file'')

Column index: 
1:Degree of coefficients 
2:Order of coefficients 
3:g coefficient at position n,m 
4:h coefficient at position n,m 
5:dg coefficient at position n,m 
6:dh coefficient at position n,m 
g and h are the Gauss coefficients of main geomagnetic model (nT) 
dg and dh are the Gauss coefficients of secular geomagnetic model (nT/years)

[[File:COF.png|center]]

==== Ionospheric coefficients ====

Ionospheric coefficients files contains ionospheric coefficient to model the state of the ionosphere.

{| class="wikitable"
|-
! scope="col"| Data type
! scope="col"| Data provider
! scope="col"| Format
! scope="col"| Reader
|-
|'''CCIR12'''
|N/A
|See below
|[<nowiki/>{{JavaDoc4.17}}/fr/cnes/sirius/patrius/signalpropagation/ionosphere/R12Loader.html R12Loader]
|-
|'''USK(NEWUSK)'''
|N/A
|See below
|[<nowiki/>{{JavaDoc4.17}}/fr/cnes/sirius/patrius/signalpropagation/ionosphere/USKLoader.html USKLoader]
|}

'''CCIR12 file format''' (''Column text file'')

Column index: 
1:Year 
2:Month 
3:Unused 
4:Midval 
5:Unused 
6:Midday 

[[File:CCIR12.png]]

'''USK file format''' (''Line text file'')

[[File:NEWUSK.png|center]]

==== Solar activity ====

Solar activity contains solar flux and geomagnetic coefficients for a given timespan. ACSOL and NOAA files usually provide data for several years.

{| class="wikitable"
|-
! scope="col"| Data type
! scope="col"| Data provider
! scope="col"| Format
! scope="col"| Reader
|-
|'''ACSOL'''
|N/A
|See below
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/ACSOLFormatReader.html ACSOLFormatReader]
|-
|'''NOAA'''
|N/A
|See below
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/NOAAFormatReader.html NOAAFormatReader]
|}

'''ACSOL file format''' (''Column text file'')

Column index: 
1:Julian day since 1950 
2:Seconds of the day (UTC) 
3:Flux at JD + seconds 
4-11 are the three-hours AP of the intervals

[[File:ACSOL.png|center]]

'''NOAA file format''' (''Column text file'')

Column index: 
1:Day 
2:Flux at the day 
3:The background flux 
4-11:the three-hours AP of the intervals 
12:Year 
13:Unused character flag

==== Pole data ====

These files contains earth orientation parameters (polar motion, LOD, etc.) used in frames transformation. 
These data are usually valid of a timespan of several days/months, although there is no theoretical limit.

{| class="wikitable"
|-
! scope="col"| Data type
! scope="col"| Data provider
! scope="col"| Format
! scope="col"| Reader
|-
|'''Bulletin B'''
|[http://hpiers.obspm.fr/eoppc/bul/bulb_new/]
|[https://datacenter.iers.org/productMetadata.php?id=207]
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/configuration/eop/BulletinBFilesLoader.html BulletinBFilesLoader]
|-
|'''EOP 05 C04'''
|[http://hpiers.obspm.fr/iers/eop/eopc04_05/]
|See below
|[<nowiki/>{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/configuration/eop/EOPC04FilesLoader.html EOPC04FilesLoader]
|-
|'''Datas "Rapid and Prediction" (TXT)'''
|[http://maia.usno.navy.mil/ser7]
|[http://maia.usno.navy.mil/ser7/readme.finals]
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/configuration/eop/RapidDataAndPredictionColumnsLoader.html RapidDataAndPredictionColumnsLoader]
|-
|'''Datas "Rapid and Prediction" (XML)'''
|[http://www.iers.org/IERS/EN/DataProducts/EarthOrientationData/eop.html]
|Same datas than the column file but write in the xml format
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/configuration/eop/RapidDataAndPredictionXMLLoader.html RapidDataAndPredictionXMLLoader]
|}

'''EOP 05 C04 files format''' (''Column text file'')

Column index: 
1:Date at 0h(UTC) 
2:Modified Julian Day 
3:x(") 
4:y(") 
5:UT1-UTC(s) 
6:LOD(s) 
7:DPsi(") 
8:DEps(") 
9:x error (") 
10:y error (") 
11:UT1-UTC error (s) 
12:LOD error(s) 
13:Dpsi error(") 
14:DEpsilon error(") 
x and y are the coordinales of the Celestial Ephemeris Pole. 
UT1: Universal time, the time of the earth clock 
LOD: Length Of Day is the excess of revolution time

[[File:EOP08C04.png|center]]

==== TAI-UTC shift====

These files contains TAI-TUC shift. Official data contains shift since the beginning of space era (1961).

{| class="wikitable"
|-
! scope="col"| Data type
! scope="col"| Data provider
! scope="col"| Format
! scope="col"| Reader
|-
|'''Gap TAI-UTC'''
|[https://hpiers.obspm.fr/eop-pc/index.php?index=TAI-UTC_tab&lang=en]
|See below
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/time/UTCTAIHistoryFilesLoader.html UTCTAIHistoryFilesLoader]
|}

'''TAI-UTC file format''' (''Column text file'')

Column index: 
1:Begining date-Ending date 
2:Difference TAI-UTC between the begining date and the ending date

[[File:TAI-TUC.png|center]]

==== Orbital data ====

These files are used to store orbital ephemeris. 
TLE provides orbit at one date. Ephemeris is then retrieved thanks to SGP4/SDP4 propagation model. 
SP3 files provide orbit over an extended time span (ex: 1 day).

{| class="wikitable"
|-
! scope="col"| Data type
! scope="col"| Data provider
! scope="col"| Format
! scope="col"| Reader
|-
|'''TLE'''
|Celestrack or others providers
|[https://ensatellite.com/tle/]
[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/propagation/analytical/tle/TLESeries.html TLESeries]
|-
|'''SP3'''
|GPS and GLONASS only [https://gssc.esa.int/portal/?vuePage=1&size=20&mode=map&sortOption=recent&resource_format=SP3]
|[https://files.igs.org/pub/data/format/sp3c.txt]
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/files/sp3/SP3File.html SP3File]
|}

Note: * SP3 files can be written by anyone. They are however mainly used ton provide GPS and GLONASS ephemeris.

Note2: * If the accuracy is not present in the SP3 file, a value of 0 automatically given. This allows the parsing of the SP3 to continue while giving the user the information that the accuracy field was not read (0 is an impossible value since the accuracy is given as 2^n).

==== Third body ephemeris ====

Third body ephemeris files contains ephemeris for third bodies (Moon, Sun, Jupiter) over an extended time span (ex: 1 or several days).

{| class="wikitable"
|-
! scope="col"| Data type
! scope="col"| Data provider
! scope="col"| Format
! scope="col"| Reader
|-
|'''JPL'''
|[https://ssd.jpl.nasa.gov/ephem.html]
|[https://ssd.jpl.nasa.gov/planets/eph_export.html]
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/JPLCelestialBodyLoader.html JPLCelestialBodyLoader]
|}

== Contents ==
=== Interfaces ===
The data package includes the following interfaces :

'''Data'''

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''DataLoader'''
|Interface for loading data files from DataProvider data providers.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/data/DataLoader.html ...]
|-
|'''DataProvider'''
|Interface for providing data files to DataLoader file loaders.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/data/DataProvider.html ...]
|}

=== Classes ===
The data package includes the following classes :

'''Data'''

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''DataProvidersManager'''
|This class is the single point of access for all data loading features.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/data/DataProvidersManager.html ...]
|-
|'''DirectoryCrawler'''
|This class handles data files recursively starting from a root directories.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/data/DirectoryCrawler.html ...]
|-
|'''NetworkCrawler'''
|This class handles a list of URLs pointing to data files or zip/jar on the net.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/data/NetworkCrawler.html ...]
|-
|'''ZipJarCrawler'''
|This class browses all entries in a zip/jar archive in filesystem or in classpath.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/data/ZipJarCrawler.html ...]
|}

== [[File:lightBulb.png]] Tips & Tricks ==
=== Strengths ===

* Lightweight implementation. The providers never load data, they merely provide streams on demand to the loaders.
* Scalable for using data from several heterogeneous sources.
* Scalable for new data types : the user only needs to create a new <code>DataLoader</code> implementation to use a new data type in this system.

=== Weaknesses ===

* The user must be aware the data loading overhead happens any time a <code>DataLoader</code> is fed, so the user must manage its loaders so that they are fed only once.
* Several sources for the same type of data cannot be used, since only the last provider added is used to feed data to a loader - unless the user manages the providers list accordingly, knowing one can only add elements or reset the whole list.
* The regexp is the only way to match a data file and a <code>DataLoader</code>.
* As of today, the data management system is a thread-hostile singleton : a multithreaded application shares the same providers list for all threads, and it may deadlock on a concurrent access!

User Manual 4.17 Force models

2025-12-12T13:38:32Z

Admin tsn :

== Introduction ==
=== Scope ===
The scope of this section is to present the force models available in PATRIUS. Forces models can be added to Patrius Numerical propagator.

=== Javadoc ===

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/package-summary.html Package fr.cnes.sirius.patrius.forces]
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/drag/package-summary.html Package fr.cnes.sirius.patrius.forces.drag]
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/package-summary.html Package fr.cnes.sirius.patrius.forces.gravity]
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/potential/package-summary.html Package fr.cnes.sirius.patrius.forces.gravity.potential]
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/variations/package-summary.html Package fr.cnes.sirius.patrius.forces.gravity.variations]
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/variations/coefficients/package-summary.html Package fr.cnes.sirius.patrius.forces.gravity.variations.coefficients]
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/tides/package-summary.html Package fr.cnes.sirius.patrius.forces.gravity.tides]
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/radiation/package-summary.html Package fr.cnes.sirius.patrius.forces.radiation]
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/radiation/package-summary.html Package fr.cnes.sirius.patrius.forces.radiation]
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/package-summary.html Package fr.cnes.sirius.patrius.forces]
|}

=== Links ===
'''Algorithms used'''

The algorithms used for the tides (earth and ocean) are taken from the FORTRAN code in ZOOM- see Manuel algorithmique OBELIX below. The routines used as references are given hereunder :
* f_maroce.f90
* fmf_ccadmt.f90
* obelixutil.f90
* mc_argfond.f90

The algorithms used for the rediffused radiation pressure are taken from OBELIX library. The routines used as references are given hereunder :
* fpr_elements
* fai_daccdd

The method used to compute the resulting acceleration is the same as that used in the [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/CunninghamAttractionModel.html Cunnigham attraction model].

'''Other Documents'''
* Manuel algorithmique OBELIX (Obelix-NT-12-1, version 4 révision 0 du 30/03/2012)

=== Useful Documents ===
* Cunningham; Leland E., ''On the computation of the spherical harmonic terms needed during the numerical integration of the orbital motion of an artificial satellite (Celestial Mechanics 2)'', Lockheed Missiles and Space Company, Sunnyvale and Astronomy Department University of California, Berkeley), 1970. Available [http://adsabs.harvard.edu/full/1970CeMec...2..207C here].
* Drozyner; A., ''Recurrent calculation of gravitational acceleration of a satellite'', Acta Astronomica, vol. 27, no. 1, 1977, p. 15-22. Available [http://adsabs.harvard.edu/full/1977AcA....27...15D here].

=== Package Overview ===
==== Parameterizable models====
Parameterizable models are supported. 
A parameter of a model can be define as Parameter (given its descriptor and value), a constant function, a linear function, a Nth order polynomial function, a piecewise function or an intervals function.

All parameters are handled in a the [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/parameter/Parameterizable.html Parameterizable] class. 
In case of a using a function for a model's paramater (Fx), the [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/parameter/Parameter.html Parameter] defined are automatically stored in the super class [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/parameter/Parameterizable.html Parameterizable]. 
Note that in this case, it is not Fx that is stored but ax and bx (with Fx = ax*t + bx).

==== Tides ====

The architecture of the <code>fr.cnes.sirius.patrius.forces.gravity.tides</code> package is given hereunder. The classes [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/tides/OceanTides.html OceanTides] and [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/tides/TerrestrialTides.html TerrestrialTides] extend [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/tides/AbstractTides.html AbstractTides].

Please note that not all implementations are present in the following diagram for the sake of clarity.

[[File:Tides.png|center]]

The architecture of the <code>fr.cnes.sirius.patrius.forces.gravity.tides.coefficients</code> package is given hereunder. The user must use the [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/tides/coefficients/OceanTidesCoefficientsFactory.html OceanTidesCoefficientsFactory class] to get an instance of the OceanTidesCoefficientsProvider interface, and pass it as an argument to the constructor of the [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/tides/OceanTidesDataProvider.html OceanTidesDataProvider class].

[[File:TidesCoeffs2.png|center]]

== Features Description ==
=== Available force models ===
The force models implemented are (by using DirectBodyAttraction as a wrapper for these gravity models) :
* Central gravity force (note that the harmonic gravity models have the central term contribution activated by default; it can be deactivated by means of the setCentralTermContribution(boolean) method of the AbstractHarmonicGravityModel abstract class) :
** Normalized attraction model : Balmino
** Unnormalized attraction models : Cunningham and Droziner
** Model defined by a grid with interpolated values: GridAttractionModel
* Third body gravity force (including harmonics)
* Atmospheric drag
** Based on DTM2000, DTM2012, JB2006, US76 and MSIS2000 atmosphere models and solar activity data
* Solar radiation pressure force
* Terrestrial tides: the earth tide is the deformation of the solid earth caused by the gravitational attraction of the Sun and moon. The standard used for constants and Love numbers is IERS 2003. The potential of the earth deformation is composed of 3 terms:
** the potential of earth tide: the potential is computed for degree 2 and takes into account complex Love numbers for long period (k20), diurnal (k21) and semi-diurnal (k22) terms. The potential for degree 3 is optional.
** the frequency correction of the Love numbers is also optional. It is applied on diurnal Love number (k21) [see Wahr and Zhu theory].
** the ellipticity correction is also optional. The ellipticity effect involves corrections on terms of degree 4 [see Wahr theory, 1981]
* Ocean Tides
* Solar pressure rediffused by the earth (albedo pressure and infrared emissivity pressure)
* Empirical forces

* Relativistic effects :
** Schwarzschild effect : the most important effect
** Coriolis effect (or geodetic precession)
** Lense-Thirring effect : due to the rotation of central body

The acceleration derivatives implemented are :

{| class="wikitable"
|-
! scope="col"| Force model
! scope="col"| wrt Position
! scope="col"| wrt Velocity
! colspan="3"| wrt additional parameters
|-
! colspan="3"|
! scope="col"| Parameter
! scope="col"| ParamDiffFunction
! scope="col"| Parameter or ParamDiffFunction from a model
|-
|'''Cunningham attraction'''
|yes
|no
|k
|no
|no
|-
|'''Balmino attraction'''
|yes
|no
|k
|no
|no
|-
|'''Droziner attraction'''
|no
|no
|k
|no
|no
|-
|'''Grid attraction model'''
|no
|no
|k
|no
|no
|-
|'''Newtonian attraction'''
|yes
|no
|k, MU
|no
|no
|-
|'''Variable potential model'''
|yes
|no
|k
|no
|no
|-
|'''Third body attraction'''
|yes
|no
|k
|no
|no
|-
|'''Drag force'''
|yes
|yes
|no
|no
|DragSensitive(AeroModel: Cx, Cn, Ct)
|-
|'''Direct solar radiation'''
|yes
|NA(null derivatives)
|Reference flux
|no
|RadiationSensitive(DirectRadiativeModel : k0, ka, ks, kd)
|-
|'''Rediffused solar radiation'''
|yes
|NA(null derivatives)
|no
|no
|RediffusedRadiationSensitive(RediffusedRadiativeModel : k0Ir, k0Al, ka, ks, kd)
|-
|'''Empirical force'''
|NA(null derivatives)
|NA(null derivatives)
|no
|AX_COEFFICIENT, AY_COEFFICIENT, AZ_COEFFICIENT, BX_COEFFICIENT, BY_COEFFICIENT, BZ_COEFFICIENT, CX_COEFFICIENT, CY_COEFFICIENT, CZ_COEFFICIENT
|no
|-
|'''Ocean tides'''
|yes
|NA(null derivatives)
|no
|no
|no
|-
|'''Terrestrial tides'''
|yes
|NA(null derivatives)
|no
|no
|no
|-
|'''Schwarzschild'''
|yes
|yes
|no
|no
|no
|-
|'''Coriolis'''
|NA(null derivatives)
|yes
|no
|no
|no
|-
|'''Lense-Thirring'''
|yes
|yes
|no
|no
|no
|}

Note : The partial derivatives of the Balmino acceleration model are that of the Cunningham attraction model. They are thus limited in degree and order (sum should be lower or equal than approx. 160).

=== Gravity potential ===
==== Static potential models ====

The data is read through the Orekit <code>DataLoader</code> infrastructure; it provides several ways to load gravitational data. Please see the [[User Manual 3.4.1 Data management system|Data Management System section]] for more information.

The user access point is the <code>GravityFieldFactory</code> which automatically detects available files and uses the adequate loader. If no file is specified by the user, this factory uses the first available file.

The normalized attraction model is more accurate that the unnormalized attraction models in that it allows computing gravity fields to a much higher degree / order.

'''Warning''' : using a 0x0 Earth potential model (Cunningham, Drozyner, Balmino, etc.) is equivalent to a simple Newtonian attraction. However computation times will be much slower since this case is not particularized and hence conversion from body frame (often ITRF) to integration frame is necessary.

==== Variable potential models ====

The data is read through the Orekit <code>DataLoader</code> infrastructure; it provides several ways to load gravitational data. Please see the [[User Manual 4.1 Data management system|Data Management System section]] for more information.

The user access point is the <code>VariableGravityFieldFactory</code> which automatically detects available files and uses the adequate loader. If no file is specified by the user, this factory uses the first available file.

Regarding the corrections computation, the user has three choices :
* not to take any corrections into account, using the first constructor (VariablePotentialAttractionModel(Frame, VariablePotentialCoefficientsProvider, int, int))
* compute corrections at instanciation only (see code snippet hereunder),
* compute corrections every time.

The user specifies, with the computeAtEachCall boolean set to true, if corrections are to be recomputed each time.

<syntaxhighlight lang="java">
// Get the variable potential data provider
final VariablePotentialCoefficientsProvider provider = VariableGravityFieldFactory.getVariablePotentialProvider();
// Variable potential force model
final int degree = 80;
final int order = 80;
final int degreeOptional = 50;
final int orderOptional = 50;
final boolean computeAtEachCall = true;
final VariablePotentialAttractionModel grav = new VariablePotentialAttractionModel(FramesFactory.getITRF(),
provider, degree, order, degreeOptional, orderOptional, computeAtEachCall);
</syntaxhighlight>

The <code>grav</code> force model can then be used with the numerical propagator.

==== Static grid potential model ====

For small bodies where body cannot be considered as spherical with uniform gravity field, a class <code>GridAttractionModel</code> can be used. This class loads a static gravity field and then interpolate potential and attraction data at user required position.
This class requires at construction:
* A <code>GridAttractionProvider</code>: this is a generic provider providing potential and acceleration at grid points. Currently two implements are available: <code>CartesianGridAttractionLoader</code> (for cartesian grids) and <code>SphericalGridAttractionLoader</code> (for spherical grids).
* An 3D interpolator <code>TrivariateGridInterpolator</code>. Currently two interpolators are available: linear (<code>TriLinearIntervalsInterpolator</code>) and Spline (<code>TricubicSplineInterpolator</code>).
* A back-up attraction model <code>ForceModel</code> which will be used if requested position is out of grid boundaries (for instance Cunhingham, Droziner or event Newtonian model).
* The body Frame
This model then works like any other force model: it can be used in a numerical propagator.

'''Warning''': when using this model, Newtonian attraction included in numerical propagator should be disabled! In order to do so, call the method <code>Numericalpropagator.disableNewtonianAttraction()</code>

=== Tides ===

In the very same way, the user access point to Ocean Tides Coefficients is the <code>OceanTidesCoefficientsFactory</code> which automatically detects available files and uses the adequate loader. If no file is specified by the user, this factory uses the first available file. The loaded data can then be used by the <code>OceanTides</code> model.

<syntaxhighlight lang="java">
// Directory containing the file fes2004_gr
final File tiDir = new File("/my/data/gravity/tides");
// The directory is given to the data loader
DataProvidersManager.getInstance().addProvider(new DirectoryCrawler(tiDir));
// The FES2004 file is registered in the OceanTidesCoefficientsFactory
OceanTidesCoefficientsFactory.addOceanTidesCoefficientsReader(new FES2004FormatReader("fes2004_gr"));
// A provider for the FES2004 data is created
final OceanTidesCoefficientsProvider provider = OceanTidesCoefficientsFactory.getCoefficientsProvider();
// Get the C± ans S± coefficients and C± and ε± for a given Doodson number
final double doodson = 65.555;
final int order = 2;
final int degree = 1;
final double[] CS = provider.getCpmSpm(doodson, order, degree);
final double[] CE = provider.getCpmEpm(doodson, order, degree);
</syntaxhighlight>

The [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/tides/OceanTides.html OceanTides] uses a [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/tides/OceanTidesDataProvider.html OceanTidesDataProvider] which uses itself a [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/tides/coefficients/OceanTidesCoefficientsProvider.html OceanTidesCoefficientsProvider], such as the [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/tides/coefficients/FES2004FormatReader.html FES 2004 format reader class], and calls the <code>getCpmSpm(double, double, double)</code> methods internally. When the user has created an instance of the [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/tides/OceanTidesDataProvider.html OceanTidesDataProvider] class, he can pass it on to the constructor of [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/tides/OceanTides.html OceanTides], like so :

<syntaxhighlight lang="java">
final Frame earthFrame = FramesFactory.getITRF();
final double earthRadius = 6378136.;
final double mu = Constants.EIGEN5C_EARTH_MU;
final double density = 1025;
final int degree = 10;
final int order = 10;
final boolean ignoreSecondaryWaves = true;

final OceanTidesCoefficientsProvider coefficientsProvider = OceanTidesCoefficientsFactory.getCoefficientsProvider();
final TidesStandard convention = TidesStandard.GINS2004;
final OceanTidesDataProvider dataProvider = new OceanTidesDataProvider(coefficientsProvider, convention);

final OceanTides tides = new OceanTides(earthFrame, earthRadius, mu,
density, degree, order, ignoreSecondaryWaves, dataProvider);
</syntaxhighlight>

The [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/tides/TerrestrialTides.html TerrestrialTides] uses a [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/tides/TerrestrialTidesDataProvider.html TerrestrialTidesDataProvider]. When the user has created an instance of the [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/tides/TerrestrialTidesDataProvider.html TerrestrialTidesDataProvider] class, he can pass it on to the constructor of [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/tides/OceanTides.html OceanTides], like so :
<syntaxhighlight lang="java">
final List<CelestialBody> bodies = new ArrayList<CelestialBody>();
bodies.add(CelestialBodyFactory.getSun());
bodies.add(CelestialBodyFactory.getMoon());
final TerrestrialTides terrestrialTides = new TerrestrialTides(earthFrame, earthRadius, mu, bodies, false, false, false, new TerrestrialTidesDataProvider());
</syntaxhighlight>

=== Drag force ===
Before implementing the drag force, one has to define a vehicle with aerodynamic properties. To do so, it is advised to consult the page about [SPC_FORCES_Home assembly models for force models]. Given an assembly with the right aerodynamic properties, the user can create an instance of [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/assembly/models/AeroModel.html AeroModel] or [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/assembly/models/DragLiftModel.html DragLiftModel], and use it to create an instance of DragForce.

The implementation of the DragForce class allows at construction to take in account a multiplicative coefficient on the drag acceleration.
Let k be this coefficient, then the attribute k instance of IParamDiffFunction can be instantiated in the following constructors :

<syntaxhighlight lang="java">
// Simple constructor with multiplicative factor k = 1.0
public DragForce(final Atmosphere atmosphere, final DragSensitive spacecraft)

// Constructor for k being a double
public DragForce(final double k, final Atmosphere atmosphere, final DragSensitive spacecraft)

// Constructor for k being a Parameter
public DragForce(final Parameter k, final Atmosphere atmosphere, final DragSensitive spacecraft)

// General constructor for k being an IParamDiffFunction
// This constructor is called by the others
public DragForce(final IParamDiffFunction k, final Atmosphere atmosphere, final DragSensitive spacecraft)
</syntaxhighlight>

In the main constructor, the derivable parameters of function k are stored in the jacobians parameters list the via the method
<code> addJacobiansParameter </code>, the other in the parameters list via <code> addParameter </code>.

==== Partial derivatives ====

The drag force model allows the user to compute the partial derivatives of the atmospheric drag acceleration, only for a spherical spacecraft; the available derivatives are the following:

* with respect to the spacecraft position in the inertial frame;
* with respect to the spacecraft velocity in the inertial frame;
* with respect to the drag coefficient (Cx);
* with respect to parameters of function k which are derivable.

===== Partial derivatives with respect to spacecraft position =====

The derivatives with respect to position require the derivative of the atmospheric density with respect to the altitude <math>\frac{\partial \rho }{\partial h}</math>, which is computed by finite differences by a method of altitude variation. We present here the case where the DragSensitive used is an instance of <code>AeroModel</code>.

They are given by MontenBruck, "Satellite Orbit", according the following equation : 
<math>\frac{\partial^{2} {r}} {\partial {r}} = - \frac{1}{2} C_{d} \frac{S}{m} ||v_r|| v_r \frac{\partial \rho }{\partial r}- \frac{\partial^{2} {r}} {\partial {v}} X(\omega_{Earth})</math>

where <math>v_r</math> is the relative velocity such that <math>v_r = v- \omega_{Earth} \times r</math>. 
Moreover, we have :

<math>X(\omega) = \left( \begin{array}{ccc}
0 &-\omega_{z} & \omega_{y} \\
\omega_{z} & 0 &-\omega_{x} \\
-\omega_{y} & \omega_{x} & 0 \end{array} \right)</math> and <math>\frac{\partial \rho }{\partial r} = (\frac{\partial \rho}{\partial x}, \frac{\partial \rho}{\partial y}, \frac{\partial \rho}{\partial z})</math>

The density partial derivatives are computed by considering the variation of density while the altitude varies : 
<math>\delta r = r (1 + \frac{step_{alt}} {||r||} )</math> 
<math>\delta \rho = \frac{\rho(r + \delta r)- \rho(r)}{step_{alt}}</math> 
<math>\frac{\partial \rho }{\partial r} = (\cos(long) \cos(lat) \delta \rho,\sin(long) \cos(lat) \delta \rho,\sin(lat) \delta \rho)</math>

where <math>step_{alt}</math> can be chosen at construction of the <code>AeroModel</code> (equal to 10m by default).

===== Partial derivatives with respect to spacecraft velocity =====

The partial derivatives of the drag force with respect to the spacecraft velocity in the inertial frame are computed using the exact equations.

===== Partial derivatives with respect to the drag coefficient (Cx) =====

The partial derivatives of the drag force with respect to the drag coefficient are computed using the exact equations. 
Note that the ballistic coefficient for a spherical spacecraft is equal to <math>{B}_{c}=\frac{S {C}_{X}}{M}</math>, where <math>S</math> is the cross-sectional area of the sphere, <math>{C}_{X}</math> is the drag coefficient and <math>M</math> is the mass.

===== Partial derivatives with respect to k parameters =====

The partial derivatives of the drag force with respect to k parameters are simply computed by multiplying the drag acceleration by the partial derivative value of k with respect to the considered parameter.

=== Solar radiation pressure ===
Before implementing the solar radiation pressure or the rediffused solar radiation pressure, one has to define a vehicle with radiative properties. To do so, it is advised to consult the page about [SPC_FORCES_Home forces models using the assembly].

==== Direct solar radiation pressure ====

Direct solar radiation pressure is the force created by Sun photons impacting the spacecraft. The class is <code>SolarRadiationPressure</code>.
It provides the following features:
* Any occulting body can be provided (Earth, Moon, etc.). Multiple occulting bodies can be added using method <code>addOccultingBody</code>. By default, one occulting body is included at construction.
* Eclipses computation can be deactivated through method <code>setEclipsesComputation</code>. By default eclipses computation are activated.

Before implementing the solar radiation pressure (that takes into account Earth flattening), one has to define a vehicle with radiative properties. To do so, it is advised to consult the page which describes how to build and use [SPC_VEH_Home the Assembly] ([SPC_VBU_Home see also...]).

The following code snippet allows the user to create an instance of the ForceModel class that can be passed to the NumericalPropagator. This instance will calculate the SRP by computing penumbra and umbra events for a flattened Earth.

<syntaxhighlight lang="java">
// Constants
final double ae = 6.3781360000000000E+06;
final double f = 3.3528040724231161E-03;

// ITRF frame
final Frame itrf = FramesFactory.getITRF();

// Sun and Earth
final CelestialBody sun = CelestialBodyFactory.getSun();
final BodyShape earth = new OneAxisEllipsoid(ae, f, itrf, "earth");

// Assembly definition
final AssemblyBuilder builder = new AssemblyBuilder();
final String mainPart = "satellite";
builder.addMainPart(mainPart);
builder.addProperty(new RadiativeProperty(1, 0, 0), mainPart);
builder.addProperty(new MassProperty(mass), mainPart);
builder.addProperty(new RadiativeSphereProperty(1), mainPart);

// The RadiationSensitive instance
final DirectRadiativeModel sc = new DirectRadiativeModel(builder.returnAssembly());

// SRP
final SolarRadiationPressure srp = new SolarRadiationPressure(sun, earth, sc);
</syntaxhighlight>

==== Rediffused solar radiation pressure ====

Example for the rediffused solar radiation pressure implementation :

<syntaxhighlight lang="java">
// sun ephemerides
CelestialBodyFactory.clearCelestialBodyLoaders();
final JPLCelestialBodyLoader loader = new JPLCelestialBodyLoader("unxp2000.405",
EphemerisType.SUN);
final CelestialBody sun = loader.loadCelestialBody(CelestialBodyFactory.SUN);

// emissivity model
final IEmissivityModel modelE = new KnockeRiesModel();

// build the assembly
final AssemblyBuilder builder = new AssemblyBuilder();
.
.
.
final Assembly assembly = builder.returnAssembly();

// RSRP model (albedo=true/false, ir=true/false, albedo global multiplicative factor=1,
//infrared global multiplicative factor=1
final RediffusedRadiativeModel RSRP = new RediffusedRadiativeModel(albedo, ir, 1, 1, assembly);

// RSRP force, number of corona, number of meridian=10
final RediffusedRadiationPressure f = new RediffusedRadiationPressure(sun, FramesFactory.getITRF(),
10, 10, modelE, RSRP);
</syntaxhighlight>

It is also possible to compute these forces using assemblies, as seen in the [SPC_VEH_Home spacecraft chapter]. 
'''Warning''': This model is valid only if the number of corona and the number of meridian are higher than (5,5).

=== Relativistic Effects ===

The computation of the relativistic effects is available in PATRIUS, in the force models. The model used to represent these effects is composed of 3 terms :
* the Schwarzschild term, which is the most important
* the Coriolis term, also known as the geodetic precession term
* the Lense-Thirring term, involving the rotation of the considered central body

Three classes (one for each effect) are implemented in the package <code>fr.cnes.sirius.patrius.forces.relativistic</code>. The SchwarzschildRelativisticEffect, CoriolisRelativisticEffect, and LenseThirringRelativisticEffect implement the <code>ForceModel</code> and <code>GradientModel</code> interfaces like all force models classes, and extend <code>JacobianParameterizable</code>.

The following sections focus on each relativistic effect. 
Implementing the same <code>ForceModel</code> interface, the computation of the acceleration is available via the method <code>computeAcceleration(final SpacecraftState s)</code>. 
Also, the computation of the acceleration partial derivatives with respect to state (position and velocity) is available via <code>addDAccDState(final SpacecraftState s, final double[][] dAccdPos, final double[][] dAccdVel)</code>. 
The computation of partial derivatives with respect to parameters in <code>addDAccDParam(final SpacecraftState s, final Parameter param, final double[] dAccdParam)</code> raise an exception since no parameter is supported by these force models.

==== Schwarzschild effect ====

An instance of the class SchwarzschildRelativisticEffect can be created using one of the following constructor:

<syntaxhighlight lang="java">public SchwarzschildRelativisticEffect(final double mu, final boolean computePartialDerivativesPos, final boolean computePartialDerivativesVel)</syntaxhighlight>

<syntaxhighlight lang="java">public SchwarzschildRelativisticEffect(final double mu)</syntaxhighlight>

where mu is the central attraction coefficient, the boolean allowing the computation (or not) of the partial derivatives. In the second constructor, booelan are set to true.

The acceleration due to the Schwarzschild effect is analytically computed using the formula:

<math>\vec{a}_{sch} = \frac{\mu} {c^{2} r^{3}} ((4 \frac{{\mu}}{r}- v^{2}) \vec{r} + 4 (\vec{v}.\vec{r}) \vec{v})</math>

where :
* <math>\vec{r}</math> is the spacecraft position in an inertial centered central body frame
* <math>\vec{v}</math> is the spacecraft velocity in an inertial centered central body frame
* <math>\mu</math> is the attraction coefficient of the central body <math>(m^3 s^{-2})</math>
* <math>c</math> the constant speed of light

The partial derivatives with respect to state are computed with the following formulae :

<math>(\frac{\partial a_{i,sch}}{\partial r_j})_{1 \leq i,j \leq 3} = \frac{-3 r_j}{r^2} a_{i,sch} + \frac{\mu} {c^{2} r^{3}} (\frac{-4 \mu r_j}{r^3} r_i + (4 \frac{\mu}{r}- v^2) \delta_{ij} + 4 v_j v_i)</math>

<math>(\frac{\partial a_{i,sch}}{\partial v_j})_{1 \leq i,j \leq 3} = \frac{\mu} {c^{2} r^{3}} (-2 v_j r_i + 4 r_j v_i + 4 (\vec{v}.\vec{r}) \delta_{ij})</math>

<math>\delta_{ij}</math> being the Kronecker symbol.

==== Coriolis effect ====

An instance of the class CoriolisRelativisticEffect can be created using one of the following constructor:

<syntaxhighlight lang="java">public CoriolisRelativisticEffect(final double muSun, final PVCoordinatesProvider sun, final boolean computePartialDerivativesVel)</syntaxhighlight>

<syntaxhighlight lang="java">public CoriolisRelativisticEffect(final double muSun, final PVCoordinatesProvider sun)</syntaxhighlight>

where
* muSun is the central attraction coefficient of the Sun
* sun represent the sun PV coordinates in an inertial body centered frame
* axis is an orthogonal axis to the ecliptic plane of the body.

In the second constructor, boolean is set to true.

The acceleration due to the Coriolis effect is analytically computed using the formula:

<math>\vec{a}_{cor} = 2 \vec{\Omega}_{cor} \times \vec{v}</math>

with :
* <math>\mu_{Sun}</math> the attraction coefficient of the Sun
* <math>{r}_{body/Sun}</math> the distance between Sun and the central body
* <math>\vec{u}_{z,ecl}</math> the normal axis to the ecliptic plane of the body

<math>\vec{\Omega}_{cor} = \frac{-3}{2} \frac{\mu_{Sun}}{c^2 {r^3}_{Sun}} (\vec{v}_{Sun} \times \vec{r}_{Sun})</math>

Note that this formula for <math>\vec{\Omega}_{cor}</math> is valid for a IERS2003 model.

with :
* <math>\vec{r}_{Sun}</math> the position of the Sun in an inertial body centered frame
* <math>\vec{v}_{Sun}</math> the velocity of the Sun in an inertial body centered frame

The partial derivatives with respect to velocity are computed with the following formula :

<math>(\frac{\partial a_{i,cor}}{\partial v_j})_{1 \leq i,j \leq 3} = 2 \left( \begin{array}{ccc}
0 &-\Omega_{cor,3} & \Omega_{cor,2} \\
\Omega_{cor,3} & 0 &-\Omega_{cor,1} \\
-\Omega_{cor,2} & \Omega_{cor,1} & 0 \end{array} \right)</math>

if we denote <math>\vec{\Omega}_{cor} = (\Omega_{cor,1} \hspace{0.4cm} \Omega_{cor,2} \hspace{0.4cm} \Omega_{cor,3})^T</math>. We show easily that the derivatives with respect to the position are null.

==== Lense-Thirring effect ====

An instance of the class LenseThirringRelativisticEffect can be created using one of the following constructor:

<syntaxhighlight lang="java">public LenseThirringRelativisticEffect(final double mu, final Frame frame, final boolean computePartialDerivativesPos, final boolean computePartialDerivativesVel)</syntaxhighlight >

<syntaxhighlight lang="java">public LenseThirringRelativisticEffect(final double mu, final Frame frame)</syntaxhighlight>

where
* mu is the central attraction coefficient
* frame defines pole of the central body

In the second constructor, boolean are set to true.

The acceleration due to the Lense-Thirring effect is analytically computed using the formula (IERS 20003 standard):

<math>\vec{a}_{LT} = 2 \frac{\mu}{c^2 r^3} (\frac{3}{r^2} (\vec{r}.\vec{J}) \vec{r}- \vec{J}) \times \vec{v}</math>

where :

* <math>\vec{J} = 9.8* 10^8 \hspace{0.4cm} \vec{u}_{z,Earth}</math> is the Earth angular momentum.

Finally, the partial derivatives are computed with the following formulae:

<math>(\frac{\partial a_{i,LT}}{\partial r_j})_{1 \leq i,j \leq 3} = \frac{-3 r_j}{r} a_{i,LT} + \frac{6 \mu} {c^2 r^5} ((J_j- \frac{2 r_j} {r^2} (\vec{r}.\vec{J})) (\vec{r} \times \vec{v})_i + (\vec{r}.\vec{J}) \frac{\partial}{\partial r_j} (\vec{r} \times \vec{v})_i)</math>

<math>(\frac{\partial a_{i,LT}} {\partial v_j})_{1 \leq i,j \leq 3} = \left( \begin{array}{ccc}
0 &-\Omega_{LT,3} & \Omega_{LT,2} \\
\Omega_{LT,3} & 0 &-\Omega_{LT,1} \\
-\Omega_{LT,2} & \Omega_{LT,1} & 0 \end{array} \right)</math>

where

<math>(\frac{\partial}{\partial r_j} (\vec{r} \times \vec{v})_i)_{1 \leq i,j \leq 3} = \left( \begin{array}{ccc}
0 & v_3 &-v_2 \\
-v_3 & 0 &-v_1 \\
v_2 & v_1 & 0 \end{array} \right)</math>

and <math>\Omega_{LT} = \frac{\mu}{c^2 r^3} ( \frac{3}{r^2}(\vec{r}.\vec{J}) \vec{r}- \vec{J})</math>

=== Thrust ===
Thrust models include:
* Continuous thrust maneuver
* Constant thrust error

Note that impulse thrust are defined as events.

==== Continuous thrust maneuver ====

The <code>ContinuousThrustManeuver</code> class implements the <code>ForceModel</code> interface. 
Maneuvers can be defined providing values for thrust, ISP fuel tank using <code>TankProperty</code> and <code>PropulsiveProperty</code> and the acceleration direction and its related frame:

<syntaxhighlight lang="java">ContinuousThrustManeuver(final AbsoluteDate date, final double duration, final PropulsiveProperty engine,
final Vector3D direction, final MassProvider massProvider, final TankProperty tank)</syntaxhighlight>

More information on these properties are available at [SPC_FORCES_Prop4 TankProperty] and [SPC_FORCES_Prop5 PropulsiveProperty].

==== Constant thrust error ====

The <code>ConstantThrustError</code> class implements the <code>ForceModel</code> interface like the <code>ContinuousThrustManeuver</code> class. The constant thrust error model is a fictitious force model used to compute the difference between the expected maneuver and the actual one. The user defines the three functions representing the three components (x, y, z) of the error as well as the thrust start and end (which can be defined either by its start date and its duration or using event detectors). These functions can depend on parameters. Thrust start and stop criterion can be defined in two different ways (see below).
Being a force model, an acceleration value (the error value) can be computed at any date. Moreover, the partial derivatives of the error at any date with respect to the parameters are available via the method '''computeDerivative(SpacecraftState, Parameter)'''.

'''Maneuver start and stop criterion can either be defined:'''

◦ With a start date and a duration (former method) 
◦ With event detectors, first detector for starting the thrust, second detector for stopping the thrust. Action.STOP is required to trigger (start/stop) the thrust. Any other action will be discarded. When using event detectors, pay attention to events that may occur several times. If you want the thrust to perform only once, the event detectors the event detectors have to be included in a nth occurrence detector or its <code>shouldBeRemoved()</code> method have to return <code>true</code>. Otherwise the thrust may be performed more than once: if a thrust starts at the perigee (using a perigee detector) and stops at the apogee (using an apogee detector), then the thrust will start at every perigee and stop at every apogee.

=== Empirical force ===
The <code>EmpiricalForce</code> class provides a model describing a generic empirical force; an empirical force is a "pseudo acceleration" with the same frequency of the spacecraft orbital frequency (or a multiple of this frequency). One or more instances of this force can be added to a propagator in order to represent a more complex empirical force model.

Given a local frame (usually a LOF frame), and three vectors A, B and C defined in this frame, the acceleration in this local frame due to empirical force is the following: 
<math>\overrightarrow{a}_{local}=\overrightarrow{A}\cos(n\omega t) + \overrightarrow{B}\sin(n\omega t) + \overrightarrow{C}</math> 
n is the harmonic factor and <math>\omega</math> is the orbital period. 
As <math>\omega</math> is usually unknown, <math>\cos(n\omega t)</math> and <math>\sin(n\omega t)</math> are computed from the orbital position of the spacecraft:

* when the orbit is highly inclined, the orbital position can be computed from the position of the ascending node;

* when the orbit is heliosyncronous, the orbital position can be computed from the projection of the Sun in the orbital plane;

The user is free to choose a reference vector <math>\overrightarrow{S}</math> that, once projected in the orbital plane, defines a reference direction used to compute the spacecraft position and then <math>\cos(n\omega t)</math> and <math>\sin(n\omega t)</math>.

Components of the vectors A, B and C can be defined as parameter and/or parameterizable functions :

<syntaxhighlight lang="java">
final int harmoCoef = 1;
EmpiricalForce f = new EmpiricalForce(harmoCoef, Vector3D.PLUS_K,
new LinearFunction(new AbsoluteDate(), new Parameter("ax", 1), new Parameter("bx", 2)),
new ConstantFunction(new Parameter("ay", 1)),
new ConstantFunction(new Parameter("az", 0)),
new LinearFunction(new AbsoluteDate(), new Parameter("by", 1), new Parameter("b", 2)),
new ConstantFunction(new Parameter("by", 1)),
new ConstantFunction(new Parameter("bz", 0)),
new LinearFunction(new AbsoluteDate(), new Parameter("bz", 1), new Parameter("b", 2)),
new ConstantFunction(new Parameter("cy", 1)) ,
new ConstantFunction(new Parameter("cz", 0)),
LOFType.TNW);
</syntaxhighlight>

== Getting Started ==

In this section, code samples are given in order to show user how to define some forces and how to correctly set the propagator by passing it these forces.

=== Static potential models ===

The following code sample shows how to set a gravity potential model (static) :

<syntaxhighlight lang="java">
// Directory containing the file grim5_C1.dat
final File potdir = new File("/my/data/gravity/potential");
// The directory is given to the data loader
DataProvidersManager.getInstance().addProvider(new DirectoryCrawler(potdir));
// The GRGS file is registered in the GravityFieldFactory
GravityFieldFactory.addPotentialCoefficientsReader(new GRGSFormatReader("grim5_C1.dat", true));
// A provider for the GRGS data is created
final PotentialCoefficientsProvider provider = GravityFieldFactory.getPotentialProvider();

// Get the tesserial-sectorial and zonal coefficients,
// degree 5, order 3, normalized
// normalized Cosine coefficients
final double[][] normalizedC = provider.getC(5, 3, true);
// normalized Sine coefficients
final double[][] normalizedS = provider.getS(5, 3, true);

// degree 5, order 3, normalized
// unnormalized Cosine coefficients
final double[][] unnormalizedC = provider.getC(5, 3, false);
// unnormalized Sine coefficients
final double[][] unnormalizedS = provider.getS(5, 3, false);

// Balmino model : normalized
final Frame itrfFrame = FramesFactory.getITRF();
final double mu = Constants.GRIM5C1_EARTH_MU;
final double ae = Constants.GRIM5C1_EARTH_EQUATORIAL_RADIUS;

final BalminoAttractionModel balmino = new BalminoAttractionModel(itrfFrame, ae, mu, normalizedC, normalizedS);

// Cunningham model : unnormalized- Same as DrozinerAttractionModel
final CunninghamAttractionModel Cunningham = new CunninghamAttractionModel(itrfFrame, ae, mu, normalizedC, normalizedS);
</syntaxhighlight>

=== Drag force ===

Hereunder the steps to define an instance of <code>DragForce</code>.

<syntaxhighlight lang="java">
// sun ephemerides
CelestialBodyFactory.clearCelestialBodyLoaders();
final JPLEphemeridesLoader loader = new JPLEphemeridesLoader("unxp2000.405",
JPLEphemeridesLoader.EphemerisType.SUN);

final JPLEphemeridesLoader loaderEMB = new JPLEphemeridesLoader("unxp2000.405",
JPLEphemeridesLoader.EphemerisType.EARTH_MOON);
final JPLEphemeridesLoader loaderSSB = new JPLEphemeridesLoader("unxp2000.405",
JPLEphemeridesLoader.EphemerisType.SOLAR_SYSTEM_BARYCENTER);

CelestialBodyFactory.addCelestialBodyLoader(CelestialBodyFactory.EARTH_MOON, loaderEMB);
CelestialBodyFactory.addCelestialBodyLoader(CelestialBodyFactory.SOLAR_SYSTEM_BARYCENTER, loaderSSB);

loader.loadCelestialBody(CelestialBodyFactory.SUN);

final PVCoordinatesProvider sun = CelestialBodyFactory.getSun();

// DTM2000 atmosphere
final Frame itrf = FramesFactory.getITRF();
final OneAxisEllipsoid earth = new OneAxisEllipsoid(6378136.460, 1.0 / 298.257222101, itrf);
SolarActivityDataFactory.addSolarActivityDataReader(new ACSOLFormatReader(
SolarActivityDataFactory.ACSOL_FILENAME));
final SolarActivityDataProvider data = SolarActivityDataFactory.getSolarActivityDataProvider();
final DTMSolarData in = new DTMSolarData(data);
earth.setAngularThreshold(1e-10);
final DTM2000 atm = new DTM2000(in, sun, earth);

// aero model of the assembly
final AeroModel model = new AeroModel(createAssemblyWithAeroProperties());

// force
final ForceModel drag = new DragForce(atm, model);
</syntaxhighlight>

The following lines show how to set the proper configuration in order to compute the derivatives defined by given equations (see part Partial derivatives with respect to spacecraft position) :

<syntaxhighlight lang="java">
// create the spherical spacecraft:
final AssemblyBuilder builder = new AssemblyBuilder();
// add main part (one sphere)
builder.addMainPart("MAIN_BODY");
// sphere property
final double radius = 10.;
final double cx = 2.;
final AeroSphereProperty asp = new AeroSphereProperty(radius, cx);
builder.addProperty(asp, "MAIN_BODY");
// adding aero properties
// one facet
final Vector3D normal = Vector3D.PLUS_J;
final double area = 10.;
final Facet facet = new Facet(normal, area);
// aero facet property
final double cn = 2., ct = 1.;
final IPartProperty aeroFacetProp = new AeroFacetProperty(facet, cn, ct);
builder.addProperty(aeroFacetProp, "MAIN_BODY");
// adding mass properties
final IPartProperty massMainProp = new MassProperty(100.);
builder.addProperty(massMainProp, "MAIN_BODY");
// assembly creation
final Assembly assembly = builder.returnAssembly();

// create the atmosphere:
final double ae = Constants.GRIM5C1_EARTH_EQUATORIAL_RADIUS;
final double f = Constants.GRIM5C1_EARTH_FLATTENING;
final Atmosphere atmosphere = new SimpleExponentialAtmosphere(
new OneAxisEllipsoid(ae, 1.0 / 298.257222101, FramesFactory.getITRF()), 0.0004, 42000.0, 7500.0);

// Build an AeroModel with an atmosphere model and a GeodPosition
//(compulsory for density partial derivatives computation)
final GeodPosition geodPos = new GeodPosition(ae, f)
final AeroModel aeroModel = new AeroModel(assembly, atmosphere, geodPos);

// create the drag force:
final DragForce force = new DragForce(atmosphere, aeroModel);</syntaxhighlight>

=== Constant thrust error ===

Here is an example of how to define a constant thrust error model:
<syntaxhighlight lang="java">
AbsoluteDate date = new AbsoluteDate(2005, 03, 01, TimeScalesFactory.getTAI());
double duration = 360;
Parameter ax = new Parameter("ax", 1.e-12);
Parameter ay = new Parameter("ay", 2.e-12);
Parameter az = new Parameter("az", 3.e-12);
Parameter bx = new Parameter("bx", 4.e-12);
Parameter by = new Parameter("by", 5.e-12);
Parameter bz = new Parameter("bz", 6.e-12);
Parameter cx = new Parameter("cx", 7.e-12);
Parameter cy = new Parameter("cy", 8.e-12);
Parameter cz = new Parameter("cz", 9.e-12);
IParamDiffFunction fx = new QuadraticFunction(date, ax, bx, cx);
IParamDiffFunction fy = new QuadraticFunction(date, ay, by, cy);
IParamDiffFunction fz = new QuadraticFunction(date, az, bz, cz);
ConstantThrustError error = new ConstantThrustError(date, duration, LOFType.TNW, fx, fy, fz);
</syntaxhighlight>

== Propagator settings : force models and events ==

Forces implement the <code>ForceModel</code> interface (true for all forces except ImpulseManeuver). They are intended to be used with the <code>NumericalPropagator</code>. The <code>addForceModel(ForceModel)</code> will add a ForceModel to the list of forces the propagator uses at each step.

The simplest way to include a force in the dynamic model is to make an instance of it and to add it to the propagator. Given a <code>ForceModel force</code>, one can use the following code :

<syntaxhighlight lang="java">
myPropagator.addForceModel(force);
</syntaxhighlight>

Note that the NumericalPropagator and the MultiNumericalPropagator do not use anymore the Newtonian gravity model by default. It should now be added manually to the list of the force models before starting the propagation.

Please refer to the [ORB_PGEN_Home Propagation page ] for more information.

Nota : The ImpulseManeuver force does not implement the ForceModel interface. It implements the EventDetector and should be handled as such (see code below). For more information about Events, please refer to the [MIS_EVT_Home Events section].

<syntaxhighlight lang="java">
myPropagator.addEventDetector(myImpulse);
</syntaxhighlight>

Important note: forces implement also the <code>GradientModel</code> necessary to provide partial dérivatives computation information. If creating a force model and wishing to compute partial dérivatives, the created force should both inherit <code>ForceModel</code> and <code>GradientModel</code>.

== Contents ==
=== Interfaces ===
{| class="wikitable"
|-
! scope="col"| Interface
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''ForceModel'''
|This interface represents a force modifying spacecraft motion.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/ForceModel.html ...]
|-
|'''GradientModel'''
|This interface provides information about partial derivatives computation.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/GradientModel.html ...]
|-
|'''GravityModel'''
|This interface provides information about gravitational attraction models.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/GravityModel.html ...]
|-
|'''AbstractGravityModel'''
|This abstract class represents a gravitational attraction model.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/AbstractGravityModel.html ...]
|-
|'''AbstractHarmonicGravityModel'''
|This abstract class represents a gravitational attraction model with harmonics.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/AbstractHarmonicGravityModel.html ...]
|-
|'''GridAttractionProvider'''
|Data providers for grid attraction model.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/grid/GridAttractionProvider.html ...]
|-
|'''RadiationSensitive'''
|This interface is used to provide an direct solar radiative pressure model.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/radiation/RadiationSensitive.html ...]
|-
|'''RediffusedRadiationSensitive'''
|This interface is used to provide an rediffused radiative pressure model.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/radiation/RediffusedRadiationSensitive.html ...]
|}

=== Classes ===
{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''DragForce'''
|Atmospheric drag force model.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/drag/DragForce.html ...]
|-
|'''EarthGravitationalModelFactory'''
|Factory to provide earth gravitational model.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/EarthGravitationalModelFactory.html ...]
|-
|'''CunninghamGravityModel'''
|This class represents the gravitational field of a celestial body. It uses unnormalized zonal, tesseral and sectorial coefficients.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/CunninghamGravityModel.html ...]
|-
|'''DrozinerGravityModel'''
|This class represents the gravitational field of a celestial body. It uses unnormalized zonal, tesseral and sectorial coefficients.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/DrozinerGravityModel.html ...]
|-
|'''BalminoGravityModel'''
|This class represents the Balmino attraction model of a gravitational field of a celestial body. It uses normalized zonal, tesseral and sectorial coefficients.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/BalminoGravityModel.html ...]
|-
|'''VariablePotentialGravityModel'''
|This class represents a variable gravity field. It computes a static potential and a time variable potential.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/variations/VariablePotentialGravityModel.html ...]
|-
|'''NewtonianGravityModel'''
|Force model for Newtonian central body attraction.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/NewtonianGravityModel.html ...]
|-
|'''GridGravityModel'''
|Gravity model for small bodies using a precomputed grid and a 3D interpolator.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/grid/GridGravityModel.html ...]
|-
|'''CartesianGridAttractionLoader'''
|Cartesian-based grid for grid attraction model.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/grid/CartesianGridAttractionLoader.html ...]
|-
|'''SphericalGridAttractionLoader'''
|Spherical-based grid for grid attraction model.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/grid/SphericalGridAttractionLoader.html ...]
|-
|'''AbstractTides'''
|This class implements the methods for perturbating force due to tides.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/tides/AbstractTides.html ...]
|-
|'''OceanTides'''
|This class implements the perturbating force due to ocean tides.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/tides/OceanTides.html ...]
|-
|'''TerrestrialTides'''
|This class implements the perturbating force due to terrestrial tides.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/tides/TerrestrialTides.html ...]
|-
|'''PoleTides'''
|This class implements the perturbating force due to solid Earth and oceanic pole tides.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/tides/PoleTides.html ...]
|-
|'''DirectBodyAttraction'''
|Direct body attraction force model used to include gravity models in the list of force models.
|[<nowiki/>{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/DirectBodyAttraction.html ...]
|-
|'''ThirdBodyAttraction'''
|Third body attraction force model (including harmonics).
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/ThirdBodyAttraction.html ...]
|-
|'''SolarRadiationPressure'''
|Direct solar radiation pressure force model.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/radiation/SolarRadiationPressure.html ...]
|-
|'''RediffusedRadiationPressure'''
|PATRIUS Rediffused solar pressure force model.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/radiation/RediffusedRadiationPressure.html ...]
|-
|'''EmpiricalForce'''
|Empirical force model.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/EmpiricalForce.html ...]
|-
|'''ConstantThrustError'''
|Model of the error of a simple maneuver with constant thrust.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/maneuvers/ConstantThrustError.html ...]
|-
|'''SchwarzschildRelativisticEffect'''
|This class computes the relativistic Schwarzschild effect.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/relativistic/SchwarzschildRelativisticEffect.html ...]
|-
|'''CoriolisRelativisticEffect'''
|This class computes the relativistic Coriolis effect.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/relativistic/CoriolisRelativisticEffect.html ...]
|-
|'''LenseThirringRelativisticEffect'''
|This class computes the relativistic Lense-Thirring effect.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/relativistic/LenseThirringRelativisticEffect.html ...]
|}

[[Category:User_Manual_4.17_Orbit_Propagation]]

User Manual 4.17 Progmission

2025-11-27T14:24:00Z

Admin tsn : Page créée avec « == Introduction == === Scope === The scope of this section is to present the mission analysis features available in Patrius library. These features are localized in the '''progmission''' package to host mission analysis features inspired by Celestlab. === Javadoc === All the classes related to mission analysis are in the following packages: {| class="wikitable" |- ! scope="col"| Library ! scope="col"| Javadoc |- |Patrius |[{{JavaDoc4.17}}/fr/cnes/sirius/patri... »

== Introduction ==
=== Scope ===
The scope of this section is to present the mission analysis features available in Patrius library.

These features are localized in the '''progmission''' package to host mission analysis features inspired by Celestlab.

=== Javadoc ===
All the classes related to mission analysis are in the following packages:

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/progmission/package-summary.html Package fr.cnes.sirius.patrius.progmission]
|}

=== Useful Documents ===
None as of now.

== Features Description ==
The mission analysis provides the following main features:
* Interplanetary functions
* Visibility and eclipse computation functions
* Keplerian orbits properties

== Interplanetary functions ==

The following Celestlab functions are imported into Patrius:
* <code>CL_ip_sphereInfluence</code>: Analytical computation of the radius of the sphere of influence from the gravitational parameters of the two bodies and the distance between them.
* <code>CL_ip_insertionDv</code>: Analytical computation of the ΔV for insertion into an elliptical orbit around a planet from an initial hyperbolic orbit.
* <code>CL_ip_escapeDv</code>: Analytical computation of the ΔV to escape a planet into a hyperbolic orbit from an initial elliptical orbit. The final class InterplanetaryUtils will group all these static functions and will not be instantiable.

=== Sphere of influence computation ===
The following methods allow to compute the sphere of influence (SOI) radius around the lightest body (smallest mu) given the provided mu values and distance:
* <code>double computeSphereInfluenceRadius(double mu1, double mu2, double distance)</code>
* <code>double[] computeSphereInfluenceRadius(double[] mu1, double[] mu2, double[] distance)</code>
* <code>double computeSphereInfluenceRadius(CelestialBody body1, CelestialBody body2, AbsoluteDate date)</code>
* <code>double[] computeSphereInfluenceRadius(List bodiesList1, List bodiesList2, List dates)</code>

Inspired by the Celestlab function<code>CL_ip_sphereInfluence</code>.

=== Insertion ΔV computation ===
The following methods allow to compute the instantaneous DV needed at the perigee to reach the targeted elliptic orbit from the current hyperbolic orbit around the Earth:
* <code>double[] computeInsertionDV (double vinf, double rph, double sma, double tanoh, double mu)</code>
* <code>double[] computeInsertionDV (double vinf, double rph, double sma)</code>
* <code>List<double[]> computeInsertionDV (double[] vinf, double[] rph, double[] sma, double[] tanoh, double mu)</code>
* <code>List<double[]> computeInsertionDV (double[] vinf, double[] rph, double[] sma)</code>
* <code>Pair<Orbit, double>computeInsertionDV (Orbit orbit, double sma)</code>
* <code>List<Pair<Orbit, double>> computeInsertionDV (List<Orbit> orbitList, double[] sma)</code>

Inspired by the Celestlab function <code>CL_ip_insertionDv</code>.

=== Escape ΔV computation ===
The following methods allow to compute the instantaneous DV needed at the perigee to reach the targeted hyperbolic orbit from the current elliptic orbit around the Earth:
* <code>double[] computeEscapeDV (double sma, double ecc, double vinf, double tanoe, double mu)</code>
* <code>double[] computeEscapeDV (double sma, double ecc, double vinf)</code>
* <code>List<double[]> computeEscapeDV (double[] sma, double[] ecc, double[] vinf, double[] tanoe, double mu)</code>
* <code>List<double[]> computeEscapeDV (double[] sma, double[] ecc, double[] vinf)</code>
* <code>Pair<Orbit, double> computeEscapeDV (Orbit orbit, double vInf)</code>
* <code>List<Pair<Orbit, double>> computeEscapeDV (List<Orbit> orbitList, double[] vInf)</code>

Inspired by the Celestlab function <code>CL_ip_escapeDv</code>.

== Visibility and eclipse computation functions ==

The following Celestlab functions are imported into Patrius:
* <code>CL_ev_eclipse</code>: Computation of eclipse intervals between a satellite, a star (light source), and an occulting body.
* <code>CL_ev_stationVisibility</code>: Computation of visibility intervals between a satellite and a station that defines a minimum elevation angle.
* <code>CL_gm_eclipse</code>: Analytical computation of various eclipse results for an elliptical orbit. The results include the eclipse duration, the initial and final PSO values (start/end of eclipse), and the angle describing the portion of the orbit in eclipse.
* <code>CL_gm_visiParams</code>: Analytical computation of various visibility parameters around a spherical body, specifying the distances between the body’s center and, respectively, the observing satellite and the point of interest. The results include central angles, the distance between the satellite and the target, the elevation angle, and the incidence angle.

=== ProgDetectorUtils class features ===

This class can be used to compute the interval lists associated to detectors (rather the phenomena derived from them) for a given propagator and propagation interval.

The event detectors will be wrapped with coding event detectors that will be added to the propagator.

The main usage of this class is to make event detectors usages more convenient for users. It offers severals kind of constructors and provides only one service : <code>getIntervals()</code> to retrieve the map linking each event detector provided to the instance and the list of the intervals of their associated phenomenon.

== Keplerian orbits properties ==

The following Celestlab functions are imported into Patrius:
* <code>CL_kp_anomConvert</code>: Analytical computation to convert one type of orbital anomaly to another.
* <code>CL_kp_apsConvert</code>: Analytical computation to convert orbital characteristics at periapsis or apoapsis.
* <code>CL_kp_characteristics</code>: Analytical computation of various orbital parameters for elliptical or hyperbolic orbits. The results include the orbital period, mean motion, hyperbolic excess velocity, orbital energy, escape velocities, and others.

=== AnomalyUtils class features ===

The <code>CL_kp_anomConvert</code> service is provided by the <code>AnomalyUtils</code> class (in fr.cnes.sirius.patrius.orbits package).

This class describes static methods allowing to convert anomaly types from/to true/mean/eccentric for elliptical or hyperbolic orbits. It supports "e" or "ex/ey" representations.

=== KeplerianParamComputer class features ===

The <code>CL_kp_apsConvert</code> service is provided by the <code>KeplerianParamComputer</code> class.

This class describes static methods allowing to compute various keplerian characteristics based on the semi-major axis, eccentricity and true anomaly such as the periapsis radius/altitude, the apoapsis radius/altitude, the periapsis/apoapsis velocity and the hyperbolic excess velocity.

=== KeplerianParamUtils class features ===

The <code>CL_kp_characteristics</code> service is provided by the <code>KeplerianParamUtils</code> class.

This class describes static methods allowing to compute various type of parameters for elliptical or hyperbolic orbits such as the orbital period, mean motion, hyperbolic excess velocity, orbital energy, escape velocities, and others. It uses an internal enumerate class ApsParamType to make easier to get the expected parameter without having to deal with a large number of methods.

== Contents ==
=== Classes ===
{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''AnomalyUtils'''
|Anomalies conversion features.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/orbits/AnomalyUtils.html ...]
|-
|'''EventUtils'''
|Event features imported from CelestLab.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/progmission/EventUtils.html ...]
|-
|'''InterplanetaryUtils'''
|Interplanetary features imported from CelestLab.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/progmission/InterplanetaryUtils.html ...]
|-
|'''KeplerianParamComputer'''
|Keplerian parameters characteristics from kep params features imported from CelestLab.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/progmission/KeplerianParamComputer.html ...]
|-
|'''KeplerianParamUtils'''
|Keplerian parameters characteristics features imported from CelestLab.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/progmission/KeplerianParamUtils.html ...]
|-
|'''ProgDetectorUtils'''
|Event detectors simplified usage.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/progmission/ProgDetectorUtils.html ...]
|}

[[Category:User_Manual_4.17_Mission]]

User Manual 4.17 Propagation

2025-11-27T09:38:20Z

Admin tsn :

== Introduction ==

=== Scope ===
This section makes a general presentation of propagators : explanations about using them are given with practical examples of use illustrated by code chuncks.

The PATRIUS library offers different propagators :

* Numerical propagator (see [[User Manual 4.17 Numerical propagation|dedicated User Manual]])
* Analytical propagators (Keplerian, Eckstein-Hechler, J2 secular, Lyddane secular and long period) (see [[User Manual 4.17 Analytical propagation|dedicated User Manual]])
* Analytical 2D propagator (see [[User Manual 4.17 Analytical propagation|dedicated User Manual]])
* TLE propagator (Two Line Element) (see [[User Manual 4.17 Analytical propagation|dedicated User Manual]])
* Precomputed ephemeris propagator (see [[User Manual 4.17 Analytical propagation|dedicated User Manual]])
* The STELA propagator (see [[User Manual 4.17 Semi-analytical propagation|dedicated User Manual]])

Features presented in this section are available to all propagators.

=== Javadoc ===
Some of the propagation packages available in the Patrius library are listed here :

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/propagation/package-summary.html Package fr.cnes.sirius.patrius.propagation]
|}

=== Links ===
None as of now.

=== Useful Documents ===
None as of now.

=== Package Overview ===
None.

== Features description ==

=== Propagation mode ===
There are three different propagation modes : slave, master and ephemeris generation.

==== Slave mode ====
Set to '''slave mode''', the propagator computes the final orbit for a given date and returns it to the user without any intermediate feedback.

==== Master mode : using step handlers ====
When the user wants to call some specific function at the end of each successful step or at the end of a given fixed step during the integration, the propagator has to be set to '''master mode''' and a step handler which represents the specific function has to be designed by the user and given to the propagator : the associated method is <code>handleStep()</code>.

To illustrate how to use this mode on a pratical example, let's define some initial state with :

* ''' an inertial frame '''
* ''' a date in some time scale '''
* ''' a central attraction coefficient '''
* ''' an orbit defined by its keplerian parameters '''

<syntaxhighlight lang="java">
// Inertial frame
Frame inertialFrame = FramesFactory.getEME2000();
// Initial date
TimeScale utc = TimeScalesFactory.getUTC();
AbsoluteDate initialDate = new AbsoluteDate(2004, 01, 01, 23, 30, 00.000,utc);
// Central attraction coefficient
double mu = 3.986004415e+14;
// Initial orbit
double a = 24396159; // semi major axis in meters
double e = 0.72831215; // eccentricity
double i = Math.toRadians(7); // inclination
double omega = Math.toRadians(180); // perigee argument
double raan = Math.toRadians(261); // right ascention of ascending node
double lM = 0; // mean anomaly
Orbit initialOrbit = new KeplerianOrbit(a, e, i, omega, raan, lM, PositionAngle.MEAN,
inertialFrame, initialDate, mu);
// Initial state definition
SpacecraftState initialState = new SpacecraftState(initialOrbit);
</syntaxhighlight>

Here we use a more sophisticated NumericalPropagator based on an some adaptive step integrator provided by the math package, but no matter which integrator is used.

<syntaxhighlight lang="java">
// Adaptive step integrator
// with a minimum step of 0.001 and a maximum step of 1000
double minStep = 0.001;
double maxstep = 1000.0;
double positionTolerance = 10.0;
OrbitType propagationType = OrbitType.KEPLERIAN;
double[][] tolerances =
NumericalPropagator.tolerances(positionTolerance, initialOrbit, propagationType);
AdaptiveStepsizeIntegrator integrator =
new DormandPrince853Integrator(minStep, maxstep, tolerances[0], tolerances[1]);
</syntaxhighlight>

We set up the integrator, and force it to use Keplerian parameters for propagation.

<syntaxhighlight lang="java">
NumericalPropagator propagator = new NumericalPropagator(integrator);
propagator.setOrbitType(propagationType);
</syntaxhighlight>

A force model, reduced here to a single perturbing gravity field, is taken into account.
More precisions on force models can be found in [ORB_FORCE_Home in Force models page].

<syntaxhighlight lang="java">
Frame ITRF = FramesFactory.getITRF(); // terrestrial frame
double ae = 6378137.; // equatorial radius in meter
double c20 = -1.08262631303e-3; // J2 potential coefficient

// potential coefficients arrays (only J2 is considered here)
double[][] c = new double[3][1];
c[0][0] = 0.0;
c[2][0] = c20;
double[][] s = new double[3][1];
ForceModel cunningham = new CunninghamAttractionModel(ITRF, ae, mu, c, s);
</syntaxhighlight>

This force model is simply added to the propagator:

<syntaxhighlight lang="java">
propagator.addForceModel(cunningham);
</syntaxhighlight>

The propagator operating mode is set to master mode with fixed step and a TutorialStepHandler which implements the interface PatriusFixedStepHandler in order to fulfill the handleStep method to be called within the loop. For the purpose of this tutorial, the handleStep method will just print the current state at the moment.

<syntaxhighlight lang="java">
propagator.setMasterMode(60., new TutorialStepHandler());
</syntaxhighlight>

Then, the initial state is set for the propagator:

<syntaxhighlight lang="java">
propagator.setInitialState(initialState);
</syntaxhighlight>

Finally, the propagator is just asked to propagate, from the initial state, for a given duration.
<syntaxhighlight lang="java">
SpacecraftState finalState =
propagator.propagate(new AbsoluteDate(initialDate, 630.));
</syntaxhighlight>

Clearly, with a few lines of code, the main application delegates to the propagator the care of handling regular outputs through a variable step integration loop.

The only need is to derived some class from the interface PatriusFixedStepHandler to realize a handleStep method, as follows:
<syntaxhighlight lang="java">
private static class TutorialStepHandler implements PatriusFixedStepHandler {

public void handleStep(SpacecraftState currentState, boolean isLast) {
System.out.println(" time : " + currentState.getDate());
System.out.println(" " + currentState.getOrbit());
if (isLast) {
System.out.println(" this was the last step ");
}
}
}
</syntaxhighlight>

For the same result, with the slave mode, it would have required much more programming.

The printed results are shown below:
<syntaxhighlight lang="java">
time : 2004-01-01T23:30:00.000
keplerian parameters: {a: 2.4396159E7; e: 0.72831215; i: 7.0; pa: 180.0; raan: 261.0; v: 0.0;}
time : 2004-01-01T23:31:00.000
keplerian parameters: {a: 2.439564424480015E7; e: 0.7283054179012741; i: 6.999949573716115; pa: 180.01089879431635; raan: 260.9999744509341; v: 5.270522984259634;}
time : 2004-01-01T23:32:00.000
keplerian parameters: {a: 2.4394130981544524E7; e: 0.7282856263106472; i: 6.999800432744152; pa: 180.02168751826343; raan: 260.9997982967906; v: 10.50387496695558;}
time : 2004-01-01T23:33:00.000
keplerian parameters: {a: 2.4391710665289845E7; e: 0.7282539637676634; i: 6.999563066306985; pa: 180.03226220891892; raan: 260.99933874845317; v: 15.664604011799053;}
time : 2004-01-01T23:34:00.000
keplerian parameters: {a: 2.438852138985819E7; e: 0.7282122258929671; i: 6.9992532645274546; pa: 180.04252939476373; raan: 260.9984960696569; v: 20.720499012905563;}
time : 2004-01-01T23:35:00.000
keplerian parameters: {a: 2.438473009191154E7; e: 0.7281625851163973; i: 6.998890000900681; pa: 180.05240967921347; raan: 260.9972118041821; v: 25.643756282394765;}
time : 2004-01-01T23:36:00.000
keplerian parameters: {a: 2.4380513619406037E7; e: 0.7281073453198131; i: 6.998493179635541; pa: 180.06183982161005; raan: 260.9954699357843; v: 30.411707875362936;}
time : 2004-01-01T23:37:00.000
keplerian parameters: {a: 2.4376042162606522E7; e: 0.7280487266192758; i: 6.998081669198389; pa: 180.0707733525973; raan: 260.9932919569584; v: 35.00709604303499;}
time : 2004-01-01T23:38:00.000
keplerian parameters: {a: 2.4371467133870374E7; e: 0.727988707383731; i: 6.997671877833683; pa: 180.07917999091737; raan: 260.99072804117174; v: 39.41795154717632;}
time : 2004-01-01T23:39:00.000
keplerian parameters: {a: 2.4366914169719197E7; e: 0.7279289324335715; i: 6.99727695633292; pa: 180.08704419756123; raan: 260.98784670576674; v: 43.63716855903322;}
time : 2004-01-01T23:40:00.000
keplerian parameters: {a: 2.436248074752743E7; e: 0.7278706810843818; i: 6.996906568384245; pa: 180.09436319418123; raan: 260.9847250080804; v: 47.66188030915512;}
this was the last step
Final date : 2004-01-01T23:40:30.000
Final state : keplerian parameters: {a: 2.4360331834936075E7; e: 0.7278424290862751; i: 6.996732681960374; pa: 180.097820317503; raan: 260.98309840201875; v: 49.6013850854552;}
</syntaxhighlight>

==== Ephemeris mode ====
The '''ephemeris generation mode''' is used when the user needs random access to the orbit state at any date after the propagation. Be aware that this mode may be memory intensive since all intermediate results are stored.

To illstrate it, let's also first define some initial state with :

* ''' an inertial frame '''
* ''' a date in some time scale '''
* ''' a central attraction coefficient '''
* ''' an orbit defined by its keplerian parameters '''

<syntaxhighlight lang="java">
// Inertial frame
Frame inertialFrame = FramesFactory.getEME2000();
// Initial date
TimeScale utc = TimeScalesFactory.getUTC();
AbsoluteDate initialDate = new AbsoluteDate(2004, 01, 01, 23, 30, 00.000,utc);
// Central attraction coefficient
double mu = 3.986004415e+14;
// Initial orbit
double a = 24396159; // semi major axis in meters
double e = 0.72831215; // eccentricity
double i = Math.toRadians(7); // inclination
double omega = Math.toRadians(180); // perigee argument
double raan = Math.toRadians(261); // right ascention of ascending node
double lM = 0; // mean anomaly
Orbit initialOrbit = new KeplerianOrbit(a, e, i, omega, raan, lM, PositionAngle.MEAN,
inertialFrame, initialDate, mu);
// Initial state definition
SpacecraftState initialState = new SpacecraftState(initialOrbit);
</syntaxhighlight>

Here we use a simple NumericalPropagator, without perturbation, based on a classical fixed step Runge-Kutta integrator provided by the math package.
<syntaxhighlight lang="java">
double stepSize = 10;
FirstOrderIntegrator integrator = new ClassicalRungeKuttaIntegrator(stepSize);
NumericalPropagator propagator = new NumericalPropagator(integrator);
</syntaxhighlight>

The initial state is set for this propagator:
<syntaxhighlight lang="java">
propagator.setInitialState(initialState);
</syntaxhighlight>

Then, the propagator operating mode is simply set to ephemeris mode:
<syntaxhighlight lang="java">
propagator.setEphemerisMode();
</syntaxhighlight>

And the propagation is performed for a given duration.
<syntaxhighlight lang="java">
SpacecraftState finalState =
propagator.propagate(new AbsoluteDate(initialDate, 6000));
</syntaxhighlight>

This finalState can be used for anything, to be printed for example just like below:
<syntaxhighlight lang="java">
Numerical propagation :
Final date : 2004-01-02T01:10:00.000
equinoctial parameters: {a: 2.4396159E7;
ex: 0.11393312156755062; ey: 0.719345418868777;
hx: -0.009567941763699867; hy: -0.06040960680288257;
lv: 583.1250344407331;}
</syntaxhighlight>

Throughout the propagation, intermediate states are stored within an ephemeris which can be recovered now just with one instruction:
<syntaxhighlight lang="java">
BoundedPropagator ephemeris = propagator.getGeneratedEphemeris();
System.out.println(" Ephemeris defined from " + ephemeris.getMinDate() +
" to " + ephemeris.getMaxDate());
</syntaxhighlight>

The ephemeris is defined as a BoundedPropagator, which means that it is valid only between the propagation initial and final dates. The code above give the following result:
<syntaxhighlight lang="java">
Ephemeris defined from 2004-01-01T23:30:00.000 to 2004-01-02T01:10:00.000
</syntaxhighlight>

Between these dates, the ephemeris can be used as any propagator to propagate the orbital state towards any intermediate date just with one instruction:
<syntaxhighlight lang="java">
SpacecraftState intermediateState = ephemeris.propagate(intermediateDate);
</syntaxhighlight>

Here are results obtained with intermediate dates set to 3000 second after start date and to exactly the final date:
<syntaxhighlight lang="java">
Ephemeris propagation :
date : 2004-01-02T00:20:00.000
equinoctial parameters: {a: 2.4396159E7;
ex: 0.11393312156755062; ey: 0.719345418868777;
hx: -0.009567941763699867; hy: -0.06040960680288257;
lv: 559.0092657655284;}
date : 2004-01-02T01:10:00.000
equinoctial parameters: {a: 2.4396159E7;
ex: 0.11393312156755062; ey: 0.719345418868777;
hx: -0.009567941763699867; hy: -0.06040960680288257;
lv: 583.1250344407331;}
</syntaxhighlight>

The following shows the error message we get when we try to use a date outside of the ephemeris range (in this case, the intermediate date was set to 1000 seconds before ephemeris start:
<syntaxhighlight lang="java">
out of range date for ephemerides: 2004-01-01T23:13:20.000
</syntaxhighlight>

==== Choosing the suitable mode ====

Here are given advantages and drawbacks of each mode according the context : be sure to use the suitable one reading it !

{| class="wikitable"
| Use case
| without dense output
| with dense output
| with event detection
| with step handler
|-
|slave
| + faster than the others since it has no step handler
| - not adapted when it comes to generate a dense output
| + adapted
| - not adapted
|-
|master
| - not really adapted
| - not really adapted (could be adapted with a specific step handler)
| + adapted
| + adapted
|-
|ephemeris generation
| - not really adapted
| + adapted
| + adapted
| - not adapted
|}

NB : To get a dense output, the user should not propagate on a series of time intervals to get intermediate results because at the end of any propagation, the last step is likely readjusted to reach exactly the propagation end date. This behavior differs from the expected one : the integrator parametrization is bypassed, this behavior should remain rare.

=== Propagation frame ===
Both analytical and numerical propagators are able to propagate orbits which are defined in a not inertial or pseudo-inertial frame.
However, the propagation has to be performed in an inertial frame, as a result:
* If initial state frame is inertial and user did not specify propagation frame, then propagation will be performed in initial state frame
* If initial state frame is not inertial and user did not specify propagation frame, then an exception will be thrown
* If the user specified a propagation frame, then propagation is performed in specified frame, independently of initial state frame

Propagation frame can be specified using method <code>setOrbitFrame(final Frame frame)</code> of propagators.

=== Events management ===
This paragraph aims to show the power and simplicity of the event handling mechanism. One needs to check the visibility between a satellite and a ground station during some time range. 
We will use, and extend, the predefined ElevationDetector to perform the task. The goal is not to make a complete presentation of events detectors but to introduce it in the context of propagators : 
events detectors are spreadly developped at the [MIS_EVT_Home dedicated Events detection page].
First, let's set up an initial state for the satellite defined by a position and a velocity at one date in some inertial frame.

<syntaxhighlight lang="java">
Vector3D position = new Vector3D(-6142438.668, 3492467.560, -25767.25680);
Vector3D velocity = new Vector3D(505.8479685, 942.7809215, 7435.922231);
PVCoordinates pvCoordinates = new PVCoordinates(position, velocity);
AbsoluteDate initialDate =
new AbsoluteDate(2004, 01, 01, 23, 30, 00.000, TimeScalesFactory.getUTC());
Frame inertialFrame = FramesFactory.getEME2000();
</syntaxhighlight>

We also need to set the central attraction coefficient to define the initial orbit as a KeplerianOrbit.
<syntaxhighlight lang="java">
double mu = 3.986004415e+14;
Orbit initialOrbit =
new KeplerianOrbit(pvCoordinates, inertialFrame, initialDate, mu);
</syntaxhighlight>

As a propagator, we consider a KeplerianPropagator to compute the simple keplerian motion. It could be more elaborate without modifying the general purpose of this speech.
<syntaxhighlight lang="java">
Propagator kepler = new KeplerianPropagator(initialOrbit);
</syntaxhighlight>

Then, let's define the ground station by its coordinates as an EllipsoidPoint:
<syntaxhighlight lang="java">
double ae = 6378137.0; // equatorial radius in meter
double f = 1.0 / 298.257223563; // flattening
Frame ITRF = FramesFactory.getITRF(); // terrestrial frame at an arbitrary date
BodyShape earth = new OneAxisEllipsoid(ae, f, ITRF);
double longitude = Math.toRadians(45.);
double latitude = Math.toRadians(25.);
double altitude = 0.;
EllipsoidPoint station1 = new EllipsoidPoint(earth, LLHCoordinatesSystem.ELLIPSODETIC, latitude, longitude, altitude, "point");
</syntaxhighlight>

And let's associate to it a TopocentricFrame related to a BodyShape in some terrestrial frame.

<syntaxhighlight lang="java">
TopocentricFrame sta1Frame = new TopocentricFrame(earth, station1, "station1");
</syntaxhighlight>

More precisions on BodyShape and BodyPoint can be found in [FDY_BODY_Home Bodies page].
More precisions on TopocentricFrame can be found in [FDY_FRAME_Home Frames page].

An EventDetector is defined as a VisibilityFromStationDetector which is derived from an ElevationDetector with the same specific parameters.
<syntaxhighlight lang="java">
double maxcheck = 1.;
double elevation = Math.toRadians(5.);
EventDetector sta1Visi = new VisibilityFromStationDetector(maxcheck, elevation, sta1Frame);
</syntaxhighlight>

This EventDetector is added to the propagator:
<syntaxhighlight lang="java">
kepler.addEventDetector(sta1Visi);
</syntaxhighlight>

Finally, the propagator is simply asked to perform until some final date, in slave mode by default.

It will propagate from the initial date to the first raising or for the fixed duration according to the behavior implemented in the VisibilityDetector class.
<syntaxhighlight lang="java">
SpacecraftState finalState =
kepler.propagate(new AbsoluteDate(initialDate, 1500.));
</syntaxhighlight>
The main application code is very simple, all the work is done inside the propagator thanks to the VisibilityDetector class especially created for the purpose.

This class extends the ElevationDetector class, by overriding the eventOccurred method with the special ability to print the results of the visibility check, both the raising and the setting time, and to stop the propagation just after the setting detection.

The printed result is shown below. We can see that the propagation stopped just after detecting the raising:
<syntaxhighlight lang="java">
Visibility on station1 begins at 2004-01-01T23:31:52.097
Visibility on station1 ends at 2004-01-01T23:42:48.850
Final state : 2004-01-01T23:42:48.850
</syntaxhighlight>

== Content ==
=== Interfaces ===

{| class="wikitable"
|-
! scope="col"| Interface
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''BoundedPropagator
|This interface is intended for ephemerides valid only during a time range.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/propagation/BoundedPropagator.html ...]
|-
|'''Propagator
|This interface provides a way to propagate an orbit at any time.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/propagation/Propagator.html ...]
|-
|'''SpacecraftStateProvider
|This interface is a generic interface for all SpacecraftState providers (such as propagator).
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/propagation/SpacecraftStateProvider.html ...]
|}

=== Classes ===

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''SpacecraftState'''
|This class is the representation of a complete state holding orbit, attitude for forces and for events computation and additional states at a given date.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/propagation/SpacecraftState.html ...]
|}

[[Category:User_Manual_4.17_Orbit_Propagation]]

User Manual 4.17 Ephemeris

2025-11-27T09:36:11Z

Admin tsn :

== Introduction ==
=== Scope ===
This section describes the propagation of spacecraftstates based on interpolation of position velocity ephemeris.

=== Javadoc ===
The concerned classes are avalaible in the following packages :

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/utils/package-summary.html Package fr.cnes.sirius.patrius.utils]
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/propagation/package-summary.html Package fr.cnes.sirius.patrius.propagation]
|}

=== Links ===
None as of now.

=== Useful Documents ===
None as of now.

=== Package Overview ===
See the [ORB_PRO_PkgOverview Propagator ] page for more generic information about propagators.

Propagation based on interpolation of position velocity ephemeris has been design to be very simple to use:

* Ephemeris propagators extend <code>AbstractPropagator</code> class. As a result all propagators features (event detection, etc.) are available.

* Ephemeris propagators are based on a <code>PVCoordinateProvider</code> to retrieve the orbital parameters at required date.

* Implementation of <code>PVCoordinateProvider</code> based on ephemeris interpolation (Hermite, or Lagrange).

* Implementation of <code>AdditionalStatesProvider</code> based on an ephemeris of additional states.

== Features Description ==
=== PVCoordinatesPropagator ===
The PV coordinate propagator extends <code>AbstractPropagator</code> and provides a simple way to propagate an initial spacecraft state coherent with the provided <code>PVCoordinatesProvider</code> and the eventual attitude and additional states provider.

The propagation of position velocity is based on the getPVCoordinates of the given <code>PVCoordinatesProvider</code>. 
The propagation of attitude is based on the given <code>AttitudeProvider</code>. 
The propagation of the additional states is based on the given <code>AdditionalStatesProvider</code>.

A classical simple use case is :

* <code>PVCoordinatesProvider</code> : One of the provider based on ephemeris interpolation (Lagrange or Hermite)

* <code>AttitudeProvider</code> : Null. The attitude of the propagated spacecraft state is null.

* <code>AdditionalStatesProvider</code> : Null. The additional states of the propagated spacecraft state is null.

A classical advanced use case is to add an attitude provider and the SimpleAdditionalStateProvider described in next paragraph.

'''Warning''': Events detector with <code>Action.RESET_STATE</code> should not be used with this propagator fed with a "precomputed" PV coordinate provider (such as an ephemeris or an orbit object). In particular, impulse maneuvers cannot be used. Otherwise propagation will fail. 
This is due to the fact that the provided PV coordinate provider is not valid any more after the <code>Action.RESET_STATE</code> action.

=== SimpleAdditionalStateProvider ===
The <code>SimpleAdditionalStateProvider</code> is an implementation of <code>AdditionalStateProvider</code> based on additional states ephemeris.

The computation of an additional state for a given date is the following:

* If the given date is found in the ephemeris, the associated additional state vector is returned

* Otherwise a linera interpolation is performed.

=== PVCoordinateProvider Ephemeris ===
Two classes provide PVCoordinates at a given date from an ephemeris interpolation :

* <code>EphemerisPvLagrange</code> : Computes the PVCoordinates using a Hermite interpolation (<code>HermiteInterpolator</code>) of the ephemeris without providing any derivatives on points to be interpolated (this allows to improve the computation performance with respect to a classical Lagrange approach - <code>PolynomialFunctionLagrangeForm</code> - by a factor 4).

* <code>EphemerisPvHermite</code> : Computes the PVCoordinates using a Hermite interpolation of the ephemeris

Both can be built from a list of spacecraftstates or from list of dates- positions - velocities expressed in a given frame.

It is possible to accept the interpolation in a non-optimal range through a setting at the construction (disabled by default). Meaning the ephemeris can still be interpolated in a degraded case with less samples than required by the order in the lower or upper bound.

==== Lagrange interpolation ====

Intermediate states are computed with a Lagrange interpolator (order 8 by default) which :

* expects that spacecraft states are chronologically sorted (duplicates are allowed). If not sorted, no exception will be thrown and result might be wrong.

* is based on an instance of PolynomialFunctionLagrangeForm, which is stored at each interpolation to be reused for same interpolation interval, and updated if the interpolation is not in the same interval <math>t \in [t_{i}, t_{i+1}[</math>, where <math>i \in \left\{0, ..., N \right\}</math> and <math>N</math> is the size of the handled ephemeris.

The interpolation order <math>n</math> for LagrangeEphemeris should be an even number, and the interpolation date should correspond to an index that belongs in <math>n/2- 1 \leq i \leq N-1-n/2</math>.

==== Hermite interpolation ====

Intermediate states are computed with a Hermite interpolator which :

* expects the spacecraft states to be chronologically sorted (duplicates are allowed). If not sorted, no exception will be thrown and result might be wrong.

* is based on an instance of HermiteInterpolator, which is stored at each interpolation to be reused for same interpolation interval, and updated if the interpolation is not in the same interval <math>t \in [t_{i}, t_{i+1}[</math>, where <math>i \in \left\{0, ..., N \right\}</math> and <math>N</math> is the size of the handled ephemeris (in closed-open convention).

For HermiteEphemeris, the interpolation can use the acceleration array if it is available.

=== PVCoordinateProvider AlmanacPVCoordinates ===
The class <code>AlmanacPVCoordinates</code> extends the <code>PVCoordinateProvider</code>. 
It provides PVCoordinates (position and velocity) of GNSS almanacs. 
Almanacs can be provided using the <code>AlmanacGNSSParameters</code> class. 
The classes <code>CNAVGNSSParameters</code> and <code>LNAVGNSSParameters</code> are simple containers for broadcast model CNAV and LNAV ephemeris description parameters of GNSS satellites (GPS and BeiDou for CNAV and GPS, BeiDou and Galileo for LNAV).

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

== Contents ==
=== Interfaces ===
None as of now.

=== Classes ===
{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''IntegratedEphemeris'''
|This class stores sequentially generated orbital parameters for later retrieval.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/propagation/precomputed/IntegratedEphemeris.html ...]
|-
|'''Ephemeris'''
|This class is designed to accept and handle tabulated orbital entries. Tabulated entries are classified and then extrapolated in way to obtain continuous output, with accuracy and computation methods configured by the user.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/propagation/precomputed/Ephemeris.html ...]
|-
|'''EphemerisPvLagrange'''
|This class handles tabulated spacecraft states entries and implements PVCoordinatesProvider interface. Tabulated entries are chronologically classified. A Lagrange interpolation is perfomed to compute PV coordinates at a given date. The class is an extension is based on a common Lagrange-Hermite approch provided by class <code>AbstractEphemerisPvHermiteLagrange</code>.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/orbits/pvcoordinates/EphemerisPvLagrange.html ...]
|-
|'''EphemerisPvHermite'''
|This class handles tabulated spacecraft states entries and implements PVCoordinatesProvider interface. Tabulated entries are chronologically classified. A Hermite interpolation is perfomed to compute PV coordinates at a given date. The class is an extension is based on a common Lagrange-Hermite approch provided by class <code>AbstractEphemerisPvHermiteLagrange</code>.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/orbits/pvcoordinates/EphemerisPvHermite.html ...]
|-
|'''PVCoordinatesPropagator'''
|This class extends AbstractPropagator. It simply implements propagate orbit method using the getPVCoordinate from the PVCoordinate provider it handles. The propagator is initialized with given initial date, frame and mu to build a coherent initial spacecraftstate. This initialisation calls the PVCoordinateProvider getPVCoordinates method to the given date which can raise an error if the date is out of bound for exemple. This class will be basically used with '''EphemerisPvLagrange''' and '''EphemerisPvHermite'''.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/propagation/PVCoordinatesPropagator.html ...]
|-
|'''SimpleAdditionalStateProvider'''
|This class implements AdditionalStateProvider interface. It simply handles a list of dates associated to additional state vectors. For a given date it returns the associated additional state vector or a propagation exception if this date is not found. This class will be basically used with '''PVCoordinatesPropagator'''.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/propagation/SimpleAdditionalStateProvider.html ...]
|-
|'''AlmanacPVCoordinates'''
|This class computes PV coordinates at any date from a GPS or Galileo Almanac.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/orbits/pvcoordinates/AlmanacPVCoordinates.html ...]
|}

[[Category:User_Manual_4.17_Orbit_Propagation]]

User Manual 4.17 Celestial bodies

2025-11-27T09:34:46Z

Admin tsn :

__NOTOC__
== Introduction ==
=== Scope ===
The celestial bodies are described by their main features : position and geometry. The positions are ephemeris that must be loaded from models, the geometries are created as one axis ellipsoids or facet bodies.
The package provides a factory able to create any celestial body of the solar system.

=== Javadoc ===
The classes for bodies description are available in the package <code>bodies</code> of Patrius.

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
|Orekit
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/package-summary.html Package fr.cnes.sirius.patrius.bodies]
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/package-summary.html Package fr.cnes.sirius.patrius.bodies]
|}

=== Links ===

Orekit bodies : [https://www.orekit.org/static/architecture/bodies.html Orekit Bodies architecture description ]

IAU report : [https://astrogeology.usgs.gov/groups/iau-wgccre Report of the IAU Working Group on Cartographic Coordinates and Rotational Elements: 2009]

=== Useful Documents ===
None as of now.

=== Package Overview ===
None.

== Features Description ==
=== Celestial bodies ===
The Moon, the Sun and planets of the solar system are all represented by the [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/CelestialBody.html CelestialBody] interface. This class associates a name (eg Sun) to :
* a gravitational coefficient GM
*a body centered ICRF frame (which can be retrieved with method <code>getICRF()</code>).
*a body centered EME2000 frame (which can be retrieved with method <code>getEME2000()</code>).
*a body centered inertial frame taking into account only the constant part (α, δ) of IAUPole (which can be retrieved with method <code>getInertialFrame(IAUPoleModelType.CONSTANT)</code>).
*a body centered inertial frame taking into account only the constant and secular parts (α, δ) of IAUPole (which can be retrieved with method <code>getInertialFrame(IAUPoleModelType.MEAN)</code>).
*a body centered inertial frame taking into account the constant secular and harmonics parts (α, δ) of IAUPole (which can be retrieved with method <code>getInertialFrame(IAUPoleModelType.TRUE)</code>).
*a body centered rotating frame taking into account only the constant part w of IAUPole (which can be retrieved with method <code>getRotatingFrame(IAUPoleModelType.CONSTANT)</code>). It's parent frame is the inertial equator frame.
*a body centered rotating frame taking into account only the constant and secular parts w of IAUPole (which can be retrieved with method <code>getRotatingFrame(IAUPoleModelType.MEAN)</code>). It's parent frame is the mean equator frame.
*a body centered rotating frame taking into account the constant secular and harmonics parts w of IAUPole (which can be retrieved with method <code>getRotatingFrame(IAUPoleModelType.TRUE)</code>). It's parent frame is the true equator frame.

Inertially-oriented and body-oriented frames are defined in the following way:
* Body-centered inertial frame is centered on the celestial body centered and pole axis (Z axis) is shifted by right ascension α and declination δ.
* Body-centered rotating frame is linked to inertially-oriented frame by a rotation of angle W(t) (reference values for W(t) is provided by IAU).

To build a celestial body, the user can:
* use the static methods of the <code>CelestialBodyFactory</code> to create instances of the most common celestial bodies (Moon, Sun, Jupiter, etc.). JPL Ephemeris data are used. Warning: using the factory requires to load JPL Ephemeris data beforehand.
* use the simplified models (Meeus, etc.).
* creates its own celestial body using the class <code>UserCelestialBody</code> as well as its own pole motion using the class <code>UserIAUPole</code>.

For the two first case (JPL and Meeus), the pole data of the body are automatically retrieved using the IAU data through <code>IAUPoleFactory</code> class (data is contained within PATRIUS).
By default, IAU pole data for planetary bodies (including Sun and moon) are available in PATRIUS through the use of the <code>IAUPoleFactory.getIAUPole()</code>. Data come from the IAU 2009 working group Technical Note.

These methods are detailed in the following sections.

=== Ephemeris Loader ===
For any celestial body of the Solar System, the actual computation of its position and velocity relies on the JPL planetary ephemerides files. These files are binary files and loaded thanks to the JPLCelestialBodyLoader object.

Note that celestial bodies and associated ephemeris loaders are distinct: a class loads the ephemeris returning a <code>CelestialBodyEphemeris</code> while the other loads the whole <code>CelestialBody</code>.
However, for sake of clarity, the main visible loaders are celestial body loaders.

For the moment, this object is able to load JPL DE XXX files and IMCCE INPOP files which are the most commonly used data files (see below for an exact list of accepted files). For instance with the most common files, the JPL DE 405 covers the years 1600 to 2200 at maximum precision, the JPL DE 406 covers the years-3000 to +3000 at only slightly reduced precision. The DE 405 file is the basis for the Astronomical Almanac and leads to sufficiently accurate results and, for most purposes, even the accuracy of DE 406 is sufficient.

==== JPLCelestialBodyLoader ====

In order to generate the ephemerides of one celestial body of the Solar System, one has to use the JPLCelestialBodyLoader as follows :

<syntaxhighlight lang="java">
final JPLCelestialBodyLoader loaderEMB = new JPLCelestialBodyLoader(fileName,
EphemerisType.EARTH_MOON);
final JPLCelestialBodyLoader loaderSSB = new JPLCelestialBodyLoader(fileName,
EphemerisType.SOLAR_SYSTEM_BARYCENTER);
CelestialBodyFactory.addCelestialBodyLoader(CelestialBodyFactory.EARTH_MOON, loaderEMB);
CelestialBodyFactory.addCelestialBodyLoader(CelestialBodyFactory.SOLAR_SYSTEM_BARYCENTER, loaderSSB);

// Reference frame
Frame icrf = FramesFactory.getICRF();

// Ephemeris of the Sun
JPLCelestialBodyLoaderloader = new JPLCelestialBodyLoader("unxp2000.405",
EphemerisType.SUN);

// Creation of the Sun
CelestialBody sun = loader.loadCelestialBody(CelestialBodyFactory.SUN);

// Coordinates of the Sun given a date and a reference frame
PVCoordinates pvSun = sun.getPVCoordinates(date, icrf);
</syntaxhighlight>

When the user wants to create a JPLCelestialBodyLoader, first of all, he must supply the folder where the DE XXX files are stored. Then he has to give the name of the file which contains the data (DE XXX), the type of celestial body and a date (desired central date) as entries of the JPLCelestialBodyLoader.

The first argument (name of the data file) may be <code>null</code>. In this case, Patrius takes the first compatible file found. If one wants only files from the DE 405 ephemerides, for instance, he has to give the String <code> "^unx[mp](\\d\\d\\d\\d)\\.(?:405)$"</code>. The last argument can also be <code>null</code>. If the central date is not mentionned an arbitrary 100 days range will be loaded whereas if it is mentionned all data within a +/-50 days range around this date will be loaded.

Once the data is loaded, thanks to the JPLCelestialBodyLoader, the user can create the celestial body with the method loadCelestialBody() of the JPLCelestialBodyLoaderclass. To do so, the user has to be sure that all required data is loaded. Indeed, apart from the Moon, the Earth and the Earth-Moon barycenter, the creation of a celestial body requires some data on the Earth Moon barycenter and the Solar System barycenter in order to instanciate the frame in which the ephemerides of the celestial body will be defined. Therefore, the user has to create a JPLCelestialBodyLoaderfor the Earth-Moon barycenter and the Solar System barycenter prior to creating the celestial body, otherwise Patrius will arbitrarily load a DE file to generate the corresponding ephemerides that are used afterwards for the generation of the frame. Then the user has to complete the list of the loaders of the CelestialBodyFactory with these two loaders before calling the method loadCelestialBody().

A static method <code>hasNoLoader()</code> in the class <code>CelestialBodyFactory</code> allows for a given celestial body to verify if a default loader exists. The user can verify if a specific loader exists for the body before using the default one this way.

NB : The user has to clean the CelestialBodyFactory memory if he does not want to work with the previously defined celestial bodies.

==== JPL ephemerides ====

The JPL ephemerides data is available on the [ftp://ssd.jpl.nasa.gov/pub/eph/planets/ JPL FTP server] [R3].

Available ephemerides :

{| class="wikitable"
|-
! scope="col"| Development Ephemerides
! scope="col"| Created in...
! scope="col"| Description
|-
|DE200
|September 1981
|includes nutations but not librations. 
Referred to the dynamical equator and equinox of 2000. 
Covers JED 2305424.13 (1599 DEC 09) to JED 2513360.5 (2169 MAR 31).

This ephemeris was used for the Astronomical Almanac from 1984 to 2003. (See Standish, 1982 and Standish, 1990).
|-
|DE202
|October 1987
|includes nutations and librations. 
Referred to the dynamical equator and equinox of 2000. 
Covers JED 2414992.5 (1899 DEC 04) to JED 2469808.5 (2050 JAN 02).
|-
|DE403
|May 1993
|includes nutations and librations. 
Referred to the International Celestial Reference Frame. 
Covers JED 2305200.5 (1599 APR 29) to JED 2524400.5 (2199 JUN 22).

Fit to planetary and lunar laser ranging data.(See Folkner et al. 1994).
|-
|DE405, DE406
|May 1997
|For the DE405:

includes both nutations and librations. 
Referred to the International Celestial Reference Frame. 
Covers JED 2305424.130 (1599 DEC 09) to JED 2525008.50 (2201 FEB 20)

For the DE406 :

the same as the DE405 except the time span : Spans JED 0624976.50 (-3001 FEB 04) to 2816912.50 (+3000 MAY 06)

This is the same integration as DE405, with the accuracy of the interpolating polynomials has been lessened to reduce file size for the longer time span covered by the file.
|-
|DE410
|April 2003
|includes nutations and librations. 
Referred to the International Celestial Reference Frame. 
Covers JED 2415056.5 (1900 FEB 06) to JED 2458832.5 (2019 DEC 15).

Ephemeris used for Mars Exploration Rover navigation.
|-
|DE413
|November 2004
|includes nutations and librations. 
Referred to the International Celestial Reference Frame. 
Covers JED 2414992.5, (1899 DEC 04) to JED 2469872.5 (2050 MAR 07).

Created to update the orbit of Pluto to aid in planning for an occultation of a relatively bright star by Charon on 11 July 2005.
|-
|DE414
|May 2005
|includes nutations and librations. 
Covers JED 2414992.5, (1899 DEC 04) to JED 2469872.5 (2050 MAR 07).

Fit to ranging data from MGS and Odyssey through 2003. (See Konopliv et al., 2006.)
|-
|DE418
|August 2007
|includes nutations and librations. 
Covers JED 2414864.13 (1899 JUL 29) to JED 2470192.5 (2051 JAN 21)
|-
|DE421
|February 2008
|includes nutations and librations. 
Referred to the International Celestial Reference Frame. 
Covers JED 2414864.13 (1899 JUL 29) to JED 2471184.13 (2053 OCT 09)

Fit to planetary and lunar laser ranging data. (See Folkner et al., 2009)
|-
|DE422
|September 2009
|includes nutations and librations. 
Referred to the International Celestial Reference Frame. 
Covers JED 625648.5, (-3000 DEC 07) to JED 2816816.5, (3000 JAN 30).

Intended for the MESSENGER mission to Mercury. 
Extended integration time to serve as successor to DE406. 
Fit to ranging data from MGS and Odyssey through 2003. (See Konopliv et al., 2010.)
|-
|DE423
|February 2010
|includes nutations and librations. 
Referred to the International Celestial Reference Frame version 2.0. 
Covers JED 2378480.5, (1799 DEC 16) to JED 2524624.13, (2200 FEB 02).

Intended for the MESSENGER mission to Mercury.
|}

==== IMCCE INPOP ephemerides ====

The IMCCE INPOP ephemeris is available on IMCCE website.

Available INPOP ephemerides :
* 06b
* 06c
* 08a
* 10a
* 10b
* 10e
* 13c
* 17a
* 19a

=== Simplified analytical models ===
==== Meeus Model ====

The Meeus Model is a simplified model which gives the position of the Sun and the Moon with respect to the time T expressed in centuries (TT time scale). This model is an analytical model less precise than the DE ephemerides given by JPL. It is adapted for onboard applications.
The class implementing the Meeus Model allows three different models computing the position of the Sun with appropriate equations : the standard model (provided by Jean Meeus), the Stela model and an onboard model. The main differences between these model is the computation of the obliquity of the ecliptic : indeed, its value is fixed to 0 for the standard model, given by an expression involving <math>T, T^{2}</math>for Stela model and <math>T, T^{2}, T^{3}</math> for the onboard model.
Moreover, the onboard model computed the position in J2000 frame, whereas standard and Stela models use respectively EOD and MOD frame.

Regarding the precision, one has to expect a maximum difference of 25593km in position for the Sun and a maximum angular difference of 34.13'' (wrt DE405 ephemerides). For the Moon, one has to expect a maximum difference of 26 km in position and a maximum angular difference of 15.2'' (wrt DE405 ephemerides). As for the performances (in terms of execution time), the Meeus model for the Sun is faster than the DE405 ephemerides. However, we did not come to the same conclusion for the Moon even by decreasing the degree of precision (number of terms taken into account to compute the latitude, longitude and distance which are needed to compute in fine the position of the Moon).

{| class="wikitable"
|-
!
! scope="col"| Deviation in position wrt DE423
! scope="col"| Angular deviation wrt DE423
|-
|'''Sun'''
|12000 km
|34.13''
|-
|'''Moon 62x66x46'''
|12.4 km
|15.2''
|-
|'''Moon 26x13x13'''
|225 km
|122''
|-
|'''Moon 9x4x3'''
|1591 km
|889''
|}

{| class="wikitable"
|-
!
! scope="col"| Deviation in position wrt DE405
! scope="col"| Angular deviation wrt DE405
|-
|'''Sun'''
|25593km
|34.13''
|-
|'''Moon 62x66x46'''
|26 km
|15.2''
|}

{| class="wikitable"
|-
!
! scope="col"| Number of elementary operations
! scope="col"| Number of trigonometric operations
|-
|'''Sun'''
|89
|10
|-
|'''Moon 62x66x46'''
|2671
|182
|-
|'''Moon 26x13x13'''
|917
|60
|-
|'''Moon 9x4x3'''
|401
|24
|}

References for the tables :
* "Modèles d'éphémérides luni-solaires", CNES DCT/SB/MS, 03/14/2011
* "Modèle MEEUS pour éphémérides Lune-Soleil : Compléments sur le nombre d'opérations", CNES DCT/SB/MS

{| class="wikitable"
|-
!
! scope="col"| execution time - DE405
! scope="col"| execution time- MEEUS
|-
|'''Sun'''
|59 s 548 ms
|19 s 938 ms
|-
|'''Moon 62x66x46'''
|11 s 625 ms
|3 mn 22 s 323 ms
|-
|'''Moon 26x13x13'''
|11 s 625 ms
|1 mn 17 s 74 ms
|-
|'''Moon 9x4x3'''
|11 s 625 ms
|40 s 326 ms
|}

In order to build such a Sun or Moon, one has to use the object MeeusSun or MeeusMoon which both extend AbstractCelestialBody. Note that it is not possible to build those celestial bodies from the CelestialBodyFactory, for the moment.

==== Basic board Sun model ====
The basic board Sun model is a simplified analytical model which gives the direction of the Sun (the normalized position) with respect to time.
This model is similar to the Meeus model (the constants of the model are different) and is adapted for onboard applications.
The reference inertial frame is the CIRF.

=== User-defined celestial bodies ===
User can defined its own celestial body by using <code>UserCelestialBody</code>.
This class requires to provide:
* Its name.
* Its position-velocity through time using a <code>PVCoordinateProvider</code> implementation.
* Its gravitational constant.
* Its pole motion using <code>IAUPole</code> implementation or directly the <code>UserIAUPole</code> implementation.
The <code>UserIAUPole</code> is a simple way to build standard pole motion from IAU note. It requires to provide for each component (α, δ and W) a list of functions of duration in days and duration in centuries (from a reference epoch) as defined in IAU note. This functions are <code>UnivariateDifferentiableFunction</code>.
Available functions in PATRIUS include:
* <code>PolynomialFunction</code>: polynomial function
* <code>SineFunction</code>: function of the form k.sin(f) with f an <code>UnivariateDifferentiableFunction</code>
* <code>CosineFunction</code>: function of the form k.cos(f) with f an <code>UnivariateDifferentiableFunction</code>

'''Example: building Ceres'''.
According to the IAU report, Ceres has the following parameters:
* α = 291◦ ± 5◦
* δ = 59◦ ± 5◦
* W = 170.90◦ + 952.1532◦d
With ''d'' being the interval in days from the standard epoch (the standard epoch is JD 2451545.0, i.e. 2000 January 1 12 hours TDB)

Ceres gravitational constant is 6.263E10 m^^3^^kg^^-1^^s^^-2^^.

If one knows Ceres motion given for instance by a <code>PVCoordinatePropagator</code> ''pv'', then one can build Ceres with the following code:

<syntaxhighlight lang="java">
// Gravitational parameter
final double gm = 6.263E10;

// Pole motion - Method 1 - Implementation if IAUPole interface
final IAUPole pole = new IAUPole() {
@Override
public double getPrimeMeridianAngle(final AbsoluteDate date) {
// W
final double d = date.durationFrom(AbsoluteDate.J2000_EPOCH) / Constants.JULIAN_DAY;
return FastMath.toRadians(170.90) + FastMath.toRadians(952.1532)* d;
}

@Override
public Vector3D getPole(final AbsoluteDate date) {
// Pole bias: alpha and delta
return new Vector3D(FastMath.toRadians(291), FastMath.toRadians(59));
}
...
};

// Pole motion - Method 2 - Use of UserIAUPole class
// Alpha 0 coefficients
final List<IAUPoleFunction> alpha0List = new ArrayList<IAUPoleFunction>();
alpha0List.add(new IAUPoleFunction(IAUPoleType.CONSTANT, new PolynomialFunction(new double[] { 291 }), IAUTimeDependency.DAYS);
final IAUPoleCoefficients1D alpha0Coeffs = new IAUPoleCoefficients1D(alpha0List);
// Delta 0 coefficients
final List<IAUPoleFunction> delta0List = new ArrayList<IAUPoleFunction>();
delta0List.add(new IAUPoleFunction(IAUPoleType.CONSTANT, new PolynomialFunction(new double[] { 59 }), IAUTimeDependency.DAYS);
final IAUPoleCoefficients1D delta0Coeffs = new IAUPoleCoefficients1D(delta0List );
// W coefficients
final List<IAUPoleFunction> w0List = new ArrayList<IAUPoleFunction>();
w0List.add(new IAUPoleFunction(IAUPoleType.CONSTANT, new PolynomialFunction(new double[] { 170.9 }), IAUTimeDependency.DAYS);
w0List.add(new IAUPoleFunction(IAUPoleType.SECULAR, new PolynomialFunction(new double[] { 0, 952.1532 }), IAUTimeDependency.DAYS);
final IAUPoleCoefficients1D wCoeffs = new IAUPoleCoefficients1D(w0List);
// Build pole
final IAUPole pole = new UserIAUPole(new IAUPoleCoefficients(alpha0Coeffs, delta0Coeffs, wCoeffs));

// Build Ceres body
final CelestialBody ceres = new UserCelestialBody("Ceres", pv, gm, pole, FramesFactory.getICRF(), null);

</syntaxhighlight>

Then <code>ceres</code> object possesses all features of:
* A <code>CelestialBody</code>: retrieve body-centered inertial frames or body-centered rotating frames
* A <code>PVCoordinateProvider</code>: retrieve position and velocity at any time

==== BodyShape====

The BodyShape interface carries servals features common to body shapes such as its name, frame, intersection point computation, distance to a line, closest point computation, body point transformation.
A couple of getter/setter allows to configure the LLHCoordinatesSystem associated to the shape, which can be ELLIPSODETIC, BODYCENTRIC_RADIAL or BODYCENTRIC_NORMAL. This coordinates system is used for instance by closest point computation or body point transformation.
The interface extends the PVCoordinatesProvider and ApparentRadiusProvider interfaces. The first carry the service to determine the PVCoordinates of the body at any date and the second describes two related features:
* Compute the apparent radius of the occulting body from the spacecraft (observer) position. Given a plane containing the spacecraft position, the center of the occulting body (the body shape) and the center of the occulted body, and given a line contained within this plane, passing by the spacecraft position and tangent to the mesh of the occulting body, the apparent radius corresponds to the length of the line starting from the center of the occulting body, perpendicular to the first given line and ending at the intersection of the two lines.
* Compute the apparent radius in a plane containing the spacecraft position, the center of the occulting body and a specified direction instead of the occulted body position. The rest of the behavior stays identical.
Note: The apparent radius is computed in one direction from the frame origin of the body to the perpendicular tangent line. In case of dissymmetric shape, this definition it might introduce some limitations as the radius computed in the other direction would be different.

==== OneAxisEllipsoid ====

This type is used to represent the shape of a planet. One very useful implementation represents an ellipsoid (OneAxisEllipsoid). It is constructed from an equatorial radius, a flattening coefficient, and a reference frame that will be used to localize Geodetic points on the shape.

The one-axis ellipsoid is a good approximate model for most planet-size and larger natural bodies. It is the equilibrium shape reached by a fluid body under its own gravity field when it rotates. The symmetry axis is the rotation or polar axis.

It could be interesting to obtain the intersection point of a line from the satellite to the surface of the body for a given altitude. To that purpose, one can use the method getIntersectionPoint(Line, Vector3D, Frame, AbsoluteDate, double) of the interface BodyShape.

<syntaxhighlight lang="java">

AbsoluteDate date = new AbsoluteDate(new DateComponents(2008, 03, 21),
TimeComponents.H12,
TimeScalesFactory.getUTC());
CelestialBodyFrame frame = FramesFactory.getITRF();
// Body shape model
OneAxisEllipsoid earth = new OneAxisEllipsoid(6378136.460, 1 / 298.257222101, frame);

// Satellite on any position

circ = new CircularOrbit(7178000.0, 0.5e-4, 0., FastMath.toRadians(50.), FastMath.toRadians(0.),
FastMath.toRadians(90.), PositionAngle.MEAN,
FramesFactory.getEME2000(), date, mu);

// Transform satellite position to position/velocity parameters in EME2000 and ITRF200B
PVCoordinates pvSatEME2000 = circ.getPVCoordinates();
PVCoordinates pvSatItrf = frame.getTransformTo(FramesFactory.getEME2000(), date).transformPVCoordinates(pvSatEME2000);
Vector3D pSatItrf = pvSatItrf.getPosition();

// Nadir point of the satellite
Vector3D pointItrf = new Vector3D.ZERO;
Vector3D direction = Vector3D(1., pSatItrf,-1., pointItrf);
Line line = new Line(pSatItrf, direction);
// intersection point between the ellipsoid and the line that joins the satellite and the center of the body
double altitude = 0;
EllipsoidPoint nadir = earth.getIntersectionPoint(line, pSatItrf, frame, date, altitude);

</syntaxhighlight>

Note: The ThreeAxisEllipsoid class shares many features with the OneAxisEllipsoid and allows to define an ellipsoid fully defined by its three axis radius (along the directions (0, 0, 1) ; (0, 1, 0) ; (0, 0, 1)).

OneAxisEllipsoid extends the AbstractEllipsoidBodyShape class (also extended by ThreeAxisEllipsoid) and AbstractEllipsoidBodyShape implements the EllipsoidBodyShape interface, which extends the StarConvexBodyShape interface, which, at its turn, extends the BodyShape interface (already introduced).

==== Facet celestial body ====

<code>FacetBodyShape</code> is a class used to define a celestial body as a mesh. This is particularly useful for small irregular bodies such as asteroids.
For example, Phobos contains here 100 000 vertices and 200 000 facets:
[[File:Phobos.jpg|center]]

This class:
* Inherits the <code>BodyShape</code> interface and hence can be used together with <code>EclipseDetector</code> and <code>SensorModel</code>.
* Provides some useful and optimised methods for small body handling. Facets are connected to each other allowing some methods to be writen in a recursive or iterative way and hence being very fast. If n is the number of vertices of the body, fast recursive or iterative methods are in O(log(n)).

For use as a <code>CelestialBody</code>, this class must be linked to a <code>UserCelestialBody</code>.

===== Mesh provider =====

A mesh is described by a list of facets <code>Triangle</code> and or vertices <code>Vertex</code>. A <code>Triangle</code> contains three vertices.
Mesh is provided by the generic interface <code>MeshProvider</code>. This interface currently possesses two implementation:
* <code>ObjMeshLoader</code>: in this case, the mesh is provided under official .obj file format. See [https://en.wikipedia.org/wiki/Wavefront_.obj_file This page] for more information on the format.
* <code>GeodeticMeshLoader</code>: in this case, the mesh is provided in an ASCII column file listing each vertex in the format [Latitude Longitude Altitude].

===== Available methods =====

Note that most methods return exact results. For example, <code>distanceTo</code> methods returns exact distance to mesh body. Only <code>getEllipsoid(EllipsoidType)</code> and <code>getApparentRadius</code> methods return a simplified result.

<code>FacetBodyShape</code> provides the following methods:
* <code>getIntersection(Line, Vector3D, Frame, AbsoluteDate)</code> and similar which return an <code>Intersection</code> object.This object contains the intersection point as well as the <code>Triangle</code> containing the intersection point. This method is recursive and is in O(log(n)).
* <code>buildPoint(LLHCoordinatesSystem, double, double, double, String)</code> and similar which return the facet point associated to the specified corrinates in the given LLH coordinates system.
* <code>getApparentRadius</code> / <code>getApparentRadiusDirection</code> methods which provides the local radius of the body shape seen by an observer in the direction of an occulted body or a specified direction using an approximate iterative algorithm. This method is used by EclipseDetector for instance.
* <code>resize(MarginType, double)</code> method which returns a resized body shape.
* <code>closestPointTo</code> methods which return the two closest points between the line given in input and the current facet body shape. One of the two points belongs to the line, the other to the facet body shape.
* <code>distanceTo()</code> method which returns the distance to the body. This method is recursive and is hence in O(log(n)).
* <code>getNeighbors()</code> methods which returns the neighbors triangles to:
** A point or a triangle given a "neighborhood distance"
** A triangle given a "neighborhood order". In this case, order 1 returns the immediate neighbors of the triangles, order 2 returns also the neighbors' neighbors and so on.
This method is recursive and is hence in O(log(n)).
* <code>getFieldData()</code> which returns a container <code>FieldData</code> containing data related to the field of view:
** Visible triangles from the satellite field of view <code>IFieldOfView</code>. A visible triangle must be entirely in the field of view and not masked by any other triangle.
** Contour of the seen triangles. Contour is strictly contained in the field of view
If main direction of the field of view is provided, this method is recursive and is in O(log(n)). Otherwise, it is in O(n) and is much slower.
* <code>isInEclipse()</code> method which returns true if the satellite is currently in eclipse, false otherwise. Penumbra is not taken into account. This method is in O(log(n)).
* <code>getNeverVisibleTriangles()</code> which returns a list of facets which are never visible from the provided ephemeris. Visibility criteria is the same as for <code>getFieldData()</code> method. This method is in O((n)).
* <code>getNeverEnlightenedTriangles()</code> which returns a list of facets which are never enlightened by the Sun. Visibility criteria is the same as for <code>getFieldData()</code> method. This method is in O((n)).
* <code>getVisibleAndEnlightenedTriangles()</code> which returns a list of facets which are visible and enlightened at the same time, at least once on the provided ephemeris. Visibility criteria is the same as for <code>getFieldData()</code> method. This method is in O((n)).
* <code>getEllipsoidType()</code> which returns the type of the ellipsoid.

The class <code>BodyShapeFitter</code> allows to build shapes fitted on the main Shape provided as input. Different criteria are available and the type of ellipsoid returned can be obtained by calling the method <code>getEllipsoid(EllipsoidType)</code>.

==== EllipsoidPoint====

The ellipsoid point is defined by a latitude, a longitude and an altitude in the frame associated to the ellipsoid (EllipsoidBodyShape). It could be interesting to know the position of a satellite in terms of geodetic coordinates rather than Cartesian ones and vice versa (the corresponding methods in OneAxisEllipsoid).

<syntaxhighlight lang="java">
// equatorial radius of the celestial body
double ae = 6378137.0;
// flatness of the celestial body
double f = 1.0 / 298.257222101;
// date
AbsoluteDate date = AbsoluteDate.J2000_EPOCH;
// reference frame attached to the body
CelestialBodyFrame frame = FramesFactory.getITRF();
// body shape model (ellipsoid)
OneAxisEllipsoid model = new OneAxisEllipsoid(ae, f, frame);

// transformation with jacobian matrix : cartesian to geodetic

// initial cartesian point that will be transformed
Vector3D cp = new Vector3D(4637885.347, 121344.1308, 4362452.869);
// coresponding ellipsoid point
EllipsoidPoint point = model.buildPoint(cp, frame, date, "point");

// transformation with jacobian matrix : geodetic to cartesian

// coresponding Cartesian point
Vector3D cp2 = model.computePositionFromEllipsodeticCoordinates(0.852479154923577, 0.0423149994747243, 111.6);
</syntaxhighlight>

It could be also interesting to obtain the jacobian matrix of the transformation.

<syntaxhighlight lang="java">

// transformation : cartesian to geodetic

final double[][] computedJacobian = LLHCoordinatesSystem.ELLIPSODETIC.jacobianFromCartesian(point);

// transformation : geodetic to cartesian

final double[][] computedJacobian2 = LLHCoordinatesSystem.ELLIPSODETIC.jacobianToCartesian(point);
</syntaxhighlight>

The enumeration LLHCoordinatesSystem.ELLIPSODETIC allows the computation of the time derivatives of the LLH coordinates of a point. There are two algorithms implemented:
* Analytical calculation for OneAxisEllipsoid
* Finite-difference numerical calculation for all other types of ellipsoid, such as ThreeAxisEllipsoid

The selection between the analytical and numerical method is automatic and the only function to call is the following:
<syntaxhighlight lang="java">
double[] LLHCoordinatesSystem.ELLIPSODETIC.computeLLHRates(final BodyShape bodyShape, final PVCoordinates pv, final Frame frame,
final AbsoluteDate date)
</syntaxhighlight>

The longitude, latitude, and height rates are returned and expressed in rad/s, rad/s, et m/s respectively.

Here is a full example of how to use this functionality:

<syntaxhighlight lang="java">
// Create Earth OneAxisEllipsoid
final double ae = 6378137.0;// GRS80 constant
final double flattening = 1.0 / 298.257222101;// GRS80 constant
final CelestialBodyFrame itrf = FramesFactory.getITRF();
final CelestialBodyFrame gcrf = FramesFactory.getGCRF();
final OneAxisEllipsoid earth = new OneAxisEllipsoid(ae, flattening, itrf);
final AbsoluteDate date = new AbsoluteDate(2010, 7, 9, 20, 30, 0);

// Create orbit around the Earth in GCRF
final double mu = 3.986005e14;// GRS80 constant
final KeplerianOrbit orbit = KeplerianOrbit(ae + 700e3, 0.0, 0.5, 1.2, 1.1, 2.3, PositionAngle.TRUE, gcrf, date, mu);

// Compute the rates using the analytical implementation
final double[] rates = LLHCoordinatesSystem.ELLIPSODETIC
.computeLLHRates(earth, orbit.getPVCoordinates(), gcrf, date);
</syntaxhighlight>

== Getting Started ==
TBD

== Contents ==
=== Interfaces ===

{| class="wikitable"
|-
! scope="col"| Interface
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''ApparentRadiusProvider'''
|Interface representing apparent radius providers.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/ApparentRadiusProvider.html ...]
|-
|'''BodyShape'''
|Interface representing the rigid surface shape of a natural body.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/BodyShape.html ...]
|-
|'''CelestialBody'''
|Interface for celestial bodies like Sun, Moon or solar system planets.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/CelestialBody.html ...]
|-
|'''CelestialBodyEphemeris'''
|Interface for celestial body ephemeris like Sun, Moon or solar system planets.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/CelestialBodyEphemeris.html ...]
|-
|'''CelestialBodyLoader'''
|Interface for celestial body loaders.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/CelestialBodyLoader.html ...]
|-
|'''CelestialBodyEphemerisLoader'''
|Interface for celestial body ephemeris loaders.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/CelestialBodyEphemerisLoader.html ...]
|-
|'''MeshLoader'''
|Interface for FacetCelestialBody mesh provider.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/mesh/MeshProvider.html ...]
|}

=== Classes ===
{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''CelestialBodyFactory'''
|Factory class for bodies of the solar system.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/CelestialBodyFactory.html ...]
|-
|'''BodyPoint'''
|Point location relative to a 2D body surface.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/GeodeticPoint.html ...]
|-
|'''JPLCelestialBodyLoader'''
|Loader for JPL ephemerides binary files (DE 405, DE 406, ...).
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/JPLCelestialBodyLoader.html ...]
|-
|'''OneAxisEllipsoid'''
|Modeling of a one-axis ellipsoid.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/OneAxisEllipsoid.html ...]
|-
|'''ThreeAxisEllipsoid'''
|Modeling of a tri-axis ellipsoid.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/ThreeAxisEllipsoid.html ...]
|-
|'''MeeusSun'''
|Position of the Sun according to Meeus model. Three models with there appropriate equations are avaible : the standard model (former MeeusSun), Stela model (former MeeuSunStela) and an on-board model
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/MeeusSun.html ...]
|-
|'''MeeusMoon'''
|Position of the Moon according to Meeus model.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/MeeusMoon.html ...]
|-
|'''BasicBoardSun'''
|Direction of the Sun according to a basic board Sun model.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/BasicBoardSun.html ...]
|-
|'''UserCelestialBody'''
|User-defined celestial body
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/UserCelestialBody.html ...]
|-
|'''UserIAUPole'''
|User-defined IAU pole motion
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/UserIAUPole.html ...]
|-
|'''IAUPoleFactory'''
|Factory for retrieval of solar system bodies IAU pole data
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/IAUPoleFactory.html ...]
|-
|'''IAUPoleFunction'''
|Atomic IAU pole function. IAU pole data is the sum of atomic IAUPoleFunction.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/IAUPoleFunction.html ...]
|-
|'''FacetBodyShape'''
|Celestial body defined by a mesh.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/mesh/FacetBodyShape.html ...]
|-
|'''BodyShapeFitter'''
|Fitter for a given body shape provided as input.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/mesh/BodyShapeFitter.html ...]
|-
|'''Triangle'''
|Unitary facet (triangle) for a FacetCelestialBody.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/mesh/Triangle.html ...]
|-
|'''ObjMeshLoader'''
|.obj 3D file mesh loader.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/mesh/ObjMeshLoader.html ...]
|-
|'''GeodeticMeshLoader'''
|Mesh loader for ASCII files describing the body with latitude/longitude/altitude components (1 per line).
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/mesh/GeodeticMeshLoader.html ...]
|}

[[Category:User_Manual_4.17_Flight_Dynamics]]

User Manual 4.17 Events: orbital

2025-11-27T09:24:38Z

Admin tsn :

== Introduction ==
=== Scope ===
Here are presented all the events detectors of the theme "orbital".

=== Javadoc ===
Those event detectors are available in the packages :

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detecors/package-summary.html Package fr.cnes.sirius.patrius.events.detectors]
|}

=== Links ===
None as of now.

=== Useful Documents ===
None as of now.

=== Package Overview ===
None as of now.

== Features Description ==
=== Detectors ===
This section describes the meaning of the g switching function for the "orbital" event detectors, and their particularities :

==== Alignment Detector ====

This detector computes the difference <math>\theta</math> between the alignment angle <math>\beta_{threshold}</math> and the angle between the satellite position, the central body and the second body position projection in the orbital plane. 
If <math>\theta_1 =-\pi - \theta</math> and <math>\theta_2 = \pi - \theta</math>, the g switching function will be: 
<math>\theta_1</math> if <math>\theta < \theta_1</math>, 
<math>\theta</math> if <math>\theta < \theta_2</math>, 
and <math>\theta_2</math> otherwise.

<math>\beta_{threshold}</math> is an oriented angle and is positive when is oriented as the orbital momentum.

[[File:alignmentDetector.png|750x400px]]

Axes <math>\vec a</math> (satellite normalized position) and <math>\vec b</math> (satellite normalized velocity) are transformed into axes <math>\vec x</math> and <math>\vec y</math> knowing the value of <math>\beta_{threshold}</math> angle; g is found projecting the target body position in the orbital plane and computing its <math>\vec x</math> and <math>\vec y</math> components.

* <math>g>0 :</math> target body projection is in the half-plane <math>y>0</math>
* <math>g<0 :</math> target body projection is in the half-plane <math>y<0</math>
* <math>g=0 :</math> target body projection belongs to the straight line <math>y=0</math>

==== Altitude Detector ====

The g switching function measures the difference between the current altitude <math>h_{sat}</math> and the threshold altitude <math>h_{thr}</math>.

* <math>g > 0 : h_{sat} > h_{thr}</math>
* <math>g<0 : h_{sat} < h_{thr}</math>

==== ApsideDetector ====

The g switching function is the dot product of the satellite position and velocity vectors: <math>g =\vec p \cdot \vec v</math>

* <math>g>0 :</math> the satellite is in the half-orbit from perigee to apogee;
* <math>g<0 :</math> the satellite is in the half-orbit from apogee to perigee.

[[File:apside.png|center|539x316px]]

==== DateDetector ====

The g switching function is the value of the difference between the current date and the target date. If no event dates have been added i.e. if no target dates have been initialized, <math>g=-1</math>.

==== RelativeDateDetector ====
This detector extends of DateDetector. The g switching function is the same as the [[#DateDetector|DateDetector]].

==== EclipseDetector ====

This detector is in charge of the umbra/penumbra eclipse events detection. 
Different features are available:
* the occulted and occulting bodies are both spherical;
* the occulted body is a direction;
* the occulting body has an ellipsoid shape.

In addition to that, the <code>EclipseDetector</code> can detect eclipse events based on a threshold lighting ratio <math>\epsilon_{0}</math>: 
<math>0<=\epsilon_{0}<=1</math>. 
When <math>\epsilon_{0}=0</math>, an eclipse event is triggered only if whole occulted body is hidden by the occulting body (total eclipse); when <math>\epsilon_{0}=1</math>, an event is immediately triggered when the occulted body is partially hidden (penumbra eclipse). 
As a general rule, the lighting ratio is equal to: 
<math>\epsilon = 1-\frac{A_{occulted}}{\pi r_{occulted}^2}</math> 
where <math>r_{occulted}</math> is the apparent radius of the occulted body. 
The g function is: <math>g=\epsilon_{0}-\epsilon</math>

The g switching function computation needs the satellite position vector (<math>\vec P_{sat}</math>), the occulted body (<math>\vec P_{ted}</math>) and occulting body (<math>\vec P_{ing}</math>) position vectors. 
<math>\vec {PS}=\vec {P_{ted}}-\vec {P_{sat}}</math>, <math>sin(\widehat{rs})=\dfrac{r_{ted}}{|\vec {PS}|}</math> 
<math>\vec {PO}=\vec {P_{ing}}-\vec {P_{sat}}</math>, <math>sin(\widehat{ro})=\dfrac{r_{ing}}{|\vec {PO}|}</math>. 
<math>\alpha</math> is the angle between <math>\vec {PS}</math> and <math>\vec {PO}</math>. 
Distinction is made between total eclipse and partial eclipse. 
The following diagrams show the evolution of the g function value for an eclipse scenario with two spherical bodies.

===== Total eclipse =====

The passage to umbra is detected. The g switching function is <math>g = \alpha- \widehat{ro} + \widehat{rs}</math>.

* <math>g>0 :</math> satellite is not in eclipse:
[[File:eclipse1.png|576x274px]]
* <math>g=0 :</math> beginning of umbra:
[[File:eclipse2.png|570x161px]]
* <math>g<0 :</math> umbra:
[[File:eclipse3.png|574x180px]]
* <math>g=0 :</math> end of umbra:
[[File:eclipse4.png|570x182px]]
* <math>g>0 :</math> satellite is not in eclipse:
[[File:eclipse5.png|588x264px]]

===== Partial eclipse =====

The passage to penumbra is detected. The g switching function is <math>g = \alpha- \widehat {ro} - \widehat {rs}</math>.

* <math>g>0 :</math> satellite is not in eclipse:
[[File:eclipse6.png|566x273px]]
* <math>g=0 :</math> beginning of penumbra:
[[File:eclipse7.png|552x198px]]
* <math>g<0 :</math> penumbra:
[[File:eclipse8.png|581x178px]]
* <math>g=0 :</math> end of penumbra:
[[File:eclipse9.png|578x217px]]

Another feature of the <code>EclipseDetector</code> is the detection of partial and total eclipse by a spheroid.

[[File:ellipsoideclipse.png|center]]

The point on the horizon (H) is calculated as the point of the ellipsoid that is in the same plane as A, C and S (respectively center of occulted body, center of occulting body and satellite). The distance of H to the center C of the ellipsoid is then projected onto a plane orthogonal to the Satellite / Occulting (SA) body direction, and the resulting length is considered as the radius of an "apparent" sphere representing the occulting body. The partial and total eclipse are then computed as per above.

===== Particular case =====

A specific case is having a spacecraft lower than the occulting body radius (i.e. spacecraft altitude < occulting body radius). 
Two cases are possible:
* The satellite is behind the occulted body (angle occulted body- occulting body - satellite > Pi/2): satellite is considered to be in total eclipse.
* The satellite is in front of the occulted body (angle occulted body- occulting body - satellite <= Pi/2): apparent radius of occulting body cannot be computed. Hence it is considered to be equal to Pi/2 (slight approximation since it means satellite is considered to be lying exactly on the surface of the occulting body). Then usual computation of g function applies.

==== BodyInEclipseDetector====

This detector is in charge of the umbra/penumbra eclipse events detection for a non-point target body. 3 bodies are considered to compute the BodyInEclipse events:

*Target body: body on which the eclipse events are to be detected.

*Occulted body: this is the body that is no longer visible from the target body due to the presence of the occulting body in the line of sight (the occulted body is generally the sun).

*Occulting body: body that causes the eclipse.
[[Fichier:BodyInEclipseDetector1.png|centré|683x683px]]
The following assumptions are made:
* The three bodies are considered spherical during calculations (the apparent radius of the bodies are used).
* For the cases where the target body is fully in eclipse, the target body must be much smaller than the possible irregularities of the occulting body to avoid false positives. (Further explanation of this point in the edge cases section).
* No atmospheric effect is taken into account.
*The propagation delay can be activated or not.

The core of the algorithm consists of selecting a point on the surface of the target that is representative of the surface of the target as a whole, and then calculating the illumination rate at that point.

The calculation of g is therefore done in three steps:
*Selection of the reference point: This depends on the type of eclipse targeted (partial or total; whether the body is completely eclipsed or not), the chosen model (complete or simplified), and the relative position of the bodies involved.
* Calculation of the illumination rate at the selected target point.
*Comparison of the obtained illumination rate with the target illumination rate (0 if we are looking for total eclipses, 1 if we are looking for partial eclipses).
2 modes are available for the computation of eclipse events:

1. Exact model:

In this model, the occulted body is considered as non-punctual. 4 points are of interest to detect the eclipse events:
*HPPU = point of interest for entry partially in penumbra
*HPU = point of interest for entry partially in umbra
* HTPU = point of interest for entry totally in penumbra
*HTU = point of interest for entry totally in umbra
[[Fichier:BodyInEclipseDetector2.png|centré|776x776px]]
2. Approximative model

In this model, the occulted body is considered as punctual. In this case, only 2 interest points exists to detect eclipse events:
*HP = point of interest for entry partially in eclipse
*HT = point of interest for entry totally in eclipse
[[Fichier:BodyInEclipseDetector3.png|centré|771x771px]]
For any of the models, the lighting ratio of the corresponding interest points is computed to detect the events.

The lighting ratio is then compared against the target lighting ratio (0 if we want to detect total eclipses and 1 for partial eclipses), and the value of the g function (switching function) is returned for a given date.

'''Edge Cases:'''

'''Occulting body << Target Body:'''

If the occulting body is smaller than the target body, it might happen that none of the 4 points of interest is in eclipse, however the target body is partially in eclipse as shown in the figure below:
[[Fichier:BodyInEclipseDetector4.png|centré|806x806px]]
This case is possible only if the line SA intersects the target body. In this case, none of the interest points of the exact model or of the approximative model are used to compute the lighting ratio. In this case it is the intersection point HC that is used to compute the lighting ratio (to know if it is inside umbra or only inside penumbra).

'''Shape of occulting body non spherical:'''

In the hypotheses section it was said that the 3 bodies are considered spherical. However, it is really only the occulted and the target bodies that have to be spherical. The occulting body might have any other shape. It is during the computation that we model the occulting body as spherical by using the getApparentRadius method.

In certain edge cases, a BodyInEclipse event might be raised by the propagator, even though this is not actually the case. This type of situation can occur when the occulting body is elongated in the direction of the plane of the eclipse.
[[Fichier:BodyInEclipseDetector5.png|centré]]
The calculation method considers a planar projection of the problem. When an object is detected as "completely in the shadow" of another, it is ensured that the furthest point of the eclipse cone in the plane containing the centers of the three objects is in eclipse. This guarantees that all points of the target object belonging to this plane are in eclipse. However, there is no guarantee for points outside of the plane. This is not an issue when the obscuring object is spherical, but it can become one when it is elongated. In the example below, the target is considered "entirely" eclipsed by the detector, even though some points are illuminated.

This type of case is unlikely to occur in the Earth-Moon scenario, where the obscuring body is very close to a sphere, but it is not impossible in the case of asteroids, which have non-regular shapes. Other problems of this kind can arise when the body is not convex, but such cases become extremely rare.

This is why for the cases where the target body is fully in eclipse, the target body must be much smaller than the possible irregularities of the occulting body to avoid false positives.

====PlaneCrossingDetector====
The detector allows to detect if a spacecraft crosses a plane defined in a specific reference frame. The following entries are needed to define a <code>PlaneCrossingDetector</code>:
*plane reference frame ;
*point which is contained in the plane ;
* normal vector to plane.

The detection function <math>g()</math> monitors the dot product between the normal vector to plane and the distance position vector of the spacecraft with respect to the origin of the point of the plan:
*<math>g>0 :</math>the satellite is over the plane;
*<math>g<0 :</math>the satellite is under the plane.

==== NodeDetector ====
The <code>NodeDetector</code> detects the orbital nodes; the user can choose what the detect (ascending nodes, descending nodes or both) through the <code>slopeSelection </code> parameter. It is a particular application case of the <code>PlaneCrossingDetector</code>. 
The g switching function returns the Z component of the satellite position in the geocentric frame:
* <math>g>0 :</math>the satellite is over the equatorial plane (in its orbit from ascending node to descending node);
*<math>g<0 :</math>the satellite is under the equatorial plane (in its orbit from descending node to ascending node).

====DistanceDetector====

The <code>DistanceDetector </code> detects the time when the distance between the spacecraft and a point of space reaches a given value.

The point of space is given as a <code>PVcoordinatesProvider</code> : it can be either a celestial body (as a <code>CelestialBody</code>), a point at the surface of a body (as a <code>TopocentricFrame</code>), or any another class that implements that interface.

Here is the example for a point on the surface of a body :

<syntaxhighlight lang="java">
// earth shape
final BodyShape earth = new OneAxisEllipsoid(earthRadius, ea, ITRFFrame);

// considered point
final EllipsoidPoint point = new EllipsoidPoint(ellipsoid, LLHCoordinatesSystem.ELLIPSODETIC, latitude, longitude, altitude, "point ");

// associated topocentric frame : this object is a PVCoordinatesProvider
final TopocentricFrame topoFramePoint = new TopocentricFrame(point, "Gstation");

// detector
final DistanceDetector detector = new DistanceDetector(topoFramePoint, distance);
</syntaxhighlight>

Its g switching function computes the difference between the spacecraft position and the point position (in the same frame), and then subtracts the given distance from its norm.

*<math>g>0 :</math>the distance spacecraft/point is bigger than the distance threshold value;
*<math>g<0 :</math>the distance spacecraft/point is smaller than the distance threshold value;

====ExtremaDistanceDetector====

The <code>ExtremaDistanceDetector</code> detects if the spacecraft is at a local extremum for the distance relative to a point of space, defined the same way as in the previous DistanceDetector. The choice of the extremum (maximum, minimum, or both) is done with the constructor, through the <code>distanceType</code> parameter.

The g switching function returns the square norm of the velocity for the vector representing this distance, thus the sign change is indeed a local extremum.

====ExtremaLatitudeDetector====

The <code>ExtremaLatitudeDetector</code> detects if the spacecraft is at a local extremum for the geodetic latitude. The choice of the extremum (maximum, minimum, or both) is done with the constructor, through the <code>latitudeType</code> parameter.

The g switching function returns the z-component of the spacecraft velocity in the orbit definition frame.

====LatitudeDetector====
The <code>LatitudeDetector</code> detects the time when the spacecraft reaches a given geodetic latitude, the <code>BodyShape</code> of the earth being known to compute it.

The g switching function returns the difference between the current latitude and the one to detect.

====ExtremaLongitudeDetector====

The <code>ExtremaLongitudeDetector</code> detects if the spacecraft is at a local extremum for the longitude. The choice of the extremum (maximum, minimum, or both) is done with the constructor, through the <code>extremumType</code> parameter.

The g switching function is the dot vector of the position with the result of the cross product of the velocity relative to the body and unitary vector Z : 
<math>g =\vec P \cdot (\vec Vrel \wedge \vec Vz)</math>

The main part of this function is the cross product which switches when the relative velocity is colinear to Z.

====LongitudeDetector====
The <code>LongitudeDetector</code> detects the time when the spacecraft reaches a given longitude.

Working with longitude always gives a problem of continuity when longitude pass from PI rad to- PI rad. The best solution find to avoid this is to save some information from the last computation of the g function.

In this way the g function is the following difference expressed between-PI rad and PI rad : currentLongitude - longitudeToDetect

At each g function call, this difference is saved, and each time the difference between the current difference and the last difference is greater than PI rad, it means there is a discontinuity, the g fonction is opposed. This avoids discontinuity. Then all zero are detected.

This solution, also avoids problem about detecting a longitude at PI rad further (that we meet with a sin(a- b) g function).

====AOLDetector====

The <code>AOLDetector</code> detects when the spacecraft reaches a predetermined argument of latitude (true, mean or eccentric supportes) with respect to a given equator ; the argument of latitude is the angle between the spacecraft position and the ascending node.

The g switching function returns the sinus of the difference between the spacecraft current angular position <math>\beta</math> and the threshold position value <math>\beta_{input}</math>: 
<math>g=sin(\beta- \beta_{input})</math> 
An AOL event is triggered only if the g-function slope is positive at its zero.

====AnomalyDetector====

The <code>AnomalyDetector</code> detects when the spacecraft reaches a predetermined anomaly; the anomaly is the angle between the spacecraft position and the perigee. 
Three types of anomaly can be detected: true, mean and eccentric anomaly.

The g switching function returns the sinus of the difference between the spacecraft current anomaly and the threshold anomaly value: 
<math>g=sin(\alpha- \alpha_{input})</math> 
(This g function is identical to the AOLDetector g function). 
Like the <code>AOLDetector</code>, an anomaly event is triggered only if the g-function slope is positive at its zero.

Using precaution : This detector is unusable on a circular orbit where the perigee always moves very fast and in any way.

====ThreeBodiesAngleDetector====

The <code>ThreeBodiesAngleDetector</code> detects when the angle between three bodies (they can be celestial bodies, spacecrafts, ground stations, ...) is equal to a predetermined value. 
If <math>\vec{P_{1}}</math>, <math>\vec{P_{2}}</math> and <math>\vec{P_{3}}</math> are the positions of the three bodies, and <math>\vec{P_{21}}</math> is the difference <math>\vec{P_{2}}-\vec{P_{1}}</math> and <math>\vec{P_{23}}</math> the difference <math>\vec{P_{2}}-\vec{P_{3}}</math>, the computed angle will be: <math>\widehat{\vec{P_{21}} \vec{P_{23}}}</math>

[[File:threeBodies.PNG|center]]

The g switching function returns the difference between the current angle between the three bodies and the threshold angle. The threshold angle is not oriented and its value is between 0 and PI.

====ExtremaThreeBodiesAngleDetector====
The <code>ExtremaThreeBodiesAngleDetector</code> detects when the angle between three bodies (defined the same way as in the <code>ThreeBodiesAngleDetector</code>) reaches its minimal or maximal value. 
The choice of the detected extremum (maximum, minimum, or both) is done with the constructor, through the <code>extremumType</code> parameter.

The g switching function returns the derivative of the angle value (in fact, part of the derivative : a factor with a
constant sign has been ignored). 
This derivative is obtained by expressing all the positions and velocities of the two extreme points (<math>P_{1}</math> and <math>P_{3}</math>) in a frame linked to the one at the angle origin (<math>P_{2}</math>). 
If the two vectors from the new origin are <math>\vec{P_{21}}</math> and <math>\vec{P_{23}}</math> the angle expression is : <math>\arccos(\vec{P_{21}}.\vec{P_{23}} / (|\vec{P_{21}}|.|\vec{P_{23}}|))</math> 
Once derivated as <math>(gof)' = (g'of).f'</math> and the <math>arccos</math> derivative being always negative, the switching function is minus the derivative of the inner expression <math>\vec{P_{21}}.\vec{P_{23}} / (|\vec{P_{21}}|.|\vec{P_{23}}|)</math>.

====BetaAngleDetector====

The <code>BetaAngleDetector</code> detects when the beta angle reaches a predetermined value; the beta angle is the angle between the orbit plane and the vector to the Sun.
[[File:BetaAngle.png|center]]

The beta angle belongs to [- π/2 , π/2 ]; its sign is positive when the Sun is in the half-plane containing the spacecraft's momentum.

==== LocalTimeAngleDetector====

The <code>LocalTimeAngleDetector</code> detects when the spacecraft local time is equal to a predetermined value; the spacecraft local time is the angle between the projections of the Earth-Sun vector and the Earth-spacecraft vector in the equatorial plane plus PI. In PATRIUS, local time is expressed as an angle in the range [-PI; PI[. Local time angle is PI (or 12.00h) when the geometric angle Sun-Earth-Spacecraft is 0 and 0 (or 0.00h) when this angle is PI. 
The local time is increasing for prograde orbits and decreasing for retrograde orbits. The events are detected in both cases.

The g function is the following difference expressed between-PI rad and PI rad : 
<math>currentLocalTime- localTimeToDetect</math>

At each g function call, this difference is saved, and each time the difference between the current difference and the last difference is greater than PI rad, it means there is a discontinuity, the g fonction is opposed. This avoids discontinuity. Then all zero are detected.

This solution, also avoids problem about detecting a local time at PI rad further (that we meet with a sin(a- b) g function).

====BodyPointLocalTimeAngleDetector====

The <code>BodyPointLocalTimeAngleDetector</code> follows the same logic as its parent class <code>LocalTimeAngleDetector</code> but, instead of computing the events for a certain position of the spacecraft, the events are computed with respect to a point of the surface of the body, by using the zenithal direction (normal to the surface).

To compute the local time of a certain point in a body, first the Frame is verified (it cannot be null). Then, the normal direction of the body point is computed. Afterwards, the sun position is obtained. The local time corresponds to the angle between the projections of the Earth-Sun and the normal direction over the equatorial plane plus PI.

====SolarTimeAngleDetector====

The <code>SolarTimeAngleDetector</code> detects when the spacecraft solar time is equal to a predetermined value; the spacecraft solar time is the angle between the the Earth-Sun projection in the orbital plane and the Earth-spacecraft vector plus PI. In PATRIUS, solar time is expressed as an angle in the range [-PI; PI[. Solar time angle is PI (or 12.00h) when the geometric angle Sun-Earth-Spacecraft is 0 and 0 (or 0.00h) when this angle is PI. 
The solar time is always increasing with time. It is mesured around the orbit momentum.

The g switching function returns the sinus of the difference between the spacecraft current solar time <math>\theta</math> and the threshold solar time value <math>\theta_{t}</math>: 
<math>g=sin(\theta- \theta_{t})</math> 
Like the <code>AOLDetector</code>, a solar time event is triggered only if the g-function slope is positive at its zero.

====NadirSolarIncidenceDetector ====

The <code>NadirSolarIncidenceDetector</code> detects when the solar incidence, seen from the nadir point of the spacecraft, reaches a predetermined value. 
The solar incidence is the angle between the nadir- satellite vector and the nadir - sun vector.

[[File:nadirsolarincidence.png|center]]

====BodyPointSolarIncidenceDetector====

The <code>BodyPointSolarIncidenceDetector</code> detects when the solar incidence angle reaches a predetermined value. The solar incidence is the angle between the interest point-satellite vector and the interest point-sun vector. The interest point being described by a BodyPoint.

[[Fichier:BodyPointSolarIncidenceDetector.png|center]]

====EarthZoneDetector====

The <code>EarthZoneDetector</code> detects when the spacecraft enters and leaves an earth zone. Several separated zones can be defined for one detector instance. In that case, the EarthZoneDetector detects the entery of the satellite NADIR point in any of the zones.

The zones can be described two ways :
*As an array of {latitude, longitudes} that define the geodetic points with a zero altitude on a BodyShape. With this definition, the test made will be the entering of the spacecraft's NADIR point in the zone.
*As an array of vectors expressed in a given frame. With this definition, the entering of the spacecraft itself in the conic field from the center of the given frame to those points will be detected. Note that the given frame must be a terrestrial frame for the detection of earth zones entering, but the use of other frames is possible (other bodies, inertial frames…).

In both cases, the points must respect the following conditions :
*At least 3 points are needed to define a zone
*two consecutive points must not be too close (1.e-10 on the difference of thier normalized values)
*the arc between two consecutive points must not cross the one between two consecutive others of the same zone.

The points must also be given in the right order : from the point i to the point i + 1, if the associated vector from the center of the earth are <math>v_{i}</math> and <math>v_{i + 1}</math>, the inside of the zone is on the left, e.g. the side of the positive cross vector <math>v_{i} . v_{i + 1}</math>.

Constructors with default maxCheck and threshold values are available, but beware of their values, and use the other constructors if needed : if the zone is complex and the MaxCheck too large, the event detection could fail, because it would not manage to converge. To compute the event with enough precision to converge, set a small enough MaxCheck. To compute an approximative event even if the zone is precise and complex, set a large enough Threshold.

===Particular detections===
All those detectors can be used for the following particular cases :

*sub-solar point reaching : use the SolarTimeAngleDetector with a "12h" time to detect.
*generic masking by a spherical body : use the GenericEclipseDetector, or the ThreeBodiesAngleDetector.
*terminator reaching (the nadir point reaches the night / day limit) : use the NadirSolarIncidenceDetector with a zero incidence.
*Sun interference in ground antennas : use the ThreeBodiesAngleDetector.
*RF interference between the main spacecraft and another one : use the ThreeBodiesAngleDetector

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

== Contents==
===Interfaces===
All the detectors implement the interface :

{| class="wikitable"
|-
! scope="col" |Interface
! scope="col" |Summary
! scope="col" |Javadoc
|-
|EventDetector
|This interface represents an event finder.
|[<nowiki/>{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/EventDetector.html EventDetector ]
|}

===Classes===
{| class="wikitable"
|-
! scope="col" |Class
! scope="col" |Summary
! scope="col" |Javadoc
|-
|AlignmentDetector
|This class handles (satellite/central body/projection in the orbital plane of secondary body) alignment events.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/AlignmentDetector.html AlignmentDetector]
|-
|AltitudeDetector
|This class handles satellite altitude crossing events.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/AltitudeDetector.html AltitudeDetector]
|-
|ApsideDetector
|This class handles satellite apogee and perigee crossing events.
| [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/ApsideDetector.html ApsideDetector]
|-
|BodyInEclipseDetector
|This class handles the umbra/penumbra eclipse events detection for a non-point target body
|[{{JavaDoc4.17}}<nowiki>/fr/cnes/sirius/patrius/events/detectors/BodyInEclipseDetector.html BodyInEclipseDetector]</nowiki>
|-
|BodyPointLocalTimeAngleDetector
|This class handles events representing the fact that a point on the surface of a spacecraft reaches a certain local time angle
|[{{JavaDoc4.17}}<nowiki>/fr/cnes/sirius/patrius/events/detectors/BodyPointLocalTimeAngleDetector.html BodyPointLocalTimeAngleDetector]</nowiki>
|-
|DateDetector
|This class handles the occurrence of predefined dates.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/DateDetector.html DateDetector]
|-
|EclipseDetector
|This class handles total or partial eclipse events.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/EclipseDetector.html EclipseDetector]
|-
|NodeDetector
|This class handles satellite equator crossing events.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/NodeDetector.html NodeDetector]
|-
|DistanceDetector
|This class handles events relating to the distance between the satellite and a given body.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/DistanceDetector.html DistanceDetector]
|-
|ExtremaDistanceDetector
|This class handles events representing the reaching of extrema for the distance to a given body.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/ExtremaDistanceDetector.html ExtremaDistanceDetector]
|-
| ExtremaLatitudeDetector
|This class handles events representing the reaching of extrema for the geodetic latitude.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/ExtremaLatitudeDetector.html ExtremaLatitudeDetector]
|-
|ExtremaLongitudeDetector
|This class handles events representing the reaching of extrema for the longitude.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/ExtremaLongitudeDetector.html ExtremaLongitudeDetector]
|-
|LatitudeDetector
|This class handles events representing the reaching of a given geodetic latitude, the earth shape being known.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/LatitudeDetector.html LatitudeDetector]
|-
|LongitudeDetector
|This class handles events representing the reaching of a given longitude
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/LongitudeDetector.html LongitudeDetector]
|-
|AnomalyDetector
|This class handles events representing the reaching of an anomaly angle.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/AnomalyDetector.html AnomalyDetector]
|-
|AOLDetector
| This class handles events representing the reaching of an argument of latitude value.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/AOLDetector.html AOLDetector]
|-
|ThreeBodiesAngleDetector
|This class handles events representing the reaching of a predetermined angle between three bodies.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/ThreeBodiesAngleDetector.html ThreeBodiesAngleDetector]
|-
|ExtremaThreeBodiesAngleDetector
|This class handles events representing the reaching of of extrema for the angle between three bodies.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/ExtremaThreeBodiesAngleDetector.html ExtremaThreeBodiesAngleDetector]
|-
|BetaAngleDetector
|This class handles the event : reaching a given beta angle value for a spacecraft.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/BetaAngleDetector.html BetaAngleDetector]
|-
|LocalTimeAngleDetector
|This class handles events representing the reaching of a predetermined spacecraft local time angle.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/LocalTimeAngleDetector.html LocalTimeAngleDetector]
|-
|SolarTimeAngleDetector
|This class handles events representing the reaching of a predetermined spacecraft solar time angle.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/SolarTimeAngleDetector.html SolarTimeAngleDetector]
|-
|NadirSolarIncidenceDetector
|This class handles events representing the reaching of a predetermined spacecraft nadir point solar incidence.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/NadirSolarIncidenceDetector.html NadirSolarIncidenceDetector]
|-
|EarthZoneDetector
|This class handles events representing the entering and leaving of earth zones.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/EarthZoneDetector.html EarthZoneDetector]
|-
|}
[[Category:User Manual 4.17 Mission]]

Fichier:BodyPointSolarIncidenceDetector.png

2025-11-27T09:23:11Z

Admin tsn :

BodyPointSolarIncidenceDetector

User Manual 4.17 Events: orbital

2025-11-27T09:19:57Z

Admin tsn :

== Introduction ==
=== Scope ===
Here are presented all the events detectors of the theme "orbital".

=== Javadoc ===
Those event detectors are available in the packages :

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detecors/package-summary.html Package fr.cnes.sirius.patrius.events.detectors]
|}

=== Links ===
None as of now.

=== Useful Documents ===
None as of now.

=== Package Overview ===
None as of now.

== Features Description ==
=== Detectors ===
This section describes the meaning of the g switching function for the "orbital" event detectors, and their particularities :

==== Alignment Detector ====

This detector computes the difference <math>\theta</math> between the alignment angle <math>\beta_{threshold}</math> and the angle between the satellite position, the central body and the second body position projection in the orbital plane. 
If <math>\theta_1 =-\pi - \theta</math> and <math>\theta_2 = \pi - \theta</math>, the g switching function will be: 
<math>\theta_1</math> if <math>\theta < \theta_1</math>, 
<math>\theta</math> if <math>\theta < \theta_2</math>, 
and <math>\theta_2</math> otherwise.

<math>\beta_{threshold}</math> is an oriented angle and is positive when is oriented as the orbital momentum.

[[File:alignmentDetector.png|750x400px]]

Axes <math>\vec a</math> (satellite normalized position) and <math>\vec b</math> (satellite normalized velocity) are transformed into axes <math>\vec x</math> and <math>\vec y</math> knowing the value of <math>\beta_{threshold}</math> angle; g is found projecting the target body position in the orbital plane and computing its <math>\vec x</math> and <math>\vec y</math> components.

* <math>g>0 :</math> target body projection is in the half-plane <math>y>0</math>
* <math>g<0 :</math> target body projection is in the half-plane <math>y<0</math>
* <math>g=0 :</math> target body projection belongs to the straight line <math>y=0</math>

==== Altitude Detector ====

The g switching function measures the difference between the current altitude <math>h_{sat}</math> and the threshold altitude <math>h_{thr}</math>.

* <math>g > 0 : h_{sat} > h_{thr}</math>
* <math>g<0 : h_{sat} < h_{thr}</math>

==== ApsideDetector ====

The g switching function is the dot product of the satellite position and velocity vectors: <math>g =\vec p \cdot \vec v</math>

* <math>g>0 :</math> the satellite is in the half-orbit from perigee to apogee;
* <math>g<0 :</math> the satellite is in the half-orbit from apogee to perigee.

[[File:apside.png|center|539x316px]]

==== DateDetector ====

The g switching function is the value of the difference between the current date and the target date. If no event dates have been added i.e. if no target dates have been initialized, <math>g=-1</math>.

==== RelativeDateDetector ====
This detector extends of DateDetector. The g switching function is the same as the [[#DateDetector|DateDetector]].

==== EclipseDetector ====

This detector is in charge of the umbra/penumbra eclipse events detection. 
Different features are available:
* the occulted and occulting bodies are both spherical;
* the occulted body is a direction;
* the occulting body has an ellipsoid shape.

In addition to that, the <code>EclipseDetector</code> can detect eclipse events based on a threshold lighting ratio <math>\epsilon_{0}</math>: 
<math>0<=\epsilon_{0}<=1</math>. 
When <math>\epsilon_{0}=0</math>, an eclipse event is triggered only if whole occulted body is hidden by the occulting body (total eclipse); when <math>\epsilon_{0}=1</math>, an event is immediately triggered when the occulted body is partially hidden (penumbra eclipse). 
As a general rule, the lighting ratio is equal to: 
<math>\epsilon = 1-\frac{A_{occulted}}{\pi r_{occulted}^2}</math> 
where <math>r_{occulted}</math> is the apparent radius of the occulted body. 
The g function is: <math>g=\epsilon_{0}-\epsilon</math>

The g switching function computation needs the satellite position vector (<math>\vec P_{sat}</math>), the occulted body (<math>\vec P_{ted}</math>) and occulting body (<math>\vec P_{ing}</math>) position vectors. 
<math>\vec {PS}=\vec {P_{ted}}-\vec {P_{sat}}</math>, <math>sin(\widehat{rs})=\dfrac{r_{ted}}{|\vec {PS}|}</math> 
<math>\vec {PO}=\vec {P_{ing}}-\vec {P_{sat}}</math>, <math>sin(\widehat{ro})=\dfrac{r_{ing}}{|\vec {PO}|}</math>. 
<math>\alpha</math> is the angle between <math>\vec {PS}</math> and <math>\vec {PO}</math>. 
Distinction is made between total eclipse and partial eclipse. 
The following diagrams show the evolution of the g function value for an eclipse scenario with two spherical bodies.

===== Total eclipse =====

The passage to umbra is detected. The g switching function is <math>g = \alpha- \widehat{ro} + \widehat{rs}</math>.

* <math>g>0 :</math> satellite is not in eclipse:
[[File:eclipse1.png|576x274px]]
* <math>g=0 :</math> beginning of umbra:
[[File:eclipse2.png|570x161px]]
* <math>g<0 :</math> umbra:
[[File:eclipse3.png|574x180px]]
* <math>g=0 :</math> end of umbra:
[[File:eclipse4.png|570x182px]]
* <math>g>0 :</math> satellite is not in eclipse:
[[File:eclipse5.png|588x264px]]

===== Partial eclipse =====

The passage to penumbra is detected. The g switching function is <math>g = \alpha- \widehat {ro} - \widehat {rs}</math>.

* <math>g>0 :</math> satellite is not in eclipse:
[[File:eclipse6.png|566x273px]]
* <math>g=0 :</math> beginning of penumbra:
[[File:eclipse7.png|552x198px]]
* <math>g<0 :</math> penumbra:
[[File:eclipse8.png|581x178px]]
* <math>g=0 :</math> end of penumbra:
[[File:eclipse9.png|578x217px]]

Another feature of the <code>EclipseDetector</code> is the detection of partial and total eclipse by a spheroid.

[[File:ellipsoideclipse.png|center]]

The point on the horizon (H) is calculated as the point of the ellipsoid that is in the same plane as A, C and S (respectively center of occulted body, center of occulting body and satellite). The distance of H to the center C of the ellipsoid is then projected onto a plane orthogonal to the Satellite / Occulting (SA) body direction, and the resulting length is considered as the radius of an "apparent" sphere representing the occulting body. The partial and total eclipse are then computed as per above.

===== Particular case =====

A specific case is having a spacecraft lower than the occulting body radius (i.e. spacecraft altitude < occulting body radius). 
Two cases are possible:
* The satellite is behind the occulted body (angle occulted body- occulting body - satellite > Pi/2): satellite is considered to be in total eclipse.
* The satellite is in front of the occulted body (angle occulted body- occulting body - satellite <= Pi/2): apparent radius of occulting body cannot be computed. Hence it is considered to be equal to Pi/2 (slight approximation since it means satellite is considered to be lying exactly on the surface of the occulting body). Then usual computation of g function applies.

==== BodyInEclipseDetector====

This detector is in charge of the umbra/penumbra eclipse events detection for a non-point target body. 3 bodies are considered to compute the BodyInEclipse events:

*Target body: body on which the eclipse events are to be detected.

*Occulted body: this is the body that is no longer visible from the target body due to the presence of the occulting body in the line of sight (the occulted body is generally the sun).

*Occulting body: body that causes the eclipse.
[[Fichier:BodyInEclipseDetector1.png|centré|683x683px]]
The following assumptions are made:
* The three bodies are considered spherical during calculations (the apparent radius of the bodies are used).
* For the cases where the target body is fully in eclipse, the target body must be much smaller than the possible irregularities of the occulting body to avoid false positives. (Further explanation of this point in the edge cases section).
* No atmospheric effect is taken into account.
*The propagation delay can be activated or not.

The core of the algorithm consists of selecting a point on the surface of the target that is representative of the surface of the target as a whole, and then calculating the illumination rate at that point.

The calculation of g is therefore done in three steps:
*Selection of the reference point: This depends on the type of eclipse targeted (partial or total; whether the body is completely eclipsed or not), the chosen model (complete or simplified), and the relative position of the bodies involved.
* Calculation of the illumination rate at the selected target point.
*Comparison of the obtained illumination rate with the target illumination rate (0 if we are looking for total eclipses, 1 if we are looking for partial eclipses).
2 modes are available for the computation of eclipse events:

1. Exact model:

In this model, the occulted body is considered as non-punctual. 4 points are of interest to detect the eclipse events:
*HPPU = point of interest for entry partially in penumbra
*HPU = point of interest for entry partially in umbra
* HTPU = point of interest for entry totally in penumbra
*HTU = point of interest for entry totally in umbra
[[Fichier:BodyInEclipseDetector2.png|centré|776x776px]]
2. Approximative model

In this model, the occulted body is considered as punctual. In this case, only 2 interest points exists to detect eclipse events:
*HP = point of interest for entry partially in eclipse
*HT = point of interest for entry totally in eclipse
[[Fichier:BodyInEclipseDetector3.png|centré|771x771px]]
For any of the models, the lighting ratio of the corresponding interest points is computed to detect the events.

The lighting ratio is then compared against the target lighting ratio (0 if we want to detect total eclipses and 1 for partial eclipses), and the value of the g function (switching function) is returned for a given date.

'''Edge Cases:'''

'''Occulting body << Target Body:'''

If the occulting body is smaller than the target body, it might happen that none of the 4 points of interest is in eclipse, however the target body is partially in eclipse as shown in the figure below:
[[Fichier:BodyInEclipseDetector4.png|centré|806x806px]]
This case is possible only if the line SA intersects the target body. In this case, none of the interest points of the exact model or of the approximative model are used to compute the lighting ratio. In this case it is the intersection point HC that is used to compute the lighting ratio (to know if it is inside umbra or only inside penumbra).

'''Shape of occulting body non spherical:'''

In the hypotheses section it was said that the 3 bodies are considered spherical. However, it is really only the occulted and the target bodies that have to be spherical. The occulting body might have any other shape. It is during the computation that we model the occulting body as spherical by using the getApparentRadius method.

In certain edge cases, a BodyInEclipse event might be raised by the propagator, even though this is not actually the case. This type of situation can occur when the occulting body is elongated in the direction of the plane of the eclipse.
[[Fichier:BodyInEclipseDetector5.png|centré]]
The calculation method considers a planar projection of the problem. When an object is detected as "completely in the shadow" of another, it is ensured that the furthest point of the eclipse cone in the plane containing the centers of the three objects is in eclipse. This guarantees that all points of the target object belonging to this plane are in eclipse. However, there is no guarantee for points outside of the plane. This is not an issue when the obscuring object is spherical, but it can become one when it is elongated. In the example below, the target is considered "entirely" eclipsed by the detector, even though some points are illuminated.

This type of case is unlikely to occur in the Earth-Moon scenario, where the obscuring body is very close to a sphere, but it is not impossible in the case of asteroids, which have non-regular shapes. Other problems of this kind can arise when the body is not convex, but such cases become extremely rare.

This is why for the cases where the target body is fully in eclipse, the target body must be much smaller than the possible irregularities of the occulting body to avoid false positives.

====PlaneCrossingDetector====
The detector allows to detect if a spacecraft crosses a plane defined in a specific reference frame. The following entries are needed to define a <code>PlaneCrossingDetector</code>:
*plane reference frame ;
*point which is contained in the plane ;
* normal vector to plane.

The detection function <math>g()</math> monitors the dot product between the normal vector to plane and the distance position vector of the spacecraft with respect to the origin of the point of the plan:
*<math>g>0 :</math>the satellite is over the plane;
*<math>g<0 :</math>the satellite is under the plane.

==== NodeDetector ====
The <code>NodeDetector</code> detects the orbital nodes; the user can choose what the detect (ascending nodes, descending nodes or both) through the <code>slopeSelection </code> parameter. It is a particular application case of the <code>PlaneCrossingDetector</code>. 
The g switching function returns the Z component of the satellite position in the geocentric frame:
* <math>g>0 :</math>the satellite is over the equatorial plane (in its orbit from ascending node to descending node);
*<math>g<0 :</math>the satellite is under the equatorial plane (in its orbit from descending node to ascending node).

====DistanceDetector====

The <code>DistanceDetector </code> detects the time when the distance between the spacecraft and a point of space reaches a given value.

The point of space is given as a <code>PVcoordinatesProvider</code> : it can be either a celestial body (as a <code>CelestialBody</code>), a point at the surface of a body (as a <code>TopocentricFrame</code>), or any another class that implements that interface.

Here is the example for a point on the surface of a body :

<syntaxhighlight lang="java">
// earth shape
final BodyShape earth = new OneAxisEllipsoid(earthRadius, ea, ITRFFrame);

// considered point
final EllipsoidPoint point = new EllipsoidPoint(ellipsoid, LLHCoordinatesSystem.ELLIPSODETIC, latitude, longitude, altitude, "point ");

// associated topocentric frame : this object is a PVCoordinatesProvider
final TopocentricFrame topoFramePoint = new TopocentricFrame(point, "Gstation");

// detector
final DistanceDetector detector = new DistanceDetector(topoFramePoint, distance);
</syntaxhighlight>

Its g switching function computes the difference between the spacecraft position and the point position (in the same frame), and then subtracts the given distance from its norm.

*<math>g>0 :</math>the distance spacecraft/point is bigger than the distance threshold value;
*<math>g<0 :</math>the distance spacecraft/point is smaller than the distance threshold value;

====ExtremaDistanceDetector====

The <code>ExtremaDistanceDetector</code> detects if the spacecraft is at a local extremum for the distance relative to a point of space, defined the same way as in the previous DistanceDetector. The choice of the extremum (maximum, minimum, or both) is done with the constructor, through the <code>distanceType</code> parameter.

The g switching function returns the square norm of the velocity for the vector representing this distance, thus the sign change is indeed a local extremum.

====ExtremaLatitudeDetector====

The <code>ExtremaLatitudeDetector</code> detects if the spacecraft is at a local extremum for the geodetic latitude. The choice of the extremum (maximum, minimum, or both) is done with the constructor, through the <code>latitudeType</code> parameter.

The g switching function returns the z-component of the spacecraft velocity in the orbit definition frame.

====LatitudeDetector====
The <code>LatitudeDetector</code> detects the time when the spacecraft reaches a given geodetic latitude, the <code>BodyShape</code> of the earth being known to compute it.

The g switching function returns the difference between the current latitude and the one to detect.

====ExtremaLongitudeDetector====

The <code>ExtremaLongitudeDetector</code> detects if the spacecraft is at a local extremum for the longitude. The choice of the extremum (maximum, minimum, or both) is done with the constructor, through the <code>extremumType</code> parameter.

The g switching function is the dot vector of the position with the result of the cross product of the velocity relative to the body and unitary vector Z : 
<math>g =\vec P \cdot (\vec Vrel \wedge \vec Vz)</math>

The main part of this function is the cross product which switches when the relative velocity is colinear to Z.

====LongitudeDetector====
The <code>LongitudeDetector</code> detects the time when the spacecraft reaches a given longitude.

Working with longitude always gives a problem of continuity when longitude pass from PI rad to- PI rad. The best solution find to avoid this is to save some information from the last computation of the g function.

In this way the g function is the following difference expressed between-PI rad and PI rad : currentLongitude - longitudeToDetect

At each g function call, this difference is saved, and each time the difference between the current difference and the last difference is greater than PI rad, it means there is a discontinuity, the g fonction is opposed. This avoids discontinuity. Then all zero are detected.

This solution, also avoids problem about detecting a longitude at PI rad further (that we meet with a sin(a- b) g function).

====AOLDetector====

The <code>AOLDetector</code> detects when the spacecraft reaches a predetermined argument of latitude (true, mean or eccentric supportes) with respect to a given equator ; the argument of latitude is the angle between the spacecraft position and the ascending node.

The g switching function returns the sinus of the difference between the spacecraft current angular position <math>\beta</math> and the threshold position value <math>\beta_{input}</math>: 
<math>g=sin(\beta- \beta_{input})</math> 
An AOL event is triggered only if the g-function slope is positive at its zero.

====AnomalyDetector====

The <code>AnomalyDetector</code> detects when the spacecraft reaches a predetermined anomaly; the anomaly is the angle between the spacecraft position and the perigee. 
Three types of anomaly can be detected: true, mean and eccentric anomaly.

The g switching function returns the sinus of the difference between the spacecraft current anomaly and the threshold anomaly value: 
<math>g=sin(\alpha- \alpha_{input})</math> 
(This g function is identical to the AOLDetector g function). 
Like the <code>AOLDetector</code>, an anomaly event is triggered only if the g-function slope is positive at its zero.

Using precaution : This detector is unusable on a circular orbit where the perigee always moves very fast and in any way.

====ThreeBodiesAngleDetector====

The <code>ThreeBodiesAngleDetector</code> detects when the angle between three bodies (they can be celestial bodies, spacecrafts, ground stations, ...) is equal to a predetermined value. 
If <math>\vec{P_{1}}</math>, <math>\vec{P_{2}}</math> and <math>\vec{P_{3}}</math> are the positions of the three bodies, and <math>\vec{P_{21}}</math> is the difference <math>\vec{P_{2}}-\vec{P_{1}}</math> and <math>\vec{P_{23}}</math> the difference <math>\vec{P_{2}}-\vec{P_{3}}</math>, the computed angle will be: <math>\widehat{\vec{P_{21}} \vec{P_{23}}}</math>

[[File:threeBodies.PNG|center]]

The g switching function returns the difference between the current angle between the three bodies and the threshold angle. The threshold angle is not oriented and its value is between 0 and PI.

====ExtremaThreeBodiesAngleDetector====
The <code>ExtremaThreeBodiesAngleDetector</code> detects when the angle between three bodies (defined the same way as in the <code>ThreeBodiesAngleDetector</code>) reaches its minimal or maximal value. 
The choice of the detected extremum (maximum, minimum, or both) is done with the constructor, through the <code>extremumType</code> parameter.

The g switching function returns the derivative of the angle value (in fact, part of the derivative : a factor with a
constant sign has been ignored). 
This derivative is obtained by expressing all the positions and velocities of the two extreme points (<math>P_{1}</math> and <math>P_{3}</math>) in a frame linked to the one at the angle origin (<math>P_{2}</math>). 
If the two vectors from the new origin are <math>\vec{P_{21}}</math> and <math>\vec{P_{23}}</math> the angle expression is : <math>\arccos(\vec{P_{21}}.\vec{P_{23}} / (|\vec{P_{21}}|.|\vec{P_{23}}|))</math> 
Once derivated as <math>(gof)' = (g'of).f'</math> and the <math>arccos</math> derivative being always negative, the switching function is minus the derivative of the inner expression <math>\vec{P_{21}}.\vec{P_{23}} / (|\vec{P_{21}}|.|\vec{P_{23}}|)</math>.

====BetaAngleDetector====

The <code>BetaAngleDetector</code> detects when the beta angle reaches a predetermined value; the beta angle is the angle between the orbit plane and the vector to the Sun.
[[File:BetaAngle.png|center]]

The beta angle belongs to [- π/2 , π/2 ]; its sign is positive when the Sun is in the half-plane containing the spacecraft's momentum.

==== LocalTimeAngleDetector====

The <code>LocalTimeAngleDetector</code> detects when the spacecraft local time is equal to a predetermined value; the spacecraft local time is the angle between the projections of the Earth-Sun vector and the Earth-spacecraft vector in the equatorial plane plus PI. In PATRIUS, local time is expressed as an angle in the range [-PI; PI[. Local time angle is PI (or 12.00h) when the geometric angle Sun-Earth-Spacecraft is 0 and 0 (or 0.00h) when this angle is PI. 
The local time is increasing for prograde orbits and decreasing for retrograde orbits. The events are detected in both cases.

The g function is the following difference expressed between-PI rad and PI rad : 
<math>currentLocalTime- localTimeToDetect</math>

At each g function call, this difference is saved, and each time the difference between the current difference and the last difference is greater than PI rad, it means there is a discontinuity, the g fonction is opposed. This avoids discontinuity. Then all zero are detected.

This solution, also avoids problem about detecting a local time at PI rad further (that we meet with a sin(a- b) g function).

====BodyPointLocalTimeAngleDetector====

The <code>BodyPointLocalTimeAngleDetector</code> follows the same logic as its parent class <code>LocalTimeAngleDetector</code> but, instead of computing the events for a certain position of the spacecraft, the events are computed with respect to a point of the surface of the body, by using the zenithal direction (normal to the surface).

To compute the local time of a certain point in a body, first the Frame is verified (it cannot be null). Then, the normal direction of the body point is computed. Afterwards, the sun position is obtained. The local time corresponds to the angle between the projections of the Earth-Sun and the normal direction over the equatorial plane plus PI.

====SolarTimeAngleDetector====

The <code>SolarTimeAngleDetector</code> detects when the spacecraft solar time is equal to a predetermined value; the spacecraft solar time is the angle between the the Earth-Sun projection in the orbital plane and the Earth-spacecraft vector plus PI. In PATRIUS, solar time is expressed as an angle in the range [-PI; PI[. Solar time angle is PI (or 12.00h) when the geometric angle Sun-Earth-Spacecraft is 0 and 0 (or 0.00h) when this angle is PI. 
The solar time is always increasing with time. It is mesured around the orbit momentum.

The g switching function returns the sinus of the difference between the spacecraft current solar time <math>\theta</math> and the threshold solar time value <math>\theta_{t}</math>: 
<math>g=sin(\theta- \theta_{t})</math> 
Like the <code>AOLDetector</code>, a solar time event is triggered only if the g-function slope is positive at its zero.

====NadirSolarIncidenceDetector ====

The <code>NadirSolarIncidenceDetector</code> detects when the solar incidence, seen from the nadir point of the spacecraft, reaches a predetermined value. 
The solar incidence is the angle between the nadir- satellite vector and the nadir - sun vector.

[[File:nadirsolarincidence.png|center]]

====EarthZoneDetector====

The <code>EarthZoneDetector</code> detects when the spacecraft enters and leaves an earth zone. Several separated zones can be defined for one detector instance. In that case, the EarthZoneDetector detects the entery of the satellite NADIR point in any of the zones.

The zones can be described two ways :
*As an array of {latitude, longitudes} that define the geodetic points with a zero altitude on a BodyShape. With this definition, the test made will be the entering of the spacecraft's NADIR point in the zone.
*As an array of vectors expressed in a given frame. With this definition, the entering of the spacecraft itself in the conic field from the center of the given frame to those points will be detected. Note that the given frame must be a terrestrial frame for the detection of earth zones entering, but the use of other frames is possible (other bodies, inertial frames…).

In both cases, the points must respect the following conditions :
*At least 3 points are needed to define a zone
*two consecutive points must not be too close (1.e-10 on the difference of thier normalized values)
*the arc between two consecutive points must not cross the one between two consecutive others of the same zone.

The points must also be given in the right order : from the point i to the point i + 1, if the associated vector from the center of the earth are <math>v_{i}</math> and <math>v_{i + 1}</math>, the inside of the zone is on the left, e.g. the side of the positive cross vector <math>v_{i} . v_{i + 1}</math>.

Constructors with default maxCheck and threshold values are available, but beware of their values, and use the other constructors if needed : if the zone is complex and the MaxCheck too large, the event detection could fail, because it would not manage to converge. To compute the event with enough precision to converge, set a small enough MaxCheck. To compute an approximative event even if the zone is precise and complex, set a large enough Threshold.

====SurfaceDistanceDetector====

The <code>SurfaceDistanceDetector</code> detects when the distance from the spacecraft to the surface of a given body reaches a predetermined value. The detector is constructed by providing the BodyShape whose distance is watched, the distance triggering the event and the distance type (CLOSEST or RADIAL). Other constructors are available to parametrize common detector attributes.

===Particular detections===
All those detectors can be used for the following particular cases :

*sub-solar point reaching : use the SolarTimeAngleDetector with a "12h" time to detect.
*generic masking by a spherical body : use the GenericEclipseDetector, or the ThreeBodiesAngleDetector.
*terminator reaching (the nadir point reaches the night / day limit) : use the NadirSolarIncidenceDetector with a zero incidence.
*Sun interference in ground antennas : use the ThreeBodiesAngleDetector.
*RF interference between the main spacecraft and another one : use the ThreeBodiesAngleDetector

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

== Contents==
===Interfaces===
All the detectors implement the interface :

{| class="wikitable"
|-
! scope="col" |Interface
! scope="col" |Summary
! scope="col" |Javadoc
|-
|EventDetector
|This interface represents an event finder.
|[<nowiki/>{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/EventDetector.html EventDetector ]
|}

===Classes===
{| class="wikitable"
|-
! scope="col" |Class
! scope="col" |Summary
! scope="col" |Javadoc
|-
|AlignmentDetector
|This class handles (satellite/central body/projection in the orbital plane of secondary body) alignment events.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/AlignmentDetector.html AlignmentDetector]
|-
|AltitudeDetector
|This class handles satellite altitude crossing events.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/AltitudeDetector.html AltitudeDetector]
|-
|ApsideDetector
|This class handles satellite apogee and perigee crossing events.
| [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/ApsideDetector.html ApsideDetector]
|-
|BodyInEclipseDetector
|This class handles the umbra/penumbra eclipse events detection for a non-point target body
|[{{JavaDoc4.17}}<nowiki>/fr/cnes/sirius/patrius/events/detectors/BodyInEclipseDetector.html BodyInEclipseDetector]</nowiki>
|-
|BodyPointLocalTimeAngleDetector
|This class handles events representing the fact that a point on the surface of a spacecraft reaches a certain local time angle
|[{{JavaDoc4.17}}<nowiki>/fr/cnes/sirius/patrius/events/detectors/BodyPointLocalTimeAngleDetector.html BodyPointLocalTimeAngleDetector]</nowiki>
|-
|DateDetector
|This class handles the occurrence of predefined dates.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/DateDetector.html DateDetector]
|-
|EclipseDetector
|This class handles total or partial eclipse events.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/EclipseDetector.html EclipseDetector]
|-
|NodeDetector
|This class handles satellite equator crossing events.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/NodeDetector.html NodeDetector]
|-
|DistanceDetector
|This class handles events relating to the distance between the satellite and a given body.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/DistanceDetector.html DistanceDetector]
|-
|ExtremaDistanceDetector
|This class handles events representing the reaching of extrema for the distance to a given body.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/ExtremaDistanceDetector.html ExtremaDistanceDetector]
|-
| ExtremaLatitudeDetector
|This class handles events representing the reaching of extrema for the geodetic latitude.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/ExtremaLatitudeDetector.html ExtremaLatitudeDetector]
|-
|ExtremaLongitudeDetector
|This class handles events representing the reaching of extrema for the longitude.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/ExtremaLongitudeDetector.html ExtremaLongitudeDetector]
|-
|LatitudeDetector
|This class handles events representing the reaching of a given geodetic latitude, the earth shape being known.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/LatitudeDetector.html LatitudeDetector]
|-
|LongitudeDetector
|This class handles events representing the reaching of a given longitude
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/LongitudeDetector.html LongitudeDetector]
|-
|AnomalyDetector
|This class handles events representing the reaching of an anomaly angle.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/AnomalyDetector.html AnomalyDetector]
|-
|AOLDetector
| This class handles events representing the reaching of an argument of latitude value.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/AOLDetector.html AOLDetector]
|-
|ThreeBodiesAngleDetector
|This class handles events representing the reaching of a predetermined angle between three bodies.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/ThreeBodiesAngleDetector.html ThreeBodiesAngleDetector]
|-
|ExtremaThreeBodiesAngleDetector
|This class handles events representing the reaching of of extrema for the angle between three bodies.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/ExtremaThreeBodiesAngleDetector.html ExtremaThreeBodiesAngleDetector]
|-
|BetaAngleDetector
|This class handles the event : reaching a given beta angle value for a spacecraft.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/BetaAngleDetector.html BetaAngleDetector]
|-
|LocalTimeAngleDetector
|This class handles events representing the reaching of a predetermined spacecraft local time angle.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/LocalTimeAngleDetector.html LocalTimeAngleDetector]
|-
|SolarTimeAngleDetector
|This class handles events representing the reaching of a predetermined spacecraft solar time angle.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/SolarTimeAngleDetector.html SolarTimeAngleDetector]
|-
|NadirSolarIncidenceDetector
|This class handles events representing the reaching of a predetermined spacecraft nadir point solar incidence.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/detectors/NadirSolarIncidenceDetector.html NadirSolarIncidenceDetector]
|-
|EarthZoneDetector
|This class handles events representing the entering and leaving of earth zones.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/EarthZoneDetector.html EarthZoneDetector]
|-
|}
[[Category:User Manual 4.17 Mission]]

User Manual 4.17 Root-Finding Algorithms

2025-11-27T09:16:59Z

Admin tsn :

__NOTOC__
== Introduction ==
=== Scope ===
This section is about the root-finding algorithms for univariate real functions provided by the library.
First we explain how to use the root-finding algorithms.
Then a focus is made on the following root finding methods: Brent, Newton, Bisection and Müller.

=== Javadoc ===
All solvers are in the following package :
[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/solver/package-summary.html fr.cnes.sirius.patrius.math.analysis.solver]

=== Links ===
None as of now.

=== Useful Documents ===
None as of now.

=== Package Overview ===
The package <code>fr.cnes.sirius.patrius.math.analysis.solvers</code> contains all the solvers described here.

== Features Description ==

=== About root finding ===
This library provides root-finding algorithms for real univariate functions.
The function for which a root is searched has to be provided as a [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/UnivariateFunction.html UnivariateFunction].
The root-finding algorithm is implemented through the [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/solver/UnivariateSolver.html UnivariateSolver] interface.

A very generic example would be :

<syntaxhighlight lang="java">
UnivariateFunction f = <some function>;
UnivariateSolver solver = <some solver>;
int numberOfEvals = 100;
double startInterval = 5.;
double endInterval = 10.;

double root = solver.solve(numberOfEvals , f, startInterval , endInterval);
</syntaxhighlight>

This means the solver with look for a root value of f in the interval [5. , 10.], and will have to do so in no more than 100 evaluation steps.

==== Test functions ====

We will demonstrate the use of root-finding algorithms with two test input functions : a periodic function and a linear function. These functions are defined as follows : 
'''''sinus function''''' : SinFunction

<syntaxhighlight lang="java">
public class SinFunction implements DifferentiableUnivariateFunction {

public double value(double x) {
return FastMath.sin(x);
}

public UnivariateFunction derivative() {
return new UnivariateFunction() {
public double value(double x) {
return FastMath.cos(x);
}
};
}
</syntaxhighlight>

'''''linear function''''' : XMinus5Function

<syntaxhighlight lang="java">
public class XMinus5Function implements DifferentiableUnivariateFunction {

public double value(double x) {
return x- 5;
}

public UnivariateFunction derivative() {
return new UnivariateFunction() {
public double value(double x) {
return 1.0;
}
};
}
</syntaxhighlight>

==== Available solvers ====

The library provides around ten solvers, but the following have been more thoroughly tested :
* BrentSolver
* NewtonSolver
* BisectionSolver
* MullerSolver
* LaguerreSolver
* PolynomialRootsFinder

=== Brent method ===
The'''''Brent's method''''' is a root-finding algorithm combining the bisection method, the secant method and inverse quadratic interpolation. It has the reliability of bisection but it can be as quick as some of the less reliable methods. The idea is to use the secant method or inverse quadratic interpolation if possible, because they converge faster, but to fall back to the more robust bisection method if necessary.

<syntaxhighlight lang="java">
UnivariateFunction f = new SinFunction ();
double r;
UnivariateSolver solver = new BrentSolver();

r = solver.solve(100, f, 3, 4);
</syntaxhighlight>

Result : r = PI

<syntaxhighlight lang="java">
UnivariateFunction f = new XMinus5Function ();
double r;
UnivariateSolver solver = new BrentSolver();

r = solver.solve(100, f, 1, 2);
</syntaxhighlight>

Result : NoBracketingException exception

'''''behavior deteriorated in case of several roots in the interval''''' :

<syntaxhighlight lang="java">
UnivariateFunction f = new SinFunction ();
double r;
UnivariateSolver solver = new BrentSolver();

r = solver.solve(100, f, 1, 20);
</syntaxhighlight>

Result : r = PI

<syntaxhighlight lang="java">
UnivariateFunction f = new SinFunction ();
double r;
UnivariateSolver solver = new BrentSolver();

r = solver.solve(100, f, 2, 20);
</syntaxhighlight>

Result : r = 3 PI

<syntaxhighlight lang="java">
UnivariateFunction f = new SinFunction ();
double r;
UnivariateSolver solver = new BrentSolver();

r = solver.solve(100, f, 7, 20);
</syntaxhighlight>

Result : NoBracketingException exception

=== Newton method ===
The '''''Newton's method''''' (also known as the Newton–Raphson method) is a method for finding successively better approximations to the roots of a real-valued function. The idea of the method is as follows: one starts with an initial guess which is reasonably close to the true root, then the function is approximated by its tangent line, and one computes the x-intercept of this tangent line. This x-intercept will typically be a better approximation to the function's root than the original guess, and the method can be iterated.

IMPORTANT : the Newton solver only works for differentiable functions, this is reflected in the interface and class inheritances.

<syntaxhighlight lang="java">
DifferentiableUnivariateFunction f = new XMinus5Function ();
double r;
DifferentiableUnivariateSolver solver = new NewtonSolver();

r = solver.solve(100, f, 1, 6);
</syntaxhighlight>

Result : r = 5

'''''aberrant behavior''''' :

<syntaxhighlight lang="java">
DifferentiableUnivariateFunction f = new SinFunction();
double r;
DifferentiableUnivariateSolver solver = new NewtonSolver();

r = solver.solve(100, f, 1, 2);
</syntaxhighlight>

Result : r =- 4 PI

<syntaxhighlight lang="java">
DifferentiableUnivariateFunction f = new SinFunction();
double r;
DifferentiableUnivariateSolver solver = new NewtonSolver();

r = solver.solve(100, f, 1, 3);
</syntaxhighlight>

Result : r = PI

<syntaxhighlight lang="java">
DifferentiableUnivariateFunction f = new XMinus5Function ();
double r;
DifferentiableUnivariateSolver solver = new NewtonSolver();

r = solver.solve(100, f, 5.1, 20);
</syntaxhighlight>

Result : r = 5

=== Bisection method ===
The '''''bisection method''''' is a root-finding method which repeatedly bisects an interval and then selects a subinterval in which a root must lie for further processing. It is a very simple and robust method, but it is also relatively slow.

<syntaxhighlight lang="java">
UnivariateFunction f = new XMinus5Function ();
double r;
UnivariateSolver solver = new BisectionSolver();

r = solver.solve(100, f, 3, 4);
</syntaxhighlight>

Result : r = PI

'''''behavior deteriorated''''' :

<syntaxhighlight lang="java">
UnivariateFunction f = new XMinus5Function ();
double r;
UnivariateSolver solver = new BisectionSolver();

r = solver.solve(100, f, 5.1, 20);
</syntaxhighlight>

Result : r = 20 (the upper bound of the interval)

=== Müller method ===
The'''''Müller's method''''' is based on the secant method, which constructs at every iteration a line through two points on the graph of f. Instead, Müller's method uses three points, constructs the parabola through these three points, and takes the intersection of the x-axis with the parabola to be the next approximation.

<syntaxhighlight lang="java">
UnivariateFunction f = new XMinus5Function ();
double r;
UnivariateSolver solver = new MullerSolver();

r = solver.solve(100, f, 1, 6);
</syntaxhighlight>

Result : r = 5

=== Laguerre method ===
The '''''Laguerre method''''' is based on root finding of real coefficient polynomials. For reference, see “A First Course in Numerical Analysis, ISBN 048641454X, chapter 8.”
In short, laguerre's method is global solver in the sense that it can start with any initial approximation and be able to solve all roots from that point. The algorithm requires a bracketing condition.
When creating an instance of this solver, the relative accuracy, absolute accuracy and function value accuracy needs to be provided.
With this instance, it is then possible to call the different “solveComplex” or “solveAllComplex” methods. The difference being that “solveComplex” methods find one complex root for the polynomial with the given coefficients, starting from the given initial value, while solveAllComplex methods return an array with all the complex roots of the polynomial.
The polynomial is to be provided to the methods as a list of coefficients, in descending degree order. So, if for example we want to find the roots for 3x^2 – 2x + 4 = 0, the coefficients array should be [3, -2, 4].
It is also possible to configure the maximum number of iterations and the initial guess to start looking for solutions. Moreover, an array of initial guesses with their corresponding array of maximum iterations per guess can be given as well. If this is the case, the first initial point is checked. If no solution is found, the following initial points are checked. If after all the initial solution points the problem does not converge still, an error is raised.
Possible errors:
* NullArgumentException if the coefficients of the polynomial are null
* NoDataException if the coefficients array is empty
* TooManyEvaluationsException if after the max number of iterations, the problem does not converge.
An example of code can be found below. In this example we try to find the complex solutions of a certain polynomial. Its coefficients are expressed in the “coefs” array. First, we check that using 0.0 as initial guess, the problem does not converge after 100 iterations. Then, we try to solve the problem again giving “0.0” and “-1.0” as initial guesses. The code should return all the complex roots of the polynomial:

<syntaxhighlight lang="java">
// Coefficients of the polynomial in descending degree order
final double[] coefs = { -1277.3007688108385, -2784.4747201350438, -3484.5151185287687, -3025.129112243774, -1809.09448519026, -659.3527056579327, -192.0264504557372, -30.431131343092268, -4.143607944239528 };
final LaguerreSolver laguerreSolver = new LaguerreSolver();

// Check that with one initial point, no solution is obtained.
try {
final Complex[] rootsFail = laguerreSolver.solveAllComplex(coefs, 0.0, 100);
// This part of the code should not be reached
Assert.fail();
} catch (TooManyEvaluationsException e) {
// Check the message is the attended one.
Assert.assertEquals(e.getMessage(), "illegal state: maximal count (100) exceeded: evaluations");
}

// Reconfigure the solver with multiple initial guesses:
final Complex[] roots =
laguerreSolver.solveAllComplex(coefs, new double[] { 0.0, -1.0 }, new int[] { 100, 100 });

// Ref value of roots
final Complex[] rootsRef = new Complex[] { new Complex(-1.0866082737090914, -0.5144910983744713),
new Complex(-1.0866082737090914, 0.5144910983744713),
new Complex(-0.19830816503367565, -1.1728862134932596),
new Complex(-0.19830816503367568, 1.1728862134932596), new Complex(-1.3187864867933607, -3.034067652882213),
new Complex(-1.3187864867933603, 3.034067652882214), new Complex(-1.0683543434675484, 3.553800385639665),
new Complex(-1.068354343467548, -3.553800385639666) };

// Verify value of roots
for (int i = 0; i < roots.length; i++) {
Assert.assertEquals(rootsRef[i].getReal(), roots[i].getReal(), Precision.DOUBLE_COMPARISON_EPSILON);
Assert.assertEquals(rootsRef[i].getImaginary(), roots[i].getImaginary(), Precision.DOUBLE_COMPARISON_EPSILON);
}
</syntaxhighlight>

=== PolynomialRootsFinder method ===
The '''''PolynomialRootsFinder method''''' computes the roots of the polynomial p represented by an array of coefficients, starting with the coefficient of greater degree. A coefficient of 0 indicates that an intermediate power is not present in the equation. It can compute either just the real part of the roots, or the full complex solution.

In this solver, the roots of the polynomial are calculated by computing the eigenvalues of the companion matrix A:
<syntaxhighlight lang="java">
A = diag(ones(n-1, 1), -1);
A(1,:) = -p(2:n+1)./p(1);
r = eig(A);
</syntaxhighlight>

The results produced are the exact eigenvalues of a matrix within roundoff error of the companion matrix, A. However, this does not mean that they are the exact roots of a polynomial whose coefficients are within roundoff error of those in p.
The public method findRootsRealPolynomial() computes the real part of the roots of the polynomial, while findRootsComplexPolynomial() computes the full complex solution. To use either of these methods, it is only necessary to give as input the list of coefficients representing the polynomial (in decreasing degree order). So, if for example we want to find the roots for 3x^2 – 2x + 4 = 0, the coefficients array should be [3, -2, 4].
Possible errors:
* NullArgumentException if the coefficients of the polynomial are null
* NoDataException if the coefficients array is empty or the degree of the polynomial is lower than 1.
An example of code can be found below. In this example we try to find the complex solutions of a certain polynomial. Its coefficients are expressed in the “coefs” array.

<syntaxhighlight lang="java">
// Define coefficients
final double[] coefficients = { 3, -2, 4 };

// Compute roots
double[] roots = PolynomialRootsFinder.findRootsRealPolynomial(coefficients);
</syntaxhighlight>

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

== Contents ==
=== Interfaces ===
The library defines the following interfaces related to solvers:

{| class="wikitable"
|-
! scope="col"| Interface
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''UnivariateSolver'''
|Interface for a univariate solver
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/solver/UnivariateSolver.html ...]
|-
|'''UnivariateDifferentiableSolver'''
|Interface for a differentiable univariate real solver
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/solver/UnivariateDifferentiableSolver.html ...]
|}

=== Classes ===
This section is about the following classes related to solvers :

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''BrentSolver'''
|Brent solver implementation.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/solver/BrentSolver.html ...]
|-
|'''NewtonRaphsonSolver'''
|Newton-Raphson solver implementation.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/solver/NewtonRaphsonSolver.html ...]
|-
|'''BisectionSolver'''
|Bisection solver implementation.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/solver/BisectionSolver.html ...]
|-
|'''MullerSolver'''
|Müller solver implementation.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/solver/MullerSolver.html ...]
|-
|'''LaguerreSolver'''
|Laguerre solver implementation.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/solver/LaguerreSolver.html ...]
|-
|'''PolynomialRootsFinder'''
|PolynomialRootsFinder solver implementation.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/solver/PolynomialRootsFinder.html ...]
|}

== [[File:lightBulb.png]] Tips & Tricks ==
Summing up : the solvers appear to behave in unexpected ways when the initial conditions are not "ideal". Therefore It is advised, when using the solvers, to :

* avoid non-ideal initial conditions,
* read the solvers' javadoc carefully,
* always check if the solvers' results are appropriate.

[[Category:User_Manual_4.17_Mathematics]]

User Manual 4.17 Events: sensors

2025-11-27T08:32:16Z

Admin tsn :

<gallery>
Exemple.jpg|Description 1
Exemple.jpg|Description 2
</gallery>
== Introduction ==
=== Scope ===
Here are presented all the events detectors of the theme "sensors".

=== Javadoc ===
Those event detectors are available in the packages :

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
|Orekit
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/propagation/events/package-summary.html Package fr.cnes.sirius.patrius.propagation.event]
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/package-summary.html Package fr.cnes.sirius.patrius.events]
|}

=== Links ===
None as of now.

=== Useful Documents ===
None as of now.

=== Package Overview ===
None as of now.

== Features Description ==
=== g functions ===
This section describes the meaning of the g switching function for the "sensors" event detectors :

==== CircularFieldOfViewDetector ====

The g switching function for the circular field of view is : <math>g=\alpha_{half aperture}-\alpha_{_{center-targetPosSat}}</math>. 
<math>\vec {targetPosSat}</math> is the satellite-target body vector in the satellite frame; <math>\alpha_{half aperture}</math> is the fov half aperture angle and <math>\alpha_{center-targetPosSat}</math> is the absolute value of the angle between target direction and field of view center.

* <math>g < 0 :</math> the target body is outside the field of view:
[[File:circularfov1.png|555x336px]]

* <math>g > 0 :</math> the target body is inside the field of view:
[[File:circularfov2.png|547x311px]]

==== CentralBodyMaskCircularFOVDetector ====

This detector is a combination of the previous circular field of view detector and the [MIS_ORB_Home#HPartialandTotaleclipsebyaspheroid eclipse detector] for an ellipsoid body. 
It detects the visibility only when the target is not eclipsed by the central body. 
The g switching function is : 
<math>g=min(circularFieldOfView, ellipsoidEclipse)</math>.

==== DihedralFieldOfViewDetector ====

The g switching function computes the distance between the target and the nearest boundary of the field of view. 
The double dihedral field of view is identified by the two following axes: 

* <math>axis_ {1}</math> is the axis of the first dihedral (<math>\vec n_ {1}</math> is its normal vector)
* <math>axis_ {2}</math> is the axis of the second dihedral (<math>\vec n_ {2}</math> is its normal vector)
If these 2 axes are orthogonal, we have a rectangular field of view. Otherwise, we have a trapezoidal field of view.

* <math>center</math> is the vector representing the fov center (intersection between the two dihedrals central planes). 
This axis must be obviously orthogonal to the 2 previous axis, but not necessarily in direct order.

The value of the g function is computed in two steps:

#computing the angular distance between the target body and the first dihedral, and then subtracting it from the fov first half-aperture angle; [[File:dihedralfov1.png]]
#computing the angular distance between the target body and the second dihedral, and then subtracting it from the fov second half-aperture angle; [[File:Bidihedral2.png]]

The lowest distance is then chosen to compute the g function.

* <math>g<0 :</math> the target body is ouside the field of view;
* <math>g>0 :</math> the target body is inside the field of view.

==== TargetInFieldOfViewDetector ====

This detector is defined from a sensor of an assembly part (see the Spacecraft user manual for details on sensor models). 
A sensor can contain a spherical main target (PVCoordinatesProvider + radius) and a field of view (IFieldOfView) defined in the local frame of the sensor. 
The g function of this sensor is positive when AT LEAST A PART this target is in the field, negative otherwise. So it detects the times when the target first enters and totaly leaves the field. 
In order to proceed to this computation, the MAIN frame (and so all of the part's frames) is updated from the current SpacecraftState.

==== SensorInhibitionDetector ====

This detector is defined from a sensor of an assembly part (see the Spacecraft user manual for details on sensor models). 
A sensor can contain an array of couples "inhibition target point" (PVCoordinatesProvider) / "inhibition field" (IFieldOfView) defined in the local frame of the sensor. 
The g function of this detector is positive when AT LEAST ONE of the inhibition target is AT LEAST PARTIALLY in its associated inhibition field. So it detects the first and last times of inhibition. 
In order to proceed to this computation, the MAIN frame (and so all of the part's frames) is updated from the current SpacecraftState.

==== MaskingDetector ====

This detector is defined from a sensor of an assembly part (see the Spacecraft user manual for details on sensor models). 
A sensor model can have a list of masking objects. Those objects are :

* Parts of the same spacecraft (that must have A GEOMETRY property)
* Parts of others spacecrafts, built as [MIS_SENSORS_SecondSpc SecondarySpacecraft] objects (that must have A GEOMETRY property)
* Celestial bodies, built as a [MIS_SENSORS_PatriusBodySpheroid BodyShape] objects. The g function of this detector is positive when AT LEAST ONE of the potentially masking bodies masks the target, negative otherwise. The masking happens when the line
segment between the sensor and the target's center is cut between them by the shape of the masking object. The "getMaskingObjectName" method allows the user to know wich one of the masking objects realises the masking event when occuring.

==== SensorVisibilityDetector ====

This detector is defined from a sensor of an assembly part (see the Spacecraft user manual for details on sensor models). 
It is based on the three previous ones : the g function is positive when the main target is IN the field of view AND ALL of the inhibition targets are OUT of their associated inhibition field, AND NO masking object cuts the sensor / target center line segment. When used with earth ellipsoid, the computation of sight axis local elevation on earth uses a rapid algorithm with limited accuracy : typically 1.3e-4 degrees (worst case, satellite altitude 250 Km, latitude 45 deg., East sight direction) if sight axis is 25 degrees above horizon, and 1.4e-6 degrees (worst case) if sight axis is 0,25 degrees above horizon.
The target’s sensor can either be defined as the signal emitter or receiver in the appropriated constructor.

==== ExtremaSightAxisDetector ====

This detector detects local extrema angle between the sight axis of a part having the SENSOR property and a given target. The target is a PVCoordinatesProvder, it means that it can be a point on the central body (TopocentricFrame) or another vehicle (Propagator).

This detector doesn't take into account masking by the earth.

This detector has also been design to work without assembly and part. In this case, the sight axis is given as a Vector3D and is apply to the origin of the orbital local frame taking attitude into account.

The switching function is based on the extrema three body angle detector where P1 is the target, P2 is the origin of the frame (sensor part frame, or orbital local frame) and P3 is the sight axis.

See the [SPC_Home Spacecraft] user manual for details about sensor models and the [MIS_ORB_Home Orbit determination detectors] user manual for details about extrema three bodies angle detector.

'''Note''': for the detection of events linked to the sight axis of an instrument, see also <code>CircularFieldOfViewDetector</code> and <code>CentralBodyMaskCircularFOVDetector</code>; they detect the passing of the sight axis close to a target (on ground, fixed or moving target, satellite, celestial body) taking account of the masking by the Earth. Events of the <code>ExtremaSigthAxisDetector</code> can also be filtered with phenomena detected with <code>CentralBodyMaskCircularFOVDetector</code>.

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

== Contents ==
=== Interfaces ===
All the detectors implement the interface :

{| class="wikitable"
|-
! scope="col"| Interface
! scope="col"| Summary
! scope="col"| Javadoc
|-
| EventDetector
|This interface represents an event finder.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/propagation/events/EventDetector.html EventDetector ]
|}

=== Classes ===

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
| CircularFieldOfViewDetector
|This class handles target entry/exit events with respect to a satellite sensor circular field of view.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/propagation/events/CircularFieldOfViewDetector.html CircularFieldOfViewDetector]
|-
| CentralBodyMaskCircularFOVDetector
|This class handles target entry/exit events with respect to a satellite sensor circular field of view taking central body masking into account.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/CentralBodyMaskCircularFOVDetector.html CentralBodyMaskCircularFOVDetector]
|-
| DihedralFieldOfViewDetector
|This class handles target entry/exit events with respect to a satellite sensor dihedral field of view.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/propagation/events/DihedralFieldOfViewDetector.html DihedralFieldOfViewDetector]
|-
| TargetInFieldOfViewDetector
|This class handles events representing the time when the main target of a sensor enters the field of view.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/sensor/TargetInFieldOfViewDetector.html TargetInFieldOfViewDetector]
|-
| SensorInhibitionDetector
|This class handles events representing the time when at least one of the the inhibition target of a sensor enters the field of view.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/sensor/SensorInhibitionDetector.html SensorInhibitionDetector ]
|-
| MaskingDetector
|This class handles events representing the time when at least one of the potentially masking objects that have been set to the sensor model is cutting the sensor / target center line segment.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/sensor/MaskingDetector.html MaskingDetector]
|-
| SensorVisibilityDetector
|This class handles events representing the time when, at the same time, 1) the main target of a sensor enters the field of view, 2) masking objects that have been set to the sensor model are not cutting the sensor/target center line segment and 3) no inhibition target is in its inhibition field.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/sensor/SensorVisibilityDetector.html SensorVisibilityDetector ]
|-
| ExtremaSightAxisDetector
|This class handles events representing extrema of the angular angle between a sight axis on a vehicle and a target. This doesn't take into account eventual masking from any occulting body even from central body.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/sensor/ExtremaSightAxisDetector.html ExtremaSightAxisDetector]
|}

[[Category:User_Manual_4.17_Mission]]

User Manual 4.17 Data management system

2025-11-27T08:30:21Z

Admin tsn : Page créée avec «  == Introduction == === Scope === The scope of this chapter is to present data management. This section presents the three modules of the data management system originally provided by Orekit : * how does the data management system work? * how to set it up? * how to use it? * how to add data to what already exists? * what are the pros and cons of this system? === Javadoc === The data objects are available in the package <code>fr.cnes.sirius.patrius.data</code>.... »

== Introduction ==
=== Scope ===
The scope of this chapter is to present data management. This section presents the three modules of the data management system originally provided by Orekit :

* how does the data management system work?
* how to set it up?
* how to use it?
* how to add data to what already exists?
* what are the pros and cons of this system?

=== Javadoc ===
The data objects are available in the package <code>fr.cnes.sirius.patrius.data</code>.

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
| Orekit
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/data/package-summary.html Package fr.cnes.sirius.patrius.data]
|}

=== Links ===
{{specialInclusion prefix=$theme_sub section="Links"/}}

=== Useful Documents ===
{{specialInclusion prefix=$theme_sub section="UsefulDocs"/}}

=== Package Overview ===
The data loading process is organized through three main objects.

The <code>DataProvider</code> classes handle data sources. Each one of them has a particular type of source it can browse. The <code>DirectoryCrawler</code> performs a bottom-first search in a directory tree. The <code>ZipJarCrawler</code> works alike, but inside a compressed file. The <code>ClassPathCrawler</code> handles a list of data files and/or compressed files that are in the classpath (it can not search recursively like the <code>DirectoryCrawler</code> though). Finally, the <code>NetworkCrawler</code> works like the <code>ClassPathCrawler</code>, although in its case, it has a list of URLs instead of files. There is no limit to the number of DataProviders a program can use at once.

The Providers are listed and put to work through the <code>DataProvidersManager</code> singleton. This is the single point of access to the data management system. It contains a list of Providers that are queried every time a user needs data.

The various crawlers provide streams to the <code>DataLoader</code>. From these streams, the DataLoaders can reconstruct data that was stored in files (either compressed or not), even if some files come from different sources. These streams effectively separate the machine world from the program world, because they hide the former to the latter. Therefore, parsing data from a new format only means creating a loader, and being able to read another kind of file means creating a <code>DataProvider</code>. Note that the DataLoaders usually serve as a facade for the higher layers of the program.

== Features Description ==

=== Data providers ===

==== Default provider ====
The data management system can use a system-wide property, <code>orekit.data.path</code>, as an entry point for default data. This default data must be file-based (either a file system entry point or a java resource) and either a directory or a zip/jar file.
Setting a default provider is not mandatory, and must be done explicitly by :

* setting a value to <code>orekit.data.path</code>,
* calling <code>addDefaultProviders</code> on the data provider manager.

==== Adding a provider ====
{{specialInclusion prefix=$theme_sub section="Provider"/}}

==== Using the data management system ====
The data management system main operation is through the <code>feed</code> method. This method takes a <code>DataLoader</code>, and a regexp string matching the name of files the <code>DataLoader</code> is able to process. In this method call :

* the <code>DataProviders</code> list is traversed in the priority order.
* the first <code>DataProvider</code> providing a file matching the regexp is the one (and only) used to feed the <code>DataLoader</code>.

==== Adding new data ====
{{specialInclusion prefix=$theme_sub section="Adding"/}}

=== File formats ===
Patrius can read a variety of files:
* '''Static potential files'''
These files contains static potential coefficients up to a certain order and degree and are used to compute Earth (or any other body) static potential perturbation.

* '''Variable potential files'''
Theses files contains variable potential coefficients up to a certain order and degree and are used to compute Earth (or any other body) variable potential perturbation.

* '''Geomagnetic coefficients files'''
These files contains geomagnetic coefficients and are used to compute Earth (or any other body) geomagnetic field.

* '''Ionospheric coefficients files'''
These files contains ionospheric data and are used to compute Earth ionospheric correction.

* '''Solar activity files'''
These files contains solar flux and geomagnetic coefficients are used to get solar activity in order to compute drag perturbation.

* '''Earth Orientation Parameters files'''
These files contains earth orientation parameters (polar motion, LOD, etc.) used in frames transformation.

* '''TAI-UTC shift files'''
These files contains TAI-TUC shift.

* '''Orbital data files'''
These files are used to store orbital ephemeris

* '''Third body ephemeris files'''
These files are used to store third-body orbital ephemeris (Sun, Moon, etc.)

The following sections describe all file readable in PATRIUS. When the file format is not described anywhere, a short description is detailed below the tab.

==== Static Potential ====

Static potential coefficients files contains potential coefficients up to a certain order and degree. 
Warning: at very high order and degree (> 100), some numerical quality issues can appear and results may be degraded.

{| class="wikitable"
|-
! scope="col"| Data type
! scope="col"| Data provider
! scope="col"| Format
! scope="col"| Reader
|-
|'''GRGS'''
|Not direct link. This link provides GRGC potential coefficients [http://grgs.obs-mip.fr/grace/variable-models-grace-lageos/interactive-tools/Check-individual-solutions]
|[http://grgs.obs-mip.fr/grace/variable-models-grace-lageos/formats]
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/potential/GRGSFormatReader.html GRGSFormatReader]
|-
|'''EGM'''
|[http://earth-info.nga.mil/GandG/wgs84/gravitymod/egm2008/first_release.html]
|See below
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/potential/EGMFormatReader.html EGMFormatReader]
|-
|'''ICGEM'''
|[http://icgem.gfz-potsdam.de/tom_longtime]
|[http://icgem.gfz-potsdam.de/ICGEM-Format-2011.pdf]
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/potential/ICGEMFormatReader.html ICGEMFormatReader]
|-
|'''SHM'''
|Not provided (not used any more, replaced by ICGEM format)
|See below
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/potential/SHMFormatReader.html SHMFormatReader]
|}

'''EGM file format''' (''Column text file'')

Column index: 
1:Degree of coefficients 
2:Order of coefficients 
3:Tesseral-sectorial cosinus coefficient 
4:Tesseral-sectorial sinus coefficient 
5:Sigma applied to the cosinus 
6:Sigma applied to the sinus

[[File:EGM.png|center]]

'''SHM file format''' (''Column text file'')

Column index: 
2:Degree of coefficients 
3:Order of coefficients 
4:Tesseral-sectorial cosinus coefficient 
5:Tesseral-sectorial sinus coefficient 

[[File:SHM.png|center]]

==== Variable Potential ====

Variable potential coefficients files contains potential coefficients up to a certain order and degree. 
Warning: at very high order and degree (> 100), some numerical quality issues can appear and results may be degraded.

FES2004 is used to model oceanic tides.

{| class="wikitable"
|-
! scope="col"| Data type
! scope="col"| Data provider
! scope="col"| Format
! scope="col"| Reader
|-
|'''GRGSRL02'''
|[http://grgs.obs-mip.fr/grace/variable-models-grace-lageos/interactive-tools/Check-individual-solutions]
|[http://grgs.obs-mip.fr/grace/variable-models-grace-lageos/formats]
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/variations/coefficients/GRGSRL02FormatReader.html GRGSRL02FormatReader]
|-
|'''FES2004'''
|[https://www.aviso.altimetry.fr/en/data/products/auxiliary-products/global-tide-fes.html]
|See below
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/gravity/tides/coefficients/FES2004FormatReader.html FES2004FormatReader]
|}

'''FES2004 file format''' (''Column text file'')

Column index: 
1:Doodson number 
2:Darwin number 
3:Degree of coefficients 
4:Order of coefficients 
5:Sinus coefficient positif 
6:Cosinus coefficient positif 
7:Sinus coefficient negatif 
8:Cosinus coefficient negatif 
9:Positif coefficient 
10:Epsilon positif 
11:Negatif coefficient 
12:Negatif epsilon

[[File:FES2004.png|center]]

==== Geomagnetic coefficients ====

Geomagnetic coefficients fiels contains geomagnetic coefficients up to a certain order and degree.

{| class="wikitable"
|-
! scope="col"| Data type
! scope="col"| Data provider
! scope="col"| Format
! scope="col"| Reader
|-
|'''COF'''
|IGCRF data: [https://www.ngdc.noaa.gov/IAGA/vmod/igrf.html] WMM data: [https://www.ngdc.noaa.gov/geomag/WMM/soft.shtml]
|See below
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/models/earth/COFFileFormatReader.html COFFileFormatReader]
|}

'''COF file format''' (''Column text file'')

Column index: 
1:Degree of coefficients 
2:Order of coefficients 
3:g coefficient at position n,m 
4:h coefficient at position n,m 
5:dg coefficient at position n,m 
6:dh coefficient at position n,m 
g and h are the Gauss coefficients of main geomagnetic model (nT) 
dg and dh are the Gauss coefficients of secular geomagnetic model (nT/years)

[[File:COF.png|center]]

==== Ionospheric coefficients ====

Ionospheric coefficients files contains ionospheric coefficient to model the state of the ionosphere.

{| class="wikitable"
|-
! scope="col"| Data type
! scope="col"| Data provider
! scope="col"| Format
! scope="col"| Reader
|-
|'''CCIR12'''
|N/A
|See below
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/signalpropagation/iono/R12Loader.html R12Loader]
|-
|'''USK(NEWUSK)'''
|N/A
|See below
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/signalpropagation/iono/USKLoader.html USKLoader]
|}

'''CCIR12 file format''' (''Column text file'')

Column index: 
1:Year 
2:Month 
3:Unused 
4:Midval 
5:Unused 
6:Midday 

[[File:CCIR12.png]]

'''USK file format''' (''Line text file'')

[[File:NEWUSK.png|center]]

==== Solar activity ====

Solar activity contains solar flux and geomagnetic coefficients for a given timespan. ACSOL and NOAA files usually provide data for several years.

{| class="wikitable"
|-
! scope="col"| Data type
! scope="col"| Data provider
! scope="col"| Format
! scope="col"| Reader
|-
|'''ACSOL'''
|N/A
|See below
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/ACSOLFormatReader.html ACSOLFormatReader]
|-
|'''NOAA'''
|N/A
|See below
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/NOAAFormatReader.html NOAAFormatReader]
|}

'''ACSOL file format''' (''Column text file'')

Column index: 
1:Julian day since 1950 
2:Seconds of the day (UTC) 
3:Flux at JD + seconds 
4-11 are the three-hours AP of the intervals

[[File:ACSOL.png|center]]

'''NOAA file format''' (''Column text file'')

Column index: 
1:Day 
2:Flux at the day 
3:The background flux 
4-11:the three-hours AP of the intervals 
12:Year 
13:Unused character flag

==== Pole data ====

These files contains earth orientation parameters (polar motion, LOD, etc.) used in frames transformation. 
These data are usually valid of a timespan of several days/months, although there is no theoretical limit.

{| class="wikitable"
|-
! scope="col"| Data type
! scope="col"| Data provider
! scope="col"| Format
! scope="col"| Reader
|-
|'''Bulletin B'''
|[ftp://hpiers.obspm.fr/iers/bul/bulb_new]
|[ftp://hpiers.obspm.fr/iers/bul/bulb_new/bulletinb.pdf]
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/configuration/eop/BulletinBFilesLoader.html BulletinBFilesLoader]
|-
|'''EOP 05 C04'''
|[ftp://hpiers.obspm.fr/iers/eop/eopc04_05]
|See below
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/configuration/eop/EOP05C04FilesLoader.html EOP05C04FilesLoader]
|-
|'''EOP 08 C04'''
|[https://datacenter.iers.org/web/guest/eop/-/somos/5Rgv/version/212]
|See below
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/configuration/eop/EOP08C04FilesLoader.html EOP08C04FilesLoader]
|-
|'''Datas "Rapid and Prediction" (TXT)'''
|[http://maia.usno.navy.mil/ser7]
|[http://maia.usno.navy.mil/ser7/readme.finals]
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/configuration/eop/RapidDataAndPredictionColumnsLoader.html RapidDataAndPredictionColumnsLoader]
|-
|'''Datas "Rapid and Prediction" (XML)'''
|[https://datacenter.iers.org/eop/-/somos/5Rgv/eop?]
|Same datas than the column file but write in the xml format
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/configuration/eop/RapidDataAndPredictionXMLLoader.html RapidDataAndPredictionXMLLoader]
|}

'''EOP 05 C04 and EOP 08 C04 files format''' (''Column text file'')

Column index: 
1:Date at 0h(UTC) 
2:Modified Julian Day 
3:x(") 
4:y(") 
5:UT1-UTC(s) 
6:LOD(s) 
7:DPsi(") 
8:DEps(") 
9:x error (") 
10:y error (") 
11:UT1-UTC error (s) 
12:LOD error(s) 
13:Dpsi error(") 
14:DEpsilon error(") 
x and y are the coordinales of the Celestial Ephemeris Pole. 
UT1: Universal time, the time of the earth clock 
LOD: Length Of Day is the excess of revolution time

[[File:EOP08C04.png|center]]

==== TAI-UTC shift====

These files contains TAI-TUC shift. Official data contains shift since the beginning of space era (1961).

{| class="wikitable"
|-
! scope="col"| Data type
! scope="col"| Data provider
! scope="col"| Format
! scope="col"| Reader
|-
|'''Gap TAI-UTC'''
|[ftp://hpiers.obspm.fr/iers/bul/bulc/UTC-TAI.history]
|See below
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/time/UTCTAIHistoryFilesLoader.html UTCTAIHistoryFilesLoader]
|}

'''TAI-UTC file format''' (''Column text file'')

Column index: 
1:Begining date-Ending date 
2:Difference TAI-UTC between the begining date and the ending date

[[File:TAI-TUC.png|center]]

==== Orbital data ====

These files are used to store orbital ephemeris. 
TLE provides orbit at one date. Ephemeris is then retrieved thanks to SGP4/SDP4 propagation model. 
SP3 files provide orbit over an extended time span (ex: 1 day).

{| class="wikitable"
|-
! scope="col"| Data type
! scope="col"| Data provider
! scope="col"| Format
! scope="col"| Reader
|-
|'''TLE'''
|[https://www.projectpluto.com/pluto/mpecs/pseudo.htm]
|[https://www.mmto.org/obscats/tle.html]
[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/propagation/analytical/tle/TLESeries.html TLESeries]
|-
|'''SP3'''
|GPS and GLONASS only [ftp://cddis.gsfc.nasa.gov/gnss/products]
|[ftp://igs.org/pub/data/format/sp3_docu.txt]
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/files/sp3/SP3File.html SP3File]
|}

Note: * SP3 files can be written by anyone. They are however mainly used ton provide GPS and GLONASS ephemeris.

Note2: * If the accuracy is not present in the SP3 file, a value of 0 automatically given. This allows the parsing of the SP3 to continue while giving the user the information that the accuracy field was not read (0 is an impossible value since the accuracy is given as 2^n).

==== Third body ephemeris ====

Third body ephemeris files contains ephemeris for third bodies (Moon, Sun, Jupiter) over an extended time span (ex: 1 or several days).

{| class="wikitable"
|-
! scope="col"| Data type
! scope="col"| Data provider
! scope="col"| Format
! scope="col"| Reader
|-
|'''JPL'''
|[https://ssd.jpl.nasa.gov/pub/eph/planets/SunOS]
|[https://ssd.jpl.nasa.gov/pub/eph/planets/Linux]
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/JPLCelestialBodyLoader.html JPLCelestialBodyLoader]
|}

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

== Contents ==
=== Interfaces ===
The data package includes the following interfaces :

'''Data'''

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''DataLoader'''
|Interface for loading data files from DataProvider data providers.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/data/DataLoader.html ...]
|-
|'''DataProvider'''
|Interface for providing data files to DataLoader file loaders.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/data/DataProvider.html ...]
|}

=== Classes ===
The data package includes the following classes :

'''Data'''

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''DataProvidersManager'''
|This class is the single point of access for all data loading features.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/data/DataProvidersManager.html ...]
|-
|'''DirectoryCrawler'''
|This class handles data files recursively starting from a root directories.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/data/DirectoryCrawler.html ...]
|-
|'''NetworkCrawler'''
|This class handles a list of URLs pointing to data files or zip/jar on the net.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/data/NetworkCrawler.html ...]
|-
|'''ZipJarCrawler'''
|This class browses all entries in a zip/jar archive in filesystem or in classpath.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/data/ZipJarCrawler.html ...]
|}

== [[File:lightBulb.png]] Tips & Tricks ==
=== Strengths ===

* Lightweight implementation. The providers never load data, they merely provide streams on demand to the loaders.
* Scalable for using data from several heterogeneous sources.
* Scalable for new data types : the user only needs to create a new <code>DataLoader</code> implementation to use a new data type in this system.

=== Weaknesses ===

* The user must be aware the data loading overhead happens any time a <code>DataLoader</code> is fed, so the user must manage its loaders so that they are fed only once.
* Several sources for the same type of data cannot be used, since only the last provider added is used to feed data to a loader - unless the user manages the providers list accordingly, knowing one can only add elements or reset the whole list.
* The regexp is the only way to match a data file and a <code>DataLoader</code>.
* As of today, the data management system is a thread-hostile singleton : a multithreaded application shares the same providers list for all threads, and it may deadlock on a concurrent access!

Accueil

2025-11-26T14:01:08Z

Admin tsn :

__NOTOC__
== WHERE TO GET IT? ==

Just go [https://www.connectbycnes.fr/en/patrius there] ...

== WHY PATRIUS? ==

'''PATRIUS''' is a core space dynamics Java library that enables to quickly develop high level algorithms such as orbit extrapolator. '''PATRIUS''' contains several low level classes (i.e.: such as matrix, vectors, orbits parameters) as well as high level classes and interfaces (i.e.: numerical propagators, attitude laws, manoeuvers sequences).

== MAIN ADVANTAGES ==

All the main domains of space dynamics are available:
* Analysis, algebra & geometry (quaternions, derivable functions, integrators …)
* Core objects for space dynamics (dates, orbits, frames...)
* Orbit propagation: analytical, semi-analytical and numerical propagators, a full set of force models
* Maneuvers: impulsive or continuous thrust, sequences
* Attitude: extensible set of attitude laws, sequences and guidance framework
* Events: event detection (orbital, sensor events, etc.) and post-processing (chronograms)
* Spacecraft: characteristics of mass, geometry (drag force), sensors field of view, etc.

'''PATRIUS''' got a deep validation by comparison with precise orbitography tools. Moreover, it is now fully used by CNES tools, in particular for operational flight dynamics subsystem (FDS). For that reason the criticity level is “'''C'''”.

Furthermore, '''PATRIUS''' design relies on extensible Java interfaces and robust design patterns.

== REMARKS ==

A data package ([https://www.connectbycnes.fr/en/patriusdataset PATRIUS_DATASET]) is also provided in addition allowing access to some data models.

Tutorials are available in specific tutorials pages.

== CURRENT VERSION: 4.17 ==
'''PATRIUS''' V4.17 is a release adding a few features as well as correcting some bugs (see [[Main_differences_between_V4.15_and_V4.14|here]]).

== PREVIOUS VERSIONS (available on the Web site) ==

* Version 4.16
* Version 4.15
* Version 4.14
* Version 4.13
* Version 4.12
* Version 4.11
* Version 4.10
* Version 4.9
* Version 4.8
* Version 4.7
* Version 4.6.1
* Version 4.5.1
* Version 4.4
* Version 4.3
* Version 4.2
* Version 4.1.1
* Version 4.1
* Version 4.0
* Version 3.4.1
* Version 3.3
* Version 3.2

== DEPENDENCIES ==

See when the different PATRIUS versions were released and what JAVA version each is compatible with [[Patrius_Versions_and_Dependencies|here]]

== JAVA DOC ==

[https://patrius.cnes.fr/images/upload/JavaDocs/V4.17 Current Java Doc]

[https://patrius.cnes.fr/images/upload/JavaDocs/V4.16 Java Doc 4.16] 
[https://patrius.cnes.fr/images/upload/JavaDocs/V4.15 Java Doc 4.15] 
[https://patrius.cnes.fr/images/upload/JavaDocs/V4.14 Java Doc 4.14] 
[https://patrius.cnes.fr/images/upload/JavaDocs/V4.13 Java Doc 4.13] 
[https://patrius.cnes.fr/images/upload/JavaDocs/V4.12 Java Doc 4.12] 
[https://patrius.cnes.fr/images/upload/JavaDocs/V4.11 Java Doc 4.11] 
[https://patrius.cnes.fr/images/upload/JavaDocs/V4.10.2 Java Doc 4.10.2] 
[https://patrius.cnes.fr/images/upload/JavaDocs/V4.9.1 Java Doc 4.9.1] 
[https://patrius.cnes.fr/images/upload/JavaDocs/V4.8 Java Doc 4.8] 
[https://patrius.cnes.fr/images/upload/JavaDocs/V4.7 Java Doc 4.7] 
[https://patrius.cnes.fr/images/upload/JavaDocs/V4.6.1 Java Doc 4.6.1] 
[https://patrius.cnes.fr/images/upload/JavaDocs/V4.5.1 Java Doc 4.5.1] 
[https://patrius.cnes.fr/images/upload/JavaDocs/V4.4 Java Doc 4.4] 
[https://patrius.cnes.fr/images/upload/JavaDocs/V4.3 Java Doc 4.3] 
[https://patrius.cnes.fr/images/upload/JavaDocs/V4.2 Java Doc 4.2] 
[https://patrius.cnes.fr/images/upload/JavaDocs/V4.1.1 Java Doc 4.1.1] 
[https://patrius.cnes.fr/images/upload/JavaDocs/V4.1 Java Doc 4.1] 
[https://patrius.cnes.fr/images/upload/JavaDocs/V4.0 Java Doc 4.0] 
[https://patrius.cnes.fr/images/upload/JavaDocs/V3.4.1 Java Doc 3.4.1] 
[https://patrius.cnes.fr/images/upload/JavaDocs/V3.3 Java Doc 3.3] 
[https://patrius.cnes.fr/images/upload/JavaDocs/V3.2 Java Doc 3.2]

Catégorie:User Manual 4.17

2025-11-26T13:58:20Z

Admin tsn : Page créée avec «  == Introduction == This document is the main user manual of the PATRIUS library, which provides Java classes in a wide range of themes related with space flight dynamics. The library has several purposes : * to be a basis for the next generation FDS development * to be used in mission analysis and internal studies Its classes contain the main basis algorithms and objects representation that shall be used in further developments. For each theme, a specific ma... »

== Introduction ==
This document is the main user manual of the PATRIUS library, which provides Java classes in a wide range of themes related with space flight dynamics.

The library has several purposes :

* to be a basis for the next generation FDS development
* to be used in mission analysis and internal studies

Its classes contain the main basis algorithms and objects representation that shall be used in further developments.

For each theme, a specific manual is available.

== Applicable and Reference Documents ==
=== Applicable Documents ===
'''[A1]''' ''CDCF- Fonctions de Base du Patrimoine de Dynamique du Vol'', V1.2, SIRIUS-CF-DV-0049-CN, 2011. 
'''[A2]''' ''Dossier de réutilisation Orekit et Commons Math'', V1.0, SIRIUS-DLR-DV-0080-CN, 2010.

== Glossary ==
{| class="wikitable"
|-
!scope="row"| SDD
| Software Design Document
|-
!scope="row"| SRS
| Software Requirements Specification
|-
!scope="row"| SUM
| Software User Manual
|-
!scope="row"| SValP
| Software Validation Plan
|-
!scope="row"| SVerP
| Software Verification Plan
|-
!scope="row"| SVS
| Software Validation Specification
|}

== Conventions ==
All the user manuals contain some java code sample as use examples.

These samples are recognizable by the following colors convention :

<syntaxhighlight lang="java">
Vector3D originCone = new Vector3D(1.0, 1.0, 1.0);
Vector3D direction = new Vector3D(2.0, 0.0, 0.0);
double angle = FastMath.PI / 4.0;
double height = 5.0;
RightCircularCone cone = new RightCircularCone(originCone, axis, angle, height);
</syntaxhighlight>

PATRIUS uses the '''International System of Units (SI units)''' (m, kg, s, N, etc.). It is used for all PATRIUS input/output as well as internally for any computation.

== Overview ==
This document is an aid for developers coding software using the PATRIUS library. The library provides Java classes to represent basis objects and contains low level algorithms to be used in the new FDS and mission analysis softwares.
The user guide describes and explains the use of every class and functionality available.

Each theme of the library is the object of a specific document. These themes are :

* Math basis
* Flight dynamics basis
* Attitude
* Spacecraft
* Orbits
* Mission
* Tools
* Support

PATRIUS is under Apache Licence 2.0.

== Quick Start==
Here is a description of each theme of the PATRIUS library and an overview of its contents. See each associated document for the details.

=== Mathematics ===
This theme is not directly linked to flight dynamics. It include. It provides the mathematical tools for the rest of the library.

Its contains classes for :

* function analysis (interpolations, polynomials, ...)
* numerical intergrators
* geometry (planes, lines, shapes, rotations, 3d vectors and matrixes...)
* low level functions and constants (sine, cosine, PI, ...)
* linear algebra (real matrix and vectors, decompositions and other matrix computations, ...

The Mathematics User Manual can be found [[:Category:User_Manual_4.17_Mathematics|here]].

=== Flight Dynamics ===
This theme contains the basis of orbital mechanics :

* position-velocity and orbital parameters conversions
* frames and frames transforms
* dates and time scales
* time intervals

The Flight Dynamics User Manual can be found [[:Category:User_Manual_4.17_Flight_Dynamics|here]].

=== Spacecraft ===
This theme contains everything useful to describe a spacecraft and its use :

* general architecture (describing the spacecraft by one or several parts)
* geometry
* mass caracteristics
* equipments (GS, antenna, instruments and associated computations...)
* caracteristics used in forces computations (radiative, drag...)
* torques computations

The Spacecraft User Manual can be found [[:Category:User_Manual_4.17_Spacecraft|here]].

=== Attitude ===
This theme contains the tools to predict the spacecraft attitude:

* attitude laws
* cinematics and guidance

The Attitude User Manual can be found [[:Category:User_Manual_4.17_Attitude|here]].

=== Orbits ===
This theme contains everything useful to propagate an orbit in time and perform orbits restitutions :

* numerical and analytical propagators
* physical models (for forces)
* Measures and filtering tools

The Orbits User Manual can be found [[:Category:User_Manual_4.17_Orbit_Propagation|here]].

=== Mission ===
This theme regroups the events computation, projections and use tools.

The Mission User Manual can be found [[:Category:User_Manual_4.17_Mission|here]].

=== Tools ===
This theme comprises some external tools such as the ephemeris comparator.

The Tools User Manual can be found [[User_Manual_4.17_Tools|here]].

=== Support ===
This theme is cross-functional. It contains for example the explaination of the data manager use and action.

The Support User Manual can be found [[User_Manual_4.17_Support|here]].

== Patrius Configuration ==
As of PATRIUS version 4.14, some propagation models and optimization algorithms are backward compatible to the PATRIUS version 4.12. '''Without any action done by the user, the backward compatibility is activated by default'''. More details about this important option are reported [[:Category:Patrius_Backward_Compatibility_4.17|here]].

== Thread-Safety ==
For all content belonging to the PATRIUS library, the thread safety of every class will be evaluated,
and the results listed here.

The known levels of thread safety for a class are:

* immutable: the contents of an instance never change after creation, therefore the class is thread-safe.
* unconditionally thread-safe / thread-safe: the whole class is thread-safe by design.
* conditionally thread-safe: the class is thread-safe if certain conditions (specific to the class) are met.
* not thread-safe: the class is not thread-safe. If the class is used in a threaded environment, all accesses to the class must be synchronized.
* thread-hostile: the class is known to break threads, even when no instance is shared between threads!

=== About the comments ===

Some recurring comments are explained here :

* "Exposed mutable attributes.": the class contains attributes that either "come" from outside the class, or whose reference can be obtained from the class. Unless the attributes are thread-safe or accessed in a thread-safe manner somehow, this breaks the thread safety of the class.
* "documented as immutable, but technically untrue": Patrius document classes that are non-final as immutable- but the (quite strict) usual definition of immutability mandates that an immutable class ''must'' be final, because a non-final class can be subclassed and this subclass can break immutability "silently" (an user could access this subclass through the superclass reference and believe it is immutable due to the superclasses' documentation.) Therefore: when a class is documented as immutable, it means ''only the documented implementation'' is immutable. For safety, we chose to document these classes here as "unconditionally thread-safe", a statement that is not assumed to be preserved by subclassing.

=== Thread safety ===
Details concerning the thread safety for each of the PATRIUS classes can be found [[:Category:Thread_Safety_4.17|here]].

==== Note : Frames and thread-safety ====

It was determined that several Frame implementations were thread-hostile.

The current evaluation of these changes from a thread-safety point of view leads us to state the following :

* The IERS frames (GCRF, CIRF, TIRF and ITRF) are thread-safe.

== Known Issues ==
None.

Catégorie:Patrius Backward Compatibility 4.17

2025-11-26T13:58:03Z

Admin tsn : Page créée avec «  == Introduction == A specific backward compatibility mechanism is implemented in PATRIUS allowing by default to have a backward compatibility with PATRIUS version 4.12 propagation models and/or optimisation algorithms. If any action is provided by the user, the '''backward compatibility is activated by default in PATRIUS''' : this means that external users will see their code/functions working with some of the propagation models/optimisation algorithms of PATRIU... »

== Introduction ==
A specific backward compatibility mechanism is implemented in PATRIUS allowing by default to have a backward compatibility with PATRIUS version 4.12 propagation models and/or optimisation algorithms.
If any action is provided by the user, the '''backward compatibility is activated by default in PATRIUS''' : this means that external users will see their code/functions working with some of the propagation models/optimisation algorithms of PATRIUS version 4.12.

== Backward compatibility functionalities ==

=== Available options ===
Three options are available for users via the enum <code>PatriusVersionCompatibility</code> of the class <code>PatriusConfiguration</code>:
* OLD_MODELS : the user will use the propagation models and optimisation algorithms coded in PATRIUS version 4.12;
* MIXED_MODELS : the user will just use propagation models coded in PATRIUS version 4.12 (no backward compatibility on optimisation algorithms);
* NEW_MODELS : no backward compatibility mechanism is used.

=== Backward compatibility for propagation models ===
As previously mentioned, types <code>PatriusVersionCompatibility.OLD_MODELS</code> or <code>MIXED_MODELS</code> allow to restore some of the propagation models to the state of PATRIUS version 4.12 for the following functionalities:
* eclipse detection via the class <code>EclipseDetector</code>;
* solar radiation pressure computation with the class <code>SolarRadiationPressure</code>;
* use of previous obliquity coefficients in the class <code>EclipticMODProvider</code> ;
* allows the use of previous entries in the factory <code>PrecessionNutationModelFactory</code> and pole coordinates computation in the class <code>IERS20032010PrecessionNutation</code>.

=== Backward compatibility for optimisation algorithms ===
The type of compatibility configuration OLD_MODELS allows to restore also the behaviour of the optimisation algorithm for matrix conversion existing in PATRIUS 4.12 and implemented in the method <code>convertMatrixFromAToB</code> of the class <code>AbstractBodyAttraction</code>.

== How to set our own Patrius compatibility configuration ==
The class <code>PatriusConfiguration</code> contains a setter <code>setPatriusCompatibilityMode(PatriusVersionCompatibility)</code> that allows to switch our own configuration as a function of the user needs.
A specific getter <code>getPatriusCompatibilityMode</code> allows to retrieve the used configuration at any moment if needed.

[[Category:User_Manual_4.17]]

Catégorie:Thread Safety 4.17

2025-11-26T13:57:41Z

Admin tsn : Page créée avec « The following tables contains information about the different class of PATRIUS and their thread-safety properties. {| class="wikitable" |- ! scope="col"| Class (total number : 43) ! scope="col"| Concurrency ! scope="col"| Comment |- |fr.cnes.sirius.patrius.math.UtilsCommonsMath |immutable | |- |fr.cnes.sirius.patrius.math.analysis.differentiation.RiddersDifferentiator |immutable | |- |fr.cnes.sirius.patrius.math.analysis.interpolation.BiLinearIntervalsFunction |... »

The following tables contains information about the different class of PATRIUS and their thread-safety properties.

{| class="wikitable"
|-
! scope="col"| Class (total number : 43)
! scope="col"| Concurrency
! scope="col"| Comment
|-
|fr.cnes.sirius.patrius.math.UtilsCommonsMath
|immutable
|
|-
|fr.cnes.sirius.patrius.math.analysis.differentiation.RiddersDifferentiator
|immutable
|
|-
|fr.cnes.sirius.patrius.math.analysis.interpolation.BiLinearIntervalsFunction
|not thread-safe
|input ISearchIndex not thread-safe
|-
|fr.cnes.sirius.patrius.math.analysis.interpolation.BiLinearIntervalsInterpolator
|unconditionally thread-safe
|
|-
|fr.cnes.sirius.patrius.math.analysis.interpolation.TriLinearIntervalsFunction
|not thread-safe
|input ISearchIndex not thread-safe
|-
|fr.cnes.sirius.patrius.math.analysis.interpolation.TriLinearIntervalsInterpolator
|unconditionally thread-safe
|
|-
|fr.cnes.sirius.patrius.math.analysis.interpolation.UniLinearIntervalsFunction
|not thread-safe
|input ISearchIndex not thread-safe
|-
|fr.cnes.sirius.patrius.math.analysis.interpolation.UniLinearIntervalsInterpolator
|unconditionally thread-safe
|
|-
|fr.cnes.sirius.patrius.math.analysis.polynomials.ElementaryMultiplicationTypes
|unconditionally thread-safe
|
|-utility class without attributes
|fr.cnes.sirius.patrius.math.analysis.polynomials.FourierDecompositionEngine
|not thread-safe
|not thread safe because of the setFunction method that can change the UnivariateFunction being decomposed
|-
|fr.cnes.sirius.patrius.math.analysis.polynomials.FourierSeries
|immutable
|
|-
|fr.cnes.sirius.patrius.math.analysis.polynomials.FourierSeriesApproximation
|immutable if function is immutable
|
|-
|fr.cnes.sirius.patrius.math.analysis.polynomials.TrigonometricPolynomialFunction
|immutable
|
|-
|fr.cnes.sirius.patrius.math.analysis.polynomials.TrigonometricPolynomialPrimitive
|immutable
|
|-
|fr.cnes.sirius.patrius.math.geometry.euclidean.threed.Disk
|immutable
|
|-
|fr.cnes.sirius.patrius.math.geometry.euclidean.threed.Ellipse
|immutable
|
|-
|fr.cnes.sirius.patrius.math.geometry.euclidean.threed.Ellipsoid
|immutable
|
|-
|fr.cnes.sirius.patrius.math.geometry.euclidean.threed.EllipticCone
|immutable
|
|-
|fr.cnes.sirius.patrius.math.geometry.euclidean.threed.EllipticCylinder
|immutable
|
|-
|fr.cnes.sirius.patrius.math.geometry.euclidean.threed.InfiniteEllipticCone
|immutable
|
|-
|fr.cnes.sirius.patrius.math.geometry.euclidean.threed.InfiniteEllipticCylinder
|immutable
|
|-
|fr.cnes.sirius.patrius.math.geometry.euclidean.threed.InfiniteRectangleCone
|immutable
|
|-
|fr.cnes.sirius.patrius.math.geometry.euclidean.threed.InfiniteRectangleCylinder
|immutable
|
|-
|fr.cnes.sirius.patrius.math.geometry.euclidean.threed.InfiniteRightCircularCone
|immutable
|
|-
|fr.cnes.sirius.patrius.math.geometry.euclidean.threed.InfiniteRightCircularCylinder
|immutable
|
|-
|fr.cnes.sirius.patrius.math.geometry.euclidean.threed.LineSegment
|immutable
|
|-
|fr.cnes.sirius.patrius.math.geometry.euclidean.threed.Matrix3D
|immutable
|
|-
|fr.cnes.sirius.patrius.math.geometry.euclidean.threed.Parallelepiped
|immutable
|
|-
|fr.cnes.sirius.patrius.math.geometry.euclidean.threed.Plate
|immutable
|
|-
|fr.cnes.sirius.patrius.math.geometry.euclidean.threed.RectangleCone
|immutable
|
|-
|fr.cnes.sirius.patrius.math.geometry.euclidean.threed.RightCircularCone
|immutable
|
|-
|fr.cnes.sirius.patrius.math.geometry.euclidean.threed.RightCircularCylinder
|immutable
|
|-
|fr.cnes.sirius.patrius.math.geometry.euclidean.threed.Sphere
|immutable
|
|-
|fr.cnes.sirius.patrius.math.geometry.euclidean.threed.SphericalCap
|immutable
|
|-
|fr.cnes.sirius.patrius.math.geometry.euclidean.threed.Spheroid
|immutable
|
|-
|fr.cnes.sirius.patrius.math.linear.UDDecompositionImpl
|immutable
|
|-
|fr.cnes.sirius.patrius.math.ode.nonstiff.RungeKutta6Integrator
|not thread-safe
|
|-
|fr.cnes.sirius.patrius.math.ode.nonstiff.RungeKutta6StepInterpolator
|not thread-safe
|
|-
|fr.cnes.sirius.patrius.math.random.UniformlyCorrelatedRandomVectorGenerator
|not thread-safe
|
|-
|fr.cnes.sirius.patrius.math.utils.BinarySearchIndexClosedOpen
|immutable
|
|-
|fr.cnes.sirius.patrius.math.utils.BinarySearchIndexOpenClosed
|immutable
|
|-
|fr.cnes.sirius.patrius.math.utils.RecordSegmentSearchIndex
|immutable
|
|-
|fr.cnes.sirius.patrius.math.utils.SearchIndexLibrary
|immutable
|
|}

{| class="wikitable"
|-
! scope="col"| Class (total number : 103)
! scope="col"| Concurrency
! scope="col"| Comment
|-
|fr.cnes.sirius.patrius.attitudes.AttitudeChronologicalComparator
|immutable
|
|-
|fr.cnes.sirius.patrius.attitudes.AttitudeFrame
|not thread safe
|it is a Frame.
|-
|fr.cnes.sirius.patrius.attitudes.AttitudeLawLeg
|conditionally thread-safe
|The use of an AttitudeLaw makes it thread-safe only if the AttitudeLaw is.
|-
|fr.cnes.sirius.patrius.attitudes.AttitudeLegLaw
|conditionally thread-safe
|The use of an AttitudeLegLaw makes it thread-safe only if the two AttitudeLaw and the AttitudeLeg are.
|-
|fr.cnes.sirius.patrius.attitudes.AttitudeLegsSequence
|not thread-safe
|The instances are mutable.
|-
|fr.cnes.sirius.patrius.attitudes.AttitudeTransformProvider
|conditionally thread-safe
|is thread-safe if all attributes are.
|-
|fr.cnes.sirius.patrius.attitudes.ComposedAttitudeLaw
|conditionally thread-safe
|is thread-safe if the AttitudeLaw attribute is.
|-
|fr.cnes.sirius.patrius.attitudes.ConstantSpinSlew
|not thread safe
|this class is not thread safe because the slew can be re-computed while the method getAttitude(PVCoordinatesProvider, AbsoluteDate, Frame) is called.
|-
|fr.cnes.sirius.patrius.attitudes.DirectionTrackingOrientation
|conditionally thread safe
|the IDirection object has to be thread-safe itself
|-
|fr.cnes.sirius.patrius.attitudes.FixedStepAttitudeEphemerisGenerator
|not thread-safe
|The AttitudeLegsSequence attribute is mutable.
|-
|fr.cnes.sirius.patrius.attitudes.OrientationFrame
|not thread safe
|it is a Frame.
|-
|fr.cnes.sirius.patrius.attitudes.OrientationTransformProvider
|conditionally thread-safe
|thread-safe if all attributes are.
|-
|fr.cnes.sirius.patrius.attitudes.RelativeTabulatedAttitudeLaw
|conditionally thread-safe
|The use of an RelativeTabulatedAttitudeLaw makes it thread-safe only if the AttitudeLeglaw is
|-
|fr.cnes.sirius.patrius.attitudes.RelativeTabulatedAttitudeLeg
|immutable
|
|-
|fr.cnes.sirius.patrius.attitudes.SunPointing
|unconditionally thread safe
|
|-
|fr.cnes.sirius.patrius.attitudes.TabulatedAttitude
|immutable
|
|-
|fr.cnes.sirius.patrius.attitudes.TwoDirectionsAttitude
|unconditionally thread safe
|
|-
|fr.cnes.sirius.patrius.attitudes.TwoSpinBiasSlew
|not thread safe
|this class is not thread safe because the local attitude ephemeris is changed.
|-
|fr.cnes.sirius.patrius.attitudes.VariableStepAttitudeEphemerisGenerator
|not thread-safe
|The AttitudeLegsSequence attribute is mutable.
|-
|fr.cnes.sirius.patrius.attitudes.directions.CelestialBodyPolesAxisDirection
|conditionally thread-safe
|this class is thread-safe only if the underlying CelestialBody is too.
|-
|fr.cnes.sirius.patrius.attitudes.directions.CentralBodyCenterDirection
|immutable
|
|-
|fr.cnes.sirius.patrius.attitudes.directions.ConstantVectorDirection
|not thread-safe
|The use of a frame linked to the tree of frames makes this class not thread-safe.
|-
|fr.cnes.sirius.patrius.attitudes.directions.CrossProductDirection
|conditionally thread-safe
|this class is not thread-safe
|-
|fr.cnes.sirius.patrius.attitudes.directions.GenericTargetDirection
|not thread-safe
|Not thread-safe by default.No use case for sharing an instance between threads found.
|-
|fr.cnes.sirius.patrius.attitudes.directions.GlintApproximatePointingDirection
|not thread-safe
|Not thread-safe by default.No use case for sharing an instance between threads found.
|-
|fr.cnes.sirius.patrius.attitudes.directions.GroundVelocityDirection
|conditionally thread-safe
|The use of a celestial body linked to the tree of frames makes this class thread-safe only if the underlying CelestialBody is too.
|-
|fr.cnes.sirius.patrius.attitudes.directions.MomentumDirection
|conditionally thread-safe
|The use of a celestial body linked to the tree of frames makes this class thread-safe only if the underlying CelestialBody is too.
|-
|fr.cnes.sirius.patrius.attitudes.directions.NadirDirection
|conditionally thread-safe
|The use of a celestial body linked to the tree of frames makes this class thread-safe only if the underlying CelestialBody is too.
|-
|fr.cnes.sirius.patrius.attitudes.directions.ToCelestialBodyCenterDirection
|conditionally thread-safe
|The use of a celestial body linked to the tree of frames makes this class thread-safe only if the underlying CelestialBody is too.
|-
|fr.cnes.sirius.patrius.attitudes.directions.VelocityDirection
|not thread-safe
|Not thread-safe by default. No use case for sharing an instance between threads found.
|-
|fr.cnes.sirius.patrius.attitudes.kinematics.SlerpInterpolator
|immutable
|
|-
|fr.cnes.sirius.patrius.bodies.ExtendedOneAxisEllipsoid
|not thread-safe
|the use of frames makes this class not thread-safe
|-
|fr.cnes.sirius.patrius.bodies.MeeusMoon
|immutable
|
|-
|fr.cnes.sirius.patrius.bodies.MeeusSun
|immutable
|
|-
|fr.cnes.sirius.patrius.forces.atmospheres.MSIS2000.ApCoef
|immutable
|
|-
|fr.cnes.sirius.patrius.forces.atmospheres.MSIS2000.Flags
|not thread-safe
|
|-
|fr.cnes.sirius.patrius.forces.atmospheres.MSIS2000.Input
|not thread-safe
|
|-
|fr.cnes.sirius.patrius.forces.atmospheres.MSIS2000.NRLMSISE00
|thread-hostile
|
|-
|fr.cnes.sirius.patrius.forces.atmospheres.MSIS2000.NRLMSISE00Data
|immutable
|
|-
|fr.cnes.sirius.patrius.forces.atmospheres.MSIS2000.Output
|not thread-safe
|
|-
|fr.cnes.sirius.patrius.forces.atmospheres.MSISE2000
|thread-hostile
|The direct use of thread hostile objects makes this class thread hostile itself.
|-
|fr.cnes.sirius.patrius.forces.atmospheres.US76
|thread-hostile
|The direct use of thread hostile objects makes this class thread hostile itself.
|-
|fr.cnes.sirius.patrius.forces.atmospheres.US76Data
|immutable
|
|-
|fr.cnes.sirius.patrius.forces.atmospheres.solarActivity.ACSOLFormatReader
|not thread-safe
|instance is mutable
|-
|fr.cnes.sirius.patrius.forces.atmospheres.solarActivity.ConstantSolarActivity
|immutable
|
|-
|fr.cnes.sirius.patrius.forces.atmospheres.solarActivity.NOAAFormatReader
|not thread-safe
|instance is mutable
|-
|fr.cnes.sirius.patrius.forces.atmospheres.solarActivity.SolarActivityDataFactory
|thread-hostile
|uses {@link DataProvidersManager} which is thread hostile
|-
|fr.cnes.sirius.patrius.forces.atmospheres.solarActivity.SolarActivityToolbox
|immutable
|
|-
|fr.cnes.sirius.patrius.forces.atmospheres.solarActivity.specialized.ClassicalMSISE2000SolarData
|conditionally thread-safe
|thread-safe if SolarActivityDataProvider is thread-safe
|-
|fr.cnes.sirius.patrius.forces.atmospheres.solarActivity.specialized.ContinuousMSISE2000SolarData
|conditionally thread-safe
|thread-safe if SolarActivityDataProvider is thread-safe
|-
|fr.cnes.sirius.patrius.forces.atmospheres.solarActivity.specialized.DTM2000SolarData
|conditionally thread-safe
|thread-safe if SolarActivityDataProvider is thread-safe
|-
|fr.cnes.sirius.patrius.forces.gravity.EarthGravitationalModelFactory
|not thread-safe
|the presence of static methods makes this class not thread-safe
|-
|fr.cnes.sirius.patrius.forces.gravity.tides.OceanTides
|not thread-safe
|not thread safe because of the method updateCoefficientsCandS().
|-
|fr.cnes.sirius.patrius.forces.gravity.tides.OceanTidesDataProvider
|immutable
|
|-
|fr.cnes.sirius.patrius.forces.gravity.tides.OceanTidesWaves
|immutable
|
|-
|fr.cnes.sirius.patrius.forces.gravity.tides.TerrestrialTides
|not thread-safe
|not thread safe because of the method updateCoefficientsCandS().
|-
|fr.cnes.sirius.patrius.forces.gravity.tides.TerrestrialTidesDataProvider
|thread safe
|
|-
|fr.cnes.sirius.patrius.forces.gravity.tides.TidesStandards
|immutable
|
|-
|fr.cnes.sirius.patrius.forces.gravity.tides.TidesToolbox
|immutable
|
|-
|fr.cnes.sirius.patrius.forces.gravity.tides.coefficients.FES2004FormatReader
|not thread-safe
|instance is mutable
|-
|fr.cnes.sirius.patrius.forces.gravity.tides.coefficients.OceanTidesCoefficientsFactory
|thread-hostile
|uses a thread-hostile DataProvidersManager
|-
|fr.cnes.sirius.patrius.forces.gravity.tides.coefficients.OceanTidesCoefficientsSet
|immutable
|
|-
|fr.cnes.sirius.patrius.forces.gravity.variations.VariablePotentialAttractionModel
|not thread-safe
|not thread-safe because of global arrays
|-
|fr.cnes.sirius.patrius.forces.gravity.variations.coefficients.GRGSRL02FormatReader
|not thread-safe
|because of static fields
|-
|fr.cnes.sirius.patrius.forces.gravity.variations.coefficients.VariableGravityFieldFactory
|not thread-safe
|because of static fields
|-
|fr.cnes.sirius.patrius.forces.gravity.variations.coefficients.VariablePotentialCoefficientsSet
|immutable
|
|-
|fr.cnes.sirius.patrius.forces.maneuvers.ConstantThrustError
|not thread-safe
|internal mutable attributes
|-
|fr.cnes.sirius.patrius.forces.maneuvers.VariableThrustManeuver
|not thread-safe
|internal mutable attributes
|-
|fr.cnes.sirius.patrius.forces.radiation.ElementaryFlux
|immutable
|immutable class
|-
|fr.cnes.sirius.patrius.forces.radiation.KnockeRiesModel
|immutable
|
|-
|fr.cnes.sirius.patrius.forces.radiation.RediffusedFlux
|conditionally thread-safe
|thread-safe if all constructor parameters are too.
|-
|fr.cnes.sirius.patrius.forces.radiation.RediffusedRadiationPressure
|conditionally thread-safe
|thread-safe if the CelestialBody attribute is.
|-
|fr.cnes.sirius.patrius.propagation.analytical.covariance.CovarianceInterpolation
|not thread-safe
|internal mutable attributes
|-
|fr.cnes.sirius.patrius.propagation.analytical.covariance.OrbitCovariance
|immutable
|
|-
|fr.cnes.sirius.patrius.propagation.analytical.twod.Analytical2DOrbitModel
|conditionally thread-safe
|thread safe if the underlying Analytical2DParameterModel andAbsoluteDate objects are thread safe
|-
|fr.cnes.sirius.patrius.propagation.analytical.twod.Analytical2DParameterModel
|immutable
|
|-
|fr.cnes.sirius.patrius.propagation.analytical.twod.Analytical2DPropagator
|not thread-safe
|extends the AbstractPropagator class
|-
|fr.cnes.sirius.patrius.propagation.analytical.twod.DateIntervalLinearFunction
|thread-safe
|
|-
|fr.cnes.sirius.patrius.propagation.analytical.twod.DateIntervalParabolicFunction
|thread-safe
|
|-
|fr.cnes.sirius.patrius.propagation.analytical.twod.DatePolynomialFunction
|thread-safe
|
|-
|fr.cnes.sirius.patrius.propagation.events.AOLDetector
|not thread-safe
|attributes are mutable and related to propagation.
|-
|fr.cnes.sirius.patrius.propagation.events.AnomalyDetector
|not thread-safe
|attributes are mutable and related to propagation.
|-
|fr.cnes.sirius.patrius.propagation.events.BetaAngleDetector
|not thread-safe
|attributes are mutable and related to propagation.
|-
|fr.cnes.sirius.patrius.propagation.events.DistanceDetector
|not thread-safe
|attributes are mutable and related to propagation.
|-
|fr.cnes.sirius.patrius.propagation.events.ExtremaDistanceDetector
|not thread-safe
|attributes are mutable and related to propagation.
|-
|fr.cnes.sirius.patrius.propagation.events.ExtremaElevationDetector
|not thread-safe
|the link to the tree of frames makes this class not thread-safe
|-
|fr.cnes.sirius.patrius.propagation.events.ExtremaLatitudeDetector
|not thread-safe
|attributes are mutable and related to propagation.
|-
|fr.cnes.sirius.patrius.propagation.events.ExtremaLongitudeDetector
|not thread-safe
|attributes are mutable and related to propagation.
|-
|fr.cnes.sirius.patrius.propagation.events.ExtremaThreeBodiesAngleDetector
|not thread-safe
|attributes are mutable and related to propagation.
|-
|fr.cnes.sirius.patrius.propagation.events.LatitudeDetector
|not thread-safe
|attributes are mutable and related to propagation.
|-
|fr.cnes.sirius.patrius.propagation.events.LocalTimeDetector
|not thread-safe
|attributes are mutable and related to propagation.
|-
|fr.cnes.sirius.patrius.propagation.events.LongitudeDetector
|not thread-safe
|attributes are mutable and related to propagation.
|-
|fr.cnes.sirius.patrius.propagation.events.NadirSolarIncidenceDetector
|thread-hostile
|the earth celestial body is thread hostile itself.
|-
|fr.cnes.sirius.patrius.propagation.events.NthOccurrenceDetector
|not thread-safe
|use of internal mutable attributes
|-
|fr.cnes.sirius.patrius.propagation.events.SolarTimeDetector
|not thread-safe
|attributes are mutable and related to propagation.
|-
|fr.cnes.sirius.patrius.propagation.events.ThreeBodiesAngleDetector
|not thread-safe
|attributes are mutable and related to propagation.
|-
|fr.cnes.sirius.patrius.propagation.precomputed.HermiteEphemeris
|not thread-safe
|internal mutable attributes
|-
|fr.cnes.sirius.patrius.propagation.precomputed.LagrangeEphemeris
|not thread-safe
|instances are mutable
|-
|fr.cnes.sirius.patrius.time.LocalTime
|not thread-safe
|
|-
|fr.cnes.sirius.patrius.utils.AbsoluteDateIntervalsList
|not thread-safe
|thread safety is not required for this class. And, TreeSet is not thread-safe.
|-
|fr.cnes.sirius.patrius.utils.EphemerisPvHermite
|not thread-safe
|internal mutable attributes
|-
|fr.cnes.sirius.patrius.utils.EphemerisPvLagrange
|not thread-safe
|internal mutable attributes
|-
|fr.cnes.sirius.patrius.utils.ReferencePointsDisplacement
|conditionally thread-safe
|is thread-safe if the celestial body is too.
|}

{| class="wikitable"
|-
! scope="col"| Class (total number : 162)
! scope="col"| Concurrency
! scope="col"| Comment
|-
|fr.cnes.sirius.patrius.utils.UtilsPatrius
|immutable
|
|-
|fr.cnes.sirius.patrius.assembly.Assembly
|not thread-safe
|The use of a frame linked to the tree of frames in each of the parts makes this class not thread-safe.
|-
|fr.cnes.sirius.patrius.assembly.AssemblyBuilder
|not thread-safe
|The assembly is not thread-safe itself
|-
|fr.cnes.sirius.patrius.assembly.MainPart
|not thread-safe
|The use of a frame linked to the tree of frames makes this class not thread-safe.
|-
|fr.cnes.sirius.patrius.assembly.Part
|not thread-safe
|The use of a frame linked to the tree of frames makes this class not thread-safe.
|-
|fr.cnes.sirius.patrius.assembly.models.AeroModel
|not thread-safe
|The use of a frame (Assembly attribute) linked to the tree of frames in each of the parts makes this class not thread-safe.
|-
|fr.cnes.sirius.patrius.assembly.models.AeroWrenchModel
|not thread-safe
|class uses internal mutable attributes and frames
|-
|fr.cnes.sirius.patrius.assembly.models.DirectRadiativeModel
|not thread-safe
|The use of a frame (Assembly attribute) linked to the tree of frames in each of the parts makes this class not thread-safe.
|-
|fr.cnes.sirius.patrius.assembly.models.DirectRadiativeWrenchModel
|not thread-safe
|class uses internal mutable attributes and frames
|-
|fr.cnes.sirius.patrius.assembly.models.DragLiftModel
|not thread-safe
|The use of a frame (Assembly attribute) linked to the tree of frames in each of the parts makes this class not thread-safe.
|-
|fr.cnes.sirius.patrius.assembly.models.InertiaComputedModel
|not thread-safe
|the direct use of a not thread-safe Assembly makes this class not thread-safe itself
|-
|fr.cnes.sirius.patrius.assembly.models.InertiaSimpleModel
|not thread-safe
|the frame and setters makes this class not thread-safe
|-
|fr.cnes.sirius.patrius.assembly.models.MagneticMoment
|conditionally thread-safe
|thread-safe if the underlying frame is thread-safe
|-
|fr.cnes.sirius.patrius.assembly.models.MassModel
|not thread-safe
|uses internal mutable attributes
|-
|fr.cnes.sirius.patrius.assembly.models.RFLinkBudgetModel
|immutable
|
|-
|fr.cnes.sirius.patrius.assembly.models.RediffusedRadiativeModel
|not thread-safe
|The use of a frame (Assembly attribute) linked to the treeof frames in each of the parts makes this class not thread-safe.
|-
|fr.cnes.sirius.patrius.assembly.models.SensorModel
|not thread-safe
|the direct use of a not thread-safe Assembly makes this classnot thread-safe itself
|-
|fr.cnes.sirius.patrius.assembly.properties.AeroApplicationPoint
|immutable
|
|-
|fr.cnes.sirius.patrius.assembly.properties.AeroFacetProperty
|immutable
|
|-
|fr.cnes.sirius.patrius.assembly.properties.AeroGlobalProperty
|immutable
|
|-
|fr.cnes.sirius.patrius.assembly.properties.AeroSphereProperty
|immutable
|
|-
|fr.cnes.sirius.patrius.assembly.properties.CrossSectionProviderProperty
|conditionally thread-safe
|the CrossSectionProvider object must be immutable. In this case, thisclass is immutable itself and thus, is not subject to thread safety tests.
|-
|fr.cnes.sirius.patrius.assembly.properties.GeometricProperty
|conditionally thread-safe
|the SolidShape object must be immutable. In this case, thisclass is immutable itself and thus, is not subject to thread safety tests.
|-
|fr.cnes.sirius.patrius.assembly.properties.InertiaCylinderProperty
|not thread-safe
|the use of frames makes this class not thread-safe
|-
|fr.cnes.sirius.patrius.assembly.properties.InertiaParallelepipedProperty
|not thread-safe
|the use of frames makes this class not thread-safe
|-
|fr.cnes.sirius.patrius.assembly.properties.InertiaSimpleProperty
|not thread-safe
|the use of frames makes this class not thread-safe
|-
|fr.cnes.sirius.patrius.assembly.properties.InertiaSphereProperty
|not thread-safe
|the use of frames makes this class not thread-safe
|-
|fr.cnes.sirius.patrius.assembly.properties.MassEquation
|not thread-safe
|internal mutable attributes
|-
|fr.cnes.sirius.patrius.assembly.properties.MassProperty
|immutable
|
|-
|fr.cnes.sirius.patrius.assembly.properties.RFAntennaProperty
|immutable
|
|-
|fr.cnes.sirius.patrius.assembly.properties.RadiativeApplicationPoint
|immutable
|
|-
|fr.cnes.sirius.patrius.assembly.properties.RadiativeFacetProperty
|immutable
|
|-
|fr.cnes.sirius.patrius.assembly.properties.RadiativeIRProperty
|immutable
|
|-
|fr.cnes.sirius.patrius.assembly.properties.RadiativeProperty
|immutable
|
|-
|fr.cnes.sirius.patrius.assembly.properties.RadiativeSphereProperty
|immutable
|
|-
|fr.cnes.sirius.patrius.assembly.properties.SensorProperty
|not thread-safe
|
|-
|fr.cnes.sirius.patrius.assembly.properties.features.Facet
|immutable
|
|-
|fr.cnes.sirius.patrius.bodies.BasicBoardSun
|immutable
|
|-
|fr.cnes.sirius.patrius.events.CentralBodyMaskCircularFOVDetector
|not thread-safe
|one attribute not thread-safe and one conditionally thread-safe
|-
|fr.cnes.sirius.patrius.events.CodedEvent
|immutable
|
|-
|fr.cnes.sirius.patrius.events.CodedEventsList
|not thread-safe
|no thread-sharing use case was identified for this class, so thread safety is not required. Though, some precautions are taken, as an example, the method getList() returns a copy of the list and not directly the attribute list itself.
|-
|fr.cnes.sirius.patrius.events.CodedEventsLogger
|not thread-safe
|no thread-sharing use case was identified for this class, so thread safety is not required.
|-
|fr.cnes.sirius.patrius.events.CombinedPhenomenaDetector
|not thread-safe or thread-hostile
|As of now, existing EventDetector implementations are either not thread-safe or thread-hostile, so this class also is. But this class could probably become conditionally thread-safe, the main thread safety condition would then be that the included EventDetector should be thread-safe.
|-
|fr.cnes.sirius.patrius.events.EarthZoneDetector
|not thread-safe
|attributes are mutable and related to propagation.
|-
|fr.cnes.sirius.patrius.events.GenericCodingEventDetector
|not thread-safe or thread-hostile
|As of now, existing EventDetector implementations are either not thread-safe or thread-hostile, so this class also is. But this class could probably become conditionally thread-safe, the main thread safety condition would then be that the included EventDetector should be thread-safe.
|-
|fr.cnes.sirius.patrius.events.PhenomenaList
|not thread-safe
|no thread-sharing use case was identified for this class, so thread safety is not required. Though, some precautions are taken, as an example, the method getList() returns a copy of the list and not directly the attribute list itself.
|-
|fr.cnes.sirius.patrius.events.Phenomenon
|immutable
|
|-
|fr.cnes.sirius.patrius.events.multi.MultiCodedEventsLogger
|not thread-safe
|no thread-sharing use case was identified for this class, so thread safety is not required.
|-
|fr.cnes.sirius.patrius.events.multi.MultiEventsLogger
|not thread-safe
|
|-
|fr.cnes.sirius.patrius.events.multi.MultiGenericCodingEventDetector
|not thread-safe or thread-hostile
|As of now, existing MultiEventDetector implementations are either not thread-safe or thread-hostile, so this class also is. But this class could probably become conditionally thread-safe, the main thread safety condition would then be that the included MultiEventDetector should be thread-safe.
|-
|fr.cnes.sirius.patrius.events.postprocessing.AndCriterion
|immutable
|
|-
|fr.cnes.sirius.patrius.events.postprocessing.DelayCriterion
|immutable
|
|-
|fr.cnes.sirius.patrius.events.postprocessing.ElementTypeFilter
|immutable
|
|-
|fr.cnes.sirius.patrius.events.postprocessing.EventsDuringPhenomenaFilter
|immutable
|
|-
|fr.cnes.sirius.patrius.events.postprocessing.MergePhenomenaCriterion
|immutable
|
|-
|fr.cnes.sirius.patrius.events.postprocessing.MergeTimelines
|immutable
|
|-
|fr.cnes.sirius.patrius.events.postprocessing.OccurrenceFilter
|immutable
|
|-
|fr.cnes.sirius.patrius.events.postprocessing.OrCriterion
|immutable
|
|-
|fr.cnes.sirius.patrius.events.postprocessing.PhenomenonDurationFilter
|immutable
|
|-
|fr.cnes.sirius.patrius.events.postprocessing.PolarizationSingleSelection
|immutable
|
|-
|fr.cnes.sirius.patrius.events.postprocessing.PolarizationSwitch
|immutable
|
|-
|fr.cnes.sirius.patrius.events.postprocessing.TimeFilter
|immutable
|
|-
|fr.cnes.sirius.patrius.events.postprocessing.Timeline
|not thread-safe
|the timeline is not thread safe due to the methods removeCodedEvent(CodedEvent) and removePhenomenon(Phenomenon)
|-
|fr.cnes.sirius.patrius.events.sensor.ExtremaSightAxisDetector
|not thread-safe
|attributes are mutable and related to propagation, and the direct use of a not thread-safe Assembly makes this class not thread-safe itself
|-
|fr.cnes.sirius.patrius.events.sensor.MaskingDetector
|not thread-safe
|The use of a not thread-safe SensorModel makes this class not thread-safe.
|-
|fr.cnes.sirius.patrius.events.sensor.RFVisibilityDetector
|not thread-safe
|the direct use of a not thread-safe Assembly makes this classnot thread-safe itself
|-
|fr.cnes.sirius.patrius.events.sensor.SatToSatMutualVisibilityDetector
|not thread-safe
|the direct use of a not thread-safe Assembly makes this class not thread-safe itself
|-
|fr.cnes.sirius.patrius.events.sensor.SecondarySpacecraft
|not thread-safe
|the direct use of a not thread-safe Assembly makes this classnot thread-safe itself
|-
|fr.cnes.sirius.patrius.events.sensor.SensorInhibitionDetector
|not thread-safe
|the direct use of a not thread-safe Assembly makes this classnot thread-safe itself
|-
|fr.cnes.sirius.patrius.events.sensor.SensorVisibilityDetector
|not thread-safe
|the direct use of a not thread-safe Assembly makes this classnot thread-safe itself
|-
|fr.cnes.sirius.patrius.events.sensor.StationToSatMutualVisibilityDetector
|not thread-safe
|the direct use of a not thread-safe Assembly makes this classnot thread-safe itself
|-
|fr.cnes.sirius.patrius.events.sensor.TargetInFieldOfViewDetector
|not thread-safe
|the direct use of a not thread-safe Assembly makes this classnot thread-safe itself
|-
|fr.cnes.sirius.patrius.events.sensor.VisibilityFromStationDetector
|not thread-safe
|the direct use of a not thread-safe Assembly makes this classnot thread-safe itself
|-
|fr.cnes.sirius.patrius.fieldsofview.AzimuthElevationField
|immutable
|
|-
|fr.cnes.sirius.patrius.fieldsofview.BooleanField
|conditionally thread-safe
|the used fields must be thread-safe themselves.All available fields are immutable.
|-
|fr.cnes.sirius.patrius.fieldsofview.CircularField
|immutable
|
|-
|fr.cnes.sirius.patrius.fieldsofview.EllipticField
|immutable
|
|-
|fr.cnes.sirius.patrius.fieldsofview.FieldAngularFace
|immutable
|
|-
|fr.cnes.sirius.patrius.fieldsofview.InvertField
|conditionally thread-safe
|the used field must be thread-safe itself.All available fields are immutable.
|-
|fr.cnes.sirius.patrius.fieldsofview.OmnidirectionalField
|immutable
|
|-
|fr.cnes.sirius.patrius.fieldsofview.PyramidalField
|immutable
|
|-
|fr.cnes.sirius.patrius.fieldsofview.RectangleField
|immutable
|
|-
|fr.cnes.sirius.patrius.fieldsofview.SectorField
|immutable
|
|-
|fr.cnes.sirius.patrius.forces.EmpiricalForce
|not thread-safe
|attributes are mutable
|-
|fr.cnes.sirius.patrius.forces.maneuvers.ManeuversSequence
|not thread-safe
|The instances are mutable.
|-
|fr.cnes.sirius.patrius.forces.radiation.SolarRadiationPressureEllipsoidCircular
|not thread-safe
|fields use Frames
|-
|fr.cnes.sirius.patrius.groundstation.GeometricStationAntenna
|not thread-safe
|link to the tree of frames
|-
|fr.cnes.sirius.patrius.groundstation.RFStationAntenna
|not thread-safe
|link to the tree of frames
|-
|fr.cnes.sirius.patrius.guidance.AngularVelocitiesHarmonicProfile
|conditionally thread-safe
|thread-safe if the Frame attribute is thread-safe.
|-
|fr.cnes.sirius.patrius.guidance.AngularVelocitiesPolynomialProfile
|conditionally thread-safe
|thread-safe if the attributes are thread-safe
|-
|fr.cnes.sirius.patrius.guidance.GuidanceProfileBuilder
|immutable
|
|-
|fr.cnes.sirius.patrius.guidance.QuaternionHarmonicProfile
|conditionally thread-safe
|thread-safe if the Frame attribute is thread-safe.
|-
|fr.cnes.sirius.patrius.guidance.QuaternionPolynomialProfile
|conditionally thread-safe
|thread-safe if the attributes are thread-safe
|-
|fr.cnes.sirius.patrius.guidance.QuaternionPolynomialSegment
|conditionally thread-safe
|thread-safe if the UnivariateFunction attributes are thread-safe
|-
|fr.cnes.sirius.patrius.guidance.Vector3DPolynomialSegment
|conditionally thread-safe
|thread-safe if the UnivariateFunction attributes are thread-safe
|-
|fr.cnes.sirius.patrius.propagation.PVCoordinatePropagator
|not thread-safe
|extends the AbstractPropagator class
|-
|fr.cnes.sirius.patrius.propagation.SimpleAdditionalStateProvider
|immutable
|
|-
|fr.cnes.sirius.patrius.propagation.events.multi.AdaptedMonoEventDetector
|conditionally thread-safe
|Conditionally thread-safe if all attributes are thread-safe
|-
|fr.cnes.sirius.patrius.propagation.events.multi.AdaptedMultiEventDetector
|conditionally thread-safe
|Conditionally thread-safe if all attributes are thread-safe
|-
|fr.cnes.sirius.patrius.propagation.events.multi.OneSatEventDetectorWrapper
|not thread-safe
|
|-
|fr.cnes.sirius.patrius.propagation.numerical.multi.MultiEphemerisModeHandler
|not thread-safe
|
|-
|fr.cnes.sirius.patrius.propagation.numerical.multi.MultiNumericalPropagator
|not thread-safe
|attributes are mutable and related to propagation.
|-
|fr.cnes.sirius.patrius.propagation.numerical.multi.MultiStateVectorInfo
|immutable
|
|-
|fr.cnes.sirius.patrius.propagation.precomputed.multi.MultiIntegratedEphemeris
|immutable
|
|-
|fr.cnes.sirius.patrius.propagation.sampling.multi.MultiAdaptedStepHandler
|not thread-safe
|
|-
|fr.cnes.sirius.patrius.propagation.sampling.multi.MultiPatriusStepNormalizer
|not thread-safe
|
|-
|fr.cnes.sirius.patrius.signalpropagation.AzoulayModel
|immutable
|
|-
|fr.cnes.sirius.patrius.signalpropagation.SignalPropagation
|not thread-safe
|use of the frames tree
|-
|fr.cnes.sirius.patrius.signalpropagation.SignalPropagationModel
|not thread-safe
|use of the frames tree
|-
|fr.cnes.sirius.patrius.signalpropagation.iono.BentModel
|thread-safe
| with the use of a synchronized tag
|-
|fr.cnes.sirius.patrius.signalpropagation.iono.R12Loader
|conditionally thread-safe
|the instance is mutable, but no longer changes after the first call to getR12() (the first call triggers the DataProvidersManager on the instance). This means : an instance can be shared and used in several threads, if getR12() is called once in a single thread context first.
|-
|fr.cnes.sirius.patrius.signalpropagation.iono.USKData
|immutable
|
|-
|fr.cnes.sirius.patrius.signalpropagation.iono.USKLoader
|conditionally thread-safe
|the instance is mutable, but no longer changes after the first call to getData() (the first call triggers the DataProvidersManager on the instance). This means : an instance can be shared and used in several threads, if getData() is called once in a single thread context first.
|-
|fr.cnes.sirius.patrius.stela.JavaMathAdapter
|unconditionally thread-safe
|
|-
|fr.cnes.sirius.patrius.stela.PerigeeAltitudeDetector
|conditionally thread-safe
|the OrbitNatureConverter attribute needs to be thread-safe
|-
|fr.cnes.sirius.patrius.stela.StelaSpacecraftFactory
|unconditionally thread-safe
|access to the only static field is synchronized
|-
|fr.cnes.sirius.patrius.stela.bodies.EarthRotation
|immutable
|
|-
|fr.cnes.sirius.patrius.stela.bodies.GeodPosition
|immutable
|
|-
|fr.cnes.sirius.patrius.stela.bodies.MeeusMoonStela
|immutable
|
|-
|fr.cnes.sirius.patrius.stela.bodies.MeeusSunStela
|immutable
|
|-
|fr.cnes.sirius.patrius.stela.forces.Squaring
|immutable
|
|-
|fr.cnes.sirius.patrius.stela.forces.StelaLagrangeEquations
|not thread-safe
|not thread-safe because two threads can simultaneously modify global attributes of the class
|-
|fr.cnes.sirius.patrius.stela.forces.atmospheres.MSIS00Adapter
|thread-hostile
|The direct use of thread hostile objects makes this class thread hostile itself.
|-
|fr.cnes.sirius.patrius.stela.forces.drag.StelaAeroModel
|immutable
|
|-
|fr.cnes.sirius.patrius.stela.forces.drag.StelaAtmosphericDrag
|not thread-safe
|not thread-safe due to use of mutable attributes
|-
|fr.cnes.sirius.patrius.stela.forces.drag.StelaCd
|immutable
|
|-
|fr.cnes.sirius.patrius.stela.forces.gravity.StelaTesseralAttraction
|not thread-safe
|not thread-safe due to use of mutable attributes
|-
|fr.cnes.sirius.patrius.stela.forces.gravity.StelaThirdBodyAttraction
|not thread-safe
|not thread-safe because two threads can simultaneously modify attributes of the class
|-
|fr.cnes.sirius.patrius.stela.forces.gravity.StelaZonalAttraction
|conditionally thread-safe
|thread safe if the PotentialCoefficientsProvider used is thread safe
|-
|fr.cnes.sirius.patrius.stela.forces.gravity.StelaZonalAttractionJ10
|thread-safe
|
|-
|fr.cnes.sirius.patrius.stela.forces.gravity.StelaZonalAttractionJ11
|thread-safe
|
|-
|fr.cnes.sirius.patrius.stela.forces.gravity.StelaZonalAttractionJ12
|thread-safe
|
|-
|fr.cnes.sirius.patrius.stela.forces.gravity.StelaZonalAttractionJ13
|thread-safe
|
|-
|fr.cnes.sirius.patrius.stela.forces.gravity.StelaZonalAttractionJ14
|thread-safe
|
|-
|fr.cnes.sirius.patrius.stela.forces.gravity.StelaZonalAttractionJ15
|thread-safe
|
|-
|fr.cnes.sirius.patrius.stela.forces.gravity.StelaZonalAttractionJ8
|thread-safe
|
|-
|fr.cnes.sirius.patrius.stela.forces.gravity.StelaZonalAttractionJ9
|thread-safe
|
|-
|fr.cnes.sirius.patrius.stela.forces.gravity.TesseralQuad
|not thread-safe
|use of internal mutable attributes
|-
|fr.cnes.sirius.patrius.stela.forces.noninertial.NonInertialContribution
|thread-safe
|
|-
|fr.cnes.sirius.patrius.stela.forces.radiation.SRPPotential
|conditionally thread-safe
|thread safe if the CelestialBody used is thread safe
|-
|fr.cnes.sirius.patrius.stela.forces.radiation.SRPSquaring
|conditionally thread-safe
|thread-safe if the given sun is thread-safe
|-
|fr.cnes.sirius.patrius.stela.forces.radiation.StelaSRPSquaring
|conditionally thread-safe
|thread-safe if the SRPSquaring and SRPPotential models are thread-safe.
|-
|fr.cnes.sirius.patrius.stela.orbits.JacobianConverter
|unconditionally thread-safe
|
|-
|fr.cnes.sirius.patrius.stela.orbits.OrbitNatureConverter
|not thread-safe
|instances are mutable
|-
|fr.cnes.sirius.patrius.stela.orbits.StelaEquinoctialOrbit
|immutable
|
|-
|fr.cnes.sirius.patrius.stela.propagation.ForcesStepHandler
|not thread-safe
|
|-
|fr.cnes.sirius.patrius.stela.propagation.StelaBasicInterpolator
|not thread-safe
|
|-
|fr.cnes.sirius.patrius.stela.propagation.StelaDifferentialEquations
|not thread-safe
|not thread-safe due to use of mutable attributes
|-
|fr.cnes.sirius.patrius.stela.propagation.StelaGTOPropagator
|not thread-safe
|use of mutable attributes
|-
|fr.cnes.sirius.patrius.stela.propagation.StelaPartialDerivativesEquations
|not thread-safe
|use of mutable attributes
|-
|fr.cnes.sirius.patrius.stela.propagation.data.TimeDerivativeData
|not thread-safe
|
|-
|fr.cnes.sirius.patrius.orbits.pvcoordinates.AlmanacPVCoordinates
|immutable
|
|-
|fr.cnes.sirius.patrius.math.interval.AngleInterval
|immutable
|
|-
|fr.cnes.sirius.patrius.math.interval.AngleTools
|unconditionally thread-safe
|
|-
|fr.cnes.sirius.patrius.math.Comparators
|unconditionally thread-safe
|
|-
|fr.cnes.sirius.patrius.utils.GPSGalileoAlmanacParameter
|immutable
|
|-
|fr.cnes.sirius.patrius.math.interval.GenericInterval
|immutable
|
|-
|fr.cnes.sirius.patrius.wrenches.DragWrench
|not thread-safe
|class uses internal mutable attributes and frames
|-
|fr.cnes.sirius.patrius.wrenches.GenericWrenchModel
|not thread-safe
|uses frames
|-
|fr.cnes.sirius.patrius.wrenches.GravitationalAttractionWrench
|conditionally thread-safe
|thread-safe if the inertia model is thread-safe
|-
|fr.cnes.sirius.patrius.wrenches.MagneticWrench
|conditionally thread-safe
|thread-safe if the underlying geo magnetic field is also thread-safe
|-
|fr.cnes.sirius.patrius.wrenches.SolarRadiationWrench
|not thread-safe
|class uses internal mutable attributes and frames
|}

=== Patrius-tools thread safety ===

Here is a list of all patrius-tools classes and thread-safety:

{| class="wikitable"
|-
! scope="col"| Class (total number : 23)
! scope="col"| Concurrency
! scope="col"| Comment
|-
|fr.cnes.sirius.patrius.tools.ephemerisComparator.ComparisonData
|not thread-safe
|this class is not thread safe due to setThresholds(ArrayList)
|-
|fr.cnes.sirius.patrius.tools.ephemerisComparator.Data
|not thread-safe
|matches the concurrency of the parameter type : using an immutable type is HIGHLY recommended
|-
|fr.cnes.sirius.patrius.tools.ephemerisComparator.DateDPFacade
|immutable
|
|-
|fr.cnes.sirius.patrius.tools.ephemerisComparator.DeviationProviderFactory
|immutable
|
|-
|fr.cnes.sirius.patrius.tools.ephemerisComparator.DoubleDPFacade
|immutable
|
|-
|fr.cnes.sirius.patrius.tools.ephemerisComparator.EphemerisComparator
|not thread-safe
|it uses non thread-safe objects
|-
|fr.cnes.sirius.patrius.tools.ephemerisComparator.EphemerisComparatorMain
|not thread-safe
|it uses non thread-safe objects
|-
|fr.cnes.sirius.patrius.tools.ephemerisComparator.MeaningfulData
|immutable
|
|-
|fr.cnes.sirius.patrius.tools.ephemerisComparator.MeaningfulDataComparator
|immutable
|
|-
|fr.cnes.sirius.patrius.tools.ephemerisComparator.PSimuDataLoader
|not thread-safe
|the file could be tampered with while reading it
|-
|fr.cnes.sirius.patrius.tools.ephemerisComparator.PVCoordinatesDPFacade
|immutable
|
|-
|fr.cnes.sirius.patrius.tools.ephemerisComparator.QuaternionDPFacade
|immutable
|
|-
|fr.cnes.sirius.patrius.tools.ephemerisComparator.RawDataComparator
|not thread-safe
|this class is not thread safe due to the attribute 'relative' which can change
|-
|fr.cnes.sirius.patrius.tools.ephemerisComparator.Report
|thread-safe
|
|-
|fr.cnes.sirius.patrius.tools.ephemerisComparator.RotationDPFacade
|immutable
|
|-
|fr.cnes.sirius.patrius.tools.ephemerisComparator.Setup
|not thread-safe
|this class is not thread safe due to the fact that some attributes are not private
|-
|fr.cnes.sirius.patrius.tools.ephemerisComparator.ThresholdsData
|not thread-safe
|this class is not thread safe due to getFirstRefusedLines()
|-
|fr.cnes.sirius.patrius.tools.ephemerisComparator.VectorDPFacade
|immutable
|
|-
|fr.cnes.sirius.patrius.tools.exception.EphemerisComparatorException
|not thread-safe
|extends Exception
|-
|fr.cnes.sirius.patrius.tools.exception.EphemerisComparatorRuntimeException
|not thread-safe
|extends Exception
|-
|fr.cnes.sirius.patrius.tools.force.validation.BasicPVCoordinatesProvider
|not thread-safe
|
|-
|fr.cnes.sirius.patrius.tools.force.validation.PVEphemerisLoader
|not thread safe
|
|-
|fr.cnes.sirius.patrius.tools.force.validation.Report
|not thread safe
|
|}

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Concurrency
! scope="col"| Comment
|-
|fr.cnes.sirius.patrius.math.analysis.integration.TrapezoidIntegrator
|not thread-safe
|Instances are mutable.
|-
|fr.cnes.sirius.patrius.math.analysis.integration.SimpsonIntegrator
|not thread-safe
|Instances are mutable.
|-
|fr.cnes.sirius.patrius.math.analysis.interpolation.BicubicSplineInterpolatingFunction
|not thread-safe
|Instances are mutable (unprotected lazy initialization).
|-
|fr.cnes.sirius.patrius.math.analysis.interpolation.BicubicSplineInterpolator
|unconditionally thread-safe
|Would be immutable if the class were final.
|-
|fr.cnes.sirius.patrius.math.analysis.interpolation.TricubicSplineInterpolatingFunction
|unconditionally thread-safe
|Would be immutable if the class were final.
|-
|fr.cnes.sirius.patrius.math.analysis.interpolation.TricubicSplineInterpolator
|unconditionally thread-safe
|Would be immutable if the class were final.
|-
|fr.cnes.sirius.patrius.math.analysis.polynomials.PolynomialFunction
|unconditionally thread-safe
|Would be immutable if the class were final- documented as immutable, but technically untrue.
|-
|fr.cnes.sirius.patrius.math.analysis.polynomials.PolynomialFunctionLagrangeForm
|not thread-safe
|Instances are mutable (unprotected lazy initialization).
|-
|fr.cnes.sirius.patrius.math.analysis.polynomials.PolynomialFunctionNewtonForm
|not thread-safe
|Instances are mutable (unprotected lazy initialization).
|-
|fr.cnes.sirius.patrius.math.analysis.polynomials.HelmholtzPolynomial
|not thread-safe
|Instances are mutable.
|-
|fr.cnes.sirius.patrius.math.analysis.solvers.BrentSolver
|not thread-safe
|Instances are mutable (inner Incrementor instance).
|-
|fr.cnes.sirius.patrius.math.analysis.solvers.NewtonSolver
|not thread-safe
|Instances are mutable (inner Incrementor instance).
|-
|fr.cnes.sirius.patrius.math.analysis.solvers.BisectionSolver
|not thread-safe
|Instances are mutable (inner Incrementor instance).
|-
|fr.cnes.sirius.patrius.math.analysis.solvers.MullerSolver
|not thread-safe
|Instances are mutable (inner Incrementor instance).
|-
|fr.cnes.sirius.patrius.math.geometry.euclidean.threed.Plane
|not thread-safe
|Instances are mutable.
|-
|fr.cnes.sirius.patrius.math.geometry.euclidean.threed.Rotation
|unconditionally thread-safe
|Would be immutable if the class were final- documented as immutable, but technically untrue.
|-
|fr.cnes.sirius.patrius.math.geometry.euclidean.threed.RotationOrder
|immutable
|
|-
|fr.cnes.sirius.patrius.math.geometry.euclidean.threed.Vector3D
|unconditionally thread-safe
|Would be immutable if the class were final- documented as immutable, but technically untrue.
|-
|fr.cnes.sirius.patrius.math.geometry.euclidean.threed.Screw
|unconditionally thread-safe
|Would be immutable if the class were final- documented as immutable, but technically untrue.
|-
|fr.cnes.sirius.patrius.math.linear.Array2DRowRealMatrix
|not thread-safe
|Instances are mutable.
|-
|fr.cnes.sirius.patrius.math.linear.ArrayRealVector
|not thread-safe
|Instances are mutable.
|-
|fr.cnes.sirius.patrius.math.linear.CholeskyDecompositionImpl
|not thread-safe
|Exposed mutable attributes (getters on RealMtrix).
|-
|fr.cnes.sirius.patrius.math.linear.LUDecompositionImpl
|not thread-safe
|Exposed mutable attributes (getters on RealMtrix).
|-
|fr.cnes.sirius.patrius.math.linear.QRDecompositionImpl
|not thread-safe
|Exposed mutable attributes (getters on RealMtrix).
|-
|fr.cnes.sirius.patrius.math.ode.events.EventHandler
|not thread-safe
|Instances are mutable.
|-
|fr.cnes.sirius.patrius.math.ode.events.EventException
|unconditionally thread-safe
|Would be immutable if the class were final.
|-
|fr.cnes.sirius.patrius.math.ode.nonstiff.ClassicalRungeKuttaIntegrator
|not thread-safe
|Instances are mutable.
|-
|fr.cnes.sirius.patrius.math.ode.nonstiff.DormandPrince54Integrator
|not thread-safe
|Instances are mutable.
|-
|fr.cnes.sirius.patrius.math.ode.nonstiff.DormandPrince853Integrator
|not thread-safe
|Instances are mutable.
|-
|fr.cnes.sirius.patrius.math.ode.nonstiff.GraggBulirschStoerIntegrator
|not thread-safe
|Instances are mutable.
|-
|fr.cnes.sirius.patrius.math.random.JDKRandomGenerator
|thread-safe
|Extends a class from the Java API whose thread-safety status is undocumented, but probably thread-safe.
|-
|fr.cnes.sirius.patrius.math.stat.StatUtils
|immutable
|Final utility class with reentrant static methods only.
|-
|fr.cnes.sirius.patrius.math.stat.descriptive.rank.Median
|not thread-safe
|Instances are mutable.
|-
|fr.cnes.sirius.patrius.math.stat.descriptive.rank.Percentile
|not thread-safe
|Instances are mutable.
|-
|fr.cnes.sirius.patrius.math.util.FastMath
|immutable
|Final utility class with reentrant static methods only.
|-
|fr.cnes.sirius.patrius.math.util.MathUtils
|immutable
|Final utility class with reentrant static methods only.
|}

* when these are documented as "immutable" in their javadoc, it is stated so.
* the remainder was evaluated by the PATRIUS team.

The list of all validated classes is also available in the SVS.

NOTE : thread hostility has not been systematically researched, so it is not fully documented in this revision.

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Concurrency
! scope="col"| Comment
|-
|fr.cnes.sirius.patrius.attitudes.Attitude
|conditionally thread-safe
|Exposed mutable attribute (getter on Frame), Attitude is thread-safe when the Frame is.
|-
|fr.cnes.sirius.patrius.attitudes.AttitudesSequence
|not thread-safe
|Instances are mutable.
|-
|fr.cnes.sirius.patrius.attitudes.BodyCenterPointing
|unconditionally thread-safe
|Would be immutable if the class were final- documented as immutable, but technically untrue.
|-
|fr.cnes.sirius.patrius.attitudes.CelestialBodyPointed
|unconditionally thread-safe
|Would be immutable if the class were final- documented as immutable, but technically untrue.
|-
|fr.cnes.sirius.patrius.attitudes.BodyCenterGroundPointing.java
|immutable
|
|-
|fr.cnes.sirius.patrius.attitudes.FixedRate
|unconditionally thread-safe
|Would be immutable if the class were final- documented as immutable, but technically untrue.
|-
|fr.cnes.sirius.patrius.attitudes.InertialProvider
|unconditionally thread-safe
|Would be immutable if the class were final- documented as immutable, but technically untrue.
|-
|fr.cnes.sirius.patrius.attitudes.LofOffset
|conditionally thread-safe
|Is thread-safe when the Frame attribute is.
|-
|fr.cnes.sirius.patrius.attitudes.NadirPointing
|unconditionally thread-safe
|Would be immutable if the class were final- documented as immutable, but technically untrue.
|-
|fr.cnes.sirius.patrius.attitudes.SpinStabilized
|unconditionally thread-safe
|Would be immutable if the class were final- documented as immutable, but technically untrue.
|-
|fr.cnes.sirius.patrius.attitudes.TargetGroundPointing.java
|immutable
|
|-
|fr.cnes.sirius.patrius.attitudes.TargetPointing
|unconditionally thread-safe
|Would be immutable if the class were final- documented as immutable, but technically untrue.
|-
|fr.cnes.sirius.patrius.attitudes.YawCompensation
|unconditionally thread-safe
|Would be immutable if the class were final- documented as immutable, but technically untrue.
|-
|fr.cnes.sirius.patrius.attitudes.YawSteering
|unconditionally thread-safe
|Would be immutable if the class were final- documented as immutable, but technically untrue.
|-
|fr.cnes.sirius.patrius.attitudes.kinematics.KinematicsToolkit
|immutable
|
|-
|fr.cnes.sirius.patrius.attitudes.kinematics.AbstractOrientationFunction
|conditionally thread-safe
|Thread-safe if the attribute differentiator is thread-safe and if the implementation of this abstract class is thread-safe too.
|-
|fr.cnes.sirius.patrius.attitudes.kinematics.AbstractVector3DFunction
|conditionally thread-safe
|Thread-safe if the attributes differentiator and integrator are thread-safe and if the implementation of this abstract class is thread-safe too.
|-
|fr.cnes.sirius.patrius.attitudes.kinematics.DynamicsElements
|immutable
|
|-
|fr.cnes.sirius.patrius.bodies.GeodeticPoint
|unconditionally thread-safe
|Would be immutable if the class were final- documented as immutable, but technically untrue.
|-
|fr.cnes.sirius.patrius.bodies.JPLEphemeridesLoader
|conditionally thread-safe
|Unprotected mutable fields are modified by the loadData() method. If this method call is protected, the instance is thread-safe.
|-
|fr.cnes.sirius.patrius.bodies.OneAxisEllipsoid
|not thread-safe
|Instances are mutable.
|-
|fr.cnes.sirius.patrius.data.ClasspathCrawler
|conditionally thread-safe
|The feed() method modifies a mutable reference (DataLoader) that may not be thread-safe. If the call to feed() is protected and the DataLoader is not thread-hostile, OR if the DataLoader is thread-safe, then the instance is thread-safe.
|-
|fr.cnes.sirius.patrius.data.DataProvidersManager
|thread-hostile
|Contains an unprotected singleton.
|-
|fr.cnes.sirius.patrius.data.DirectoryCrawler
|conditionally thread-safe
|The feed() method modifies a mutable reference (DataLoader) that may not be thread-safe. If the call to feed() is protected and the DataLoader is not thread-hostile, OR if the DataLoader is thread-safe, then the instance is thread-safe.
|-
|fr.cnes.sirius.patrius.data.NetworkCrawler
|conditionally thread-safe
|The feed() method modifies a mutable reference (DataLoader) that may not be thread-safe. If the call to feed() is protected and the DataLoader is not thread-hostile, OR if the DataLoader is thread-safe, then the instance is thread-safe.
|-
|fr.cnes.sirius.patrius.data.PoissonSeries
|unconditionally thread-safe
|Technically non-immutable, but immutable "in practice".
|-
|fr.cnes.sirius.patrius.data.ZipJarCrawler
|conditionally thread-safe
|The feed() method modifies a mutable reference (DataLoader) that may not be thread-safe. If the call to feed() is protected and the DataLoader is not thread-hostile, OR if the DataLoader is thread-safe, then the instance is thread-safe.
|-
|fr.cnes.sirius.patrius.utils.exception.PatriusException
|not thread-safe
|Exposed mutable attributes.
|-
|fr.cnes.sirius.patrius.utils.exception.PropagationException
|not thread-safe
|Exposed mutable attributes.
|-
|fr.cnes.sirius.patrius.forces.ConstantFunction
|not thread-safe
|uses internal mutable attributes.
|-
|fr.cnes.sirius.patrius.forces.IJacobiansParameterizable
|not thread-safe
|uses internal mutable attributes.
|-
|fr.cnes.sirius.patrius.forces.IParamDiffFunction
|not thread-safe
|uses internal mutable attributes.
|-
|fr.cnes.sirius.patrius.forces.IParameterizableFunction
|not thread-safe
|uses internal mutable attributes.
|-
|fr.cnes.sirius.patrius.forces.LinearFunction
|not thread-safe
|uses internal mutable attributes.
|-
|fr.cnes.sirius.patrius.forces.Parameter
|not thread-safe
|uses internal mutable attributes.
|-
|fr.cnes.sirius.patrius.forces.Parameterizable
|not thread-safe
|uses internal mutable attributes.
|-
|fr.cnes.sirius.patrius.forces.PiecewiseFunction
|not thread-safe
|uses internal mutable attributes.
|-
|fr.cnes.sirius.patrius.forces.BoxAndSolarArraySpacecraft
|unconditionally thread-safe
|Would be immutable if the class were final- documented as immutable, but technically untrue.
|-
|fr.cnes.sirius.patrius.forces.drag.DTM2000
|not thread-safe
|Exposed mutable attributes.
|-
|fr.cnes.sirius.patrius.forces.drag.DragForce
|not thread-safe
|Exposed mutable attributes.
|-
|fr.cnes.sirius.patrius.forces.gravity.BalminoAttractionModel.java
|not thread-safe
|uses internal mutable attributes
|-
|fr.cnes.sirius.patrius.forces.gravity.potential.EGMFormatReader
|not thread-safe
|Instances are mutable.
|-
|fr.cnes.sirius.patrius.forces.gravity.potential.GravityFieldFactory
|unconditionally thread-safe
|Access to mutable fields are synchronized.
|-
|fr.cnes.sirius.patrius.forces.gravity.potential.GRGSFormatReader
|not thread-safe
|Instances are mutable.
|-
|fr.cnes.sirius.patrius.forces.gravity.potential.ICGEMFormatReader
|not thread-safe
|Instances are mutable.
|-
|fr.cnes.sirius.patrius.forces.gravity.potential.SHMFormatReader
|not thread-safe
|Instances are mutable.
|-
|fr.cnes.sirius.patrius.forces.gravity.CunninghamAttractionModel
|not thread-safe
|Instances are mutable.
|-
|fr.cnes.sirius.patrius.forces.gravity.DrozinerAttractionModel
|not thread-safe
|Instances are mutable.
|-
|fr.cnes.sirius.patrius.forces.gravity.GravityToolbox.java
|immutable
|
|-
|fr.cnes.sirius.patrius.forces.gravity.NewtonianAttraction
|not thread-safe
|Instances are mutable.
|-
|fr.cnes.sirius.patrius.forces.gravity.ThirdBodyAttraction
|not thread-safe
|Instances are mutable.
|-
|fr.cnes.sirius.patrius.forces.maneuvers.ConstantThrustManeuver
|not thread-safe
|Instances are mutable.
|-
|fr.cnes.sirius.patrius.forces.radiation.SolarRadiationPressureCircular
|not thread-safe
|Instances are mutable.
|-
|fr.cnes.sirius.patrius.frames.Frame
|not thread-safe
|Unprotected mutable attribute- but thread-safety problems relative to this attribute have yet to be found, so Frame is "almost" thread-safe.
|-
|fr.cnes.sirius.patrius.frames.FramesFactory
|unconditionally thres-safe
|Access to mutable fields are synchronized. NOTE : The IERS frames provided by this class are thread-safe, these are provided by the getGCRF(), getCIRF(), getTIRF() and getITRF() methods.
|-
|fr.cnes.sirius.patrius.frames.LocalOrbitalFrame
|not thread-safe
|Instances are mutable.
|-
|fr.cnes.sirius.patrius.frames.OrphanFrame
|unconditionally thread-safe
|No attributes, static methods only.
|-
|fr.cnes.sirius.patrius.frames.TopocentricFrame
|not thread-safe
|Is a Frame.
|-
|fr.cnes.sirius.patrius.frames.configuration.DiurnalRotation
|conditionally thread-safe
|thread-safe if constructor parameters are thread safe
|-
|fr.cnes.sirius.patrius.frames.configuration.FramesConfigurationFactory
|thread-safe
|only static methods
|-
|fr.cnes.sirius.patrius.frames.configuration.FramesConfigurationImplementation
|conditionally thread-safe
|thread-safe if constructor parameters are thread safe
|-
|fr.cnes.sirius.patrius.frames.configuration.PolarMotion
|conditionally thread-safe
|thread-safe if constructor parameters are thread safe
|-
|fr.cnes.sirius.patrius.frames.configuration.eop.AbstractEOPHistory
|conditionally thread-safe
|Uses the time stamped cache mechanism. Thread-safe as long as the mechanisms that add entries to the lists do so in a thread-safe manner (see EOPHistoryFactory).
|-
|fr.cnes.sirius.patrius.frames.configuration.eop.BulletinBFilesLoader
|unconditionally thread-safe
|
|-
|fr.cnes.sirius.patrius.frames.configuration.eop.EOP05C04FilesLoader
|unconditionally thread-safe
|
|-
|fr.cnes.sirius.patrius.frames.configuration.eop.EOP08C04FilesLoader
|unconditionally thread-safe
|
|-
|fr.cnes.sirius.patrius.frames.configuration.eop.EOP1980Entry
|immutable
|
|-
|fr.cnes.sirius.patrius.frames.configuration.eop.EOP1980History.java
|unconditionally thread-safe
|Uses the time stamped cache mechanism|
|-
|fr.cnes.sirius.patrius.frames.configuration.eop.EOP2000Entry
|immutable
|
|-
|fr.cnes.sirius.patrius.frames.configuration.eop.EOP2000History
|unconditionally thread-safe
|Uses the time stamped cache mechanism|
|-
|fr.cnes.sirius.patrius.frames.configuration.eop.EOPEntry
|immutable
|
|-
|fr.cnes.sirius.patrius.frames.configuration.eop.EOPHistoryFactory
|unconditionally thread-safe
|getters use synchronized keyword were access to loader lists is performed
|-
|fr.cnes.sirius.patrius.frames.configuration.eop.NoEOP2000History
|immutable
|
|-
|fr.cnes.sirius.patrius.frames.configuration.eop.NutationCorrection
|immutable
|
|-
|fr.cnes.sirius.patrius.frames.configuration.eop.PoleCorrection
|immutable
|
|-
|fr.cnes.sirius.patrius.frames.configuration.eop.RapidDataAndPredictionColumnsLoader
|unconditionally thread-safe
|
|-
|fr.cnes.sirius.patrius.frames.configuration.eop.RapidDataAndPredictionXMLLoader
|unconditionally thread-safe
|
|-
|fr.cnes.sirius.patrius.frames.configuration.libration.LibrationCorrectionModelFactory
|immutable
|only static final fields
|-
|fr.cnes.sirius.patrius.frames.configuration.libration.IERS2010LibrationCorrection
|unconditionally thread-safe
|
|-
|fr.cnes.sirius.patrius.frames.configuration.libration.NoLibrationCorrection
|immutable
|
|-
|fr.cnes.sirius.patrius.frames.configuration.precessionnutation.CIPCoordinates
|immutable
|
|-
|fr.cnes.sirius.patrius.frames.configuration.precessionnutation.CIPCoordinatesGenerator
|conditionally thread-safe
|As long as a generator is referenced by one {@link TimeStampedCache cache} only, it is guaranteed to be called in a thread-safe way, even if the cache is used in a multi-threaded environment.
|-
|fr.cnes.sirius.patrius.frames.configuration.precessionnutation.IERS20032010PrecessionNutation
|unconditionally thread-safe
|
|-
|fr.cnes.sirius.patrius.frames.configuration.precessionnutation.PrecessionNutationCache
|conditionally thread-safe
|thread safe if precession nutation model is thread-safe
|-
|fr.cnes.sirius.patrius.frames.configuration.precessionnutation.PrecessionNutationModelFactory
|immutable
|only static final fields
|-
|fr.cnes.sirius.patrius.frames.configuration.sp.IERS2010SPCorrection
|immutable
|
|-
|fr.cnes.sirius.patrius.frames.configuration.sp.NoSpCorrection
|immutable
|
|-
|fr.cnes.sirius.patrius.frames.configuration.sp.SPrimeModelFactory
|immutable
|
|-
|fr.cnes.sirius.patrius.frames.configuration.tides.TidelCorrectionCache
|conditionally thread-safe
|thread safe if tides model is thread-safe
|-
|fr.cnes.sirius.patrius.frames.configuration.tides.TidalCorrection
|immutable
|
|-
|fr.cnes.sirius.patrius.frames.configuration.tides.TidalCorrectionGenerator
|conditionally thread-safe
|As long as a generator is referenced by one {@link TimeStampedCache cache} only, it is guaranteed to be called in a thread-safe way, even if the cache is used in a multi-threaded environment.
|-
|fr.cnes.sirius.patrius.frames.configuration.tides.IERS2000TidalCorrection
|unconditionally thread-safe
|
|-
|fr.cnes.sirius.patrius.frames.configuration.tides.IERS2010TidalCorrection
|unconditionally thread-safe
|
|-
|fr.cnes.sirius.patrius.frames.configuration.tides.NoTidalCorrection
|immutable
|
|-
|fr.cnes.sirius.patrius.frames.configuration.tides.TidalCorrectionModelFactory
|immutable
|
|-
|fr.cnes.sirius.patrius.frames.transformations.HelmertTransformation
|unconditionally thread-safe
|Would be immutable if the class were final- documented as immutable, but technically untrue.
|-
|fr.cnes.sirius.patrius.frames.transformations.Transform
|unconditionally thread-safe
|Would be immutable if the class were final- documented as immutable, but technically untrue.
|-
|fr.cnes.sirius.patrius.models.earth.COFFileFormatReader.java
|not thread-safe
|instance is mutable
|-
|fr.cnes.sirius.patrius.models.earth.FixedDelayModel.java
|not thread-safe
|instance is mutable
|-
|fr.cnes.sirius.patrius.models.earth.GeoMagneticModelReader.java
|not thread-safe
|instance is mutable
|-
|fr.cnes.sirius.patrius.models.earth.GeoMagneticElements
|unconditionally thread-safe
|Would be immutable if the class were final
|-
|fr.cnes.sirius.patrius.models.earth.GeoMagneticField
|not thread-safe
|Instance are mutable
|-
|fr.cnes.sirius.patrius.models.earth.GeoMagneticFieldFactory
|unconditionally thread-safe
|Access to mutable fields are synchronized.
|-
|fr.cnes.sirius.patrius.models.earth.ModelLoader
|not thread-safe
|Mutable fields
|-
|fr.cnes.sirius.patrius.orbits.CartesianOrbit
|immutable
|Modified by Patrius team.
|-
|fr.cnes.sirius.patrius.orbits.CircularOrbit
|immutable
|Modified by Patrius team.
|-
|fr.cnes.sirius.patrius.orbits.EquinoctialOrbit
|immutable
|Modified by Patrius team.
|-
|fr.cnes.sirius.patrius.orbits.KeplerianOrbit
|immutable
|Modified by Patrius team.
|-
|fr.cnes.sirius.patrius.orbits.ApsisOrbit
|immutable
|Created by Patrius team.
|-
|fr.cnes.sirius.patrius.orbits.EquatorialOrbit
|immutable
|Created by Patrius team.
|-
|fr.cnes.sirius.patrius.propagation.analytical.EcksteinHechlerPropagator
|not thread-safe
|Instances are mutable.
|-
|fr.cnes.sirius.patrius.propagation.analytical.KeplerianPropagator
|not thread-safe
|Instances are mutable.
|-
|fr.cnes.sirius.patrius.propagation.events.AdaptedAdditionalStatesEventDetector
|conditionally thread-safe
|if all attributes are thread safe.
|-
|fr.cnes.sirius.patrius.propagation.events.AdaptedEventDetector
|not thread-safe
|Exposed mutable attributes.
|-
|fr.cnes.sirius.patrius.propagation.events.AdditionalStatesEventsLogger
|not thread-safe
|Exposed mutable attributes.
|-
|fr.cnes.sirius.patrius.propagation.events.AlignmentDetector
|not thread-safe
|Exposed mutable attributes.
|-
|fr.cnes.sirius.patrius.propagation.events.AltitudeDetector
|not thread-safe
|Exposed mutable attributes.
|-
|fr.cnes.sirius.patrius.propagation.events.ApsideDetector
|not thread-safe
|Exposed mutable attributes.
|-
|fr.cnes.sirius.patrius.propagation.events.CircularFieldOfViewDetector
|not thread-safe
|Exposed mutable attributes.
|-
|fr.cnes.sirius.patrius.propagation.events.DateDetector
|not thread-safe
|Instances are mutable.
|-
|fr.cnes.sirius.patrius.propagation.events.DihedralFieldOfViewDetector
|not thread-safe
|Exposed mutable attributes.
|-
|fr.cnes.sirius.patrius.propagation.events.EclipseDetector
|not thread-safe
|Exposed mutable attributes.
|-
|fr.cnes.sirius.patrius.propagation.events.ElevationDetector
|not thread-safe
|Exposed mutable attributes.
|-
|fr.cnes.sirius.patrius.propagation.events.EventShifter
|not thread-safe
|Exposed mutable attributes.
|-
|fr.cnes.sirius.patrius.propagation.events.EventsLogger
|not thread-safe
|Exposed mutable attributes.
|-
|fr.cnes.sirius.patrius.propagation.events.EventState
|not thread-safe
|Exposed mutable attributes.
|-
|fr.cnes.sirius.patrius.propagation.events.GroundMaskElevationDetector
|not thread-safe
|Exposed mutable attributes.
|-
|fr.cnes.sirius.patrius.propagation.events.NodeDetector
|not thread-safe
|Exposed mutable attributes.
|-
|fr.cnes.sirius.patrius.propagation.numerical.AdditionalStateInfo
|Immutable
|
|-
|fr.cnes.sirius.patrius.propagation.numerical.JacobiansMapper
|unconditionally thread-safe
|Would be immutable if the class were final- documented as immutable, but technically untrue.
|-
|fr.cnes.sirius.patrius.propagation.numerical.NumericalPropagator
|not thread-safe
|As documented.
|-
|fr.cnes.sirius.patrius.propagation.events.PartialDerivativesEquations
|not thread-safe
|Instances are mutable.
|-
|fr.cnes.sirius.patrius.propagation.precomputed.Ephemeris
|not thread-safe
|Instances are mutable.
|-
|fr.cnes.sirius.patrius.propagation.precomputed.IntegratedEphemeris
|not thread-safe
|Instances are mutable.
|-
|fr.cnes.sirius.patrius.propagation.sampling.AdaptedStepHandler
|not thread-safe
|Instances are mutable.
|-
|fr.cnes.sirius.patrius.propagation.SpacecraftState
|unconditionally thread-safe
|Would be immutable if the class were final- documented as immutable, but technically untrue.
|-
|fr.cnes.sirius.patrius.propagation.SimpleMassModel.java
|not thread-safe
|instance is mutable. WARNING : this class is wrongfully documented as immutable (javadoc)! It is mutable.
|-
|fr.cnes.sirius.patrius.time.AbsoluteDate
|unconditionally thread-safe
|Would be immutable if the class were final- documented as immutable, but technically untrue.
|-
|fr.cnes.sirius.patrius.time.DateComponents
|unconditionally thread-safe
|Would be immutable if the class were final- documented as immutable, but technically untrue.
|-
|fr.cnes.sirius.patrius.time.DateTimeComponents
|unconditionally thread-safe
|Would be immutable if the class were final- documented as immutable, but technically untrue.
|-
|fr.cnes.sirius.patrius.time.GalileoScale
|unconditionally thread-safe
|Would be immutable if the class were final.
|-
|fr.cnes.sirius.patrius.time.GPSScale
|thread-hostile
|A deprecated method calls the thread-hostile TimeScalesFactory. When this method is removed, the class will become thread-safe.
|-
|fr.cnes.sirius.patrius.time.TimeComponents
|unconditionally thread-safe
|Would be immutable if the class were final- documented as immutable, but technically untrue.
|-
|fr.cnes.sirius.patrius.time.TimeScalesFactory
|thread-hostile
|Contains unprotected singletons.
|-
|fr.cnes.sirius.patrius.time.TAIScale
|thread-hostile
|A deprecated method calls the thread-hostile TimeScalesFactory. When this method is removed, the class will become thread-safe.
|-
|fr.cnes.sirius.patrius.time.TTScale
|thread-hostile
|A deprecated method calls the thread-hostile TimeScalesFactory. When this method is removed, the class will become thread-safe.
|-
|fr.cnes.sirius.patrius.time.UTCScale
|thread-hostile
|A deprecated method calls the thread-hostile TimeScalesFactory. When this method is removed, the class will (likely) become thread-safe.
|-
|fr.cnes.sirius.patrius.time.UTCTAIHistoryFilesLoader
|not thread-safe
|Exposed mutable attributes.
|-
|fr.cnes.sirius.patrius.time.UTCTAIOffset
|not thread-safe
|Instances are mutable.
|-
|fr.cnes.sirius.patrius.time.UT1Scale
|not thread-safe
|Exposed mutable attributes.
|-
|fr.cnes.sirius.patrius.utils.PVCoordinates
|unconditionally thread-safe
|Would be immutable if the class were final- documented as immutable, but technically untrue.
|-
|fr.cnes.sirius.patrius.wrenches.Wrench.java
|immutable
|
|}

[[Category:User_Manual_4.17]]

Catégorie:User Manual 4.17 Attitude

2025-11-26T13:56:48Z

Admin tsn : Page créée avec «  == Introduction == This section describes attitude features of Patrius: attitude laws, slew, guidance, etc. == Applicable and Reference Documents == === Applicable Documents === '''[A1]''' ''CDCF - Fonctions de Base du Patrimoine de Dynamique du Vol'', V1.2, SIRIUS-CF-DV-0049-CN, 2011. '''[A2]''' ''Dossier de réutilisation Orekit et Commons Math'', V1.0, SIRIUS-DLR-DV-0080-CN, 2010. === Reference Documents === None applicable. == Overview ==... »

== Introduction ==
This section describes attitude features of Patrius: attitude laws, slew, guidance, etc.

== Applicable and Reference Documents ==
=== Applicable Documents ===

'''[A1]''' ''CDCF - Fonctions de Base du Patrimoine de Dynamique du Vol'', V1.2, SIRIUS-CF-DV-0049-CN, 2011. 
'''[A2]''' ''Dossier de réutilisation Orekit et Commons Math'', V1.0, SIRIUS-DLR-DV-0080-CN, 2010.

=== Reference Documents ===

None applicable.

== Overview ==
The Attitude package of the PATRIUS library has been developed according to the SIRIUS Scope Statement '''[A1]'''. The themes developed are described hereafter :

; Directions
: Implementation of directions of space that can evolve in time.

; Attitude laws
: Several attitude laws are available. These laws were originally designed for orbit determination needs: in order to broaden their applications, a wrapper object has been created to meet the spacecraft attitude field needs.

; Attitudes sequence
: Implementation of an attitudes sequence for orbit determination: it is possible to define an attitude law as a series of attitude laws in the context of a propagation.

; Attitude legs sequence
: Implementation for spacecraft attitude field of an attitude sequence: it is possible to define an attitude leg as a series of attitude legs.

; Attitude composition
: Implementation of an object that enables to define an attitude law as a composition of several laws.

; Orientation
: Orientations are similar to attitude providers except that it returns only one angle.

; Slew
: Implementation of slew. Slews are used in the attitudes sequence to define the transition between two laws. Slews are splits into two functions: slew computations through dedicated classes and slew realization.

; Kinematics
: Implementation of a tool box for kinematics calculations.

; Guidance command
: Implementation of the ground and the on-board guidance commands. The first one is computed, the second one is simulated. In both cases, it should be possible to compute the guidance command from a law and to consider the guidance command itself as a law.

[[Category:User_Manual_4.17]]

User Manual 4.17 Slew

2025-11-26T13:56:34Z

Admin tsn : Page créée avec « __NOTOC__ == Introduction == === Scope === A slew performs the transition between two attitude laws. === Javadoc === The attitude objects linked to slews are available in the package fr.cnes.sirius.patrius.attitudes. {| class="wikitable" |- ! scope="col"| Library ! scope="col"| Javadoc |- |Patrius |[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/package-summary.html Package fr.cnes.sirius.patrius.attitudes] |} === Links === None as of now. === Useful Docum... »

__NOTOC__
== Introduction ==
=== Scope ===
A slew performs the transition between two attitude laws.

=== Javadoc ===
The attitude objects linked to slews are available in the package fr.cnes.sirius.patrius.attitudes.

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/package-summary.html Package fr.cnes.sirius.patrius.attitudes]
|}

=== Links ===
None as of now.

=== Useful Documents ===
None as of now.

=== Package Overview ===
The slew conception is split into two features:
* The slew computation. Classes ''computing'' the slew are provided in PATRIUS.
* The slew realization. All classes realizing a slew implements the <code>Slew</code> interface. Slews are mainly of two types:
** Analytical slews (such as <code>ConstantSpinSlew</code>
** Pre-computed slews stored in a <code>TabulatedSlew</code>. In this case, a slew ''computer'' will compute the tabulated ephemeris of the slew.

A slew is bounded in time and as a result inherits the [ATT_LEG_Home AttitudeLeg] interface.

== Features ==
=== Constant spin slew ===
The constant spin slew is a basic slew maneuver type. Between the initial quaternion and the final one, a spherical linear interpolation describes the behavior of the spacecraft.
Two constraint types are available:
* Duration constraint: spin is computed to match constraint.
<syntaxhighlight lang="java">final Slew slew = new ConstantSpinSlew(firstAttitude, secondAttitude);</syntaxhighlight>
* Angular velocity constraint: initial slew date or final slew date is computed to match constraint.
** Initial slew date is known:
<syntaxhighlight lang="java">final Slew slew = new ConstantSpinSlewComputer(angularConstraint).compute(pvProvider, initialLaw, initialDate, finalLaw, null);</syntaxhighlight>
** Final slew date is known:
<syntaxhighlight lang="java">final Slew slew = new ConstantSpinSlewComputer(angularConstraint).compute(pvProvider, initialLaw, null, finalLaw, finalDate);</syntaxhighlight>

=== Spin bias slew ===
The two spin bias slew is a slew maneuver type. The velocity depends on the value of the slew angle.

In order to compute properly the slew, the user must specify the initial and final laws, the parameters of the two angular velocity fields, plus the stabilisation margin:

<syntaxhighlight lang="java">final TwoSpinBiasSlewComputer computer = new TwoSpinBiasSlewComputer(
step, theta_max, tau, epsInRall, omega2, theta, epsOutRall, omega1, dtStab);</syntaxhighlight>

Once the slew maneuver is defined, the computation can be performed on an orbital state using the following method:
<syntaxhighlight lang="java">
final TabulatedSlew slew = computer.compute(startLaw, initialDate, finalLaw, null);
</syntaxhighlight>

The slew is then represented by a generic <code>TabulatedSlew</code> which stores the slew under a tabulated ephemeris.

=== ISIS Spin bias slew ===
This spin bias slew is a slew with a trapezoidal angular velocity profile:
- Constant acceleration phase
- Constant angular velocity phase (zero acceleration phase)
- Constant decceleration phase

[[File:ISISSpin2.png|center]]

This slew can be computed using methods: 
- <code>IsisSpinBiasSlewComputer.computeAnalytical</code>: this class provides an analytical solution to the slew 
- <code>IsisSpinBiasSlewComputer.computeNumerical</code>: this class provides an numerical solution to the slew
The two classes returns close results ( < 1E-2 rad), though analytical solution is more accurate.

The slews can be used in two ways: 
- Provide an initial law, an initial date and a target final law 
- Provide an final law, a final date and a target initial law 
'''Warning''': slew computed in both ways will never be exactly the same depending on user-chosen convergence threshold and maximum number of iterations (result will be exactly the same if convergence threshold is lower than machine precision and number of allowed iterations high enough to support convergence). In case the maximum number of iterations is reached, the user is prevented by a warning message (if the option <code>throwExceptionOnMaxIterations</code> is at false).

The slew has then to be calculated using method <code>compute()</code>.
The slew is then represented by a generic <code>TabulatedSlew</code> which stores the slew under a tabulated ephemeris.
Finally the slew can be used like any other slew.

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

== Contents ==
=== Interfaces ===

{| class="wikitable"
|-
! scope="col"| Interface
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''AttitudeLeg'''
|This interface extends the AttitudeProvider interface and adds the time interval of validity notion to the attitude laws.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/AttitudeLeg.html AttitudeLeg]
|-
|'''Slew'''
|This interface implements a generic slew model set.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/Slew.html Slew]
|}

=== Classes ===

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''ConstantSpinSlew'''
|This class implements the constant spin slew maneuver profile.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/ConstantSpinSlew.html ConstantSpinSlew]
|-
|'''TabulatedSlew'''
|This class implements a generic tabulated slew, once computed with one of the computer classes.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/TabulatedSlew.html TabulatedSlew]
|-
|'''AngularVelocitiesPolynomialSlew'''
|This class implements a generic angular velocities polynomial slew.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/AngularVelocitiesPolynomialSlew.html AngularVelocitiesPolynomialSlew]
|-
|'''ConstantSpinSlewComputer'''
|This class computes a constant spin slew into a ConstantSpinSlew.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/slew/ConstantSpinSlewComputer.html ConstantSpinSlewComputer]
|-
|'''TwoSpinBiasSlewComputer'''
|This class computes a two spin bias slew into a TabulatedSlew.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/slew/TwoSpinBiasSlewComputer.html TwoSpinBiasSlewComputer]
|-
|'''IsisSpinBiasSlewComputer'''
|This class computes an ISIS spin bias slew into a TabulatedSlew.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/slew/IsisSpinBiasSlewComputer.html IsisSpinBiasSlewComputer]
|}

[[Category:User_Manual_4.17_Attitude]]

User Manual 4.17 Rotation, AngularCoordinates, Tranform and Attitude : how to use them

2025-11-26T13:56:20Z

Admin tsn : Page créée avec « __NOTOC__ == Introduction == In PATRIUS, several objects allow the user to represent rotations and perform some frame transformations, from simplest to most complex: * <code>Rotation</code>: this class defines a rotation. No frame and date is associated. * <code>AngularCoordinates</code>: this class defines a rotation, a rotation rate and optionally a rotation acceleration. No frame and date is associated. * <code>Transform</code>: this class defines angular coo... »

__NOTOC__
== Introduction ==
In PATRIUS, several objects allow the user to represent rotations and perform some frame transformations, from simplest to most complex:
* <code>Rotation</code>: this class defines a rotation. No frame and date is associated.
* <code>AngularCoordinates</code>: this class defines a rotation, a rotation rate and optionally a rotation acceleration. No frame and date is associated.
* <code>Transform</code>: this class defines angular coordinates and PV coordinates at a given date.
* <code>Attitude</code>: this class defines angular coordinates at a given date with respect to a reference frame.

== Rotation ==
=== Definition ===

A rotation is represented by the object <code>Rotation</code> (see [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidian/threed/Rotation.html Javadoc]).

A rotation is a transformation that transforms a reference frame (in black) into a frame of interest (in blue). The result is expressed in the reference frame.

[[File:Orientation.png|center]]

The formula giving the transformation are the following:

<center>
<math>\vec{X_{int / ref}} = R(\vec{X_{ref / ref}})</math>
<math>\vec{Y_{int / ref}} = R(\vec{Y_{ref / ref}})</math>
<math>\vec{Z_{int / ref}} = R(\vec{Z_{ref / ref}})</math>
</center>

The rotation object is not linked to any frame, so remember, the rotation is can be applied to any set of coordinates as long as it is consistent with how you defined your rotation.

=== Features ===

The <code>Rotation</code> objects can be defined by several manners:
* Using quaternions (used as internal representation), see [MAT_ROT_Home Quaternions]
* Using a 3x3 rotation matrix
* Using an axis and an angle
* Using Euler angles
* etc.

The <code>Rotation</code> offers several features:
* Rotate a vector expressed in the reference frame to the frame of interest (= express this vector in the frame of interest): <code>Rotation.applyInverseTo(Vector3D)</code>
* Rotate a vector expressed in the frame of interest to the reference frame (= express this vector in the reference frame): <code>Rotation.applyTo(Vector3D)</code>
* Compose two rotation: <code>Rotation.applyInverseTo(Rotation)</code>. R2.applyInverseTo(R1) returns R2^^-1^^ o R1
* Compose two rotation: <code>Rotation.applyTo(Rotation)</code>. R2.applyTo(R1) returns R2 o R1
* Get Euler angles (given an Euler sequence): <code>Rotation.getAngles()</code>
* Get rotation matrix associated to rotation: <code>Rotation.getMatrix()</code>
* etc.

=== Code examples ===

Let's consider:
* A frame F1 [x1, y1, z1]
* A frame F2 [x2, y2, z2] with x2 = y1, y2 =-x1, z2 = z1
Then F2 is obtained by a rotation of 90° around z1 of F1

The following code defines the frames F1 and F2 and performs some transformations:
<syntaxhighlight lang="java">
// Define the rotation transforming F1 into F2: the axis is [0, 0, 1] and the angle is (Pi / 2)
final Rotation rotation = new Rotation(Vector3D.PLUS_K, FastMath.PI / 2.);
// Defines a vector v1 in F1
final Vector3D v1 = new Vector3D(1., 1., 1.);
// Express v1 in F2 = v2 = [1,-1, 1]
final Vector3D v2 = rotation.applyInverseTo(v1);
// Express v2 in F1 = v3. v3 is then equal to v1
final Vector3D v3 = rotation.applyTo(v2);
// Retrieve axis of rotation [0, 0, 1] and angle
final Vector3D axis = rotation.getAxis();
final double angle = rotation.getAngle();
</syntaxhighlight>

Other methods are used in a similar fashion.

== Angular coordinates ==
=== Definition ===

Angular coordinates are represented by the object <code>AngularCoordinates</code> (see [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/utils/AngularCoordinates.html Javadoc]).
Angular coordinates contain:
* A rotation defined with a <code>Rotation</code> object (see above)
* A rotation rate defined with a <code>Vector3D</code> object.
* A rotation rate derivative (or rotation acceleration) defined with a <code>Vector3D</code> object.

'''The convention used to describe the orientation of the frame of interest in <code>AngularCoordinates</code> is the same used in <code>Rotation</code>''': the rotation represents the transformation from a reference frame to a frame of interest, expressed in reference frame. However <code>AngularCoordinates.applyTo()</code> returns the opposite of <code>Rotation.applyTo()</code>.

'''Orientation''' 
The orientation is described by a rotation (see above).

'''Rotation Rate''' 
The Rotation Rate is a 3D vector expressed'''in the frame of interest'''.
Its norm is the angular velocity of the frame of interest. Its direction is the instant axis of spin.
Here is the case of a spin around the Z axis :

[[File:rotationRate.png|center]]

'''Rotation Acceleration''' 
The Rotation Acceleration is a 3D vector expressed'''in the frame of interest'''.
Its norm is the angular acceleration of the frame of interest. As the rotation rate, its direction is the instant axis of spin (see image above).

This computation is optional. All methods are doubled:
* One provides computation without rotation rate derivative.
* One provides computation with or without rotation rate derivative (a boolean is provided):
<syntaxhighlight lang="java">
AngularCoordinates(final PVCoordinates u1, final PVCoordinates u2,
final PVCoordinates v1, final PVCoordinates v2,
final double tolerance, final boolean spinDerivativesComputation)
</syntaxhighlight>
Don't compute spin derivative if you don't need to since it is time consuming.

=== Features ===

The <code>AngularCoordinates</code> class offers several features:
* Rotate a vector expressed in the reference frame to the frame of interest (= express this vector in the frame of interest): <code>AngularCoordinates.applyTo()</code>. Warning: this is opposite from <code>Rotation.applyTo()</code>!
* Given a time shift, shift internal rotation using rotation rate and derivative if provided: <code>AngularCoordinates.shiftedBy()</code>
* Internal rotation as a <code>Rotation</code> object can be retrieved and methods shown in the Rotation section are available. Retrieved rotation has the same convention as Rotation class.
* etc.

=== Code examples ===

Here is an examples of how to time-shift a rotation using the rotation rate. This example involves different frames and helps understand them.

<syntaxhighlight lang="java">
// Get the content of angular coordinates
// Rotation represent a transformation from a reference frame F1 to a frame of interest F2, expressed in F1
// Rotation acceleration and rotation rate are expressed in frame of interest F2
Vector3D rotation_acceleration = angularCoordinates.getRotationAcceleration()
Vector3D rotation_rate = angularCoordinates.getRotationRate();
Rotation orientation = angularCoordinates.getRotation();

// To compose two rotations, they must be expressed in the same frame (here F1).
// The orientation is expressed in the reference frame F1, so the shift (evolution of the rotation) has to be expressed in the reference frame F1 too.
// To create it, the rotation rate has itself to be expressed in the reference frame F1.

// Get rotation rate which is expressed in F2 in reference frame F1
Vector3D rotation_rate_in_ref_frame = orientation.applyTo(rotation_rate);

// The rotation shift can then be created ("dt" is the time duration of the shift). This rotation shift is expressed in F1
Rotation shift = new Rotation(rotation_rate_in_ref_frame, rotation_rate_in_ref_frame.getNorm()* dt);

// The time-shifted orientation can finally be computed: this rotation represents the transformation from the reference frame F1 to a frame of interest F3 which is shifted from F2.
Rotation finalRotation = shift.applyTo(orientation);
</syntaxhighlight>

For information, the shifted rotation can be directly retrieved using the method <code>shyftedBy()</code> of <code>AngularCoordinates</code>.
<syntaxhighlight lang="java">
AngularCoordinates shifted = angularCoordinates.shiftedBy(dt);
Rotation shiftedRotation = shifted.getRotation();
</syntaxhighlight>

== Transform ==

[[File:rotationRate.png|center]]

=== Definition ===

Transform are represented by the object <code>Transform</code> (see [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/transformations/Transform.html Javadoc]).
A Transform object contains:
* A date of the transformation
* A position, velocity, acceleration (optional)
* A rotation, rotation rate, rotation rate derivative (optional)
of a "destination" frame (or frame of interest) in an "origin" frame (or reference frame).

[[File:transform.png|center]]

'''The convention used to describe the orientation and rotation rate of the "destination" frame in Transform is the same as in Rotation and AngularCoordinates''' : the rotation returned by <code>Transform.getRotation()</code> is the one that transforms the basis vectors of the "origin" frame into the ones of the "destination" frame.

The position and velocity of the "destination" are expressed in the "origin" frame.

=== Features ===

The <code>Transform</code> class offers several features:
* Transform a vector expressed in origin frame in destination frame: <code>Transform.transformVector()</code>
* Transform a PVCoordinates expressed in origin frame in destination frame: <code>Transform.transformPVCoordinates()</code>
* Retrieve jacobian of transformation: <code>Transform.getJacobian()</code>
* Internal rotation as a <code>Rotation</code> object (as well as rotation rate, etc.) can be retrieved and methods shown in the Rotation section are available. Retrieved rotation has the same convention as Rotation class. Other attributes (rotation rate, etc.) have the same convention as AngularCoordinates class.
* etc.

=== Code examples ===

In the following example, the "origin" is a TNW local orbital frame and the "destination" is the GCRF inertial frame.

<syntaxhighlight lang="java">
// Build transform from TNW local orbital frame to GCRF
final Frame lof = new LocalOrbitalFrame(FramesFactory.getGCRF(), LOFType.TNW, orbit, "TNW");
final Frame gcrf = FramesFactory.getGCRF();
final Transform transform = lof.getTransformTo(gcrf, AbsoluteDate.J2000_EPOCH);
// Define a vector v = [1, 0, 0] in TNW frame
final Vector3D v_TNW = Vector3D.PLUS_I;
// Get v in GCRF frame
final Vector3D v_GCRF = transform.transformVector(v_TNW);
// Get v back in TNW
final Vector3D v_TNW2 = transform.getInverse().transformVector(v_GCRF);
</syntaxhighlight>

== Attitude ==
=== Definition ===

An attitude object contains all information about the satellite's orientation at a date.

Attitudes are represented by the object <code>Attitude</code> (see [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/Attitude.html Javadoc]).
Attitude contain:
* Angular coordinates.
* A date.
* A reference frame.
Attitude object contains information to rotate the reference frame to a frame of interest (often the satellite frame), expressed in the reference frame.
For example, attitude laws via the method getAttitude(Frame, etc.) will return the Attitude in provided frame, the attitude being the transformation from provided frame to satellite platform frame).

'''The convention used to describe the orientation of the frame of interest in <code>Attitude</code> is the same used in <code>AngularCoordinates</code>''': the rotation represents the transformation from a reference frame to a frame of interest, expressed in reference frame.

=== Features ===

The <code>Attitude</code> class offers several features:
* Change the attitude reference frame: <code>Attitude.withReferenceFrame()</code>
* Internal rotation as a <code>Rotation</code> object (as well as rotation rate, etc.) can be retrieved and methods shown in the Rotation section are available. Retrieved rotation has the same convention as Rotation class. Other attributes (rotation rate, etc.) have the same convention as AngularCoordinates class.
* Perform interpolation: <code>Attitude.interpolate()</code>
* etc.

=== Code examples ===

This example creates an attitude from a reference frame GCRF to the satellite frame, change the reference frame to CIRF and then rotate a vector.

<syntaxhighlight lang="java">
// Define attitude from BodyCenterPointing attitude law, expressed in GCRF frame
final AttitudeLaw attitudeLaw = new BodyCenterPointing();
final Frame gcrf = FramesFactory.getGCRF();
final Attitude attitude_GCRF = attitudeLaw.getAttitude(orbit, AbsoluteDate.J2000_EPOCH, gcrf);
// Change attitude reference frame to CIRF
final Frame cirf = FramesFactory.getCIRF();
final Attitude attitude_CIRF = attitude_GCRF.withReferenceFrame(cirf);

// Define a vector v = [1, 0, 0] in satellite frame
final Vector3D v_Sat = Vector3D.PLUS_I;
// Get attitude rotation (from reference frame = CIRF to frame of interest = satellite frame)
final Rotation rotation = attitude_CIRF.getRotation();
// Get v in CIRF frame
final Vector3D v_CIRF = rotation.applyInverseTo(v_Sat);

</syntaxhighlight>

==More code examples==
Here is an example of code that may help understanding the use of rotations in attitudes and frames transformations.

<syntaxhighlight lang="java">
// GCRF, reference frame
final Frame gcrf = FramesFactory.getGCRF();

// Axis of the GCRF frame, expressed in GCRF
final Vector3D xGCRF_inGCRF = Vector3D.PLUS_I;
final Vector3D yGCRF_inGCRF = Vector3D.PLUS_J;
final Vector3D zGCRF_inGCRF = Vector3D.PLUS_K;

// Directions associated to those axis
final IDirection xGCRF = new ConstantVectorDirection(xGCRF_inGCRF, gcrf);
final IDirection yGCRF = new ConstantVectorDirection(yGCRF_inGCRF, gcrf);
final IDirection zGCRF = new ConstantVectorDirection(zGCRF_inGCRF, gcrf);

// Creation of a "zero" PV provider
final PVCoordinatesProvider pvProv = new PVCoordinatesProvider() {
public PVCoordinates getPVCoordinates(AbsoluteDate date, Frame frame)
throws PatriusException {
return new PVCoordinates(Vector3D.ZERO, Vector3D.ZERO);
}
};

// a date...
final AbsoluteDate date = new AbsoluteDate(2014, 10, 2, 11, 46, 00,
TimeScalesFactory.getTAI());

// Axis of the satellite frame, expressed in the satellite frame
final Vector3D xSat_inRSat = Vector3D.PLUS_I;
final Vector3D ySat_inRSat = Vector3D.PLUS_J;
final Vector3D zSat_inRSat = Vector3D.PLUS_K;

// The attitude law :
//- axe Xsat on Y_GCRF,
//- axe Ysat "as close as possible" to Z_GCRF.
// We are implicitly defining the orientation of the satellite frame.
final TwoDirectionAttitudeLaw attLaw = new TwoDirectionAttitudeLaw(yGCRF, zGCRF, xSat_inRSat, ySat_inRSat);

// Attitude computation,
// and getting of the associated rotation.
Attitude att = attLaw.getAttitude(pvProv, date, gcrf);
Rotation rot = att.getRotation ();

// Computation of the axis of the satellite frame in the GCRF
Vector3D xSat_inGCRF = rot.applyTo(xGCRF_inGCRF);
Vector3D ySat_inGCRF = rot.applyTo(yGCRF_inGCRF);
Vector3D zSat_inGCRF = rot.applyTo(zGCRF_inGCRF);

// Print
System.out.println("xSat_inGCRF: " + xSat_inGCRF);
System.out.println("ySat_inGCRF: " + ySat_inGCRF);
System.out.println("zSat_inGCRF: " + zSat_inGCRF);

// getting the attitude quaternion
Quaternion q = rot.getQuaternion ();
System.out.println("quaternion: " + q);

// Printing the axis and angle of the rotation,
// to visualize its "right" definition.
System.out.println(" axis: " + rot.getAxis());
System.out.println(" angle: " + rot.getAngle());

// Creation of the satellite frame
AttitudeFrame attFrame = new AttitudeFrame(pvProv, attLaw, gcrf);

// getting the transformation from the satellite frame to the GCRF
Transform transform = attFrame.getTransformTo(gcrf, date);

// Changing the expression frame of Xsat from Rsat into GCRF
// to match the previous result :
System.out.println("xSat_inGCRF: " + xSat_inGCRF);
System.out.println("transform.transformVector(xSat_inRSat): " +
transform.transformVector(xSat_inRSat));
</syntaxhighlight>

[[Category:User_Manual_4.17_Attitude]]

User Manual 4.17 Attitude law

2025-11-26T13:56:05Z

Admin tsn : Page créée avec « __NOTOC__ == Introduction == === Scope === The purpose of this chapter is to describe the current Patrius attitude laws. === Javadoc === The attitude objects are available in the package fr.cnes.sirius.patrius.attitudes. {| class="wikitable" |- ! scope="col"| Library ! scope="col"| Javadoc |- |Patrius |[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/package-summary.html Package fr.cnes.sirius.patrius.attitudes] |- |Patrius |[{{JavaDoc4.17}}/fr/cnes/sirius/pa... »

__NOTOC__
== Introduction ==
=== Scope ===
The purpose of this chapter is to describe the current Patrius attitude laws.

=== Javadoc ===
The attitude objects are available in the package fr.cnes.sirius.patrius.attitudes.

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/package-summary.html Package fr.cnes.sirius.patrius.attitudes]
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/package-summary.html Package fr.cnes.sirius.patrius.attitudes]
|}

=== Links ===
Orekit attitudes : [https://www.orekit.org/static/architecture/attitudes.html Orekit Attitudes architecture description ]

=== Useful Documents ===
None as of now.

== Features Description ==
=== Generalities ===
The Orekit class <code>AttitudeProvider</code> represents a generic provider for an attitude law. Attitude from an attitude provider can be retrieved using the methods <code>getAttitude(...)</code>

The new <code>AttitudeLaw</code> interface, implementing <code>AttitudeProvider</code> has been added to represent an attitude provider without a time interval of validity.

Instead, to meet spacecraft attitude field needs, a wrapper object has been created. The idea is to provide objects more suited for spacecraft attitude field rather than orbit determination field, that means to associate a specific time interval of validity to the attitude laws. The new objects <code>AttitudeLeg</code> and <code>AttitudeLawLeg</code> meet the requirements.
<code>AttitudeLawLeg</code> wraps an <code>AttitudeLaw</code> object and defines a time interval of validity. This class implements the <code>AttitudeLeg</code> interface which extends the <code>AttitudeProvider</code> interface and adds the methods to get the time interval.

In pratical terms, when it comes to create an attitude law for spacecraft attitude field purposes, the user has to create first an <code>AttitudeLaw</code> which is then given to an <code>AttitudeLawLeg</code> object, in addition to the initial and final date of the time interval of validity:

<syntaxhighlight lang="java">
// Attitude law leg provider

// Elliptic earth shape
final OneAxisEllipsoid earthShape = new OneAxisEllipsoid(6378136.460, 1 / 298.257222101, frameITRF);

// Target pointing attitude provider over satellite nadir at date, without yaw compensation
final NadirPointing nadirLaw = new NadirPointing(earthShape);

// First date
final AbsoluteDate date1 = new AbsoluteDate(new DateComponents(2012, 01, 01),
TimeComponents.H00, TimeScalesFactory.getUTC());
// Last date
final AbsoluteDate date2 = date1.shiftedBy(3600);

// Attitude law leg
final AttitudeLawLeg myAttitudeLaw = new AttitudeLawLeg(nadirLaw, date1, date2);
</syntaxhighlight>

Besides, compared to Orekit, the <code>Attitude</code> object has been slightly modified. In addition to the rotation and the rotation rate it can also provide the rotation acceleration, and its computation can be activated (or not) by the user. Therefore, an additional <code>getAttitude()</code> method and a <code>setSpinDerivativesComputation(final boolean setSpinDerivatives)</code> method have been created to the <code>AttitudeProvider</code> interface. This last method allows the user to activate the rotation acceleration computation. By default, only the rotation and the angular velocity is computed.

=== Available attitude laws ===

==== Ground pointing attitude laws ====
The satellite x axis is aligned to the satellite velocity vector, and the z axis points to the ground target:
* Body center ground pointing: the satellite z axis is pointing to the body frame center.

* Nadir pointing: the satellite z axis is pointing to the vertical of the ground point under satellite.

* Target ground pointing: the satellite z axis is pointing to a ground point target;

* LOF offset pointing: the attitude pointing law is defined by an attitude provider and the satellite axis vector chosen for pointing.

These laws require a body shape and a frame.

==== Body center attitude law ====
The satellite z axis points to a the body center; this law does not require a body shape.

==== Target attitude law ====
The satellite z axis points to a target; this law does not require a body shape.

==== Celestial body pointed attitude law ====
The celestial body pointed law is defined by two elements:
* a celestial body towards which some satellite axis is exactly aimed

* a phasing reference defining the rotation around the pointing axis

==== Fixed rate attitude law ====
The fixed rate attitude law handles a constant rate around a fixed axis.
This corresponding attitude provider performs a simple linear extrapolation from an initial orientation, a rotation axis and a rotation rate.

==== Constant attitude law ====
The satellite frame has a constant orientation in a given reference frame. This orientation is defined by a rotation provided by the user.

==== LOF offset attitude law ====
It is an attitude law defined by fixed Roll, Pitch and Yaw angles (in any order) with respect to a local orbital frame.

==== Spin stabilized attitude law ====
Spin stabilized attitude provider. Spin stabilized laws are handled as wrappers for an underlying non-rotating law.

==== Yaw compensation attitude law ====
Yaw compensation is mainly used for Earth observation satellites: as a satellite moves along its track, the image of ground points moves on the focal point of the optical sensor. This motion is a combination of the satellite motion, the Earth rotation and the current attitude (in particular if the pointing includes Roll or Pitch offset). 
In order to reduce geometrical distortion, the yaw angle is changed a little from the simple ground pointing attitude such that the apparent motion of ground points is along a prescribed axis (orthogonal to the optical sensor rows), taking into account all effects.

==== Yaw steering attitude law ====
Yaw steering is mainly used for low Earth orbiting satellites with no missions-related constraints on yaw angle. It sets the yaw angle in such a way the solar arrays have maximal lightning without changing the roll and pitch.

==== Two directions attitude law ====
The two directions provided by this attitude law are the following:
* the first direction is aligned with a given satellite axis;

* the second direction is aligned at best with another given satellite axis.

This attitude law can be used to represent the '''GAP''' (geocentric), and the '''SUP''' (heliocentric) pointing laws.

==== RelativeTabulatedAttitudeLaw ====
<code>RelativeTabulatedAttitudeLaw</code> is an implementation of <code>AttitudeLaw</code>. It is composed of a <code>AttitudeLegLaw:attitudeLegLaw</code> attribute defined by : 
- An instance of <code>RelativeTabulatedAttitudeLeg:leg</code> built with an <code>List<Pair<Double, Rotation>></code> (or an <code>List<Pair<Double, AngularCoordinates>>)</code> input. 
- Two instances of <code>AttitudeLaw</code> to apply if the input date is inferior or superior to the interval of validity of <code>leg</code>. These laws can be of two types : <code>ConstantAttitudeLaw</code> or <code>ExtrapolatedAttitudeLaw</code> (local private class of <code>RelativeTabulatedAttitudeLaw</code>).

The <code>ConstantAttitudeLaw</code> is created with the input frame of <code>RelativeTabulatedAttitudeLaw</code>, and the value of the rotation to the bound of the interval (minimum or maximum).

The <code>ExtrapolatedAttitudeLaw</code> is a local private class. It is an implementation of <code>AttitudeLaw</code>. It is created with an <code>AngularCoordinates</code> and the expression frame of this attitude. Its method <code>getAttitude()</code> returns <code>AngularCoordinates.shiftedBy(double)</code>.

The <code>ExtrapolatedAttitudeLaw</code> is created with : 
- the input frame of <code>RelativeTabulatedAttitudeLaw</code> 
- the <code>AngularCoordinates</code> to the bound of the interval (minimum or maximum). 
Here is an example of a creation of an instance of <code>RelativeTabulatedAttitudeLaw</code> :

<syntaxhighlight lang="java">

// build law before as a ConstantAttitudeLaw
final RelativeTabulatedAttitudeLaw.AroundAttitudetype lawBefore =
RelativeTabulatedAttitudeLaw.AroundAttitudetype.CONSTANT_ATT;

// build law after as a ExtrapolatedAttitudeLaw
final RelativeTabulatedAttitudeLaw.AroundAttitudetype lawAfter =
RelativeTabulatedAttitudeLaw.AroundAttitudetype.EXTRAPOLATED_ATT;

// build RelativeTabulatedAttitudeLaw
final RelativeTabulatedAttitudeLaw relativeTabulatedAttitudeLaw =
new RelativeTabulatedAttitudeLaw(refDate, listAr, frame, lawBefore, lawAfter);

</syntaxhighlight>

==== AeroAttitudeLaw ====
<code>AeroAttitudeLaw </code> is a law that aligns platform frame (Ox, Oy, Oz) with a frame defined by 3 angles: angle of attack, sideslip and velocity roll.
With the following conventions: 
- Platform frame is (Ox, Oy, Oz) with Ox along main frame, Oz in the symmetry plane of the aircraft toward up direction. 
- Velocity frame is (Oxv, Oyv, Ozv) with Oxv being along velocity and Ozv in the symmetry plane of the aircraft toward up direction. 
The three angles are defined in the following way: 
- Angle of attack is angle between (Oxv, Oyv) plane and Ox vector. 
- Sideslip is angle between Oxv vector and (Ox, Oz) symmetry plane 
- Velocity roll is angle around velocity vector.

==== AttitudeLegLaw ====
<code>AttitudeLegLaw</code> is an implementation of <code>AttitudeLaw</code>. It is composed of : an instance of <code>AttitudeLeg:leg</code>, an instance of <code>AttitudeLaw:lawbefore</code> and an other instance of <code>AttitudeLaw:lawAfter</code>. Its method <code>getAttitude(pvProv, date, frame)</code> returns : 
- <code>lawbefore.getAttitude(pvProv, date, frame)</code> is the date is inferior to the interval of validity of leg 
- <code>leg.getAttitude(pvProv, date, frame)</code> is the date is contained in the interval of validity of leg 
- <code>lawAfter.getAttitude(pvProv, date, frame)</code> is the date is superior to the the interval of validity of leg

=== Attitudes sequence ===
The attitudes sequence represents a sequence of several attitude laws (<code>AttitudeLaw</code> instances).

Unlike the <code>AttitudeLeg</code> objects, the <code>AttitudeLaw</code> instances do not have an interval of validity, therefore the switching from one law to another can not be based on time intervals.
For a given date, only one attitude law in the sequence is in an "active" state, so that the attitude of the spacecraft is computed from that attitude law. The laws are activated in turn according to some switching events, which are added to the sequence before starting the propagation.

Note that during the propagation, the previously used attitude legs are stored along with their validity intervals. Hence, the <code>AttitudesSequence</code> object always returns a consistent attitude for any given date in the past. The current active attitude leg is valid only since the last switch (or forever in the past if it is the first leg).

==== Building an attitudes sequence ====

Here is how an attitudes sequence is built:

* An empty attitudes sequence is created: <code>new AttitudesSequence()</code>;

* The attitudes laws that will compose the sequence are instantiated;

* The switching detectors are instantiated and set up using the <code>addSwitchingCondition(AttitudeLaw, EventDetector, boolean, boolean, AttitudeLaw)</code> command; in addition to the event detector, the previous and the next attitude laws associated to the switching condition are specified; Warning: switching detectors should have <code>Action.RESET_STATE</code> as action.

* The <code>registerSwitchEvents(Propagator)</code> method is called once before propagation, after the switching conditions have been set, in order to wrap switch events to the propagator.


[https://github.com/{{{owner|CNES}}}/{{{repo|patrius-tutorials}}}/{{{action|blob}}}/{{{branch|main}}}/{{{file|{{{1|src/main/java/attitudes/LOFOffsetAttitudeLaw.java}}}}}}#L56 {{{text|{{{2|Tutorial: LOFOffsetAttitudeLaw.java}}}}}}]

<noinclude>

==== Code sample ====

<syntaxhighlight lang="java">
final Frame gcrf = FramesFactory.getGCRF();

// Build the attitudes sequence:
final AttitudesSequence aseq = new AttitudesSequence();

final EventDetector switcherToTwo = new DateDetector(date.shiftedBy(100)) {
@Override
public Action eventOccurred(final SpacecraftState s, final boolean increasing, final boolean forward) throws PatriusException {
// Action.RESET_STATE is compulsory for the switch to be taken into account
return Action.RESET_STATE;
}
};

final EventDetector switcherToOne = new DateDetector(date.shiftedBy(200)) {
@Override
public Action eventOccurred(final SpacecraftState s, final boolean increasing, final boolean forward) throws PatriusException {
// Action.RESET_STATE is compulsory for the switch to be taken into account
return Action.RESET_STATE;
}
};

// Instantiate the attitude laws:
final AttitudeLaw lawOne = new LofOffset(gcrf, LOFType.QSW);
final AttitudeLaw lawTwo = new LofOffset(gcrf, LOFType.TNW);

// Add the switching detectors to the sequence:
aseq.addSwitchingCondition(lawTwo, switcherToOne, true, true, lawOne);
aseq.addSwitchingCondition(lawOne, switcherToTwo, true, true, lawTwo);

aseq.resetActiveProvider(lawOne);

// Properly register switching events to the propagator:
final Propagator propagator = new KeplerianPropagator(orbit, aseq);
aseq.registerSwitchEvents(propagator);

// Propagation:
propagator.propagate(date.shiftedBy(150));
</syntaxhighlight>

=== Attitude composition ===
The <code>ComposedAttitudeLaw</code> class allows to compose a main attitude law (implementing the <code>AttitudeLaw</code> interface) and one or several orientation laws (<code>IOrientationLaw</code> interface) whose purpose is to modify this law in order to obtain the "composed" attitude law.

It shall be created this way :

<syntaxhighlight lang="java">
// attitude law creation
AttitudeLaw attitudeLaw = new MyAttitudeLaw(...);

// orientation laws creation (modifiers)
IOrientationLaw orientationLaw1 = new AnyOrientationLaw(...);
IOrientationLaw orientationLaw2 = new AnyOtherOrientationLaw(...);

// modifiers list creation
final LinkedList<IOrientationLaw> modifiers = new LinkedList<IOrientationLaw>();

modifiers.add(orientationLaw1);
modifiers.add(orientationLaw2);

// composed attitude creation
final ComposedAttitudeLaw composedAtt = new ComposedAttitudeLaw(attitudeLaw, modifiers);
</syntaxhighlight>

The <code>ComposedAttitudeLaw</code> class implements the <code>AttitudeLawModifier</code> interface : it shall be used as any <code>AttitudeLaw</code>, and can also provide its "underlying attitude law" (the main attitude law used to build it).

Dedicated frames exist to describe those laws and are used to compute the composition :

* The <code>AttitudeFrame</code> is a frame defined by any attitude law (<code>AttitudeProvider</code>) and position velocity coordinates (<code>PVCoordinatesProvider</code>). At any date, its center is the position of the <code>PVCoordinatesProvider</code>, and its rotation from a reference frame is given by the attitude law.

* The <code>OrientationFrame</code> is defined from another <code>OrientationFrame</code> or from an <code>AttitudeFrame</code> by the corrections (<code>IOrientationLaw</code> objects) applied to them.

The <code>ComposedAttitudeLaw</code> class can be used to represent a biased geocentric pointing law ('''biased GAP'''): a geocentric attitude law is associated to a "modifier" that represents a constant rotation. This specific pointing law is used for the thrust: the bias added to the main pointing direction is the direction of the thrust.

== Getting Started ==
TBD

== Contents ==
=== Interfaces ===
{| class="wikitable"
|-
! scope="col"| Interface
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''AttitudeProvider'''
|This interface is the main interface of the attitudes package, it is related to the orbit determination field.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/AttitudeProvider.html ...]
|-
|'''AttitudeLaw'''
|This interface represents a generic attitude law provider, for which no interval of validity is specified.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/AttitudeLaw.html ...]
|-
|'''AttitudeLawModifier'''
|This interface represents an attitude law provider that modifies/wraps another underlying provider.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/AttitudeLawModifier.html ...]
|-
|'''IOrientationLaw'''
|Orientation law.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/IOrientationLaw.html ...]
|}

=== Classes ===

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''AbstractAttitudeLaw'''
|Abstract class representing the basic implementation of an attitude law provider.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/AbstractAttitudeLaw.html ...]
|-
|'''Attitude'''
|Object representing the attitude of the spacecraft for a specific date and in a specific frame.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/Attitude.html ...]
|-
|'''AttitudesSequence'''
|This class represents a sequence of attitude laws that are activated in turn according to switching events..
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/AttitudesSequence.html ...]
|-
|'''TwoDirectionAttitudeLaw'''
|This class implements a generic two directions attitude law. The first direction is aligned with a given satellite axis, the second direction is aligned at best with another given satellite axis.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/TwoDirectionAttitudeLaw.html ...]
|-
|'''AttitudeFrame'''
|Spacecraft frame (dynamic frame whose orientation is defined by the attitude law).
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/AttitudeFrame.html ...]
|-
|'''OrientationFrame'''
|Spacecraft orientation frame.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/OrientationFrame.html ...]
|-
|'''BodyCenterPointing'''
|This class implements a body center pointing attitude law: the satellite z axis is pointing to the body frame center.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/BodyCenterPointing.html ...]
|-
|'''BodyCenterGroundPointing'''
|This class implements a body center ground pointing attitude law: the satellite z axis is pointing to the ground pointing corresponding to the body frame center.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/BodyCenterGroundPointing.html ...]
|-
|'''CelestialBodyPointed'''
|This class handles a celestial body pointed attitude provider.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/CelestialBodyPointed.html ...]
|-
|'''FixedRate'''
|This class handles a simple attitude provider at constant rate around a fixed axis.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/FixedRate.html ...]
|-
|'''GroundPointing'''
|This class is a basic model for different kind of ground pointing attitude providers.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/GroundPointing.html ...]
|-
|'''GroundPointingWrapper'''
|This class leverages common parts for compensation modes around ground pointing attitudes.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/GroundPointingWrapper.html ...]
|-
|'''ConstantAttitudeLaw'''
|This class handles an constant attitude provider.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/ConstantAttitudeLaw.html ...]
|-
|'''LofOffset'''
|Attitude law defined by fixed Roll, Pitch and Yaw angles (in any order) with respect to a local orbital frame.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/LofOffset.html ...]
|-
|'''LofOffsetPointing'''
|This attitude pointing law is defined by an attitude provider and the satellite axis vector chosen for pointing.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/LofOffsetPointing.html ...]
|-
|'''NadirPointing'''
|This class handles nadir pointing attitude provider.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/NadirPointing.html ...]
|-
|'''SpinStabilized'''
|This class handles a spin stabilized attitude provider.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/SpinStabilized.html ...]
|-
|'''TargetPointing'''
|This class handles target pointing attitude provider.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/TargetPointing.html ...]
|-
|'''TargetGroundPointing'''
|This class handles target ground pointing attitude provider.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/TargetPointing.html ...]
|-
|'''YawCompensation'''
|This class handles yaw compensation attitude provider.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/YawCompensation.html ...]
|-
|'''YawSteering'''
|This class handles yaw steering attitude law.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/YawSteering.html ...]
|-
|'''ComposedAttitudeLaw'''
|Composed attitude law provider.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/ComposedAttitudeLaw.html ...]
|-
|'''DirectionTrackingOrientation'''
|One direction orientation law. This law has to be used within a composed attitude law as a law modifier.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/DirectionTrackingOrientation.html ...]
|-
|'''SunPointing'''
|This class implements a Sun pointing attitude law. The first direction is the satellite-sun direction, the second direction is either the sun poles axis or the normal to the satellite orbit plane.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/SunPointing.html ...]
|-
|'''IsisSunPointing'''
|This class implements a ISIS Sun pointing attitude law. The first direction is the satellite-sun direction (being the - Z_sun axis computed in GCRF frame), the second direction is the Y_sun axis computed in GCRF.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/IsisSunPointing.html ...]
|-
|'''AttitudeLegLaw'''
|This class implements an attitude leg, one attitude law before the leg and one attitude law after the leg.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/AttitudeLegLaw.html ...]
|-
|'''RelativeTabulatedAttitudeLaw'''
|This class implements a tabulated attitude leg with relative dates, with one attitude law before the leg and one attitude law after the leg.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/RelativeTabulatedAttitudeLaw.html ...]
|-
|'''AeroAttitudeLaw'''
|This class implements an aerodynamic attitude law defined by angle of attack, side slip and velocity roll.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/AeroAttitudeLaw.html ...]
|}

[[Category:User_Manual_4.17_Attitude]]

User Manual 4.17 Attitude leg

2025-11-26T13:55:49Z

Admin tsn : Page créée avec « __NOTOC__ == Introduction == === Scope === The purpose of this chapter is to describe the current Patrius attitude legs. An attitude leg is a time-bounded attitude law. Generalities on attitude laws can be found [ATT_ALW_Home here]. === Javadoc === {| class="wikitable" |- ! scope="col"| Library ! scope="col"| Javadoc |- |Patrius |[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/package-summary.html Package fr.cnes.sirius.patrius.attitudes] |- |Patrius |[{{Jav... »

__NOTOC__
== Introduction ==
=== Scope ===
The purpose of this chapter is to describe the current Patrius attitude legs.

An attitude leg is a time-bounded attitude law. Generalities on attitude laws can be found [ATT_ALW_Home here].

=== Javadoc ===
{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/package-summary.html Package fr.cnes.sirius.patrius.attitudes]
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/package-summary.html Package fr.cnes.sirius.patrius.attitudes]
|}

=== Links ===

Orekit attitudes : [https://www.orekit.org/static/architecture/attitudes.html Orekit Attitudes architecture description ]

=== Useful Documents ===
None as of now.

=== Package Overview ===
The attitude leg <code>AttitudeLeg</code> interface inherits the <code>AttitudeProvider</code> interface.
Its place in the global Attitude design can be found [ATT_ALW_PkgOverview here].
It also inherits the general <code>Leg</code> interface presented below.

== Features Description ==

=== Generalities: the Leg and the LegsSequence interfaces ===
Attitude legs inherit the interface <code>AttitudeLeg</code>.
In addition to <code>AttitudeProvider</code> services, they inherit the methods of the <code>Leg</code> interface which means they are time-bounded attitude providers.

The <code>Leg</code> interface is a generic interface for time-bounded timestamped data. It has only one method <code>getTimeInterval()</code> (as well as method allowing to retrieve start and end of interval). This <code>Leg</code> interface allows to define an <code>AttitudeLeg</code>.

In order to define an attitude sequence <code>StrictAttitudeLegsSequence</code>, another generic interface is available: the <code>LegsSequence</code> interface. This interface defines a sequence of <code>Leg</code> and provides methods to manipulate a collection of timestamped legs similarly to the <code>Collection</code> interface (methods <code>first()</code>, <code>next()</code>, etc.).
A implementation of <code>LegsSequence</code> is available: <code>StrictLegsSequence</code>. This class handles a sequence of legs which are strictly ordered (not overlapping is allowed), legs are ordered by their starting date.
The sequence of attitude legs <code>StrictAttitudeLegsSequence</code> inherits the <code>StrictLegsSequence</code> by considering legs as <code>AttitudeLegs</code>.

'''Note:''' the <code>Leg</code>and <code>LegsSequence</code>interfaces are purely generic and therefore can be used for any other time-bounded data.

=== Available attitude leg ===
==== Attitude legs sequence ====
An attitude legs sequence is a container for several attitude legs, contiguous for their time intervals, in such a way that the attitude legs sequence can be processed like a single attitude leg by the propagator.

The attitude legs sequence is the equivalent of the [ATT_ALW_Home#HAttitudessequence Attitudes sequence], using attitude legs (<code>AttitudeLeg</code> instances) rather than attitude laws (<code>AttitudeLaw</code> instances).
The switching from one attitude leg to another is based on the time interval of validity of the two legs.

==== TabulatedAttitude ====
<code>TabulatedAttitude</code> is an implementation of <code>AttitudeLeg</code>. It represents a tabulated attitude leg.

In order to interpolate the attitude at a date, the user must specify a list of '''ordered''' attitudes, and can specify a number of points used by Hermite interpolation.
If not specified, the number of points used by Hermite interpolation is set to a default number (currently 2).
<syntaxhighlight lang="java">
final List<Attitude> attList = new ArrayList<Attitude>();
attList.add(attitude0);
attList.add(attitude1);
final int nbrInterpPoints = 2;
final TabulatedAttitude attLeg = new TabulatedAttitude(attList, nbrInterpPoints);
</syntaxhighlight>

It is possible to get the non-interpolated ordered attitudes :
<syntaxhighlight lang="java">
final List<Attitude> attitudes = attLeg.getAttitudes();
</syntaxhighlight>

Once the tabulated is defined, the computation can be performed on any orbital state using <code>getAttitude()</code> method:
<syntaxhighlight lang="java">
Attitude attitude = attLeg.getAttitude(orbit, date, FramesFactory.getEME2000());
</syntaxhighlight>

==== RelativeTabulatedAttitudeLeg ====
<code>RelativeTabulatedAttitudeLeg</code> is an implementation of <code>AttitudeLeg</code>. An instance of <code>RelativeTabulatedAttitudeLeg</code> can be created with a <code>List<Pair<Double, Rotation>></code> or with a <code>List<Pair<Double, AngularCoordinates>></code>. Each <code>Rotation</code> (or <code>AngularCoordinates</code>) is associated with a <code>double</code> representing its time ellapsed in seconds since the reference date. Here is an example of a creation of an instance of <code>RelativeTabulatedAttitudeLeg</code> :

<syntaxhighlight lang="java">
// date and frame
AbsoluteDate refDate = new AbsoluteDate(2008, 1, 1, TimeScalesFactory.getTAI());
Frame frame = FramesFactory.getGCRF();
double timeEllapsedSinceRefDate = 1.0;

// List of AR
List<Pair<Double, AngularCoordinates>> listAr = new ArrayList<Pair<Double, AngularCoordinates>>();
final AngularCoordinates ar = new AngularCoordinates(
new Rotation(false, 0.48, 0.64, 0.36, 0.48), Vector3D.PLUS_I, Vector3D.PLUS_J);
listAr.add(new Pair<Double, AngularCoordinates>(timeEllapsedSinceRefDate, ar));

// create RelativeTabulatedAttitudeLeg
final RelativeTabulatedAttitudeLeg relativeTabulatedAttitudeLeg =
new RelativeTabulatedAttitudeLeg(refDate, frame, listAr);
</syntaxhighlight>

== Getting Started ==
=== Building an attitude legs sequence ===

The attitude legs sequence was designed as a simple container, it performs only a few coherence checks on its inner attitude laws. Here's how an attitude sequence is built.

* An attitude legs sequence is created empty, associated to a single <code>PVCoordinatesProvider</code> instance.

* The sequence is mutable, attitude laws can be added to it one by one.

* Each attitude law is identified by a code.

* The sequence has a validity time interval, which is the grouping of the validity time intervals of all contained laws.

* The time interval of a newly added law must be contiguous to the grouped time interval of the already added laws. Otherwise an PatriusException is thrown.

* As soon as the sequence contains at least one law, methods of the <code>AttitudeLeg</code> interface can be called on the attitude sequence. The attitude sequence forwards the request to the appropriate attitude leg (according to the asking date), but replaces the <code>PVCoordinatesProvider</code> attribute of the call with the inner <code>PVCoordinatesProvider</code> instance.

=== AttitudeLawLeg and AttitudeLegsSequence : Code sample ===

<syntaxhighlight lang="java">
final BodyCenterPointing earthCenterAttitudeLaw = new BodyCenterPointing(itrf);
final AttitudeLeg law1 = new AttitudeLawLeg(earthCenterAttitudeLaw, date1, date2);
final AttitudeLeg law2 = ... ;
final AttitudeLeg law3 = ... ;

PVCoordinatesProvider pvProvider = new CartesianOrbit(pvCoordinates, gcrf, date1, mu);
final StrictAttitudeLegsSequence sequence = new StrictAttitudeLegsSequence(pvProvider);
sequence.add(law1);
sequence.add(law2);
sequence.add(law3);

// Call to getAttitude on the sequence
final Attitude attitude = sequence.getAttitude(pvProvider, date, itrf);
</syntaxhighlight>

== Contents ==
=== Interfaces ===
{| class="wikitable"
|-
! scope="col"| Interface
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''Leg'''
|This interface is a generic interface for any king of time-bounded data.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/utils/legs/Leg.html ...]
|-
|'''LegsSequence'''
|This interface is a generic interface for any sequence of legs.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/utils/legs/LegsSequence.html ...]
|-
|'''AttitudeLeg'''
|This interface extends the AttitudeProvider interface and adds the time interval of validity notion to the attitude laws.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/AttitudeLeg.html ...]
|}

=== Classes ===
{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''StrictLegsSequence'''
|This class is a generic class for handling any sequence of legs.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/utils/legs/StrictLegsSequence.html ...]
|-
|'''AttitudeLawLeg'''
|Object representing an attitude law for spacecraft attitude field purposes.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/AttitudeLawLeg.html ...]
|-
|'''TabulatedAttitude'''
|Object representing a tabulated attitude leg : the attitude at a date is interpolated from a list of known ones.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/TabulatedAttitude.html ...]
|-
|'''StrictAttitudeLegsSequence'''
|Object representing a sequence of attitude legs.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/StrictAttitudeLegsSequence.html ...]
|-
|'''RelativeTabulatedAttitudeLeg'''
|This class implements a tabulated attitude leg with relative dates.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/RelativeTabulatedAttitudeLeg.html ...]
|}

[[Category:User_Manual_4.17_Attitude]]

User Manual 4.17 Attitude Profile

2025-11-26T13:55:33Z

Admin tsn : Page créée avec « __NOTOC__ == Introduction == === Scope === An attitude profile is an attitude law providing the computation of an instantaneous attitude without any reference to the satellite orbit, nor to its attitude laws sequence. The purpose of this section is to present the attitude profiles available through the Patrius library. === Javadoc === The guidance models and classes are available in the attitude profiles package in the Patrius library. {| class="wikitable" |- !... »

__NOTOC__
== Introduction ==
=== Scope ===
An attitude profile is an attitude law providing the computation of an instantaneous attitude without any reference to the satellite orbit, nor to its attitude laws sequence. The purpose of this section is to present the attitude profiles available through the Patrius library.

=== Javadoc ===
The guidance models and classes are available in the attitude profiles package in the Patrius library.

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/profiles/package-summary.html Package fr.cnes.sirius.patrius.attitudes/profiles]
|}

=== Links ===
None as of now.

=== Useful Documents ===
None as of now.

=== Package Overview ===

== Features Description ==

PATRIUS handles different guidance profiles types:
* Profile expressed as quaternions represented as polynomials by means of UnivariateFunction: <code>QuaternionPolynomialProfile</code>
* Profile expressed as quaternions represented as polynomials by means of DatePolynomialFunctionInterface: <code>QuaternionDatePolynomialProfile</code>
* Profile expressed as quaternions represented as harmonics: <code>QuaternionHarmonicProfile</code>
* Profile expressed as angular velocities represented as polynomials: <code>AngularVelocitiesPolynomialProfile</code>
* Profile expressed as angular velocities represented as harmonics: <code>AngularVelocitiesHarmonicProfile</code>

=== Harmonic guidance profiles ===
The functions representing the angular velocity of the satellite and the quaternion (or the Euler angles) expressing its orientation can be represented by an harmonic profile.
The harmonic profile is a [MAT_TPOL_Home#HFourierSeries Fourier decomposition] of a periodic function:

<math>
S_n\left(f(x)\right) = a_0(f) + \sum_{k=1}^n\left(a_k(f)\cos\left(k x {2\pi\over T}\right) + b_k(f)\sin\left(k x {2\pi\over T}\right)\right)
</math>

The period T is generally computed knowing the nodes crossing periods.

The Fourier coefficients (n > 0) of <math>f</math> (the angular velocity / quaternions / Euler angles function) are given by :

<math>
a_0(f) = {1\over T}\int_{-T/2}^{T/2} \! f(t) \, \mathrm{d}t
</math>

<math>
b_0(f) = 0
</math>

<math>
a_n(f) = {2\over T}\int_{-T/2}^{T/2} \! f(t) \cos\left(n t {2\pi\over T}\right) \, \mathrm{d}t
</math>

<math>
b_n(f) = {2\over T}\int_{-T/2}^{T/2} \! f(t) \sin\left(n t {2\pi\over T}\right) \, \mathrm{d}t
</math>

=== Polynomial guidance profiles ===
A polynomial guidance profile is generally composed by several segments (a segment corresponds to a time interval). Each segment contains the coefficients for the computation of a polynomial law representing the quaternion (or the Euler angles), or the angular velocity of the satellite; this polynomial law is valid only inside the time interval associated to the segment.

For a quaternion, the polynomials are defined as :

<math>Qc_k(t) = \begin{pmatrix}
\displaystyle\sum_{i=0}^n {a_0}_k^i \left( t-t_k \over {\Delta t} \right) \\
\displaystyle\sum_{i=0}^n {a_1}_k^i \left( t-t_k \over {\Delta t} \right) \\
\displaystyle\sum_{i=0}^n {a_2}_k^i \left( t-t_k \over {\Delta t} \right) \\
\displaystyle\sum_{i=0}^n {a_3}_k^i \left( t-t_k \over {\Delta t} \right)
\end{pmatrix}</math>

And for the angular velocity :

<math>\Omega c_k(t) = \begin{pmatrix}
\displaystyle\sum_{i=0}^n {a_x}_k^i \left( \frac{t-t_k}{\Delta t} \right) \\
\displaystyle\sum_{i=0}^n {a_y}_k^i \left( \frac{t-t_k}{\Delta t} \right) \\
\displaystyle\sum_{i=0}^n {a_z}_k^i \left( \frac{t-t_k}{\Delta t} \right)
\end{pmatrix}</math>

== Getting Started ==

=== Build an harmonic profile from an attitude law ===

Given :
* the profile start date <code>origin</code>,
* the frame of expression <code>frame</code>,
* the Fourier series for each quaternion <code>q0</code>, <code>q1</code>, <code>q2</code> and <code>q3</code>,
* the profile time boundaries <code>timeInterval</code>,

one can build an angular velocities guidance profile using the code snippet below :

<syntaxhighlight lang="java">
profile = new QuaternionHarmonicProfile(origin, frame, q0, q1, q2, q3, timeInterval);
</syntaxhighlight>

== Contents ==
=== Interfaces ===

{| class="wikitable"
|-
! scope="col"| Interface
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''AttitudeProfile'''
|Interface for all attitude profiles.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/profiles/AttitudeProfile.html ...]
|}

=== Classes ===

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''QuaternionHarmonicProfile'''
|Object representing a quaternion guidance profile, calculated with Fourier series.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/guidance/QuaternionHarmonicProfile.html ...]
|-
|'''QuaternionPolynomialProfile'''
|Object representing a quaternion guidance profile, calculated with polynomials by means of QuaternionPolynomialSegment.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/guidance/QuaternionPolynomialProfile.html ...]
|-
|'''QuaternionDatePolynomialProfile'''
|Object representing a quaternion guidance profile, calculated with polynomials by means of QuaternionDatePolynomialSegment.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/guidance/QuaternionDatePolynomialProfile.html ...]
|-
|'''QuaternionPolynomialSegment'''
|Object representing a quaternion polynomial guidance profile on a segment by means of UnivariateFunction.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/guidance/QuaternionPolynomialSegment.html ...]
|-
|'''QuaternionDatePolynomialSegment'''
|Object representing a quaternion polynomial guidance profile on a segment by means of DatePolynomialFunctionInterface.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/guidance/QuaternionDatePolynomialSegment.html ...]
|-
|'''AngularVelocitiesHarmonicProfile'''
|Represents an angular velocities guidance profile, calculated with Fourier series.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/guidance/AngularVelocitiesHarmonicProfile.html ...]
|-
|'''AngularVelocitiesPolynomialProfile'''
|Represents an angular velocities guidance profile, calculated with polynomial functions.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/guidance/AngularVelocitiesPolynomialProfile.html ...]
|-
|'''AngularVelocitiesPolynomialProfileLeg'''
|Object representing an angular velocity polynomial guidance profile on a segment.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/guidance/AngularVelocitiesPolynomialProfileLeg.html ...]
|}

[[Category:User_Manual_4.17_Attitude]]

User Manual 4.17 Directions

2025-11-26T13:55:18Z

Admin tsn : Page créée avec « __NOTOC__ == Introduction == === Scope === The “direction” objects are used for attitude computation purposes to describe different types of axis in space that can evolve in time. A direction provides a vector in space at any date in a given frame. A direction can be for example "spacecraft-moon" or "nadir direction of the spacecraft". An attitude law can then be defined using two of those directions. All available directions belong to the following categori... »

__NOTOC__
== Introduction ==
=== Scope ===
The “direction” objects are used for attitude computation purposes to describe different types of axis in space that can evolve in time. A direction provides a vector in space at any date in a given frame.
A direction can be for example "spacecraft-moon" or "nadir direction of the spacecraft".
An attitude law can then be defined using two of those directions.

All available directions belong to the following categories:
* Defined by a "target" moving point, and a given origin point;

* Defined by a vector only known to be constant in time in a particular frame, or defined by a physical property.

The available features are listed in the description of the general <code>IDirection</code> interface or of the more specific <code>ITargetDirection</code> interface (for directions pointing a target).

=== Javadoc ===
The directions are available in the package <code>fr.cnes.sirius.patrius.attitudes.directions</code> of the PATRIUS library.

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/package-summary.html Package fr.cnes.sirius.patrius.attitudes.directions]
|}

=== Links ===
None as of now.

=== Useful Documents ===
None as of now.

=== Package Overview ===
The following diagram represents the two main interfaces of the "directions" package, and for each interface some of the implemented directions.

Please note that not all implementations are present in the following diagram for the sake of clarity.

[[File:PATRIMOINESIRIUSdirections.png]]

== Features Description ==
=== Directions ===
The available directions are:

==== Basic direction ====
This direction is defined at any date by a vector; this vector can be constant in a frame, or it can be defined by a physical property (for instance the axis of the poles of a celestial body, the orbit momentum, the velocity vector...).

The <code>getVector</code> and <code>getLine</code> methods of this interface use a <code>PVCoordinatesProvider</code> to represent the origin of the direction, but for some of them this input parameter is unused (for instance for the poles of a celestial body direction). See each javadoc for the associated behavior.

All directions can also provide the line containing the given origin and directed by the vector, expressed in any frame of the tree.

===== Ground velocity direction =====
This direction is used for instance when it comes to take pictures of the ground. To avoid distortion, the satellite has to compensate the earth rotation around its yaw axis. On the following drawing, the red direction is the one that has to be followed to compensate the earth rotation.

[[File:vitsol.png|center]]

==== Target direction ====
This direction also implements the methods of basic directions.
It is defined at any date by the position of two points of space: the target (that defines the direction) and the origin given by the user. The associated vector (and line) is computed from the origin to the target.

=== Aberration corrections ===
The available aberration corrections are:
* NONE: no aberration correction is applied.
* LIGHT_TIME: the light-time aberration correction is applied. This aberration correction takes into account the apparent displacement of the source (from the receiver point of view) or of the observer (from the transmitter point of view) during the time of propagation.
* STELLAR: the stellar aberration correction is applied. This aberration correction takes into account the observer velocity at reception time (from the receiver point of view) or the source velocity at transmission time (from the transmitter point of view).
* ALL: both the light-time and the stellar aberration corrections are applied.

== Getting Started ==

=== Use ===
==== For all directions ====

All the directions implement the "IDirection" interface and so provide the "getVector" method. This method needs a date and a frame to express the vector, and the PV coordinates of the origin point (unused for some of them). It shall be used this way :

<syntaxhighlight lang="java">
Vector3D directionVector = myDirection.getVector(pvCoordinatesProvider, date, frame);
</syntaxhighlight>

They also provide the "getLine" method, with the same arguments.

<syntaxhighlight lang="java">
Line directionLine = myDirection.getLine(pvCoordinatesProvider, date, frame);
</syntaxhighlight>

NB : when the PVCoordinatesProvider is null then the origin of the direction is tacitly the frame origin.

==== For target directions ====

The directions that implement the "ITargetDirection" interface also provide the "getTarget" method :

<syntaxhighlight lang="java">
PVCoordinates directionTarget = myTargetDirection.getTargetPVCoordinates(date, frame);
</syntaxhighlight>

== Contents ==
=== Interfaces ===
{| class="wikitable"
|-
! scope="col"| Interface
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''IDirection '''
|General interface for all directions classes. All basic directions implement it.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/directions/IDirection.html ...]
|-
|'''ITargetDirection'''
|This interface extends IDirection for the particular case of directions defined by a target point. The vector's direction is oriented from the given origin to the target.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/directions/ITargetDirection.html ...]
|}

=== Classes ===
{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''ConstantVectorDirection'''
|Vector constant in one of the frames of the tree.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/directions/ConstantVectorDirection.html ...]
|-
|'''VelocityDirection'''
|Velocity of the origin point expressed in a reference frame, projected in the given one.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/directions/VelocityDirection.html ...]
|-
|'''MomentumDirection'''
|Momentum : normal vector to the trajectory plane of the origin point around a celestial body.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/directions/MomentumDirection.html ...]
|-
|'''CelestialBodyPolesAxisDirection'''
|Axis of the poles of a celestial body.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/directions/CelestialBodyPolesAxisDirection.html ...]
|-
|'''ToCelestialBodyCenterDirection'''
|Vector from the origin to the center of a celestial body.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/directions/ToCelestialBodyCenterDirection.html ...]
|-
|'''EarthCenterDirection'''
|Vector from the origin to the center of the Earth central body.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/directions/EarthCenterDirection.html ...]
|-
|'''GenericTargetDirection'''
|Defined by a PVCoordinatesProvider target.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/directions/GenericTargetDirection.html ...]
|-
|'''BodyPointTargetDirection'''
|Defined by target which is a BodyPoint on a BodyShape.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/directions/BodyPointTargetDirection.html ...]
|-
|'''GroundVelocityDirection'''
|Defined by the location of the ground target point given by the pointing direction of the satellite and the body shape.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/directions/GroundVelocityDirection.html ...]
|-
|'''NadirDirection'''
|Defined by the location of the nadir point and the satellite position.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/directions/NadirDirection.html ...]
|-
|'''CrossProductDirection'''
|Cross Product of two directions.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/directions/CrossProductDirection.html ...]
|-
|'''GlintApproximatePointingDirection'''
|Direction to the Sun specular reflexion point.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/directions/GlintApproximatePointingDirection.html ...]
|-
|'''EarthToCelestialBodyCenterDirection'''
|Direction from Earth to the celestial body center.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/directions/EarthToCelestialBodyCenterDirection.html ...]
|}

[[Category:User_Manual_4.17_Attitude]]

User Manual 4.17 Kinematics

2025-11-26T13:54:50Z

Admin tsn : Page créée avec « __NOTOC__ == Introduction == === Scope === The purpose is to extend the attitude package with classes and methods to compute and process kinematics operations. === Javadoc === The kinematics objects are available in the package fr.cnes.sirius.patrius.attitudes.kinematics. {| class="wikitable" |- ! scope="col"| Library ! scope="col"| Javadoc |- |Orekit |[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/kinematics/package-summary.html Package fr.cnes.sirius.patr... »

__NOTOC__
== Introduction ==
=== Scope ===
The purpose is to extend the attitude package with classes and methods to compute and process kinematics operations.

=== Javadoc ===
The kinematics objects are available in the package fr.cnes.sirius.patrius.attitudes.kinematics.

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
|Orekit
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/kinematics/package-summary.html Package fr.cnes.sirius.patrius.attitudes.kinematics]
|}

=== Links ===
None as of now.

=== Useful Documents ===
None as of now.

=== Package Overview ===
The following diagram represents the main classes of the package :
<code>fr.cnes.sirius.patrius.attitudes.kinematics</code>.

Please note that not all implementations are present in the following diagram for the sake of clarity.

[[File:kinematics.png|center]]

== Features Description ==
=== Quaternions differentiation ===
A quaternion can be differentiated using various methods:

* The quaternion differentiation’s formula <math>\dot{Q}_{S/R} = \frac{1}{2}Q_{S/R}\Omega_{S/R}^{[S]}</math>.
This formula connects time derivative of the quaternion q(t) with the vector of angular velocity W(t).

* When the quaternion is represented by a set of differentiable functions (Fourier series or polynomials), a direct analytic computation can be performed to get its derivative;

* Numerical differentiation (using finite difference, Ridders differentiation method, ...)

=== Quaternion integration ===
A rotation can be integrated, knowing its spin time function, using these methods:
* Wilcox method, with available approximations orders 1 to 4
* Edwards method, that corresponds to an order 3 approximation

=== Spin computation ===
The spin can be represented by a vector (instantaneous spin), or by a time-dependent function.
The computation of the instantanous value of the spin can be made by one of the following methods:

* estimate the spin from two rotations corresponding to two different dates;
* using the kinematics equation when a quaternion and its derivative are known;
* compute the spin from the Euler or Cardan angles and their derivatives;
* using a direct analytic computation (when the function representing its variation over time is available).

=== Time-dependent orientation function===
The interface <code>OrientationFunction</code> and the abstract class <code>AbstractOrientationFunction</code> have been added to the kinematics package in order to represent a time-dependent orientation function.

These classes provide the following functionalities:

* return the orientation at a date, by the <code>getOrientation(AbsoluteDate)</code> method; it is an abstract method because it is specific to the orientation (or attitude) law the user wants to implement;

* return the function representing the derivative of the quaternion components, by the <code>derivative()</code> method. A numerical differentiation method is used to compute the derivatives, nevertheless the classes inheriting the <code>AbstractOrientationFunction</code> can override this method and return the analytical function representing the derivatives, when possible.

* compute the function representing the spin using the <math>\Omega_{S/R}^{[S]} = 2Q_{S/R}\dot{Q}_{S/R}</math> formula, by the <code>computeSpinFunction()</code> method. The derivatives of the quaternion are computed thanks to the <code>derivative()</code> method.

* estimate the function representing the spin using two rotations corresponding to two different dates (the velocity is supposed to be constant during the time interval between the two rotations), by the <code>estimateRateFunction(dt)</code> method.

* return the spin at a date, by the <code>computeSpin(AbsoluteDate)</code>, or <code>estimateRate(AbsoluteDate, dt)</code> methods (they call the <code>computeSpinFunction()</code> and <code>estimateRateFunction(dt)</code> methods)

=== Time-dependent spin function===
The interface <code>Vector3DFunction</code> and the abstract class <code>AbstractVector3DFunction</code> have been added to the kinematics package in order to represent a time-dependent vector 3D function; a vector 3D function is used to represent the spin, or the n-th derivative of the spin.

These classes provide the following functionalities:

* return the vector at a date, by the <code>getVector3D(AbsoluteDate)</code> method; it is an abstract method because it is specific to the spin (or derivative of the spin) the user wants to implement;

* return the function representing the n-th derivative of the vector, by the <code>nthDerivative(order)</code> method. A numerical differentiation method is used to compute the derivatives, nevertheless the classes inheriting the <code>AbstractVector3DFunction</code> can override this method and return the analytical function representing the derivatives, when possible.
This method uses the classes contained in the differentiation package, in particular the <code>DerivativeStructure</code> class, which allows to compute the n-th derivatives of a function at a point;

* return the integral of the function by the <code>integral(x0, xf)</code> method. A numerical integration method is used to compute the integral, nevertheless the classes inheriting the <code>AbstractVector3DFunction</code> can override this method and return the analytical function representing the integral, when possible.

The <code>DynamicsElements</code> object is created from a spin function and it gathers the n-th derivatives of spin at a given date; an attribute of this class is contained in the <code>Attitude</code> class.

=== Differentiate a quaternion ===
As a time-dependent quaternion can be represented by the <code>OrientationFunction</code> interface, the derivative of the quaternion can be computed using the <code>derivative()</code> method. As this method is implemented by the user, he can choose to use a numerical differentiation method or to compute the exact derivative, when possible.

The derivative of a quaternion can be also computed using the kinematics equation: <math>\dot{Q}_{S/R} = \frac{1}{2}Q_{S/R}\Omega_{S/R}^{[S]}</math>. 
This equation is implemented by the following method in the kinematics toolkit:

<syntaxhighlight lang="java">public static Quaternion differentiateQuaternion(final Quaternion q, final Vector3D spin)</syntaxhighlight>

=== Integrate a quaternion ===
The rotation integration is to be made by the class <code>AngularVelocitiesPolynomialProfileLeg</code>. This class requires to provide the integration method (Wilcox up to order 4 or Edwards) as well as the angular rate on each component.

=== Differentiate and integrate a vector ===
In a similar way to the orientation function, a new class has been added in order to represent a time-dependent 3-D vector function. This class implements the <code>Vector3DFunction</code> interface, and it contains the methods to compute the derivative of the vector or its integral over a time period. The computation can be done using a numerical method or it can be analytical, when possible.

=== Compute the spin ===
The Kinematics package contains some methods aiming to compute the instantaneous spin. These methods are listed hereafter:

* Estimation: two rotations corresponding to two different dates are used to compute the spin (the velocity is supposed to be constant during the time interval between the two rotations).
This function is implemented by the following method in the kinematics toolkit:

<syntaxhighlight lang="java">public static Vector3D estimateSpin(final Rotation start, final Rotation end, final double dt)</syntaxhighlight>.

* <math>\Omega_{S/R}^{[S]} = 2Q_{S/R}\dot{Q}_{S/R}</math>, when knowing the derivative of the quaternion.
This equation is implemented by the following kinematics toolkit method:

<syntaxhighlight lang="java">public static Vector3D computeSpin(final Quaternion q, final Quaternion qd)</syntaxhighlight>.

* Using the derivative of the Euler or Cardan angles:
** Euler (not to be used when the angles are small):
<math>\Omega_{S/R}^{[S]} = \left[ \begin{array}{c} \dot{\psi}\sin(\theta)\sin(\phi) + \dot{\theta}\cos(\phi) \\ \dot{\psi}\sin(\theta)\cos(\phi)- \dot{\theta}\sin(\phi) \\ \dot{\psi}\cos(\theta) + \dot{\phi} \end{array} \right]</math>
** Cardan (only to be used when the angles are small):
<math>\Omega_{S/R}^{[S]} = \left[ \begin{array}{c}-\dot{\psi}\sin(\theta)+\dot{\phi} \\ \dot{\psi}\cos(\theta)\sin(\phi) + \dot{\theta}\cos(\phi) \\ \dot{\psi}\cos(\theta)\cos(\phi) - \dot{\theta}\sin(\phi) \end{array} \right]</math>

These formula are implemented by the following kinematics toolkit method:

<syntaxhighlight lang="java">public static Vector3D computeSpin(final double[] ang, final double[] angd, final RotationOrder order)</syntaxhighlight>.

* Analytic computation: if the spin is represented by a function, its instantaneous value must be obtained by direct analytic computation (the <code>IVector3DFunction</code> classes have been created for this purpose)

== Getting Started ==
TBD

== Contents ==
=== Interfaces ===
{| class="wikitable"
|-
! scope="col"| Interface
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''OrientationFunction'''
|This interface represents a generic univariate orientation function.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/kinematics/OrientationFunction.html ...]
|-
|'''Vector3DFunction'''
|This interface represents a generic univariate 3-D vector function.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/kinematics/Vector3DFunction.html ...]
|}

=== Classes ===

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''AbstractOrientationFunction'''
|This class represents an orientation function.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/kinematics/AbstractOrientationFunction.html ...]
|-
|'''AbstractVector3DFunction'''
|This class represents a spin function, or a spin n-th derivative function.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/kinematics/AbstractVector3DFunction.html ...]
|}

[[Category:User_Manual_4.17_Attitude]]

User Manual 4.17 Orientation

2025-11-26T13:54:10Z

Admin tsn : Page créée avec « __NOTOC__ == Introduction == === Scope === The purpose of this chapter is to describe the orientation package. An orientation provider is an interface that provides methods to return an angle as a function of a spacecraft state. === Javadoc === {| class="wikitable" |- ! scope="col"| Library ! scope="col"| Javadoc |- |Patrius |[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/orientations/package-summary.html Package fr.cnes.sirius.patrius.attitudes.orientation... »

__NOTOC__
== Introduction ==
=== Scope ===
The purpose of this chapter is to describe the orientation package.

An orientation provider is an interface that provides methods to return an angle as a function of a spacecraft state.

=== Javadoc ===
{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/orientations/package-summary.html Package fr.cnes.sirius.patrius.attitudes.orientations]
|}

=== Links ===
None as of now.

=== Useful Documents ===
None as of now.

=== Package Overview ===

== Features Description ==
The orientations package is designed similarly to attitude providers:
* An interface <code>OrientationAngleProvider</code> returns an angle given a spacecraft state (similarly to <code>AttitudeProvider</code> which returns an Attitude)
* An interface <code>OrientationAngleLaw</code> gathers orientation laws and is similar to <code>AttitudeLaw</code>
* An interface <code>OrientationAngleLeg</code> is a time-bounded leg and is similar to <code>AttitudeLeg</code>
* An interface <code>OrientationAngleProfile</code> is a profile of orientation angles and is similar to <code>AttitudeProfile</code>
* A class <code>OrientationAngleLawLeg</code> is a law leg and is similar to <code>AttitudeLawLeg</code>
* A class <code>OrientationAngleLawLegsSequence</code> is a sequence of <code>OrientationAngleLawLeg</code> and is similar to <code>AttitudeLawLegsSequence</code>
* A class <code>OrientationAngleProfileSequence</code> is a sequence of <code>OrientationAngleProfile</code> and is similar to <code>AttitudeProfileSequence</code>

Note: the package currently does not provide any implementation of <code>OrientationAngleProvider</code> interface except for constant angles.

== Getting Started ==
Use is identical to attitudes. See the [[Catégorie:User Manual 4.4 Attitude|Attitude]] page for examples.

== Contents ==
=== Interfaces ===
{| class="wikitable"
|-
! scope="col"| Interface
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''OrientationAngleProvider'''
|Interface for all orientation angles providers.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/orientations/OrientationAngleProvider.html ...]
|-
|'''OrientationAngleLaw'''
|Interface for all orientation angles lasw.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/orientations/OrientationAngleLaw.html ...]
|-
|'''OrientationAngleLeg'''
|Interface for all orientation angles legs.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/orientations/OrientationAngleLeg.html ...]
|-
|'''OrientationAngleProfile'''
|Interface for all orientation angles profiles.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/orientations/OrientationAngleProfile.html ...]
|}

=== Classes ===
{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''OrientationAngleLawLeg'''
|Orientation angle law leg.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/OrientationAngleLawLeg.html ...]
|-
|'''OrientationAngleLawLegsSequence'''
|Sequence of Orientation angle legs.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/OrientationAngleLawLegsSequence.html ...]
|-
|'''OrientationAngleProfileSequence'''
|Sequence of Orientation angle profiles.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/OrientationAngleProfileSequence.html ...]
|}

[[Category:User_Manual_4.17_Attitude]]

Catégorie:User Manual 4.17 Flight Dynamics

2025-11-26T13:52:03Z

Admin tsn : Page créée avec «  == Introduction == In order to determine the position and velocity of a spacecraft at a given time, a reference frame with respect to which position and velocity as well as appropriate systems of coordinates and time measurements are required. These elements underpin the physical model that describes the dynamic system. The fundamentals of orbital mechanics have evolved over centuries and require evermore improvements to the dynamical models and coordinate and t... »

== Introduction ==
In order to determine the position and velocity of a spacecraft at a given time, a reference frame with respect to which position and velocity as well as appropriate systems of coordinates and time measurements are required. These elements underpin the physical model that describes the dynamic system. The fundamentals of orbital mechanics have evolved over centuries and require evermore improvements to the dynamical models and coordinate and time systems.

[[File:referenceframe.gif|center]]

Time has evolved from using the motion of the Sun to describe the fundamental unit of time to the current use of atomic clocks to define the second.

At first based on Solar motion, time representation and measurement systems have considerably changed and currently involve measuring seconds with atomic clocks.

Definitions of reference frames and reference systems have also considerably changed with the IERS standards and are more and more accurate. As observational accuracy has increased, models have generally increased in complexity, taking into consideration more and more details.

== Applicable and Reference Documents ==

=== Applicable Documents ===

'''[A1]''' ''CDCF - Fonctions de Base du Patrimoine de Dynamique du Vol'', V1.2, SIRIUS-CF-DV-0049-CN, 2011. 
'''[A2]''' ''Dossier de réutilisation Orekit et Commons Math'', V1.0, SIRIUS-DLR-DV-0080-CN, 2010.

=== Reference Documents ===

'''[R1]''' ''IERS website [http://www.iers.org/nn_10968/IERS/EN/IERSHome/home.html?__nnn=true].'' 
'''[R2]''' ''Spaceflight Dynamics'', Part I, Jean-Pierre Carrou, edition 1995, chapter 10.4.5.'' 
'''[R3]''' ''JPL FTP server: [ftp://ssd.jpl.nasa.gov/pub/eph/planets/]''.

== Glossary ==
{| class="wikitable"
|-
|'''CIRF'''
|Celestial Intermediate Reference Frame
|-
|'''DE'''
|Development Ephemerides
|-
|'''ERA'''
|Earth Rotation Angle
|-
|'''GCRF'''
|Geocentric Celestial Reference Frame
|-
|'''IERS'''
|Development Ephemerides
|-
|'''ITRF'''
|International Terrestrial Reference Frame
|-
|'''JPL'''
|Jet Propulsion Laboratory
|-
|'''TIRF'''
|Terrestrial Intermediate Reference Frame
|-
|'''UT1'''
|Universal Time
|-
|'''UTC'''
|Coordinated Universal Time
|-
|}

== Overview ==
The flight dynamics basis of the PATRIUS library are mainly based on the packages bodies, frames, time and orbits of original OREKIT. Some evolutions have been brougth to meet the SIRIUS Scope Statement '''[A1]''', for instance, the topocentric frame has been slightly modified and two objects have been created in order to represent a topocentric mounting and a Cardan mounting.

Several themes are developped in this section :

* IERS conventions : this chapter is dedicated to the use of the IERS frames in Orekit. Its purpose is to help the user avoid some traps and know what to numerical precision to expect from subsequent computations.

* Topocentric frame : this chapter deals with the modifications brought to the TopocentricFrame object and how to use it.

* Body shape : this chapter explains how a body model can be constructed. The one-axis ellipsoid model is available. In this chapter, the use of the transformation methods from Cartesian coordinates to geodetic coordinates and vice versa is explained, these methods are linked to the body model.

* Ephemerides loader : this chapter explains how to use the JPLEphemeridesLoader to load bodies ephemerides. Only the DE 405 and DE 406 loaders are available.

[[Catégorie:User Manual 4.17]]

User Manual 4.17 Orbits

2025-11-26T13:51:42Z

Admin tsn : Page créée avec « __NOTOC__ == Introduction == === Scope === The "orbits" package contains classes to represent the orbital state of a spacecraft at a given time. Several types of orbits are available (cartesian, keplerian, equinoctial...). The jacobian matrix for each orbital parameter / cartesian parameter conversion are also available for their current value. An "Orbit" (implementing "Orbit" class) object is not to be misunderstood with an "Orbital parameters" object (implemen... »

__NOTOC__
== Introduction ==
=== Scope ===
The "orbits" package contains classes to represent the orbital state of a spacecraft at a given time. Several types of orbits are available (cartesian, keplerian, equinoctial...).
The jacobian matrix for each orbital parameter / cartesian parameter conversion are also available for their current value.

An "Orbit" (implementing "Orbit" class) object is not to be misunderstood with an "Orbital parameters" object (implement "IOrbitalParameters" interface). An orbit uses as attributes:
* Orbital parameters
* A date
* A frame (not necessarily inertial or pseudo-inertial)

For more information about orbital parameters, please refer to [FDY_PARAM_Home Orbital parameters].

=== Javadoc ===
The classes for orbits description are available in the package <code>fr.cnes.sirius.patrius.orbits</code>.

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
| Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/orbits/package-summary.html Package fr.cnes.sirius.patrius.orbits]
|}

=== Links ===
None as of now.

=== Useful Documents ===
None as of now.

=== Package Overview ===
All different orbits types extend the abstract generic Orbit class (the following class package may not contain all classes extending Orbit class).

[[File:orbits.PNG|center]]

The enum "PositionAngle" lists the three types of position angle (anomaly, alpha angle...) available : TRUE, MEAN, ECCENTRIC.

== Features Description ==
=== Available orbit types ===
The available orbit types are :
* Cartesian : X, Y, Z, Vx, Vy, Vz (including also acceleration Ax, Ay, Az)
* Keplerian : a, e, i, perigee argument, right ascension of ascending node, anomaly (in each position angle types)
* Equinoctial : a, ex, ey (eccentricity vector), hx, hy (inclination vector), true longitude argument (in each position angle types)
* Alternate equinoctial : n (mean motion), ex, ey (eccentricity vector), hx, hy (inclination vector), longitude argument (in each position angle types, but stored in mean)
* Circular : a, ex, ey (eccentricity vector), i, right ascension of ascending node, true latitude argument (in each position angle types)
* Apsis : periapsis, apoapsis, i, perigee argument, right ascension of ascending node, anomaly (in each position angle types)
* Equatorial : a, e, longitude of the periapsis (ω + Ω), ix (first component of inclination vector), iy (second component of inclination vector), anomaly (in each position angle types)

=== Jacobians ===
For each orbital parameter type (keplerian, equinoctial, circular, apsis, equatorial), the jacobian matrices "orbital parameters with respect to cartesian parameters" and "cartesian parameters with respect to orbital parameters" are available.
The jacobian matrix related to the conversion between an orbital parameter type A to an orbital parameter type B is also available (computed by getJacobian method) for each orbital parameter type.

For all except the equinoctial and equatorial parameters, the "with respect to cartesian parameters" jacobian (getJacobianWrtCartesian method) is computed with direct analytic methods, and the "with respect to orbital parameters" (getJacobianWrtParameters method) obtained by computing the inverse of the previous one.
For the equinoctial and equatorial parameters, both computations are direct and analytic.

== Getting Started ==
Any orbit can be defined using the chosen constructor. Here is an to define a circular orbit:

<syntaxhighlight lang="java">
final KeplerianParameters keplerianParameters = new KeplerianParameters(10000E3, 0.1, 0.2, 0.3, 0.4, 0.5, PositionAngle.TRUE, Constants.EGM96_EARTH_MU);
final CircularOrbit orbit = new CircularOrbit(keplerianParameters, FramesFactory.getEME2000(), date);
</syntaxhighlight>

Internal parameters of circular orbits are circular parameters. They can be retrieved and converted using conversion routines provided by [[User_Manual_4.1_Orbital_parameters|Orbital parameters]] objects:

<syntaxhighlight lang="java">
final CartesianParameters cartesianParameters = orbit.getParameters().getCartesianParameters();
</syntaxhighlight>

== Contents ==

=== Interfaces ===
None as of now.

=== Classes ===
{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''Orbit'''
|Abstract class for all orbits.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/orbits/Orbit.html ...]
|-
|'''CartesianOrbit'''
|Instant orbit described by its cartesian parameters.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/orbits/CartesianOrbit.html ...]
|-
|'''KeplerianOrbit'''
|Instant orbit described by its keplerian parameters.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/orbits/KeplerianOrbit.html ...]
|-
|'''CircularOrbit'''
|Instant orbit described by its circular parameters.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/orbits/CircularOrbit.html ...]
|-
|'''EquinoctialOrbit'''
|Instant orbit described by its equinoctial parameters.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/orbits/EquinoctialOrbit.html ...]
|-
|'''AlternateEquinoctialOrbit'''
|Instant orbit described by its equinoctial parameters.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/orbits/AlternateEquinoctialOrbit.html ...]
|-
|'''EquatorialOrbit'''
|Instant orbit described by its equatorial parameters.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/orbits/EquatorialOrbit.html ...]
|-
|'''ApsisOrbit'''
|Instant orbit described by its apsis parameters.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/orbits/ApsisOrbit.html ...]
|}

[[Category:User_Manual_4.17_Flight_Dynamics]]

User Manual 4.17 SpacecraftState

2025-11-26T13:51:23Z

Admin tsn : Page créée avec « __NOTOC__ == Introduction == === Scope === This section describes the SpacecraftState object. === Javadoc === The object [{{JavaDoc4.17}}//fr/cnes/sirius/patrius/propagation/SpacecraftState.html SpacecraftState] is available in the package <code>fr.cnes.sirius.patrius.propagation</code>. === Links === Here is only described the SpacecraftState structure. Please refer to [ORB_PRO_Home propagation chapter]. === Useful Documents === None as of now. === Overv... »

__NOTOC__
== Introduction ==
=== Scope ===
This section describes the SpacecraftState object.

=== Javadoc ===
The object [{{JavaDoc4.17}}//fr/cnes/sirius/patrius/propagation/SpacecraftState.html SpacecraftState] is available in the package <code>fr.cnes.sirius.patrius.propagation</code>.

=== Links ===
Here is only described the SpacecraftState structure.
Please refer to [ORB_PRO_Home propagation chapter].

=== Useful Documents ===
None as of now.

=== Overview ===
The [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/propagation/SpacecraftState.html SpacecraftState] is composed of : 
- an [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/orbits/Orbit.html orbit] 
- an [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/Attitude.html attitude for forces computation] 
- an [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/Attitude.html attitude for events computation] 
- a map of additional states (including mass states added from [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/propagation/MassProvider.html MassProvider]). 

Two attitudes are stored in order to apply (if needed) a different treatment to each attitude.

== Features Description ==
=== One orbit ===
The [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/propagation/SpacecraftState.html SpacecraftState] is composed of one [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/orbits/Orbit.html Orbit].
It is possible to simply declare a SpacecraftState with an orbit :
<code>final SpacecraftState state = new SpacecraftState(orbit);</code>

The orbit could be updated using the following method :
<code>final SpacecraftState newState = state.updateOrbit(newOrbit);</code>
The attitude and additional states will remain the same and a new SpacecraftState will be created.

=== Two attitudes ===
The user can use one single

[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/Attitude.html Attitude] or two different [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/Attitude.html Attitude] objects : one for forces computation and one for events computation. The following constructor can be used :

<code>final SpacecraftState state = new SpacecraftState(orbit, attitudeForces, attitudeEvents);</code>

It is possible to get the attitude for forces or events computation using the following methods:

<syntaxhighlight lang="java">final Attitude attForces = state.getAttitudeForces();
final Attitude attEvents = state.getAttitudeEvents();</syntaxhighlight>

The user can deals with a single attitude in the SpacecraftState using the following constructor:
<syntaxhighlight lang="java">final SpacecraftState state = new SpacecraftState(orbit, attitude);
final Attitude att = state.getAttitude();</syntaxhighlight>

If the following constructor is used, both attitudes are set to null value:
<code>final SpacecraftState state = new SpacecraftState(orbit);</code>
Then calling <code>getAttitude</code> or <code>getAttitudeForces</code> or <code>getAttitudeEvents</code> will return null attitude.

=== Additional states ===
The additional states are stored in the SpacecraftState using a Map with the additional states names as keys. The additional states are in the type <code>double[]</code>.
The additional states map could be given directly to the constructor as follow :

<syntaxhighlight lang="java">Map<String, double[]> addStates = new HashMap<String, double[]>();
addStates.put("name", new double[]{1.0});
SpacecraftState state = new SpacecraftState(orbit, attitudeForces, attitudeEvents, addStates); </syntaxhighlight>

It is possible to add an additional state to a SpacecraftState using'''''addAdditionalState''''':

<code>state2 = state.addAdditionalState("name2", new double[]{0.1, 0.1});</code>

Note :'''''addAdditionalState''''' returns a new SpacecraftState with the added additional state. It is necessary to store the returned object. The additional state is not added to the current state.

=== Mass ===
A [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/propagation/MassProvider.html MassProvider] can be provided to the SpacecraftState. In that case, the mass information are automaticaly stored as additional states. Be careful, the mass values can never be negative:

<syntaxhighlight lang="java">final SpacecraftState state = new SpacecraftState(orbit, massProvider);
final SpacecraftState state = new SpacecraftState(orbit, attitudeForces, attitudeEvents, massProvider, addStates); </syntaxhighlight>

The mass provider can be added to the SpacecraftState after its initilisation with the method <code>addMassProvider</code> :
<syntaxhighlight lang="java">final SpacecraftState state = new SpacecraftState(orbit);
final SpacecraftState newState = state.addMassProvider(massProvider);</syntaxhighlight>

The mass parts from MassProvider are added to additional states map with the key : "MASS_<partName>".

The total mass of the SpacecraftState could not be obtained.

It is possible to obtain the mass of a given part :
<code>state.getMass("part1"); </code>

and to update the mass of a given part :
<code>state.updateMass("part1", 1000.0); </code>

=== State vector ===
The [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/propagation/SpacecraftState.html SpacecraftState] object could be created from a state vector :
<code>final SpacecraftState state = new SpacecraftState(stateVector, OrbitType.CARTESIAN, PositionAngle.MEAN, date, mu, frame, addStatesInfo, attProviderForces, attProviderEvents);</code>

To build the SpacecraftState, it is necessary to know the size and the index of all additional states in the state vector. This information could be obtained from an old state using the following method :
<code>final Map<String, AdditionalStateInfo> addStatesInfos = state.getAdditionalStatesInfos();</code>

The state vector could be obtained from a SpacecraftState :
<syntaxhighlight lang="java">final double[] stateVector = new double[]{};
state.mapStateToArray(OrbitType.CARTESIAN, PositionAngle.MEAN, stateVector); </syntaxhighlight>

=== Transform ===

The [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/propagation/SpacecraftState.html SpacecraftState] class contains methods to compute the following transformations :
- <code>toTransform()</code> or <code>toTransformForces()</code> : Transform from orbit/attitude reference frame to spacecraft frame (attitude used for forces computation which is the default attitude). 
- <code>toTransformEvents()</code> : Transform from orbit/attitude reference frame to spacecraft frame attitude used for events computation (same as toTransform if there is no specific attitude for Events).
- <code>toTransform(Frame)</code> or <code>toTransformForces(Frame)</code> : Transform from specified [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/Frame.html Frame] to spacecraft frame (attitude used for forces computation which is the default attitude). 
- <code>toTransformEvents(Frame)</code> : Transform from specified [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/Frame.html Frame] to spacecraft frame attitude used for events computation (same as toTransform(Frame) if there is no attitude specific for Events). 
- <code>toTransform(LOFType)</code> : Transform from orbit/attitude reference frame to local orbital frame ([{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/LOFType.html LOFType]). 
- <code>toTransform(Frame, LOFType)</code> : Transform from specified [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/Frame.html Frame] to local orbital frame ([{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/LOFType.html LOFType]). 

== Getting Started ==

=== Using Transform ===

Here after is presented the computation of a station position in spacecraft frame:
<syntaxhighlight lang="java">
// Station position defined in GCRF
final Vector3D station_InGCRF = new Vector3D(Constants.EGM96_EARTH_EQUATORIAL_RADIUS, 0, 0);
final Frame gcrf = FramesFactory.getGCRF();
// Compute transform from GCRF to spacecraft frame
final Transform transform = state.toTransform(gcrf);
// Station position in spacecraft frame
final Vector3D station_InSpacecraftFrame = transform.transformVector(station_InGCRF);
</syntaxhighlight>

Here after is presented the computation of the Sun direction in spacecraft frame.
<syntaxhighlight lang="java">
// Compute transform from orbit/attitude reference frame to local orbital frame TNW
final Transform transform = state.toTransform(LOFType.TNW);
// Position of Sun in local orbital frame TNW
final Vector3D pos = transform.transformPosition(sun.getPVCoordinates().getPosition());
</syntaxhighlight>
If an [{{JavaDoc4.17}}//fr/cnes/sirius/patrius/assembly/Assembly.html Assembly] is used, this is not necessary to use these methods because the conversion methods are included in Assembly functionalities (see [SPC_VBU_Home dedicated User Manual]).

== Contents ==
=== Interfaces ===

{| class="wikitable"
|-
! scope="col"| Interface
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''MassProvider'''
|Interface providing the mass for spacecraft models.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/propagation/MassProvider.html ...]
|}

=== Classes ===

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''SpacecraftState'''
|This class is the representation of a complete state holding orbit, attitude for forces and for events computation and additional states at a given date.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/propagation/SpacecraftState.html ...]
|-
|'''Attitude'''
|Object representing the attitude of the spacecraft for a specific date and in a specific frame.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/attitudes/Attitude.html ...]
|}

[[Category:User_Manual_4.17_Flight_Dynamics]]

User Manual 4.17 Time

2025-11-26T13:51:09Z

Admin tsn : Page créée avec « __NOTOC__ == Introduction == === Scope === Despite its current use, time requires careful attention in the description of physical phenomena. Indeed the rate at which time passes has to be accurate in order to guarantee the best physical description of a phenomenon. To that purpose several time scales have been set up and with the introduction of atomic clocks, more accurate time scales have been defined. === Javadoc === The object related with dates and time s... »

__NOTOC__
== Introduction ==
=== Scope ===
Despite its current use, time requires careful attention in the description of physical phenomena. Indeed the rate at which time passes has to be accurate in order to guarantee the best physical description of a phenomenon. To that purpose several time scales have been set up and with the introduction of atomic clocks, more accurate time scales have been defined.

=== Javadoc ===
The object related with dates and time scales are available in the package <code>fr.cnes.sirius.patrius.time</code>.

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/time/package-summary.html Package fr.cnes.sirius.patrius.time]
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/utils/package-summary.html Package fr.cnes.sirius.patrius.utils]
|}

=== Links ===
''Time architecture description'', [http://procyon.cst.cnes.fr/mvnsites/1_0_1/orekit/architecture/time.html Orekit site].

=== Useful Documents ===
None as of now.

=== Package Overview ===

Please note that not all implementations are present in the following diagram for the sake of clarity.

[[File:timeOrekit.JPG]]

This package overview is from the OREKIT website, under apache license.

== Features Description ==
=== Dates ===
In Patrius, the class <code>AbsoluteDate</code> represents a specific instant in time. There are several ways to create a date :

* for instance, one way is to give the date with a calendar form (year, month and day as 3 integers or as a <code>DateComponents</code> object) and a time scale : <code>AbsoluteDate(int, int, int, TimeScale)</code> or <code>AbsoluteDate(DateComponents, TimeScale)</code>
* to be more precise the informations of the hour, the minute and the second can be added : <code>AbsoluteDate(int, int, int, int, int, double, TimeScale)</code> or <code>AbsoluteDate(DateComponents, TimeComponents, TimeScale)</code>
NB : a DateComponents object represents a date broken up as year, month and day ; a TimeComponents object represents a day broken up as hour, minute and second.
* another way is to give a predefined date and an elapsed duration from this date : <code>AbsoluteDate(AbsoluteDate, double)</code>
* through a CNES Julian date and associated timescale: <code>AbsoluteDate(double, TimeScale)</code>. Note that the reversed conversion (from AbsoluteDate to CNES JD is also available with method <code>toCNESJulianDate()</code>

{{warning|For advanced users only : a constructor <code>AbsoluteDate(long, double)</code> is available. It uses as parameters an "epoch" and an "offset", which are in fact the attributes of AbsoluteDate. These attributes have no meaning outside of AbsoluteDate, and are not meant to be exposed or manipulated directly by regular users. This constructor was added for the purpose of creating AbsoluteDate instances very quickly from a static storage (apart from serialization) and without loss of precision. Getters for "epoch" and "offset" are also available for this purpose.'''Use at your own risk!'''}}

As for the time scale, Patrius contains 10 different time scales among which the TAI scale (International Atomic Time), the TT scale (Terrestrial Time), the UT1 scale (Universal Time), the UTC scale (Coordinated Universal Time)... The creation of a time scale is done through the <code>TimeScalesFactory</code> as follows : <code>TimeScale scale = TimeScalesFactory.getTT();</code>

Note that for UTC scale, some data are required (the UTC-TAI shift).
This data can be handled through the <code>TimeScalesFactory</code> class.
By default, some loaders are added to <code>TimeScalesFactory</code> in the following order:
*<code>UTCTAIHistoryFilesLoader</code>: UTC-TAI file in IERS format (file UTC-TAI.history)
There is no included data in PATRIUS by default
Once loaded, data are stored in static variables and are used for UTC time scale retrieval.

Some reference epochs are directly available, for instance :

* J2000 epoch (2000-01-01T12:00:00) in TT scale : <code>AbsoluteDate date = AbsoluteDate.J2000_EPOCH;</code>
* julian epoch (-4712-01-01T12:00:00) in TT scale : <code>AbsoluteDate date = AbsoluteDate.JULIAN_EPOCH;</code>
* fifties epoch (CNES julian dates origin, 1950-01-01T00:00:00) in TT scale : <code>AbsoluteDate date = AbsoluteDate.FIFTIES_EPOCH_TT;</code>
* fifties epoch (CNES julian dates origin) in UTC scale : <code>AbsoluteDate date = AbsoluteDate.FIFTIES_EPOCH_UTC;</code>
* Java Reference epoch (1970-01-01T00:00:00) in UTC scale : <code>AbsoluteDate date = AbsoluteDate.JAVA_EPOCH;</code>
* ...

=== Time Interval ===
This implementation for time intervals, <code>AbsoluteDateInterval</code>, uses the <code>AbsoluteDate</code> class as the endpoint value type.

Infinite endpoints ( <code>AbsoluteDate.PAST_INFINITY</code> and <code>AbsoluteDate.FUTURE_INFINITY</code> ) are supported, but as open endpoints only. Empty intervals are also forbidden.

This implementation extends the class <code>ComparableInterval</code>, inheriting the following operations:

* check if two intervals are equal:
<code> boolean equal = interval.equals(Object) </code>

* check if two intervals overlap:
<code> boolean overlaps = interval.overlaps(ComparableInterval<T>) </code>

* check if the interval includes another interval:
<code> boolean includes = interval.includes(ComparableInterval<T>) </code>

* check if the interval is connected to another interval (its lower point coincides with the upper point of the input interval, and one point is closed and the other open):
<code> boolean connected = interval.isConnectedTo(ComparableInterval<T>) </code>

* compare the lower end point with the lower end point of another interval:
<code> int compare = interval.compareLowerEndTo(ComparableInterval<T>) </code>

* compare the upper end point with the upper end point of another interval:
<code> int compare = interval.compareUpperEndTo(ComparableInterval<T>) </code>

In addition to inherited capabilities, the class can also:

* compute the duration of the interval in seconds (as computed in a regular timescale- the duration has a physical meaning):
<code> double duration = interval.getDuration() </code>

* compute the duration between intervals in seconds (that is : the duration between the end of the earlier interval and the beginning of the later one):
<code>double duration = interval.durationFrom(AbsoluteDateInterval nextInterval) </code>

* merge the interval with another interval if possible (the intervals must overlap or be connected to be merged):
<code>AbsoluteDateInterval mergedInterval = interval.mergeTo(AbsoluteDateInterval) </code>

* get the intersection between two intervals when overlapping:
<code> AbsoluteDateInterval intersection = interval.getIntersectionWith(AbsoluteDateInterval) </code>

* compare the duration of an interval with the duration of another interval:
<code> int compare = interval.compareDurationTo(AbsoluteDateInterval) </code>

* create a list of equally spaced dates within an interval:
** <code> List<AbsoluteDate> datesList = interval.getDateList(double) </code> (if providing a step)
** <code> List<AbsoluteDate> datesList = interval.getDateList(int) </code> (if providing a number of dates)
Boundaries type (open, closed) are taken into account (more information in the javadoc of these methods)

==== List of time intervals ====

The class <code>AbsoluteDateIntervalsList</code> represents a list of time intervals (whose elements are <code>AbsoluteDateInterval</code> instances).
As <code>AbsoluteDateInterval</code> objects implement the <code>Comparable</code> interface via the class <code>ComparableInterval</code>, the time intervals in the list are automatically ordered by their lower/upper dates.

<syntaxhighlight lang="java">
final AbsoluteDateIntervalsList list = new AbsoluteDateIntervalsList();
IntervalEndpointType open = IntervalEndpointType.OPEN;
IntervalEndpointType closed = IntervalEndpointType.CLOSED;
// set up the time intervals to add:
final AbsoluteDateInterval i1 = new AbsoluteDateInterval(open, date1, date2, closed);
final AbsoluteDateInterval i2 = new AbsoluteDateInterval(closed, date1, date3, open);
list.add(i1);
list.add(i2);
</syntaxhighlight>

In addition to the methods inherited from the <code>TreeSet</code> class, <code>AbsoluteDateIntervalsList</code> can also:

* tell which time intervals in the list contain a predetermined date:
<code>AbsoluteDateIntervalsList intervals = list.getIntervalsContainingDate(date)</code>

* compute the shortest interval containing all the intervals belonging to the list:
<code>AbsoluteDateInterval inclusiveInterval = list.getInclusiveInterval(); </code>

* compute the list of complementary intervals of the given intervals list:
<code>AbsoluteDateIntervalsList complementaryList = list.getComplementaryIntervals();</code>

Please see the Javadoc for more information.

=== Local time and solar time ===
Local time is represented by the angle between the projections of the Earth-Sun vector and the Earth-Spacecraft vector in the equatorial plane. Local time is expressed in hours and its value is 12h when this angle is 0 rad. Beware, in PATRIUS, local time is always expressed as an angle in the range [-PI; PI[ and always represents the angle between the projections of the Earth-Sun vector and the Earth-Spacecraft vector in the equatorial plane. If one wants to retrieve local time (in hours) from the local time angle provided by PATRIUS, the following formula should be used:

<center>Local time = 12h + local time angle* 12 / Pi.</center>

Local time increases for prograde orbits and decreases for retrograde orbits.

Similarly, solar time is represented by the angle between the Earth-Sun projection in the orbital plane and the Earth-Spacecraft vector. Solar time is expressed in hours and its value is 12h when this angle is 0 rad. Beware, in PATRIUS, solar time is always expressed as an angle in the range [-PI; PI[ and always represents the angle between the Earth-Sun projection in the orbital plane and the Earth-Spacecraft vector. If one wants to retrieve solar time (in hours) from the solar time angle provided by PATRIUS, the following formula should be used:

<center>Solar time = 12h + solar time angle* 12 / Pi.</center>

Solar time always increases with time. It is mesured around the orbit momentum.

The class <code>LocalTimeAngle</code> provides methods to compute:
* True local time angle using <code>computeTrueLocalTimeAngle()</code>. Local time is always computed in TIRF frame. True local time is represented by the angle between projection of satellite position and Sun position over the equatorial plane in provided frame. Returned time is expressed in seconds in the range [-PI; PI[.
* Mean local time angle using <code>computeMeanLocalTimeAngle()</code>. Local time angle is always computed in TIRF frame. Mean local time is the sum of true local time and equation of time (EOT):

<center><math>Mean local time = True local time + EOT</math></center>

* Equation of time using <code>computeEquationOfTime()</code>:

Equation of time is true local time of GMST ([0; 0; 1] vector in TIRF frame) minus seconds in the date:

<center><math>EOT =-(Local time GMST - sec)</math></center>

Equation of time is periodic over one year in the range [-16min; +14min]:

[[File:EquationOfTime.png|center]]

* RAAN from local true/mean time with methods <code>computeRAANFromMeanLocalTime</code> and <code>computeRAANFromTrueLocalTime</code>.

== Getting Started ==
==== AbsoluteDateInterval ====

Here is given a code example on how to use the <code>AbsoluteDateInterval</code>:

<syntaxhighlight lang="java">
final AbsoluteDate t1 = new AbsoluteDate("1969-11-03", TimeScalesFactory.getTT());
final AbsoluteDate t2 = new AbsoluteDate("1969-11-04", TimeScalesFactory.getTT());
final AbsoluteDate t3 = new AbsoluteDate("1969-11-06", TimeScalesFactory.getTT());
final AbsoluteDate t4 = new AbsoluteDate("1969-11-07", TimeScalesFactory.getTT());
final IntervalEndpointType open = IntervalEndpointType.OPEN;
final double dayInSeconds = Constants.JULIAN_DAY;
// Two separated intervals, two days of separation :
// ..] t1 ; t2 [....] t3 ; t4 [..
final AbsoluteDateInterval ad1A = new AbsoluteDateInterval(open, t1, t2, open);
final AbsoluteDateInterval ad1B = new AbsoluteDateInterval(open, t3, t4, open);
final double dur11 = ad1B.durationFrom(ad1A);
final double dur12 = ad1A.durationFrom(ad1B);
// ad1B begins 2 days after ad1A ends : duration from is + 2 days
Assert.assertEquals(2.* dayInSeconds, dur11, 0.);
// ad1A ends 2 days before ad1B begins : duration from is- 2 days
Assert.assertEquals(-2.* dayInSeconds, dur12, 0.);
</syntaxhighlight>

== Contents ==
=== Interfaces ===
{| class="wikitable"
|-
! scope="col"| Interface
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''TimeScale'''
|Interface for time scales.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/time/TimeScale.html ...]
|-
|'''TimeStamped'''
|This interface represents objects that have a AbsoluteDate date attached to them.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/time/TimeStamped.html ...]
|}

=== Classes ===
{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''AbsoluteDate'''
|This class represents a specific instant in time.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/time/AbsoluteDate.html ...]
|-
|'''AbsoluteDateInterval'''
|This class implements an interval based on the AbsoluteDate class.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/time/AbsoluteDateInterval.html ...]
|-
|'''AbsoluteDateIntervalsList'''
|This class represents a list of AbsoluteDateInterval objects.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/time/AbsoluteDateIntervalsList.html ...]
|-
|'''ChronologicalComparator'''
|Comparator for TimeStamped instance.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/time/ChronologicalComparator.html ...]
|-
|'''ComparableInterval'''
|Class describing an interval of Comparable data.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/interval/ComparableInterval.html ...]
|-
|'''DateComponents'''
|Class representing a date broken up as year, month and day components.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/time/DateComponents.html ...]
|-
|'''DateTimeComponents'''
|Holder for date and time components.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/time/DateTimeComponents.html ...]
|-
|'''GalileoScale'''
|Galileo system time scale.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/time/GalileoScale.html ...]
|-
|'''GenericInterval'''
|Generic class to describe an interval.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/utils/GenericInterval.html ...]
|-
|'''GMSTScale'''
|Greenwich Mean Sidereal Time.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/time/GMSTScale.html ...]
|-
|'''GPSScale'''
|GPS time scale.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/time/GPSScale.html ...]
|-
|'''TAIScale'''
|International Atomic Time.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/time/TAIScale.html ...]
|-
|'''TCBScale'''
|Barycentric Coordinate Time.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/time/TCBScale.html ...]
|-
|'''TCGScale'''
|Geocentric Coordinate Time.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/time/TCGScale.html ...]
|-
|'''TDBScale'''
|Barycentric Dynamic Time.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/time/TDBScale.html ...]
|-
|'''TimeComponents'''
|Class representing a time within the day broken up as hour, minute and second components.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/time/TimeComponents.html ...]
|-
|'''TimeScalesFactory'''
|Factory for predefined time scales.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/time/TimeScalesFactory.html ...]
|-
|'''TTScale'''
|Terrestrial Time as defined by IAU(1991) recommendation IV.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/time/TTScale.html ...]
|-
|'''UT1Scale'''
|Universal Time 1.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/time/UT1Scale.html ...]
|-
|'''UTCScale'''
|Coordinated Universal Time.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/time/UTCScale.html ...]
|-
|'''LocalTimeAngle'''
|Local time angle computation methods.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/time/LocalTimeAngle.html ...]
|}

== Tutorials ==
=== Tutorial 1 ===
[[DatesTutorials|Tutoriel sur les dates]]

[[Category:User_Manual_4.17_Flight_Dynamics]]

User Manual 4.17 Celestial bodies

2025-11-26T13:50:47Z

Admin tsn : Page créée avec « __NOTOC__ == Introduction == === Scope === The celestial bodies are described by their main features : position and geometry. The positions are ephemeris that must be loaded from models, the geometries are created as one axis ellipsoids or facet bodies. The package provides a factory able to create any celestial body of the solar system. === Javadoc === The classes for bodies description are available in the package <code>bodies</code> of Patrius. {| class="wi... »

__NOTOC__
== Introduction ==
=== Scope ===
The celestial bodies are described by their main features : position and geometry. The positions are ephemeris that must be loaded from models, the geometries are created as one axis ellipsoids or facet bodies.
The package provides a factory able to create any celestial body of the solar system.

=== Javadoc ===
The classes for bodies description are available in the package <code>bodies</code> of Patrius.

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
|Orekit
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/package-summary.html Package fr.cnes.sirius.patrius.bodies]
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/package-summary.html Package fr.cnes.sirius.patrius.bodies]
|}

=== Links ===

Orekit bodies : [https://www.orekit.org/static/architecture/bodies.html Orekit Bodies architecture description ]

IAU report : [https://astrogeology.usgs.gov/groups/iau-wgccre Report of the IAU Working Group on Cartographic Coordinates and Rotational Elements: 2009]

=== Useful Documents ===
None as of now.

=== Package Overview ===
None.

== Features Description ==
=== Celestial bodies ===
The Moon, the Sun and planets of the solar system are all represented by the [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/CelestialBody.html CelestialBody] interface. This class associates a name (eg Sun) to :
* a gravitational coefficient GM
*a body centered ICRF frame (which can be retrieved with method <code>getICRF()</code>).
*a body centered EME2000 frame (which can be retrieved with method <code>getEME2000()</code>).
*a body centered inertial frame taking into account only the constant part (α, δ) of IAUPole (which can be retrieved with method <code>getInertialFrame(IAUPoleModelType.CONSTANT)</code>).
*a body centered inertial frame taking into account only the constant and secular parts (α, δ) of IAUPole (which can be retrieved with method <code>getInertialFrame(IAUPoleModelType.MEAN)</code>).
*a body centered inertial frame taking into account the constant secular and harmonics parts (α, δ) of IAUPole (which can be retrieved with method <code>getInertialFrame(IAUPoleModelType.TRUE)</code>).
*a body centered rotating frame taking into account only the constant part w of IAUPole (which can be retrieved with method <code>getRotatingFrame(IAUPoleModelType.CONSTANT)</code>). It's parent frame is the inertial equator frame.
*a body centered rotating frame taking into account only the constant and secular parts w of IAUPole (which can be retrieved with method <code>getRotatingFrame(IAUPoleModelType.MEAN)</code>). It's parent frame is the mean equator frame.
*a body centered rotating frame taking into account the constant secular and harmonics parts w of IAUPole (which can be retrieved with method <code>getRotatingFrame(IAUPoleModelType.TRUE)</code>). It's parent frame is the true equator frame.

Inertially-oriented and body-oriented frames are defined in the following way:
* Body-centered inertial frame is centered on the celestial body centered and pole axis (Z axis) is shifted by right ascension α and declination δ.
* Body-centered rotating frame is linked to inertially-oriented frame by a rotation of angle W(t) (reference values for W(t) is provided by IAU).

To build a celestial body, the user can:
* use the static methods of the <code>CelestialBodyFactory</code> to create instances of the most common celestial bodies (Moon, Sun, Jupiter, etc.). JPL Ephemeris data are used. Warning: using the factory requires to load JPL Ephemeris data beforehand.
* use the simplified models (Meeus, etc.).
* creates its own celestial body using the class <code>UserCelestialBody</code> as well as its own pole motion using the class <code>UserIAUPole</code>.

For the two first case (JPL and Meeus), the pole data of the body are automatically retrieved using the IAU data through <code>IAUPoleFactory</code> class (data is contained within PATRIUS).
By default, IAU pole data for planetary bodies (including Sun and moon) are available in PATRIUS through the use of the <code>IAUPoleFactory.getIAUPole()</code>. Data come from the IAU 2009 working group Technical Note.

These methods are detailed in the following sections.

=== Ephemeris Loader ===
For any celestial body of the Solar System, the actual computation of its position and velocity relies on the JPL planetary ephemerides files. These files are binary files and loaded thanks to the JPLCelestialBodyLoader object.

Note that celestial bodies and associated ephemeris loaders are distinct: a class loads the ephemeris returning a <code>CelestialBodyEphemeris</code> while the other loads the whole <code>CelestialBody</code>.
However, for sake of clarity, the main visible loaders are celestial body loaders.

For the moment, this object is able to load JPL DE XXX files and IMCCE INPOP files which are the most commonly used data files (see below for an exact list of accepted files). For instance with the most common files, the JPL DE 405 covers the years 1600 to 2200 at maximum precision, the JPL DE 406 covers the years-3000 to +3000 at only slightly reduced precision. The DE 405 file is the basis for the Astronomical Almanac and leads to sufficiently accurate results and, for most purposes, even the accuracy of DE 406 is sufficient.

==== JPLCelestialBodyLoader ====

In order to generate the ephemerides of one celestial body of the Solar System, one has to use the JPLCelestialBodyLoader as follows :

<syntaxhighlight lang="java">
final JPLCelestialBodyLoader loaderEMB = new JPLCelestialBodyLoader(fileName,
EphemerisType.EARTH_MOON);
final JPLCelestialBodyLoader loaderSSB = new JPLCelestialBodyLoader(fileName,
EphemerisType.SOLAR_SYSTEM_BARYCENTER);
CelestialBodyFactory.addCelestialBodyLoader(CelestialBodyFactory.EARTH_MOON, loaderEMB);
CelestialBodyFactory.addCelestialBodyLoader(CelestialBodyFactory.SOLAR_SYSTEM_BARYCENTER, loaderSSB);

// Reference frame
Frame icrf = FramesFactory.getICRF();

// Ephemeris of the Sun
JPLCelestialBodyLoaderloader = new JPLCelestialBodyLoader("unxp2000.405",
EphemerisType.SUN);

// Creation of the Sun
CelestialBody sun = loader.loadCelestialBody(CelestialBodyFactory.SUN);

// Coordinates of the Sun given a date and a reference frame
PVCoordinates pvSun = sun.getPVCoordinates(date, icrf);
</syntaxhighlight>

When the user wants to create a JPLCelestialBodyLoader, first of all, he must supply the folder where the DE XXX files are stored. Then he has to give the name of the file which contains the data (DE XXX), the type of celestial body and a date (desired central date) as entries of the JPLCelestialBodyLoader.

The first argument (name of the data file) may be <code>null</code>. In this case, Patrius takes the first compatible file found. If one wants only files from the DE 405 ephemerides, for instance, he has to give the String <code> "^unx[mp](\\d\\d\\d\\d)\\.(?:405)$"</code>. The last argument can also be <code>null</code>. If the central date is not mentionned an arbitrary 100 days range will be loaded whereas if it is mentionned all data within a +/-50 days range around this date will be loaded.

Once the data is loaded, thanks to the JPLCelestialBodyLoader, the user can create the celestial body with the method loadCelestialBody() of the JPLCelestialBodyLoaderclass. To do so, the user has to be sure that all required data is loaded. Indeed, apart from the Moon, the Earth and the Earth-Moon barycenter, the creation of a celestial body requires some data on the Earth Moon barycenter and the Solar System barycenter in order to instanciate the frame in which the ephemerides of the celestial body will be defined. Therefore, the user has to create a JPLCelestialBodyLoaderfor the Earth-Moon barycenter and the Solar System barycenter prior to creating the celestial body, otherwise Patrius will arbitrarily load a DE file to generate the corresponding ephemerides that are used afterwards for the generation of the frame. Then the user has to complete the list of the loaders of the CelestialBodyFactory with these two loaders before calling the method loadCelestialBody().

A static method <code>hasNoLoader()</code> in the class <code>CelestialBodyFactory</code> allows for a given celestial body to verify if a default loader exists. The user can verify if a specific loader exists for the body before using the default one this way.

NB : The user has to clean the CelestialBodyFactory memory if he does not want to work with the previously defined celestial bodies.

==== JPL ephemerides ====

The JPL ephemerides data is available on the [ftp://ssd.jpl.nasa.gov/pub/eph/planets/ JPL FTP server] [R3].

Available ephemerides :

{| class="wikitable"
|-
! scope="col"| Development Ephemerides
! scope="col"| Created in...
! scope="col"| Description
|-
|DE200
|September 1981
|includes nutations but not librations. 
Referred to the dynamical equator and equinox of 2000. 
Covers JED 2305424.13 (1599 DEC 09) to JED 2513360.5 (2169 MAR 31).

This ephemeris was used for the Astronomical Almanac from 1984 to 2003. (See Standish, 1982 and Standish, 1990).
|-
|DE202
|October 1987
|includes nutations and librations. 
Referred to the dynamical equator and equinox of 2000. 
Covers JED 2414992.5 (1899 DEC 04) to JED 2469808.5 (2050 JAN 02).
|-
|DE403
|May 1993
|includes nutations and librations. 
Referred to the International Celestial Reference Frame. 
Covers JED 2305200.5 (1599 APR 29) to JED 2524400.5 (2199 JUN 22).

Fit to planetary and lunar laser ranging data.(See Folkner et al. 1994).
|-
|DE405, DE406
|May 1997
|For the DE405:

includes both nutations and librations. 
Referred to the International Celestial Reference Frame. 
Covers JED 2305424.130 (1599 DEC 09) to JED 2525008.50 (2201 FEB 20)

For the DE406 :

the same as the DE405 except the time span : Spans JED 0624976.50 (-3001 FEB 04) to 2816912.50 (+3000 MAY 06)

This is the same integration as DE405, with the accuracy of the interpolating polynomials has been lessened to reduce file size for the longer time span covered by the file.
|-
|DE410
|April 2003
|includes nutations and librations. 
Referred to the International Celestial Reference Frame. 
Covers JED 2415056.5 (1900 FEB 06) to JED 2458832.5 (2019 DEC 15).

Ephemeris used for Mars Exploration Rover navigation.
|-
|DE413
|November 2004
|includes nutations and librations. 
Referred to the International Celestial Reference Frame. 
Covers JED 2414992.5, (1899 DEC 04) to JED 2469872.5 (2050 MAR 07).

Created to update the orbit of Pluto to aid in planning for an occultation of a relatively bright star by Charon on 11 July 2005.
|-
|DE414
|May 2005
|includes nutations and librations. 
Covers JED 2414992.5, (1899 DEC 04) to JED 2469872.5 (2050 MAR 07).

Fit to ranging data from MGS and Odyssey through 2003. (See Konopliv et al., 2006.)
|-
|DE418
|August 2007
|includes nutations and librations. 
Covers JED 2414864.13 (1899 JUL 29) to JED 2470192.5 (2051 JAN 21)
|-
|DE421
|February 2008
|includes nutations and librations. 
Referred to the International Celestial Reference Frame. 
Covers JED 2414864.13 (1899 JUL 29) to JED 2471184.13 (2053 OCT 09)

Fit to planetary and lunar laser ranging data. (See Folkner et al., 2009)
|-
|DE422
|September 2009
|includes nutations and librations. 
Referred to the International Celestial Reference Frame. 
Covers JED 625648.5, (-3000 DEC 07) to JED 2816816.5, (3000 JAN 30).

Intended for the MESSENGER mission to Mercury. 
Extended integration time to serve as successor to DE406. 
Fit to ranging data from MGS and Odyssey through 2003. (See Konopliv et al., 2010.)
|-
|DE423
|February 2010
|includes nutations and librations. 
Referred to the International Celestial Reference Frame version 2.0. 
Covers JED 2378480.5, (1799 DEC 16) to JED 2524624.13, (2200 FEB 02).

Intended for the MESSENGER mission to Mercury.
|}

==== IMCCE INPOP ephemerides ====

The IMCCE INPOP ephemeris is available on IMCCE website.

Available INPOP ephemerides :
* 06b
* 06c
* 08a
* 10a
* 10b
* 10e
* 13c
* 17a
* 19a

=== Simplified analytical models ===
==== Meeus Model ====

The Meeus Model is a simplified model which gives the position of the Sun and the Moon with respect to the time T expressed in centuries (TT time scale). This model is an analytical model less precise than the DE ephemerides given by JPL. It is adapted for onboard applications.
The class implementing the Meeus Model allows three different models computing the position of the Sun with appropriate equations : the standard model (provided by Jean Meeus), the Stela model and an onboard model. The main differences between these model is the computation of the obliquity of the ecliptic : indeed, its value is fixed to 0 for the standard model, given by an expression involving <math>T, T^{2}</math>for Stela model and <math>T, T^{2}, T^{3}</math> for the onboard model.
Moreover, the onboard model computed the position in J2000 frame, whereas standard and Stela models use respectively EOD and MOD frame.

Regarding the precision, one has to expect a maximum difference of 25593km in position for the Sun and a maximum angular difference of 34.13'' (wrt DE405 ephemerides). For the Moon, one has to expect a maximum difference of 26 km in position and a maximum angular difference of 15.2'' (wrt DE405 ephemerides). As for the performances (in terms of execution time), the Meeus model for the Sun is faster than the DE405 ephemerides. However, we did not come to the same conclusion for the Moon even by decreasing the degree of precision (number of terms taken into account to compute the latitude, longitude and distance which are needed to compute in fine the position of the Moon).

{| class="wikitable"
|-
!
! scope="col"| Deviation in position wrt DE423
! scope="col"| Angular deviation wrt DE423
|-
|'''Sun'''
|12000 km
|34.13''
|-
|'''Moon 62x66x46'''
|12.4 km
|15.2''
|-
|'''Moon 26x13x13'''
|225 km
|122''
|-
|'''Moon 9x4x3'''
|1591 km
|889''
|}

{| class="wikitable"
|-
!
! scope="col"| Deviation in position wrt DE405
! scope="col"| Angular deviation wrt DE405
|-
|'''Sun'''
|25593km
|34.13''
|-
|'''Moon 62x66x46'''
|26 km
|15.2''
|}

{| class="wikitable"
|-
!
! scope="col"| Number of elementary operations
! scope="col"| Number of trigonometric operations
|-
|'''Sun'''
|89
|10
|-
|'''Moon 62x66x46'''
|2671
|182
|-
|'''Moon 26x13x13'''
|917
|60
|-
|'''Moon 9x4x3'''
|401
|24
|}

References for the tables :
* "Modèles d'éphémérides luni-solaires", CNES DCT/SB/MS, 03/14/2011
* "Modèle MEEUS pour éphémérides Lune-Soleil : Compléments sur le nombre d'opérations", CNES DCT/SB/MS

{| class="wikitable"
|-
!
! scope="col"| execution time - DE405
! scope="col"| execution time- MEEUS
|-
|'''Sun'''
|59 s 548 ms
|19 s 938 ms
|-
|'''Moon 62x66x46'''
|11 s 625 ms
|3 mn 22 s 323 ms
|-
|'''Moon 26x13x13'''
|11 s 625 ms
|1 mn 17 s 74 ms
|-
|'''Moon 9x4x3'''
|11 s 625 ms
|40 s 326 ms
|}

In order to build such a Sun or Moon, one has to use the object MeeusSun or MeeusMoon which both extend AbstractCelestialBody. Note that it is not possible to build those celestial bodies from the CelestialBodyFactory, for the moment.

==== Basic board Sun model ====
The basic board Sun model is a simplified analytical model which gives the direction of the Sun (the normalized position) with respect to time.
This model is similar to the Meeus model (the constants of the model are different) and is adapted for onboard applications.
The reference inertial frame is the CIRF.

=== User-defined celestial bodies ===
User can defined its own celestial body by using <code>UserCelestialBody</code>.
This class requires to provide:
* Its name.
* Its position-velocity through time using a <code>PVCoordinateProvider</code> implementation.
* Its gravitational constant.
* Its pole motion using <code>IAUPole</code> implementation or directly the <code>UserIAUPole</code> implementation.
The <code>UserIAUPole</code> is a simple way to build standard pole motion from IAU note. It requires to provide for each component (α, δ and W) a list of functions of duration in days and duration in centuries (from a reference epoch) as defined in IAU note. This functions are <code>UnivariateDifferentiableFunction</code>.
Available functions in PATRIUS include:
* <code>PolynomialFunction</code>: polynomial function
* <code>SineFunction</code>: function of the form k.sin(f) with f an <code>UnivariateDifferentiableFunction</code>
* <code>CosineFunction</code>: function of the form k.cos(f) with f an <code>UnivariateDifferentiableFunction</code>

'''Example: building Ceres'''.
According to the IAU report, Ceres has the following parameters:
* α = 291◦ ± 5◦
* δ = 59◦ ± 5◦
* W = 170.90◦ + 952.1532◦d
With ''d'' being the interval in days from the standard epoch (the standard epoch is JD 2451545.0, i.e. 2000 January 1 12 hours TDB)

Ceres gravitational constant is 6.263E10 m^^3^^kg^^-1^^s^^-2^^.

If one knows Ceres motion given for instance by a <code>PVCoordinatePropagator</code> ''pv'', then one can build Ceres with the following code:

<syntaxhighlight lang="java">
// Gravitational parameter
final double gm = 6.263E10;

// Pole motion - Method 1 - Implementation if IAUPole interface
final IAUPole pole = new IAUPole() {
@Override
public double getPrimeMeridianAngle(final AbsoluteDate date) {
// W
final double d = date.durationFrom(AbsoluteDate.J2000_EPOCH) / Constants.JULIAN_DAY;
return FastMath.toRadians(170.90) + FastMath.toRadians(952.1532)* d;
}

@Override
public Vector3D getPole(final AbsoluteDate date) {
// Pole bias: alpha and delta
return new Vector3D(FastMath.toRadians(291), FastMath.toRadians(59));
}
...
};

// Pole motion - Method 2 - Use of UserIAUPole class
// Alpha 0 coefficients
final List<IAUPoleFunction> alpha0List = new ArrayList<IAUPoleFunction>();
alpha0List.add(new IAUPoleFunction(IAUPoleType.CONSTANT, new PolynomialFunction(new double[] { 291 }), IAUTimeDependency.DAYS);
final IAUPoleCoefficients1D alpha0Coeffs = new IAUPoleCoefficients1D(alpha0List);
// Delta 0 coefficients
final List<IAUPoleFunction> delta0List = new ArrayList<IAUPoleFunction>();
delta0List.add(new IAUPoleFunction(IAUPoleType.CONSTANT, new PolynomialFunction(new double[] { 59 }), IAUTimeDependency.DAYS);
final IAUPoleCoefficients1D delta0Coeffs = new IAUPoleCoefficients1D(delta0List );
// W coefficients
final List<IAUPoleFunction> w0List = new ArrayList<IAUPoleFunction>();
w0List.add(new IAUPoleFunction(IAUPoleType.CONSTANT, new PolynomialFunction(new double[] { 170.9 }), IAUTimeDependency.DAYS);
w0List.add(new IAUPoleFunction(IAUPoleType.SECULAR, new PolynomialFunction(new double[] { 0, 952.1532 }), IAUTimeDependency.DAYS);
final IAUPoleCoefficients1D wCoeffs = new IAUPoleCoefficients1D(w0List);
// Build pole
final IAUPole pole = new UserIAUPole(new IAUPoleCoefficients(alpha0Coeffs, delta0Coeffs, wCoeffs));

// Build Ceres body
final CelestialBody ceres = new UserCelestialBody("Ceres", pv, gm, pole, FramesFactory.getICRF(), null);

</syntaxhighlight>

Then <code>ceres</code> object possesses all features of:
* A <code>CelestialBody</code>: retrieve body-centered inertial frames or body-centered rotating frames
* A <code>PVCoordinateProvider</code>: retrieve position and velocity at any time

=== Body shapes ===
The one-axis ellipsoid is a good approximate model for most planet-size and larger natural bodies. It is the equilibrium shape reached by a fluid body under its own gravity field when it rotates. The symmetry axis is the rotation or polar axis.

==== OneAxisEllipsoid ====

This type is used to represent the shape of a planet. One very useful implementation represents an ellipsoid (OneAxisEllipsoid). It is constructed from an equatorial radius, a flattening coefficient, and a reference frame that will be used to localize Geodetic points on the shape.

It could be interesting to obtain the intersection point of a line from the satellite to the surface of the body for a given altitude. To that purpose, one can use the method getIntersectionPoint(Line, Vector3D, Frame, AbsoluteDate, double) of the interface BodyShape.

<syntaxhighlight lang="java">

AbsoluteDate date = new AbsoluteDate(new DateComponents(2008, 03, 21),
TimeComponents.H12,
TimeScalesFactory.getUTC());
CelestialBodyFrame frame = FramesFactory.getITRF();
// Body shape model
OneAxisEllipsoid earth = new OneAxisEllipsoid(6378136.460, 1 / 298.257222101, frame);

// Satellite on any position

circ = new CircularOrbit(7178000.0, 0.5e-4, 0., FastMath.toRadians(50.), FastMath.toRadians(0.),
FastMath.toRadians(90.), PositionAngle.MEAN,
FramesFactory.getEME2000(), date, mu);

// Transform satellite position to position/velocity parameters in EME2000 and ITRF200B
PVCoordinates pvSatEME2000 = circ.getPVCoordinates();
PVCoordinates pvSatItrf = frame.getTransformTo(FramesFactory.getEME2000(), date).transformPVCoordinates(pvSatEME2000);
Vector3D pSatItrf = pvSatItrf.getPosition();

// Nadir point of the satellite
Vector3D pointItrf = new Vector3D.ZERO;
Vector3D direction = Vector3D(1., pSatItrf,-1., pointItrf);
Line line = new Line(pSatItrf, direction);
// intersection point between the ellipsoid and the line that joins the satellite and the center of the body
double altitude = 0;
EllipsoidPoint nadir = earth.getIntersectionPoint(line, pSatItrf, frame, date, altitude);

</syntaxhighlight>

Note: The ThreeAxisEllipsoid class shares many features with the OneAxisEllipsoid and allows to define an ellipsoid fully defined by its three axis radius (along the directions (0, 0, 1) ; (0, 1, 0) ; (0, 0, 1)).

==== BodyShape and OneAxisEllipsoid ====

OneAxisEllipsoid extends the AbstractEllipsoidBodyShape class (also extended by ThreeAxisEllipsoid) and AbstractEllipsoidBodyShape implements the EllipsoidBodyShape interface, which extends the StarConvexBodyShape interface, which, at its turn, extends the BodyShape interface.
See the [MIS_SENSORS_PatriusBodySpheroid specific page] for more details.

==== Facet celestial body ====

<code>FacetBodyShape</code> is a class used to define a celestial body as a mesh. This is particularly useful for small irregular bodies such as asteroids.
For example, Phobos contains here 100 000 vertices and 200 000 facets:
[[File:Phobos.jpg|center]]

This class:
* Inherits the <code>BodyShape</code> interface and hence can be used together with <code>EclipseDetector</code> and <code>SensorModel</code>.
* Provides some useful and optimised methods for small body handling. Facets are connected to each other allowing some methods to be writen in a recursive or iterative way and hence being very fast. If n is the number of vertices of the body, fast recursive or iterative methods are in O(log(n)).

For use as a <code>CelestialBody</code>, this class must be linked to a <code>UserCelestialBody</code>.

===== Mesh provider =====

A mesh is described by a list of facets <code>Triangle</code> and or vertices <code>Vertex</code>. A <code>Triangle</code> contains three vertices.
Mesh is provided by the generic interface <code>MeshProvider</code>. This interface currently possesses two implementation:
* <code>ObjMeshLoader</code>: in this case, the mesh is provided under official .obj file format. See [https://en.wikipedia.org/wiki/Wavefront_.obj_file This page] for more information on the format.
* <code>GeodeticMeshLoader</code>: in this case, the mesh is provided in an ASCII column file listing each vertex in the format [Latitude Longitude Altitude].

===== Available methods =====

Note that most methods return exact results. For example, <code>distanceTo</code> methods returns exact distance to mesh body. Only <code>getEllipsoid(EllipsoidType)</code> and <code>getApparentRadius</code> methods return a simplified result.

<code>FacetBodyShape</code> provides the following methods:
* <code>getIntersection(Line, Vector3D, Frame, AbsoluteDate)</code> and similar which return an <code>Intersection</code> object.This object contains the intersection point as well as the <code>Triangle</code> containing the intersection point. This method is recursive and is in O(log(n)).
* <code>buildPoint(LLHCoordinatesSystem, double, double, double, String)</code> and similar which return the facet point associated to the specified corrinates in the given LLH coordinates system.
* <code>getApparentRadius()</code> methods which provides the local radius from an object and an occulted body using an approximate iterative algorithm. This method is to be used only by <code>EclipseDetector</code>.
* <code>resize(MarginType, double)</code> method which returns a resized body shape.
* <code>closestPointTo</code> methods which return the two closest points between the line given in input and the current facet body shape. One of the two points belongs to the line, the other to the facet body shape.
* <code>distanceTo()</code> method which returns the distance to the body. This method is recursive and is hence in O(log(n)).
* <code>getNeighbors()</code> methods which returns the neighbors triangles to:
** A point or a triangle given a "neighborhood distance"
** A triangle given a "neighborhood order". In this case, order 1 returns the immediate neighbors of the triangles, order 2 returns also the neighbors' neighbors and so on.
This method is recursive and is hence in O(log(n)).
* <code>getFieldData()</code> which returns a container <code>FieldData</code> containing data related to the field of view:
** Visible triangles from the satellite field of view <code>IFieldOfView</code>. A visible triangle must be entirely in the field of view and not masked by any other triangle.
** Contour of the seen triangles. Contour is strictly contained in the field of view
If main direction of the field of view is provided, this method is recursive and is in O(log(n)). Otherwise, it is in O(n) and is much slower.
* <code>isInEclipse()</code> method which returns true if the satellite is currently in eclipse, false otherwise. Penumbra is not taken into account. This method is in O(log(n)).
* <code>getNeverVisibleTriangles()</code> which returns a list of facets which are never visible from the provided ephemeris. Visibility criteria is the same as for <code>getFieldData()</code> method. This method is in O((n)).
* <code>getNeverEnlightenedTriangles()</code> which returns a list of facets which are never enlightened by the Sun. Visibility criteria is the same as for <code>getFieldData()</code> method. This method is in O((n)).
* <code>getVisibleAndEnlightenedTriangles()</code> which returns a list of facets which are visible and enlightened at the same time, at least once on the provided ephemeris. Visibility criteria is the same as for <code>getFieldData()</code> method. This method is in O((n)).
* <code>getEllipsoidType()</code> which returns the type of the ellipsoid.

The class <code>BodyShapeFitter</code> allows to build shapes fitted on the main Shape provided as input. Different criteria are available and the type of ellipsoid returned can be obtained by calling the method <code>getEllipsoid(EllipsoidType)</code>.

==== EllipsoidPoint====

The ellipsoid point is defined by a latitude, a longitude and an altitude in the frame associated to the ellipsoid (EllipsoidBodyShape). It could be interesting to know the position of a satellite in terms of geodetic coordinates rather than Cartesian ones and vice versa (the corresponding methods in OneAxisEllipsoid).

<syntaxhighlight lang="java">
// equatorial radius of the celestial body
double ae = 6378137.0;
// flatness of the celestial body
double f = 1.0 / 298.257222101;
// date
AbsoluteDate date = AbsoluteDate.J2000_EPOCH;
// reference frame attached to the body
CelestialBodyFrame frame = FramesFactory.getITRF();
// body shape model (ellipsoid)
OneAxisEllipsoid model = new OneAxisEllipsoid(ae, f, frame);

// transformation with jacobian matrix : cartesian to geodetic

// initial cartesian point that will be transformed
Vector3D cp = new Vector3D(4637885.347, 121344.1308, 4362452.869);
// coresponding ellipsoid point
EllipsoidPoint point = model.buildPoint(cp, frame, date, "point");

// transformation with jacobian matrix : geodetic to cartesian

// coresponding Cartesian point
Vector3D cp2 = model.computePositionFromEllipsodeticCoordinates(0.852479154923577, 0.0423149994747243, 111.6);
</syntaxhighlight>

It could be also interesting to obtain the jacobian matrix of the transformation.

<syntaxhighlight lang="java">

// transformation : cartesian to geodetic

final double[][] computedJacobian = LLHCoordinatesSystem.ELLIPSODETIC.jacobianFromCartesian(point);

// transformation : geodetic to cartesian

final double[][] computedJacobian2 = LLHCoordinatesSystem.ELLIPSODETIC.jacobianToCartesian(point);
</syntaxhighlight>

The enumeration LLHCoordinatesSystem.ELLIPSODETIC allows the computation of the time derivatives of the LLH coordinates of a point. There are two algorithms implemented:
* Analytical calculation for OneAxisEllipsoid
* Finite-difference numerical calculation for all other types of ellipsoid, such as ThreeAxisEllipsoid

The selection between the analytical and numerical method is automatic and the only function to call is the following:
<syntaxhighlight lang="java">
double[] LLHCoordinatesSystem.ELLIPSODETIC.computeLLHRates(final BodyShape bodyShape, final PVCoordinates pv, final Frame frame,
final AbsoluteDate date)
</syntaxhighlight>

The longitude, latitude, and height rates are returned and expressed in rad/s, rad/s, et m/s respectively.

Here is a full example of how to use this functionality:

<syntaxhighlight lang="java">
// Create Earth OneAxisEllipsoid
final double ae = 6378137.0;// GRS80 constant
final double flattening = 1.0 / 298.257222101;// GRS80 constant
final CelestialBodyFrame itrf = FramesFactory.getITRF();
final CelestialBodyFrame gcrf = FramesFactory.getGCRF();
final OneAxisEllipsoid earth = new OneAxisEllipsoid(ae, flattening, itrf);
final AbsoluteDate date = new AbsoluteDate(2010, 7, 9, 20, 30, 0);

// Create orbit around the Earth in GCRF
final double mu = 3.986005e14;// GRS80 constant
final KeplerianOrbit orbit = KeplerianOrbit(ae + 700e3, 0.0, 0.5, 1.2, 1.1, 2.3, PositionAngle.TRUE, gcrf, date, mu);

// Compute the rates using the analytical implementation
final double[] rates = LLHCoordinatesSystem.ELLIPSODETIC
.computeLLHRates(earth, orbit.getPVCoordinates(), gcrf, date);
</syntaxhighlight>

== Getting Started ==
TBD

== Contents ==
=== Interfaces ===

{| class="wikitable"
|-
! scope="col"| Interface
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''BodyShape'''
|Interface representing the rigid surface shape of a natural body.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/BodyShape.html ...]
|-
|'''CelestialBody'''
|Interface for celestial bodies like Sun, Moon or solar system planets.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/CelestialBody.html ...]
|-
|'''CelestialBodyEphemeris'''
|Interface for celestial body ephemeris like Sun, Moon or solar system planets.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/CelestialBodyEphemeris.html ...]
|-
|'''CelestialBodyLoader'''
|Interface for celestial body loaders.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/CelestialBodyLoader.html ...]
|-
|'''CelestialBodyEphemerisLoader'''
|Interface for celestial body ephemeris loaders.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/CelestialBodyEphemerisLoader.html ...]
|-
|'''MeshLoader'''
|Interface for FacetCelestialBody mesh provider.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/mesh/MeshProvider.html ...]
|}

=== Classes ===
{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''CelestialBodyFactory'''
|Factory class for bodies of the solar system.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/CelestialBodyFactory.html ...]
|-
|'''BodyPoint'''
|Point location relative to a 2D body surface.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/GeodeticPoint.html ...]
|-
|'''JPLCelestialBodyLoader'''
|Loader for JPL ephemerides binary files (DE 405, DE 406, ...).
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/JPLCelestialBodyLoader.html ...]
|-
|'''OneAxisEllipsoid'''
|Modeling of a one-axis ellipsoid.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/OneAxisEllipsoid.html ...]
|-
|'''MeeusSun'''
|Position of the Sun according to Meeus model. Three models with there appropriate equations are avaible : the standard model (former MeeusSun), Stela model (former MeeuSunStela) and an on-board model
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/MeeusSun.html ...]
|-
|'''MeeusMoon'''
|Position of the Moon according to Meeus model.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/MeeusMoon.html ...]
|-
|'''BasicBoardSun'''
|Direction of the Sun according to a basic board Sun model.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/BasicBoardSun.html ...]
|-
|'''UserCelestialBody'''
|User-defined celestial body
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/UserCelestialBody.html ...]
|-
|'''UserIAUPole'''
|User-defined IAU pole motion
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/UserIAUPole.html ...]
|-
|'''IAUPoleFactory'''
|Factory for retrieval of solar system bodies IAU pole data
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/IAUPoleFactory.html ...]
|-
|'''IAUPoleFunction'''
|Atomic IAU pole function. IAU pole data is the sum of atomic IAUPoleFunction.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/IAUPoleFunction.html ...]
|-
|'''FacetBodyShape'''
|Celestial body defined by a mesh.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/mesh/FacetBodyShape.html ...]
|-
|'''BodyShapeFitter'''
|Fitter for a given body shape provided as input.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/mesh/BodyShapeFitter.html ...]
|-
|'''Triangle'''
|Unitary facet (triangle) for a FacetCelestialBody.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/mesh/Triangle.html ...]
|-
|'''ObjMeshLoader'''
|.obj 3D file mesh loader.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/mesh/ObjMeshLoader.html ...]
|-
|'''GeodeticMeshLoader'''
|Mesh loader for ASCII files describing the body with latitude/longitude/altitude components (1 per line).
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/bodies/mesh/GeodeticMeshLoader.html ...]
|}

[[Category:User_Manual_4.17_Flight_Dynamics]]

User Manual 4.17 Frames

2025-11-26T13:50:32Z

Admin tsn : Page créée avec « __NOTOC__ == Introduction == === Scope === In Patrius, a frame is represented by the class Frame. The different frames are organized as a tree whose root is the ICRF. A frame is defined by a transformation with respect to its parent. A frame factory enables us to build easily some current frames such as GCRF, EME2000, ITRF... Models and data defining transformations between frame is defined in [FDY_FRCON_Home Frames configuration] === Javadoc === The frames are... »

__NOTOC__
== Introduction ==
=== Scope ===
In Patrius, a frame is represented by the class Frame. The different frames are organized as a tree whose root is the ICRF. A frame is defined by a transformation with respect to its parent. A frame factory enables us to build easily some current frames such as GCRF, EME2000, ITRF...
Models and data defining transformations between frame is defined in [FDY_FRCON_Home Frames configuration]

=== Javadoc ===
The frames are available in the package <code>fr.cnes.sirius.patrius.frames</code>.

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/package-summary.html Package fr.cnes.sirius.patrius.frames]
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/transformations/package-summary.html Package fr.cnes.sirius.patrius.frames.transformations]
|}

=== Links ===
* [https://www.orekit.org/static/architecture/frames.html Frames architecture] (some of this information may be obsolete)

=== Useful Documents ===
None as of now.

=== Package Overview ===
None.

== Features Description ==

=== Frames ===
The following frames are available in PATRIUS:

* Reference frames :
** ICRF,
** ICRF translated on the Earth-Moon Barycenter (EMB),
** GCRF,
** CIRF,
** TIRF,
** ITRF,
** EME 2000,
** Ecliptic J2000,
** MOD with and without EOP corrections,
** TOD with and without EOP corrections,
** GTOD with and without EOP corrections,
** G50,
** VEIS 1950,
** and more ...
* Local orbital frames
* Vehicule frame (see AttitudeFrame in the [ATT_ALW_Home attitude laws] section)
* Topocentric frames
* CelestialBody frame (frame centerd on a celestial body)

To use any of the reference frames, the user must use the FramesFactory like so :

<syntaxhighlight lang="java">
Frame eme2000 = FramesFactory.getEME2000();
</syntaxhighlight>

PATRIUS implements a frame configuration mechanism. To use it, see the [FDY_FRAME_Home#HTheFramesConfiguration Frames Configuration] section in this page.

See [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/FramesFactory.html FramesFactory javadoc] for a complete list of public methods.

Note that, since PATRIUS 4.13, referential can be defined for any frame using the method <code>Frame.setReferential(Frame)</code>. By default, the referential is the same as the frame. Changing the referential will only impact the projection of the velocities in the destination frame.

==== Topocentric frame ====
A topocentric frame can be instantiated with the class TopocentricFrame. This class is based on the definition of a BodyPoint as origin of the frame.

===== TopocentricFrame =====

This class provides several constructors. The simplest one returns an East oriented topocentric frame. The second one, that works with an angle, returns a North oriented topocentric frame if the angle is 0, or an image of this frame through the rotation around the zenith direction of the given angle (counterclockwise).

<syntaxhighlight lang="java">
// Reference frame = ITRF
Frame frameITRF = FramesFactory.getITRF();

// Elliptic earth shape
OneAxisEllipsoid earthSpheric = new OneAxisEllipsoid(6378136.460, 0., frameITRF);

// Geodetic point at which to attach the frame
final EllipsoidPoint point = new EllipsoidPoint(earthSpheric , LLHCoordinatesSystem.ELLIPSODETIC, FastMath.toRadians(0.), FastMath.toRadians(30.), 0., "point ");

// Build the east frame
TopocentricFrame topoEast = new TopocentricFrame(point, "lon 30 lat 0");

// Build a frame rotated by 30° from the North frame
TopocentricFrame topo30 = new TopocentricFrame(point, FastMath.toRadians(30.), "lon 30 lat 0");

</syntaxhighlight>

It can provide a number of directions, such as West, North or Nadir. It provides methods that compute elevation, azimuth and the range of a point located by a cartesian vector.

<syntaxhighlight lang="java">
// get the zenith or the Nadir
Vector3D north = topoEast.getZenith();
Vector3D nadir = topoEast.getNadir();

// compute the azimuth of a position
Vector3D position = new Vector3D(1.0, 2.0, 3.0);
double azimuth = topo30.getAzimuth(position, earthSpheric.getBodyFrame(), date);

</syntaxhighlight>

Finally, being a Frame, it can be used to automatically transform a position/velocity to any frame (the inverse is also possible).

<syntaxhighlight lang="java">
//get the transformation from the topocentric East to the ITRF
Transform eastTOitrf = topoEast.getTransformTo(frameITRF, AbsoluteDate.FIFTIES_EPOCH_UTC);

//apply the transformation
PVCoordinates pointPVeast= new PVCoordinates(new Vector3D(0.,-1., 1), Vector3D.ZERO);
PVCoordinates pointPVitrf= eastTOitrf.transformPVCoordinates(pointPVeast);
</syntaxhighlight>

We can instantiate a TopocentricFrame without GeodeticCoordinates using either cartesian coordinates and a zenith direction or cartesian coordinates associated with a Body shape. This allows to define accurate Topocentric Frame on bodies which are not ellipsoids (e.g. Phobos).

===== TopocentricCoordinates =====

The topocentric coordinates are defined by the elevation, the azimuth and the distance from the center of the local topocentric frame [R2].

[[File:azimut.gif|center]]

The azimuth is the angle between the local North and the projection of the line which joins the center of the topocentric frame and the satellite in the horizontal plane. This angle ranges from 0 to 2<math>\pi</math>. This angle is oriented by the axis opposite to the Zenith. On the figure, the angle g is called the bearing, it is linked to the azimuth by : g = 2<math>\pi</math>- azimuth.

The elevation is the angle between the line which joins the center of the topocentric frame and the satellite and the projection of this line in the horizontal plane. This angle ranges from-<math>\pi</math>/2 to <math>\pi</math>/2. This angle is oriented by the image of the West axis by the rotation of angle azimuth and around Zenith axis. On the figure, s is the elevation angle.

If the elevation equals <math>{\pi\over2}</math> or <math>-{\pi\over2}</math>, the azimuth is undefined.

The object TopocentricCoordinates contains also the first derivatives of these elements (elevation rate, azimuth rate and range rate).

We can transform the position of the satellite expressed in Cartesian coordinates into TopocentriCoordinates and vice versa.

We can also transform PVCoordinates into TopocentricCoordinates and vice versa.

<syntaxhighlight lang="java">
// North topocentric frame
final EllipsoidPoint point = new EllipsoidPoint(earthSpheric , LLHCoordinatesSystem.ELLIPSODETIC, FastMath.toRadians(43.604482), FastMath.toRadians(1.443962), 0., "point ");
final TopocentricFrame topoNorth = new TopocentricFrame(point, 0., "north topocentric frame");
final AbsoluteDate date = new AbsoluteDate(new DateComponents(2008, 04, 07), TimeComponents.H00, TimeScalesFactory.getUTC());
// Topocentric coordinates
TopocentricPosition topoCoord = new TopocentricPosition(FastMath.acos(FastMath.sqrt(2. / 3.)), FastMath.toRadians(315), FastMath.sqrt(3));
// Cartesian coordinates (position only)
Vector3D position = topoNorth.transformFromTopocentricToPosition(topoCoord);
</syntaxhighlight>

<syntaxhighlight lang="java">
// North topocentric frame
final EllipsoidPoint point = new EllipsoidPoint(ellipsoid, LLHCoordinatesSystem.ELLIPSODETIC, FastMath.toRadians(43.604482), FastMath.toRadians(1.443962), 0., "point ");
final TopocentricFrame topoNorth = new TopocentricFrame(point, 0., "north topocentric frame");
final AbsoluteDate date = new AbsoluteDate(new DateComponents(2008, 04, 07), TimeComponents.H00, TimeScalesFactory.getUTC());
// Cartesian coordinates (position only)
Vector3D position = new Vector3D(1,1,1);
// Topocentric Coordinates
TopocentricPosition topoCoord = topoNorth.transformFromPositionToTopocentric(position, topoNorth, date);
</syntaxhighlight>

===== CardanMounting =====

The Cardan mounting is defined by two angles (X and Y) and the distance from the center of the local topocentric frame [R2].

[[File:cardan.gif|center]]

The X angle is the angle between the Zenith and the projection of the line which joins the center of the topocentric frame and the satellite in the vertical plane (plane defined by the Zenith and the West axis). This angle ranges from-<math>\pi</math> to <math>\pi</math>. This angle is oriented by the South axis. On the figure, x is the X angle.

The Y angle is the angle between the line which joins the center of the topocentric frame and the satellite and the projection of this line in the vertical plane (plane defined by the Zenith and the West axis). This angle ranges from-<math>\pi</math>/2 and <math>\pi</math>/2. It is oriented by the image of the West axis by the rotation of angle X and around North axis. On the figure, y is the Y angle.

If the Y angle equals <math>\pi</math>/2 or-<math>\pi</math>/2, the X angle is undefined.

The object CardanMounting contains also the first time derivatives of these elements (X angle rate, Y angle rate and range rate).

We can transform the position of the satellite expressed in Cartesian coordinates into CardanMounting and vice versa.

We can also transform PVCoordinates into cardanMounting and vice versa.

<syntaxhighlight lang="java">
// North topocentric frame
final EllipsoidPoint point = new EllipsoidPoint(ellipsoid, LLHCoordinatesSystem.ELLIPSODETIC, FastMath.toRadians(43.604482), FastMath.toRadians(1.443962), 0., "point ");
final TopocentricFrame topoNorth = new TopocentricFrame(point, 0., "north topocentric frame");
final AbsoluteDate date = new AbsoluteDate(new DateComponents(2008, 04, 07),
TimeComponents.H00,
TimeScalesFactory.getUTC());
// Cardan mounting
CardanMountPosition cardanCoord = new CardanMountPosition(FastMath.toRadians(45), FastMath.acos(FastMath.sqrt(2. / 3.)), FastMath.sqrt(3));
// Cartesian coordinates (position only)
Vector3D position = topoNorth.transformFromCardanToPosition(cardanCoord);
</syntaxhighlight>

<syntaxhighlight lang="java">
// North topocentric frame
final EllipsoidPoint point = new EllipsoidPoint(ellipsoid, LLHCoordinatesSystem.ELLIPSODETIC, FastMath.toRadians(43.604482), FastMath.toRadians(1.443962), 0., "point ");
final TopocentricFrame topoNorth = new TopocentricFrame(point, 0., "north topocentric frame");
final AbsoluteDate date = new AbsoluteDate(new DateComponents(2008, 04, 07), TimeComponents.H00, TimeScalesFactory.getUTC());
// Cartesian coordinates (position only)
Vector3D position = new Vector3D(1,1,1);
// Cardan mounting
cardanCoord = topoNorth.transformFromPositionToCardan(position, topoNorth, date);
</syntaxhighlight>

==== CelestialBodyFrame ====

This frame is a wrapper for frames centered on celestial bodies. All celestial bodies-centered frames are instances of CelestialBodyFrame (including geocentric frames).

==== "H0- n" frame ====
The "H0- n" frame is a pseudo-inertial frame; its parent frame is the GCRF.
It uses the frozen transformation of the ITRF with respect to the GCRF frame at the date "H0- n", combined with a rotation by a fixed angle around the Z axis of the ITRF frame.

==== TwoDirectionFrame ====
The <code>TwoDirectionFrame</code> is a generic reference frame that can be build starting from two directions and two axis given as input. The specific reference frame inherits from the generic <code>Frame</code> and uses an internal implementation of a <code>TransformProvider</code> in order to define a specific <code>Transform</code> starting from a specific date.

The <code>Transform</code> is obtained as follows :
* a translation obtained starting from the <code>PVCoordinatesProvider</code> and the <code>Frame</code> given as input to the constructor ;
* a rotation obtained starting from the directions defined towards the axis of the reference frame ;
* a rotation rate which is built a finite difference method with the method <code>AngularCoordinates.estimateRate(…)</code> : the finite difference step for the computation can be configurable by the used when creating the reference frame.

== Getting Started ==
TBD

== Contents ==
=== Interfaces ===

=== Classes ===

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''PredefinedFrame'''
| Base class for the predefined frames that are managed by FramesFactory.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/PredefinedFrame.html ...]
|-
|'''CelestialBodyFrame'''
| Class for frames centered on celestial bodies.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/CelestialBodyFrame.html ...]
|-
|'''Frame'''
|Tridimensional references frames class.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/Frame.html ...]
|-
|'''FramesFactory'''
|Factory for predefined reference frames.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/FramesFactory.html ...]
|-
|'''HelmertTransformation'''
|Transformation class for geodetic systems.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/transformations/HelmertTransformation.html ...]
|-
|'''LocalOrbitalFrame'''
|Class for frames moving with an orbiting satellite.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/LocalOrbitalFrame.html ...]
|-
|'''TopocentricFrame'''
|The topocentric frame.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/TopocentricFrame.html ...]
|-
|'''Transform'''
|Transformation class in three dimensional space.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/transformations/Transform.html ...]
|-
|'''H0MinusNProvider'''
|Provider for the "H0-n" frame.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/transformations/H0MinusNProvider.html ...]
|-
|'''H0MinusNFrame'''
|"H0-n" frame.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/H0MinusNFrame.html ...]
|-
|'''TwoDirectionFrame'''
|A generic frame the can be built starting from two directions and two axes.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/TwoDirectionFrame.html ...]
|-
|'''FrameConvention'''
|Enumeration of all frame conventions used in Patrius.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/configuration/FrameConvention.html ...]
|-
|'''SynodicFrame'''
|Synodic frame: frame linked to the 3-body problem. In practise this frame generalizes the concept of synodic frame (not necessarily linked to the 3-body problem).
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/SynodicFrame.html ...]
|-
|'''TranslatedFrame'''
|Frame realizing a translation from a parent frame (axis direction remains unchanged).
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/TranslatedFrame.html ...]
|-
|'''GCRFProvider'''
|Provider for the "GCRF" frame (from its parent frame, the EMB frame).
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/transformations/GCRFProvider.html ...]
|-
|'''EMBProvider'''
|Provider for the "EMB" frame (from its parent frame, the ICRF frame).
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/transformations/EMBProvider.html ...]
|}

== [[File:lightBulb.png]] Tips & Tricks ==
=== IERS frames transformations ===

This chapter sums up the up and downsides of the use of the IERS frames. Its purpose is to help the user avoid some traps and know what to expect as to the numerical precision of the computations. Further explanations about the IERS frames can be found on the [http://www.iers.org/nn_10968/IERS/EN/IERSHome/home.html?__nnn=true IERS website]'''[R1]'''.

==== Tips ====

The ICRF frame is the frame colinear to GCRF frame and centered on solar system barycenter.

One can compute the transformations between two frames with a specific frames configuration passed as a parameter as opposed to the current frame configuration (that is obtained with the <code>FramesFactory.getConfiguration()</code> method). Given a date and a user specific config, the method to call is :

<syntaxhighlight lang="java">
frame1.getTransformTo(frame2, date, config);
</syntaxhighlight>

One can also compute the jacobian matrix of the conversion between two frames. Given a date epoch, the jacobian matrix of the conversion from frame1 to frame2 is computed by the method <code>getTransformJacobian</code> called by :
<syntaxhighlight lang="java">
frame1.getTransformJacobian(frame2, epoch);
</syntaxhighlight>

==== Traps ====

The first thing to check when working with IERS frames is the presence of the Earth Orientation Parameters bulletins it requires. Indeed, if the c04 bulletins of the correct year cannot be found in the data, Patrius will use the ones stored internally to compute the transformations. To be sure that Patrius will use the good files, the user has first to point out the directory which contains these files. The fact that it doesn't warn the user that it does not have the parameters for the time of the simulation may lead to error, and thus the deviation compared to a reference could be enormous without the user being aware. One more thing to know about these bulletins is that they have to be continuous, meaning that the transformation won't work (and will throw an exception) if there are missing years or month in the files.

Make sure to use IAU 2000 EOP data, otherwise nutation corrections are null.

==== Usage of Frames ====

The methods to be used in order to instanciate the IERS Frames are :

* FramesFactory.getGCRF()
* FramesFactory.getCIRF()
* FramesFactory.getTIRF()
* FramesFactory.getITRF()

[[Category:User_Manual_4.17_Flight_Dynamics]]

User Manual 4.17 Frames configuration

2025-11-26T13:50:17Z

Admin tsn : Page créée avec « __NOTOC__ == 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 |- |Patrius |[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/configuration/package-summary.html Package fr.c... »

__NOTOC__
== 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
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/configuration/package-summary.html Package fr.cnes.sirius.patrius.frames.configuration]
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/configuration/eop/package-summary.html Package fr.cnes.sirius.patrius.frames.configuration.eop]
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/configuration/tides/package-summary.html Package fr.cnes.sirius.patrius.frames.configuration.tides]
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/configuration/libration/package-summary.html Package fr.cnes.sirius.patrius.frames.configuration.libration]
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/configuration/precessionnutation/package-summary.html Package fr.cnes.sirius.patrius.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]

=== Useful Documents ===
None as of now.

=== Package Overview ===
None as of now.

== 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. Note that this convention requires to provide EOP data. 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.
* A simple configuration which can be retrieved by calling <code>FramesConfigurationFactory.getSimpleConfiguration(boolean)</code>. This configuration is useful because it removes the need for EOP data. Depending on the value of the provided boolean, this configuration leads to the following equalities:
** Boolean = true (use of EOP models): GCRF != CIRF, TIRF = ITRF
** Boolean = false (no use of EOP models): GCRF == CIRF, TIRF = ITRF. Hence only Earth Rotation Angle is taken into account from GCRF to ITRF frame.

==== 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 [{{JavaDoc4.17}}/FramesFactory fr/cnes/sirius/patrius/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 [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/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 [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/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:
& 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 [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/configuration/PrecessionNutation.html PrecessionNutation javadoc] for the description of the above parameters).

===== 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 [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/configuration/eop/EOPHistory.html EOPHistory] interface represents EOP data. It has two implementations : [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/configuration/eop/EOP1980History.html EOP1980History] and [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/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 [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/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);
// EOPC04FilesLoader reads the input stream and fills the history object
EOPC04FilesLoader.fillHistory(eop2000History, is);
</syntaxhighlight>

Of course, in this case, the file has to be in the proper format for the EOPC04FilesLoader (see its [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/configuration/eop/EOPC04FilesLoader.html javadoc] for information).

For the 1980 EOP paradigm, the user must proceed in a similar fashion by manually creating an [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/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
* EOC04 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.setEOPHistory(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 : [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/configuration/eop/NoEOP1980HistoryLoader.html NoEOP1980HistoryLoader]. The user need only to create an instance of that class and feed it the [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/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, [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/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. Warning: in this case, as the UT1-TAI remains constant the (UT1-UTC) absolute value returned may become higher than 0.9 second depending on leap seconds (for UTC time scale) existing outside this interval.

===== 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 [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/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 ==
=== 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_IERS2010_INTERPOLATED);

builder.setDiurnalRotation(defaultDiurnalRotation);
builder.setPolarMotion(defaultPolarMotion);
builder.setCIRFPrecessionNutation(precNut);
builder.setEOPHistory(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>

== 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.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/configuration/FramesConfiguration.html ...]
|-
|'''EOPHistory'''
|Interface for retrieving Earth Orientation Parameters history throughout a large time range.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/configuration/eop/EOPHistory.html ...]
|-
|'''LibrationCorrectionModel'''
|This interface provides the pole corrections as well as the ut1-utc corrections due to libration.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/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.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/configuration/precessionnutation/PrecessionNutationModel.html ...]
|-
|'''SPrimeModel'''
|This interface provides the s' correction (used for the following transformation : TIRF -> ITRF).
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/configuration/sp/SPrimeModel.html ...]
|-
|'''TidalCorrectionModel'''
|This interface provides the pole corrections as well as the ut1-utc corrections due to tidal effects.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/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.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/configuration/FramesConfigurationBuilder.html ...]
|-
|'''FramesConfigurationFactory'''
|Frames configuration factory. Contains useful configurations.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/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).
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/configuration/DiurnalRotation.html ...]
|-
|'''PolarMotion'''
|This class contains the different polar motion corrections (libration, tidal effects, sp correction).
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/configuration/PolarMotion.html ...]
|-
|'''PrecessionNutation'''
|This class contains the precession nutation model used within the FramesConfigurationImplementation class.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/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).
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/configuration/libration/IERS2010LibrationCorrection.html ...]
|-
|'''NoLibrationCorrection'''
|This class ignores the libration effects.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/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.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/configuration/precessionnutation/PrecessionNutationConvention.html ...]
|-
|'''IERS20032010PrecessionNutation'''
|Compute the precession nutation correction according to the new IAU-2000 model.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/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).
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/configuration/sp/IERS2010SPCorrection.html ...]
|-
|'''NoSpCorrection'''
|This class ignores the quantity s'.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/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.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/configuration/tides/IERS2010TidalCorrection.html ...]
|-
|'''IERS2003TidalCorrection'''
|Compute tidal correction of the pole motion.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/configuration/tides/IERS2003TidalCorrection.html ...]
|-
|'''NoTidalCorrection'''
|This class ignores the tidal effects.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/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.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/configuration/eop/EOP2000History.html ...]
|-
|'''EOP2000HistoryConstantOutsideInterval'''
| This class extends the EOP2000History but returns boundaries values when date is out of data range.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/configuration/eop/EOP2000HistoryConstantOutsideInterval.html ...]
|-
|'''EOPC04FilesLoader'''
| This class is a generic reader for EOPC04 files.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/frames/configuration/eop/EOPC04FilesLoader.html ...]
|}

[[Category:User_Manual_4.17_Flight_Dynamics]]

User Manual 4.17 Orbital parameters

2025-11-26T13:49:56Z

Admin tsn : Page créée avec « __NOTOC__ == Introduction == === Scope === The "Orbital parameters" package contains classes to represent the orbital state of a space object. Several types of parameters are available (cartesian, keplerian, equinoctial... with different position angle definitions : true, mean, eccentric). Orbital parameters do not define a date nor a frame. To fully define an orbit, including date and frame, please refer to [FDY_Orbits_Home Orbits]. === Javadoc === The classe... »

__NOTOC__
== Introduction ==

=== Scope ===
The "Orbital parameters" package contains classes to represent the orbital state of a space object. Several types of parameters are available (cartesian, keplerian, equinoctial... with different position angle definitions : true, mean, eccentric).
Orbital parameters do not define a date nor a frame. To fully define an orbit, including date and frame, please refer to [FDY_Orbits_Home Orbits].

=== Javadoc ===
The classes for orbital parameters description are available in the package <code>fr.cnes.sirius.patrius.orbits.orbitalparameters</code>.

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
| Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/orbits/orbitalparameters/package-summary.html Package fr.cnes.sirius.patrius.orbits.orbitalparameters]
|}

=== Links ===
None as of now.

=== Useful Documents ===
None as of now.

=== Package Overview ===
All different orbital parameters types extend the abstract class AbstractOrbitalParameters and implement the interface IOrbitalParameters (the following class package may not contain all classes extending AbstractOrbitalParameters class).

[[File:orbitalparameters.png|center]]

All conversions methods from one type to another are specifically handled by each type of orbital parameters, thus optimising conversions.

== Features Description ==
=== Available parameters ===
The available parameters types are :
* Cartesian : X, Y, Z, Vx, Vy, Vz
* Keplerian : a, e, i, perigee argument, right ascension of ascending node, anomaly (in each position angle types)
* Equinoctial : a, ex, ey (eccentricity vector), hx, hy (inclination vector), longitude argument (in each position angle types)
* Alternate equinoctial : n (mean motion), ex, ey (eccentricity vector), hx, hy (inclination vector), longitude argument (in each position angle types but stored in mean)
* Stela Equinoctial : a, ex, ey (eccentricity vector), ix, iy (inclination vector), mean longitude argument
* Circular : a, ex, ey (eccentricity vector), i, right ascension of ascending node, latitude argument (in each position angle types)
* Apsis (using radius) : periapsis, apoapsis, i, perigee argument, right ascension of ascending node, anomaly (in each position angle types)
* Apsis (using altitude) : altitude of periapsis, altitude of apoapsis, i, perigee argument, right ascension of ascending node, anomaly (in each position angle types)
* Equatorial : a, e, longitude of the periapsis (ω + Ω), ix (first component of inclination vector), iy (second component of inclination vector), anomaly (in each position angle types)
* Reentry : altitude, latitude, longitude, velocity norm, slope of velocity, azimuth of velocity

== Getting Started ==
Any orbital parameters can be defined using the chosen constructor. Here is an example using circular parameters and true anomaly:

<syntaxhighlight lang="java">
final CircularParameters circularParameters = new CircularParameters(10000E3, 0.1, 0.2, 0.3, 0.4, 0.5, PositionAngle.TRUE, Constants.EGM96_EARTH_MU);
</syntaxhighlight>

Then conversions to any orbital parameters type can directly be obtained using the conversion routines. Here is an example of conversion to equinoctial parameters:

<syntaxhighlight lang="java">
final EquinoctialParameters equinoctialParameters = circularParameters .getEquinoctialParameters();
</syntaxhighlight>

== Contents ==

=== Interfaces ===
None as of now.

=== Classes ===
{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''CartesianParameters'''
|Cartesian parameters object.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/orbits/orbitalparameters/CartesianParameters.html ...]
|-
|'''KeplerianParameters'''
|Keplerian parameters object.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/orbits/orbitalparameters/KeplerianParameters.html ...]
|-
|'''CircularParameters'''
|Circular parameters object.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/orbits/orbitalparameters/CircularParameters.html ...]
|-
|'''EquinoctialParameters'''
|Equinoctial parameters object.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/orbits/orbitalparameters/EquinoctialParameters.html ...]
|-
|'''AlternateEquinoctialParameters'''
|Alternate Equinoctial parameters object.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/orbits/orbitalparameters/AlternateEquinoctialParameters.html ...]
|-
|'''StelaEquinoctialParameters'''
|Stela equinoctial parameters object.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/orbits/orbitalparameters/StelaEquinoctialParameters.html ...]
|-
|'''EquatorialParameters'''
|Equatorial parameters object.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/orbits/orbitalparameters/EquatorialParameters.html ...]
|-
|'''ApsisRadiusParameters'''
|Apsis parameters object (using radius).
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/orbits/orbitalparameters/ApsisRadiusParameters.html ...]
|-
|'''ApsisAltitudeParameters'''
|Apsis parameters object (using altitude).
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/orbits/orbitalparameters/ApsisAltitudeParameters.html ...]
|-
|'''ReentryParameters'''
|Reentry parameters object.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/orbits/orbitalparameters/ReentryParameters.html ...]
|}

[[Category:User_Manual_4.17_Flight_Dynamics]]

Catégorie:User Manual 4.17 Mathematics

2025-11-26T13:48:02Z

Admin tsn : Page créée avec «  == Introduction == center <center><blockquote> Willingly would I burn to death like Phaeton, were this the price for reaching the sun and learning its shape, its size and its substance. ''Eudoxus of Cnidus (408 - 355 B.C.)''</blockquote></center> This section is a short presentation of the Math Library implemented in PATRIUS. The Math library of PATRIUS is based on the Open-source Commons Math library. Commons-Math has enti... »

== Introduction ==
[[File:eudoxus-1.jpg|center]]

<center><blockquote>
Willingly would I burn to death like Phaeton, 
were this the price for reaching the sun and 
learning its shape, its size and its substance. 
''Eudoxus of Cnidus (408 - 355 B.C.)''</blockquote></center>

This section is a short presentation of the Math Library implemented in PATRIUS.

The Math library of PATRIUS is based on the Open-source Commons Math library.

Commons-Math has entirely been included in PATRIUS library. It is accessible through Patrius math package: fr.cnes.sirius.patrius.math package.

Since V4.2, the user can choose and define its low-level math framework (cos, sin, exp, etc.).

== Applicable and Reference Documents ==
=== Applicable Documents ===

'''[A1]''' ''CDCF - Fonctions de Base du Patrimoine de Dynamique du Vol'', V1.2, SIRIUS-CF-DV-0049-CN, 2011. 
'''[A2]''' ''Dossier de réutilisation Orekit et Commons Math'', V1.0, SIRIUS-DLR-DV-0080-CN, 2010.

=== Reference Documents ===

'''[R1]''' Nürnberg, R.; ''Distance from a Point to an Ellipse'', Imperial College London, 2006, [http://www2.imperial.ac.uk/~~rn/distance2ellipse.pdf http://www2.imperial.ac.uk/~~rn/distance2ellipse.pdf].

== Glossary ==
None Applicable.

== Overview ==
The Math package of PATRIUS has been developed according to the SIRIUS Scope Statement '''[A1]'''. The themes developed are described hereafter:

; Constants
: Implementation of mathematical and physical constants.

; Comparisons of Numbers
: For this theme, classes and methods of comparison that allow a precise comparison of number representations have been developed.

; Angles
: For this theme, angle utilities, such as intervals, have been implemented, and allow the user to perform multiple rigorous operations with modulus problems taken into account.

; Low-level math frameworks
: A low-level math framework provides methods to compute simple math function such as sin, cos, exp, log, etc. For this theme, a generic interface for low-level math framework has been defined. Several implementations are available (FastMath and Jafama).

; Dispersions
: Various algorithms have been developped to handle different kinds of random number generation.

; Vectors
: Vector-specific operations, particularly in the case of 2D and 3D vectors, have been developed and implemented in classes such as Vector3D. It is understood that by vector, a real column vector is actually manipulated.

; Matrices
: Matrix-specific operations, particularly in the case of 3x3 and 6x6 matrices, have been developed and implemented in classes such as Matrix3D.

; Quaternions
: Quaternion-specific operations have been developed and implemented in classes such as Quaternion. It is understood that this class represents the mathematical object quaternion and, as such, is not necessarily a rotation quaternion.

; Rotations
: Rotations implemented in PATRIUS are algebraic rotations that can be represented by normalized quaternions, rotation matrices or sequences of Euler angles. The prime objective of this design is to have all the rotation representations combined, making it easier for the user to manipulate such an object.

; Geometry
: The geometry section presents the geometry classes developed and implemented in PATRIUS. It currently includes the following objects : lines, planes, plates, parallelepipeds, cylinders, cones, ellipsoids and spherical caps.

; Interpolation methods
: Implementation of several methods : spline, bicubic, tricubic, Lagrange and Newton interpolation.

; Root-Finding algorithm
: Implementation of several algorithms : Brent, Newton, Bisection and Müller.

; Trigonometric polynomials
: Real trigonometric polynomials are implemented.

; Numerical differentiation
: Implementation of two numerical differentiation methods: finite difference and Ridders.

; Numerical integration
: Implementation of two numerical integration methods: Trapezoidal and Simpson.

; Numerical ordinary differential equations
: It is the part of numerical analysis which studies the numerical solution of ordinary differential equations (ODEs). Please note: this may sometimes be called numerical integration, but we assume here that numerical integration only refers to the computation of integrals (see the corresponding theme).

[[Catégorie:User Manual 4.17]]

User Manual 4.17 Trigonometric Polynomials and Fourier Series

2025-11-26T13:47:39Z

Admin tsn : Page créée avec « __NOTOC__ == Introduction == === Scope === This section presents the Trigonometric Polynomials implemented in PATRIUS as well as Fourier Series. === Javadoc === The trigonometric polynomial (and related) objects are available in the package <code>fr.cnes.sirius.patrius.math.analysis.polynomials</code> and the FFT algorithms in <code>fr.cnes.sirius.patrius.math.transform</code> {| class="wikitable" |- ! scope="col"| Library ! scope="col"| Javadoc |- |Patrius |[{... »

__NOTOC__
== Introduction ==
=== Scope ===
This section presents the Trigonometric Polynomials implemented in PATRIUS as well as Fourier Series.

=== Javadoc ===
The trigonometric polynomial (and related) objects are available in the package <code>fr.cnes.sirius.patrius.math.analysis.polynomials</code> and the FFT algorithms in <code>fr.cnes.sirius.patrius.math.transform</code>

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/polynomials/package-summary.html Package fr.cnes.sirius.patrius.math.geometry.analysis.polynomials]
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/transform/package-summary.html Package fr.cnes.sirius.patrius.math.transform]
|}

=== Links ===
Useful resources for this theme can be found here :

* [http://en.wikipedia.org/wiki/Trigonometric_polynomial Trigonometric Polynomials]
* [http://en.wikipedia.org/wiki/List_of_trigonometric_identities List of trigonometric identities]
* [http://en.wikipedia.org/wiki/Fourier_series Fourier Series]

=== Useful Documents ===
None.

=== Package Overview ===
None.

== Features Description ==
=== Trigonometric Polynomials ===
The trigonometric polynomials are defined as :

<math>\forall t \in \mathbb{R}, P(t) = a_0 + \sum_{k=0}^n \left( a_k \cos(kt) + b_k \sin(kt) \right)</math>

And the primitive of such a function is :

<math>\forall t \in \mathbb{R}, P(t) = a_0 t + c^{te} + \sum_{k=0}^n \left( {-b_k \over k} \cos(kt) + {a_k \over k} \sin(kt) \right)</math>

Classes that represent these functions are described in this section.
=== Fourier Series ===
Let <math>f</math> be a periodic, real variable, real function with period <math>T</math>. The ''partial sums of the Fourier Series'' of <math>f</math> are given by

<math>
\forall N \in \mathbb{R}^{+*}, \, \left(S_Nf\right)(x) = a_0 + \sum_{n=1}^N\left(a_n\cos\left(n t {2\pi\over T}\right) + b_n\sin\left(n t {2\pi\over T}\right)\right)
</math>

The Fourier coefficients (n > 0) of <math>f</math> are given by :

<math>
a_0 = {1\over T}\int_{-T/2}^{T/2} \! f(t) \, \mathrm{d}t
</math>

<math>
a_n = {2\over T}\int_{-T/2}^{T/2} \! f(t) \cos\left(n t {2\pi\over T}\right) \, \mathrm{d}t
</math>

<math>
b_n = {2\over T}\int_{-T/2}^{T/2} \! f(t) \sin\left(n t {2\pi\over T}\right) \, \mathrm{d}t
</math>

Classes that allow decomposing functions into finite Fourier series are described.

=== Fast Fourier Transforms ===
A fast Fourier transform (FFT) is an algorithm to compute the discrete Fourier transform (DFT) and its inverse. Fourier analysis converts time (or space) to frequency and vice versa. An FFT rapidly computes such transformations by factorizing the DFT matrix into a product of sparse (mostly zero) factors. 
Let <math>( X_0, ..., X_{N-1})</math> be complex numbers. The DFT is defined by the formula 
<math>X_k = \sum^{N-1}_{n=0} x_n e^{-2i\pi k n/N}, \quad k=\left\{0, ..., N-1\right\}.</math>

The class <code>FastFourierTransformer.java</code> owns two methods 
<code>transform(final double[] f, final TransformType type)</code> 
<code>transform(final Complex[] f, final TransformType type)</code> 
where <code>TransformType</code> is an enumeration that defines the type of transform which is to be computed. It can be FORWARD or INVERSE.

Depending on the size, this method will use a radix-2 algorithm if the size is a power-of-two, and the Bluestein algorithm otherwise. Both algorithms are explained above.

==== The Cooley–Tukey & radix-2 the algorithm ====

By far the most commonly used FFT algorithm. This is a divide and conquer algorithm that recursively breaks down a DFT of any composite size <math>N = N_1N_2</math> into many smaller DFTs of sizes <math>N_1</math> and <math>N_2</math>, along with <math>O(N)</math> multiplications by complex roots of unity. 
The radix-2 algorithme is the most common use of FFT algorithm and is based on the Cooley–Tukey algorithm. It divides the transform into two pieces of size <math>N/2</math> at each step, and is therefore limited to power-of-two sizes.

==== The Bluestein algorithm ====

It is commonly called the chirp z-transform algorithm. It computes the discrete Fourier transform (DFT) of arbitrary sizes (including prime sizes) by re-expressing the DFT as a convolution. For more information, see [http://en.wikipedia.org/wiki/Bluestein%27s_FFT_algorithm http://en.wikipedia.org/wiki/Bluestein%27s_FFT_algorithm]

== Getting Started ==

=== Usage of a trigonometric polynomial ===
* To create the polynomial <math>P(x) =-2 + \cos(x) + 2\sin(3x)</math>, use the following code snippet :

<syntaxhighlight lang="java">
double a0 =-2;
double[] a = new double[] {1, 0, 0};
double[] b = new double[] {0, 0, 2};
TrigonometricPolynomialFunction myPol2 = new TrigonometricPolynomialFunction(a0, a, b);
</syntaxhighlight>

* To get the value of the second derivative at <math>x = 5</math>, use the following snippet :

<syntaxhighlight lang="java">
double result = myPol2.value(2,5);
// equivalent to
double result = myPol2.polynomialDerivative(2).value(5);
</syntaxhighlight>

* To get the primitive :

<syntaxhighlight lang="java">
// With an integration constant c = 1 :
TrigonometricPolynomialPrimitive result = myPol2.polynomialPrimitive(1.);
</syntaxhighlight>

* To multiply two trigonometric polynomials <math>p1</math> and <math>p2</math> :

<syntaxhighlight lang="java">
TrigonometricPolynomialFunction result = p1.multiply(p2);
</syntaxhighlight>

=== Decomposing a UnivariateFunction into a Fourier Series ===
Given a user function with period T :

<syntaxhighlight lang="java">
UnivariateFunction f = new UnivariateFunction () {
public double value(double x) {
// ...
return result;
}
};
</syntaxhighlight>

The user must build an instance of the FourierDecompositionEngine (using an [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/integration/UnivariateIntegrator.html integrator]) :

<syntaxhighlight lang="java">
FourierDecompositionEngine engine = new FourierDecompositionEngine( integrator );
</syntaxhighlight>

And pass the function, period and approximation order to it.'''NOTE :''' It is left up to the user to make sure that the specified period is coherent with the function as no internal check is conducted.

<syntaxhighlight lang="java">
engine.setOrder(10);
engine.setFunction(f, T);
</syntaxhighlight>

Then, the user can call the <code>decompose( )</code> method :

<syntaxhighlight lang="java">
FourierSeriesApproximation approximation = engine.decompose();
FourierSeries fourier = approximation.getFourier();
</syntaxhighlight>

'''Example'''

The following code snippet shows how to decompose a square function of period 2 to the 10th order :

<syntaxhighlight lang="java">
// function definition
UnivariateFunction function = new UnivariateFunction() {
public double value(final double x) {
final double local = x- FastMath.floor(x / 2) * 2;
if (local >= 1) {
return-1;
} else {
return 1;
}
}
};

// Engine parameters
UnivariateIntegrator integrator = new LegendreGaussIntegrator(5, 1e-14, 1e-14);
FourierDecompositionEngine engine = new FourierDecompositionEngine(integrator);
engine.setMaxEvals(Integer.MAX_VALUE);

// decompose
double period = 2;
engine.setOrder(10);
engine.setFunction(function, period);
FourierSeriesApproximation result = engine.decompose();
FourierSeries fourier = result.getFourier();
</syntaxhighlight>

The function and its approximation are shown hereunder. The parasite undulations are known as the [http://en.wikipedia.org/wiki/Gibbs_phenomenon Gibbs Phenomenon] :

[[File:square10.PNG|center]]

== Contents ==
=== Interfaces ===

{| class="wikitable"
|-
! scope="col"| Interface
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''UnivariateDifferentiableFunction'''
|Extension of UnivariateFunction representing a differentiable univariate function.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis//differentiation/UnivariateDifferentiableFunction.html ...]
|-
|'''IntegrableUnivariateFunction'''
|Extension of UnivariateRealFunction representing an integrable univariate function.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/IntegrableUnivariateFunction.html ...]
|-
|'''UnivariateFunction'''
|Interface representing an univariate function.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/UnivariateFunction.html ...]
|-
|'''IFastFourierTransformer'''
|Interface representing a FFT.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/transform/IFastFourierTransformer.html ...]
|}

=== Classes ===

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''FourierDecompositionEngine'''
|Decompose a UnivariateFunction as a Fourier Series using TrigonometricPolynomialFunction representation.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/polynomials/FourierDecompositionEngine.html ...]
|-
|'''FourierSeries'''
|This class represents a finite Fourier Series.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/polynomials/FourierSeries.html ...]
|-
|'''FourierSeriesApproximation'''
|Holder for a UnivariateFunction and its FourierSeries approximation.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/polynomials/FourierSeriesApproximation.html ...]
|-
|'''TrigonometricPolynomialFunction'''
|This class is the Trigonometric Polynomial Function class.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/polynomials/TrigonometricPolynomialFunction.html ...]
|-
|'''TrigonometricPolynomialPrimitive'''
|This class represents a Trigonometric Polynomial Primitive.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/polynomials/TrigonometricPolynomialPrimitive.html ...]
|-
|'''AbstractFastFourierTransformer'''
| Abstract class representing a FFT.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/transform/AbstractFastFourierTransformer.html ...]
|-
|'''FastFourierTransformer'''
| Computes the FFT for real and complex arrays.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/transform/FastFourierTransformer.html ...]
|}

[[Category:User_Manual_4.17_Mathematics]]

User Manual 4.17 Matrices

2025-11-26T13:47:20Z

Admin tsn : Page créée avec « __NOTOC__ == Introduction == === Scope === This section will focus on the following aspects : * Matrix3D and Vector3D * Generic Matrices * UD Decomposition === Javadoc === The relevant packages are documented here : {| class="wikitable" |- ! scope="col"| Library ! scope="col"| Javadoc |- | Patrius |[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/linear/package-summary.html Package fr.cnes.sirius.patrius.math.linear] |- | Patrius |[{{JavaDoc4.17}}/fr/cnes/sirius/... »

__NOTOC__
== Introduction ==
=== Scope ===
This section will focus on the following aspects :

* Matrix3D and Vector3D
* Generic Matrices
* UD Decomposition

=== Javadoc ===
The relevant packages are documented here :

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
| Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/linear/package-summary.html Package fr.cnes.sirius.patrius.math.linear]
|-
| Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/package-summary.html Package fr.cnes.sirius.patrius.math.geometry.euclidean.threed]
|}

=== Links ===
None as of now.

=== Useful Documents ===
None as of now.

=== Packages Overview ===
The matrices functionality can be found in the following packages :

* <code>fr.cnes.sirius.patrius.math.geometry.euclidean.threed</code> for Vector3D, Matrix3D
* <code>fr.cnes.sirius.patrius.math.linear</code> for RealMatrix, AbstractRealMatrix, Array2DRowRealMatrix, UDDecomposition, UDDecompositionImpl ...

Please note that not all implementations are present in the following diagram for the sake of clarity.

[[File:PATRIMOINESIRIUSDiagrammeMUmatricesgeneriques.png]]

== Features Description ==
=== The Matrix3D class ===
The Matrix3D is a real matrix designed to be used in geometric calculations. The Matrix3D is compatible with the Vector3D type, unlike the matrices implemented in the package "linear".

The packages "linear" and "geometry" both contains classes to represent vectors and matrices, but without any compatibility (for example, the "multiply" methods availables in the generic real matrices only accept the objects from the "linear" package).

To make possible the operations using both types of vectors and matrices, a constructor and a getter are added to the Vector3D and Matrix3D classes.

The constructor creates the object from a similar one (containing the same data) from the "linear" package.

For vectors :

<syntaxhighlight lang="java">
ArrayRealVector realVector = new ArrayRealVector(data);
Vector3D vector3D = new Vector3D(realVector);
</syntaxhighlight>

For matrices, the operation is described in the previous paragraph.

This construction works only if the generic real vectors and matrices dimensions are right (3 for the vectors and 3x3 for the matrices).

The getters are : "getRealMatrix()" in the Matrix3D class and "getRealVector()" in the Vector3D class. They return the generic objects containing identical data.

=== Generic real matrices ===
The library also provides generic representations of real matrices, of any size.

The RealMatrix interface presents the following services :

* usual operations (adding, multiplying)
* extraction of submatrices
* symmetry and antisymmetry tests
* orthogonality tests
* diagonality tests
* invertibility tests

The Array2DRowRealMatrix is one available implementation for generic real matrices.

=== Decompositions ===

PATRIUS provides several ways for matrix decomposition. Interface for decomposition is <code>Decomposition</code>.
A decomposition provides a way to:
* Inverse a matrix
* Separate a matrix into a product of specific matrices (orthogonal, upper triangular, etc.) depending on the solver type.
Standard decomposition in PATRIUS are:
* <code>QRDecomposition</code>
* <code>LUDecomposition</code>
* <code>CholeskyDecomposition</code>
* <code>SingularValueDecomposition</code>
* <code>UDDecompositionImpl</code>
RealMatrix interface possesses a method to get its inverse. If not provided, by default a <code>LUDecomposition</code>is used.
The QR decomposition method implements an optimisation option which is able to provide an improved process pour des matrices creuses (option "parallel" to be used for the related constructor).

==== Exemple with UD decomposition ====
The library can compute the UD decomposition of a matrix.

The UD-decomposition of the matrix A is a set of three matrices such that A = UxDxU^^t^^ with :

* U is an upper triangular matrix,
* D is a diagonal matrix,
* U^^t^^ is the transpose of U.

=== Symmetric matrices ===

Symmetric matrices are handled through the generic <code>SymmetricMatrix</code> interface.
An implementation is provided: <code>ArrayRowSymmetricMatrix</code>. This implementation optimally stores data in one single 1D-array.

== Getting Started ==

=== Matrix3D and Vector3D ===
==== The Matrix3D class ====

A Matrix3D instance be constructed from doubles :

<syntaxhighlight lang="java">
double[][] data = { {1d,2d,3d}, {2d,5d,3d}, {1d,0d,8d} };

Matrix3D matrix3d = new Matrix3D(data);
</syntaxhighlight>

Or from a RealMatrix :

<syntaxhighlight lang="java">
Array2DRowRealMatrix matrixCM = new Array2DRowRealMatrix(data);

Matrix3D matrix3D = new Matrix3D(matrixCM);
</syntaxhighlight>

If the RealMatrix or data dimensions are not 3x3, a MathIllegalArgumentException is thrown.

Some basic methods are available in it :

* Matrix3D / Matrix3D addition

<syntaxhighlight lang="java">
Matrix3D matrix3d_result = matrix3d_1.add(matrix3d_2);
</syntaxhighlight>

* Matrix3D / Matrix3D subtraction

<syntaxhighlight lang="java">
Matrix3D matrix3d_result = matrix3d_1.subtract(matrix3d_2);
</syntaxhighlight>

* Matrix3D / Matrix3D multiplication

<syntaxhighlight lang="java">
Matrix3D matrix3d_result = matrix3d_1.multiply(matrix3d_2);
</syntaxhighlight>

* Matrix3D / Vector3D multiplication

<syntaxhighlight lang="java">
Vector3D vector3d_result = matrix3d.multiply(vector3d);
</syntaxhighlight>

* Matrix3D / double multiplication

<syntaxhighlight lang="java">
Matrix3D matrix3d_result = matrix3d.multiply(2.0);
</syntaxhighlight>

* transposition

<syntaxhighlight lang="java">
Matrix3D transposed_matrix3d = matrix3d.transpose();
</syntaxhighlight>

* minimum

<syntaxhighlight lang="java">
double min = matrix3d.getMin();
</syntaxhighlight>

* maximum

<syntaxhighlight lang="java">
double max = matrix3d.getMax();
</syntaxhighlight>

* absolute values

<syntaxhighlight lang="java">
RealMatrix abs_matrix3d = matrix3d.getAbs();
</syntaxhighlight>

* transposition and Matrix3D / Vector3D multiplication

<syntaxhighlight lang="java">
Vector3D vector3d_result = matrix3d.transposeAndMultiply(vector3d);
</syntaxhighlight>

* test : orthogonal matrix ? Uses the same-named function in AbstractRealMatrix : same principle, same use.

* getRealMatrix : returns an Array2dRowRealMatrix with the same data in it

<syntaxhighlight lang="java">
RealMatrix realmatrix = matrix3d.getRealMatrix();
</syntaxhighlight>

* toString : creates a string containing all the values.

<code> final Matrix3D matrix = new Matrix3D(testData);</code> 
returns <code>"Matrix3D{{1.0,2.0,3.0},{2.0,5.0,3.0},{1.0,0.0,8.0}}"</code>

=== Generic matrices ===
==== The AbstractRealMatrix class ====

===== Symmetry and antisymmetry tests =====

The RealMatrix interface and the AbstractRealMatrix abstract class contain the two methods isSymmetric and isAntisymmetric to test if a real matrix is symmetric or antisymmetric:

<syntaxhighlight lang="java">
Array2DRowRealMatrix sym = new Array2DRowRealMatrix(symmetricData);

boolean isSymmetric = sym.isSymmetric() ;
</syntaxhighlight>

The returned boolean is TRUE if the matrix is symmetric. The equality test made on each value uses the MathUtils.equalsWithRelativeTolerance method, with an algorithm using a relative threshold described in the “Doubles Values Comparisons” paragraph of the SUM.

isAntisymmetric needs a threshold given by the user for the comparisons the zero of the diagonal values. This threshold can be taken as MathUtils.DOUBLES_COMPARISON_EPSILON for standard cases.

But if the matrix contains values closer to zero than this epsilon (1.0e-14), the user shall define their own threshold.

For the rest of the values tested (other than the diagonal), the same method as in isSymmetric is used.

<syntaxhighlight lang="java">
Array2DRowRealMatrix antisym = new Array2DRowRealMatrix(antisymmetricData);

boolean isAntisymmetric = antisym.isAntisymmetric(Precision.DOUBLE_COMPARISON_EPSILON) ;
</syntaxhighlight>

The returned boolean is TRUE if the matrix is antisymmetric.

===== Orthogonal test =====

In order to know if a real matrix is orthogonal, one can use the method isOrthogonal(), this method checks if the column vectors form an orthonormal set :

<syntaxhighlight lang="java">
double[][] orthogonalMatrix = {{ 8.0 / 9.0, 1.0 / 9.0,-4.0 / 9.0 },
{-4.0 / 9.0, 4.0 / 9.0, -7.0 / 9.0 },
{ 1.0 / 9.0, 8.0 / 9.0, 4.0 / 9.0 }};
RealMatrix matrix = new Array2DRowRealMatrix(orthogonalMatrix);
matrix.isOrthogonal(Precision.EPSILON, Precision.EPSILON));
</syntaxhighlight>

Of course, because a matrix usually results from several operations which can introduce numerical errors, one has to give 2 thresholds under which the matrix is considered to be orthogonal. These thresholds concern the normality and the orthogonality of the column vectors of the matrix.

===== Diagonal test =====

In order to know if a real matrix is diagonal, one can use the method isDiagonal() :

<syntaxhighlight lang="java">
double[][] diagonalMatrix = {{ 4.0, 0.0, 0.0, 0.0 },
{ 0.0,-1.0, 0.0, 0.0 },
{ 0.0, 0.0, 5.0, 0.0 },
{0.0, 0.0, 0.0, 9.0 }};
RealMatrix matrix = new Array2DRowRealMatrix(diagonalMatrix);
matrix.isDiagonal(Precision.EPSILON);
</syntaxhighlight>

Of course, because a matrix usually results from several operations which can introduce numerical errors, one has to give a threshold under which the non diagonal elements are considered to be zero ie the matrix is considered to be diagonal.

===== Invertible test =====

In order to know if a real matrix is invertible, one can use the method isInvertible(), this method checks if the n column vectors form a basis of Rn :

<syntaxhighlight lang="java">
double[][] nonSingularMatrix = {{ 4.0, 2.0,-1.5, 2.0 },
{ 6.0, 8.0, 2.1, 2.5 },
{ 2.0, 1.0,-0.75, 1.0 },
{-1.0, 0.0, 0.0, -0.5 }};
RealMatrix matrix = new Array2DRowRealMatrix(nonSingularMatrix);
matrix.isInvertible(Precision.EPSILON);
</syntaxhighlight>

Of course, because a matrix usually results from several operations which can introduce numerical errors, one has to give a threshold under which the column vectors are considered linearly dependant.

=== UD decomposition ===
==== The UDDecompositionImpl class ====

The UDDecompositionImpl class is the one performing the UD-decomposition of a matrix.

If the RealMatrix A is not square, a NonSquareMatrixException is thrown.
If the RealMatrix A is not symmetric, a NonSymmetricMatrixException is thrown.
If the RealMatrix A is not positive definite, a NonPositiveDefiniteMatrixException is thrown.

Two constructors are available :

* default constructor :
<code>UDDecompositionImpl(matrix,relativeSymmetryThreshold,absolutePositivityThreshold)</code>

with

* '''matrix''' = matrix to factorize,
** '''relativeSymmetryThreshold''' = threshold above which off-diagonal elements are considered too different and matrix not symmetric,
** '''absolutePositivityThreshold''' = threshold below which diagonal elements are considered null and matrix not positive definite

* basic constructor :
<code>UDDecompositionImpl(matrix)</code>

with

* '''matrix''' = matrix to factorize with relativeSymmetryThreshold = DEFAULT_RELATIVE_SYMMETRY_THRESHOLD (1.0e-15) and absolutePositivityThreshold = DEFAULT_ABSOLUTE_POSITIVITY_THRESHOLD (0.0)

The following methods are available in it :

<syntaxhighlight lang="java">
final UDDecomposition udut = new UDDecompositionImpl(matrix);
</syntaxhighlight>

* get the U matrix

<syntaxhighlight lang="java">
RealMatrix Umatrix = udut.getU();
</syntaxhighlight>

* get the D matrix

<syntaxhighlight lang="java">
RealMatrix Dmatrix = udut.getD();
</syntaxhighlight>

* get the U^^t^^ matrix

<syntaxhighlight lang="java">
RealMatrix UTmatrix = udut.getUT();
</syntaxhighlight>

* get the determinant

<syntaxhighlight lang="java">
double d = udut.getDeterminant();
</syntaxhighlight>

* get the solver based on the UD decomposition

<syntaxhighlight lang="java">
DecompositionSolver s = udut.getSolver();
</syntaxhighlight>

== Contents ==
=== Interfaces ===
The most relevant interfaces related to matrices are listed here :

{| class="wikitable"
|-
! scope="col"| Interface
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''Vector<S extends Space>'''
|This interface represents a generic vector in a vectorial space or a point in an affine space.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/Vector.html ...]
|-
|'''RealMatrix'''
|Interface defining a real-valued matrix with basic algebraic operations.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/linear/RealMatrix.html ...]
|-
|'''SymmetricMatrix'''
| Interface for symmetric matrices.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/linear/SymmetricMatrix.html ...]
|-
|'''SymmetricPositiveMatrix'''
| Interface for symmetric positive matrices.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/linear/SymmetricPositiveMatrix.html ...]
|-
|'''Decomposition'''
| Interface for matrices decompositions.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/linear/Decomposition.html ...]
|-
|'''DecompositionSolver'''
| Interface for matrices decompositions solvers. In particular thses solvers provides the inverse of a matrix.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/linear/DecompositionSolver.html ...]
|-
|'''UDDecomposition'''
|An interface to classes that implement an algorithm to calculate the UD-decomposition of a real matrix.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/linear/UDDecomposition.html ...]
|}

=== Classes ===
The most relevant classes related to matrices are listed here :

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''Vector3D'''
|This class implements vectors in a three-dimensional space.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/Vector3D.html ...]
|-
|'''Matrix3D'''
|This is a real 3x3 matrix designed to be used in geometric calculations. It is compatible with the Vector3D type.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/Matrix3D.html ...]
|-
|'''Array2DRowRealMatrix'''
|Implementation of RealMatrix using a double[][] array to store entries and LU decomposition to support linear system solution and inverse.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/linear/Array2DRowRealMatrix.html ...]
|-
|'''ArrayRowSymmetricMatrix'''
| Implementation of a symmetric matrix, implementing AbstractRealMatrix using a double[] array to store entries : storage convention is symmetric conventional full storage.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/linear/ArrayRowSymmetricMatrix.html ...]
|-
|'''DiagonalMatrix'''
| Implementation of a diagonal matrix.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/linear/DiagonalMatrix.html ...]
|-
|'''QRDecomposition'''
|Calculates the QR decomposition of a matrix.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/linear/QRDecomposition.html ...]
|-
|'''LUDecomposition'''
|Calculates the LU decomposition of a matrix.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/linear/LUDecomposition.html ...]
|-
|'''CholeskyDecomposition'''
|Calculates the Cholesky decomposition of a matrix.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/linear/CholeskyDecomposition.html ...]
|-
|'''SingularValueDecomposition'''
|Calculates the SVD decomposition of a matrix.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/linear/SingularValueDecomposition.html ...]
|}

[[Category:User_Manual_4.17_Mathematics]]

User Manual 4.17 Interpolation Methods

2025-11-26T13:47:04Z

Admin tsn : Page créée avec « __NOTOC__ == Introduction == === Scope === In this section, a focus is realised on the following interpolation methods: spline, bicubic, tricubic, Lagrange and Newton, covariance matrix and linear in 1D, 2D or 3D interpolation. === Javadoc === The interpolation objects are available in the package <code>fr.cnes.sirius.patrius.math.analysis.interpolation</code> and in the package <code>fr.cnes.sirius.patrius.propagation.analytical.covariance</code>. {| class="... »

__NOTOC__
== Introduction ==
=== Scope ===
In this section, a focus is realised on the following interpolation methods: spline, bicubic, tricubic, Lagrange and Newton, covariance matrix and linear in 1D, 2D or 3D interpolation.

=== Javadoc ===
The interpolation objects are available in the package <code>fr.cnes.sirius.patrius.math.analysis.interpolation</code> and in the package <code>fr.cnes.sirius.patrius.propagation.analytical.covariance</code>.

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
| Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/interpolation/package-summary.html Package fr.cnes.sirius.patrius.math.analysis.interpolation]
|-
| Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/interpolation/package-summary.html Package fr.cnes.sirius.patrius.math.analysis.interpolation]
|-
| Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/propagation/analytical/covariance/package-summary.html Package fr.cnes.sirius.patrius.propagation.analytical.covariance]
|}

=== Links ===
None as of now.

=== Useful Documents ===
None as of now.

=== Package Overview ===
The package <code>fr.cnes.sirius.patrius.math.analysis.interpolation</code> contains all the interpolation classes described in this section.

== Features Description ==
=== Spline interpolation ===
The '''''spline interpolator''''' generates an interpolating function <math>f(x): \mathbb{R} \rightarrow \mathbb{R}</math>. The user gives as entries 2 sets of values, the values of x, y. The interpolator gives the function f such as <math>y=f(x)</math>.

For the linear equation <math>y=2x+1</math>

<syntaxhighlight lang="java">
double x[] = { 0.0, 1.0, 2.0 };
double y[] = { 1.0, 3.0, 5.0 };

UnivariateInterpolator interpolator = new SplineInterpolator();
UnivariateFunction function = interpolator.interpolate(x, y);
double value = function .value(0.5);
</syntaxhighlight>
=== Bicubic interpolation ===
The '''''bicubic interpolator''''' generates an interpolating function <math>f(x,y): \mathbb{R}^2 \rightarrow \mathbb{R}</math>. The interpolator computes internally the coefficients of the bicubic function that is the interpolating function. The user gives as entries 3 sets of values, the values of x, y and z. The interpolator gives the function f such as <math>z=f(x,y)</math>.

For the equation of the plane <math>z=2x-3y + 5</math>

<syntaxhighlight lang="java">
double x[] = { 3, 4, 5, 6.5 };
double y[] = {-4, -3, -1, 2, 2.5 };
double z[][] = {{ 23, 20, 14, 5, 3.5 },
{ 25, 22, 16, 7, 5.5 },
{ 27, 24, 18, 9, 7.5 },
{ 30, 27, 21, 12, 10.5 }};
BivariateGridInterpolator interpolator = new BicubicSplineInterpolator();
BivariateFunction function = interpolator.interpolate(x, y, z);
</syntaxhighlight>

=== Tricubic interpolation ===
The '''''tricubic interpolator''''' generates an interpolating function <math>f(x,y,z): \mathbb{R}^3 \rightarrow \mathbb{R}</math>. The interpolator computes internally the coefficients of the tricubic function that is the interpolating function. The user gives as entries 4 sets of values, the values of x, y, z and w. The interpolator gives the function f such as <math>w=f(x,y,z)</math>.

For the equation of the plane <math>w=2x- 3y - z + 5</math>

<syntaxhighlight lang="java">
double x[] = { 3.0, 4.0, 5.0, 6.5 };
double y[] = {-4.0, -3.0, -1.0, 2.0, 2.5 };
double z[] = {-12.0, -8.0, -5.5, -3.0, 0.0, 2.5 };
double w[][][] = {{{ 35, 31, 28.5, 26, 23, 20.5 },
{ 32, 28, 25.5, 23, 20, 17.5 },
{ 26, 22, 19.5, 17, 14, 11.5 },
{ 17, 13, 10.5, 8, 5, 2.5 },
{ 15.5, 11.5, 9, 6.5, 3.5, 1 }},
{{ 37, 33, 30.5, 28, 25, 22.5 },
{ 34, 30, 27.5, 25, 22, 19.5 },
{ 28, 24, 21.5, 19, 16, 13.5 },
{ 19, 15, 12.5, 10, 7, 4.13 },
{ 17.5, 13.5, 11, 8.5, 5.5, 3 }},
{{ 39, 35, 32.5, 30, 27, 24.13 },
{ 36, 32, 39.5, 27, 24, 21.5 },
{ 30, 26, 23.5, 21, 18, 15.5 },
{ 21, 17, 14.13, 12, 9, 6.5 },
{ 19.5, 15.5, 13, 10.5, 7.5, 5 }},
{{ 42, 38, 35.5, 33, 30, 27.5 },
{ 39, 35, 32.5, 30, 27, 24.13 },
{ 33, 29, 26.5, 24, 21, 18.5 },
{ 24, 20, 17.5, 15, 12, 9.5 },
{ 22.5, 18.5, 16, 13.5, 10.5, 8 }}};

TrivariateGridInterpolator interpolator = new TricubicSplineInterpolator();
TrivariateFunction function = interpolator.interpolate(x, y, z, w);
</syntaxhighlight>

=== Lagrange interpolation ===
The '''''Lagrange interpolator''''' generates an interpolating function <math>f(x): \mathbb{R} \rightarrow \mathbb{R}</math>. The user gives as entries 2 sets of values, the values of x, y. The interpolator gives the function f such as <math>y=f(x)</math>.

For the linear equation <math>y=2x+1</math>

<syntaxhighlight lang="java">
double x[] = { 0.0, 1.0, 2.0 };
double y[] = { 1.0, 3.0, 5.0 };

UnivariateFunction interpolator = new PolynomialFunctionLagrangeForm(x,y);
double value = interpolator.value(0.5);
</syntaxhighlight>

=== Newton interpolation ===
The '''''Newton interpolator''''' generates an interpolating function <math>f(x): \mathbb{R} \rightarrow \mathbb{R}</math>. The user gives as entries 2 sets of values, the coefficients <math>c_i</math>and the centers <math>x_i</math>such as the polynomial function <math>P(x)=c_0 + c_1 (x - x_0) + ... + c_n (x - x_n)</math>. The interpolator gives the function f such as <math>y=P(x)</math>.

For the linear equation <math>y=2x+1</math>

<syntaxhighlight lang="java">
double c_i[] = { 3.0, 2.0 };
double x_i[] = { 1.0 };

UnivariateFunction interpolator = new PolynomialFunctionNewtonForm(c_i,x_i);
double value = interpolator.value(0.5);
</syntaxhighlight>

=== Covariance matrix interpolation ===
The purpose of this interpolation algorithm is to compute the covariance matrix at a given date through a simplified model of the transition matrix. When a covariance in PV coordinates is searched for an object orbiting around an celestial body, a simple dynamical model can be used, meaning limited to the newtonian attraction, plus a constant acceleration. The value of this constant acceleration will not change the transition matrix.

The transition matrix between a date <math>t_1</math> and a date <math>t</math> can be approximated :

* at order 0 : by <math>\phi_1(t_1, t) = I_{3 \times 3}</math>

* at order 1 : by <math>\phi_1(t_1, t) = I_{3 \times 3} + J_{PV} ( t- t_1)</math>

* at order 2 : by<math>\phi_1(t_1, t) =I_{3 \times 3} + J_{PV} ( t- t_1)+ 0.5 * J_{PV}^2 ( t - t_1)^2</math>

where <math>J_{PV} = \left(\begin{array}{cc} 0_{3 \times 3} & I_{3 \times 3} \\ A & 0_{3 \times 3} \end{array} \right)</math>, <math>J_{PV}^2 = \left(\begin{array}{cc} A & 0_{3 \times 3} \\ 0_{3 \times 3} & A \end{array} \right)</math> and <math>A =- \frac{ GM}{r^3}\left(I_{3 \times 3} - 3 \frac{ PP^T}{r^2}\right)</math>, where <math>A</math> is considered as a constant on the interval <math>[t_1,t]</math> and <math>P</math> is the satellite position vector.

We denote by <math>M(t)</math> the covariance matrix at instant t. Let <math>t \in [t_1,t]</math> . The transition matrices <math>\phi_1(t_1, t)</math> and <math>\phi_2(t_2, t)</math> are given by the above formula, and since matrix <math>A</math> is constant on <math>[t_1,t_2]</math>, we have that the covariance matrix at instant <math>t</math> is given by
<math>M(t) = (1- \alpha) \phi_1(t_1, t) M(t_1)\phi_1^T(t_1, t) + \alpha \phi_2(t_2, t) M(t_2)\phi_2^T(t_2, t),</math>
with <math>\alpha = \frac{t-t_1}{t_2-t_1}</math>.
=== Linear interpolation ===
These classes allow linear piecewise interpolations in dimensions 1, 2 or 3.

==== 1D interpolation ====

Let <math>f</math> be a real function <math>\mathbb{R} \rightarrow \mathbb{R}</math> and <math>[x_1,x_2]</math> the interpolation interval, where <math>f(x_1),f(x_2)</math> are known. For all <math>x \in [x_1,x_2]</math>, the interpolated value <math>f(x)</math> is given by
<math>f(x) = f(x_1) + (x-x_1) \frac{f(x_2)- f(x_1)}{x_2-x_1}.</math>

==== 2D interpolation ====
The two dimensional interpolation will be two successive 1D interpolations.
Let <math>f</math> be a real function <math>\mathbb{R}^2 \rightarrow \mathbb{R}</math> and <math>[x_1,x_2] \times [y_1,y_2]</math> the interpolation interval.
First, a 1D interpolation in the <math>y</math> direction is made, leading to
<math>f(x,y_1) = f(x_1,y_1) + (y-y_1) \frac{f(x_2,y_1)- f(x_1,y_1)}{y_2-y_1},</math>

<math>f(x,y_2) = f(x_1,y_2) + (y-y_1) \frac{f(x_2,y_2)- f(x_1,y_2)}{y_2-y_1}.</math>

Then a second 1D interpolation is made in the <math>x</math> direction with the previous two interpolated values :
<math>f(x,y) = f(x,y_1) + (x-x_1) \frac{f(x,y_2)- f(x, y_1)}{x_2-x_1}.</math>

==== 3D interpolation ====

Let <math>f</math> be a real function <math>\mathbb{R}^3 \rightarrow \mathbb{R}</math> and <math>[x_1,x_2] \times [y_1,y_2] \times [z_1,z_2]</math> the interpolation interval. There will be <math>2^3- 1</math> successives 1D interpolations.

<math>f(x,y,z)</math> is interpolated from <math>f(x,y,z_1)</math> and <math>f(x,y,z_2)</math>.

<math>f(x,y,z_1)</math> is interpolated from <math>f(x,y_1,z_1)</math> and <math>f(x,y_2,z_1)</math>.

<math>f(x,y,z_2)</math> is interpolated from <math>f(x,y_1,z_2)</math> and <math>f(x,y_2,z_2)</math>.

<math>f(x,y_1,z_1)</math> is interpolated from <math>f(x_1,y_1,z_1)</math> and <math>f(x_2,y_1,z_1)</math>.

<math>f(x,y_2,z_1)</math> is interpolated from <math>f(x_1,y_2,z_1)</math> and <math>f(x_2,y_2,z_1)</math>.

<math>f(x,y_1,z_2)</math> is interpolated from <math>f(x_1,y_1,z_2)</math> and <math>f(x_2,y_1,z_1)</math>.

<math>f(x,y_2,z_2)</math> is interpolated from <math>f(x_1,y_2,z_2)</math> and <math>f(x_2,y_2,z_2)</math>.

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

== Contents ==
=== Interfaces ===
The library defines the following interfaces related to interpolation :

{| class="wikitable"
|-
! scope="col"| Interface
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''UnivariateInterpolator'''
|Interface for a univariate interpolating function.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/interpolation/UnivariateInterpolator.html ...]
|-
|'''BivariateGridInterpolator'''
|Interface for a bivariate interpolating function where the sample points must be specified on a regular grid.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/interpolation/BivariateGridInterpolator.html ...]
|-
|'''TrivariateGridInterpolator'''
|Interface for a trivariate interpolating function where the sample points must be specified on a regular grid.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/interpolation/TrivariateGridInterpolator.html ...]
|-
|'''UnivariateFunction'''
|Interface for a univariate function
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/UnivariateFunction.html ...]
|}

=== Classes ===
This section is about the following classes related to interpolation :

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''SplineInterpolator'''
|Spline interpolator for a univariate real function.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/interpolation/SplineInterpolator.html ...]
|-
|'''BicubicSplineInterpolator'''
|Bicubic spline interpolator for a bivariate real function.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/interpolation/BicubicSplineInterpolator.html ...]
|-
|'''TricubicSplineInterpolator'''
|Tricubic spline interpolator for a trivariate real function.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/interpolation/TricubicSplineInterpolator.html ...]
|-
|'''PolynomialFunctionLagrangeForm'''
|Lagrange interpolator, directly usable as a univariate real function.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/polynomials/PolynomialFunctionLagrangeForm.html ...]
|-
|'''PolynomialFunctionNewtonForm'''
|Newton interpolator, directly usable as a univariate real function.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/polynomials/PolynomialFunctionNewtonForm.html ...]
|}

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''CovarianceInterpolation'''
|Interpolator of a covariance matrix based on its two surrounding covariance matrices.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/propagation/analytical/covariance/CovarianceInterpolation.html ...]
|}

{| class="wikitable"
|-
! scope="col" |Class
! scope="col" | Summary
! scope="col" |Javadoc
|-
|'''CovarianceInterpolation'''
|Interpolator of a covariance matrix based on its two surrounding covariance matrices.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/propagation/analytical/covariance/CovarianceInterpolation.html ...]
|}

{| class="wikitable"
|-
! scope="col" |Class
! scope="col" |Summary
! scope="col" |Javadoc
|-
|'''AbstractLinearIntervalsFunction'''
|Abstract class for linear interpolations.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/interpolation/AbstractLinearIntervalsFunction.html ...]
|-
|'''UniLinearIntervalsFunction'''
| Linear one-dimensional function.
| [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/interpolation/UniLinearIntervalsFunction.html ...]
|-
|'''BiLinearIntervalsFunction'''
|Linear two-dimensional function.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/interpolation/BiLinearIntervalsFunction.html ...]
|-
|'''TriLinearIntervalsFunction'''
|Linear three-dimensional function.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/interpolation/TriLinearIntervalsFunction.html ...]
|-
|'''UniLinearIntervalsInterpolator'''
|Interpolator of linear one-dimensional functions.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/interpolation/UniLinearIntervalsInterpolator.html ...]
|-
|'''BiLinearIntervalsInterpolator'''
|Interpolator of linear two-dimensional functions.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/interpolation/BiLinearIntervalsInterpolator.html ...]
|-
|'''TriLinearIntervalsInterpolator'''
|Interpolator of linear three-dimensional functions.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/interpolation/TriLinearIntervalsInterpolator.html ...]
|}

{| class="wikitable"
|-
! scope="col" |Class
! scope="col" |Summary
! scope="col" |Javadoc
|-
|'''Covariance'''
|Class containing a covariance matrix and the list of parameter descriptors of every row in the covariance matrix
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/covariance/Covariance.html Covariance]
|-
|'''AbstractOrbitalCovariance'''
|An orbital covariance associates a Covariance instance with a given date and the frame, orbit type (Cartesian, Keplerian, etc) and position angle type (mean, true, eccentric) in which it is expressed.
|[{{JavaDoc4.17}}<nowiki>/fr/cnes/sirius/patrius/covariance/AbstractOrbitalCovariance.html AbstractOrbitalCovariance]</nowiki>
|-
|'''OrbitalCovariance'''
|Class containing a covariance matrix and its associated Orbit.
|[{{JavaDoc4.17}}<nowiki>/fr/cnes/sirius/patrius/covariance/OrbitalCovariance.html OrbitalCovariance]</nowiki>
|-
|'''MultiOrbitalCovariance'''
|Class containing a covariance matrix associated to multiple orbits
|[{{JavaDoc4.17}}<nowiki>/fr/cnes/sirius/patrius/covariance/MultiOrbitalCovariance.html MultiOrbitalCovariance]</nowiki>
|}

[[Category:User Manual 4.17 Mathematics]]

User Manual 4.17 Angles and Intervals

2025-11-26T13:46:48Z

Admin tsn : Page créée avec « __NOTOC__ == Introduction == === Scope === This section describes how angles, intervals and angle intervals are defined and used in the PATRIUS library. === Javadoc === The angle-related objects are available in the package <code>fr.cnes.sirius.patrius.math.interval</code> in the PATRIUS library. The class defining an interval end point, though, is in the package <code>fr.cnes.sirius.patrius.utils</code>. {| class="wikitable" |- ! scope="col"| Library ! scope=... »

__NOTOC__
== Introduction ==
=== Scope ===
This section describes how angles, intervals and angle intervals are defined and used in the PATRIUS library.

=== Javadoc ===
The angle-related objects are available in the package <code>fr.cnes.sirius.patrius.math.interval</code> in the PATRIUS library. The class defining an interval end point, though, is in the package <code>fr.cnes.sirius.patrius.utils</code>.

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/interval/package-summary.html Package fr.cnes.sirius.patrius.math.interval]
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/utils/package-summary.html Package fr.cnes.sirius.patrius.utils]
|}

=== Links ===
None as of now.

=== Useful Documents ===
None as of now.

=== Package Overview ===
The package <code>fr.cnes.sirius.patrius.utils</code> contains the class IntervalEndPoint that defines the type of boundary (CLOSED, OPEN) of an interval end.

The package <code>fr.cnes.sirius.patrius.utils</code> contains the actual angle-related classes.

[[File:PATRIMOINESIRIUSSUMDiagAngles.png]]

== Features Description ==
=== Generic intervals ===
An interval is made of two endpoints, and each endpoint may be closed or opened.

This is the most generic implementation of intervals : the class <code>GenericInterval<T></code>. The enumeration provides the endpoint types : CLOSED and OPEN.

This class is meant to be used as a parent class for all intervals implementations.

This class makes no assumption on the nature of the parameter class T, so it may create intervals of anything- but the functionality for this class is limited (we only have getters for the endpoints values, and their type). That's why it's meant to be used as a parent class.

The class is immutable, in the sense that the endpoints objects are set at the interval creation.

'''Mutable types should not be used as endpoint value types!'''

Examples :

<syntaxhighlight lang="java">
final IntervalEndpointType lowType = IntervalEndpointType.OPEN;
final Double lowValue = new Double(34.136);
final IntervalEndpointType upType = IntervalEndpointType.CLOSED;
final Double upValue = new Double(-2.3e34);
// Note the order of values is off : this class cannot enforce an order
final GenericInterval<Double> tgi = new GenericInterval<Double>(lowType, lowValue, upValue, upType);
final Double gLow = tgi.getLowerData();
assertTrue(gLow.equals(lowValue));
</syntaxhighlight>

Please see the Javadoc for more information.

Example with doubles: interval [1.0, 2.0[ :

<syntaxhighlight lang="java">
GenericInterval<Double> interval = new GenericInterval<Double>(IntervalEndpointType.CLOSED, 1.0, 2.0, IntervalEndpointType.OPEN);
</syntaxhighlight>

=== Comparable intervals ===
This implementation of intervals, <syntaxhighlight lang="java">ComparableInterval<T extends Comparable<T>></syntaxhighlight>, is for types implementing the Comparable interface ( for instance : <code>Integer</code>, <code>Double</code>).

This implementation inherits from <code>GenericInterval<T></code>; in addition to inherited capabilities, it enforces a proper order on the lower and upper endpoints. A <code>ComparableInterval</code> can also :

* tell if a given value is inside an interval
* tell if an interval is inside another
* tell if two intervals overlap
* merge two intervals
* ...

Please see the Javadoc for more information.

=== Angle intervals ===
The AngleInterval class represents an interval of doubles that shall be used to deal with angles. It contains the end points values and types (enum OPENED and CLOSED, class IntervalEndPointType), the mid value (“reference”) and the interval length.

=== Angle tools ===
This class is a toolbox containing static methods to perform operations on angles, for instance :

* angleInInterval : sets an angle in an interval modulo 2Pi

Due to numerical quality issues, the algorithm is the following :

- If the interval is of the form [a, a + 2Pi[, then
if x < a and x + 2Pi >= a + 2Pi, the angle is set to a (numerical quality issue due to the non-iqual repartition of real values around lower and upper boundaries)
if x = 2Pi, the angle is set to a
- If the interval is of the form ]a, a + 2Pi], then
if x > a + 2Pi and x – 2Pi <= a, the angle is set to a + 2Pi (numerical quality issue due to the non-iqual repartition of real values around lower and upper boundaries)
if x = a, the angle is set to a + 2Pi
- Else
if x < a, the angle is set to x + 2Pi
if x > a + 2Pi, the angle is set to x- 2Pi
else the angle is x

* angle comparisons
* supplementary, complementary angles computation

== Getting Started ==

=== Comparable intervals ===
Hereunder is given a code example illustrating how the <code>ComparableInterval</code> object behaves:

<syntaxhighlight lang="java">
final Double d1 = new Double(-4.44);
final Double d2 = new Double(2.22);
final Double d3 = new Double(6.23);
final Double d4 = new Double(8.72);
final IntervalEndpointType open = IntervalEndpointType.OPEN;
final IntervalEndpointType closed = IntervalEndpointType.CLOSED;
// Interval : [ -4.44 ; 2.22 [
final ComparableInterval<Double> ti1 = new ComparableInterval<Double>(closed, d1, d2, open);
final Double inside1 = new Double(-4.44);
final Double inside2 = new Double(-2.24);
final Double outside1 = new Double(-0.2313E96);
final Double outside2 = new Double(-4.45);
assertTrue(ti1.contains(inside1));
assertTrue(ti1.contains(inside2));
assertTrue(!ti1.contains(outside1));
assertTrue(!ti1.contains(outside2));
// Two open overlapping intervals
// ] d1 ; d3 [
// ...] d2 ; d4 [
final ComparableInterval<Double> ovo1 = new ComparableInterval<Double>(open, d1, d3, open);
final ComparableInterval<Double> ovo2 = new ComparableInterval<Double>(open, d2, d4, open);
assertTrue(ovo1.overlaps(ovo2));
assertTrue(ovo2.overlaps(ovo1));
// Two closed intervals, first includes second
// [ d1 .....;..... d4 ]
// .....[ d2 ; d3 ]
final ComparableInterval<Double> clos1 = new ComparableInterval<Double>(closed, d1, d4, closed);
final ComparableInterval<Double> clos2 = new ComparableInterval<Double>(closed, d2, d3, closed);
assertTrue(clos1.includes(clos2));
assertTrue(!clos2.includes(clos1));
</syntaxhighlight>

=== Angle intervals ===
Two constructors are available for an AngleInterval instance :

* One needing directly the end points values and types. Its signature is in the writing order. For example, to create [0.0, 2PI[ :

<syntaxhighlight lang="java">
AngleInterval angleInterval1 = new AngleInterval(IntervalEndpointType.CLOSED, 0.0,
MathUtils.TWO_PI, IntervalEndpointType.OPEN);
</syntaxhighlight>

* One needing the reference and length values, and the end points nature. Here, the signature is : “reference”, “length”, “lower end point type”, “upper end point type”. To create [-PI, PI[ :

<syntaxhighlight lang="java">
AngleInterval angleInterval1 = new AngleInterval(0.0, MathUtils.TWO_PI,
IntervalEndpointType.CLOSED, IntervalEndpointType.OPEN);
</syntaxhighlight>

Those constructors throw an exception « MathIllegalArgumentException » if the interval is not valid. It is considered not valid if :

* The length is strictly greater than 2PI
* The length is equal to 2PI and both end points are “closed”
* The length is negative
* The length is zero and at least one end point is opened (an interval with only one double in it is accepted)

Those intervals are impossible to modify once created : they have no setters. To get an interval with different values, a new one shall be constructed.

=== Angle tools ===
==== The method "angleInInterval" ====

The method « angleInInterval » computes the (2PI) modulus of an angle (given as a double) in an angle interval (AngleInterval object) :

* If a (2PI) modulus of the input angle exists in the interval, its value is returned. Because the angles have a maximum length of 2PI with at least an open end point, there can be only one solution.
* If no value in the interval is a solution, it means the operation is impossible with the given inputs, and a « MathIllegalArgumentException » is thrown.

Use example :

<syntaxhighlight lang="java">
try {
// Angle
double angle = 6*FastMath.PI;

// Interval creation
AngleInterval angleInterval = new AngleInterval(IntervalEndpointType.OPEN,
- MathUtils.HALF_PI, MathUtils.HALF_PI, IntervalEndpointType.OPEN);

// angle in interval
double result = AngleTools.angleInInterval(angle, angleInterval);
}
catch (MathIllegalArgumentException e) {
// correct catch!
}

</syntaxhighlight>

« result » value is here 0.0 : the modulus of 6PI in ]-PI/2,-PI/2[

==== Comparisons methods ====

The comparison methods available in the AngleTools class are the same as the one for doubles in the « Comparators » class : relative comparisons using a default epsilon. Input angles are only expressed in the input interval before the comparison.

If the computation in the interval of one of the input angles is not possible, a « MathIllegalArgumentException » is thrown.

Use example :

<syntaxhighlight lang="java">
try {
// Angle
double angle1 = 6*FastMath.PI;
double angle2 = 4*FastMath.PI + 0.1;

// Interval creation
AngleInterval angleInterval = new AngleInterval(IntervalEndpointType.OPEN,
- MathUtils.HALF_PI, MathUtils.HALF_PI, IntervalEndpointType.OPEN);

// angle in interval
boolean isLowerOrEqual = AngleTools.lowerOrEqual(angle1, angle2, angleInterval);
}
catch (MathIllegalArgumentException e) {
// correct catch !
}

</syntaxhighlight>

Both angles are here computable in the given interval. The first one is lower than the second once in the interval : the returned result is “true”

==== Supplementary, complementary and opposite angles ====

The tools box AngleTools proposes the methods to compute supplementary (method supplementaryAngle), complementary (method complementaryAngle) and opposite (method oppositeAngle) angles, taking into account an angle interval (of the type AngleInterval previously described)

Those methods first compute a common supplementary, complementary or opposite angle, and then try to express the result in the given interval. If this last operation is not possible, an exception is thrown (MathIllegalArgumentException).

Use example :

<syntaxhighlight lang="java">
try {
// Interval creation
AngleInterval angleInterval = new AngleInterval(IntervalEndpointType.OPEN,
- MathUtils.HALF_PI, MathUtils.HALF_PI, IntervalEndpointType.OPEN);

// computation
double angle = 3.0/4.0*FastMath.PI + 6.0*FastMath.PI;
double res = AngleTools.supplementaryAngle(angle, angleInterval);

}
catch (MathIllegalArgumentException e) {
// correct catch !

}

</syntaxhighlight>

The result is here computable, its value is PI/4.

== Contents ==
=== Interfaces ===
None as of now.

=== Classes ===
Here is a summary of the most important classes :
{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''IntervalEndpointType'''
|Defines an interval end point as OPEN or CLOSED.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/interval/IntervalEndpointType.html ...]
|-
|'''AngleInterval'''
|Implements an interval of angles, taking angles' modulus into account.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/interval/AngleInterval.html ...]
|-
|'''AngleTools'''
|Provides several angle-related utility methods.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/interval/AngleTools.html ...]
|-
|'''GenericInterval'''
|Implements a generic interval.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/interval/GenericInterval.html ...]
|-
|'''AbsoluteDateInterval'''
|This class implements an interval based on the AbsoluteDate class using the ComparableInterval class.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/time/AbsoluteDateInterval.html ...]
|-
|'''AbsoluteDateIntervalsList'''
|The class describe a list of AbsoluteDateInterval.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/time/AbsoluteDateIntervalList.html ...]
|-
|'''ComparableInterval'''
|The class describe an interval of Comparable data.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/interval/ComparableInterval.html ...]
|-
|'''ComparableIntervalsList'''
|The class describe a list of ComparableInterval.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/interval/ComparableIntervalsList.html ...]
|}

[[Category:User_Manual_4.17_Mathematics]]

User Manual 4.17 Geometry

2025-11-26T13:46:32Z

Admin tsn : Page créée avec « __NOTOC__ == Introduction == === Scope === The geometry objects implemented in the PATRIUS library are both infinite and finite shapes. The finite shapes shall be used for example to represent parts of a spacecraft or celestial bodies. The infinite ones can represent more mathematical surfaces such as instruments' characteristics. All the objects provide methods to compute interactions with lines (intersections, distances, etc...), points and other objects.... »

__NOTOC__
== Introduction ==
=== Scope ===
The geometry objects implemented in the PATRIUS library are both infinite and finite shapes.

The finite shapes shall be used for example to represent parts of a spacecraft or celestial bodies. The infinite ones can represent more mathematical surfaces such as instruments' characteristics.

All the objects provide methods to compute interactions with lines (intersections, distances, etc...), points and other objects.

=== Javadoc ===
The geometry objects are available in the package <code>fr.cnes.sirius.patrius.math.geometry.euclidean.threed</code>.

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/package-summary.html Package fr.cnes.sirius.patrius.math.geometry.euclidean.threed]
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/package-summary.html Package fr.cnes.sirius.patrius.math.geometry.euclidean.threed]
|}

=== Links ===
The math package contains several other packages related to geometry (1D, 2D, 3D) and provides objects for Binary Space Partitioning (BSP) Tree. See javadoc for more information.
Some other "basic" objects are contained in the threed package and documented in other parts of this manual (eg : Rotations, Matrix3D).

=== Useful Documents ===
Useful reference documents for this theme can be found here :

* Nürnberg, R.; ''Distance from a Point to an Ellipse'', Imperial College London, 2006, [http://www2.imperial.ac.uk/~~rn/distance2ellipse.pdf http://www2.imperial.ac.uk/~~rn/distance2ellipse.pdf].

=== Package Overview ===
The aim of the following diagram is to present the architecture implemented for the Geometry package. This does not mean that all the classes and/or interfaces are in the Geometry package and it does not mean that all the classes and interfaces of the package are presented.

[[File:geometry.PNG|center]]

== Features Description ==
=== 2D Objects ===
The two dimensional objects (in three dimensional space) implemented in the PATRIUS library are given hereunder :

* Lines
* Planes
* Plates
* Disks
* Ellipses

Please refer to the [MAT_GEO_Home#HClasses Classes section] for more information.

=== 3D Objects ===
The three dimensional objects (in three dimensional space) implemented in the PATRIUS library are given hereunder :

* Infinite and Finite Cylinders (right circular, elliptic and rectangular)
* Infinite and Finite Cones (right circular, oblique circular and rectangular)
* Spheres, Spheroids and Spherical Caps
* Parallelepipeds

Please refer to the [MAT_GEO_Home#HClasses Classes section] for more information.

=== Interactions between objects ===
[MAT_GEO_Home#HInterfaces Interfaces] have been implemented for geometrical objects in order to set a standard as to what method each and any geometrical object should implement.

As of now, (some of the) geometrical objects must provide methods to :
* Check if a line intersects with said objects,
* Compute and return the intersection points,
* Compute and return the closest point on the object surface to a given user point,
* Compute and return the distance between these two points,
* Compute and return the closest point on the object surface to a given user line and return the closest points on the line and on the object,
* Compute and return the distance between an object and a given user line.

Plese refer to the [MAT_GEO_Home#HInteractions Interactions section] for more details.

== Getting Started ==

=== Interactions ===
Given an object implementing the [MAT_GEO_Home#HInterfaces Shape] interface, the following methods are available :

'''intersects(Line) : boolean''' 
Test the intersection of the object with a user given line.

Code snippet :
<syntaxhighlight lang="java">
Line line = new Line(lineOrigin, lineDirection);
boolean result = myObject.intersects(line);
</syntaxhighlight>

'''getIntersectionPoints(Line) : Vector3D[]''' 
Compute the intersection point of the object with a user given line.

Code snippet :
<syntaxhighlight lang="java">
Line line = new Line(lineOrigin, lineDirection);
Vector3D[] intersectionPoints = myObject.getIntersectionPoints(line);
</syntaxhighlight>

'''closestPointTo(Vector3D) : Vector3D''' 
Compute the point on the surface of the object that is the closest to a user given point.

Code snippet :
<syntaxhighlight lang="java">
Vector3D point = new Vector3D(1.0, 2.0, 3.0);
Vector3D result = myObject.closestPointTo(point);
</syntaxhighlight>

'''distanceTo(Vector3D) : double''' 
Compute the shortest distance from the surface of the object and user given point.

Code snippet :
<syntaxhighlight lang="java">
Line line = new Line(lineOrigin, lineDirection);
double distance = myObject.distanceTo(line);
</syntaxhighlight>

'''closestPointTo(Line) : Vector3D[]''' 
Compute the points realizing the shortest distance to a line (the first one is from the line, the second one from the object ). If the line intersects the object , the two points are identical, and equal to the first one returned by the "getIntersectionPoints" method. If the line is parallel to the object 's side, the closest point to the origin is used.

Code snippet :
<syntaxhighlight lang="java">
Line line = new Line(lineOrigin, lineDirection);
Vector3D[] points = myObject.closestPointTo(line);
</syntaxhighlight>

'''distanceTo(Line) : double''' 
Compute the shortest distance from a line to the surface of the object.

Code snippet :
<syntaxhighlight lang="java">
Line line = new Line(lineOrigin, lineDirection);
double distance = myObject.distanceTo(line);
</syntaxhighlight>

== Contents ==
=== Interfaces ===
{| class="wikitable"
|-
! scope="col"| Interface
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''Cone'''
|This interface extends the SolidShape interface for the particular case of cones.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/Cone.html ...]
|-
|'''CrossSectionProvider'''
|Interface for all geometric objects that can provide their cross section from a direction defined by a Vector3D.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/CrossSectionProvider.html ...]
|-
|'''Cylinder'''
|This interface extends the SolidShape interface for the particular case of cylinders.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/Cylinder.html ...]
|-
|'''IEllipsoid'''
|This interface extends the InfiniteShape interface for the particular cases of ellipsoid objects.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/IEllipsoid.html ...]
|-
|'''InfiniteCone'''
|This interface extends the InfiniteShape interface for the particular cases of infinite cones.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/InfiniteCone.html ...]
|-
|'''InfiniteCylinder'''
|This interface extends the InfiniteShape interface for the particular cases of infinite cylinders.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/InfiniteCylinder.html ...]
|-
|'''InfiniteShape'''
|This interface extends the Shape interface for the particular cases of infinite shapes.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/InfiniteShape.html ...]
|-
|'''Shape'''
|This interface is the '''main interface for all shapes''', including infinite and solid shapes. It defines the general methods required by each geometrical object implementing any of the above interfaces : All of them must be able to compute their intersection and distance to a line. See [MAT_GEO_Home#HInteractionsbetweenobjects Interactions].
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/Shape.html ...]
|-
|'''SolidShape'''
|This interface extends the Shape interface for the particular cases of solids.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/SolidShape.html ...]
|}

=== Classes ===
'''Basic Shapes'''

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''Disk'''
|The class represent disks in a three dimensional space.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/Disk.html ...]
|-
|'''Ellipse'''
|The class represent ellipses in a three dimensional space.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/Ellipse.html ...]
|-
|'''Line'''
|The class represent lines in a three dimensional space.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/Line.html ...]
|-
|'''Plane'''
|The class represent planes in a three dimensional space.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/Plane.html ...]
|-
|'''Plate'''
|This is a describing class for a 3D rectangle plate shape, with some algorithm to compute intersections and distances to some other objects.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/Plate.html ...]
|-
|'''Parallelepiped'''
|This is a describing class for a rectangle parallelepiped shape, with some algorithm to compute intersections and distances to some other objects.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/Parallelepiped.html ...]
|}

'''Cylinders'''

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''InfiniteEllipticCylinder'''
|This class is the Infinite Elliptic Cylinder class.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/InfiniteEllipticCylinder.html ...]
|-
|'''InfiniteRightCircularCylinder'''
|This is a describing class for a 3D infinite right circular cylinder, with some algorithm to compute intersections and distances to some other objects.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/InfiniteRightCircularCylinder.html ...]
|-
|'''InfiniteRectangleCylinder'''
|This is a describing class for a 3D infinite rectangle cylinder, with some algorithm to compute intersections and distances to some other objects.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math//geometry/euclidean/threed/InfiniteRectangleCylinder.html ...]
|-
|'''EllipticCylinder'''
|This is a describing class for a 3D oblique circular cylinder ended by two planes normal to its axis, with some algorithm to compute intersections and distances to some other objects.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/EllipticCylinder.html ...]
|-
|'''RightCircularCylinder'''
|This is a describing class for a 3D right circular cylinder ended by two planes normal to its axis, with some algorithm to compute intersections and distances to some other objects.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/RightCircularCylinder.html ...]
|}

NB : For the rectangular cylinder, please refer to the parallelepiped class mentioned above.

'''Cones'''

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''InfiniteRightCircularCone'''
|This is a describing class for a 3D infinite cone, with some algorithm to compute intersections and distances to some other objects.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/InfiniteRightCircularCone.html ...]
|-
|'''InfiniteEllipticCone'''
|This class is the Infinite Elliptic Cone class.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/InfiniteEllipticCone.html ...]
|-
|'''InfiniteRectangleCone'''
|This is a describing class for a 3D infinite cone, with some algorithm to compute intersections and distances to some other objects.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/InfiniteRectangleCone.html ...]
|-
|'''RightCircularCone'''
|This is a describing class for a 3D right circular cone ended by a plane normal to its axis, with some algorithm to compute intersections and distances to some other objects.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/RightCircularCone.html ...]
|-
|'''EllipticCone'''
|This is a describing class for a 3D elliptic cone ended by a plane normal to its axis, with some algorithm to compute intersections and distances to some other objects.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/EllipticCone.html ...]
|-
|'''RectangleCone'''
|This is a describing class for a 3D rectangle cone ended by a plane normal to its axis (pyramid), with some algorithm to compute intersections and distances to some other objects.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/RectangleCone.html ...]
|}

'''Ellipsoids'''

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''Ellipsoid'''
|This is a describing class for an ellipsoid, with some algorithm to compute intersections and distances to some other objects.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/Ellipsoid.html ...]
|-
|'''Sphere'''
|This is a describing class for a 3D spherical shape, with some algorithm to compute intersections and distances to some other objects.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/Sphere.html ...]
|-
|'''Spheroid'''
|This is the Spheroid (also called Revolved Ellipsoid) class.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/Spheroid.html ...]
|}

'''Other objects'''

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''Facet'''
|Implements a representation of a facet.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/assembly/properties/features/Facet.html ...]
|-
|'''SphericalCap'''
|Implements a representation of a spherical cap solid.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/SphericalCap.html ...]
|-
|'''SphericalCoordinates'''
|Spherical coordinates to Vector3D .
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/SphericalCoordinates.html ...]
|}

[[Category:User_Manual_4.17_Mathematics]]

User Manual 4.17 Dispersions

2025-11-26T13:46:14Z

Admin tsn : Page créée avec « __NOTOC__ == Introduction == === Scope === This section describes how dispersions are defined and used in the PATRIUS library. Dispersions are not to be mixed up with random generation (not detailed in this page). Dispersions always rely on a random generator. === Javadoc === The dispersions objects are available in the package <code>fr.cnes.sirius.patrius.math.random</code>. This package also handles random generation. {| class="wikitable" |- ! scope="col"| Li... »

__NOTOC__
== Introduction ==
=== Scope ===
This section describes how dispersions are defined and used in the PATRIUS library.
Dispersions are not to be mixed up with random generation (not detailed in this page). Dispersions always rely on a random generator.

=== Javadoc ===
The dispersions objects are available in the package <code>fr.cnes.sirius.patrius.math.random</code>. This package also handles random generation.

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/random/package-summary.html Package fr.cnes.sirius.patrius.math.random]
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/random/package-summary.html Package fr.cnes.sirius.patrius.math.random]
|}

=== Links ===
None as of now.

=== Useful Documents ===
None as of now.

=== Package Overview ===

== Features Description ==
=== Random number generation ===
Distributed random number generation is based on using implementations of interface <code>fr.cnes.sirius.patrius.math.random.NormalizedRandomGenerator</code>.
Each implementation of this interface provides a specific dispersion scheme. For instance, the following code will generate random numbers with Gaussian distribution of mean 0 and unit standard deviation:
<syntaxhighlight lang="java">
final RandomGenerator g = new JDKRandomGenerator();
final NormalizedRandomGenerator generator = new GaussianRandomGenerator(g);
final double value = generator.nextNormalizedDouble();
</syntaxhighlight>

As shown in the above example, building a dispersion object requires a random generator implementing <code>fr.cnes.sirius.patrius.math.random.RandomGenerator</code> interface.

=== Random vector generation ===
Correlated random vector generation is based on using implementations of interface <code>fr.cnes.sirius.patrius.math.random.RandomVectorGenerator</code>.
Each implementation of this interface provides a specific dispersion scheme. For instance, the following code will generate uniformly correlated random vectors according to provided covariance matrix:
<syntaxhighlight lang="java">
final RandomGenerator g = new JDKRandomGenerator();
final RandomVectorGenerator generator = new UniformlyCorrelatedRandomVectorGenerator(mean, covariance, 0, g);
final double[] value = generator.nextVector();
</syntaxhighlight>

As shown in the above example, building a dispersion object requires a random generator implementing <code>fr.cnes.sirius.patrius.math.random.RandomGenerator</code> interface.

=== Correlated random vector generator ===
The user provides a covariance matrix and a random generator. 
'''When using Gaussian correlated random vector generator''':
* The covariance matrix root is extracted using a Cholesky decomposition. The number of columns of the root matrix corresponds to the rank of the provided covariance matrix.
* An uncorrelated vector of size the rank of the covariance matrix is generated using the provided random generator
* The final correlated vector is obtained by multiplying the covariance root matrix by this generated vector.

'''When using uniformly correlated random vector generator''', the process is more complex:
* The covariance matrix is converted into a correlation matrix. Standard deviation vector is extracted from the process. Obtained correlation matrix must be positive semi-definite (all eigenvalues must be non negative).
* Spearman correction is applied to the correlation matrix. If corrected correlation matrix is not positive semi-definite, correction is not applied.
[[File:spearmanCorrection.png|center]]
* The correlation matrix root is extracted using a Cholesky decomposition. The number of columns of the root matrix corresponds to the rank of the correlation matrix.
* A uncorrelated vector of size the rank of the covariance matrix is generated using the provided random generator
* The product of correlation matrix root L and uncorrelated vector T is then transformed to get a uniform law:
[[File:uniformCorrection.png|center]]
* The final correlated vector is obtained by linearly multiplying z by the standard deviation vector.

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

== Contents ==
=== Interfaces ===
The library defines the following interfaces related to dispersions:

{| class="wikitable"
|-
! scope="col"| Interface
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''NormalizedRandomGenerator'''
|Interface for normalized random generators
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/random/NormalizedRandomGenerator.html ...]
|-
|'''RandomVectorGenerator'''
|Interface for random vector generators
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/random/RandomVectorGenerator.html ...]
|}

Note: interface for random number generators is <code>fr.cnes.sirius.patrius.math.random.RandomGenerator</code>.

=== Classes ===
The library defines the following classes related to dispersions:

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''GaussianRandomGenerator'''
|Generator following Gaussian distribution
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/random/GaussianRandomGenerator.html ...]
|-
|'''UniformRandomGenerator'''
|Generator following uniform distribution
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/random/UniformRandomGenerator.html ...]
|-
|'''UncorrelatedRandomVectorGenerator'''
|Generator for Gaussian uncorrelated vectors
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/random/UncorrelatedRandomVectorGenerator.html ...]
|-
|'''CorrelatedRandomVectorGenerator'''
|Generator for Gaussian correlated vectors
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/random/CorrelatedRandomVectorGenerator.html ...]
|-
|'''UniformlyCorrelatedRandomVectorGenerator'''
|Generator for uniformly correlated vectors
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/random/UniformlyCorrelatedRandomVectorGenerator.html ...]
|-
|'''UnitSphereRandomVectorGenerator'''
|Generator for vectors isotropically located on a sphere
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/random/UnitSphereRandomVectorGenerator.html ...]
|}

[[Category:User_Manual_4.17_Mathematics]]

User Manual 4.17 Double Comparisons

2025-11-26T13:45:57Z

Admin tsn : Page créée avec « __NOTOC__ == Introduction == === Scope === The « Comparators » class contains static methods to perform relative comparisons of doubles. === Javadoc === The Comparators class is available in the <code>package fr.cnes.sirius.patrius.math.interval</code>. {| class="wikitable" |- ! scope="col"| Library ! scope="col"| Javadoc |- |Patrius |[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/interval/package-summary.html Package fr.cnes.sirius.patrius.math.interval] |}... »

__NOTOC__
== Introduction ==
=== Scope ===
The « Comparators » class contains static methods to perform relative comparisons of doubles.

=== Javadoc ===
The Comparators class is available in the <code>package fr.cnes.sirius.patrius.math.interval</code>.

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/interval/package-summary.html Package fr.cnes.sirius.patrius.math.interval]
|}

=== Links ===
Some elements about the “equals” comparators previously proposed in the “MathUtils” class are described in the document “Comparing floating point numbers” by Bruce Dawson : [http://www.cygnus-software.com/papers/comparingfloats/comparingfloats.htm http://www.cygnus-software.com/papers/comparingfloats/comparingfloats.htm].

=== Useful Documents ===
None as of now.

=== Package Overview ===
The doubles comparison issue is adressed through a single utility class, [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/Comparators.html Comparators], in the fr.cnes.sirius.patrius.utils package.

== Features Description ==
=== Algorithms and espilon value ===
The need here is to compare two values with a known maximum relative difference.

The “equals” comparators previously proposed in the “MathUtils” class are of two types :

* a simple absolute comparison using an epsilon
* a more complex one, described in the document “Comparing floating point numbers” by Bruce Dawson (see the Links paragraph)

This last comparison makes more sense to compare real values and takes into account the precision issues due to the double type. It works as well with any exponent (high values or close to zero…), but the relative difference accepted between two equal doubles is uncontrolled, between 2.5e-16 and 1.25e-16 for a maxUlps of 1 (difference between two consecutive doubles).

Here is proposed a new comparison method to control the maximum relative difference and still have a comparison that makes sense when computed.

=== The Comparators class ===
The new comparison method is implemented in the Comparators class. Its simplified algorithm is described below with pseudo-code.

''x and y are two doubles.''

* '' IF x equals y in the Bruce Dawson’s way ''
** ''=> Then the return is “TRUE” regardless to relative difference''
* '' ELSE :''
** ''=> IF the absolute relative difference is lower than the epsilon, then the return is “TRUE”''
* ''ENDIF''

NB : the epsilon can be chosen by the user, eventually between 2.5e-16 and 1.25e-16 (min and max values for the relative difference in Bruce Dawson’s algorithm). In that case, the comparison becomes at worst uncontrolled and doesn’t make any sense : sometimes the epsilon will be used, sometimes not, without information to the user. If the chosen epsilon is lower than 1.25e-16, it becomes useless.

The default epsilon proposed is :

''Comparators.DOUBLE_COMPARISON_EPSILON'' = 1.0e-14

(two orders higher than the max relative difference between to consecutive doubles)

==== Using the Comparators class ====

The Comparators class provides the following static methods ''equal, lowerOrEqual, greaterOrEqual, lowerStrict, greaterStrict,'' for doubles comparison purposes.

Their returns are Booleans, in order to be used the same way as classical « > », « == »…

Code examples :

<syntaxhighlight lang="java">
if (Comparators.equals(x, y, eps)) { } // epsilon given by the user
if (Comparators.equals(x, y)) { } // default epsilon
if (Comparators.lowerOrEqual(x, y)) { } // default epsilon
</syntaxhighlight>

These comparisons are relative and use an epsilon value. Each method is duplicated, so the choice is given to use the default epsilon (''Comparators.DOUBLE_COMPARISON_EPSILON'') or any other value, by adding it to the method’s signature.

To respect the '''IEEE Standard 754''', a “NaN” is considered different to any other double, including “NaN” itself, and the positive and negative infinite values are considered only equal to themselves (see behaviour examples).

==== Examples of "equals" method behaviour (using default epsilon) : ====

{| class="wikitable"
|-
! scope="col"| X
! scope="col"| Y
! scope="col"| |X-Y|/Y
! scope="col"| MathUtils.equals result
! scope="col"| Comparators.equals result
|-
|0.0
|1.0e-300
|1.0
|false
|false
|-
|1.25000000000000025
|1.25
|2.0e-16
|false
|true
|-
|1.0000000000000002
|1.0
|2.0e-16
|true
|true
|-
|1.0000000000000001e+300
|1.0e+300
|1.0e-16
|true
|true
|-
|1.0000000000000001e-300
|1.0e-300
|1.0e-16
|true
|true
|-
|1.000000000000001
|1.0
|1.0e-15
|false
|true
|-
|1.000000000000001e+300
|1.0e+300
|1.0e-15
|false
|true
|-
|1.000000000000001e-300
|1.0e-300
|1.0e-15
|false
|true
|-
|1.0000000000001
|1.0
|1.0e-13
|false
|false
|-
|1.0000000000001e+300
|1.0e+300
|1.0e-13
|false
|false
|-
|1.0000000000001e-300
|1.0e-300
|1.0e-13
|false
|false
|-
|NaN
|NaN
| -
|false
|false
|-
|NaN
|Any other double
| -
|false
|false
|-
|POSITIVE_INFINITE
|POSITIVE_INFINITE
| -
|true
|true
|-
|POSITIVE_INFINITE
|Any other double
| -
|false
|false
|}

Notice the second and third lines : two pair of doubles with the same relative difference imply a “false” for the first, and a “true” for the second.

Using a relative epsilon allows us to stay coherent in any case.

'''Beware :''' when realizing a comparison close to zero, you must think about the type of comparison needed. In order to perform comparison in the same way regardless to the exponents, our comparator considers a double with a very low exponent different to zero (first line of the example). In some cases, an absolute comparison with epsilon shall be needed (to compare the result of a computation to zero...).

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

== Contents ==
=== Interfaces ===
None as of now.

=== Classes ===
The only class is <code>fr.cnes.sirius.patrius.math.Comparators</code>.

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''Comparators'''
|Static comparison methods for real numbers
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/Comparators.html ...]
|}

[[Category:User_Manual_4.17_Mathematics]]

User Manual 4.17 Math frameworks

2025-11-26T13:45:32Z

Admin tsn : Page créée avec « __NOTOC__ == Introduction == === Scope === This section describes PATRIUS handling of low-level math frameworks. A low-level math framework provides simple math operations such as sin, cos, exp, etc. Before PATRIUS 4.2, the only existing framework is <code>FastMath</code>. Since version 4.2, the notion of math framework has been generalized and the user can use various framework: * FastMath * Math * StrictMath * JAFAMA 2.3.1 FastMath * JAFAMA 2.3.1 StrictFastMath... »

__NOTOC__
== Introduction ==
=== Scope ===
This section describes PATRIUS handling of low-level math frameworks.
A low-level math framework provides simple math operations such as sin, cos, exp, etc. Before PATRIUS 4.2, the only existing framework is <code>FastMath</code>.
Since version 4.2, the notion of math framework has been generalized and the user can use various framework:
* FastMath
* Math
* StrictMath
* JAFAMA 2.3.1 FastMath
* JAFAMA 2.3.1 StrictFastMath
* An implementation corresponding for each function to fastest implementations among all above libraries.
* Its own defined framework

JAFAMA is a fast open-source Math library. To be usable in PATRIUS, a dependency to JAFAMA 2.3.1 has been added in PATRIUS pom.xml file.

=== Javadoc ===
The math framework classes are available in the package <code>fr.cnes.sirius.patrius.math.framework</code>.

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/framework/package-summary.html Package fr.cnes.sirius.patrius.math.framework]
|}

=== Links ===
One of the framework available is JAFAMA. JAFAMA is an open-source library under Apache 2.0 licence.
More information can be found at https://github.com/jeffhain/jafama

=== Useful Documents ===
None as of now.

=== Package Overview ===

== Features Description ==

=== Features ===

A low-level Math framework is a class implementing all the original <code>FastMath</code> functions (sin, exp, min, atan, etc.).
All low-level Math framework should implement the <code>MathLibrary</code> interface.
Currently there are three implementations of the MathLibrary interface:
* <code>FastMathWrapper</code> which is a wrapper for FastMath static class.
* <code>MathWrapper</code> which is a wrapper for Math static class.
* <code>StrictMathWrapper</code> which is a wrapper for StrictMath static class.
* <code>JafamaFastMathWrapper</code> which is a wrapper for JAFAMA FastMath static class.
* <code>JafamaStrictFastMathWrapper</code> which is a wrapper for JAFAMA StrictFastMath static class.
* <code>FastestMathLibWrapper</code> which is a wrapper for fastest math library among the listed above. Fastest functions are mainly Jafama FastMath functions except for simple functions (abs, ceil, floor, round, etc.) for which FastMath or StrictMath are faster.
The user can also define its own low-level Math framework by providing its own implementation of the <code>MathLibrary</code> interface.

Then in order to use the chosen low-level Math framework, the user must use the static class <code>MathLib</code>:
* By first defining the Math framework to use with methods <code>MathLib.setMathLibrary()</code> if different from FastMath.
* By then using the MathLib functions like the FastMath functions: <code>MathLib.sin(...)</code>
Notes:
* by default, FastMath is set as the low-level Math library.
* inner PATRIUS functions call MathLib which by default call FastMath. Hence there is strictly no numerical differences between use of PATRIUS 4.2 or older versions of PATRIUS.
* MathLib has function sinAndCos which allows the computation of sine and cosine of a value in one single operation. If using Jafama, the computational cost is reduced by about 30%. There is no impact if using another framework.

When the user defines a low-level math framework then all PATRIUS operations are performed using this framework.

=== Performances of available Math framework ===

==== Computation times ====

Here are displayed computation time gains with using JAFAMA library (reference: FastMath).

{| class="wikitable"
|-
! scope="col"| Item
! scope="col"| Jafama FastMath
! scope="col"| Jafama StrictFastMath
|-
|'''Numerical propagation'''
| <center>≈ -10%</center>
| <center>≈ -10%</center>
|-
|'''Analytical propagation'''
| <center>≈ -30%</center>
| <center>≈ -30%</center>
|-
|'''Attitude computation'''
| <center>≈ -10%</center>
| <center>≈ -10%</center>
|}

Note: these are averaged orders of magnitude and may vary from one case to another.

==== Accuracy ====

As stated in JAFAMA website, relative accuracy of operations is 1E-15 (no regression would required a relative accuracy better than 1E-16). As a result, use of PATRIUS with JAFAMA will lead to slightly different results. This will not occur on all operations.

Here are displayed absolute/relative error for standard PATRIUS uses with using JAFAMA library (reference: FastMath).

{| class="wikitable"
|-
! scope="col"| Item
! scope="col"| Jafama FastMath
! scope="col"| Jafama StrictFastMath
|-
|'''Framework functions'''
| <center><1E-15 rel.</center>
| <center><1E-15 rel.</center>
|-
|'''Low-level space mechanics functions'''
| <center><1E-15 rel.</center>
| <center><1E-15 rel.</center>
|-
|'''LEO propagation on 24h'''
| <center><1E-6m</center>
| <center><1E-6m</center>
|-
|'''GEO propagation on 24h'''
| <center><1E-5m</center>
| <center><1E-5m</center>
|-
|'''GTO propagation on 24h'''
| <center><1E-6m</center>
| <center><1E-6m</center>
|}

Roughly, an absolute accuracy on position of 1E-6m for LEO orbits means a relative accuracy of 1E-12.

The accuracy (with respect to FastMath) is directly correlated to the number of used JAFAMA operations. To get an idea of what accuracy to expect:
* 1 single JAFAMA operation leads to a relative accuracy of 1E-15 or better
* 1 propagation over 24 h (with millions calls to JAFAMA) leads to a relative accuracy of 1E-12

**Warning: **Except for StrictMath, PATRIUS does not guarantee implementations of various JVM will return the exact same result.

== Getting Started ==

In the following section are defined potential use of Math framework.

=== Simple user ===

This user does not want to change anything with PATRIUS 4.2 upgrade. He has two options:
* Continue to use FastMath and do nothing in particular:
<syntaxhighlight lang="java">final double y = FastMath.sin(x);</syntaxhighlight>
* Still use FastMath through the use of MathLib
<syntaxhighlight lang="java">final double y = MathLib.sin(x);</syntaxhighlight>
Note: by default, MathLib calls FastMath.

=== Intermediate user ===

This user wants to use another Math framework (here FastMath from JAFAMA):
<syntaxhighlight lang="java">
MathLib.setMathLibrary(MathLibraryType.JAFAMA_FASTMATH);
final double y = MathLib.sin(x);
</syntaxhighlight>

=== Advanced user ===

This user wants to use his own math framework:
<syntaxhighlight lang="java">final MathLibrary myOwnFramework = new MathLibrary() {
public double sin(final double x) {
return ...;
}
...
}
MathLib.setMathLibrary(myOwnFramework);
final double y = MathLib.sin(x);
</syntaxhighlight>

== Contents ==
=== Interfaces ===
The library defines the following interfaces related to math frameworks:

{| class="wikitable"
|-
! scope="col"| Interface
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''MathLibrary'''
|Interface for low-level Math framework
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/framework/MathLibrary.html ...]
|}

=== Classes ===
The library defines the following classes related to low-level Math frameworks:

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''MathLib'''
|Static class for generic low-level math functions use
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/MathLib.html ...]
|-
|'''MathLibraryType'''
|Enumeration for currently available Math framework in PATRIUS
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/framework/MathLibraryType.html ...]
|-
|'''FastMathWrapper'''
|Wrapper of FastMath class implementing MathLibrary interface
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/framework/FastMathWrapper.html ...]
|-
|'''MathWrapper'''
|Wrapper of Math class implementing MathLibrary interface
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/framework/MathWrapper.html ...]
|-
|'''StrictMathWrapper'''
|Wrapper of StrictMath class implementing MathLibrary interface
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/framework/StrictMathWrapper.html ...]
|-
|'''JafamaFastMathWrapper'''
|Wrapper of Jafama FastMath class implementing MathLibrary interface
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/framework/JafamaFastMathWrapper.html ...]
|-
|'''JafamaStrictFastMathWrapper'''
|Wrapper of Jafama StrictFastMath class implementing MathLibrary interface
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/framework/JafamaStrictFastMathWrapper.html ...]
|-
|'''FastestMathLibWrapper'''
|Implementation wrapping the fastest implementation among Math, FastMath, StrictMath and Jafama for each function
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/framework/FastestMathLibWrapper.html ...]
|-
|'''FastMath'''
|Original class from PATRIUS providing low-level math functions
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/FastMath.html ...]
|}

[[Category:User_Manual_4.17_Mathematics]]

User Manual 4.17 Numerical differentiation and integration

2025-11-26T13:45:12Z

Admin tsn : Page créée avec « __NOTOC__ == Introduction == === Scope === This section détails numerical differentialtion and integration (not to be misunderstood with numerical integration of ODE). A focus is realised on: * differentiation methods of real univariate functions: Ridders and finite difference. * integration methods of real univariate functions : Trapezoidal and Simpson. === Javadoc === The numerical differentiator objects are available in the package <code>fr.cnes.sirius.patri... »

__NOTOC__
== Introduction ==
=== Scope ===
This section détails numerical differentialtion and integration (not to be misunderstood with numerical integration of ODE). A focus is realised on:
* differentiation methods of real univariate functions: Ridders and finite difference.
* integration methods of real univariate functions : Trapezoidal and Simpson.

=== Javadoc ===
The numerical differentiator objects are available in the package <code>fr.cnes.sirius.patrius.math.analysis.differentiation</code>.
The numerical integrator objects are available in the package <code>fr.cnes.sirius.patrius.math.analysis.integration</code>.

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/differentiation/package-summary.html Package fr.cnes.sirius.patrius.math.analysis.differentiation]
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/integration/package-summary.html Package fr.cnes.sirius.patrius.math.analysis.integration]
|}

=== Links ===
Links to the implemented integration methods :

http://mathworld.wolfram.com/TrapezoidalRule.html

http://mathworld.wolfram.com/SimpsonsRule.html

=== Useful Documents ===
None as of now.

=== Package Overview ===
The numerical differentiation conception is described hereafter :

[[File:differentiators.png|center]]

Accuracy of integration method (all examples are based on sinus function):

{| class="wikitable"
|-
! scope="col"| Default setting
! scope="col"| Value
|-
|Maximum absolute error
|1.0e-15
|-
|Maximum relative error
|1.0e-6
|-
|Maximum number of iterations
|64
|-
|Minimum number of iterations
|3
|}

Note : the accuracy of the results and the computing time are directly dependent on the value of maximum relative error.

== Features Description ==

=== Numerical differentiation ===

==== Finite difference ====
Finite difference is the discrete analog of the derivative. The user can choose the number of points to use and the step size (the gap between each point).

==== Ridders algorithm ====
The derivative of a function at a point x is computed using the Ridders method of polynomial extrapolation.

=== Numerical Integration ===
=== Trapezoidal method ===
The trapezoidal rule works by approximating the region under the graph of the function as a trapezoid and calculating its area.

<syntaxhighlight lang="java">
UnivariateFunction f = new SinFunction();
UnivariateIntegrator integrator = new TrapezoidIntegrator();
double r = integrator.integrate(10000, f, 0, FastMath.PI);
</syntaxhighlight>

Result : r = 1.9999996078171345 (exact result = 2)

And :

<syntaxhighlight lang="java">
integrator = new TrapezoidIntegrator(1.e-12, 1.0e-15, 3, 64);
r = integrator.integrate(10000000, f, 0, FastMath.PI);
</syntaxhighlight>

Result : r = 1.9999999999904077

But :
<syntaxhighlight lang="java">integrator = new TrapezoidIntegrator(1.e-13, 1.0e-15, 3, 64);
r = integrator.integrate(10000000, f, 0, FastMath.PI);</syntaxhighlight>

Result : r = no result (infinite time !)

=== Simpson method ===
Simpson's rule is a Newton-Cotes formula for approximating the integral of a function using quadratic polynomials (i.e., parabolic arcs instead of the straight line segments used in the trapezoidal rule).
In general, this method has faster convergence than the trapezoidal rule for functions which are twice continuously differentiable, though not in all specific cases.

<syntaxhighlight lang="java">
UnivariateFunction f = new SinFunction();
UnivariateIntegrator integrator = new SimpsonIntegrator();
double r = integrator.integrate(10000, f, 0, FastMath.PI);
</syntaxhighlight>

Result : r = 2.000000064530001 (exact result = 2)

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

== Contents ==
=== Interfaces ===
{| class="wikitable"
|-
! scope="col"| Interface
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''UnivariateFunctionDifferentiator'''
|This interface represents a generic numerical differentiator.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/differentiation/UnivariateFunctionDifferentiator.html ...]
|-
|UnivariateIntegrator
|Interface for univariate integration algorithms.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/integration/UnivariateIntegrator.html ...]
|}

=== Classes ===
{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''FiniteDifferencesDifferentiator'''
|Apply the finite difference method to differentiate a function.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/differentiation/FiniteDifferencesDifferentiator.html ...]
|-
|'''RiddersDifferentiator'''
|Apply the Ridders algorithm to differentiate a function.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/differentiation/RiddersDifferentiator.html ...]
|-
|TrapezoidIntegrator
|The class implements the Trapezoidal rule
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/integration/TrapezoidIntegrator.html ...]
|-
|SimpsonIntegrator
|The class implements the Simpson rule
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/integration/SimpsonIntegrator.html ...]
|}

[[Category:User_Manual_4.17_Mathematics]]

User Manual 4.17 Numerical ordinary differential equations

2025-11-26T13:44:39Z

Admin tsn : Page créée avec « __NOTOC__ == Introduction == === Scope === This library can compute solutions for ordinary differential equations, as numerical approximations. The problems are usually in the form of : Compute an estimate of y(t) from t=t0 to t=t1, knowing the derivative y'=f(t,y), and y(t0)=y0. The library can also handle multiple discrete events detection based on the results of the ongoing estimation, which can be used to dynamically alter the conditions of the problem being... »

__NOTOC__
== Introduction ==
=== Scope ===
This library can compute solutions for ordinary differential equations, as numerical approximations.
The problems are usually in the form of :
Compute an estimate of y(t) from t=t0 to t=t1, knowing the derivative y'=f(t,y), and y(t0)=y0.

The library can also handle multiple discrete events detection based on the results of the ongoing estimation, which can be used to dynamically alter the conditions of the problem being solved, or even stop the integration (for instance : when the function y reaches an expected value, the value of t at this point being the information needed, there is no need to go on).

=== Javadoc ===
==== Integrators ====

The ODE integrators are provided in the following packages :

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/ode/package-summary.html Package fr.cnes.sirius.patrius.math.ode]
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/ode/nonstiff/package-summary.html Package fr.cnes.sirius.patrius.math.ode.nonstiff]
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/ode/sampling/package-summary.html Package fr.cnes.sirius.patrius.math.ode.sampling]
|}

==== Event handling ====

The events are managed in the following package :

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/ode/events/package-summary.html Package fr.cnes.sirius.patrius.math.ode.events]
|}

=== Links ===
None as of now.

=== Useful Documents ===
A general purpose explanation of this section can be found here :

[http://en.wikipedia.org/wiki/Numerical_ordinary_differential_equations http://en.wikipedia.org/wiki/Numerical_ordinary_differential_equations]

=== Package Overview ===

Please note that not all implementations are present in the following diagram for the sake of clarity.

Integrators :

[[File:Integrators2.PNG|center]]

Events package :

[[File:PATRIMOINESIRIUSSUMDiagEvents.png|center]]

== Features Description ==
=== Integrators ===
The provided integrators include :
* the Classical Runge Kutta integrator,
* the Dormand Prince 8(5, 3) integrator,
* the Gragg Bulirsch Stoer integrator,
* the 6th order Runge-Kutta integretor.
* the Stormer-Cowell integrator

The ODE package documentation can be found [http://commons.apache.org/proper/commons-math/userguide/ode.html here ].

=== Events ===
Event handling during an integrator run is a core functionality of the math package,
therefore this is already well-documented in the Javadoc (please see the relevant section).
This here is a short summary of how event handling works.

==== How to monitor events ====
* '''create an EventHandler implementation''' You need to create an EventHandler implementation for the event you want to trace. The most important method here is the g() method : <code>double g(double t, double[] y) throws EventException;</code> This method (which takes as input a solution of the integration problem at a given "time" t) should be designed so that '''when the event occurs, the sign of the method changes'''. It should also be continuous. The other methods of the interface are :
** <syntaxhighlight lang="java">int eventOccurred(double t, double[] y, boolean increasing, boolean forward) throws EventException</syntaxhighlight> This method is called when an event happens. It should return :
*** STOP if the integration computation should stop
*** RESET_STATE if the event handler wants to change the state vector before the integration resumes (the resetState method will be called)
*** RESET_DERIVATIVES if the state vector's derivatives need to be recomputed before the integration resumes
*** CONTINUE if the integration should continue as if nothing happened
** <syntaxhighlight lang="java">void resetState(double t, double[] y) throws EventException</syntaxhighlight> This method is called when eventOccured has returned RESET_STATE. This method should modify the y array, which will change the way the integration performs.
* '''add the EventHandler to an appropriate integrator''' Using an EventHandler on a given integration problem is simple : just add it to the integrator instance before computing the solution. <syntaxhighlight lang="java">integrator.addEventHandler(eventHandler, maxCheckInterval, convergence, maxIterationCount);</syntaxhighlight> Aside from the EventHandler itself, the other parameters are : 
** maxCheckInterval : Maximal time interval between events handler checks.
** convergence : precision needed for the event "time" value.
** iterationCount : maximum number of iterations to find the event "time" value when an event has been identified. Reaching this number means there is a problem with finding the event quickly enough (so, this counter is a way to interrupt an event search that takes too long, since finding an event should be fast if the g() function is continuous).

*'''run the integrator'''
Please see the relevant section.

==== About the EventState class ====
The EventState class is a very important class for event detection (one EventState instance is needed for each EventHandler to work), but since the integrator instantiates EventStates when needed, a regular user never needs to interact directy with an EventState object. Therefore, describing the EventState class is out of the scope of this document; all relevant information can be found in the Javadoc if needed.

== Getting Started ==

== Contents ==
=== Interfaces ===
{| class="wikitable"
|-
! scope="col"| Interface
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''FirstOrderIntegrator'''
|This interface represents a first order integrator for differential equations.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/ode/FirstOrderIntegrator.html ...]
|-
|'''ODEIntegrator'''
|This interface defines the common parts shared by integrators for first and second order differential equations.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/ode/ODEIntegrator.html ...]
|}

{| class="wikitable"
|-
! scope="col"| Interface
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''EventHandler'''
|This interface represents a handler for discrete events triggered during ODE integration.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/ode/events/EventHandler.html ...]
|}

=== Classes ===

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''AbstractIntegrator'''
|Base class managing common boilerplate for all integrators.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/ode/AbstractIntegrator.html ...]
|-
|'''AdaptiveStepsizeIntegrator'''
|This abstract class holds the common part of all adaptive stepsize integrators for Ordinary Differential Equations.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/ode/nonstiff/AdaptiveStepsizeIntegrator.html ...]
|-
|'''ClassicalRungeKuttaIntegrator'''
|This class implements the classical fourth order Runge-Kutta integrator for Ordinary Differential Equations (it is the most often used Runge-Kutta method).
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/ode/nonstiff/ClassicalRungeKuttaIntegrator.html ...]
|-
|'''RungeKutta6Integrator'''
|This class implements the sixth order Runge-Kutta integrator for Ordinary Differential Equations (it is used as the default Stela Integrator). This integrator currently has an second order interpolator.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/ode/nonstiff/RungeKutta6Integrator.html ...]
|-
|'''DormandPrince54Integrator'''
|This class implements the 5(4) Dormand-Prince integrator for Ordinary Differential Equations.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/ode/nonstiff/DormandPrince54Integrator.html ...]
|-
|'''DormandPrince853Integrator'''
|This class implements the 8(5,3) Dormand-Prince integrator for Ordinary Differential Equations.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/ode/nonstiff/DormandPrince853Integrator.html ...]
|-
|'''GraggBulirschStoerIntegrator'''
|This class implements a Gragg-Bulirsch-Stoer integrator for Ordinary Differential Equations.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/ode/nonstiff/GraggBulirschStoerIntegrator.html ...]
|-
|'''RungeKuttaIntegrator'''
|This class implements the common part of all fixed step Runge-Kutta integrators for Ordinary Differential Equations.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/ode/nonstiff/RungeKuttaIntegrator.html ...]
|-
|'''CowellIntegrator'''
|This class implements the 2nd order Stormer-Cowell integrator for Ordinary Differential Equations.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/ode/nonstiff/cowell/CowellIntegrator.html ...]
|}

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''EventState'''
|This class handles the state for one EventHandler during integration steps.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/ode/events/EventState.html ...]
|}

[[Category:User_Manual_4.17_Mathematics]]

User Manual 4.17 Optimization

2025-11-26T13:44:23Z

Admin tsn : Page créée avec « __NOTOC__ == Introduction == === Scope === This section describes PATRIUS optimization features. It will focus on the ''JOptimizer'' functionalities, which provides solvers for general convex optimization problems. In particular it provides the Following optimization solvers: * LP: Linear programming (linear criterion and constraints) * QP: Quadratic Programming (quadratic criterion and linear constraints) * QCQP: Qaudratically Constrained Quadratic Programming... »

__NOTOC__
== Introduction ==
=== Scope ===
This section describes PATRIUS optimization features.

It will focus on the ''JOptimizer'' functionalities, which provides solvers for general convex optimization problems. In particular it provides the Following optimization solvers:
* LP: Linear programming (linear criterion and constraints)
* QP: Quadratic Programming (quadratic criterion and linear constraints)
* QCQP: Qaudratically Constrained Quadratic Programming (quadratic criterion and constraints)

=== Javadoc ===
The optimization classes are available in the package <code>fr.cnes.sirius.patrius.math.optim</code>.

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/optim/package-summary.html Package fr.cnes.sirius.patrius.math.optim]
|}

=== Links ===
None as of now.

=== Useful Documents ===
None as of now.

=== Package Overview ===
The optimization functionalities for joptimizer are organized in the following packages:
*<code>fr.cnes.sirius.patrius.math.optim.joptimizer.algebra</code> compounds the classes with the algebra functionalities.
*<code>fr.cnes.sirius.patrius.math.optim.joptimizer.functions</code> compounds the classes with the optimization functions.
*<code>fr.cnes.sirius.patrius.math.optim.joptimizer.optimizers</code> compounds the classes with the optimizers.
*<code>fr.cnes.sirius.patrius.math.optim.joptimizer.solvers</code> compounds the classes with the solvers.
*<code>fr.cnes.sirius.patrius.math.optim.joptimizer.util</code> compounds the utility classes.

== Features Description ==
Features descritpion for the joptimizer package.
=== Optimizers ===
The <code>JOptimizer</code> class implements the convex optimizer (see "S.Boyd and L.Vandenberghe, Convex Optimization").

The algorithm selection is implemented as a Chain of Responsibility pattern, and this class is the client of the chain.

The different methods implemented to solve the convex optimization problem are:
* Interior point methods
**<code>PrimalDualMethod</code> : primal-dual interior-point method.
**<code>LPPrimalDualMethod</code> : primal-dual interior-point method for linear problems.
**<code>BarrierMethod</code>
*Quality constrained minimization
**<code>NewtonLEConstrainedFSP</code> : linear equality constrained newton optimizer, with a feasible starting point.
**<code>NewtonLEConstrainedISP</code> : linear equality constrained newton optimizer, with an infeasible starting point.
*Unconstrained minimization
**<code>NewtonUnconstrained</code> : unconstrained newton optimizer.

==== Optimization problem ====
The <code>OptimizationRequest</code> class has all the setting field's necessaires to define an optimization problem.

The <code>LPOptimizationRequest</code> is an extension of this class for linear optimization problems.

The general form of a linear problem is (1):
<syntaxhighlight lang="java">
min(c) s.t.
A.x = b
lb <= x <= ub
</syntaxhighlight>

The <code>OptimizationResponse</code> is the class with the getters and setters to set and get the response after the optimization.
The <code>LPOptimizationResponse</code> is the extended class applied to linear problems.

==== Standard converter ====
The <code>LPStandardConverter</code> converts a general linear problem stated in the form (2):
<syntaxhighlight lang="java">
min(c) s.t.
G.x < h
A.x = b
lb <= x <= ub
</syntaxhighlight>
to the (strictly)standard form:
<syntaxhighlight lang="java">
min(c) s.t.
A.x = b
x >= 0
</syntaxhighlight>
or to the (quasi)standard form (1).

==== Presolver ====
The <code>LPPresolver</code> implements a presolver for a linear problem in the form (1).

It applies a set of techniques to the linear programming problem before a linear programming solver solves it. This set of techniques aims at reducing the size of the LP problem by eliminating redundant constraints and variables and identifying possible infeasibility and unboundedness of the problem.

=== Solvers ===
The <code>AbstractKKTSolver</code> implements a solver for the KKT system:
<syntaxhighlight lang="java">
H.v + [A]T.w = -g
A.v = -h
</syntaxhighlight>
where H is a square and symmetric matrix.

The following classes are an extension of <code>AbstractKKTSolver</code>:
*<code>AugmentedKKTSolver</code> (for singular H)
*<code>BasicKKTSolver</code>
*<code>UpperDiagonalHKKTSolver</code> (for upper diagonal H)

=== Functions ===
Different functions are implemented, all of them twice differentiable.
*Linear functions
The <code>LinearMultivariateRealFunction</code> represents a function in the form of:
<syntaxhighlight lang="java">
f(x) = q.x + r
</syntaxhighlight>

*Quadratic functions
The <code>QuadraticMultivariateRealFunction</code> represents a function in the form of:
<syntaxhighlight lang="java">
f(x) := 1/2 x.P.x + q.x + r
</syntaxhighlight>
where x, q ∈ R n, P is a symmetric nXn matrix and r ∈ R.

With the extended <code>PSDQuadraticMultivariateRealFunction</code> and <code>PDQuadraticMultivariateRealFunction</code> classes for P symmetric and positive semi-definite, and P symmetric and positive definite, respectively.

*Barrier functions
The <code>LogarithmicBarrier</code> is the default barrier function for the barrier method algorithm.

If fi(x) are the inequalities of the problem, then the function:
<syntaxhighlight lang="java">
Φ(x) = − ∑_i (log(−fi(x)))
</syntaxhighlight>

=== Algebra ===
==== Factorization ====
The <code>CholeskyFactorization</code> implements the Cholesky L . L[T] factorization and inverse for symmetric and positive matrix:
<syntaxhighlight lang="java">
Q = L.L[T]
</syntaxhighlight>
with L lower-triangular.

==== Rescaler ====
The <code>Matrix1NornRescaler</code> calculates the matrix rescaling factors, so that the 1-norm of each row and each column of the scaled matrix asymptotically converges to one.

== Getting Started ==
=== Example 1 ===
Example of a linear problem optimized by the primal-dual interior-point method.

The problem is:
<syntaxhighlight lang="java">
min(-100x + y) s.t.
x - y = 0
0 <= x <= 1
0 <= y <= 1
</syntaxhighlight>

First, the definition of the variables:
<syntaxhighlight lang="java">
final double[] c = new double[] { -100, 1 }
final double[][] a = new double[][] { { 1, -1 } }
final double[] b = new double[] { 0 }
final double[] lb = new double[] { 0, 0 }
final double[] ub = new double[] { 1, 1 }
</syntaxhighlight>

Definition of the optimization problem by setting the variables:
<syntaxhighlight lang="java">
final LPOptimizationRequest or = new LPOptimizationRequest()
or.setC(c)
or.setA(a)
or.setB(b)
or.setLb(lb)
or.setUb(ub)
</syntaxhighlight>

Additional parameters (tolerance, check the solution accuracy, etc) can also be setted:
<syntaxhighlight lang="java">
or.setCheckKKTSolutionAccuracy(true)
or.setToleranceFeas(1.E-7)
or.setTolerance(1.E-7)
or.setDumpProblem(true)
or.setRescalingDisabled(true)
</syntaxhighlight>

Definition of the optimizer and setting the optimization problem:
<syntaxhighlight lang="java">
LPPrimalDualMethod opt = new LPPrimalDualMethod()
opt.setLPOptimizationRequest(or)
</syntaxhighlight>

Optimization and check that it has not failed:
<syntaxhighlight lang="java">
final int returnCode = opt.optimize()
if (returnCode == OptimizationResponse.FAILED) {
fail()
}
</syntaxhighlight>

Recuperate the response and the solution:
<syntaxhighlight lang="java">
final LPOptimizationResponse response = opt.getLPOptimizationResponse()
final double[] sol = response.getSolution()
</syntaxhighlight>

Validation:
<syntaxhighlight lang="java">
final RealVector cVector = new ArrayRealVector(c)
final RealVector solVector = new ArrayRealVector(sol)
final double value = cVector.dotProduct(solVector)
assertEquals(2, sol.length)
assertEquals(1, sol[0], or.getTolerance())
assertEquals(1, sol[1], or.getTolerance())
assertEquals(-99, value, or.getTolerance())
</syntaxhighlight>

=== Example 2 ===
Example of the optimization of a linear objective function with quadratic constraints.

The problem is:
<syntaxhighlight lang="java">
min(-e.x) s.t.
1/2 x.P.x < v
x + y + z = 1
x > 0
y > 0
z > 0
</syntaxhighlight>

Definition of the linear objective function:
<syntaxhighlight lang="java">
final double[] e = { -0.018, -0.025, -0.01 }
final LinearMultivariateRealFunction objectiveFunction = new LinearMultivariateRealFunction(e, 0)
</syntaxhighlight>

Definition of the quadratic and linear constraints:
<syntaxhighlight lang="java">
final double[][] p = { { 1.68, 0.34, 0.38 }, { 0.34, 3.09, -1.59 }, { 0.38, -1.59, 1.54 } }
final double v = 0.3
final PDQuadraticMultivariateRealFunction qc0 = new PDQuadraticMultivariateRealFunction(p, null,-v)
final LinearMultivariateRealFunction lc0 = new LinearMultivariateRealFunction(new double[] { -1, 0, 0 }, 0)
final LinearMultivariateRealFunction lc1 = new LinearMultivariateRealFunction(new double[] { 0, -1, 0 }, 0)
final LinearMultivariateRealFunction lc2 = new LinearMultivariateRealFunction(new double[] { 0, 0, -1 }, 0)
final ConvexMultivariateRealFunction[] constraints = new ConvexMultivariateRealFunction[] { qc0, lc0, lc1, lc2 }
</syntaxhighlight>

Definition of the equality constraint:
<syntaxhighlight lang="java">
final double[][] a = {{ 1, 1, 1 }}
final double[] b = { 1 }
</syntaxhighlight>

Definition of the optimization problem and setting the parameters:
<syntaxhighlight lang="java">
final OptimizationRequest or = new OptimizationRequest()
or.setF0(objectiveFunction)
or.setFi(constraints)
or.setA(a)
or.setB(b)
or.setToleranceFeas(1.e-6) // additional parameter
</syntaxhighlight>

Definition of the optimizer and setting the optimization problem:
<syntaxhighlight lang="java">
final JOptimizer opt = new JOptimizer()
opt.setLPOptimizationRequest(or)
</syntaxhighlight>

Optimization and check that it has not failed:
<syntaxhighlight lang="java">
final int returnCode = opt.optimize()
if (returnCode == OptimizationResponse.FAILED) {
fail()
}
</syntaxhighlight>

Recuperate the response and the solution:
<syntaxhighlight lang="java">
final LPOptimizationResponse response = opt.getLPOptimizationResponse()
final double[] sol = response.getSolution()
</syntaxhighlight>

Validation:
<syntaxhighlight lang="java">
assertEquals(1., sol[0] + sol[1] + sol[2], 1.e-6)
assertTrue(sol[0] > 0)
assertTrue(sol[1] > 0)
assertTrue(sol[2] > 0)
final RealVector xVector = MatrixUtils.createRealVector(sol)
final RealMatrix pMatrix = MatrixUtils.createRealMatrix(p)
final double xPx = xVector.dotProduct(pMatrix.operate(xVector))
assertTrue(0.5 * xPx < v)
</syntaxhighlight>

== Contents ==
=== Interfaces ===
The interfaces related to the joptimizer are listed here :

{| class="wikitable"
|-
! scope="col"| Interface
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''BarrierFunction'''
|Interface for the barrier function used by a given barrier optimization method.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/optim/joptimizer/functions/BarrierFunction.html ...]
|-
|'''ConvexMultivariateRealFunction'''
|Interface for convex multivariate real functions.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/optim/joptimizer/functions/ConvexMultivariateRealFunction.html ...]
|-
|'''MatrixRescaler'''
|An interface to classes that implement an algorithm to rescale matrices.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/optim/joptimizer/algebra/MatrixRescaler.html ...]
|-
|'''StrictlyConvexMultivariateRealFunction'''
|Interface for striclty convex multivariate real functions.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/optim/joptimizer/functions/StrictlyConvexMultivariateRealFunction.html ...]
|-
|'''TwiceDifferentiableMultivariateRealFunction'''
|Interface for twice-differentiable multivariate functions.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/optim/joptimizer/functions/TwiceDifferentiableMultivariateRealFunction.html ...]
|}

=== Classes ===
The classes related to the joptimizer are listed here :

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''AlgebraUtils'''
|Algebraic utility operations
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/optim/joptimizer/algebra/AlgebraUtils.html ...]
|-
|'''CholeskyFactorization'''
|Implements the Cholesky L.L[T] factorization and inverse for symmetric and positive matrix.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/optim/joptimizer/algebra/CholeskyFactorization.html ...]
|-
|'''Matrix1NornRescaler'''
|Calculates the matrix rescaling factors so that the 1-norm of each row and each column of the scaled matrix asymptotically converges to one.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/optim/joptimizer/algebra/Matrix1NornRescaler.html ...]
|-
|'''FunctionsUtils'''
|Utility class for optimization function building.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/optim/joptimizer/functions/FunctionsUtils.html ...]
|-
|'''LinearMultivariateRealFunction'''
|Represents a function f(x) = q.x + r.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/optim/joptimizer/functions/LinearMultivariateRealFunction.html ...]
|-
|'''LogarithmicBarrier'''
|Default barrier function for the barrier method algorithm.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/optim/joptimizer/functions/LogarithmicBarrier.html ...]
|-
|'''PDQuadraticMultivariateRealFunction'''
|Extends the class QuadraticMultivariateRealFunction with P symmetric and positive definite.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/optim/joptimizer/functions/PDQuadraticMultivariateRealFunction.html ...]
|-
|'''PSDQuadraticMultivariateRealFunction'''
|Extends the class QuadraticMultivariateRealFunction with P symmetric and positive semi-definite.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/optim/joptimizer/functions/PSDQuadraticMultivariateRealFunction.html ...]
|-
|'''QuadraticMultivariateRealFunction'''
|Represents a quadratic multivariate function in the form of f(x):= 1/2 x.P.x + q.x + r.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/optim/joptimizer/functions/QuadraticMultivariateRealFunction.html ...]
|-
|'''AbstractLPOptimizationRequestHandler'''
|Abstract class for Linear Problem Optimization Request Handler.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/optim/joptimizer/optimizers/AbstractLPOptimizationRequestHandler.html ...]
|-
|'''BarrierMethod'''
|Implements the Barrier Method.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/optim/joptimizer/optimizers/BarrierMethod.html ...]
|-
|'''BasicPhaseIBM'''
|Implements the Basic Phase I Method as a Barried Method.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/optim/joptimizer/optimizers/BasicPhaseIBM.html ...]
|-
|'''BasicPhaseILPPDM'''
|Implements the Basic Phase I Method form LP problems as a Primal-Dual Method.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/optim/joptimizer/optimizers/BasicPhaseILPPDM.html ...]
|-
|'''BasicPhaseIPDM'''
|Implements the Basic Phase I Method as a Primal-Dual Method.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/optim/joptimizer/optimizers/BasicPhaseIPDM.html ...]
|-
|'''JOptimizer'''
|Implements the convex optimizer.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/optim/joptimizer/optimizers/JOptimizer.html ...]
|-
|'''LPPresolver'''
|Presolver for a linear problem.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/optim/joptimizer/optimizers/LPPresolver.html ...]
|-
|'''LPPrimalDualMethod'''
|Implements the Primal-dual interior-point method for linear problems.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/optim/joptimizer/optimizers/LPPrimalDualMethod.html ...]
|-
|'''LPStandardConverter'''
|Converts a general LP problem into a strictly standard or quasi standard form.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/optim/joptimizer/optimizers/LPStandardConverter.html ...]
|-
|'''NewtonLEConstrainedFSP'''
|Linear equality constrained newton optimizer, with feasible starting point.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/optim/joptimizer/optimizers/NewtonLEConstrainedFSP.html ...]
|-
|'''NewtonLEConstrainedISP'''
|Linear equality constrained newton optimizer, with infeasible starting point.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/optim/joptimizer/optimizers/NewtonLEConstrainedISP.html ...]
|-
|'''NewtonUnconstrained'''
|Unconstrained newton optimizer.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/optim/joptimizer/optimizers/NewtonUnconstrained.html ...]
|-
|'''OptimizationRequest'''
|Implements an optimization problem.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/optim/joptimizer/optimizers/OptimizationRequest.html ...]
|-
|'''OptimizationRequestHandler'''
|Generic class for optimization process.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/optim/joptimizer/optimizers/OptimizationRequestHandler.html ...]
|-
|'''OptimizationResponse'''
|Optimization process output: stores the solution as well as an exit code.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/optim/joptimizer/optimizers/OptimizationResponse.html ...]
|-
|'''PrimalDualMethod'''
|Implements a primal-dual interior-point method.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/optim/joptimizer/optimizers/PrimalDualMethod.html ...]
|-
|'''AbstractKKTSolver'''
|Abstract class for solving KKT systems.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/optim/joptimizer/solvers/AbstractKKTSolver.html ...]
|-
|'''AugmentedKKTSolver'''
|Extension of AbstractKKTSolver for singular matrix.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/optim/joptimizer/solvers/AugmentedKKTSolver.html ...]
|-
|'''BasicKKTSolver'''
|Extension of AbstractKKTSolver for the basic solver.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/optim/joptimizer/solvers/BasicKKTSolver.html ...]
|-
|'''UpperDiagonalHKKTSolver'''
|Extends the class AbstractKKTSolver for upper diagonal matrix.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/optim/joptimizer/solvers/UpperDiagonalHKKTSolver.html ...]
|-
|'''ArrayUtils'''
|Class offering operations on arrays, primitive arrays (like int[]) and primitive wrapper arrays (like Integer[]).
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/optim/joptimizer/util/ArrayUtils.html ...]
|-
|'''MutableInt'''
|A mutable (int) wrapper.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/optim/joptimizer/util/MutableInt.html ...]
|-
|'''Utils'''
|Utility class.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/optim/joptimizer/util/Utils.html ...]
|}

[[Category:User_Manual_4.17_Mathematics]]

User Manual 4.17 Rotations and quaternions

2025-11-26T13:44:02Z

Admin tsn : Page créée avec « __NOTOC__ == Introduction == === Scope === This section describes rotation and quaternions. === Javadoc === The relevant packages are documented here : {| class="wikitable" |- ! scope="col"| Library ! scope="col"| Javadoc |- | Patrius |[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/package-summary.html Package fr.cnes.sirius.patrius.math.geometry.euclidean.threed] |- | Patrius |[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/complex/packa... »

__NOTOC__
== Introduction ==
=== Scope ===
This section describes rotation and quaternions.

=== Javadoc ===
The relevant packages are documented here :

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
| Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/package-summary.html Package fr.cnes.sirius.patrius.math.geometry.euclidean.threed]
|-
| Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/complex/package-summary.html Package fr.cnes.sirius.patrius.math.complex]
|}

=== Links ===

=== Useful Documents ===
None as of now.

=== Package Overview ===
The relevant functionality can be found in the following packages :

* <code>fr.cnes.sirius.patrius.math.complex</code> for the Quaternion class.
* <code>fr.cnes.sirius.patrius.math.cnesmerge.geometry.euclidean.threed</code> for the Rotation class.
* <code>fr.cnes.sirius.patrius.math.geometry.euclidean.threed</code> for the RotationOrder class.

[[File:PATRIMOINESIRIUSSUMDiagQuatRot.png]]

== Features Description ==
=== Rotations ===
The Rotation is part of the math package fr.cnes.sirius.patrius.math.geometry.euclidean.threed.

The Rotation is represented by a [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/complex/Quaternion.html quaternion]: it is a unit quaternion (a quaternion of norm one). 
The [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/Rotation.html Rotation class] represents an algebraic rotation (i.e. a mathematical rotation).

In a three dimensional space, a rotation <math>r</math> is a function that maps vectors to vectors <math>r: \vec{v} \mapsto \vec{w}</math>. The rotation can be defined by one angle <math>\theta</math> and one axis <math>\vec{u}</math>, transforming <math>\vec{v}</math> into <math>\vec{w}</math> as described in the following figure.

[[File:Rotations.png|center]]

There are several ways to represent rotations. Amongst the most used are quaternions and rotation matrices. The following paragraphs aim to discuss each of them.

=== Quaternions ===
An advantageous way to deal with rotations is by using quaternions (class <code>Quaternion</code>). The quaternion that represents the rotation <math>r</math> defined by an angle <math>\theta</math> and a '''normalized''' axis <math>\vec{u}</math> is :
<center>
<math>Q = \left( \begin{array}{ccc}
cos(\theta / 2) \\
\vec{u}.sin(\theta / 2) \end{array} \right)</math>
</center>

With <math>\vec{u} = ( u_x, u_y, u_z )</math>, <math>Q</math> can also be written as :

<center>
<math>Q = \left( \begin{array}{ccc}
cos(\theta / 2) \\
u_x.sin(\theta / 2) \\
u_y.sin(\theta / 2) \\
u_z.sin(\theta / 2)\end{array} \right)</math>
</center>

Quaternions that represent rotations are normalized :

<center><math>||Q|| = q_0^2 + q_1^2 + q_2^2 + q_3^2 = 1</math></center>

For normalized quaternions, the inverse quaternion <math>Q^{-1}</math> is the same as the conjugate <math>Q^*</math>:
<center>
<math>Q^{-1} =Q^* = \left( \begin{array}{ccc}
cos(\theta / 2) \\
-\vec{u}.sin(\theta / 2) \end{array} \right)</math>
</center>

The image <math>\vec{w}</math> of a vector <math>\vec{v}</math> transformed by the rotation represented by <math>Q</math> is given by :

<center><math>\vec{w} = Q.\vec{v}.Q^{*}</math></center>

====Examples of rotations and associated quaternions====
The rotation defined by the angle <math>\theta = \pi/2</math> and the axis <math>\vec{u} = \vec{z}</math> is represented by the quaternion :

<center>
<math>Q = \left( \begin{array}{ccc}
cos(\pi / 4) \\
0.sin(\pi / 4) \\
0.sin(\pi / 4) \\
1.sin(\pi / 4)\end{array} \right) = \left( \begin{array}{ccc}
\sqrt 2 / 2 \\
0 \\
0 \\
\sqrt 2 / 2\end{array} \right)</math>
</center>

The rotation defined by the angle <math>\theta = 2\pi/3</math> and the axis <math>\vec{u} = (1,1,1)</math> (witch has to be normalized) is represented by the quaternion :

<center>
<math>Q = \left( \begin{array}{ccc}
cos(\pi / 3) \\
1/\sqrt 3.sin(\pi / 3) \\
1/\sqrt 3.sin(\pi / 3) \\
1/\sqrt 3.sin(\pi / 3)\end{array} \right) = \left( \begin{array}{ccc}
1 / 2 \\
1 / 2 \\
1 / 2 \\
1 / 2\end{array} \right)</math>
</center>

====Rotation composition with quaternions====
<math>r_1: \vec{w_1} \mapsto \vec{w_2}</math> and <math>r_2: \vec{w_2} \mapsto \vec{w_3}</math> being two known rotations, the rotation composition <math>r: \vec{w_1} \mapsto \vec{w_3}</math> can be computed as well. The quaternion corresponding to that new rotation is:

<center><math>Q = Q{_2}.Q{_1}</math>.</center>

This can be proven as follows:

<math>\vec{w_2} = Q{_1}.\vec{w_1} .Q_{1}^{-1}</math>
<math>\vec{w_3} = Q{_2}.\vec{w_2} .Q_{2}^{-1}</math>

Substituting <math>\vec{w_2}</math> in the expression of <math>\vec{w_3}</math>:

<center><math>\vec{w_3} = Q{_2}.Q{_1}.\vec{w_1} .Q_{1}^{-1}.Q_{2}^{-1} = (Q{_2}.Q{_1}).\vec{w_1} .(Q_{2}.Q_{1})^{-1} = Q.\vec{w_1} .Q^{-1}</math>.</center>

Notice that in the expression of the quaternion <math>Q</math> the rightmost quaternion is the one corresponding to the first rotation to be performed.

=== Rotation matrices ===
The matrix representation of a rotation is very intuitive altough more redundant compared to quaternions. A rotation matrix is a 3x3 (real) square matrix. 
If the rotation <math>r</math> transforms an inital basis <math>(\vec{x}, \vec{y}, \vec{z})</math> to a new one <math>(\vec{i}, \vec{j}, \vec{k})</math> the columns of the rotation matrix are given by the components of the rotated basis vectors, expressed in the initial one.

<center><math>M = \left( \begin{array}{ccc}
i_x & j_x & k_x \\
i_y & j_y & k_y \\
i_z & j_z & k_z \end{array} \right)</math>
</center>
The matrix <math>M</math> has the following properties:

* <math>M</math> is orthogonal (each column has norm 1)
* <math>det(M) = 1</math>
* <math>M^{-1} = M^{T}</math>

====Rotation matrix in term of quaternions====
Given a quaternion <math>Q = ( q_0, q_1, q_2, q_3 )</math> the rotation matrix has the following expression in term of the components of <math>Q</math>:

<center>
<math>M = \left( \begin{array}{ccc}
q_0^2 + q_1^2-q_2^2 -q_3^2 & 2q_1q_2 + q_0q_3 & 2q_0q_2 + q_1q_3 \\
2q_0q_3 + q_1q_2 & q_0^2 + q_1^2-q_2^2 -q_3^2 & 2q_2q_3 + q_0q_1 \\
2q_1q_3 + q_0q_2 & 2q_0q_1 + q_2q_3 & q_0^2 + q_1^2-q_2^2 -q_3^2 \end{array} \right)</math></center>

=== Rotation interpolation ===
There are two implemented rotations interpolation methods :

- LERP 
- SLERP

=== LERP ===

The LERP (linear interpolation method) is a method of curve fitting using linear polynomials. It is used for rotation interpolation goal in the PATRIUS library and relies on quaternion properties. 
Let <math>q_{0}</math> and <math>q_{1}</math> be two normed quaternions and <math>t</math> an interpolation parameter in the [0;1] range. We can defined <math>q_{t}</math> as the interpolated quaternion so as:

<math>q_{t}= q_{0} + t\times(q_{1}- q_{0})</math>

=== SLERP ===

The SLERP (spherical linear interpolation method) refers to constant-speed motion along a unit-radius great circle arc, given the ends and an interpolation parameter between 0 and 1.It is used for rotation interpolation goal in the PATRIUS library. It relies on quaternion capabilities.
Let <math>q_{0}</math> and <math>q_{1}</math> be two normed quaternions and <math>t</math> an interpolation parameter in the [0;1] range.

First method:
We can defined <math>q_{t}</math> as the interpolated quaternion so as :

<math>q_{t} = q_{0} ( q_{0}^{-1} q_{1} )'</math>

where-prime- operation is defined such as : <math>t, q(\theta, \vec{u}): q’ = q(t \times \theta, \vec{u})</math>

Second method:
Another approch is to compute qt so as:

<math>q_{t} = q_{0} \frac{\sin (1-t)\lambda}{\sin \lambda} + q_{1} \frac{\sin (t \lambda)}{\sin \lambda}</math>

with lambda defined so as:

<math>\cos \lambda = q_{0} . q_{1}</math>

This latest approach saves computing time when dealing with many SLERP computing.

== Getting Started ==

=== Building Rotations ===
Rotations can be represented by several different mathematical entities (matrices, axis and angle, Cardan or Euler angles, quaternions). The user can build a rotation from any of these representations, and any of these representations can be retrieved from a [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/Rotation.html Rotation instance].
In addition, a rotation can also be built implicitly from a set of vectors and their image or just a vector and its image.

==== Rotation quaternion ====

The rotation can be built from a rotation quaternion using one of the following constructors :

*'''''Rotation(boolean needsNormalization, double q0, double q1, double q2, double q3)'''''
*'''''Rotation(boolean needsNormalization, final Quaternion quaternion)'''''
*'''''Rotation(boolean needsNormalization, final double[] q)'''''

A rotation can be built from a normalized quaternion, i.e. a quaternion for which <math>q_0^2 + q_1^2 + q_2^2 + q_3^2 = 1</math>. If the quaternion is not normalized, the constructor can normalize it in a preprocessing step.

Note that some conventions put the scalar part of the quaternion as the fourth component and the vector part as the first three components. The scalar part is put as the first component.

The rotation quaternion can be retrieve using '''''getQuaternion()''''' or '''''getQi()'''''.

==== Axis-angle representation ====

The rotation can be built from an axis <math>(x, y, z)</math> and an angle <math>\theta</math> with the following constructor :

<syntaxhighlight lang="java">
// 90 deg rotation around z-axis
Vector3D axis = new Vector3D(0, 0, 1);
double angle = FastMath.PI / 2.;
Rotation r = new Rotation(axis, angle);
</syntaxhighlight>

If necessary, the quaternion is normalized.

The axis and the angle can be retrieved using '''''getAxis()''''' and '''''getAngle()'''''.

==== Matrix representation ====
The rotation can be built from a rotation matrix with the following constructor :
*'''''Rotation(double[][] m, double threshold)'''''

The rotation matrix can be retrieved using '''''getMatrix()'''''.

==== Euler Angles ====

===== The RotationOrder class =====

The RotationOrder class contains static attributes, themselves being RotationOrder objects, describing every vector sequence that can be used to create a Rotation using Euler or Cardan angles.

===== Using Euler angles in rotations =====

A Rotation object can so be created using three angles and a RotationOrder describing the associated sequence of basis vectors.
The user can also get the Cardan or Euler angles by giving a sequence, using the getAngles(RotationOrder) method.
In some cases, there are singularities that make a rotation impossible to describe with a giver rotation order.

Code example :

<syntaxhighlight lang="java">
Rotation rotation = new Rotation(RotationOrder.YZX, 0.12, 0.54, 0.45);
double[] angles = rotation.getAngles(RotationOrder.ZXY);
</syntaxhighlight>

==== Others representations ====
See [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/Rotation.html Rotation javadoc].

=== Using Rotations ===
The Rotation is part of the package fr.cnes.sirius.patrius.math
.geometry.euclidean.threed.

The Rotation is represented by a rotation quaternion : it is a unit quaternion (a quaternion of norm one). 
The [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/Rotation.html Rotation class] represents an algebraic rotation (i.e. a mathematical rotation).

==== Rotate a vector ====

A rotation is an operator which basically rotates three dimensional [{{JavaDoc4.17}}//fr/cnes/sirius/patrius/math/geometry/euclidean/threed/Vector3D.html vectors] into other three dimensional [{{JavaDoc4.17}}//fr/cnes/sirius/patrius/math/geometry/euclidean/threed/Vector3D.html vectors] using '''''applyTo()'''''.

<syntaxhighlight lang="java">
// vector A
Vector3D a = new Vector3D(1, 0, 0);
// build rotation r1
Vector3D u1 = new Vector3D(0, 0, 1);
double theta1 = FastMath.PI / 2. ;
Rotation r1 = new Rotation(u1, theta1);
// vector B, image of A by r1
Vector3D b = r1.applyTo(a);
</syntaxhighlight>

==== Compose rotations ====

Since a rotation is basically a vectorial operator, several rotations can be composed together and the composite operation r = r2 o r1 is also a rotation. r1 is applied before r2 and the operator '''''applyTo()''''' is used.

<syntaxhighlight lang="java">
// build rotation r1
Vector3D u1 = new Vector3D(0, 0, 1);
double theta1 = FastMath.PI / 2. ;
Rotation r1 = new Rotation(u1, theta1);
// build rotation r2
Vector3D u2 = new Vector3D(1, 0, 0);
double theta2 = FastMath.PI / 2. ;
Rotation r2 = new Rotation(u2, theta2);
// build r2 o r1
Rotation r2_o_r1 = r2.applyTo(r1);
// vector D, image of A by r2 o r1
Vector3D d = r2_o_r1.applyTo(a);
</syntaxhighlight>

==== Change the basis of a vector ====

The rotation could be used to change the basis of a vector using '''''applyInverseTo()'''''.

<syntaxhighlight lang="java">
// Define frame R2 by building the rotation r12 in frame R1
Vector3D u12_R1 = new Vector3D(1, 1, 1);
double theta12 = FastMath.PI* 3. / 2.;
Rotation r12_R1 = new Rotation(u12_R1, theta12);
// vector A, expressed in R1
Vector3D a_R1 = new Vector3D(0.5, 0.5, 0);
// vector A, expressed in R2
Vector3D a_R2 = r12_R1.applyInverseTo(a_R1);

// Build rotation r, in R1 frame
Vector3D u_R1 = new Vector3D(0, 0, 1);
double theta = FastMath.PI;
Rotation r_R1 = new Rotation(u_R1, theta);
// Vector B, image of A by the rotation r, expressed in R1
Vector3D b_R1 = r_R1.applyTo(a_R1);
// Vector B, changed of basis, expressed in R2
Vector3D b_R2 = r12_R1.applyInverseTo(b_R1);
</syntaxhighlight>

==== Change the basis of a rotation ====

Let be r a rotation built from the coordinates of its rotation axis. This vector is expressed in a frame <math>R_1</math> ; the rotation is supported only in this frame.
Let be <math>r_12</math> the rotation from <math>R_1</math> to <math>R_2</math>, i.e. the image of the axis <math>x_1</math> expressed in <math>R_1</math> using the rotation <math>r_12</math> is the axis <math>x_2</math> expressed in <math>R_2</math> : <math>r_12(x_1) = x_2</math> with <math>x_1</math>, <math>x_2</math> and <math>r_12</math> expressed in <math>R_1</math>.

The rotation r, changed of basis to be expressed in <math>R_2</math> is obtained by'''''<math>r_12</math>.applyTo(r.revert())'''''.

<syntaxhighlight lang="java">
// Define frame R2 by building the rotation r12 in frame R1
Vector3D u12_R1 = new Vector3D(1, 1, 1);
double theta12 = FastMath.PI* 3. / 2.;
Rotation r12_R1 = new Rotation(u12_R1, theta12);
// Build rotation r, in R1 frame
Vector3D u_R1 = new Vector3D(0, 0, 1);
double theta = FastMath.PI;
Rotation r_R1 = new Rotation(u_R1, theta);
// Change the basis of r
Rotation r_R2 = r12_R1.applyTo(r_R1.revert());
</syntaxhighlight>

=== Using Quaternions ===
The <code>Quaternion</code> class provides all elementary operations on quaternions: sum, product, inverse, conjugate, norm, dot product, etc.
Below are some examples of use:

* Computing the product of two quaternions:

<syntaxhighlight lang="java">
Quaternion qA = new Quaternion(qA0,qA1,qA2,qA3);
Quaternion qB = new Quaternion(qB0,qB1,qB2,qB3);
Quaternion qProduct = Quaternion.multiply(qA,qB);
</syntaxhighlight>

* Getting the inverse of a quaternion :

<syntaxhighlight lang="java">
Quaternion q = new Quaternion(0,5.1,4,8);
Quaternion qInverse = q.getInverse();
</syntaxhighlight>

=== Using Rotations interpolation ===

===== LERP Use case =====

Here is an exemple on how one can compute LERP in Java language using PATRIUS:

<syntaxhighlight lang="java">
final Vector3D axis = new Vector3D(1,1,1);
final Rotation r1 = new Rotation(axis,FastMath.PI/6.);
final Rotation r2 = new Rotation(axis,FastMath.PI/3.);

final Rotation r = Rotation.lerp(r1, r2, 0.5);
</syntaxhighlight>

then one can retrieve corresponding rotation angle and axis:

<syntaxhighlight lang="java">
final double rangle = r.getAngle();
final Vector3D raxis = r.getAxis();
</syntaxhighlight>

Same example given in Scilab using Celestlab macros library:

<syntaxhighlight lang="scilab">
alpha1 = CL_deg2rad(30.);
q1 = CL_rot_axAng2quat([1;1;1],alpha1);
alpha2 = CL_deg2rad(60.);
q2 = CL_rot_axAng2quat([1;1;1],alpha2);
q = q1 + 0.5* (q2 - q1);
q = (1/norm(q))* q
[axis, angle] = CL_rot_quat2axAng(q)
</syntaxhighlight>

==== SLERP Use example ====

Here is an exemple on how one can compute LERP in Java language using PATRIUS:

<syntaxhighlight lang="java">
final Vector3D axis = new Vector3D(1,1,1);
final Rotation r1 = new Rotation(axis,FastMath.PI/6.);
final Rotation r2 = new Rotation(axis,FastMath.PI/3.);

final Rotation r = Rotation.slerp(r1, r2, 0.5);
</syntaxhighlight>

then one can retrieve corresponding rotation angle and axis:

<syntaxhighlight lang="java">
final double rangle = r.getAngle();
final Vector3D raxis = r.getAxis();
</syntaxhighlight>

Same example given in Scilab using Celestlab macros library:

<syntaxhighlight lang="scilab">
alpha1 = CL_deg2rad(30.);
q1 = CL_rot_axAng2quat([1;1;1],alpha1);
alpha2 = CL_deg2rad(60.);
q2 = CL_rot_axAng2quat([1;1;1],alpha2);
q = CL_rot_quatSlerp(q1,q2,.5);

[axis, angle] = CL_rot_quat2axAng(q)
</syntaxhighlight>

== Contents ==
=== Interfaces ===
None as of now.

=== Classes ===
The relevant classes are :

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''Quaternion'''
|This class implements quaternions.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/complex/Quaternion.html ...]
|-
|'''Rotation'''
|This class implements rotations in a three-dimensional space.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/Rotation.html ...]
|-
|'''RotationOrder'''
|This class is a utility representing a rotation order specification for Cardan or Euler angles specification.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/RotationOrder.html ...]
|}

[[Category:User_Manual_4.17_Mathematics]]

User Manual 4.17 Root-Finding Algorithms

2025-11-26T13:43:33Z

Admin tsn : Page créée avec « __NOTOC__ == Introduction == === Scope === This section is about the root-finding algorithms for univariate real functions provided by the library. First we explain how to use the root-finding algorithms. Then a focus is made on the following root finding methods: Brent, Newton, Bisection and Müller. === Javadoc === All solvers are in the following package : [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/math/analysis/solver/package-summary.html fr.cnes.sirius.patriu... »

Catégorie:User Manual 4.17 Mission

2025-11-26T13:40:33Z

Admin tsn : Page créée avec «  == Introduction == This section presents the events and visibility aspects of the PATRIUS library. First of all, it is necessary to manage the event detection during the propagation, to that purpose, a smart mechanism has been developped in the math package and repeated in Patrius when it comes to propagate with an AbstractPropagator. In Patrius, it is possible to register during the propagation the detected events. A new conception has been developped on this b... »

== Introduction ==
This section presents the events and visibility aspects of the PATRIUS library. First of all, it is necessary to manage the event detection during the propagation, to that purpose, a smart mechanism has been developped in the math package and repeated in Patrius when it comes to propagate with an AbstractPropagator. In Patrius, it is possible to register during the propagation the detected events. A new conception has been developped on this basis in order to create a list of CodedEvent (code + comment + date) during the propagation as well as a list of Phenomenon. Then, the user can perform a post processing on the generated events list and phenomena list thanks to several filters.

== Applicable and Reference Documents ==
=== Applicable Documents ===

'''[A1]''' ''CDCF - Fonctions de Base du Patrimoine de Dynamique du Vol'', V1.2, SIRIUS-CF-DV-0049-CN, 2011. 
'''[A2]''' ''Dossier de réutilisation Orekit et Commons Math'', V1.0, SIRIUS-DLR-DV-0080-CN, 2010.

=== Reference Documents ===

'''[R1]''' ''Apache License'', Version 2.0, January 2004, [http://www.apache.org/licenses/LICENSE-2.0.txt].

== Glossary ==
None applicable.

== Overview ==
The following themes are discussed in this section:

*'''Events detection'''

*'''Post processing on events and phenomena'''

*'''Maneuvers'''

*'''Projections'''

[[Catégorie:User Manual 4.17]]

User Manual 4.17 Projections

2025-11-26T13:40:16Z

Admin tsn : Page créée avec « == Introduction == === Scope === The scope of this section is to present the projections features available in Patrius library. Patrius provides classes to perform projections on an ellipsoid as well as various computation on the surface of an ellipsoid. Common available projections are: * Mercator * Flamsteed-Samson * Identity projection === Javadoc === All the classes related to projections are in the following packages: {| class="wikitable" |- ! scope="col"|... »

== Introduction ==
=== Scope ===
The scope of this section is to present the projections features available in Patrius library.
Patrius provides classes to perform projections on an ellipsoid as well as various computation on the surface of an ellipsoid. Common available projections are:
* Mercator
* Flamsteed-Samson
* Identity projection

=== Javadoc ===
All the classes related to projections are in the following packages:

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/projections/package-summary.html Package fr.cnes.sirius.patrius.projections]
|}

=== Links ===
More information about specific projections can be found using the following links:
* [https://en.wikipedia.org/wiki/Mercator_projection Mercator projection]
* [https://en.wikipedia.org/wiki/Sinusoidal_projection Flamsteed-Samson projection]

=== Useful Documents ===
None as of now.

=== Package Overview ===
The projections package gathers:
* An interface for all projections: <code>IProjection</code>
* Some available projections : <code>Mercator</code>, <code>GeneralizedFlamsteedSamson</code> and <code>IdentityProjection</code>
* A ellipsoid with extended features: <code>ProjectionEllipsoid</code>

The projection package can be summarized with the following UML diagram.

Please note that not all implementations are present in the following diagram for the sake of clarity.

[[File:Projections.png|center]]

== Features Description ==
Projections provide three main features:
* Projection on an ellipsoid (and its inverse application)
* Discretisation between points on the surface of an ellipsoid
* Geometric computation on the surface of an ellipsoid using class ProjectionEllipsoid

=== Projection on an ellipsoid ===

Projection on an ellipsoid is a transformation taking geodetic coordinates (latitude, longitude, altitude) as input and returning 2D map coordinates (X, Y) as output.
Inverse transformation takes 2D map coordinates (X, Y) as input and returns geodetic coordinates (latitude, longitude, altitude) as output.

Projection classes inherit projection interface <code>IProjection</code>. 
Available projections are:
* Mercator projection: <code>Mercator</code>. The Mercator projection is a cylindrical map projection which became the standard map projection for nautical purposes because of its ability to represent lines of constant course, known loxodromes, as straight segments. Mercator projection is conformal (angles are preserved) but not equivalent (areas are not preserved).

[[File:MercatorProjection.jpg|center]]

* Flamsteed-Samson projection: <code>GeneralizedFlamsteedSamson</code>. This projection is also known as the sinusoidal projection. The sinusoidal projection is equal-area and preserves distances along the horizontals but is not conformal (angles are not preserved).

[[File:SinusoidalProjection.jpg|center]]

* Identity projection: <code>IdentityProjection</code>. Identity projection is the projection [latitude, longitude, altitude] => [X = latitude, Y = longitude].

All projections provide:
* direct transformation using method <code>applyTo()</code>. It returns 2D map coordinates (X, Y) from geodetic coordinates (latitude, longitude, altitude).
* inverse transformation using method <code>applyInverseTo()</code>. It returns geodetic coordinates (latitude, longitude, altitude) from 2D map coordinates (X, Y).

=== Discretization ===

All projection classes provide various discretization methods between geodetic points.

* Discretization between two projected points using the method <code>discretize()</code>. Maximum distance between discretized point has to be provided.
* Discretization along a polygon line of geodetic coordinates using the method <code>discretizeAndApplyTo()</code>. Maximum distance between discretized point has to be provided as well as the discretization strategy.

The discretization strategy is provided with the enumeration <code>EnumLineProperty</code>. It offers the following possibilities:
* <code>STRAIGHT</code>: straight line between two geodetic points.
* <code>GREAT_CIRCLE</code>: arc being the shortest way to connect two geodetic points on an ellipsoid. The center of the ellipsis is the ellipsoid center.
* <code>STRAIGHT_RHUMB_LINE</code>: arc between two geodetic points crossing all meridians of longitude at the same angle. It corresponds to a path of constant bearing as measured relative to true north. On Mercator projection, it is represented by a straight line.

Other methods are available. For more information, refer to the javadoc of [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/projections/AbstractProjection.html AbstractProjection] class.

=== Computation on the surface of an ellipsoid ===

A specific ellipsoid class has been defined to handle projections: <code>ProjectionEllipsoid</code>. This class inherits the class <code>OneAxisEllipsoid</code>. 
It provides many useful projection-related computations on the surface of an ellipsoid. 
Available features of <code>ProjectionEllipsoid</code> are:

* Distance computation:

Orthodromic distance using method <code>computeOrthodromicDistance()</code>. Orthodromic distance is the shortest path between two points. 
Loxodromic distance using method <code>computeLoxodromicDistance()</code>. Loxodromic distance follows path of constant bearing: this is a straight line on Mercator projection. 
Meridional distance using method <code>computeMeridionalDistance()</code>. Meridional distance is the shortest distance from one point to the equator (along a meridian).

On next image, Loxodromic distance is in red, orthodromic distance in blue:
[[File:LoxodromieOrthodromie.png|center]]

* Azimuth computation:

Bearing using method <code>computeBearing()</code>. 
Spherical azimuth using method <code>computeSphericalAzimuth()</code>.

* Other computations:

Point along loxodrome, given a point, a distance from this point and an azimuth from this point, using method <code>computePointAlongLoxodrome()</code>. 
Point along orthodrome, given a point, a distance from this point and an azimuth from this point, using method <code>computePointAlongOrthodrome()</code>.

Other methods are available. For more information, refer to the javadoc of [{{JavaDoc4.17}}/fr/cnes/sirius/patrius/projections/ProjectionEllipsoid.html ProjectionEllipsoid] class.

== Getting Started ==
Projections provide three main features:
* Projection on an ellipsoid (and its inverse application)
* Discretisation between points on the surface of an ellipsoid
* Geometric computation on the surface of an ellipsoid using class <code>ProjectionEllipsoid</code>

=== Projection on an ellipsoid ===

First an ellipsoid and a projection have to be defined, here using a simple centered Mercator projection:

<syntaxhighlight lang="java">
final EllipsoidBodyShape ellipsoid = new OneAxisEllipsoid(6378137.0, 1. / 298.257223563, FramesFactory.getITRF(), "earth");
final Mercator projection = new Mercator(0., ellipsoid);
</syntaxhighlight>

Then the created projection can be used in different ways:

* Projection of geodetic coordinates:

<syntaxhighlight lang="java">
final EllipsoidPoint toulouse = new EllipsoidPoint(ellipsoid, LLHCoordinatesSystem.ELLIPSODETIC, 0.758011794, 0.026140528, 256., "toulouse");
final Vector2D projectedPoint = projection.applyTo(toulouse);
</syntaxhighlight>

* Retrieve geodetic coordinates from Mercator 2D coordinates:

<syntaxhighlight lang="java">
final EllipsoidPoint geodeticCoordinates = projection.applyInverseTo(projectedPoint.getX(), projectedPoint.getY());
</syntaxhighlight>

=== Discretization ===

First an ellipsoid and a projection have to be defined, here using a simple centered Mercator projection:

<syntaxhighlight lang="java">
final EllipsoidBodyShape ellipsoid = new OneAxisEllipsoid(6378137.0, 1. / 298.257223563, FramesFactory.getITRF(), "earth");
final Mercator projection = new Mercator(0., ellipsoid);
</syntaxhighlight>

Then the created projection can be used in different ways:

* Discretization between two projected points with a maximum distance between points of 1km:

<syntaxhighlight lang="java">
final EllipsoidPoint toulouse = new EllipsoidPoint(ellipsoid, LLHCoordinatesSystem.ELLIPSODETIC, 0.758011794, 0.026140528, 256., "toulouse");
final EllipsoidPoint london = new EllipsoidPoint(ellipsoid, LLHCoordinatesSystem.ELLIPSODETIC, 0.898844565, 0.002268928, 25., "london");
final Vector2D projectedToulouse = projection.applyTo(toulouse);
final Vector2D projectedLondon = projection.applyTo(london);
final List<Vector2D> points = projection.discretize(projectedToulouse, projectedLondon, 1000., true);
</syntaxhighlight>

* Rhumb discretization along a polygon line with a maximum distance between points of 1km followed by projection:

<syntaxhighlight lang="java">
final List<EllipsoidPoint > list = new ArrayList<>();
list.add(toulouse);
list.add(london);
final List<Vector2D> points = projection.discretizeAndApplyTo(list , EnumLineProperty.STRAIGHT_RHUMB_LINE, 1000.);
</syntaxhighlight>

* etc. Other similar discretization features are available. See javadoc for more information.

=== Computation on the surface of an ellipsoid ===

First an ellipsoid has to be defined:

<syntaxhighlight lang="java">
final EllipsoidBodyShape ellipsoid = new OneAxisEllipsoid(6378137.0, 1. / 298.257223563, FramesFactory.getITRF(), "earth");
</syntaxhighlight>

Then this ellipsoid can be used to:

* Compute distances on the surface of the ellipsoid:

<syntaxhighlight lang="java">
final double orthodromicDistance = ellipsoid.computeOrthodromicDistance(toulouse, london);
final double loxodromicDistance = ellipsoid.computeLoxodromicDistance(toulouse, london);
final double meridionalDistance = ellipsoid.computeMeridionalDistance(toulouse.getLatitude());
</syntaxhighlight>

* Compute azimuth angles on the surface of the ellipsoid:

<syntaxhighlight lang="java">
final double bearing = ellipsoid.computeBearing(toulouse, london);
final double sphericalAzimuth = ellipsoid.computeSphericalAzimuth(toulouse, london);
</syntaxhighlight>

* etc. Other similar features are available. See javadoc for more information.

== Contents ==
=== Interfaces ===

{| class="wikitable"
|-
! scope="col"| Interface
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''IProjection'''
|Interface for projections on a 3D body.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/projections/IProjection.html ...]
|}

=== Classes ===
{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''EnumLineProperty'''
|Enumeration of points connecting strategies on an ellipsoid.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/projections/EnumLineProperty.html ...]
|-
|'''IdentityProjection'''
|Identity projection.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/projections/IdentityProjection.html ...]
|-
|'''GeneralizedFlamsteedSamson'''
|Flamsteed-Samson projection.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/projections/GeneralizedFlamsteedSamson.html ...]
|-
|'''Mercator'''
|Mercator projection.
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/projections/Mercator.html ...]
|-
|'''ProjectionEllipsoid'''
|Ellipsoid with extended features (features related to projections).
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/projections/ProjectionEllipsoid.html ...]
|}

[[Category:User_Manual_4.17_Mission]]

User Manual 4.17 Postprocessing

2025-11-26T13:40:02Z

Admin tsn : Page créée avec «  == Introduction == === Scope === This section describes all postprocessing actions available on events and phenomena === Javadoc === All the classes are available in the following package: {| class="wikitable" |- ! scope="col"| Library ! scope="col"| Javadoc |- |Patrius |[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/postprocessing/package-summary.html Package fr.cnes.sirius.patrius.events.postprocessing] |} === Links === None as of now. === Useful Documen... »

== Introduction ==
=== Scope ===
This section describes all postprocessing actions available on events and phenomena

=== Javadoc ===
All the classes are available in the following package:

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
|Patrius
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/postprocessing/package-summary.html Package fr.cnes.sirius.patrius.events.postprocessing]
|}

=== Links ===
None as of now.

=== Useful Documents ===
None as of now.

=== Package Overview ===
The conception of the post processing is presented hereafter.

Please note that not all implementations are present in the following diagram for the sake of clarity.

[[File:PATRIMOINESIRIUSPostProcessing.png|center]]

After the propagation, the logger (CodedEventsLogger) has registered all of the events and the phenomena detected during the propagation. Then, the associated timeline (Timeline) is created from this logger. This object contains all of the detected events and phenomena. On this timeline, different types of post processings can be performed.

== Features Description ==
=== Phenomenon duration filter ===
This filter removes from the list the specified phenomena with a duration greater / lower than a given criterion. 
A boolean "isMinDuration" determines if the criterion is the minimum or maximum duration of the phenomena that will remain on the list. 
The comparison is made with the Comparators class "greaterOrEqual" or "lowerOrEqual" method with a e-14 relative "doubles comparison" epsilon. The phenomena with a duration equal to the criterion are so always kept in the list.

=== Element type filter ===
This filter selects all the events and/or phenomena in the Timeline whose code correspond to one or more given codes and removes them from the Timeline (or it keeps them and removes all the other elements in the Timeline). 
The user sets the codes of the elements to keep/remove using an array of string. 
If the boolean removeAll is set to false at the filter construction, then the complementary filter is built i.e. a filter which preserves in the TimeLine only the given events or phenomena type.

=== Occurrence filter ===
This filter removes all of the Nxk occurrences of a given event or phenomenon type. The type is defined by the code.

If the boolean removeAll is set to false at the filter construction, then the complementary filter is built i.e. a filter which preserves in the Timeline only the Nxk occurrences of the given event or phenomenon type.

For example, if N=3 then the third, sixth, ninth... occurrences will be kept or removed.

=== Events during phenomena filter ===
This filter removes all of the specified types of events that occur during a given phenomenon type. A type is defined by the code.

If the boolean removeAll is set to false at the filter construction, then the complementary filter is built i.e. a filter that erases the events of the given types which occur outside the given phenomenon type.

=== Time filter ===
This filter removes all of the specified events and phenomena types which occur during a given time interval. 
If the boolean removeAll is set to false, the complementary filter is built i.e. a filter which preserves the specified events and the phenomena that occur during the given time interval.

NB : if the phenomenon interval of validity overlaps the given time interval, the phenomenon is redefined with an undefined start or end event.

=== "AND" criterion on phenomena ===
This criterion adds to the phenomena list of a Timeline object the phenomena corresponding to time intervals when phenomena of particular types A AND B occur at the same time. 
The events defining the beginning and the end of those new phenomena are directly the ones of the original A and B phenomena.

=== "OR" criterion on phenomena ===
This criterion adds to the phenomena list of a Timeline object the phenomena corresponding to time intervals when phenomena of particular types A OR B occur. 
The events defining the beginning and the end of those new phenomena are directly the ones of the original A and B phenomena.

=== "NOT" criterion on phenomena ===
This criterion returns the complementary interval of of phenomenon.

=== Delayed events ===
This criterion adds delayed events for a given event type. The delay is given at the construction of the criterion, it is given in secondes, it can be either positive or negative.

=== Merged phenomena ===
This criterion merges two phenomena of a same given type if the lapse between them is below a given value. This value is given at the criterion construction, it is given in secondes.

=== Merged Timelines ===
This post-processing merges two Timelines adding all the events and phenomena of one Timeline to the other one. 
The merging operation is allowed only if the time interval of validity of the two Timelines is the same, otherwise the method <code>applyTo(Timeline list)</code> throws an exception.

=== Polarization single selection ===
This post-processing creation adds one phenomenon to the timeline; this new phenomenon represents a polarization single selection over two visibility phenomena timelines. 
If the chosen phenomenon is called for instance "VISI L", the output phenomenon code will be "VISI L Selection". 

The selection of this polarization phenomenon is made through the following three steps:

#phenomena L and R are filtered in order to remove the phenomena whose duration is shorter then dMin;
#the remaining phenomena are filtered again in order to merge two phenomena if the time between the end of one phenomenon and the beginning of the other is shorter than dMax;
#the longest phenomenon is selected among all the remaining L and R phenomena.

The following image represents an example of the polarization single selection process on the timelines L and R:

[[File:polarizationChoice.png|center]]

=== Polarization switch ===
This post-processing creation possibly adds new events to the timeline; these new events represent polarization switches over two visibility phenomena timelines. 
If the phenomenon that triggers the polarization switch is called for instance "VISI L", the output event code will be "VISI L Selection"; the date of the new polarization event will be the end date of the previous phenomenon (even if the next phenomenon has not already started).

The first steps of the polarization switching algorithm are identical to the polarization single selection algorithm:

#phenomena L and R are filtered in order to remove the phenomena whose duration is shorter then dMin;
#the remaining phenomena are filtered again in order to merge two phenomena if the time between the end of one phenomenon and the beginning of the other is shorter than dMax;
#all phenomena are kept.

The following image represents an example of these steps on the timelines L and R:

[[File:switchingPolarizationfirst.png|center]]

After these first filtering steps the polarisation switches are computed as follows :

<ol>

<li>first choice: if both phenomena L and R are active at the beginning of the interval of validity, select the longest one; if only one phenomenon is active, select it; otherwise if both phenomena are not active, select the next active phenomenon. In any case, the output event date will coincide with the beginning of the interval of validity.</li>
<li>once the first phenomenon selected, move forward until the end of it (date Tf); a new event is triggered if one of the following conditions applies: 
- at Tf the other phenomenon is active, and its remaining duration is longer than dMin; 
- the next polarization phenomenon after Tf belongs to the other polarization group of phenomena(L if the current phenomenon is R and vice versa). 
If an event is triggered, its date will be Tf.</li>
<li>apply 2. until the end of the interval of validity.</li>
</ol>

The following image represents 6 examples of the expected switching polarization events for two polarization phenomena timelines, called L and R:

[[File:switchingPolarization.png|center]]

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

== Contents ==
=== Interfaces ===
{| class="wikitable"
|-

! scope="col"| Interface
! scope="col"| Summary
|-
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/postprocessing/PostProcessing.html PostProcessing]
|This interface represents a postprocessing action on a TimeLine object.
|}

=== Classes ===

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
|-
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/postprocessing/ElementTypeFilter.html ElementTypeFilter]
|Filter that removes or keeps only the items of a specific type (code or code + comment) in a given timeline.
|-
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/postprocessing/TimeFilter.html TimeFilter]
|Filter that removes or keeps only all of the events and the phenomena that are inside a given time interval.
|-
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/postprocessing/OccurrenceFilter.html OccurrenceFilter]
|Filter that removes or keeps only the N x k occurrences of a specific element type (code or code + comment) in a given timeline.
|-
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/postprocessing/PhenomenonDurationFilter.html PhenomenonDurationFilter]
|This filter removes phenomena on a duration criterion.
|-
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/postprocessing/EventsDuringPhenomenaFilter.html EventsDuringPhenomenaFilter]
|Filter that removes or keeps only a specified type of events during a specified type of phenomena.
|-
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/postprocessing/DelayCriterion.html DelayCriterion]
|This class is a post processing criterion that delays a specified kind of events.
|-
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/postprocessing/MergePhenomenaCriterion.html MergePhenomenaCriterion]
|This class is a post processing criterion that merges two successive phenomena if the time lapse is below a given value.
|-
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/postprocessing/AndCriterion.html AndCriterion]
|Adds the phenomena corresponding to the occruences of phenomena of types A AND B at the same time.
|-
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/postprocessing/OrCriterion.html OrCriterion]
|Adds the phenomena corresponding to the occruences of phenomena of types A OR B merged.
|-
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/postprocessing/NotCriterion.html NotCriterion]
|Returns the complementary interval of of phenomenon.
|-
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/postprocessing/MergeTimelines.html MergeTimelines]
|Merges two timelines when their intervals of validity are the same.
|-
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/postprocessing/PolarizationSingleSelection.html PolarizationSingleSelection]
|Creates a new phenomenon representing the polarization single selection from two visibility phenomena.
|-
|[{{JavaDoc4.17}}/fr/cnes/sirius/patrius/events/postprocessing/PolarizationSwitch.html PolarizationSwitch]
|Adds new events to the timeline, each one representing a polarization switch.
|}

[[Category:User_Manual_4.17_Mission]]