Patrius - Contributions [fr]

Accueil

2026-06-30T08:11:30Z

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.18 ==
'''PATRIUS''' V4.18 is a release adding a few features as well as correcting some bugs (see [[Main_differences_between_V4.18_and_V4.17|here]]).

== PREVIOUS VERSIONS (available on the Web site) ==

* Version 4.17
* 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.18 Current Java Doc]

[https://patrius.cnes.fr/images/upload/JavaDocs/V4.17 Java Doc 4.17] 
[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]

Accueil

2026-06-30T08:10:59Z

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.18 ==
'''PATRIUS''' V4.18 is a release adding a few features as well as correcting some bugs (see [[Main_differences_between_V4.18_and_V4.17|here]]).

== PREVIOUS VERSIONS (available on the Web site) ==

* Version 4.17
* 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.18 Current Java Doc]

[https://patrius.cnes.fr/images/upload/JavaDocs/V4.17 Java Doc 4.16] 
[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]

Main differences between V4.18 and V4.17

2026-06-10T14:04:05Z

Admin tsn :

'''PATRIUS''' V4.18 is a major release adding some new features and correcting some bugs.

== New functionalities ==
* Added a new atmospheric model NRLMSIS 2.0, in addition from the existing NRLMSIS 1.0 model. The solar flux and geomagnetic activity inputs are the same for both versions of the MSIS models. Note that the FORTRAN reference model excludes the NO (Nitric Oxide) element. The same applies to the implemented model in PATRIUS, as it is based on the reference model. Other elements (He, O, N2, etc.), as well as pressure and temperature, are however taken into account.

* Added to the ThirdBodyAttraction constructors the ability to provide a specific gravity model for the indirect terms. If none is provided, the gravity model already supplied for the third-body attraction calculation is used to compute the indirect terms (backward compatibility). To disable the computation of indirect terms, a gravity model that does not include harmonics must be provided.
* Added a service to the ApparentRadiusProvider interface to calculate the maximum apparent radius of a body as seen by a satellite. This radius, expressed in meters, corresponds to the maximum distance from the body's center to any point on its surface belonging to the limb ellipse (contour ellipse) viewed by the satellite.
* Added new constructors to the ModelFunction class to enable the optimization of various function types: ℝⁿ → ℝ : MultivariateFunction, ℝ → ℝ : UnivariateFunction and ℝ → ℝⁿ : UnivariateVectorFunction.
* Added support of the method StrictLegsSequence#addAll
* Added systematic acceleration calculation in BSP ephemerides (previously not calculated at all) via Chebyshev polynomial expansion. No regression expected on positions and velocities.
* Added a class SafetyMarginDetector to detect escape limits crossings. User can choose between two methods to compute escape limit: either at the satellite position or at the orbit’s pericenter.
* New AstronomicalNightDetector detector allowing to find for astronomical dawn and dusk events (independent of the actual spacecraft state).
* Improved matrix toString display: Systematic display of row x column dimensions and large/small numbers are shown in scientific notation without numerical approximation for computing formats (JAVA, OCTAVE, SCILAB and NUMPY).
* Added support for the Alpha-5 TLE numbering format, extending the range of supported satellite catalog numbers from [0; 99,999] to [0; 339,999].
* Fixed excessive memory consumption in detectors inheriting from <code>AbstractSignalPropagationDetector</code>. This issue occurred when detecting a large number of events, particularly during long propagation analyses. Implementing date caching, fully transparent to the user, resolves this issue.

== Bugs fixes ==
* In BSPEphemerisLoader, fix the TDB offset extraction by applying a “/ 1000” conversion, fix an error message that could lead to an infinite loop, update the getTDBModel() method so it can be called directly without having to call before the loadCelestialBodyEphemeris method.
* Fix the method FacetBodyShape#getIntersectionPoint which was using a line defined in the wrong coordinate system to compute the closest triangles.
* Fix for reading .bsp files when the binary file format is not declared at the correct index (more robust DafHandleManager method).
* Correction in the AbstractEllipsoidBodyShape#getApparentRadiusDirection method: using the observer's PVCoordinatesProvider instead of the body's (this) as the origin for the first direction vector. This incorrect behavior had an impact when the input direction depended on the observer's trajectory (for example, with a VelocityDirection linked to the observing satellite).
* Added a cache system to store and manage the “other dates” in AbstractSignalPropagationDetector instead of storing them indefinitely in a Map, which could cause large memory consumption during long propagations.
* Added validation checks during orbital parameter construction to prevent the creation of physically inconsistent ApsisOrbit, EquatorialOrbit, or KeplerianOrbit objects:
** KeplerianParameters / EquatorialParameters: the condition “e >= 0” must be satisfied
** ApsisAltitudeParameters / ApsisRadiusParameters: the condition “periapsis > 0” must be satisfied
* Fixed an issue related to the static initialization of certain dates from the TDB time scale (which is user-configurable). These dates are now dynamically initialized within the constructors of the affected classes: <code>UserIAUPole</code>, <code>BSPEphemerisLoader</code>, and <code>PosVelChebyshev</code>. As a result, the user must configure the desired TDB scale before instantiating these classes.
* Fixed an error message returned by orbital parameters that could indicate an incorrect class name.
* Fixed the nomenclature of the VacuumSignalPropagationModel.ConvergenceAlgorithm.FIXE_POINT enum, which has been renamed to FIXED_POINT.

Main differences between V4.18 and V4.17

2026-06-10T13:17:43Z

Admin tsn :

Main differences between V4.18 and V4.17

2026-06-10T13:02:38Z

Admin tsn :

'''PATRIUS''' V4.18 is a major release adding some new features and correcting some bugs.

== New functionalities ==
* Added a new atmospheric model NRLMSIS 2.0, in addition from the existing NRLMSIS 1.0 model. The solar flux and geomagnetic activity inputs are the same for both versions of the MSIS models. Note that the FORTRAN reference model excludes the NO (Nitric Oxide) element. The same applies to the implemented model in PATRIUS, as it is based on the reference model. Other elements (He, O, N2, etc.), as well as pressure and temperature, are however taken into account.

* Added to the ThirdBodyAttraction constructors the ability to provide a specific gravity model for the indirect terms. If none is provided, the gravity model already supplied for the third-body attraction calculation is used to compute the indirect terms (backward compatibility). To disable the computation of indirect terms, a gravity model that does not include harmonics must be provided.
* Added a service to the ApparentRadiusProvider interface to calculate the maximum apparent radius of a body as seen by a satellite. This radius, expressed in meters, corresponds to the maximum distance from the body's center to any point on its surface belonging to the limb ellipse (contour ellipse) viewed by the satellite.
* Added new constructors to the ModelFunction class to enable the optimization of various function types: ℝⁿ → ℝ : MultivariateFunction, ℝ → ℝ : UnivariateFunction and ℝ → ℝⁿ : UnivariateVectorFunction.
* Added support of the method StrictLegsSequence#addAll
* Added systematic acceleration calculation in BSP ephemerides (previously not calculated at all) via Chebyshev polynomial expansion. No regression expected on positions and velocities.
* Added a class SafetyMarginDetector to detect escape limits crossings. User can choose between two methods to compute escape limit: either at the satellite position or at the orbit’s pericenter.
* Allows the user to configure the desired TDB time scale prior to instantiating UserIAUPole, BSPEphemerisLoader, and PosVelChebyshev objects. Dates are initialized within their respective constructors based on this TDB scale, rather than being handled in a static way.
* New AstronomicalNightDetector detector allowing to find for astronomical dawn and dusk events (independent of the actual spacecraft state).
* Improved matrix toString display: Systematic display of row x column dimensions and large/small numbers are shown in scientific notation without numerical approximation for computing formats (JAVA, OCTAVE, SCILAB and NUMPY).
* Added support for the Alpha-5 TLE numbering format, extending the range of supported satellite catalog numbers from [0; 99,999] to [0; 339,999].
* Fixed excessive memory consumption in detectors inheriting from <code>AbstractSignalPropagationDetector</code>. This issue occurred when detecting a large number of events, particularly during long propagation analyses. Implementing date caching, fully transparent to the user, resolves this issue.

== Bugs fixes ==
* In BSPEphemerisLoader, fix the TDB offset extraction by applying a “/ 1000” conversion, fix an error message that could lead to an infinite loop, update the getTDBModel() method so it can be called directly without having to call before the loadCelestialBodyEphemeris method.
* Fix the method FacetBodyShape#getIntersectionPoint which was using a line defined in the wrong coordinate system to compute the closest triangles.
* Fix for reading .bsp files when the binary file format is not declared at the correct index (more robust DafHandleManager method).
* Correction in the AbstractEllipsoidBodyShape#getApparentRadiusDirection method: using the observer's PVCoordinatesProvider instead of the body's (this) as the origin for the first direction vector. This incorrect behavior had an impact when the input direction depended on the observer's trajectory (for example, with a VelocityDirection linked to the observing satellite).
* Added a cache system to store and manage the “other dates” in AbstractSignalPropagationDetector instead of storing them indefinitely in a Map, which could cause large memory consumption during long propagations.
* Added validation checks during orbital parameter construction to prevent the creation of physically inconsistent ApsisOrbit, EquatorialOrbit, or KeplerianOrbit objects.
** KeplerianParameters / EquatorialParameters: the condition “e >= 0” must be satisfied
** ApsisAltitudeParameters / ApsisRadiusParameters: the condition “periapsis > 0” must be satisfied

Catégorie:Tutorials 4.18

2026-06-10T11:02:12Z

Admin tsn : Page créée avec « [https://github.com/CNES/patrius-tutorials/tree/patrius-4.18 Tutorials PATRIUS 4.18] The tutorials for PATRIUS v4.18 can now be found on the [https://github.com/CNES/patrius-tutorials/tree/patrius-4.18 CNES' GitHub page] »

[https://github.com/CNES/patrius-tutorials/tree/patrius-4.18 Tutorials PATRIUS 4.18]

The tutorials for PATRIUS v4.18 can now be found on the [https://github.com/CNES/patrius-tutorials/tree/patrius-4.18 CNES' GitHub page]

Catégorie:Tutorials 4.17

2026-06-10T11:01:28Z

Admin tsn : Page créée avec « [https://github.com/CNES/patrius-tutorials/tree/patrius-4.17 Tutorials PATRIUS 4.17] The tutorials for PATRIUS v4.17 can now be found on the [https://github.com/CNES/patrius-tutorials/tree/patrius-4.17 CNES' GitHub page] »

[https://github.com/CNES/patrius-tutorials/tree/patrius-4.17 Tutorials PATRIUS 4.17]

The tutorials for PATRIUS v4.17 can now be found on the [https://github.com/CNES/patrius-tutorials/tree/patrius-4.17 CNES' GitHub page]

User Manual 4.18 Events: orbital

2026-06-10T10:59:55Z

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.18}}/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).

==== Safety Margin Detector ====

This detector computes the safety margin ∆ with respect to the escape velocity. Users have the choice between two methods for the safety margin computation:
* INSTANTANEOUS: The safety margin is computed using the spacecraft's current velocity v and the escape velocity v_esc evaluated at the satellite's current position (v_esc=√(2μ/r)): ∆ = v/v_esc-1
* PERICENTRE: The safety margin is computed at the orbit's pericenter (where the satellite speed is maximum) using the orbital eccentricity e: ∆ = √((1+e)/2)-1

Note: For circular orbits (e=0 and v=√(μ/r)), both methods are equivalent and yield ∆ = 1/√2-1.

The g switching function is the difference between the computed safety margin ∆ and a user-defined safety margin threshold t (safetyMarginIn): g = ∆-t

==== 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]]'''AstronomicalNightDetector'''

The AstronomicalNightDetector detects when the Sun's elevation reaches a predetermined threshold, specifically designed to identify astronomical dawn and dusk events.

Astronomical night is defined as the period when the Sun is more than 18 degrees below the horizon (elevation ≤ -18°). At this stage, the sky is dark enough for all astronomical observations; no scattered sunlight illuminates the atmosphere.

This detector is independent of the actual spacecraft state, as it evaluates the Sun's position relative to a specific TopocentricFrame (e.g., a ground station or a specific terrestrial location).

The switching function measures the difference between the threshold angle and the current solar elevation: ''g = duskAngle – elevation''

The function is positive at night (when the Sun's elevation is lower than the ) and negative during the day or twilight.
[[Fichier:Twilight is the period between dawn and sunrise, and between sunset and dusk.png|alt=Twilight is the period between dawn and sunrise, and between sunset and dusk, Source: Twilight - Wikipedia|centré|sans_cadre]]
''Twilight is the period between dawn and sunrise, and between sunset and dusk, Source: [[wikipedia:Twilight|Twilight - Wikipedia]]''

By default, the is set to -18° by default, but this value can be customized in the constructor to detect other types of twilight (e.g., civil at -6° or nautical at -12°).

====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.18}}/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.18}}/fr/cnes/sirius/patrius/events/detectors/AlignmentDetector.html AlignmentDetector]
|-
|AltitudeDetector
|This class handles satellite altitude crossing events.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/events/detectors/AltitudeDetector.html AltitudeDetector]
|-
|ApsideDetector
|This class handles satellite apogee and perigee crossing events.
| [{{JavaDoc4.18}}/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.18}}<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.18}}<nowiki>/fr/cnes/sirius/patrius/events/detectors/BodyPointLocalTimeAngleDetector.html BodyPointLocalTimeAngleDetector]</nowiki>
|-
|DateDetector
|This class handles the occurrence of predefined dates.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/events/detectors/DateDetector.html DateDetector]
|-
|EclipseDetector
|This class handles total or partial eclipse events.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/events/detectors/EclipseDetector.html EclipseDetector]
|-
|NodeDetector
|This class handles satellite equator crossing events.
|[{{JavaDoc4.18}}/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.18}}/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.18}}/fr/cnes/sirius/patrius/events/detectors/ExtremaDistanceDetector.html ExtremaDistanceDetector]
|-
| ExtremaLatitudeDetector
|This class handles events representing the reaching of extrema for the geodetic latitude.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/events/detectors/ExtremaLatitudeDetector.html ExtremaLatitudeDetector]
|-
|ExtremaLongitudeDetector
|This class handles events representing the reaching of extrema for the longitude.
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/events/detectors/LatitudeDetector.html LatitudeDetector]
|-
|LongitudeDetector
|This class handles events representing the reaching of a given longitude
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/events/detectors/LongitudeDetector.html LongitudeDetector]
|-
|AnomalyDetector
|This class handles events representing the reaching of an anomaly angle.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/events/detectors/AnomalyDetector.html AnomalyDetector]
|-
|SafetyMarginDetector
| This class handles escape velocity crossing detection.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/events/detectors/SafetyMarginDetector.html SafetyMarginDetector]|-
|-
|AOLDetector
| This class handles events representing the reaching of an argument of latitude value.
|[{{JavaDoc4.18}}/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.18}}/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.18}}/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.18}}/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.18}}/fr/cnes/sirius/patrius/events/detectors/LocalTimeAngleDetector.html LocalTimeAngleDetector]
|-
|AstronomicalNightDetector
|This class handles astronomical dawn and dusk events (independent of the actual spacecraft state).
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/events/detectors/AstronomicalNightDetector.html AstronomicalNightDetector]
|-
|SolarTimeAngleDetector
|This class handles events representing the reaching of a predetermined spacecraft solar time angle.
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/events/detectors/NadirSolarIncidenceDetector.html NadirSolarIncidenceDetector]
|-
|EarthZoneDetector
|This class handles events representing the entering and leaving of earth zones.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/events/detectors/EarthZoneDetector.html EarthZoneDetector]
|-
|}
[[Category:User Manual 4.18 Mission]]

Fichier:Twilight is the period between dawn and sunrise, and between sunset and dusk.png

2026-06-10T10:53:40Z

Admin tsn :

Twilight is the period between dawn and sunrise, and between sunset and dusk

User Manual 4.18 Celestial bodies

2026-06-10T10:48:39Z

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.18}}/fr/cnes/sirius/patrius/bodies/package-summary.html Package fr.cnes.sirius.patrius.bodies]
|-
|Patrius
|[{{JavaDoc4.18}}/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.18}}/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.
* Compute the maximum apparent radius of the body as seen by the spacecraft position. This radius, expressed in meters, corresponds to the maximum distance from the body's center to any point on its surface belonging to the limb ellipse (contour ellipse) viewed by the spacecraft.
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>getMaximumApparentRadius</code> method is not supported by this class (throw an UnsupportedOperationException) as the determination of a contour ellipse won't be possible on this body shape that can define any shape.
* <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.18}}/fr/cnes/sirius/patrius/bodies/ApparentRadiusProvider.html ...]
|-
|'''BodyShape'''
|Interface representing the rigid surface shape of a natural body.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/bodies/BodyShape.html ...]
|-
|'''CelestialBody'''
|Interface for celestial bodies like Sun, Moon or solar system planets.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/bodies/CelestialBody.html ...]
|-
|'''CelestialBodyEphemeris'''
|Interface for celestial body ephemeris like Sun, Moon or solar system planets.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/bodies/CelestialBodyEphemeris.html ...]
|-
|'''CelestialBodyLoader'''
|Interface for celestial body loaders.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/bodies/CelestialBodyLoader.html ...]
|-
|'''CelestialBodyEphemerisLoader'''
|Interface for celestial body ephemeris loaders.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/bodies/CelestialBodyEphemerisLoader.html ...]
|-
|'''MeshLoader'''
|Interface for FacetCelestialBody mesh provider.
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/bodies/CelestialBodyFactory.html ...]
|-
|'''BodyPoint'''
|Point location relative to a 2D body surface.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/bodies/GeodeticPoint.html ...]
|-
|'''JPLCelestialBodyLoader'''
|Loader for JPL ephemerides binary files (DE 405, DE 406, ...).
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/bodies/JPLCelestialBodyLoader.html ...]
|-
|'''OneAxisEllipsoid'''
|Modeling of a one-axis ellipsoid.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/bodies/OneAxisEllipsoid.html ...]
|-
|'''ThreeAxisEllipsoid'''
|Modeling of a tri-axis ellipsoid.
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/bodies/MeeusSun.html ...]
|-
|'''MeeusMoon'''
|Position of the Moon according to Meeus model.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/bodies/MeeusMoon.html ...]
|-
|'''BasicBoardSun'''
|Direction of the Sun according to a basic board Sun model.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/bodies/BasicBoardSun.html ...]
|-
|'''UserCelestialBody'''
|User-defined celestial body
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/bodies/UserCelestialBody.html ...]
|-
|'''UserIAUPole'''
|User-defined IAU pole motion
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/bodies/UserIAUPole.html ...]
|-
|'''IAUPoleFactory'''
|Factory for retrieval of solar system bodies IAU pole data
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/bodies/IAUPoleFactory.html ...]
|-
|'''IAUPoleFunction'''
|Atomic IAU pole function. IAU pole data is the sum of atomic IAUPoleFunction.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/bodies/IAUPoleFunction.html ...]
|-
|'''FacetBodyShape'''
|Celestial body defined by a mesh.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/bodies/mesh/FacetBodyShape.html ...]
|-
|'''BodyShapeFitter'''
|Fitter for a given body shape provided as input.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/bodies/mesh/BodyShapeFitter.html ...]
|-
|'''Triangle'''
|Unitary facet (triangle) for a FacetCelestialBody.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/bodies/mesh/Triangle.html ...]
|-
|'''ObjMeshLoader'''
|.obj 3D file mesh loader.
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/bodies/mesh/GeodeticMeshLoader.html ...]
|}

[[Category:User_Manual_4.18_Flight_Dynamics]]

User Manual 4.18 Environment Models

2026-06-10T10:43:59Z

Admin tsn :

== Introduction ==
=== Scope ===
The scope of this section is to present the physical models available through the Patrius library.

=== Javadoc ===
All the classes related to physical models are in the <code>fr.cnes.sirius.patrius.forces</code> and <code>fr.cnes.sirius.patrius.math.parameter</code>packages. The classes related to reading potential files are in the package <code>fr.cnes.sirius.patrius.forces.gravity.potential</code>.

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
|Patrius
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/package-summary.html Package fr.cnes.sirius.patrius.forces.atmospheres]
|-
|Patrius
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/package-summary.html Package fr.cnes.sirius.patrius.forces.atmospheres.solarActivity]
|-
|Patrius
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/specialized/package-summary.html Package fr.cnes.sirius.patrius.forces.atmospheres.solarActivity.specialized]
|-
|Patrius
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/specialized/package-summary.html Package fr.cnes.sirius.patrius.forces.atmospheres.solarActivity.specialized]
|-
|Patrius
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/potential/package-summary.html Package fr.cnes.sirius.patrius.forces.gravity.potential]
|-
|Patrius
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/variations/package-summary.html Package fr.cnes.sirius.patrius.forces.gravity.variations]
|-
|Patrius
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/tides/coefficients/package-summary.html Package fr.cnes.sirius.patrius.forces.gravity.tides.coefficients]
|-
|Patrius
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/models/earth/package-summary.html Package fr.cnes.sirius.patrius.math.parameter]
|-
|Patrius
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/tides/ReferencePointsDisplacement.html Class fr.cnes.sirius.patrius.utils.ReferencePointsDisplacement]
|}

=== Links ===
Some useful links are given hereunder.

'''IERS Page'''
[http://www.iers.org/IERS/EN/Publications/TechnicalNotes/tn36.html IERS Conventions (2010), Technical Note No.36]

'''Project Pages'''

* [http://cddis.nasa.gov/ NASA - Crustal Dynamics Data Information System (CDDIS)]
* [http://op.gfz-potsdam.de/grace/ GFZ - Grace (Gravity Recovery and Climate Experiment) Mission Homepage]
* [http://icgem.gfz-potsdam.de/ICGEM/ GFZ - International Centre for Global Earth Models]
* [http://grgs.obs-mip.fr Groupe de Recherche de Géodésie Spatiale]

'''Results Pages'''

* ''EGM96: The NASA GSFC and NIMA Joint Geopotential Model'', Lemoine; F. G., Kenyon; S. C., Factor; J. K., Trimmer; R.G., Pavlis; N. K., Chinn; D. S., Cox; C. M., Klosko; S. M., Luthcke; S. B., Torrence; M. H., Wang; Y. M., Williamson; R. G., Pavlis; E. C., Rapp; R. H., Olson; T. R., NASA Goddard Space Flight Center, Greenbelt, Maryland, 20771 USA, July 1998, Available [http://cddis.nasa.gov/926/egm96/egm96.html here].
* ''GFZ : Global Gravity Field Models'', Available [http://icgem.gfz-potsdam.de/ICGEM/modelstab.html here].

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

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

== Features Description ==
=== Earth Potential Models ===

The <code>fr.cnes.sirius.patrius.forces.gravity.potential</code> package provides tools allowing the user to read external gravity potential data files. The following file formats are supported :

* EGM96 ASCII format data
* EIGEN-GRACE format
* ICGEM format
* GRGS format

Below is a diagram showing the architecture of the <code>fr.cnes.sirius.patrius.forces.gravity.potential</code> package.

[[File:physicalModels.PNG|center]]

For a detailed explanation of the Data Management System, please refer to the [SUP_DMS_Home Data Management System section] of the Support User Manual.

The <code>fr.cnes.sirius.patrius.forces.gravity.variations</code> package provides tools allowing the user to read external variable gravity potential data files. The corresponding ForceModel is also included in the package. The following file formats are supported :

* GRGS RL02

Below is a diagram showing the architecture of the <code>fr.cnes.sirius.patrius.forces.gravity.variations</code> package.

[[File:varPOT.PNG|center]]

By default, some loaders are added to <code>VariableGravityFieldFactory</code> in the following order:
*<code>GRGSRL02FormatReader</code>: GRGSR L02 file format
There is no included data in PATRIUS by default
Once loaded, data are stored in static variables and are used for variable gravity field computation.

=== Atmosphere models and solar activity model ===
==== Generalities about Solar Activity and Atmospheres ====

The atmospheres make use of solar activity in order to compute the density at the given user location excepted US76 model that is only based on altitude parameters. The PATRIUS architecture of atmospheres and solar activity is divided into three layers :

*'''Atmospheres use solar data in specific ways'''
Each atmosphere model uses the solar data in a specific way (more simply, US76 doesn't use solar data). These representations are enclosed in the atmosphere model specific interfaces, such as [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/forces/atmospheres/DTMInputParameters.html DTMInputParamters]. Atmosphere models available include US76 (for low altitudes in range 0 to 1000km), DTM2000, DTM2012 and MSISE2000.
*'''Reading and storing solar data'''
The way to store the solar data is enclosed in the [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/SolarActivityDataProvider.html SolarActivityDataProvider interface]. It defines the basic coefficients (Ap, Kp and F10.7 cm) that any solar activity data provider class should be able to return, in order to be compatible with the atmosphere specific implementations (see next point). The [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/package-summary.html solarActivity package] contains classes that can read different file formats and can return the solar activity data. So far, one class for each of the ACSOL and NOAA formats has been implemented. Additionally, one class representing constant solar activity (that requires no external file) has been implemented.
*'''Using the solar data in an adequate fashion'''
Making effective use of the solar data for specific atmospheres requires an object that provides solar data (implementing the [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/SolarActivityDataProvider.html SolarActivityDataProvider]) and answers to the interfaces that define the ways in which the atmosphere models use this data (e.g. implementing [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/forces/atmospheres/DTM2000InputParameters.html DTMInputParameters]). These classes are contained in the [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/specialized/package-summary.html fr.cnes.sirius.patrius.forces.atmospheres.solarActivity.specialized package]). So far, one class for each of the DTM2000/DTM2012 and MSISE2000 models have been implemented.

The <code>fr.cnes.sirius.patrius.forces.atmospheres.solarActivity</code> package follows the same architecture as the <code>fr.cnes.sirius.patrius.forces.gravity.potential</code> package. The user must use the [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/SolarActivityDataFactory.html SolarActivityDataFactory class].

For a detailed explanation of the Data Management System, please refer to the [SUP_DMS_Home Data Management System section] of the Support User Manual.

For performances reasons, numerical propagator checks availability of solar activity data at start of propagation and not at every solar activity data call. If required solar activity or geomagnetic activity does not cover the required range by the atmospheric model, an exception is returned.

==== Atmospheric models ====

Various models are available in PATRIUS: DTM-2000, DTM-2012, MSIS-00, US76, etc. all models inherit the <code>Atmosphere</code> interface providing total density information. 
DTM and MSIS models also implement the <code>ExtendedAtmosphere</code> interface which provides more detailed data such as temperature and partial densities of atmosphere constituents. 
Some models require solar and geomagnetic information (see below for how to provide solar and geomagnetic data).

===== MSIS2000 Atmosphere model =====

The NRLMSIS series represents the gold standard for empirical neutral atmosphere models, used to predict temperature, density, and composition from the ground to the exosphere. The transition from NRLMSISE-00 (released in 2013) to NRLMSIS 2.0 (released in 2020) marks a significant leap in modeling accuracy and architectural design. PATRIUS implements both models.

Key Differences

* NRLMSISE00 (or NRLMSIS 1.0):
** Relies on older mass spectrometer and incoherent scatter radar data. While robust, it often overestimates densities during extreme solar minimums and struggles with the precise "satellite drag" modeling required for modern space situational awareness.
** Models the primary species (He, O, N2, O, Ar, H, N) and includes an "anomalous oxygen" component to account for satellite drag discrepancies.

* NRLMSISE20 (or NRLMSIS 2.0):
** Incorporates decades of new data, including extensive satellite accelerometer measurements and improved occultation data. It is significantly more accurate in the thermosphere and exosphere, particularly during low solar activity.
** Introduces a more rigorous treatment of atomic species. Notably, it includes Atomic Nitrogen (N) and Nitric Oxide (NO) as intrinsic parts of the model (though, as you noted in your previous translation, some implementations may still exclude NO depending on the reference version used). It also ensures better mass-density consistency.
** Version 2.0 enforces stricter physical constraints between temperature and density profiles, ensuring that the transition between the lower atmosphere and the thermosphere is physically smoother.

Note that a new model NRLMSIS 2.1 has been presented in 2025. This model is not implemented yet in PATRIUS.

More information can be found at the [http://www.nrl.navy.mil/research/nrl-review/2003/atmospheric-science/picone/ Naval Research Laboratory website] and [https://map.nrl.navy.mil/map/pub/nrl/NRLMSIS/ Geospace Science & Technology Branch]. Note that several adaptations have been made to optimize the JAVA model compare to these FORTRAN models.

In order to use this atmosphere model, the user must proceed by giving the following arguments as inputs to the [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/forces/atmospheres/MSISE2000.html MSISE2000] class :

* The empirical atmosphere model it self (NRLMSISE00 or NRLMSISE20)
* Solar activity data (as a [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/forces/atmospheres/MSISE2000InputParameters.html MSISE2000InputParameters])
* the Earth model (as a [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/bodies/BodyShape.html BodyShape])
* the Sun model (as a [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/bodies/CelestialBody.html CelestialBody])

The following code snippet creates an instance of MSISE2000 :

<syntaxhighlight lang="java">
// Create an instance of the BodyShape "EARTH", with user chosen
// equatorial radius, flattening and body frame
Frame frame = FramesFactory.getITRF();
double f = 0.29825765000000E+03;
double ae = 6378136.46;
BodyShape earth = new OneAxisEllipsoid(ae, 1 / f, frame);

// Get the instance of the CelestialBody "SUN"
CelestialBody sun = CelestialBodyFactory.getSun();

// Create the solar activity data to be used
SolarActivityDataProvider solarActivity = SolarActivityDataFactory.getSolarActivityDataProvider();
final MSISE2000InputParameters msiseData = new ClassicalMSISE2000SolarData(solarActivity);

// Create an instance of the atmosphere model
Atmosphere atmosModel = new MSISE2000(new NRLMSISE00(), msiseData , earth, sun);
</syntaxhighlight>

Warning: the NRLMSISE-00 model is not continuous. There is a discontinuity every day (at 0h in UTC time scale). Discontinuities are however very small (1E-3 on a relative scale).

The main difference in usage between the models NRLMSISE-00 and NRLMSIS 2.0 is that :

* NRLMSISE-00 uses a “Flags” container to define the model’s specific settings every time we call the gtd7d(Input, Flags) method
* NRLMSIS 2.0 doesn’t use the “Flags” container when calling the gtd7d(Input, Flags). Instead, the model is configured once in its constructor by providing a specific MSISInit instance.

==== Solar and geomagnetic activity ====

Solar and geomagnetic activity can be provided in various ways:
* Constant solar activity using: <syntaxhighlight lang="java">final SolarActivityDataProvider constantSolarActivity = new ConstantSolarActivity(140, 15);</syntaxhighlight>
* Variable solar activity using (for instance):
<syntaxhighlight lang="java">
final SolarActivityDataProvider variableSolarActivity = new NOAAFormatReader(...);
final SolarActivityDataProvider otherVariableSolarActivity = new ACSOLFormatReader(...);
</syntaxhighlight>

Solar and geomagnetic activity data often having a limited timespan, the class <code>ExtendedSolarActivityWrapper</code> allows data extension with constant values. Solar and geomagnetic data returned before timespan are equals to an average of first available data (the average duration being user-chosen). Solar and geomagnetic data returned after timespan are equals to an average of last available data (the average duration being user-chosen). Example:

<syntaxhighlight lang="java">
final SolarActivityDataProvider innerProvider = new NOAAFormatReader() // Variable solar activity over a given timespan
final double duration = 86400; // Duration on which average solar activity will be computed if date out of innerProvider timespan
final ExtendedSolarActivityWrapper solarActivity = new ExtendedSolarActivityWrapper(innerProvider, duration)// Extended solar activity
</syntaxhighlight>

The above code will create an solar activity whose value will be:
* Value of innerProvider if date is within innerProvider timespan
* Average value on [lower boundary, lower boundary + duration] if date is before innerProvider lower boundary
* Average value on [upper boundary- duration, upper boundary] if date is after innerProvider upperboundary

These providers are used as inputs of atmospheric models.

===== Reading Solar Activity Data files =====

The data is read through the <code>DataLoader</code> infrastructure; it provides several ways to load solar activity data. Please see the [SUP_DMS_Home Data Management System section] for more information.

The following file formats are supported by PATRIUS:
* ACSOL format
* NOAA format

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

<syntaxhighlight lang="java">
//Directory containing the file ACSOL.act
final File potdir = new File("/my/data/solar");
//The directory is given to the data loader
DataProvidersManager.getInstance().addProvider(new DirectoryCrawler(potdir));
//The ACSOL file is registered in the SolarActivityDataFactory
//If it is the only solar activity file of the directory, this step is not necessary
SolarActivityDataFactory.addSolarActivityDataReader(new ACSOLFormatReader("ACSOL.act"));
//A provider for the data is created
final SolarActivityDataProvider provider = SolarActivityDataFactory.getSolarActivityDataProvider();
//Get the ap, kp and instant flux at date
final AbsoluteDate userDate = new AbsoluteDate();
final double ap = provider.getAp( userDate );
final double kp = provider.getKp( userDate );
final double f = provider.getInstantFluxValue( userDate );
</syntaxhighlight>

By default, some loaders are added to <code>SolarActivityDataFactory</code> in the following order:
*<code>ACSOLFormatReader</code>: ACSOL file format
*<code>NOAAFormatReader</code>: NOAA file format
There is no included data in PATRIUS by default
Once loaded, data are stored in static variables and are used for solar activity retrieval.

=== Tides models ===
==== Tides model for force computation ====

The PATRIUS <code>fr.cnes.sirius.patrius.forces.gravity.tides</code> package provides tools allowing the user to use Terestrial and Ocean tides. The <code>fr.cnes.sirius.patrius.forces.gravity.tides.coefficients</code> package also allows reading external ocean tides coefficients data files. The following file formats are supported by PATRIUS:
* FES2004 format

By default, some loaders are added to <code>OceanTidesCoefficientFactory</code> in the following order:
*<code>FES2004FormatReader</code>: FES 2004 file format
There is no included data in PATRIUS by default
Once loaded, data are stored in static variables and are used for ocean tides computation.

==== Reference point displacement ====

The PATRIUS <code>fr.cnes.sirius.patrius.utils.ReferencePointsDisplacement</code> class provides a model describing the displacement of reference points due to the effect of the solid Earth tides. The computation is performed by the static method '''solidEarthTidesCorrections(AbsoluteDate, Vector3D, Vector3D, Vector3D)'''. The implemented model has been validated by comparison with tests available in the IERS website. The example below shows the user how to compute displacements of reference points:

<syntaxhighlight lang="java">
// Test from source ftp://tai.bipm.org/iers/convupdt/chapter7/dehanttideinel/DEHANTTIDEINEL.F

// date : 13/04/2009
final AbsoluteDate date = new AbsoluteDate(2009, 4, 13, 0, 0, 0., TimeScalesFactory.getUTC());

// entries : moon position, sun position, station location
final Vector3D moon = new Vector3D(-179996231.920342,-312468450.131567, -169288918.592160);
final Vector3D sun = new Vector3D(137859926952.015, 54228127881.4350, 23509422341.6960);
final Vector3D point = new Vector3D(4075578.385, 931852.890, 4801570.154);

// compute the displacement
final Vector3D disp = ReferencePointsDisplacement.solidEarthTidesCorrections(date, point, sun, moon);

// comparison with reference results (IERS)
Assert.assertEquals(0.07700420357108125891, disp.getX(), Precision.EPSILON);
Assert.assertEquals(0.06304056321824967613, disp.getY(), Precision.EPSILON);
Assert.assertEquals(0.05516568152597246810, disp.getZ(), Precision.EPSILON);
</syntaxhighlight>

=== Geomagnetic models ===
==== Design ====

The <code>fr.cnes.sirius.patrius.models.earth</code> package provides tools allowing the user to use different geomagnetic models. For the moment, there are only the two following models available :
* IGRF 11 : International Geomagnetic Reference Field eleventh generation
* WMM 2010 : World Magnetic Model published in december 2009

A class diagram is given hereunder to show how geomagnetic is read and used in the library :

[[File:geomaguml.png]]

The user can create its own [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/models/earth/GeoMagneticModelReader.html GeoMagneticModelReader] in order to provide [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/models/earth/GeoMagneticField.html GeoMagneticField] from any file format.

By default, some loaders are added to <code>GeoMagneticFieldFactory</code> in the following order:
*<code>COFFileFormatReader</code>: COF file format
There is no included data in PATRIUS by default
Once loaded, data are stored in static variables and are used for geomagnetic field computation (IGRF and WMM).

==== IGRF 11 geomagnetic model ====

The International Geomagnetic Reference Field (IGRF) was introduced by the International Association of Geomagnetism and Aeronomy (IAGA) in 1968 in response to the demand for a standard spherical harmonic representation of the Earth's main field. The model is updated at 5-yearly intervals, the latest being the 11th generation, produced and released by IAGA Working Group V-MOD (formerly V-8) December 2009.

More information can be found at the [http://www.ngdc.noaa.gov/IAGA/vmod/index.html IAGA Division V-Mod].

==== WMM 2010 geomagnetic model ====

The World Magnetic Model is a joint product of the United States’ National Geospatial-Intelligence Agency (NGA) and the United Kingdom’s Defence Geographic Centre (DGC). The WMM was developed jointly by the National Geophysical Data Center (NGDC, Boulder CO, USA) and the British Geological Survey (BGS, Edinburgh, Scotland).

The World Magnetic Model is the standard model used by the U.S. Department of Defense, the U.K. Ministry of Defence, the North Atlantic Treaty Organization (NATO) and the International Hydrographic Organization (IHO), for navigation, attitude and heading referencing systems using the geomagnetic field. It is also used widely in civilian navigation and heading systems. The model, associated software, and documentation are distributed by NGDC on behalf of NGA. The model is produced at 5-year intervals, with the current model expiring on December 31, 2014.

The current model, WMM2010 (published 12/2009)

More information can be found at the [http://www.ngdc.noaa.gov/geomag/WMM/DoDWMM.shtml National Oceanic and Atmospheric Administration].

==== Details, limitation and precautions ====

In the geomagnetic field's computation from the different models, to convert geodetic coordinates (defined by the WGS-84 reference ellipsoid) to Earth Centered spherical coordinates, the following constants are used :

* Semi major-axis of WGS-84 ellipsoid : 6378.137 km
* The first eccentricity squared : 0.0066943799901413169961

and to compute the spherical harmonic variables for a given spherical coordinate uses the mean radius of IAU-66 ellipsoid 6371.2 km is used.

The different models are used to compute gemoagnetic field near earth surface. In the model file, the given altitude range of validity is-1 to 600 km even if we can compute field outside of this range.

The method GeoMagneticField.calculateField(final Vector3D point,final Frame frame, final AbsoluteDate date) has been added to Patrius and allows to compute the field from a position vector in a specific frame and at a specific date. This method is based on tranformModel method which recomputes the field at a date. This method doesn't work if the model doesn't support time transform. In this way, this method added to Patrius throws a Patrius exception about model not supporting time transform.

Here is the list of all possible actual models and the time transform support (please note that only dates prior to 2010 won't support time transformation) :

{| class="wikitable"
| Model and associated data file
| Model Name
| Validity Period
| Time transform support
|-
| rowspan="23"|IGRF (''GeoMagneticFieldFactory.getIGRF(..)'' uses IGRF.COF)
| IGRF00
| 1900.0 - 1905.0
| false
|-
| IGRF05
| 1905.0 - 1910.0
| false
|-
| IGRF10
| 1910.0 - 1915.0
| false
|-
|IGRF15
| 1915.0 - 1920.0
| false
|-
|IGRF20
| 1920.0 - 1925.0
| false
|-
|IGRF25
| 1925.0 - 1930.0
| false
|-
|IGRF30
| 1930.0 - 1935.0
| false
|-
|IGRF35
| 1935.0 - 1940.0
| false
|-
|IGRF40
| 1940.0 - 1945.0
| false
|-
|DGRF45
| 1945.0 - 1950.0
| false
|-
|DGRF50
| 1950.0 - 1955.0
| false
|-
|DGRF55
| 1955.0 - 1960.0
| false
|-
|DGRF60
| 1960.0 - 1965.0
| false
|-
|DGRF65
| 1965.0 - 1970.0
| false
|-
|DGRF70
| 1970.0 - 1975.0
| false
|-
|DGRF75
| 1975.0 - 1980.0
| false
|-
|DGRF80
| 1980.0 - 1985.0
| false
|-
|DGRF85
| 1985.0 - 1990.0
| false
|-
|DGRF90
| 1990.0 - 1995.0
| false
|-
|DGRF95
| 1995.0 - 2000.0
| false
|-
|DGRF2000
| 2000.0 - 2005.0
| false
|-
|DGRF2005
| 2005.0 - 2010.0
| false
|-
|IGRF2010
| 2010.0 - 2015.0
| true
|-
| rowspan="1"|WMM (''GeoMagneticFieldFactory.getWMM(..)'' uses WMM.COF)
| WMM2010
| 2010.0 - 2015.0
| true
|}

Precautions :
The method GeoMagneticField.calculateField (final double latitude, final double longitude, final double height) doesn't use SI units. Latitude and longitude are given in degrees, and height is given in kilometers.

== Getting Started ==

==== Code Example ====

The following code sample computes geomagnetic field elements for four (date, position) of a fake trajectory :

<syntaxhighlight lang="java">
public void codeExemple() throws PatriusException {

Utils.setDataRoot("earth");
FramesFactory.setConfiguration(Utils.getIERS2003ConfigurationWOEOP(true));

//Fake trajectory : list of date and list of position
List<AbsoluteDate> dateList = new ArrayList<AbsoluteDate>();
AbsoluteDate initDate = new AbsoluteDate(2010, 1, 1, 12, 0, 0.0, TimeScalesFactory.getTT());

dateList.add(initDate);
dateList.add(new AbsoluteDate(initDate, 600));
dateList.add(new AbsoluteDate(initDate, 1200));
dateList.add(new AbsoluteDate(initDate, 1800));

List<Vector3D> positionList = new ArrayList<Vector3D>();
positionList.add(new Vector3D(6.46885878304673824e+06,-1.88050918456274318e+06, -1.32931592294715829e+04));
positionList.add(new Vector3D(6.58239141552595049e+06,-1.43349476017528563e+06, -1.39460373997706010e+04));
positionList.add(new Vector3D(6.66499609614125639e+06,-9.79745192516532145e+05, -1.45334684008149434e+04));
positionList.add(new Vector3D(6.71628402448997274e+06,-5.21392324304617418e+05, -1.50526405214286660e+04));

// Get the model to the initial date
final GeoMagneticField model = GeoMagneticFieldFactory.getIGRF(dateList.get(0));

// For each date and position, compute the GeoMagneticElement and add it to a list
List<GeoMagneticElements> geoMagList = new ArrayList<GeoMagneticElements>();
int i = 0;
for (AbsoluteDate date : dateList){
geoMagList.add(model.calculateField(positionList.get(i), FramesFactory.getEME2000(), date));
}

// Print each field vector B
for (GeoMagneticElements geoMagElement : geoMagList){
System.out.println(geoMagElement.toString());
}
}
</syntaxhighlight>

This code produces the following standard output :
<syntaxhighlight lang="java">MagneticField[B={29817,109;-2303,065; -9138,097},H=29905,92,F=31270,895,I=-16,991,D=-4,417]
MagneticField[B={29442,018;-2166,283; -8949,299},H=29521,606,F=30848,261,I=-16,864,D=-4,208]
MagneticField[B={29067,408;-1996,393; -8794,324},H=29135,885,F=30434,19,I=-16,796,D=-3,929]
MagneticField[B={28695,713;-1796,821; -8680,411},H=28751,913,F=30033,681,I=-16,799,D=-3,583]</syntaxhighlight>

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

{| class="wikitable"
|-
! scope="col"| Interface
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''Atmosphere'''
|Interface for atmospheric models.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/Atmosphere.html ...]
|-
|'''ExtendedAtmosphere'''
|Interface for atmospheric models with detailed data.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/ExtendedAtmosphere.html ...]
|-
|'''SolarActivityDataProvider'''
|Interface for solar activity data providers, to be used for atmosphere models
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/SolarActivityDataProvider.html ...]
|-
|'''DTM2000InputParameters'''
|Container for solar activity data, compatible with DTM Atmosphere models.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/DTMInputParameters.html ...]
|-
|'''MSISE2000InputParameters'''
|Container for solar activity data, compatible with MSISE2000 Atmosphere model.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/MSISE2000InputParameters.html ...]
|-
|'''OceanTidesCoefficientsProvider'''
|This interface is used to provide ocean tides coefficients.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/tides/coefficients/OceanTidesCoefficientsProvider.html ...]
|-
|'''PotentialCoefficientsProvider'''
|This interface is used to provide gravity field coefficients.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/potential/PotentialCoefficientsProvider.html ...]
|-
|'''VariablePotentialCoefficientsProvider'''
|This interface is used to provide variable gravity field coefficients.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/variations/coefficients/VariablePotentialCoefficientsProvider.html ...]
|-
|'''RadiationSensitive'''
|This interface is used to provide an direct solar radiative pressure model.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/radiation/RadiationSensitive.html ...]
|-
|'''RediffusedRadiationSensitive'''
|This interface is used to provide an rediffused radiative pressure model.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/radiation/RediffusedRadiationSensitive.html ...]
|-
|'''GeoMagneticDataProvider'''
|This interface is a generic geomagnetic data provider.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/models/earth/GeoMagneticDataProvider.html ...]
|}

=== Classes ===
'''Earth potential'''

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''EGMFormatReader'''
|This reader is adapted to the EGM Format.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/potential/EGMFormatReader.html ...]
|-
|'''GravityFieldFactory'''
|Factory used to read gravity field files in several supported formats. '''Main user access point''' : the simple way of reading a potential file is by using this factory.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/potential/GravityFieldFactory.html ...]
|-
|'''VariableGravityFieldFactory'''
|Factory used to read variable gravity field files in several supported formats. '''Main user access point''' : the simple way of reading a variable potential file is by using this factory.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/variations/coefficients/VariableGravityFieldFactory.html ...]
|-
|'''GRGSFormatReader'''
|Reader for the GRGS gravity field format.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/potential/GRGSFormatReader.html ...]
|-
|'''GRGSRL02FormatReader'''
|Reader for the GRGS RL02 variable gravity field format.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/variations/coefficients/GRGSRL02FormatReader.html ...]
|-
|'''ICGEMFormatReader'''
|Reader for the ICGEM gravity field format.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/potential/ICGEMFormatReader.html ...]
|-
|'''PotentialCoefficientsReader'''
|This abstract class represents a Gravitational Potential Coefficients file reader.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/potential/PotentialCoefficientsReader.html ...]
|-
|'''SHMFormatReader'''
|Reader for the SHM gravity field format.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/potential/SHMFormatReader.html ...]
|}

'''Atmosphere Models'''

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''DTM2000'''
|This class implements the DTM2000 atmospheric model.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/DTM2000.html ...]
|-
|'''DTM2012'''
|This class implements the DTM2012 atmospheric model.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/DTM2012.html ...]
|-
|'''JB2006'''
|This class implements the JB2006 atmospheric model.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/JB2006.html ...]
|-
|'''MSISE2000'''
|This class implements the MSIS atmospheric model (from a NRLMSIS sub-model).
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/MSISE2000.html ...]
|-
|'''NRLMSISE00'''
|This class implements the NRLMSIS 1.0 atmospheric model.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/MSIS/NRLMSISE00.html ...]
|-
|'''NRLMSISE20'''
|This class implements the NRLMSIS 2.0 atmospheric model.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/MSIS/NRLMSISE20.html ...]
|-
|'''US76'''
|This class implements the US76 atmospheric model.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/US76.html ...]
|}

'''Solar Activity'''

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''DTMSolarData'''
|This class represents a solar data container adapted for the DTM atmosphere models.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/specialized/DTMSolarData.html ...]
|-
|'''ClassicalMSISE2000SolarData'''
|This class represents a solar data container adapted for the MSISE2000 atmosphere model. The average ap values are computed arithmetically.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/specialized/ClassicalMSISE2000SolarData.html ...]
|-
|'''ContinuousMSISE2000SolarData'''
|This class represents a solar data container adapted for the MSISE2000 atmosphere model. The mean ap values are computed by trapezoidal integration.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/specialized/ContinuousMSISE2000SolarData.html ...]
|-
|'''ACSOLFormatReader'''
|This class reads ACSOL format solar activity data
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/ACSOLFormatReader.html ...]
|-
|'''ConstantSolarActivity'''
|This class represents constant solar activity
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/ConstantSolarActivity.html ...]
|-
|'''NOAAFormatReader'''
|This class reads NOAA format solar activity data
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/NOAAFormatReader.html ...]
|-
|'''SolarActivityDataFactory'''
|Factory used to read solar activity files and return SolarActivityDataProvider
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/SolarActivityDataFactory.html ...]
|-
|'''SolarActivityToolbox'''
|Solar activity toolbox. Has methods to compute mean flux values, to convert from ap to kp.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/SolarActivityToolbox.html ...]
|-
|'''MarshallSolarActivityFutureEstimation'''
|This class reads and provides solar activity data needed by atmospheric models: F107 solar flux and Kp indexes.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/specialized/MarshallSolarActivityFutureEstimation.html ...]
|-
|'''ExtendedSolarActivityWrapper'''
|This class extends a solar activity provider out of its timespan with constant values.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/ExtendedSolarActivityWrapper.html ...]
|}

'''Ocean Tides Coefficients'''

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''FES2004FormatReader'''
|Reader for FES2004 format coefficients files.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/tides/coefficients/FES2004FormatReader.html ...]
|-
|'''OceanTidesCoefficientsFactory'''
|Factory used to read ocean tides coefficients files in different formats and return an OceanTidesCoefficientsProvider.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/tides/coefficients/OceanTidesCoefficientsFactory.html ...]
|-
|'''OceanTidesCoefficientsReader'''
|This abstract class represents a Ocean Tides Coefficients file reader.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/tides/coefficients/OceanTidesCoefficientsReader.html ...]
|-
|'''OceanTidesCoefficientsSet'''
|Represents a line from the ocean tides data file.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/tides/coefficients/OceanTidesCoefficientsSet.html ...]
|}

'''Geomagnetic Field'''

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''GeoMagneticElements'''
|This class contains all the elements about a magnetic field : the magnetic field vector and associated caracteristics Inclination, Declination, Total Intensity, Horizontal Intensity.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/models/earth/GeoMagneticElements.html ...]
|-
|'''GeoMagneticField'''
|These objects are produced by the factory and are based on a model for a decimal year date and allows to compute GeomagneticElements
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/models/earth/GeoMagneticField.html ...]
|-
|'''GeoMagneticFieldFactory'''
|Factory to produce GeoMagneticField.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/models/earth/GeoMagneticFieldFactory.html ...]
|-
|'''GeoMagneticModelReader'''
|To load the model from an input file
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/models/earth/GeoMagneticModelReader.html ...]
|-
|'''COFFileFormatReader'''
|Class loading the geomagnetic data from COF files.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/models/earth/COFFileFormatReader.html ...]
|}

[[Category:User_Manual_4.18_Orbit_Propagation]]

User Manual 4.18 Environment Models

2026-06-10T10:42:25Z

Admin tsn :

== Introduction ==
=== Scope ===
The scope of this section is to present the physical models available through the Patrius library.

=== Javadoc ===
All the classes related to physical models are in the <code>fr.cnes.sirius.patrius.forces</code> and <code>fr.cnes.sirius.patrius.math.parameter</code>packages. The classes related to reading potential files are in the package <code>fr.cnes.sirius.patrius.forces.gravity.potential</code>.

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
|Patrius
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/package-summary.html Package fr.cnes.sirius.patrius.forces.atmospheres]
|-
|Patrius
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/package-summary.html Package fr.cnes.sirius.patrius.forces.atmospheres.solarActivity]
|-
|Patrius
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/specialized/package-summary.html Package fr.cnes.sirius.patrius.forces.atmospheres.solarActivity.specialized]
|-
|Patrius
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/specialized/package-summary.html Package fr.cnes.sirius.patrius.forces.atmospheres.solarActivity.specialized]
|-
|Patrius
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/potential/package-summary.html Package fr.cnes.sirius.patrius.forces.gravity.potential]
|-
|Patrius
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/variations/package-summary.html Package fr.cnes.sirius.patrius.forces.gravity.variations]
|-
|Patrius
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/tides/coefficients/package-summary.html Package fr.cnes.sirius.patrius.forces.gravity.tides.coefficients]
|-
|Patrius
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/models/earth/package-summary.html Package fr.cnes.sirius.patrius.math.parameter]
|-
|Patrius
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/tides/ReferencePointsDisplacement.html Class fr.cnes.sirius.patrius.utils.ReferencePointsDisplacement]
|}

=== Links ===
Some useful links are given hereunder.

'''IERS Page'''
[http://www.iers.org/IERS/EN/Publications/TechnicalNotes/tn36.html IERS Conventions (2010), Technical Note No.36]

'''Project Pages'''

* [http://cddis.nasa.gov/ NASA - Crustal Dynamics Data Information System (CDDIS)]
* [http://op.gfz-potsdam.de/grace/ GFZ - Grace (Gravity Recovery and Climate Experiment) Mission Homepage]
* [http://icgem.gfz-potsdam.de/ICGEM/ GFZ - International Centre for Global Earth Models]
* [http://grgs.obs-mip.fr Groupe de Recherche de Géodésie Spatiale]

'''Results Pages'''

* ''EGM96: The NASA GSFC and NIMA Joint Geopotential Model'', Lemoine; F. G., Kenyon; S. C., Factor; J. K., Trimmer; R.G., Pavlis; N. K., Chinn; D. S., Cox; C. M., Klosko; S. M., Luthcke; S. B., Torrence; M. H., Wang; Y. M., Williamson; R. G., Pavlis; E. C., Rapp; R. H., Olson; T. R., NASA Goddard Space Flight Center, Greenbelt, Maryland, 20771 USA, July 1998, Available [http://cddis.nasa.gov/926/egm96/egm96.html here].
* ''GFZ : Global Gravity Field Models'', Available [http://icgem.gfz-potsdam.de/ICGEM/modelstab.html here].

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

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

== Features Description ==
=== Earth Potential Models ===

The <code>fr.cnes.sirius.patrius.forces.gravity.potential</code> package provides tools allowing the user to read external gravity potential data files. The following file formats are supported :

* EGM96 ASCII format data
* EIGEN-GRACE format
* ICGEM format
* GRGS format

Below is a diagram showing the architecture of the <code>fr.cnes.sirius.patrius.forces.gravity.potential</code> package.

[[File:physicalModels.PNG|center]]

For a detailed explanation of the Data Management System, please refer to the [SUP_DMS_Home Data Management System section] of the Support User Manual.

The <code>fr.cnes.sirius.patrius.forces.gravity.variations</code> package provides tools allowing the user to read external variable gravity potential data files. The corresponding ForceModel is also included in the package. The following file formats are supported :

* GRGS RL02

Below is a diagram showing the architecture of the <code>fr.cnes.sirius.patrius.forces.gravity.variations</code> package.

[[File:varPOT.PNG|center]]

By default, some loaders are added to <code>VariableGravityFieldFactory</code> in the following order:
*<code>GRGSRL02FormatReader</code>: GRGSR L02 file format
There is no included data in PATRIUS by default
Once loaded, data are stored in static variables and are used for variable gravity field computation.

=== Atmosphere models and solar activity model ===
==== Generalities about Solar Activity and Atmospheres ====

The atmospheres make use of solar activity in order to compute the density at the given user location excepted US76 model that is only based on altitude parameters. The PATRIUS architecture of atmospheres and solar activity is divided into three layers :

*'''Atmospheres use solar data in specific ways'''
Each atmosphere model uses the solar data in a specific way (more simply, US76 doesn't use solar data). These representations are enclosed in the atmosphere model specific interfaces, such as [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/forces/atmospheres/DTMInputParameters.html DTMInputParamters]. Atmosphere models available include US76 (for low altitudes in range 0 to 1000km), DTM2000, DTM2012 and MSISE2000.
*'''Reading and storing solar data'''
The way to store the solar data is enclosed in the [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/SolarActivityDataProvider.html SolarActivityDataProvider interface]. It defines the basic coefficients (Ap, Kp and F10.7 cm) that any solar activity data provider class should be able to return, in order to be compatible with the atmosphere specific implementations (see next point). The [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/package-summary.html solarActivity package] contains classes that can read different file formats and can return the solar activity data. So far, one class for each of the ACSOL and NOAA formats has been implemented. Additionally, one class representing constant solar activity (that requires no external file) has been implemented.
*'''Using the solar data in an adequate fashion'''
Making effective use of the solar data for specific atmospheres requires an object that provides solar data (implementing the [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/SolarActivityDataProvider.html SolarActivityDataProvider]) and answers to the interfaces that define the ways in which the atmosphere models use this data (e.g. implementing [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/forces/atmospheres/DTM2000InputParameters.html DTMInputParameters]). These classes are contained in the [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/specialized/package-summary.html fr.cnes.sirius.patrius.forces.atmospheres.solarActivity.specialized package]). So far, one class for each of the DTM2000/DTM2012 and MSISE2000 models have been implemented.

The <code>fr.cnes.sirius.patrius.forces.atmospheres.solarActivity</code> package follows the same architecture as the <code>fr.cnes.sirius.patrius.forces.gravity.potential</code> package. The user must use the [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/SolarActivityDataFactory.html SolarActivityDataFactory class].

For a detailed explanation of the Data Management System, please refer to the [SUP_DMS_Home Data Management System section] of the Support User Manual.

For performances reasons, numerical propagator checks availability of solar activity data at start of propagation and not at every solar activity data call. If required solar activity or geomagnetic activity does not cover the required range by the atmospheric model, an exception is returned.

==== Atmospheric models ====

Various models are available in PATRIUS: DTM-2000, DTM-2012, MSIS-00, US76, etc. all models inherit the <code>Atmosphere</code> interface providing total density information. 
DTM and MSIS models also implement the <code>ExtendedAtmosphere</code> interface which provides more detailed data such as temperature and partial densities of atmosphere constituents. 
Some models require solar and geomagnetic information (see below for how to provide solar and geomagnetic data).

===== MSIS2000 Atmosphere model =====

The NRLMSIS series represents the gold standard for empirical neutral atmosphere models, used to predict temperature, density, and composition from the ground to the exosphere. The transition from NRLMSISE-00 (released in 2013) to NRLMSIS 2.0 (released in 2020) marks a significant leap in modeling accuracy and architectural design. PATRIUS implements both models.

Key Differences

* NRLMSISE00 (or NRLMSIS 1.0):
** Relies on older mass spectrometer and incoherent scatter radar data. While robust, it often overestimates densities during extreme solar minimums and struggles with the precise "satellite drag" modeling required for modern space situational awareness.
** Models the primary species (He, O, N2, O, Ar, H, N) and includes an "anomalous oxygen" component to account for satellite drag discrepancies.

* NRLMSISE20 (or NRLMSIS 2.0):
** Incorporates decades of new data, including extensive satellite accelerometer measurements and improved occultation data. It is significantly more accurate in the thermosphere and exosphere, particularly during low solar activity.
** Introduces a more rigorous treatment of atomic species. Notably, it includes Atomic Nitrogen (N) and Nitric Oxide (NO) as intrinsic parts of the model (though, as you noted in your previous translation, some implementations may still exclude NO depending on the reference version used). It also ensures better mass-density consistency.
** Version 2.0 enforces stricter physical constraints between temperature and density profiles, ensuring that the transition between the lower atmosphere and the thermosphere is physically smoother.

Note that a new model NRLMSIS 2.1 has been presented in 2025. This model is not implemented yet in PATRIUS.

More information can be found at the [http://www.nrl.navy.mil/research/nrl-review/2003/atmospheric-science/picone/ Naval Research Laboratory website] and [https://map.nrl.navy.mil/map/pub/nrl/NRLMSIS/ Geospace Science & Technology Branch]. Note that several adaptations have been made to optimize the JAVA model compare to these FORTRAN models.

In order to use this atmosphere model, the user must proceed by giving the following arguments as inputs to the [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/forces/atmospheres/MSISE2000.html MSISE2000] class :

* The empirical atmosphere model it self (NRLMSISE00 or NRLMSISE20)
* Solar activity data (as a [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/forces/atmospheres/MSISE2000InputParameters.html MSISE2000InputParameters])
* the Earth model (as a [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/bodies/BodyShape.html BodyShape])
* the Sun model (as a [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/bodies/CelestialBody.html CelestialBody])

The following code snippet creates an instance of MSISE2000 :

<syntaxhighlight lang="java">
// Create an instance of the BodyShape "EARTH", with user chosen
// equatorial radius, flattening and body frame
Frame frame = FramesFactory.getITRF();
double f = 0.29825765000000E+03;
double ae = 6378136.46;
BodyShape earth = new OneAxisEllipsoid(ae, 1 / f, frame);

// Get the instance of the CelestialBody "SUN"
CelestialBody sun = CelestialBodyFactory.getSun();

// Create the solar activity data to be used
SolarActivityDataProvider solarActivity = SolarActivityDataFactory.getSolarActivityDataProvider();
final MSISE2000InputParameters msiseData = new ClassicalMSISE2000SolarData(solarActivity);

// Create an instance of the atmosphere model
Atmosphere atmosModel = new MSISE2000(new NRLMSISE00(), msiseData , earth, sun);
</syntaxhighlight>

Warning: the NRLMSISE-00 model is not continuous. There is a discontinuity every day (at 0h in UTC time scale). Discontinuities are however very small (1E-3 on a relative scale).

The main difference in usage between the models NRLMSISE-00 and NRLMSIS 2.0 is that :

* NRLMSISE-00 uses a “Flags” container to define the model’s specific settings every time we call the gtd7d(Input, Flags) method
* NRLMSIS 2.0 doesn’t use the “Flags” container when calling the gtd7d(Input, Flags). Instead, the model is configured once in its constructor by providing a specific MSISInit instance.

==== Solar and geomagnetic activity ====

Solar and geomagnetic activity can be provided in various ways:
* Constant solar activity using: <syntaxhighlight lang="java">final SolarActivityDataProvider constantSolarActivity = new ConstantSolarActivity(140, 15);</syntaxhighlight>
* Variable solar activity using (for instance):
<syntaxhighlight lang="java">
final SolarActivityDataProvider variableSolarActivity = new NOAAFormatReader(...);
final SolarActivityDataProvider otherVariableSolarActivity = new ACSOLFormatReader(...);
</syntaxhighlight>

Solar and geomagnetic activity data often having a limited timespan, the class <code>ExtendedSolarActivityWrapper</code> allows data extension with constant values. Solar and geomagnetic data returned before timespan are equals to an average of first available data (the average duration being user-chosen). Solar and geomagnetic data returned after timespan are equals to an average of last available data (the average duration being user-chosen). Example:

<syntaxhighlight lang="java">
final SolarActivityDataProvider innerProvider = new NOAAFormatReader() // Variable solar activity over a given timespan
final double duration = 86400; // Duration on which average solar activity will be computed if date out of innerProvider timespan
final ExtendedSolarActivityWrapper solarActivity = new ExtendedSolarActivityWrapper(innerProvider, duration)// Extended solar activity
</syntaxhighlight>

The above code will create an solar activity whose value will be:
* Value of innerProvider if date is within innerProvider timespan
* Average value on [lower boundary, lower boundary + duration] if date is before innerProvider lower boundary
* Average value on [upper boundary- duration, upper boundary] if date is after innerProvider upperboundary

These providers are used as inputs of atmospheric models.

===== Reading Solar Activity Data files =====

The data is read through the <code>DataLoader</code> infrastructure; it provides several ways to load solar activity data. Please see the [SUP_DMS_Home Data Management System section] for more information.

The following file formats are supported by PATRIUS:
* ACSOL format
* NOAA format

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

<syntaxhighlight lang="java">
//Directory containing the file ACSOL.act
final File potdir = new File("/my/data/solar");
//The directory is given to the data loader
DataProvidersManager.getInstance().addProvider(new DirectoryCrawler(potdir));
//The ACSOL file is registered in the SolarActivityDataFactory
//If it is the only solar activity file of the directory, this step is not necessary
SolarActivityDataFactory.addSolarActivityDataReader(new ACSOLFormatReader("ACSOL.act"));
//A provider for the data is created
final SolarActivityDataProvider provider = SolarActivityDataFactory.getSolarActivityDataProvider();
//Get the ap, kp and instant flux at date
final AbsoluteDate userDate = new AbsoluteDate();
final double ap = provider.getAp( userDate );
final double kp = provider.getKp( userDate );
final double f = provider.getInstantFluxValue( userDate );
</syntaxhighlight>

By default, some loaders are added to <code>SolarActivityDataFactory</code> in the following order:
*<code>ACSOLFormatReader</code>: ACSOL file format
*<code>NOAAFormatReader</code>: NOAA file format
There is no included data in PATRIUS by default
Once loaded, data are stored in static variables and are used for solar activity retrieval.

=== Tides models ===
==== Tides model for force computation ====

The PATRIUS <code>fr.cnes.sirius.patrius.forces.gravity.tides</code> package provides tools allowing the user to use Terestrial and Ocean tides. The <code>fr.cnes.sirius.patrius.forces.gravity.tides.coefficients</code> package also allows reading external ocean tides coefficients data files. The following file formats are supported by PATRIUS:
* FES2004 format

By default, some loaders are added to <code>OceanTidesCoefficientFactory</code> in the following order:
*<code>FES2004FormatReader</code>: FES 2004 file format
There is no included data in PATRIUS by default
Once loaded, data are stored in static variables and are used for ocean tides computation.

==== Reference point displacement ====

The PATRIUS <code>fr.cnes.sirius.patrius.utils.ReferencePointsDisplacement</code> class provides a model describing the displacement of reference points due to the effect of the solid Earth tides. The computation is performed by the static method '''solidEarthTidesCorrections(AbsoluteDate, Vector3D, Vector3D, Vector3D)'''. The implemented model has been validated by comparison with tests available in the IERS website. The example below shows the user how to compute displacements of reference points:

<syntaxhighlight lang="java">
// Test from source ftp://tai.bipm.org/iers/convupdt/chapter7/dehanttideinel/DEHANTTIDEINEL.F

// date : 13/04/2009
final AbsoluteDate date = new AbsoluteDate(2009, 4, 13, 0, 0, 0., TimeScalesFactory.getUTC());

// entries : moon position, sun position, station location
final Vector3D moon = new Vector3D(-179996231.920342,-312468450.131567, -169288918.592160);
final Vector3D sun = new Vector3D(137859926952.015, 54228127881.4350, 23509422341.6960);
final Vector3D point = new Vector3D(4075578.385, 931852.890, 4801570.154);

// compute the displacement
final Vector3D disp = ReferencePointsDisplacement.solidEarthTidesCorrections(date, point, sun, moon);

// comparison with reference results (IERS)
Assert.assertEquals(0.07700420357108125891, disp.getX(), Precision.EPSILON);
Assert.assertEquals(0.06304056321824967613, disp.getY(), Precision.EPSILON);
Assert.assertEquals(0.05516568152597246810, disp.getZ(), Precision.EPSILON);
</syntaxhighlight>

=== Geomagnetic models ===
==== Design ====

The <code>fr.cnes.sirius.patrius.models.earth</code> package provides tools allowing the user to use different geomagnetic models. For the moment, there are only the two following models available :
* IGRF 11 : International Geomagnetic Reference Field eleventh generation
* WMM 2010 : World Magnetic Model published in december 2009

A class diagram is given hereunder to show how geomagnetic is read and used in the library :

[[File:geomaguml.png]]

The user can create its own [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/models/earth/GeoMagneticModelReader.html GeoMagneticModelReader] in order to provide [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/models/earth/GeoMagneticField.html GeoMagneticField] from any file format.

By default, some loaders are added to <code>GeoMagneticFieldFactory</code> in the following order:
*<code>COFFileFormatReader</code>: COF file format
There is no included data in PATRIUS by default
Once loaded, data are stored in static variables and are used for geomagnetic field computation (IGRF and WMM).

==== IGRF 11 geomagnetic model ====

The International Geomagnetic Reference Field (IGRF) was introduced by the International Association of Geomagnetism and Aeronomy (IAGA) in 1968 in response to the demand for a standard spherical harmonic representation of the Earth's main field. The model is updated at 5-yearly intervals, the latest being the 11th generation, produced and released by IAGA Working Group V-MOD (formerly V-8) December 2009.

More information can be found at the [http://www.ngdc.noaa.gov/IAGA/vmod/index.html IAGA Division V-Mod].

==== WMM 2010 geomagnetic model ====

The World Magnetic Model is a joint product of the United States’ National Geospatial-Intelligence Agency (NGA) and the United Kingdom’s Defence Geographic Centre (DGC). The WMM was developed jointly by the National Geophysical Data Center (NGDC, Boulder CO, USA) and the British Geological Survey (BGS, Edinburgh, Scotland).

The World Magnetic Model is the standard model used by the U.S. Department of Defense, the U.K. Ministry of Defence, the North Atlantic Treaty Organization (NATO) and the International Hydrographic Organization (IHO), for navigation, attitude and heading referencing systems using the geomagnetic field. It is also used widely in civilian navigation and heading systems. The model, associated software, and documentation are distributed by NGDC on behalf of NGA. The model is produced at 5-year intervals, with the current model expiring on December 31, 2014.

The current model, WMM2010 (published 12/2009)

More information can be found at the [http://www.ngdc.noaa.gov/geomag/WMM/DoDWMM.shtml National Oceanic and Atmospheric Administration].

==== Details, limitation and precautions ====

In the geomagnetic field's computation from the different models, to convert geodetic coordinates (defined by the WGS-84 reference ellipsoid) to Earth Centered spherical coordinates, the following constants are used :

* Semi major-axis of WGS-84 ellipsoid : 6378.137 km
* The first eccentricity squared : 0.0066943799901413169961

and to compute the spherical harmonic variables for a given spherical coordinate uses the mean radius of IAU-66 ellipsoid 6371.2 km is used.

The different models are used to compute gemoagnetic field near earth surface. In the model file, the given altitude range of validity is-1 to 600 km even if we can compute field outside of this range.

The method GeoMagneticField.calculateField(final Vector3D point,final Frame frame, final AbsoluteDate date) has been added to Patrius and allows to compute the field from a position vector in a specific frame and at a specific date. This method is based on tranformModel method which recomputes the field at a date. This method doesn't work if the model doesn't support time transform. In this way, this method added to Patrius throws a Patrius exception about model not supporting time transform.

Here is the list of all possible actual models and the time transform support (please note that only dates prior to 2010 won't support time transformation) :

{| class="wikitable"
| Model and associated data file
| Model Name
| Validity Period
| Time transform support
|-
| rowspan="23"|IGRF (''GeoMagneticFieldFactory.getIGRF(..)'' uses IGRF.COF)
| IGRF00
| 1900.0 - 1905.0
| false
|-
| IGRF05
| 1905.0 - 1910.0
| false
|-
| IGRF10
| 1910.0 - 1915.0
| false
|-
|IGRF15
| 1915.0 - 1920.0
| false
|-
|IGRF20
| 1920.0 - 1925.0
| false
|-
|IGRF25
| 1925.0 - 1930.0
| false
|-
|IGRF30
| 1930.0 - 1935.0
| false
|-
|IGRF35
| 1935.0 - 1940.0
| false
|-
|IGRF40
| 1940.0 - 1945.0
| false
|-
|DGRF45
| 1945.0 - 1950.0
| false
|-
|DGRF50
| 1950.0 - 1955.0
| false
|-
|DGRF55
| 1955.0 - 1960.0
| false
|-
|DGRF60
| 1960.0 - 1965.0
| false
|-
|DGRF65
| 1965.0 - 1970.0
| false
|-
|DGRF70
| 1970.0 - 1975.0
| false
|-
|DGRF75
| 1975.0 - 1980.0
| false
|-
|DGRF80
| 1980.0 - 1985.0
| false
|-
|DGRF85
| 1985.0 - 1990.0
| false
|-
|DGRF90
| 1990.0 - 1995.0
| false
|-
|DGRF95
| 1995.0 - 2000.0
| false
|-
|DGRF2000
| 2000.0 - 2005.0
| false
|-
|DGRF2005
| 2005.0 - 2010.0
| false
|-
|IGRF2010
| 2010.0 - 2015.0
| true
|-
| rowspan="1"|WMM (''GeoMagneticFieldFactory.getWMM(..)'' uses WMM.COF)
| WMM2010
| 2010.0 - 2015.0
| true
|}

Precautions :
The method GeoMagneticField.calculateField (final double latitude, final double longitude, final double height) doesn't use SI units. Latitude and longitude are given in degrees, and height is given in kilometers.

== Getting Started ==

==== Code Example ====

The following code sample computes geomagnetic field elements for four (date, position) of a fake trajectory :

<syntaxhighlight lang="java">
public void codeExemple() throws PatriusException {

Utils.setDataRoot("earth");
FramesFactory.setConfiguration(Utils.getIERS2003ConfigurationWOEOP(true));

//Fake trajectory : list of date and list of position
List<AbsoluteDate> dateList = new ArrayList<AbsoluteDate>();
AbsoluteDate initDate = new AbsoluteDate(2010, 1, 1, 12, 0, 0.0, TimeScalesFactory.getTT());

dateList.add(initDate);
dateList.add(new AbsoluteDate(initDate, 600));
dateList.add(new AbsoluteDate(initDate, 1200));
dateList.add(new AbsoluteDate(initDate, 1800));

List<Vector3D> positionList = new ArrayList<Vector3D>();
positionList.add(new Vector3D(6.46885878304673824e+06,-1.88050918456274318e+06, -1.32931592294715829e+04));
positionList.add(new Vector3D(6.58239141552595049e+06,-1.43349476017528563e+06, -1.39460373997706010e+04));
positionList.add(new Vector3D(6.66499609614125639e+06,-9.79745192516532145e+05, -1.45334684008149434e+04));
positionList.add(new Vector3D(6.71628402448997274e+06,-5.21392324304617418e+05, -1.50526405214286660e+04));

// Get the model to the initial date
final GeoMagneticField model = GeoMagneticFieldFactory.getIGRF(dateList.get(0));

// For each date and position, compute the GeoMagneticElement and add it to a list
List<GeoMagneticElements> geoMagList = new ArrayList<GeoMagneticElements>();
int i = 0;
for (AbsoluteDate date : dateList){
geoMagList.add(model.calculateField(positionList.get(i), FramesFactory.getEME2000(), date));
}

// Print each field vector B
for (GeoMagneticElements geoMagElement : geoMagList){
System.out.println(geoMagElement.toString());
}
}
</syntaxhighlight>

This code produces the following standard output :
<syntaxhighlight lang="java">MagneticField[B={29817,109;-2303,065; -9138,097},H=29905,92,F=31270,895,I=-16,991,D=-4,417]
MagneticField[B={29442,018;-2166,283; -8949,299},H=29521,606,F=30848,261,I=-16,864,D=-4,208]
MagneticField[B={29067,408;-1996,393; -8794,324},H=29135,885,F=30434,19,I=-16,796,D=-3,929]
MagneticField[B={28695,713;-1796,821; -8680,411},H=28751,913,F=30033,681,I=-16,799,D=-3,583]</syntaxhighlight>

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

{| class="wikitable"
|-
! scope="col"| Interface
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''Atmosphere'''
|Interface for atmospheric models.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/Atmosphere.html ...]
|-
|'''ExtendedAtmosphere'''
|Interface for atmospheric models with detailed data.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/ExtendedAtmosphere.html ...]
|-
|'''SolarActivityDataProvider'''
|Interface for solar activity data providers, to be used for atmosphere models
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/SolarActivityDataProvider.html ...]
|-
|'''DTM2000InputParameters'''
|Container for solar activity data, compatible with DTM Atmosphere models.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/DTMInputParameters.html ...]
|-
|'''MSISE2000InputParameters'''
|Container for solar activity data, compatible with MSISE2000 Atmosphere model.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/MSISE2000InputParameters.html ...]
|-
|'''OceanTidesCoefficientsProvider'''
|This interface is used to provide ocean tides coefficients.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/tides/coefficients/OceanTidesCoefficientsProvider.html ...]
|-
|'''PotentialCoefficientsProvider'''
|This interface is used to provide gravity field coefficients.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/potential/PotentialCoefficientsProvider.html ...]
|-
|'''VariablePotentialCoefficientsProvider'''
|This interface is used to provide variable gravity field coefficients.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/variations/coefficients/VariablePotentialCoefficientsProvider.html ...]
|-
|'''RadiationSensitive'''
|This interface is used to provide an direct solar radiative pressure model.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/radiation/RadiationSensitive.html ...]
|-
|'''RediffusedRadiationSensitive'''
|This interface is used to provide an rediffused radiative pressure model.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/radiation/RediffusedRadiationSensitive.html ...]
|-
|'''GeoMagneticDataProvider'''
|This interface is a generic geomagnetic data provider.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/models/earth/GeoMagneticDataProvider.html ...]
|}

=== Classes ===
'''Earth potential'''

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''EGMFormatReader'''
|This reader is adapted to the EGM Format.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/potential/EGMFormatReader.html ...]
|-
|'''GravityFieldFactory'''
|Factory used to read gravity field files in several supported formats. '''Main user access point''' : the simple way of reading a potential file is by using this factory.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/potential/GravityFieldFactory.html ...]
|-
|'''VariableGravityFieldFactory'''
|Factory used to read variable gravity field files in several supported formats. '''Main user access point''' : the simple way of reading a variable potential file is by using this factory.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/variations/coefficients/VariableGravityFieldFactory.html ...]
|-
|'''GRGSFormatReader'''
|Reader for the GRGS gravity field format.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/potential/GRGSFormatReader.html ...]
|-
|'''GRGSRL02FormatReader'''
|Reader for the GRGS RL02 variable gravity field format.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/variations/coefficients/GRGSRL02FormatReader.html ...]
|-
|'''ICGEMFormatReader'''
|Reader for the ICGEM gravity field format.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/potential/ICGEMFormatReader.html ...]
|-
|'''PotentialCoefficientsReader'''
|This abstract class represents a Gravitational Potential Coefficients file reader.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/potential/PotentialCoefficientsReader.html ...]
|-
|'''SHMFormatReader'''
|Reader for the SHM gravity field format.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/potential/SHMFormatReader.html ...]
|}

'''Atmosphere Models'''

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''DTM2000'''
|This class implements the DTM2000 atmospheric model.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/DTM2000.html ...]
|-
|'''DTM2012'''
|This class implements the DTM2012 atmospheric model.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/DTM2012.html ...]
|-
|'''JB2006'''
|This class implements the JB2006 atmospheric model.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/JB2006.html ...]
|-
|'''MSISE2000'''
|This class implements the MSIS00 atmospheric model.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/MSISE2000.html ...]
|-
|'''NRLMSISE00'''
|This class implements the NRLMSISE 1.0 atmospheric model.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/MSIS/NRLMSISE00.html ...]
|-
|'''NRLMSISE20'''
|This class implements the NRLMSISE 2.0 atmospheric model.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/MSIS/NRLMSISE20.html ...]
|-
|'''US76'''
|This class implements the US76 atmospheric model.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/US76.html ...]
|}

'''Solar Activity'''

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''DTMSolarData'''
|This class represents a solar data container adapted for the DTM atmosphere models.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/specialized/DTMSolarData.html ...]
|-
|'''ClassicalMSISE2000SolarData'''
|This class represents a solar data container adapted for the MSISE2000 atmosphere model. The average ap values are computed arithmetically.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/specialized/ClassicalMSISE2000SolarData.html ...]
|-
|'''ContinuousMSISE2000SolarData'''
|This class represents a solar data container adapted for the MSISE2000 atmosphere model. The mean ap values are computed by trapezoidal integration.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/specialized/ContinuousMSISE2000SolarData.html ...]
|-
|'''ACSOLFormatReader'''
|This class reads ACSOL format solar activity data
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/ACSOLFormatReader.html ...]
|-
|'''ConstantSolarActivity'''
|This class represents constant solar activity
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/ConstantSolarActivity.html ...]
|-
|'''NOAAFormatReader'''
|This class reads NOAA format solar activity data
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/NOAAFormatReader.html ...]
|-
|'''SolarActivityDataFactory'''
|Factory used to read solar activity files and return SolarActivityDataProvider
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/SolarActivityDataFactory.html ...]
|-
|'''SolarActivityToolbox'''
|Solar activity toolbox. Has methods to compute mean flux values, to convert from ap to kp.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/SolarActivityToolbox.html ...]
|-
|'''MarshallSolarActivityFutureEstimation'''
|This class reads and provides solar activity data needed by atmospheric models: F107 solar flux and Kp indexes.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/specialized/MarshallSolarActivityFutureEstimation.html ...]
|-
|'''ExtendedSolarActivityWrapper'''
|This class extends a solar activity provider out of its timespan with constant values.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/ExtendedSolarActivityWrapper.html ...]
|}

'''Ocean Tides Coefficients'''

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''FES2004FormatReader'''
|Reader for FES2004 format coefficients files.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/tides/coefficients/FES2004FormatReader.html ...]
|-
|'''OceanTidesCoefficientsFactory'''
|Factory used to read ocean tides coefficients files in different formats and return an OceanTidesCoefficientsProvider.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/tides/coefficients/OceanTidesCoefficientsFactory.html ...]
|-
|'''OceanTidesCoefficientsReader'''
|This abstract class represents a Ocean Tides Coefficients file reader.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/tides/coefficients/OceanTidesCoefficientsReader.html ...]
|-
|'''OceanTidesCoefficientsSet'''
|Represents a line from the ocean tides data file.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/tides/coefficients/OceanTidesCoefficientsSet.html ...]
|}

'''Geomagnetic Field'''

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''GeoMagneticElements'''
|This class contains all the elements about a magnetic field : the magnetic field vector and associated caracteristics Inclination, Declination, Total Intensity, Horizontal Intensity.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/models/earth/GeoMagneticElements.html ...]
|-
|'''GeoMagneticField'''
|These objects are produced by the factory and are based on a model for a decimal year date and allows to compute GeomagneticElements
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/models/earth/GeoMagneticField.html ...]
|-
|'''GeoMagneticFieldFactory'''
|Factory to produce GeoMagneticField.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/models/earth/GeoMagneticFieldFactory.html ...]
|-
|'''GeoMagneticModelReader'''
|To load the model from an input file
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/models/earth/GeoMagneticModelReader.html ...]
|-
|'''COFFileFormatReader'''
|Class loading the geomagnetic data from COF files.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/models/earth/COFFileFormatReader.html ...]
|}

[[Category:User_Manual_4.18_Orbit_Propagation]]

User Manual 4.18 Environment Models

2026-06-10T10:39:25Z

Admin tsn :

== Introduction ==
=== Scope ===
The scope of this section is to present the physical models available through the Patrius library.

=== Javadoc ===
All the classes related to physical models are in the <code>fr.cnes.sirius.patrius.forces</code> and <code>fr.cnes.sirius.patrius.math.parameter</code>packages. The classes related to reading potential files are in the package <code>fr.cnes.sirius.patrius.forces.gravity.potential</code>.

{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
|Patrius
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/package-summary.html Package fr.cnes.sirius.patrius.forces.atmospheres]
|-
|Patrius
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/package-summary.html Package fr.cnes.sirius.patrius.forces.atmospheres.solarActivity]
|-
|Patrius
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/specialized/package-summary.html Package fr.cnes.sirius.patrius.forces.atmospheres.solarActivity.specialized]
|-
|Patrius
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/specialized/package-summary.html Package fr.cnes.sirius.patrius.forces.atmospheres.solarActivity.specialized]
|-
|Patrius
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/potential/package-summary.html Package fr.cnes.sirius.patrius.forces.gravity.potential]
|-
|Patrius
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/variations/package-summary.html Package fr.cnes.sirius.patrius.forces.gravity.variations]
|-
|Patrius
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/tides/coefficients/package-summary.html Package fr.cnes.sirius.patrius.forces.gravity.tides.coefficients]
|-
|Patrius
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/models/earth/package-summary.html Package fr.cnes.sirius.patrius.math.parameter]
|-
|Patrius
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/tides/ReferencePointsDisplacement.html Class fr.cnes.sirius.patrius.utils.ReferencePointsDisplacement]
|}

=== Links ===
Some useful links are given hereunder.

'''IERS Page'''
[http://www.iers.org/IERS/EN/Publications/TechnicalNotes/tn36.html IERS Conventions (2010), Technical Note No.36]

'''Project Pages'''

* [http://cddis.nasa.gov/ NASA - Crustal Dynamics Data Information System (CDDIS)]
* [http://op.gfz-potsdam.de/grace/ GFZ - Grace (Gravity Recovery and Climate Experiment) Mission Homepage]
* [http://icgem.gfz-potsdam.de/ICGEM/ GFZ - International Centre for Global Earth Models]
* [http://grgs.obs-mip.fr Groupe de Recherche de Géodésie Spatiale]

'''Results Pages'''

* ''EGM96: The NASA GSFC and NIMA Joint Geopotential Model'', Lemoine; F. G., Kenyon; S. C., Factor; J. K., Trimmer; R.G., Pavlis; N. K., Chinn; D. S., Cox; C. M., Klosko; S. M., Luthcke; S. B., Torrence; M. H., Wang; Y. M., Williamson; R. G., Pavlis; E. C., Rapp; R. H., Olson; T. R., NASA Goddard Space Flight Center, Greenbelt, Maryland, 20771 USA, July 1998, Available [http://cddis.nasa.gov/926/egm96/egm96.html here].
* ''GFZ : Global Gravity Field Models'', Available [http://icgem.gfz-potsdam.de/ICGEM/modelstab.html here].

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

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

== Features Description ==
=== Earth Potential Models ===

The <code>fr.cnes.sirius.patrius.forces.gravity.potential</code> package provides tools allowing the user to read external gravity potential data files. The following file formats are supported :

* EGM96 ASCII format data
* EIGEN-GRACE format
* ICGEM format
* GRGS format

Below is a diagram showing the architecture of the <code>fr.cnes.sirius.patrius.forces.gravity.potential</code> package.

[[File:physicalModels.PNG|center]]

For a detailed explanation of the Data Management System, please refer to the [SUP_DMS_Home Data Management System section] of the Support User Manual.

The <code>fr.cnes.sirius.patrius.forces.gravity.variations</code> package provides tools allowing the user to read external variable gravity potential data files. The corresponding ForceModel is also included in the package. The following file formats are supported :

* GRGS RL02

Below is a diagram showing the architecture of the <code>fr.cnes.sirius.patrius.forces.gravity.variations</code> package.

[[File:varPOT.PNG|center]]

By default, some loaders are added to <code>VariableGravityFieldFactory</code> in the following order:
*<code>GRGSRL02FormatReader</code>: GRGSR L02 file format
There is no included data in PATRIUS by default
Once loaded, data are stored in static variables and are used for variable gravity field computation.

=== Atmosphere models and solar activity model ===
==== Generalities about Solar Activity and Atmospheres ====

The atmospheres make use of solar activity in order to compute the density at the given user location excepted US76 model that is only based on altitude parameters. The PATRIUS architecture of atmospheres and solar activity is divided into three layers :

*'''Atmospheres use solar data in specific ways'''
Each atmosphere model uses the solar data in a specific way (more simply, US76 doesn't use solar data). These representations are enclosed in the atmosphere model specific interfaces, such as [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/forces/atmospheres/DTMInputParameters.html DTMInputParamters]. Atmosphere models available include US76 (for low altitudes in range 0 to 1000km), DTM2000, DTM2012 and MSISE2000.
*'''Reading and storing solar data'''
The way to store the solar data is enclosed in the [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/SolarActivityDataProvider.html SolarActivityDataProvider interface]. It defines the basic coefficients (Ap, Kp and F10.7 cm) that any solar activity data provider class should be able to return, in order to be compatible with the atmosphere specific implementations (see next point). The [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/package-summary.html solarActivity package] contains classes that can read different file formats and can return the solar activity data. So far, one class for each of the ACSOL and NOAA formats has been implemented. Additionally, one class representing constant solar activity (that requires no external file) has been implemented.
*'''Using the solar data in an adequate fashion'''
Making effective use of the solar data for specific atmospheres requires an object that provides solar data (implementing the [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/SolarActivityDataProvider.html SolarActivityDataProvider]) and answers to the interfaces that define the ways in which the atmosphere models use this data (e.g. implementing [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/forces/atmospheres/DTM2000InputParameters.html DTMInputParameters]). These classes are contained in the [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/specialized/package-summary.html fr.cnes.sirius.patrius.forces.atmospheres.solarActivity.specialized package]). So far, one class for each of the DTM2000/DTM2012 and MSISE2000 models have been implemented.

The <code>fr.cnes.sirius.patrius.forces.atmospheres.solarActivity</code> package follows the same architecture as the <code>fr.cnes.sirius.patrius.forces.gravity.potential</code> package. The user must use the [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/SolarActivityDataFactory.html SolarActivityDataFactory class].

For a detailed explanation of the Data Management System, please refer to the [SUP_DMS_Home Data Management System section] of the Support User Manual.

For performances reasons, numerical propagator checks availability of solar activity data at start of propagation and not at every solar activity data call. If required solar activity or geomagnetic activity does not cover the required range by the atmospheric model, an exception is returned.

==== Atmospheric models ====

Various models are available in PATRIUS: DTM-2000, DTM-2012, MSIS-00, US76, etc. all models inherit the <code>Atmosphere</code> interface providing total density information. 
DTM and MSIS models also implement the <code>ExtendedAtmosphere</code> interface which provides more detailed data such as temperature and partial densities of atmosphere constituents. 
Some models require solar and geomagnetic information (see below for how to provide solar and geomagnetic data).

===== MSIS2000 Atmosphere model =====

The NRLMSIS series represents the gold standard for empirical neutral atmosphere models, used to predict temperature, density, and composition from the ground to the exosphere. The transition from NRLMSISE-00 (released in 2013) to NRLMSIS 2.0 (released in 2020) marks a significant leap in modeling accuracy and architectural design. PATRIUS implements both models.

Key Differences

* NRLMSISE-00:
** Relies on older mass spectrometer and incoherent scatter radar data. While robust, it often overestimates densities during extreme solar minimums and struggles with the precise "satellite drag" modeling required for modern space situational awareness.
** Models the primary species (He, O, N2, O, Ar, H, N) and includes an "anomalous oxygen" component to account for satellite drag discrepancies.

* NRLMSIS 2.0:
** Incorporates decades of new data, including extensive satellite accelerometer measurements and improved occultation data. It is significantly more accurate in the thermosphere and exosphere, particularly during low solar activity.
** Introduces a more rigorous treatment of atomic species. Notably, it includes Atomic Nitrogen (N) and Nitric Oxide (NO) as intrinsic parts of the model (though, as you noted in your previous translation, some implementations may still exclude NO depending on the reference version used). It also ensures better mass-density consistency.
** Version 2.0 enforces stricter physical constraints between temperature and density profiles, ensuring that the transition between the lower atmosphere and the thermosphere is physically smoother.

Note that a new model NRLMSIS 2.1 has been presented in 2025. This model is not implemented yet in PATRIUS.

More information can be found at the [http://www.nrl.navy.mil/research/nrl-review/2003/atmospheric-science/picone/ Naval Research Laboratory website] and [https://map.nrl.navy.mil/map/pub/nrl/NRLMSIS/ Geospace Science & Technology Branch]. Note that several adaptations have been made to optimize the JAVA model compare to these FORTRAN models.

In order to use this atmosphere model, the user must proceed by giving the following arguments as inputs to the [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/forces/atmospheres/MSISE2000.html MSISE2000] class :

* The empirical atmosphere model it self (NRLMSISE00 or NRLMSISE20)
* Solar activity data (as a [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/forces/atmospheres/MSISE2000InputParameters.html MSISE2000InputParameters])
* the Earth model (as a [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/bodies/BodyShape.html BodyShape])
* the Sun model (as a [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/bodies/CelestialBody.html CelestialBody])

The following code snippet creates an instance of MSISE2000 :

<syntaxhighlight lang="java">
// Create an instance of the BodyShape "EARTH", with user chosen
// equatorial radius, flattening and body frame
Frame frame = FramesFactory.getITRF();
double f = 0.29825765000000E+03;
double ae = 6378136.46;
BodyShape earth = new OneAxisEllipsoid(ae, 1 / f, frame);

// Get the instance of the CelestialBody "SUN"
CelestialBody sun = CelestialBodyFactory.getSun();

// Create the solar activity data to be used
SolarActivityDataProvider solarActivity = SolarActivityDataFactory.getSolarActivityDataProvider();
final MSISE2000InputParameters msiseData = new ClassicalMSISE2000SolarData(solarActivity);

// Create an instance of the atmosphere model
Atmosphere atmosModel = new MSISE2000(new NRLMSISE00(), msiseData , earth, sun);
</syntaxhighlight>

Warning: the NRLMSISE-00model is not continuous. There is a discontinuity every day (at 0h in UTC time scale). Discontinuities are however very small (1E-3 on a relative scale).

The main difference in usage between the models NRLMSISE-00 and NRLMSIS 2.0 is that :

* NRLMSISE-00 uses a “Flags” container to define the model’s specific settings every time we call the gtd7d(Input, Flags) method
* NRLMSIS 2.0 doesn’t use the “Flags” container when calling the gtd7d(Input, Flags). Instead, the model is configured once in its constructor by providing a specific MSISInit instance.

==== Solar and geomagnetic activity ====

Solar and geomagnetic activity can be provided in various ways:
* Constant solar activity using: <syntaxhighlight lang="java">final SolarActivityDataProvider constantSolarActivity = new ConstantSolarActivity(140, 15);</syntaxhighlight>
* Variable solar activity using (for instance):
<syntaxhighlight lang="java">
final SolarActivityDataProvider variableSolarActivity = new NOAAFormatReader(...);
final SolarActivityDataProvider otherVariableSolarActivity = new ACSOLFormatReader(...);
</syntaxhighlight>

Solar and geomagnetic activity data often having a limited timespan, the class <code>ExtendedSolarActivityWrapper</code> allows data extension with constant values. Solar and geomagnetic data returned before timespan are equals to an average of first available data (the average duration being user-chosen). Solar and geomagnetic data returned after timespan are equals to an average of last available data (the average duration being user-chosen). Example:

<syntaxhighlight lang="java">
final SolarActivityDataProvider innerProvider = new NOAAFormatReader() // Variable solar activity over a given timespan
final double duration = 86400; // Duration on which average solar activity will be computed if date out of innerProvider timespan
final ExtendedSolarActivityWrapper solarActivity = new ExtendedSolarActivityWrapper(innerProvider, duration)// Extended solar activity
</syntaxhighlight>

The above code will create an solar activity whose value will be:
* Value of innerProvider if date is within innerProvider timespan
* Average value on [lower boundary, lower boundary + duration] if date is before innerProvider lower boundary
* Average value on [upper boundary- duration, upper boundary] if date is after innerProvider upperboundary

These providers are used as inputs of atmospheric models.

===== Reading Solar Activity Data files =====

The data is read through the <code>DataLoader</code> infrastructure; it provides several ways to load solar activity data. Please see the [SUP_DMS_Home Data Management System section] for more information.

The following file formats are supported by PATRIUS:
* ACSOL format
* NOAA format

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

<syntaxhighlight lang="java">
//Directory containing the file ACSOL.act
final File potdir = new File("/my/data/solar");
//The directory is given to the data loader
DataProvidersManager.getInstance().addProvider(new DirectoryCrawler(potdir));
//The ACSOL file is registered in the SolarActivityDataFactory
//If it is the only solar activity file of the directory, this step is not necessary
SolarActivityDataFactory.addSolarActivityDataReader(new ACSOLFormatReader("ACSOL.act"));
//A provider for the data is created
final SolarActivityDataProvider provider = SolarActivityDataFactory.getSolarActivityDataProvider();
//Get the ap, kp and instant flux at date
final AbsoluteDate userDate = new AbsoluteDate();
final double ap = provider.getAp( userDate );
final double kp = provider.getKp( userDate );
final double f = provider.getInstantFluxValue( userDate );
</syntaxhighlight>

By default, some loaders are added to <code>SolarActivityDataFactory</code> in the following order:
*<code>ACSOLFormatReader</code>: ACSOL file format
*<code>NOAAFormatReader</code>: NOAA file format
There is no included data in PATRIUS by default
Once loaded, data are stored in static variables and are used for solar activity retrieval.

=== Tides models ===
==== Tides model for force computation ====

The PATRIUS <code>fr.cnes.sirius.patrius.forces.gravity.tides</code> package provides tools allowing the user to use Terestrial and Ocean tides. The <code>fr.cnes.sirius.patrius.forces.gravity.tides.coefficients</code> package also allows reading external ocean tides coefficients data files. The following file formats are supported by PATRIUS:
* FES2004 format

By default, some loaders are added to <code>OceanTidesCoefficientFactory</code> in the following order:
*<code>FES2004FormatReader</code>: FES 2004 file format
There is no included data in PATRIUS by default
Once loaded, data are stored in static variables and are used for ocean tides computation.

==== Reference point displacement ====

The PATRIUS <code>fr.cnes.sirius.patrius.utils.ReferencePointsDisplacement</code> class provides a model describing the displacement of reference points due to the effect of the solid Earth tides. The computation is performed by the static method '''solidEarthTidesCorrections(AbsoluteDate, Vector3D, Vector3D, Vector3D)'''. The implemented model has been validated by comparison with tests available in the IERS website. The example below shows the user how to compute displacements of reference points:

<syntaxhighlight lang="java">
// Test from source ftp://tai.bipm.org/iers/convupdt/chapter7/dehanttideinel/DEHANTTIDEINEL.F

// date : 13/04/2009
final AbsoluteDate date = new AbsoluteDate(2009, 4, 13, 0, 0, 0., TimeScalesFactory.getUTC());

// entries : moon position, sun position, station location
final Vector3D moon = new Vector3D(-179996231.920342,-312468450.131567, -169288918.592160);
final Vector3D sun = new Vector3D(137859926952.015, 54228127881.4350, 23509422341.6960);
final Vector3D point = new Vector3D(4075578.385, 931852.890, 4801570.154);

// compute the displacement
final Vector3D disp = ReferencePointsDisplacement.solidEarthTidesCorrections(date, point, sun, moon);

// comparison with reference results (IERS)
Assert.assertEquals(0.07700420357108125891, disp.getX(), Precision.EPSILON);
Assert.assertEquals(0.06304056321824967613, disp.getY(), Precision.EPSILON);
Assert.assertEquals(0.05516568152597246810, disp.getZ(), Precision.EPSILON);
</syntaxhighlight>

=== Geomagnetic models ===
==== Design ====

The <code>fr.cnes.sirius.patrius.models.earth</code> package provides tools allowing the user to use different geomagnetic models. For the moment, there are only the two following models available :
* IGRF 11 : International Geomagnetic Reference Field eleventh generation
* WMM 2010 : World Magnetic Model published in december 2009

A class diagram is given hereunder to show how geomagnetic is read and used in the library :

[[File:geomaguml.png]]

The user can create its own [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/models/earth/GeoMagneticModelReader.html GeoMagneticModelReader] in order to provide [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/models/earth/GeoMagneticField.html GeoMagneticField] from any file format.

By default, some loaders are added to <code>GeoMagneticFieldFactory</code> in the following order:
*<code>COFFileFormatReader</code>: COF file format
There is no included data in PATRIUS by default
Once loaded, data are stored in static variables and are used for geomagnetic field computation (IGRF and WMM).

==== IGRF 11 geomagnetic model ====

The International Geomagnetic Reference Field (IGRF) was introduced by the International Association of Geomagnetism and Aeronomy (IAGA) in 1968 in response to the demand for a standard spherical harmonic representation of the Earth's main field. The model is updated at 5-yearly intervals, the latest being the 11th generation, produced and released by IAGA Working Group V-MOD (formerly V-8) December 2009.

More information can be found at the [http://www.ngdc.noaa.gov/IAGA/vmod/index.html IAGA Division V-Mod].

==== WMM 2010 geomagnetic model ====

The World Magnetic Model is a joint product of the United States’ National Geospatial-Intelligence Agency (NGA) and the United Kingdom’s Defence Geographic Centre (DGC). The WMM was developed jointly by the National Geophysical Data Center (NGDC, Boulder CO, USA) and the British Geological Survey (BGS, Edinburgh, Scotland).

The World Magnetic Model is the standard model used by the U.S. Department of Defense, the U.K. Ministry of Defence, the North Atlantic Treaty Organization (NATO) and the International Hydrographic Organization (IHO), for navigation, attitude and heading referencing systems using the geomagnetic field. It is also used widely in civilian navigation and heading systems. The model, associated software, and documentation are distributed by NGDC on behalf of NGA. The model is produced at 5-year intervals, with the current model expiring on December 31, 2014.

The current model, WMM2010 (published 12/2009)

More information can be found at the [http://www.ngdc.noaa.gov/geomag/WMM/DoDWMM.shtml National Oceanic and Atmospheric Administration].

==== Details, limitation and precautions ====

In the geomagnetic field's computation from the different models, to convert geodetic coordinates (defined by the WGS-84 reference ellipsoid) to Earth Centered spherical coordinates, the following constants are used :

* Semi major-axis of WGS-84 ellipsoid : 6378.137 km
* The first eccentricity squared : 0.0066943799901413169961

and to compute the spherical harmonic variables for a given spherical coordinate uses the mean radius of IAU-66 ellipsoid 6371.2 km is used.

The different models are used to compute gemoagnetic field near earth surface. In the model file, the given altitude range of validity is-1 to 600 km even if we can compute field outside of this range.

The method GeoMagneticField.calculateField(final Vector3D point,final Frame frame, final AbsoluteDate date) has been added to Patrius and allows to compute the field from a position vector in a specific frame and at a specific date. This method is based on tranformModel method which recomputes the field at a date. This method doesn't work if the model doesn't support time transform. In this way, this method added to Patrius throws a Patrius exception about model not supporting time transform.

Here is the list of all possible actual models and the time transform support (please note that only dates prior to 2010 won't support time transformation) :

{| class="wikitable"
| Model and associated data file
| Model Name
| Validity Period
| Time transform support
|-
| rowspan="23"|IGRF (''GeoMagneticFieldFactory.getIGRF(..)'' uses IGRF.COF)
| IGRF00
| 1900.0 - 1905.0
| false
|-
| IGRF05
| 1905.0 - 1910.0
| false
|-
| IGRF10
| 1910.0 - 1915.0
| false
|-
|IGRF15
| 1915.0 - 1920.0
| false
|-
|IGRF20
| 1920.0 - 1925.0
| false
|-
|IGRF25
| 1925.0 - 1930.0
| false
|-
|IGRF30
| 1930.0 - 1935.0
| false
|-
|IGRF35
| 1935.0 - 1940.0
| false
|-
|IGRF40
| 1940.0 - 1945.0
| false
|-
|DGRF45
| 1945.0 - 1950.0
| false
|-
|DGRF50
| 1950.0 - 1955.0
| false
|-
|DGRF55
| 1955.0 - 1960.0
| false
|-
|DGRF60
| 1960.0 - 1965.0
| false
|-
|DGRF65
| 1965.0 - 1970.0
| false
|-
|DGRF70
| 1970.0 - 1975.0
| false
|-
|DGRF75
| 1975.0 - 1980.0
| false
|-
|DGRF80
| 1980.0 - 1985.0
| false
|-
|DGRF85
| 1985.0 - 1990.0
| false
|-
|DGRF90
| 1990.0 - 1995.0
| false
|-
|DGRF95
| 1995.0 - 2000.0
| false
|-
|DGRF2000
| 2000.0 - 2005.0
| false
|-
|DGRF2005
| 2005.0 - 2010.0
| false
|-
|IGRF2010
| 2010.0 - 2015.0
| true
|-
| rowspan="1"|WMM (''GeoMagneticFieldFactory.getWMM(..)'' uses WMM.COF)
| WMM2010
| 2010.0 - 2015.0
| true
|}

Precautions :
The method GeoMagneticField.calculateField (final double latitude, final double longitude, final double height) doesn't use SI units. Latitude and longitude are given in degrees, and height is given in kilometers.

== Getting Started ==

==== Code Example ====

The following code sample computes geomagnetic field elements for four (date, position) of a fake trajectory :

<syntaxhighlight lang="java">
public void codeExemple() throws PatriusException {

Utils.setDataRoot("earth");
FramesFactory.setConfiguration(Utils.getIERS2003ConfigurationWOEOP(true));

//Fake trajectory : list of date and list of position
List<AbsoluteDate> dateList = new ArrayList<AbsoluteDate>();
AbsoluteDate initDate = new AbsoluteDate(2010, 1, 1, 12, 0, 0.0, TimeScalesFactory.getTT());

dateList.add(initDate);
dateList.add(new AbsoluteDate(initDate, 600));
dateList.add(new AbsoluteDate(initDate, 1200));
dateList.add(new AbsoluteDate(initDate, 1800));

List<Vector3D> positionList = new ArrayList<Vector3D>();
positionList.add(new Vector3D(6.46885878304673824e+06,-1.88050918456274318e+06, -1.32931592294715829e+04));
positionList.add(new Vector3D(6.58239141552595049e+06,-1.43349476017528563e+06, -1.39460373997706010e+04));
positionList.add(new Vector3D(6.66499609614125639e+06,-9.79745192516532145e+05, -1.45334684008149434e+04));
positionList.add(new Vector3D(6.71628402448997274e+06,-5.21392324304617418e+05, -1.50526405214286660e+04));

// Get the model to the initial date
final GeoMagneticField model = GeoMagneticFieldFactory.getIGRF(dateList.get(0));

// For each date and position, compute the GeoMagneticElement and add it to a list
List<GeoMagneticElements> geoMagList = new ArrayList<GeoMagneticElements>();
int i = 0;
for (AbsoluteDate date : dateList){
geoMagList.add(model.calculateField(positionList.get(i), FramesFactory.getEME2000(), date));
}

// Print each field vector B
for (GeoMagneticElements geoMagElement : geoMagList){
System.out.println(geoMagElement.toString());
}
}
</syntaxhighlight>

This code produces the following standard output :
<syntaxhighlight lang="java">MagneticField[B={29817,109;-2303,065; -9138,097},H=29905,92,F=31270,895,I=-16,991,D=-4,417]
MagneticField[B={29442,018;-2166,283; -8949,299},H=29521,606,F=30848,261,I=-16,864,D=-4,208]
MagneticField[B={29067,408;-1996,393; -8794,324},H=29135,885,F=30434,19,I=-16,796,D=-3,929]
MagneticField[B={28695,713;-1796,821; -8680,411},H=28751,913,F=30033,681,I=-16,799,D=-3,583]</syntaxhighlight>

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

{| class="wikitable"
|-
! scope="col"| Interface
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''Atmosphere'''
|Interface for atmospheric models.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/Atmosphere.html ...]
|-
|'''ExtendedAtmosphere'''
|Interface for atmospheric models with detailed data.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/ExtendedAtmosphere.html ...]
|-
|'''SolarActivityDataProvider'''
|Interface for solar activity data providers, to be used for atmosphere models
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/SolarActivityDataProvider.html ...]
|-
|'''DTM2000InputParameters'''
|Container for solar activity data, compatible with DTM Atmosphere models.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/DTMInputParameters.html ...]
|-
|'''MSISE2000InputParameters'''
|Container for solar activity data, compatible with MSISE2000 Atmosphere model.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/MSISE2000InputParameters.html ...]
|-
|'''OceanTidesCoefficientsProvider'''
|This interface is used to provide ocean tides coefficients.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/tides/coefficients/OceanTidesCoefficientsProvider.html ...]
|-
|'''PotentialCoefficientsProvider'''
|This interface is used to provide gravity field coefficients.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/potential/PotentialCoefficientsProvider.html ...]
|-
|'''VariablePotentialCoefficientsProvider'''
|This interface is used to provide variable gravity field coefficients.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/variations/coefficients/VariablePotentialCoefficientsProvider.html ...]
|-
|'''RadiationSensitive'''
|This interface is used to provide an direct solar radiative pressure model.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/radiation/RadiationSensitive.html ...]
|-
|'''RediffusedRadiationSensitive'''
|This interface is used to provide an rediffused radiative pressure model.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/radiation/RediffusedRadiationSensitive.html ...]
|-
|'''GeoMagneticDataProvider'''
|This interface is a generic geomagnetic data provider.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/models/earth/GeoMagneticDataProvider.html ...]
|}

=== Classes ===
'''Earth potential'''

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''EGMFormatReader'''
|This reader is adapted to the EGM Format.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/potential/EGMFormatReader.html ...]
|-
|'''GravityFieldFactory'''
|Factory used to read gravity field files in several supported formats. '''Main user access point''' : the simple way of reading a potential file is by using this factory.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/potential/GravityFieldFactory.html ...]
|-
|'''VariableGravityFieldFactory'''
|Factory used to read variable gravity field files in several supported formats. '''Main user access point''' : the simple way of reading a variable potential file is by using this factory.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/variations/coefficients/VariableGravityFieldFactory.html ...]
|-
|'''GRGSFormatReader'''
|Reader for the GRGS gravity field format.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/potential/GRGSFormatReader.html ...]
|-
|'''GRGSRL02FormatReader'''
|Reader for the GRGS RL02 variable gravity field format.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/variations/coefficients/GRGSRL02FormatReader.html ...]
|-
|'''ICGEMFormatReader'''
|Reader for the ICGEM gravity field format.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/potential/ICGEMFormatReader.html ...]
|-
|'''PotentialCoefficientsReader'''
|This abstract class represents a Gravitational Potential Coefficients file reader.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/potential/PotentialCoefficientsReader.html ...]
|-
|'''SHMFormatReader'''
|Reader for the SHM gravity field format.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/potential/SHMFormatReader.html ...]
|}

'''Atmosphere Models'''

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''DTM2000'''
|This class implements the DTM2000 atmospheric model.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/DTM2000.html ...]
|-
|'''DTM2012'''
|This class implements the DTM2012 atmospheric model.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/DTM2012.html ...]
|-
|'''JB2006'''
|This class implements the JB2006 atmospheric model.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/JB2006.html ...]
|-
|'''MSISE2000'''
|This class implements the MSIS00 atmospheric model.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/MSISE2000.html ...]
|-
|NRLMSISE00
|This class implements the NRLMSISE 1.0 atmospheric model.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/MSIS/NRLMSISE00.html ...]
|-
|NRLMSISE20
|This class implements the NRLMSISE 2.0 atmospheric model.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/MSIS/NRLMSISE20.html ...]
|-
|'''US76'''
|This class implements the US76 atmospheric model.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/US76.html ...]
|}

'''Solar Activity'''

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''DTMSolarData'''
|This class represents a solar data container adapted for the DTM atmosphere models.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/specialized/DTMSolarData.html ...]
|-
|'''ClassicalMSISE2000SolarData'''
|This class represents a solar data container adapted for the MSISE2000 atmosphere model. The average ap values are computed arithmetically.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/specialized/ClassicalMSISE2000SolarData.html ...]
|-
|'''ContinuousMSISE2000SolarData'''
|This class represents a solar data container adapted for the MSISE2000 atmosphere model. The mean ap values are computed by trapezoidal integration.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/specialized/ContinuousMSISE2000SolarData.html ...]
|-
|'''ACSOLFormatReader'''
|This class reads ACSOL format solar activity data
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/ACSOLFormatReader.html ...]
|-
|'''ConstantSolarActivity'''
|This class represents constant solar activity
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/ConstantSolarActivity.html ...]
|-
|'''NOAAFormatReader'''
|This class reads NOAA format solar activity data
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/NOAAFormatReader.html ...]
|-
|'''SolarActivityDataFactory'''
|Factory used to read solar activity files and return SolarActivityDataProvider
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/SolarActivityDataFactory.html ...]
|-
|'''SolarActivityToolbox'''
|Solar activity toolbox. Has methods to compute mean flux values, to convert from ap to kp.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/SolarActivityToolbox.html ...]
|-
|'''MarshallSolarActivityFutureEstimation'''
|This class reads and provides solar activity data needed by atmospheric models: F107 solar flux and Kp indexes.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/specialized/MarshallSolarActivityFutureEstimation.html ...]
|-
|'''ExtendedSolarActivityWrapper'''
|This class extends a solar activity provider out of its timespan with constant values.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/solarActivity/ExtendedSolarActivityWrapper.html ...]
|}

'''Ocean Tides Coefficients'''

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''FES2004FormatReader'''
|Reader for FES2004 format coefficients files.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/tides/coefficients/FES2004FormatReader.html ...]
|-
|'''OceanTidesCoefficientsFactory'''
|Factory used to read ocean tides coefficients files in different formats and return an OceanTidesCoefficientsProvider.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/tides/coefficients/OceanTidesCoefficientsFactory.html ...]
|-
|'''OceanTidesCoefficientsReader'''
|This abstract class represents a Ocean Tides Coefficients file reader.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/tides/coefficients/OceanTidesCoefficientsReader.html ...]
|-
|'''OceanTidesCoefficientsSet'''
|Represents a line from the ocean tides data file.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/gravity/tides/coefficients/OceanTidesCoefficientsSet.html ...]
|}

'''Geomagnetic Field'''

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''GeoMagneticElements'''
|This class contains all the elements about a magnetic field : the magnetic field vector and associated caracteristics Inclination, Declination, Total Intensity, Horizontal Intensity.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/models/earth/GeoMagneticElements.html ...]
|-
|'''GeoMagneticField'''
|These objects are produced by the factory and are based on a model for a decimal year date and allows to compute GeomagneticElements
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/models/earth/GeoMagneticField.html ...]
|-
|'''GeoMagneticFieldFactory'''
|Factory to produce GeoMagneticField.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/models/earth/GeoMagneticFieldFactory.html ...]
|-
|'''GeoMagneticModelReader'''
|To load the model from an input file
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/models/earth/GeoMagneticModelReader.html ...]
|-
|'''COFFileFormatReader'''
|Class loading the geomagnetic data from COF files.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/models/earth/COFFileFormatReader.html ...]
|}

[[Category:User_Manual_4.18_Orbit_Propagation]]

User Manual 4.18 Events: orbital

2026-06-10T10:28:19Z

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.18}}/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).

==== Safety Margin Detector ====

This detector computes the safety margin ∆ with respect to the escape velocity. Users have the choice between two methods for the safety margin computation:
* INSTANTANEOUS: The safety margin is computed using the spacecraft's current velocity v and the escape velocity v_esc evaluated at the satellite's current position (v_esc=√(2μ/r)): ∆ = v/v_esc-1
* PERICENTRE: The safety margin is computed at the orbit's pericenter (where the satellite speed is maximum) using the orbital eccentricity e: ∆ = √((1+e)/2)-1

Note: For circular orbits (e=0 and v=√(μ/r)), both methods are equivalent and yield ∆ = 1/√2-1.

The g switching function is the difference between the computed safety margin ∆ and a user-defined safety margin threshold t (safetyMarginIn): g = ∆-t

====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.18}}/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.18}}/fr/cnes/sirius/patrius/events/detectors/AlignmentDetector.html AlignmentDetector]
|-
|AltitudeDetector
|This class handles satellite altitude crossing events.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/events/detectors/AltitudeDetector.html AltitudeDetector]
|-
|ApsideDetector
|This class handles satellite apogee and perigee crossing events.
| [{{JavaDoc4.18}}/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.18}}<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.18}}<nowiki>/fr/cnes/sirius/patrius/events/detectors/BodyPointLocalTimeAngleDetector.html BodyPointLocalTimeAngleDetector]</nowiki>
|-
|DateDetector
|This class handles the occurrence of predefined dates.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/events/detectors/DateDetector.html DateDetector]
|-
|EclipseDetector
|This class handles total or partial eclipse events.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/events/detectors/EclipseDetector.html EclipseDetector]
|-
|NodeDetector
|This class handles satellite equator crossing events.
|[{{JavaDoc4.18}}/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.18}}/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.18}}/fr/cnes/sirius/patrius/events/detectors/ExtremaDistanceDetector.html ExtremaDistanceDetector]
|-
| ExtremaLatitudeDetector
|This class handles events representing the reaching of extrema for the geodetic latitude.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/events/detectors/ExtremaLatitudeDetector.html ExtremaLatitudeDetector]
|-
|ExtremaLongitudeDetector
|This class handles events representing the reaching of extrema for the longitude.
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/events/detectors/LatitudeDetector.html LatitudeDetector]
|-
|LongitudeDetector
|This class handles events representing the reaching of a given longitude
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/events/detectors/LongitudeDetector.html LongitudeDetector]
|-
|AnomalyDetector
|This class handles events representing the reaching of an anomaly angle.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/events/detectors/AnomalyDetector.html AnomalyDetector]
|-
|SafetyMarginDetector
| This class handles escape velocity crossing detection.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/events/detectors/SafetyMarginDetector.html SafetyMarginDetector]|-
|-
|AOLDetector
| This class handles events representing the reaching of an argument of latitude value.
|[{{JavaDoc4.18}}/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.18}}/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.18}}/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.18}}/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.18}}/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.18}}/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.18}}/fr/cnes/sirius/patrius/events/detectors/NadirSolarIncidenceDetector.html NadirSolarIncidenceDetector]
|-
|EarthZoneDetector
|This class handles events representing the entering and leaving of earth zones.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/events/EarthZoneDetector.html EarthZoneDetector]
|-
|}
[[Category:User Manual 4.18 Mission]]

User Manual 4.18 Events: orbital

2026-06-10T10:26:54Z

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.18}}/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).

==== Safety Margin Detector ====

This detector computes the safety margin ∆ with respect to the escape velocity. Users have the choice between two methods for the safety margin computation:
* INSTANTANEOUS: The safety margin is computed using the spacecraft's current velocity v and the escape velocity v_esc evaluated at the satellite's current position (v_esc=√(2μ/r)): ∆ = v/v_esc-1
* PERICENTRE: The safety margin is computed at the orbit's pericenter (where the satellite speed is maximum) using the orbital eccentricity e: ∆ = √((1+e)/2)-1

Note: For circular orbits (e=0 and v=√(μ/r)), both methods are equivalent and yield ∆ = 1/√2-1.

The g switching function is the difference between the computed safety margin ∆ and a user-defined safety margin threshold t (safetyMarginIn): g = ∆-t

====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.18}}/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.18}}/fr/cnes/sirius/patrius/events/detectors/AlignmentDetector.html AlignmentDetector]
|-
|AltitudeDetector
|This class handles satellite altitude crossing events.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/events/detectors/AltitudeDetector.html AltitudeDetector]
|-
|ApsideDetector
|This class handles satellite apogee and perigee crossing events.
| [{{JavaDoc4.18}}/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.18}}<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.18}}<nowiki>/fr/cnes/sirius/patrius/events/detectors/BodyPointLocalTimeAngleDetector.html BodyPointLocalTimeAngleDetector]</nowiki>
|-
|DateDetector
|This class handles the occurrence of predefined dates.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/events/detectors/DateDetector.html DateDetector]
|-
|EclipseDetector
|This class handles total or partial eclipse events.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/events/detectors/EclipseDetector.html EclipseDetector]
|-
|NodeDetector
|This class handles satellite equator crossing events.
|[{{JavaDoc4.18}}/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.18}}/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.18}}/fr/cnes/sirius/patrius/events/detectors/ExtremaDistanceDetector.html ExtremaDistanceDetector]
|-
| ExtremaLatitudeDetector
|This class handles events representing the reaching of extrema for the geodetic latitude.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/events/detectors/ExtremaLatitudeDetector.html ExtremaLatitudeDetector]
|-
|ExtremaLongitudeDetector
|This class handles events representing the reaching of extrema for the longitude.
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/events/detectors/LatitudeDetector.html LatitudeDetector]
|-
|LongitudeDetector
|This class handles events representing the reaching of a given longitude
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/events/detectors/LongitudeDetector.html LongitudeDetector]
|-
|AnomalyDetector
|This class handles events representing the reaching of an anomaly angle.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/events/detectors/AnomalyDetector.html AnomalyDetector]
|-
|SafetyMarginDetector
| This class handles escape velocity crossing detection.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/events/detectors/SafetyMarginDetector.html SafetyMarginDetector]|-
|AOLDetector
| This class handles events representing the reaching of an argument of latitude value.
|[{{JavaDoc4.18}}/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.18}}/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.18}}/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.18}}/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.18}}/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.18}}/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.18}}/fr/cnes/sirius/patrius/events/detectors/NadirSolarIncidenceDetector.html NadirSolarIncidenceDetector]
|-
|EarthZoneDetector
|This class handles events representing the entering and leaving of earth zones.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/events/EarthZoneDetector.html EarthZoneDetector]
|-
|}
[[Category:User Manual 4.18 Mission]]

Main differences between V4.18 and V4.17

2026-06-10T10:03:56Z

Admin tsn :

'''PATRIUS''' V4.18 is a major release adding some new features and correcting some bugs.

== New functionalities ==
* Added a new atmospheric model NRLMSIS 2.0, in addition from the existing NRLMSIS 1.0 model. The solar flux and geomagnetic activity inputs are the same for both versions of the MSIS models. Note that the FORTRAN reference model excludes the NO (Nitric Oxide) element. The same applies to the implemented model in PATRIUS, as it is based on the reference model. Other elements (He, O, N2, etc.), as well as pressure and temperature, are however taken into account.

* Added to the ThirdBodyAttraction constructors the ability to provide a specific gravity model for the indirect terms. If none is provided, the gravity model already supplied for the third-body attraction calculation is used to compute the indirect terms (backward compatibility). To disable the computation of indirect terms, a gravity model that does not include harmonics must be provided.
* Added a service to the ApparentRadiusProvider interface to calculate the maximum apparent radius of a body as seen by a satellite. This radius, expressed in meters, corresponds to the maximum distance from the body's center to any point on its surface belonging to the limb ellipse (contour ellipse) viewed by the satellite.
* Added new constructors to the ModelFunction class to enable the optimization of various function types: ℝⁿ → ℝ : MultivariateFunction, ℝ → ℝ : UnivariateFunction and ℝ → ℝⁿ : UnivariateVectorFunction.
* Added support of the method StrictLegsSequence#addAll
* Added systematic acceleration calculation in BSP ephemerides (previously not calculated at all) via Chebyshev polynomial expansion. No regression expected on positions and velocities.
* Added a class SafetyMarginDetector to detect escape limits crossings. User can choose between two methods to compute escape limit: either at the satellite position or at the orbit’s pericenter.
* Allows the user to configure the desired TDB time scale prior to instantiating UserIAUPole, BSPEphemerisLoader, and PosVelChebyshev objects. Dates are initialized within their respective constructors based on this TDB scale, rather than being handled in a static way.
* New AstronomicalNightDetector detector allowing to find for astronomical dawn and dusk events (independent of the actual spacecraft state).
* Improved matrix toString display: Systematic display of row x column dimensions and large/small numbers are shown in scientific notation without numerical approximation for computing formats (JAVA, OCTAVE, SCILAB and NUMPY).
* Added support for the Alpha-5 TLE numbering format, extending the range of supported satellite catalog numbers from [0; 99,999] to [0; 339,999].

== Bugs fixes ==
* In BSPEphemerisLoader, fix the TDB offset extraction by applying a “/ 1000” conversion, fix an error message that could lead to an infinite loop, update the getTDBModel() method so it can be called directly without having to call before the loadCelestialBodyEphemeris method.
* Fix the method FacetBodyShape#getIntersectionPoint which was using a line defined in the wrong coordinate system to compute the closest triangles.
* Fix for reading .bsp files when the binary file format is not declared at the correct index (more robust DafHandleManager method).
* Correction in the AbstractEllipsoidBodyShape#getApparentRadiusDirection method: using the observer's PVCoordinatesProvider instead of the body's (this) as the origin for the first direction vector. This incorrect behavior had an impact when the input direction depended on the observer's trajectory (for example, with a VelocityDirection linked to the observing satellite).
* Added a cache system to store and manage the “other dates” in AbstractSignalPropagationDetector instead of storing them indefinitely in a Map, which could cause large memory consumption during long propagations.
* Added validation checks during orbital parameter construction to prevent the creation of physically inconsistent ApsisOrbit, EquatorialOrbit, or KeplerianOrbit objects.
** KeplerianParameters / EquatorialParameters: the condition “e >= 0” must be satisfied
** ApsisAltitudeParameters / ApsisRadiusParameters: the condition “periapsis > 0” must be satisfied

Main differences between V4.18 and V4.17

2026-06-10T10:03:00Z

Admin tsn :

'''PATRIUS''' V4.18 is a major release adding some new features and correcting some bugs.

== New functionalities ==
* Added a new atmospheric model NRLMSIS 2.0, in addition from the existing NRLMSIS 1.0 model. The solar flux and geomagnetic activity inputs are the same for both versions of the MSIS models.
Note that the FORTRAN reference model excludes the NO (Nitric Oxide) element. The same applies to the implemented model in PATRIUS, as it is based on the reference model. Other elements (He, O, N2, etc.), as well as pressure and temperature, are however taken into account.
* Added to the ThirdBodyAttraction constructors the ability to provide a specific gravity model for the indirect terms. If none is provided, the gravity model already supplied for the third-body attraction calculation is used to compute the indirect terms (backward compatibility). To disable the computation of indirect terms, a gravity model that does not include harmonics must be provided.
* Added a service to the ApparentRadiusProvider interface to calculate the maximum apparent radius of a body as seen by a satellite. This radius, expressed in meters, corresponds to the maximum distance from the body's center to any point on its surface belonging to the limb ellipse (contour ellipse) viewed by the satellite.
* Added new constructors to the ModelFunction class to enable the optimization of various function types: ℝⁿ → ℝ : MultivariateFunction, ℝ → ℝ : UnivariateFunction and ℝ → ℝⁿ : UnivariateVectorFunction.
* Added support of the method StrictLegsSequence#addAll
* Added systematic acceleration calculation in BSP ephemerides (previously not calculated at all) via Chebyshev polynomial expansion. No regression expected on positions and velocities.
* Added a class SafetyMarginDetector to detect escape limits crossings. User can choose between two methods to compute escape limit: either at the satellite position or at the orbit’s pericenter.
* Allows the user to configure the desired TDB time scale prior to instantiating UserIAUPole, BSPEphemerisLoader, and PosVelChebyshev objects. Dates are initialized within their respective constructors based on this TDB scale, rather than being handled in a static way.
* New AstronomicalNightDetector detector allowing to find for astronomical dawn and dusk events (independent of the actual spacecraft state).
* Improved matrix toString display: Systematic display of row x column dimensions and large/small numbers are shown in scientific notation without numerical approximation for computing formats (JAVA, OCTAVE, SCILAB and NUMPY).
* Added support for the Alpha-5 TLE numbering format, extending the range of supported satellite catalog numbers from [0; 99,999] to [0; 339,999].

== Bugs fixes ==
* In BSPEphemerisLoader, fix the TDB offset extraction by applying a “/ 1000” conversion, fix an error message that could lead to an infinite loop, update the getTDBModel() method so it can be called directly without having to call before the loadCelestialBodyEphemeris method.
* Fix the method FacetBodyShape#getIntersectionPoint which was using a line defined in the wrong coordinate system to compute the closest triangles.
* Fix for reading .bsp files when the binary file format is not declared at the correct index (more robust DafHandleManager method).
* Correction in the AbstractEllipsoidBodyShape#getApparentRadiusDirection method: using the observer's PVCoordinatesProvider instead of the body's (this) as the origin for the first direction vector. This incorrect behavior had an impact when the input direction depended on the observer's trajectory (for example, with a VelocityDirection linked to the observing satellite).
* Added a cache system to store and manage the “other dates” in AbstractSignalPropagationDetector instead of storing them indefinitely in a Map, which could cause large memory consumption during long propagations.
* Added validation checks during orbital parameter construction to prevent the creation of physically inconsistent ApsisOrbit, EquatorialOrbit, or KeplerianOrbit objects.
** KeplerianParameters / EquatorialParameters: the condition “e >= 0” must be satisfied
** ApsisAltitudeParameters / ApsisRadiusParameters: the condition “periapsis > 0” must be satisfied

Main differences between V4.18 and V4.17

2026-06-10T09:03:59Z

Admin tsn : Page créée avec « '''PATRIUS''' V4.18 is a major release adding some new features and correcting some bugs. == New functionalities == * When reading SP3 files, if the accuracy was not present, the parsing failed. This behavior has been modified to allow the parsing of files without accuracy. In that case, the accuracy is set to “0”. This is an impossible value of accuracy since in the SP3 file it is expressed as 2^n, so it is easy for the user to id... »

'''PATRIUS''' V4.18 is a major release adding some new features and correcting some bugs.

== New functionalities ==
* When reading SP3 files, if the accuracy was not present, the parsing failed. This behavior has been modified to allow the parsing of files without accuracy. In that case, the accuracy is set to “0”. This is an impossible value of accuracy since in the SP3 file it is expressed as 2^n, so it is easy for the user to identify the values that have not been read.
* To construct a SurfaceDistanceDetector, the CelestialBody attribute has been replaced by a BodyShape. Moreover, the getBody() method from DistanceDetector has been renamed getTarget().
* The LaguerreSolver has been modifier to accept as input the maximum number of iterations allowed as well as multiple initial guesses (and their respective maximum iterations)
* A new solver PolynomialRootsFinder that computes the roots for a polynomial using the eigenvalues of the companion matrix A of the input polynomial has been added to Patrius
* It is now possible to define an extrapolation function builder in TimeStampedInterpolableEphemeris to complete the interpolation with an extrapolation feature on the left and right side of the samples. A new TimeStampedExtrapolationFunctionBuilder interface is created with no standard implementation.
* New feature in ApparentRadiusProvider allowing to compute the apparent radius of the occulting body from the spacecraft (observer) position given a specific direction to describe the computation plane. In comparison, the existing method predefine this plane with the direction of the occulted object. The rest of the method / behavior stays identical.
* BodyShape implements ApparentRadiusProvider and VariableRadiusProvider is deleted.
* New feature RealMatrix#getDeterminant() to compute the determinant value directly from the matrix instead of having to use the appropriate decomposition solver on the matrix. Also, new feature in ArithmeticUtilsTest to compute all the permutations from a double vector (equivalent to “perms” function in MatLab).
* New class AnomalyUtils to centralize every conversion methods between mean, eccentric and true anomalies.
* It is now possible to accept the non-optimal range interpolation in AbstractBoundedPVProvider (i.e. : EphemerisPvLagrange and EphemerisPvHermite)
* New constructors to build a LofOffset directly from a Rotation object
* New constructor in SensorVisibilityDetector to describe the SatToSatLinkType/LinkType (before it was forced to be in SECONDARY_TO_MAIN mode)
* Users can now read special TDB segments contained in BSP files in order to build a TDB model with TT-TDB offsets.
* New body point solar incidence detector based on the angle between the interest point-satellite vector and the interest point-sun vector.
* Possibility to provide an AbstractHarmonicGravityModel to a ThirdBodyAttraction in order to take into account the gravitational effects of the central body on this third body. The implemented modifications model the attraction of the third body γ as follows: γ = γ(third body → spacecraft) - γ(third body → central body).
* CELESTLAB inspired mission analysis functionalities added: InterplanetaryUtils (SOI computation, DV needed to join / leave an hyperbolic orbit from / to an elliptical one), ProgDetectorUtils (EventDetector wrapper used to compute intervals), EventUtils (Computation of shadow zones, visibility windows and geometry between a satellite and its target), KeplerianParamUtils (computation and conversion of several kerplerian orbit characteristics) and KeplerianParamComputer (Computation of all keplerian characteristics pertaining to an orbit defined with a semi-major axis, eccentricity and true anomaly)

== Bugs fixes ==
* The class StrictAttitudeLegsSequence can now be serialized (also, the interfaces MultiEventDetector, TimeSequence & TimeStamped extend Serializable).
* SP3 format expresses the accuracy in mm but Patrius interprets it as m. The conversion was missing.
* The interface MultiOrbitalCovarianceProvider (since 4.16) define a default implementation for its getOrbitalCovarianceProvider method.
* Fix the local time’s signal propagation computation in BodyPointLocalTimeAngleDetector.
* Fix the ConvergenceException exist only when the threshold value is reached in CartesianOrbit#meanToEccentric, CartesianOrbit#meanToHyperbolicEccentric, FacetBodyShape#getApparentRadius, CircularParameters#hyperbolicMeanToEccentric and KeplerianParameters#meanToHyperbolicEccentric
* Generalize the behavior to throw a ConvergenceException when the convergence algorithm failed in AlternateEquinoctialParameters#getLE, CircularParameters#ellipticMeanToEccentric and EquinoctialParameters#meanToEccentric
* Fix the use of the deprecated PatriusMessages.DIMENSIONS_MISMATCH error message using an explicit message instead.
* In AbstractEllipsoidBodyShape#getApparentRadius the ellipsoid’s B radius was defined uncorrectly which may result in incorrect radius computation.
* In the LineMaskingDetector detector, the case when mainElement isn’t null is now well managed.
* In AbstractBodyAttraction, the acceleration derivatives with respect to the parameter K is now computed in the input frame instead of being computed in the body frame.
* In SolarTimeAngleDetector and in AlignmentDetector the sun (respectively the body) is now expressed in the working frame, corresponding to the first pseudo-inertial frame ancestor, when the spacecraft state’s frame isn’t pseudo-inertial.
* Fix the body masking distance and the spacecraft masking distance computation in in SensorVisibilityDetector#g (uses LinkType.DOWNLINK instead of LinkType.UPLINK)
* Fix the UserIAUPole#getAngularCoordinates#ICRF_TO_INERTIAL computation by using Euler angles

Catégorie:User Manual 4.18

2026-06-10T09:03:29Z

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.18_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.18_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.18_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.18_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.18_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.18_Mission|here]].

=== Tools ===
This theme comprises some external tools such as the ephemeris comparator.

The Tools User Manual can be found [[User_Manual_4.18_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.18_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.18|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.18|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.18

2026-06-10T09:03:06Z

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.18]]

Catégorie:Thread Safety 4.18

2026-06-10T09:02:31Z

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.18]]

Catégorie:User Manual 4.18 Attitude

2026-06-10T09:01:59Z

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.18]]

User Manual 4.18 Slew

2026-06-10T09:01: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.18}}/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.18}}/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.18}}/fr/cnes/sirius/patrius/attitudes/AttitudeLeg.html AttitudeLeg]
|-
|'''Slew'''
|This interface implements a generic slew model set.
|[{{JavaDoc4.18}}/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.18}}/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.18}}/fr/cnes/sirius/patrius/attitudes/TabulatedSlew.html TabulatedSlew]
|-
|'''AngularVelocitiesPolynomialSlew'''
|This class implements a generic angular velocities polynomial slew.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/attitudes/AngularVelocitiesPolynomialSlew.html AngularVelocitiesPolynomialSlew]
|-
|'''ConstantSpinSlewComputer'''
|This class computes a constant spin slew into a ConstantSpinSlew.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/attitudes/slew/ConstantSpinSlewComputer.html ConstantSpinSlewComputer]
|-
|'''TwoSpinBiasSlewComputer'''
|This class computes a two spin bias slew into a TabulatedSlew.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/attitudes/slew/TwoSpinBiasSlewComputer.html TwoSpinBiasSlewComputer]
|-
|'''IsisSpinBiasSlewComputer'''
|This class computes an ISIS spin bias slew into a TabulatedSlew.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/attitudes/slew/IsisSpinBiasSlewComputer.html IsisSpinBiasSlewComputer]
|}

[[Category:User_Manual_4.18_Attitude]]

User Manual 4.18 Rotation, AngularCoordinates, Tranform and Attitude : how to use them

2026-06-10T09:01:13Z

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.18}}/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.18}}/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.18}}/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.18}}/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.18_Attitude]]

User Manual 4.18 Orientation

2026-06-10T09:00:49Z

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.18}}/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.18}}/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.18}}/fr/cnes/sirius/patrius/attitudes/orientations/OrientationAngleProvider.html ...]
|-
|'''OrientationAngleLaw'''
|Interface for all orientation angles lasw.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/attitudes/orientations/OrientationAngleLaw.html ...]
|-
|'''OrientationAngleLeg'''
|Interface for all orientation angles legs.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/attitudes/orientations/OrientationAngleLeg.html ...]
|-
|'''OrientationAngleProfile'''
|Interface for all orientation angles profiles.
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/attitudes/OrientationAngleLawLeg.html ...]
|-
|'''OrientationAngleLawLegsSequence'''
|Sequence of Orientation angle legs.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/attitudes/OrientationAngleLawLegsSequence.html ...]
|-
|'''OrientationAngleProfileSequence'''
|Sequence of Orientation angle profiles.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/attitudes/OrientationAngleProfileSequence.html ...]
|}

[[Category:User_Manual_4.18_Attitude]]

User Manual 4.18 Kinematics

2026-06-10T09:00:24Z

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.18}}/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.18}}/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.18}}/fr/cnes/sirius/patrius/attitudes/kinematics/OrientationFunction.html ...]
|-
|'''Vector3DFunction'''
|This interface represents a generic univariate 3-D vector function.
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/attitudes/kinematics/AbstractOrientationFunction.html ...]
|-
|'''AbstractVector3DFunction'''
|This class represents a spin function, or a spin n-th derivative function.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/attitudes/kinematics/AbstractVector3DFunction.html ...]
|}

[[Category:User_Manual_4.18_Attitude]]

User Manual 4.18 Directions

2026-06-10T09:00:01Z

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.18}}/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.18}}/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.18}}/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.18}}/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.18}}/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.18}}/fr/cnes/sirius/patrius/attitudes/directions/MomentumDirection.html ...]
|-
|'''CelestialBodyPolesAxisDirection'''
|Axis of the poles of a celestial body.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/attitudes/directions/CelestialBodyPolesAxisDirection.html ...]
|-
|'''ToCelestialBodyCenterDirection'''
|Vector from the origin to the center of a celestial body.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/attitudes/directions/ToCelestialBodyCenterDirection.html ...]
|-
|'''EarthCenterDirection'''
|Vector from the origin to the center of the Earth central body.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/attitudes/directions/EarthCenterDirection.html ...]
|-
|'''GenericTargetDirection'''
|Defined by a PVCoordinatesProvider target.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/attitudes/directions/GenericTargetDirection.html ...]
|-
|'''BodyPointTargetDirection'''
|Defined by target which is a BodyPoint on a BodyShape.
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/attitudes/directions/GroundVelocityDirection.html ...]
|-
|'''NadirDirection'''
|Defined by the location of the nadir point and the satellite position.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/attitudes/directions/NadirDirection.html ...]
|-
|'''CrossProductDirection'''
|Cross Product of two directions.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/attitudes/directions/CrossProductDirection.html ...]
|-
|'''GlintApproximatePointingDirection'''
|Direction to the Sun specular reflexion point.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/attitudes/directions/GlintApproximatePointingDirection.html ...]
|-
|'''EarthToCelestialBodyCenterDirection'''
|Direction from Earth to the celestial body center.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/attitudes/directions/EarthToCelestialBodyCenterDirection.html ...]
|}

[[Category:User_Manual_4.18_Attitude]]

User Manual 4.18 Attitude Profile

2026-06-10T08:59:40Z

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.18}}/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.18}}/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.18}}/fr/cnes/sirius/patrius/guidance/QuaternionHarmonicProfile.html ...]
|-
|'''QuaternionPolynomialProfile'''
|Object representing a quaternion guidance profile, calculated with polynomials by means of QuaternionPolynomialSegment.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/guidance/QuaternionPolynomialProfile.html ...]
|-
|'''QuaternionDatePolynomialProfile'''
|Object representing a quaternion guidance profile, calculated with polynomials by means of QuaternionDatePolynomialSegment.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/guidance/QuaternionDatePolynomialProfile.html ...]
|-
|'''QuaternionPolynomialSegment'''
|Object representing a quaternion polynomial guidance profile on a segment by means of UnivariateFunction.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/guidance/QuaternionPolynomialSegment.html ...]
|-
|'''QuaternionDatePolynomialSegment'''
|Object representing a quaternion polynomial guidance profile on a segment by means of DatePolynomialFunctionInterface.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/guidance/QuaternionDatePolynomialSegment.html ...]
|-
|'''AngularVelocitiesHarmonicProfile'''
|Represents an angular velocities guidance profile, calculated with Fourier series.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/guidance/AngularVelocitiesHarmonicProfile.html ...]
|-
|'''AngularVelocitiesPolynomialProfile'''
|Represents an angular velocities guidance profile, calculated with polynomial functions.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/guidance/AngularVelocitiesPolynomialProfile.html ...]
|-
|'''AngularVelocitiesPolynomialProfileLeg'''
|Object representing an angular velocity polynomial guidance profile on a segment.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/guidance/AngularVelocitiesPolynomialProfileLeg.html ...]
|}

[[Category:User_Manual_4.18_Attitude]]

User Manual 4.18 Attitude leg

2026-06-10T08:59:20Z

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.18}}/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.18}}/fr/cnes/sirius/patrius/attitudes/package-summary.html Package fr.cnes.sirius.patrius.attitudes]
|-
|Patrius
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/utils/legs/Leg.html ...]
|-
|'''LegsSequence'''
|This interface is a generic interface for any sequence of legs.
|[{{JavaDoc4.18}}/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.18}}/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.18}}/fr/cnes/sirius/patrius/utils/legs/StrictLegsSequence.html ...]
|-
|'''AttitudeLawLeg'''
|Object representing an attitude law for spacecraft attitude field purposes.
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/attitudes/TabulatedAttitude.html ...]
|-
|'''StrictAttitudeLegsSequence'''
|Object representing a sequence of attitude legs.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/attitudes/StrictAttitudeLegsSequence.html ...]
|-
|'''RelativeTabulatedAttitudeLeg'''
|This class implements a tabulated attitude leg with relative dates.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/attitudes/RelativeTabulatedAttitudeLeg.html ...]
|}

[[Category:User_Manual_4.18_Attitude]]

User Manual 4.18 Attitude law

2026-06-10T08:58:56Z

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.18}}/fr/cnes/sirius/patrius/attitudes/package-summary.html Package fr.cnes.sirius.patrius.attitudes] |- |Patrius |[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/attitudes/package-summary.html Package fr.cnes.sirius.patrius.attitudes]
|-
|Patrius
|[{{JavaDoc4.18}}/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.18}}/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.18}}/fr/cnes/sirius/patrius/attitudes/AttitudeLaw.html ...]
|-
|'''AttitudeLawModifier'''
|This interface represents an attitude law provider that modifies/wraps another underlying provider.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/attitudes/AttitudeLawModifier.html ...]
|-
|'''IOrientationLaw'''
|Orientation law.
|[{{JavaDoc4.18}}/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.18}}/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.18}}/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.18}}/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.18}}/fr/cnes/sirius/patrius/attitudes/TwoDirectionAttitudeLaw.html ...]
|-
|'''AttitudeFrame'''
|Spacecraft frame (dynamic frame whose orientation is defined by the attitude law).
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/attitudes/AttitudeFrame.html ...]
|-
|'''OrientationFrame'''
|Spacecraft orientation frame.
|[{{JavaDoc4.18}}/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.18}}/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.18}}/fr/cnes/sirius/patrius/attitudes/BodyCenterGroundPointing.html ...]
|-
|'''CelestialBodyPointed'''
|This class handles a celestial body pointed attitude provider.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/attitudes/CelestialBodyPointed.html ...]
|-
|'''FixedRate'''
|This class handles a simple attitude provider at constant rate around a fixed axis.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/attitudes/FixedRate.html ...]
|-
|'''GroundPointing'''
|This class is a basic model for different kind of ground pointing attitude providers.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/attitudes/GroundPointing.html ...]
|-
|'''GroundPointingWrapper'''
|This class leverages common parts for compensation modes around ground pointing attitudes.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/attitudes/GroundPointingWrapper.html ...]
|-
|'''ConstantAttitudeLaw'''
|This class handles an constant attitude provider.
|[{{JavaDoc4.18}}/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.18}}/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.18}}/fr/cnes/sirius/patrius/attitudes/LofOffsetPointing.html ...]
|-
|'''NadirPointing'''
|This class handles nadir pointing attitude provider.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/attitudes/NadirPointing.html ...]
|-
|'''SpinStabilized'''
|This class handles a spin stabilized attitude provider.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/attitudes/SpinStabilized.html ...]
|-
|'''TargetPointing'''
|This class handles target pointing attitude provider.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/attitudes/TargetPointing.html ...]
|-
|'''TargetGroundPointing'''
|This class handles target ground pointing attitude provider.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/attitudes/TargetPointing.html ...]
|-
|'''YawCompensation'''
|This class handles yaw compensation attitude provider.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/attitudes/YawCompensation.html ...]
|-
|'''YawSteering'''
|This class handles yaw steering attitude law.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/attitudes/YawSteering.html ...]
|-
|'''ComposedAttitudeLaw'''
|Composed attitude law provider.
|[{{JavaDoc4.18}}/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.18}}/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.18}}/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.18}}/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.18}}/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.18}}/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.18}}/fr/cnes/sirius/patrius/attitudes/AeroAttitudeLaw.html ...]
|}

[[Category:User_Manual_4.18_Attitude]]

Catégorie:User Manual 4.18 Flight Dynamics

2026-06-10T08:58:34Z

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.18]]

User Manual 4.18 Time

2026-06-10T08:58:11Z

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.18}}/fr/cnes/sirius/patrius/time/package-summary.html Package fr.cnes.sirius.patrius.time]
|-
|Patrius
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/time/TimeScale.html ...]
|-
|'''TimeStamped'''
|This interface represents objects that have a AbsoluteDate date attached to them.
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/time/AbsoluteDate.html ...]
|-
|'''AbsoluteDateInterval'''
|This class implements an interval based on the AbsoluteDate class.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/time/AbsoluteDateInterval.html ...]
|-
|'''AbsoluteDateIntervalsList'''
|This class represents a list of AbsoluteDateInterval objects.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/time/AbsoluteDateIntervalsList.html ...]
|-
|'''ChronologicalComparator'''
|Comparator for TimeStamped instance.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/time/ChronologicalComparator.html ...]
|-
|'''ComparableInterval'''
|Class describing an interval of Comparable data.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/interval/ComparableInterval.html ...]
|-
|'''DateComponents'''
|Class representing a date broken up as year, month and day components.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/time/DateComponents.html ...]
|-
|'''DateTimeComponents'''
|Holder for date and time components.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/time/DateTimeComponents.html ...]
|-
|'''GalileoScale'''
|Galileo system time scale.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/time/GalileoScale.html ...]
|-
|'''GenericInterval'''
|Generic class to describe an interval.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/utils/GenericInterval.html ...]
|-
|'''GMSTScale'''
|Greenwich Mean Sidereal Time.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/time/GMSTScale.html ...]
|-
|'''GPSScale'''
|GPS time scale.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/time/GPSScale.html ...]
|-
|'''TAIScale'''
|International Atomic Time.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/time/TAIScale.html ...]
|-
|'''TCBScale'''
|Barycentric Coordinate Time.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/time/TCBScale.html ...]
|-
|'''TCGScale'''
|Geocentric Coordinate Time.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/time/TCGScale.html ...]
|-
|'''TDBScale'''
|Barycentric Dynamic Time.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/time/TDBScale.html ...]
|-
|'''TimeComponents'''
|Class representing a time within the day broken up as hour, minute and second components.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/time/TimeComponents.html ...]
|-
|'''TimeScalesFactory'''
|Factory for predefined time scales.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/time/TimeScalesFactory.html ...]
|-
|'''TTScale'''
|Terrestrial Time as defined by IAU(1991) recommendation IV.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/time/TTScale.html ...]
|-
|'''UT1Scale'''
|Universal Time 1.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/time/UT1Scale.html ...]
|-
|'''UTCScale'''
|Coordinated Universal Time.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/time/UTCScale.html ...]
|-
|'''LocalTimeAngle'''
|Local time angle computation methods.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/time/LocalTimeAngle.html ...]
|}

== Tutorials ==
=== Tutorial 1 ===
[[DatesTutorials|Tutoriel sur les dates]]

[[Category:User_Manual_4.18_Flight_Dynamics]]

User Manual 4.18 SpacecraftState

2026-06-10T08:57:45Z

Admin tsn : Page créée avec « __NOTOC__ == Introduction == === Scope === This section describes the SpacecraftState object. === Javadoc === The object [{{JavaDoc4.18}}//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.18}}//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.18}}/fr/cnes/sirius/patrius/propagation/SpacecraftState.html SpacecraftState] is composed of : 
- an [{{JavaDoc4.18}}/fr/cnes/sirius/patrius/orbits/Orbit.html orbit] 
- an [{{JavaDoc4.18}}/fr/cnes/sirius/patrius/attitudes/Attitude.html attitude for forces computation] 
- an [{{JavaDoc4.18}}/fr/cnes/sirius/patrius/attitudes/Attitude.html attitude for events computation] 
- a map of additional states (including mass states added from [{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/propagation/SpacecraftState.html SpacecraftState] is composed of one [{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/attitudes/Attitude.html Attitude] or two different [{{JavaDoc4.18}}/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.18}}/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.18}}/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.18}}/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.18}}/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.18}}/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.18}}/fr/cnes/sirius/patrius/frames/LOFType.html LOFType]). 
- <code>toTransform(Frame, LOFType)</code> : Transform from specified [{{JavaDoc4.18}}/fr/cnes/sirius/patrius/frames/Frame.html Frame] to local orbital frame ([{{JavaDoc4.18}}/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.18}}//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.18}}/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.18}}/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.18}}/fr/cnes/sirius/patrius/attitudes/Attitude.html ...]
|}

[[Category:User_Manual_4.18_Flight_Dynamics]]

User Manual 4.18 Orbits

2026-06-10T08:57:21Z

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.18}}/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.18}}/fr/cnes/sirius/patrius/orbits/Orbit.html ...]
|-
|'''CartesianOrbit'''
|Instant orbit described by its cartesian parameters.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/orbits/CartesianOrbit.html ...]
|-
|'''KeplerianOrbit'''
|Instant orbit described by its keplerian parameters.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/orbits/KeplerianOrbit.html ...]
|-
|'''CircularOrbit'''
|Instant orbit described by its circular parameters.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/orbits/CircularOrbit.html ...]
|-
|'''EquinoctialOrbit'''
|Instant orbit described by its equinoctial parameters.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/orbits/EquinoctialOrbit.html ...]
|-
|'''AlternateEquinoctialOrbit'''
|Instant orbit described by its equinoctial parameters.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/orbits/AlternateEquinoctialOrbit.html ...]
|-
|'''EquatorialOrbit'''
|Instant orbit described by its equatorial parameters.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/orbits/EquatorialOrbit.html ...]
|-
|'''ApsisOrbit'''
|Instant orbit described by its apsis parameters.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/orbits/ApsisOrbit.html ...]
|}

[[Category:User_Manual_4.18_Flight_Dynamics]]

User Manual 4.18 Orbital parameters

2026-06-10T08:56:55Z

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.18}}/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.18}}/fr/cnes/sirius/patrius/orbits/orbitalparameters/CartesianParameters.html ...]
|-
|'''KeplerianParameters'''
|Keplerian parameters object.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/orbits/orbitalparameters/KeplerianParameters.html ...]
|-
|'''CircularParameters'''
|Circular parameters object.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/orbits/orbitalparameters/CircularParameters.html ...]
|-
|'''EquinoctialParameters'''
|Equinoctial parameters object.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/orbits/orbitalparameters/EquinoctialParameters.html ...]
|-
|'''AlternateEquinoctialParameters'''
|Alternate Equinoctial parameters object.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/orbits/orbitalparameters/AlternateEquinoctialParameters.html ...]
|-
|'''StelaEquinoctialParameters'''
|Stela equinoctial parameters object.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/orbits/orbitalparameters/StelaEquinoctialParameters.html ...]
|-
|'''EquatorialParameters'''
|Equatorial parameters object.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/orbits/orbitalparameters/EquatorialParameters.html ...]
|-
|'''ApsisRadiusParameters'''
|Apsis parameters object (using radius).
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/orbits/orbitalparameters/ApsisRadiusParameters.html ...]
|-
|'''ApsisAltitudeParameters'''
|Apsis parameters object (using altitude).
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/orbits/orbitalparameters/ApsisAltitudeParameters.html ...]
|-
|'''ReentryParameters'''
|Reentry parameters object.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/orbits/orbitalparameters/ReentryParameters.html ...]
|}

[[Category:User_Manual_4.18_Flight_Dynamics]]

User Manual 4.18 Frames configuration

2026-06-10T08:56:37Z

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.18}}/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.18}}/fr/cnes/sirius/patrius/frames/configuration/package-summary.html Package fr.cnes.sirius.patrius.frames.configuration]
|-
|Patrius
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/frames/configuration/eop/package-summary.html Package fr.cnes.sirius.patrius.frames.configuration.eop]
|-
|Patrius
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/frames/configuration/tides/package-summary.html Package fr.cnes.sirius.patrius.frames.configuration.tides]
|-
|Patrius
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/frames/configuration/libration/package-summary.html Package fr.cnes.sirius.patrius.frames.configuration.libration]
|-
|Patrius
|[{{JavaDoc4.18}}/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.18}}/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.18}}/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.18}}/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.18}}/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.18}}/fr/cnes/sirius/patrius/frames/configuration/eop/EOPHistory.html EOPHistory] interface represents EOP data. It has two implementations : [{{JavaDoc4.18}}/fr/cnes/sirius/patrius/frames/configuration/eop/EOP1980History.html EOP1980History] and [{{JavaDoc4.18}}/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.18}}/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.18}}/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.18}}/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.18}}/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.18}}/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.18}}/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.18}}/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.18}}/fr/cnes/sirius/patrius/frames/configuration/FramesConfiguration.html ...]
|-
|'''EOPHistory'''
|Interface for retrieving Earth Orientation Parameters history throughout a large time range.
|[{{JavaDoc4.18}}/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.18}}/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.18}}/fr/cnes/sirius/patrius/frames/configuration/precessionnutation/PrecessionNutationModel.html ...]
|-
|'''SPrimeModel'''
|This interface provides the s' correction (used for the following transformation : TIRF -> ITRF).
|[{{JavaDoc4.18}}/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.18}}/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.18}}/fr/cnes/sirius/patrius/frames/configuration/FramesConfigurationBuilder.html ...]
|-
|'''FramesConfigurationFactory'''
|Frames configuration factory. Contains useful configurations.
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/frames/configuration/DiurnalRotation.html ...]
|-
|'''PolarMotion'''
|This class contains the different polar motion corrections (libration, tidal effects, sp correction).
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/frames/configuration/PolarMotion.html ...]
|-
|'''PrecessionNutation'''
|This class contains the precession nutation model used within the FramesConfigurationImplementation class.
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/frames/configuration/libration/IERS2010LibrationCorrection.html ...]
|-
|'''NoLibrationCorrection'''
|This class ignores the libration effects.
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/frames/configuration/precessionnutation/PrecessionNutationConvention.html ...]
|-
|'''IERS20032010PrecessionNutation'''
|Compute the precession nutation correction according to the new IAU-2000 model.
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/frames/configuration/sp/IERS2010SPCorrection.html ...]
|-
|'''NoSpCorrection'''
|This class ignores the quantity s'.
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/frames/configuration/tides/IERS2010TidalCorrection.html ...]
|-
|'''IERS2003TidalCorrection'''
|Compute tidal correction of the pole motion.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/frames/configuration/tides/IERS2003TidalCorrection.html ...]
|-
|'''NoTidalCorrection'''
|This class ignores the tidal effects.
|[{{JavaDoc4.18}}/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.18}}/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.18}}/fr/cnes/sirius/patrius/frames/configuration/eop/EOP2000HistoryConstantOutsideInterval.html ...]
|-
|'''EOPC04FilesLoader'''
| This class is a generic reader for EOPC04 files.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/frames/configuration/eop/EOPC04FilesLoader.html ...]
|}

[[Category:User_Manual_4.18_Flight_Dynamics]]

User Manual 4.18 Frames

2026-06-10T08:56:16Z

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.18}}/fr/cnes/sirius/patrius/frames/package-summary.html Package fr.cnes.sirius.patrius.frames]
|-
|Patrius
|[{{JavaDoc4.18}}/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.18}}/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.18}}/fr/cnes/sirius/patrius/frames/PredefinedFrame.html ...]
|-
|'''CelestialBodyFrame'''
| Class for frames centered on celestial bodies.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/frames/CelestialBodyFrame.html ...]
|-
|'''Frame'''
|Tridimensional references frames class.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/frames/Frame.html ...]
|-
|'''FramesFactory'''
|Factory for predefined reference frames.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/frames/FramesFactory.html ...]
|-
|'''HelmertTransformation'''
|Transformation class for geodetic systems.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/frames/transformations/HelmertTransformation.html ...]
|-
|'''LocalOrbitalFrame'''
|Class for frames moving with an orbiting satellite.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/frames/LocalOrbitalFrame.html ...]
|-
|'''TopocentricFrame'''
|The topocentric frame.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/frames/TopocentricFrame.html ...]
|-
|'''Transform'''
|Transformation class in three dimensional space.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/frames/transformations/Transform.html ...]
|-
|'''H0MinusNProvider'''
|Provider for the "H0-n" frame.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/frames/transformations/H0MinusNProvider.html ...]
|-
|'''H0MinusNFrame'''
|"H0-n" frame.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/frames/H0MinusNFrame.html ...]
|-
|'''TwoDirectionFrame'''
|A generic frame the can be built starting from two directions and two axes.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/frames/TwoDirectionFrame.html ...]
|-
|'''FrameConvention'''
|Enumeration of all frame conventions used in Patrius.
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/frames/SynodicFrame.html ...]
|-
|'''TranslatedFrame'''
|Frame realizing a translation from a parent frame (axis direction remains unchanged).
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/frames/TranslatedFrame.html ...]
|-
|'''GCRFProvider'''
|Provider for the "GCRF" frame (from its parent frame, the EMB frame).
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/frames/transformations/GCRFProvider.html ...]
|-
|'''EMBProvider'''
|Provider for the "EMB" frame (from its parent frame, the ICRF frame).
|[{{JavaDoc4.18}}/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.18_Flight_Dynamics]]

User Manual 4.18 Celestial bodies

2026-06-10T08:55:53Z

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.18}}/fr/cnes/sirius/patrius/bodies/package-summary.html Package fr.cnes.sirius.patrius.bodies]
|-
|Patrius
|[{{JavaDoc4.18}}/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.18}}/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.18}}/fr/cnes/sirius/patrius/bodies/ApparentRadiusProvider.html ...]
|-
|'''BodyShape'''
|Interface representing the rigid surface shape of a natural body.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/bodies/BodyShape.html ...]
|-
|'''CelestialBody'''
|Interface for celestial bodies like Sun, Moon or solar system planets.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/bodies/CelestialBody.html ...]
|-
|'''CelestialBodyEphemeris'''
|Interface for celestial body ephemeris like Sun, Moon or solar system planets.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/bodies/CelestialBodyEphemeris.html ...]
|-
|'''CelestialBodyLoader'''
|Interface for celestial body loaders.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/bodies/CelestialBodyLoader.html ...]
|-
|'''CelestialBodyEphemerisLoader'''
|Interface for celestial body ephemeris loaders.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/bodies/CelestialBodyEphemerisLoader.html ...]
|-
|'''MeshLoader'''
|Interface for FacetCelestialBody mesh provider.
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/bodies/CelestialBodyFactory.html ...]
|-
|'''BodyPoint'''
|Point location relative to a 2D body surface.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/bodies/GeodeticPoint.html ...]
|-
|'''JPLCelestialBodyLoader'''
|Loader for JPL ephemerides binary files (DE 405, DE 406, ...).
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/bodies/JPLCelestialBodyLoader.html ...]
|-
|'''OneAxisEllipsoid'''
|Modeling of a one-axis ellipsoid.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/bodies/OneAxisEllipsoid.html ...]
|-
|'''ThreeAxisEllipsoid'''
|Modeling of a tri-axis ellipsoid.
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/bodies/MeeusSun.html ...]
|-
|'''MeeusMoon'''
|Position of the Moon according to Meeus model.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/bodies/MeeusMoon.html ...]
|-
|'''BasicBoardSun'''
|Direction of the Sun according to a basic board Sun model.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/bodies/BasicBoardSun.html ...]
|-
|'''UserCelestialBody'''
|User-defined celestial body
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/bodies/UserCelestialBody.html ...]
|-
|'''UserIAUPole'''
|User-defined IAU pole motion
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/bodies/UserIAUPole.html ...]
|-
|'''IAUPoleFactory'''
|Factory for retrieval of solar system bodies IAU pole data
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/bodies/IAUPoleFactory.html ...]
|-
|'''IAUPoleFunction'''
|Atomic IAU pole function. IAU pole data is the sum of atomic IAUPoleFunction.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/bodies/IAUPoleFunction.html ...]
|-
|'''FacetBodyShape'''
|Celestial body defined by a mesh.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/bodies/mesh/FacetBodyShape.html ...]
|-
|'''BodyShapeFitter'''
|Fitter for a given body shape provided as input.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/bodies/mesh/BodyShapeFitter.html ...]
|-
|'''Triangle'''
|Unitary facet (triangle) for a FacetCelestialBody.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/bodies/mesh/Triangle.html ...]
|-
|'''ObjMeshLoader'''
|.obj 3D file mesh loader.
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/bodies/mesh/GeodeticMeshLoader.html ...]
|}

[[Category:User_Manual_4.18_Flight_Dynamics]]

Catégorie:User Manual 4.18 Mathematics

2026-06-10T08:55:30Z

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, 8making 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.18]]

User Manual 4.18 Trigonometric Polynomials and Fourier Series

2026-06-10T08:55:03Z

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.18}}/fr/cnes/sirius/patrius/math/analysis/polynomials/package-summary.html Package fr.cnes.sirius.patrius.math.geometry.analysis.polynomials]
|-
|Patrius
|[{{JavaDoc4.18}}/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.18}}/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.18}}/fr/cnes/sirius/patrius/math/analysis//differentiation/UnivariateDifferentiableFunction.html ...]
|-
|'''IntegrableUnivariateFunction'''
|Extension of UnivariateRealFunction representing an integrable univariate function.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/analysis/IntegrableUnivariateFunction.html ...]
|-
|'''UnivariateFunction'''
|Interface representing an univariate function.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/analysis/UnivariateFunction.html ...]
|-
|'''IFastFourierTransformer'''
|Interface representing a FFT.
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/math/analysis/polynomials/FourierDecompositionEngine.html ...]
|-
|'''FourierSeries'''
|This class represents a finite Fourier Series.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/analysis/polynomials/FourierSeries.html ...]
|-
|'''FourierSeriesApproximation'''
|Holder for a UnivariateFunction and its FourierSeries approximation.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/analysis/polynomials/FourierSeriesApproximation.html ...]
|-
|'''TrigonometricPolynomialFunction'''
|This class is the Trigonometric Polynomial Function class.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/analysis/polynomials/TrigonometricPolynomialFunction.html ...]
|-
|'''TrigonometricPolynomialPrimitive'''
|This class represents a Trigonometric Polynomial Primitive.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/analysis/polynomials/TrigonometricPolynomialPrimitive.html ...]
|-
|'''AbstractFastFourierTransformer'''
| Abstract class representing a FFT.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/transform/AbstractFastFourierTransformer.html ...]
|-
|'''FastFourierTransformer'''
| Computes the FFT for real and complex arrays.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/transform/FastFourierTransformer.html ...]
|}

[[Category:User_Manual_4.18_Mathematics]]

User Manual 4.18 Rotations and quaternions

2026-06-10T08:54:35Z

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.18}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/package-summary.html Package fr.cnes.sirius.patrius.math.geometry.euclidean.threed] |- | Patrius |[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/package-summary.html Package fr.cnes.sirius.patrius.math.geometry.euclidean.threed]
|-
| Patrius
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/math/complex/Quaternion.html quaternion]: it is a unit quaternion (a quaternion of norm one). 
The [{{JavaDoc4.18}}/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.18}}/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.18}}/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.18}}/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.18}}//fr/cnes/sirius/patrius/math/geometry/euclidean/threed/Vector3D.html vectors] into other three dimensional [{{JavaDoc4.18}}//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.18}}/fr/cnes/sirius/patrius/math/complex/Quaternion.html ...]
|-
|'''Rotation'''
|This class implements rotations in a three-dimensional space.
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/RotationOrder.html ...]
|}

[[Category:User_Manual_4.18_Mathematics]]

User Manual 4.18 Root-Finding Algorithms

2026-06-10T08:54:11Z

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.18}}/fr/cnes/sirius/patrius/math/analysis/solver/package-summary.html fr.cnes.sirius.patriu... »

__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.18}}/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.18}}/fr/cnes/sirius/patrius/math/analysis/UnivariateFunction.html UnivariateFunction].
The root-finding algorithm is implemented through the [{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/math/analysis/solver/UnivariateSolver.html ...]
|-
|'''UnivariateDifferentiableSolver'''
|Interface for a differentiable univariate real solver
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/math/analysis/solver/BrentSolver.html ...]
|-
|'''NewtonRaphsonSolver'''
|Newton-Raphson solver implementation.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/analysis/solver/NewtonRaphsonSolver.html ...]
|-
|'''BisectionSolver'''
|Bisection solver implementation.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/analysis/solver/BisectionSolver.html ...]
|-
|'''MullerSolver'''
|Müller solver implementation.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/analysis/solver/MullerSolver.html ...]
|-
|'''LaguerreSolver'''
|Laguerre solver implementation.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/analysis/solver/LaguerreSolver.html ...]
|-
|'''PolynomialRootsFinder'''
|PolynomialRootsFinder solver implementation.
|[{{JavaDoc4.18}}/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.18_Mathematics]]

User Manual 4.18 Optimization

2026-06-10T08:53:48Z

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.18}}/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.18}}/fr/cnes/sirius/patrius/math/optim/joptimizer/functions/BarrierFunction.html ...]
|-
|'''ConvexMultivariateRealFunction'''
|Interface for convex multivariate real functions.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/optim/joptimizer/functions/ConvexMultivariateRealFunction.html ...]
|-
|'''MatrixRescaler'''
|An interface to classes that implement an algorithm to rescale matrices.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/optim/joptimizer/algebra/MatrixRescaler.html ...]
|-
|'''StrictlyConvexMultivariateRealFunction'''
|Interface for striclty convex multivariate real functions.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/optim/joptimizer/functions/StrictlyConvexMultivariateRealFunction.html ...]
|-
|'''TwiceDifferentiableMultivariateRealFunction'''
|Interface for twice-differentiable multivariate functions.
|[{{JavaDoc4.18}}/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.18}}/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.18}}/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.18}}/fr/cnes/sirius/patrius/math/optim/joptimizer/algebra/Matrix1NornRescaler.html ...]
|-
|'''FunctionsUtils'''
|Utility class for optimization function building.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/optim/joptimizer/functions/FunctionsUtils.html ...]
|-
|'''LinearMultivariateRealFunction'''
|Represents a function f(x) = q.x + r.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/optim/joptimizer/functions/LinearMultivariateRealFunction.html ...]
|-
|'''LogarithmicBarrier'''
|Default barrier function for the barrier method algorithm.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/optim/joptimizer/functions/LogarithmicBarrier.html ...]
|-
|'''PDQuadraticMultivariateRealFunction'''
|Extends the class QuadraticMultivariateRealFunction with P symmetric and positive definite.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/optim/joptimizer/functions/PDQuadraticMultivariateRealFunction.html ...]
|-
|'''PSDQuadraticMultivariateRealFunction'''
|Extends the class QuadraticMultivariateRealFunction with P symmetric and positive semi-definite.
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/math/optim/joptimizer/functions/QuadraticMultivariateRealFunction.html ...]
|-
|'''AbstractLPOptimizationRequestHandler'''
|Abstract class for Linear Problem Optimization Request Handler.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/optim/joptimizer/optimizers/AbstractLPOptimizationRequestHandler.html ...]
|-
|'''BarrierMethod'''
|Implements the Barrier Method.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/optim/joptimizer/optimizers/BarrierMethod.html ...]
|-
|'''BasicPhaseIBM'''
|Implements the Basic Phase I Method as a Barried Method.
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/math/optim/joptimizer/optimizers/BasicPhaseILPPDM.html ...]
|-
|'''BasicPhaseIPDM'''
|Implements the Basic Phase I Method as a Primal-Dual Method.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/optim/joptimizer/optimizers/BasicPhaseIPDM.html ...]
|-
|'''JOptimizer'''
|Implements the convex optimizer.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/optim/joptimizer/optimizers/JOptimizer.html ...]
|-
|'''LPPresolver'''
|Presolver for a linear problem.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/optim/joptimizer/optimizers/LPPresolver.html ...]
|-
|'''LPPrimalDualMethod'''
|Implements the Primal-dual interior-point method for linear problems.
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/math/optim/joptimizer/optimizers/LPStandardConverter.html ...]
|-
|'''NewtonLEConstrainedFSP'''
|Linear equality constrained newton optimizer, with feasible starting point.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/optim/joptimizer/optimizers/NewtonLEConstrainedFSP.html ...]
|-
|'''NewtonLEConstrainedISP'''
|Linear equality constrained newton optimizer, with infeasible starting point.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/optim/joptimizer/optimizers/NewtonLEConstrainedISP.html ...]
|-
|'''NewtonUnconstrained'''
|Unconstrained newton optimizer.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/optim/joptimizer/optimizers/NewtonUnconstrained.html ...]
|-
|'''OptimizationRequest'''
|Implements an optimization problem.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/optim/joptimizer/optimizers/OptimizationRequest.html ...]
|-
|'''OptimizationRequestHandler'''
|Generic class for optimization process.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/optim/joptimizer/optimizers/OptimizationRequestHandler.html ...]
|-
|'''OptimizationResponse'''
|Optimization process output: stores the solution as well as an exit code.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/optim/joptimizer/optimizers/OptimizationResponse.html ...]
|-
|'''PrimalDualMethod'''
|Implements a primal-dual interior-point method.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/optim/joptimizer/optimizers/PrimalDualMethod.html ...]
|-
|'''AbstractKKTSolver'''
|Abstract class for solving KKT systems.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/optim/joptimizer/solvers/AbstractKKTSolver.html ...]
|-
|'''AugmentedKKTSolver'''
|Extension of AbstractKKTSolver for singular matrix.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/optim/joptimizer/solvers/AugmentedKKTSolver.html ...]
|-
|'''BasicKKTSolver'''
|Extension of AbstractKKTSolver for the basic solver.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/optim/joptimizer/solvers/BasicKKTSolver.html ...]
|-
|'''UpperDiagonalHKKTSolver'''
|Extends the class AbstractKKTSolver for upper diagonal matrix.
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/math/optim/joptimizer/util/ArrayUtils.html ...]
|-
|'''MutableInt'''
|A mutable (int) wrapper.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/optim/joptimizer/util/MutableInt.html ...]
|-
|'''Utils'''
|Utility class.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/optim/joptimizer/util/Utils.html ...]
|}

[[Category:User_Manual_4.18_Mathematics]]

User Manual 4.18 Numerical ordinary differential equations

2026-06-10T08:53:28Z

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.18}}/fr/cnes/sirius/patrius/math/ode/package-summary.html Package fr.cnes.sirius.patrius.math.ode]
|-
|Patrius
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/ode/nonstiff/package-summary.html Package fr.cnes.sirius.patrius.math.ode.nonstiff]
|-
|Patrius
|[{{JavaDoc4.18}}/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.18}}/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.18}}/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.18}}/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.18}}/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.18}}/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.18}}/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.18}}/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.18}}/fr/cnes/sirius/patrius/math/ode/nonstiff/RungeKutta6Integrator.html ...]
|-
|'''DormandPrince54Integrator'''
|This class implements the 5(4) Dormand-Prince integrator for Ordinary Differential Equations.
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/math/ode/nonstiff/DormandPrince853Integrator.html ...]
|-
|'''GraggBulirschStoerIntegrator'''
|This class implements a Gragg-Bulirsch-Stoer integrator for Ordinary Differential Equations.
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/math/ode/nonstiff/RungeKuttaIntegrator.html ...]
|-
|'''CowellIntegrator'''
|This class implements the 2nd order Stormer-Cowell integrator for Ordinary Differential Equations.
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/math/ode/events/EventState.html ...]
|}

[[Category:User_Manual_4.18_Mathematics]]

User Manual 4.18 Numerical differentiation and integration

2026-06-10T08:53:06Z

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.18}}/fr/cnes/sirius/patrius/math/analysis/differentiation/package-summary.html Package fr.cnes.sirius.patrius.math.analysis.differentiation]
|-
|Patrius
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/math/analysis/differentiation/UnivariateFunctionDifferentiator.html ...]
|-
|UnivariateIntegrator
|Interface for univariate integration algorithms.
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/math/analysis/differentiation/FiniteDifferencesDifferentiator.html ...]
|-
|'''RiddersDifferentiator'''
|Apply the Ridders algorithm to differentiate a function.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/analysis/differentiation/RiddersDifferentiator.html ...]
|-
|TrapezoidIntegrator
|The class implements the Trapezoidal rule
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/analysis/integration/TrapezoidIntegrator.html ...]
|-
|SimpsonIntegrator
|The class implements the Simpson rule
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/analysis/integration/SimpsonIntegrator.html ...]
|}

[[Category:User_Manual_4.18_Mathematics]]

User Manual 4.18 Matrices

2026-06-10T08:52:41Z

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.18}}/fr/cnes/sirius/patrius/math/linear/package-summary.html Package fr.cnes.sirius.patrius.math.linear] |- | Patrius |[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/math/linear/package-summary.html Package fr.cnes.sirius.patrius.math.linear]
|-
| Patrius
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/math/geometry/Vector.html ...]
|-
|'''RealMatrix'''
|Interface defining a real-valued matrix with basic algebraic operations.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/linear/RealMatrix.html ...]
|-
|'''SymmetricMatrix'''
| Interface for symmetric matrices.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/linear/SymmetricMatrix.html ...]
|-
|'''SymmetricPositiveMatrix'''
| Interface for symmetric positive matrices.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/linear/SymmetricPositiveMatrix.html ...]
|-
|'''Decomposition'''
| Interface for matrices decompositions.
|[{{JavaDoc4.18}}/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.18}}/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.18}}/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.18}}/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.18}}/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.18}}/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.18}}/fr/cnes/sirius/patrius/math/linear/ArrayRowSymmetricMatrix.html ...]
|-
|'''DiagonalMatrix'''
| Implementation of a diagonal matrix.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/linear/DiagonalMatrix.html ...]
|-
|'''QRDecomposition'''
|Calculates the QR decomposition of a matrix.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/linear/QRDecomposition.html ...]
|-
|'''LUDecomposition'''
|Calculates the LU decomposition of a matrix.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/linear/LUDecomposition.html ...]
|-
|'''CholeskyDecomposition'''
|Calculates the Cholesky decomposition of a matrix.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/linear/CholeskyDecomposition.html ...]
|-
|'''SingularValueDecomposition'''
|Calculates the SVD decomposition of a matrix.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/linear/SingularValueDecomposition.html ...]
|}

[[Category:User_Manual_4.18_Mathematics]]

User Manual 4.18 Math frameworks

2026-06-10T08:52:17Z

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.18}}/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.18}}/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.18}}/fr/cnes/sirius/patrius/math/MathLib.html ...]
|-
|'''MathLibraryType'''
|Enumeration for currently available Math framework in PATRIUS
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/framework/MathLibraryType.html ...]
|-
|'''FastMathWrapper'''
|Wrapper of FastMath class implementing MathLibrary interface
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/framework/FastMathWrapper.html ...]
|-
|'''MathWrapper'''
|Wrapper of Math class implementing MathLibrary interface
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/framework/MathWrapper.html ...]
|-
|'''StrictMathWrapper'''
|Wrapper of StrictMath class implementing MathLibrary interface
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/framework/StrictMathWrapper.html ...]
|-
|'''JafamaFastMathWrapper'''
|Wrapper of Jafama FastMath class implementing MathLibrary interface
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/framework/JafamaFastMathWrapper.html ...]
|-
|'''JafamaStrictFastMathWrapper'''
|Wrapper of Jafama StrictFastMath class implementing MathLibrary interface
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/framework/JafamaStrictFastMathWrapper.html ...]
|-
|'''FastestMathLibWrapper'''
|Implementation wrapping the fastest implementation among Math, FastMath, StrictMath and Jafama for each function
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/framework/FastestMathLibWrapper.html ...]
|-
|'''FastMath'''
|Original class from PATRIUS providing low-level math functions
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/FastMath.html ...]
|}

[[Category:User_Manual_4.18_Mathematics]]

User Manual 4.18 Interpolation Methods

2026-06-10T08:51:54Z

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.18}}/fr/cnes/sirius/patrius/math/analysis/interpolation/package-summary.html Package fr.cnes.sirius.patrius.math.analysis.interpolation]
|-
| Patrius
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/analysis/interpolation/package-summary.html Package fr.cnes.sirius.patrius.math.analysis.interpolation]
|-
| Patrius
|[{{JavaDoc4.18}}/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.18}}/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.18}}/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.18}}/fr/cnes/sirius/patrius/math/analysis/interpolation/TrivariateGridInterpolator.html ...]
|-
|'''UnivariateFunction'''
|Interface for a univariate function
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/math/analysis/interpolation/SplineInterpolator.html ...]
|-
|'''BicubicSplineInterpolator'''
|Bicubic spline interpolator for a bivariate real function.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/analysis/interpolation/BicubicSplineInterpolator.html ...]
|-
|'''TricubicSplineInterpolator'''
|Tricubic spline interpolator for a trivariate real function.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/analysis/interpolation/TricubicSplineInterpolator.html ...]
|-
|'''PolynomialFunctionLagrangeForm'''
|Lagrange interpolator, directly usable as a univariate real function.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/analysis/polynomials/PolynomialFunctionLagrangeForm.html ...]
|-
|'''PolynomialFunctionNewtonForm'''
|Newton interpolator, directly usable as a univariate real function.
|[{{JavaDoc4.18}}/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.18}}/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.18}}/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.18}}/fr/cnes/sirius/patrius/math/analysis/interpolation/AbstractLinearIntervalsFunction.html ...]
|-
|'''UniLinearIntervalsFunction'''
| Linear one-dimensional function.
| [{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/analysis/interpolation/UniLinearIntervalsFunction.html ...]
|-
|'''BiLinearIntervalsFunction'''
|Linear two-dimensional function.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/analysis/interpolation/BiLinearIntervalsFunction.html ...]
|-
|'''TriLinearIntervalsFunction'''
|Linear three-dimensional function.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/analysis/interpolation/TriLinearIntervalsFunction.html ...]
|-
|'''UniLinearIntervalsInterpolator'''
|Interpolator of linear one-dimensional functions.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/analysis/interpolation/UniLinearIntervalsInterpolator.html ...]
|-
|'''BiLinearIntervalsInterpolator'''
|Interpolator of linear two-dimensional functions.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/analysis/interpolation/BiLinearIntervalsInterpolator.html ...]
|-
|'''TriLinearIntervalsInterpolator'''
|Interpolator of linear three-dimensional functions.
|[{{JavaDoc4.18}}/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.18}}/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.18}}<nowiki>/fr/cnes/sirius/patrius/covariance/AbstractOrbitalCovariance.html AbstractOrbitalCovariance]</nowiki>
|-
|'''OrbitalCovariance'''
|Class containing a covariance matrix and its associated Orbit.
|[{{JavaDoc4.18}}<nowiki>/fr/cnes/sirius/patrius/covariance/OrbitalCovariance.html OrbitalCovariance]</nowiki>
|-
|'''MultiOrbitalCovariance'''
|Class containing a covariance matrix associated to multiple orbits
|[{{JavaDoc4.18}}<nowiki>/fr/cnes/sirius/patrius/covariance/MultiOrbitalCovariance.html MultiOrbitalCovariance]</nowiki>
|}

[[Category:User Manual 4.18 Mathematics]]

User Manual 4.18 Geometry

2026-06-10T08:51:25Z

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.18}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/package-summary.html Package fr.cnes.sirius.patrius.math.geometry.euclidean.threed]
|-
|Patrius
|[{{JavaDoc4.18}}/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.18}}/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.18}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/CrossSectionProvider.html ...]
|-
|'''Cylinder'''
|This interface extends the SolidShape interface for the particular case of cylinders.
|[{{JavaDoc4.18}}/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.18}}/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.18}}/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.18}}/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.18}}/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.18}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/Shape.html ...]
|-
|'''SolidShape'''
|This interface extends the Shape interface for the particular cases of solids.
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/Disk.html ...]
|-
|'''Ellipse'''
|The class represent ellipses in a three dimensional space.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/Ellipse.html ...]
|-
|'''Line'''
|The class represent lines in a three dimensional space.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/Line.html ...]
|-
|'''Plane'''
|The class represent planes in a three dimensional space.
|[{{JavaDoc4.18}}/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.18}}/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.18}}/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.18}}/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.18}}/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.18}}/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.18}}/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.18}}/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.18}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/InfiniteRightCircularCone.html ...]
|-
|'''InfiniteEllipticCone'''
|This class is the Infinite Elliptic Cone class.
|[{{JavaDoc4.18}}/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.18}}/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.18}}/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.18}}/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.18}}/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.18}}/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.18}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/Sphere.html ...]
|-
|'''Spheroid'''
|This is the Spheroid (also called Revolved Ellipsoid) class.
|[{{JavaDoc4.18}}/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.18}}/fr/cnes/sirius/patrius/assembly/properties/features/Facet.html ...]
|-
|'''SphericalCap'''
|Implements a representation of a spherical cap solid.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/SphericalCap.html ...]
|-
|'''SphericalCoordinates'''
|Spherical coordinates to Vector3D .
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/geometry/euclidean/threed/SphericalCoordinates.html ...]
|}

[[Category:User_Manual_4.18_Mathematics]]

User Manual 4.18 Double Comparisons

2026-06-10T08:51:01Z

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.18}}/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.18}}/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.18}}/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.18}}/fr/cnes/sirius/patrius/math/Comparators.html ...]
|}

[[Category:User_Manual_4.18_Mathematics]]