Patrius - Modifications récentes [fr]

Main differences between V4.18 and V4.17

Admin tsn — Wed, 10 Jun 2026 14:04:05 GMT

← Version précédente		Version du 10 juin 2026 à 14:04
(2 versions intermédiaires par le même utilisateur non affichées)
Ligne 10 :		Ligne 10 :
	* Added systematic acceleration calculation in BSP ephemerides (previously not calculated at all) via Chebyshev polynomial expansion. No regression expected on positions and velocities.		* 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.		* 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).		* 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).		* 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].		* 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 ==		== Bugs fixes ==
Ligne 21 :		Ligne 21 :
	* 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).		* 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 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.		* 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		** KeplerianParameters / EquatorialParameters: the condition “e >= 0” must be satisfied
	** ApsisAltitudeParameters / ApsisRadiusParameters: the condition “periapsis > 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.

Catégorie:Tutorials 4.18

Admin tsn — Wed, 10 Jun 2026 11:02:12 GMT

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] »

Nouvelle 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

Admin tsn — Wed, 10 Jun 2026 11:01:28 GMT

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] »

Nouvelle 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

Admin tsn — Wed, 10 Jun 2026 10:59:55 GMT

Voir les modifications

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

Admin tsn — Wed, 10 Jun 2026 10:53:40 GMT

Admin tsn a téléversé Fichier:Twilight is the period between dawn and sunrise, and between sunset and dusk.png

Nouvelle page

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

User Manual 4.18 Celestial bodies

Admin tsn — Wed, 10 Jun 2026 10:48:39 GMT

← Version précédente		Version du 10 juin 2026 à 10:48
Ligne 405 :		Ligne 405 :
	* 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 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 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.		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.

Ligne 476 :		Ligne 477 :
	* <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>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>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>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>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.

User Manual 4.18 Environment Models

Admin tsn — Wed, 10 Jun 2026 10:43:59 GMT

← Version précédente		Version du 10 juin 2026 à 10:43
(2 versions intermédiaires par le même utilisateur non affichées)
Ligne 118 :		Ligne 118 :
	===== MSIS2000 Atmosphere model =====		===== MSIS2000 Atmosphere model =====

	The ~~NRLMSISE-00~~ empirical atmosphere ~~model was developed by Mike Picone~~, ~~Alan Hedin~~, and ~~Doug Drob. It describes~~ the ~~neutral temperature and densities in Earth's atmosphere from~~ ground to ~~thermospheric heights~~. (~~quoted from [http://nssdc~~.~~gsfc~~.~~nasa~~.~~gov])~~		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.

	More information can be found at the [http://www.nrl.navy.mil/research/nrl-review/2003/atmospheric-science/picone/ Naval Research Laboratory website].		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 :		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])		* 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 Earth model (as a [{{PathCurrentJavaDoc}}/fr/cnes/sirius/patrius/bodies/BodyShape.html BodyShape])
Ligne 146 :		Ligne 160 :

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

	Warning: ~~this~~ 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).		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 ====
Ligne 569 :		Ligne 588 :
	\|-		\|-
	\|'''MSISE2000'''		\|'''MSISE2000'''
	\|This class implements the ~~MSIS00~~ atmospheric model.		\|This class implements the MSIS atmospheric model (from a NRLMSIS sub-model).
	\|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/forces/atmospheres/MSISE2000.html ...]		\|[{{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'''		\|'''US76'''

User Manual 4.18 Events: orbital

Admin tsn — Wed, 10 Jun 2026 10:28:19 GMT

← Version précédente		Version du 10 juin 2026 à 10:28
(Une version intermédiaire par le même utilisateur non affichée)
Ligne 133 :		Ligne 133 :
	* 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.		* 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====		==== 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:		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:
Ligne 274 :		Ligne 274 :

	This solution, also avoids problem about detecting a longitude at PI rad further (that we meet with a sin(a- b) g function).		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====		====AOLDetector====
Ligne 473 :		Ligne 483 :
	\|This class handles events representing the reaching of an anomaly angle.		\|This class handles events representing the reaching of an anomaly angle.
	\|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/events/detectors/AnomalyDetector.html AnomalyDetector]		\|[{{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		\|AOLDetector

Main differences between V4.18 and V4.17

Admin tsn — Wed, 10 Jun 2026 10:03:56 GMT

← Version précédente		Version du 10 juin 2026 à 10:03
(Une version intermédiaire par le même utilisateur non affichée)
Ligne 2 :		Ligne 2 :

	== New functionalities ==		== 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~~.		* 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.
	* 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)~~		* 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.
	* ~~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~~		* 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.
	* 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~~.		* Added new constructors to the ModelFunction class to enable the optimization of various function types: ℝⁿ → ℝ : MultivariateFunction, ℝ → ℝ : UnivariateFunction and ℝ → ℝⁿ : UnivariateVectorFunction.
	* ~~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.~~		* Added support of the method StrictLegsSequence#addAll
	* BodyShape implements ApparentRadiusProvider and VariableRadiusProvider is deleted.		* Added systematic acceleration calculation in BSP ephemerides (previously not calculated at all) via Chebyshev polynomial expansion. No regression expected on positions and velocities.
	* 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~~).		* 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~~ class ~~AnomalyUtils~~ to ~~centralize every conversion methods between mean~~, ~~eccentric~~ and ~~true anomalies~~.		* 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.
	* ~~It is now possible to accept~~ the ~~non-optimal range interpolation~~ in ~~AbstractBoundedPVProvider~~ (i.e. ~~: EphemerisPvLagrange and EphemerisPvHermite)~~		* New AstronomicalNightDetector detector allowing to find for astronomical dawn and dusk events (independent of the actual spacecraft state).
	* ~~New constructors~~ to ~~build a LofOffset directly from a Rotation object~~		* 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).
	* ~~New constructor in SensorVisibilityDetector~~ to ~~describe~~ the ~~SatToSatLinkType/LinkType (before it was forced~~ to ~~be in SECONDARY_TO_MAIN mode)~~		* 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].
	* 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 ==		== Bugs fixes ==
	* ~~The class StrictAttitudeLegsSequence can now be serialized (also~~, the ~~interfaces MultiEventDetector~~, ~~TimeSequence & TimeStamped extend Serializable).~~		* 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.
	* SP3 format expresses the ~~accuracy in mm but Patrius interprets it as m. The conversion was missing.~~		* Fix the method FacetBodyShape#getIntersectionPoint which was using a line defined in the wrong coordinate system to compute the closest triangles.
	* The interface MultiOrbitalCovarianceProvider (~~since 4.16~~) ~~define a default implementation for its getOrbitalCovarianceProvider~~ method.		* Fix for reading .bsp files when the binary file format is not declared at the correct index (more robust DafHandleManager method).
	* Fix the ~~local time’s signal propagation computation~~ in ~~BodyPointLocalTimeAngleDetector~~.		* 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).
	* Fix ~~the ConvergenceException exist only~~ when the ~~threshold value~~ is reached in CartesianOrbit#meanToEccentric, CartesianOrbit#meanToHyperbolicEccentric, FacetBodyShape#getApparentRadius, CircularParameters#hyperbolicMeanToEccentric and KeplerianParameters#meanToHyperbolicEccentric		* 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.
	* ~~Generalize~~ the ~~behavior to throw a ConvergenceException when the convergence algorithm failed in AlternateEquinoctialParameters~~#~~getLE, CircularParameters#ellipticMeanToEccentric and EquinoctialParameters#meanToEccentric~~		* Added validation checks during orbital parameter construction to prevent the creation of physically inconsistent ApsisOrbit, EquatorialOrbit, or KeplerianOrbit objects.
	* Fix the ~~use~~ of the ~~deprecated PatriusMessages~~.~~DIMENSIONS_MISMATCH error message using~~ an ~~explicit message instead.~~		** KeplerianParameters / EquatorialParameters: the condition “e >= 0” must be satisfied
	* In AbstractEllipsoidBodyShape#getApparentRadius the ~~ellipsoid’s B radius was defined uncorrectly which may result in incorrect radius computation.~~		** ApsisAltitudeParameters / ApsisRadiusParameters: the condition “periapsis > 0” must be satisfied
	* 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~~

Main differences between V4.18 and V4.17

Admin tsn — Wed, 10 Jun 2026 09:03:59 GMT

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... »

Nouvelle page

'''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

Admin tsn — Wed, 10 Jun 2026 09:03:29 GMT

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... »

Nouvelle page

== 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

Admin tsn — Wed, 10 Jun 2026 09:03:06 GMT

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... »

Nouvelle page

== 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

Admin tsn — Wed, 10 Jun 2026 09:02:31 GMT

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 |... »

Voir les modifications

Catégorie:User Manual 4.18 Attitude

Admin tsn — Wed, 10 Jun 2026 09:01:59 GMT

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 ==... »

Nouvelle page

== 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

Admin tsn — Wed, 10 Jun 2026 09:01:34 GMT

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... »

Nouvelle page

__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

Admin tsn — Wed, 10 Jun 2026 09:01:13 GMT

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... »

Nouvelle page

__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

Admin tsn — Wed, 10 Jun 2026 09:00:49 GMT

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... »

Nouvelle page

__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

Admin tsn — Wed, 10 Jun 2026 09:00:24 GMT

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... »

Nouvelle page

__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

Admin tsn — Wed, 10 Jun 2026 09:00:01 GMT

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... »

Nouvelle page

__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

Admin tsn — Wed, 10 Jun 2026 08:59:40 GMT

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" |- !... »

Nouvelle page

__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

Admin tsn — Wed, 10 Jun 2026 08:59:20 GMT

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... »

Nouvelle page

__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

Admin tsn — Wed, 10 Jun 2026 08:58:56 GMT

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... »

Nouvelle page

__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

Admin tsn — Wed, 10 Jun 2026 08:58:34 GMT

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... »

Nouvelle page

== 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

Admin tsn — Wed, 10 Jun 2026 08:58:11 GMT

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... »

Nouvelle page

__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

Admin tsn — Wed, 10 Jun 2026 08:57:45 GMT

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... »

Nouvelle page

__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

Admin tsn — Wed, 10 Jun 2026 08:57:21 GMT

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... »

Nouvelle page

__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

Admin tsn — Wed, 10 Jun 2026 08:56:55 GMT

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... »

Nouvelle page

__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

Admin tsn — Wed, 10 Jun 2026 08:56:37 GMT

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... »

Nouvelle page

__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

Admin tsn — Wed, 10 Jun 2026 08:56:16 GMT

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... »

Nouvelle page

__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

Admin tsn — Wed, 10 Jun 2026 08:55:53 GMT

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... »

Voir les modifications

Catégorie:User Manual 4.18 Mathematics

Admin tsn — Wed, 10 Jun 2026 08:55:30 GMT

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... »

Nouvelle page

== 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

Admin tsn — Wed, 10 Jun 2026 08:55:03 GMT

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 |[{... »

Nouvelle page

__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

Admin tsn — Wed, 10 Jun 2026 08:54:35 GMT

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... »

Nouvelle page

__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

Admin tsn — Wed, 10 Jun 2026 08:54:11 GMT

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... »

Nouvelle page

__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

Admin tsn — Wed, 10 Jun 2026 08:53:48 GMT

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... »

Nouvelle page

__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

Admin tsn — Wed, 10 Jun 2026 08:53:28 GMT

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... »

Nouvelle page

__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

Admin tsn — Wed, 10 Jun 2026 08:53:06 GMT

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... »

Nouvelle page

__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

Admin tsn — Wed, 10 Jun 2026 08:52:41 GMT

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/... »

Nouvelle page

__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

Admin tsn — Wed, 10 Jun 2026 08:52:17 GMT

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... »

Nouvelle page

__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

Admin tsn — Wed, 10 Jun 2026 08:51:54 GMT

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="... »

Nouvelle page

__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

Admin tsn — Wed, 10 Jun 2026 08:51:25 GMT

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.... »

Nouvelle page

__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

Admin tsn — Wed, 10 Jun 2026 08:51:01 GMT

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] |}... »

Nouvelle page

__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]]

User Manual 4.18 Dispersions

Admin tsn — Wed, 10 Jun 2026 08:50:41 GMT

Page créée avec « __NOTOC__ == Introduction == === Scope === This section describes how dispersions are defined and used in the PATRIUS library. Dispersions are not to be mixed up with random generation (not detailed in this page). Dispersions always rely on a random generator. === Javadoc === The dispersions objects are available in the package <code>fr.cnes.sirius.patrius.math.random</code>. This package also handles random generation. {| class="wikitable" |- ! scope="col"| Li... »

Nouvelle page

__NOTOC__
== Introduction ==
=== Scope ===
This section describes how dispersions are defined and used in the PATRIUS library.
Dispersions are not to be mixed up with random generation (not detailed in this page). Dispersions always rely on a random generator.

=== Javadoc ===
The dispersions objects are available in the package <code>fr.cnes.sirius.patrius.math.random</code>. This package also handles random generation.

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

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

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

=== Package Overview ===

== Features Description ==
=== Random number generation ===
Distributed random number generation is based on using implementations of interface <code>fr.cnes.sirius.patrius.math.random.NormalizedRandomGenerator</code>.
Each implementation of this interface provides a specific dispersion scheme. For instance, the following code will generate random numbers with Gaussian distribution of mean 0 and unit standard deviation:
<syntaxhighlight lang="java">
final RandomGenerator g = new JDKRandomGenerator();
final NormalizedRandomGenerator generator = new GaussianRandomGenerator(g);
final double value = generator.nextNormalizedDouble();
</syntaxhighlight>

As shown in the above example, building a dispersion object requires a random generator implementing <code>fr.cnes.sirius.patrius.math.random.RandomGenerator</code> interface.

=== Random vector generation ===
Correlated random vector generation is based on using implementations of interface <code>fr.cnes.sirius.patrius.math.random.RandomVectorGenerator</code>.
Each implementation of this interface provides a specific dispersion scheme. For instance, the following code will generate uniformly correlated random vectors according to provided covariance matrix:
<syntaxhighlight lang="java">
final RandomGenerator g = new JDKRandomGenerator();
final RandomVectorGenerator generator = new UniformlyCorrelatedRandomVectorGenerator(mean, covariance, 0, g);
final double[] value = generator.nextVector();
</syntaxhighlight>

As shown in the above example, building a dispersion object requires a random generator implementing <code>fr.cnes.sirius.patrius.math.random.RandomGenerator</code> interface.

=== Correlated random vector generator ===
The user provides a covariance matrix and a random generator. 
'''When using Gaussian correlated random vector generator''':
* The covariance matrix root is extracted using a Cholesky decomposition. The number of columns of the root matrix corresponds to the rank of the provided covariance matrix.
* An uncorrelated vector of size the rank of the covariance matrix is generated using the provided random generator
* The final correlated vector is obtained by multiplying the covariance root matrix by this generated vector.

'''When using uniformly correlated random vector generator''', the process is more complex:
* The covariance matrix is converted into a correlation matrix. Standard deviation vector is extracted from the process. Obtained correlation matrix must be positive semi-definite (all eigenvalues must be non negative).
* Spearman correction is applied to the correlation matrix. If corrected correlation matrix is not positive semi-definite, correction is not applied.
[[File:spearmanCorrection.png|center]]
* The correlation matrix root is extracted using a Cholesky decomposition. The number of columns of the root matrix corresponds to the rank of the correlation matrix.
* A uncorrelated vector of size the rank of the covariance matrix is generated using the provided random generator
* The product of correlation matrix root L and uncorrelated vector T is then transformed to get a uniform law:
[[File:uniformCorrection.png|center]]
* The final correlated vector is obtained by linearly multiplying z by the standard deviation vector.

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

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

{| class="wikitable"
|-
! scope="col"| Interface
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''NormalizedRandomGenerator'''
|Interface for normalized random generators
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/random/NormalizedRandomGenerator.html ...]
|-
|'''RandomVectorGenerator'''
|Interface for random vector generators
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/random/RandomVectorGenerator.html ...]
|}

Note: interface for random number generators is <code>fr.cnes.sirius.patrius.math.random.RandomGenerator</code>.

=== Classes ===
The library defines the following classes related to dispersions:

{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''GaussianRandomGenerator'''
|Generator following Gaussian distribution
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/random/GaussianRandomGenerator.html ...]
|-
|'''UniformRandomGenerator'''
|Generator following uniform distribution
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/random/UniformRandomGenerator.html ...]
|-
|'''UncorrelatedRandomVectorGenerator'''
|Generator for Gaussian uncorrelated vectors
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/random/UncorrelatedRandomVectorGenerator.html ...]
|-
|'''CorrelatedRandomVectorGenerator'''
|Generator for Gaussian correlated vectors
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/random/CorrelatedRandomVectorGenerator.html ...]
|-
|'''UniformlyCorrelatedRandomVectorGenerator'''
|Generator for uniformly correlated vectors
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/random/UniformlyCorrelatedRandomVectorGenerator.html ...]
|-
|'''UnitSphereRandomVectorGenerator'''
|Generator for vectors isotropically located on a sphere
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/random/UnitSphereRandomVectorGenerator.html ...]
|}

[[Category:User_Manual_4.18_Mathematics]]

User Manual 4.18 Angles and Intervals

Admin tsn — Wed, 10 Jun 2026 08:50:20 GMT

Page créée avec « __NOTOC__ == Introduction == === Scope === This section describes how angles, intervals and angle intervals are defined and used in the PATRIUS library. === Javadoc === The angle-related objects are available in the package <code>fr.cnes.sirius.patrius.math.interval</code> in the PATRIUS library. The class defining an interval end point, though, is in the package <code>fr.cnes.sirius.patrius.utils</code>. {| class="wikitable" |- ! scope="col"| Library ! scope=... »

Nouvelle page

__NOTOC__
== Introduction ==
=== Scope ===
This section describes how angles, intervals and angle intervals are defined and used in the PATRIUS library.

=== Javadoc ===
The angle-related objects are available in the package <code>fr.cnes.sirius.patrius.math.interval</code> in the PATRIUS library. The class defining an interval end point, though, is in the package <code>fr.cnes.sirius.patrius.utils</code>.

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

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

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

=== Package Overview ===
The package <code>fr.cnes.sirius.patrius.utils</code> contains the class IntervalEndPoint that defines the type of boundary (CLOSED, OPEN) of an interval end.

The package <code>fr.cnes.sirius.patrius.utils</code> contains the actual angle-related classes.

[[File:PATRIMOINESIRIUSSUMDiagAngles.png]]

== Features Description ==
=== Generic intervals ===
An interval is made of two endpoints, and each endpoint may be closed or opened.

This is the most generic implementation of intervals : the class <code>GenericInterval<T></code>. The enumeration provides the endpoint types : CLOSED and OPEN.

This class is meant to be used as a parent class for all intervals implementations.

This class makes no assumption on the nature of the parameter class T, so it may create intervals of anything- but the functionality for this class is limited (we only have getters for the endpoints values, and their type). That's why it's meant to be used as a parent class.

The class is immutable, in the sense that the endpoints objects are set at the interval creation.

'''Mutable types should not be used as endpoint value types!'''

Examples :

<syntaxhighlight lang="java">
final IntervalEndpointType lowType = IntervalEndpointType.OPEN;
final Double lowValue = new Double(34.136);
final IntervalEndpointType upType = IntervalEndpointType.CLOSED;
final Double upValue = new Double(-2.3e34);
// Note the order of values is off : this class cannot enforce an order
final GenericInterval<Double> tgi = new GenericInterval<Double>(lowType, lowValue, upValue, upType);
final Double gLow = tgi.getLowerData();
assertTrue(gLow.equals(lowValue));
</syntaxhighlight>

Please see the Javadoc for more information.

Example with doubles: interval [1.0, 2.0[ :

<syntaxhighlight lang="java">
GenericInterval<Double> interval = new GenericInterval<Double>(IntervalEndpointType.CLOSED, 1.0, 2.0, IntervalEndpointType.OPEN);
</syntaxhighlight>

=== Comparable intervals ===
This implementation of intervals, <syntaxhighlight lang="java">ComparableInterval<T extends Comparable<T>></syntaxhighlight>, is for types implementing the Comparable interface ( for instance : <code>Integer</code>, <code>Double</code>).

This implementation inherits from <code>GenericInterval<T></code>; in addition to inherited capabilities, it enforces a proper order on the lower and upper endpoints. A <code>ComparableInterval</code> can also :

* tell if a given value is inside an interval
* tell if an interval is inside another
* tell if two intervals overlap
* merge two intervals
* ...

Please see the Javadoc for more information.

=== Angle intervals ===
The AngleInterval class represents an interval of doubles that shall be used to deal with angles. It contains the end points values and types (enum OPENED and CLOSED, class IntervalEndPointType), the mid value (“reference”) and the interval length.

=== Angle tools ===
This class is a toolbox containing static methods to perform operations on angles, for instance :

* angleInInterval : sets an angle in an interval modulo 2Pi

Due to numerical quality issues, the algorithm is the following :

- If the interval is of the form [a, a + 2Pi[, then
if x < a and x + 2Pi >= a + 2Pi, the angle is set to a (numerical quality issue due to the non-iqual repartition of real values around lower and upper boundaries)
if x = 2Pi, the angle is set to a
- If the interval is of the form ]a, a + 2Pi], then
if x > a + 2Pi and x – 2Pi <= a, the angle is set to a + 2Pi (numerical quality issue due to the non-iqual repartition of real values around lower and upper boundaries)
if x = a, the angle is set to a + 2Pi
- Else
if x < a, the angle is set to x + 2Pi
if x > a + 2Pi, the angle is set to x- 2Pi
else the angle is x

* angle comparisons
* supplementary, complementary angles computation

== Getting Started ==

=== Comparable intervals ===
Hereunder is given a code example illustrating how the <code>ComparableInterval</code> object behaves:

<syntaxhighlight lang="java">
final Double d1 = new Double(-4.44);
final Double d2 = new Double(2.22);
final Double d3 = new Double(6.23);
final Double d4 = new Double(8.72);
final IntervalEndpointType open = IntervalEndpointType.OPEN;
final IntervalEndpointType closed = IntervalEndpointType.CLOSED;
// Interval : [ -4.44 ; 2.22 [
final ComparableInterval<Double> ti1 = new ComparableInterval<Double>(closed, d1, d2, open);
final Double inside1 = new Double(-4.44);
final Double inside2 = new Double(-2.24);
final Double outside1 = new Double(-0.2313E96);
final Double outside2 = new Double(-4.45);
assertTrue(ti1.contains(inside1));
assertTrue(ti1.contains(inside2));
assertTrue(!ti1.contains(outside1));
assertTrue(!ti1.contains(outside2));
// Two open overlapping intervals
// ] d1 ; d3 [
// ...] d2 ; d4 [
final ComparableInterval<Double> ovo1 = new ComparableInterval<Double>(open, d1, d3, open);
final ComparableInterval<Double> ovo2 = new ComparableInterval<Double>(open, d2, d4, open);
assertTrue(ovo1.overlaps(ovo2));
assertTrue(ovo2.overlaps(ovo1));
// Two closed intervals, first includes second
// [ d1 .....;..... d4 ]
// .....[ d2 ; d3 ]
final ComparableInterval<Double> clos1 = new ComparableInterval<Double>(closed, d1, d4, closed);
final ComparableInterval<Double> clos2 = new ComparableInterval<Double>(closed, d2, d3, closed);
assertTrue(clos1.includes(clos2));
assertTrue(!clos2.includes(clos1));
</syntaxhighlight>

=== Angle intervals ===
Two constructors are available for an AngleInterval instance :

* One needing directly the end points values and types. Its signature is in the writing order. For example, to create [0.0, 2PI[ :

<syntaxhighlight lang="java">
AngleInterval angleInterval1 = new AngleInterval(IntervalEndpointType.CLOSED, 0.0,
MathUtils.TWO_PI, IntervalEndpointType.OPEN);
</syntaxhighlight>

* One needing the reference and length values, and the end points nature. Here, the signature is : “reference”, “length”, “lower end point type”, “upper end point type”. To create [-PI, PI[ :

<syntaxhighlight lang="java">
AngleInterval angleInterval1 = new AngleInterval(0.0, MathUtils.TWO_PI,
IntervalEndpointType.CLOSED, IntervalEndpointType.OPEN);
</syntaxhighlight>

Those constructors throw an exception « MathIllegalArgumentException » if the interval is not valid. It is considered not valid if :

* The length is strictly greater than 2PI
* The length is equal to 2PI and both end points are “closed”
* The length is negative
* The length is zero and at least one end point is opened (an interval with only one double in it is accepted)

Those intervals are impossible to modify once created : they have no setters. To get an interval with different values, a new one shall be constructed.

=== Angle tools ===
==== The method "angleInInterval" ====

The method « angleInInterval » computes the (2PI) modulus of an angle (given as a double) in an angle interval (AngleInterval object) :

* If a (2PI) modulus of the input angle exists in the interval, its value is returned. Because the angles have a maximum length of 2PI with at least an open end point, there can be only one solution.
* If no value in the interval is a solution, it means the operation is impossible with the given inputs, and a « MathIllegalArgumentException » is thrown.

Use example :

<syntaxhighlight lang="java">
try {
// Angle
double angle = 6*FastMath.PI;

// Interval creation
AngleInterval angleInterval = new AngleInterval(IntervalEndpointType.OPEN,
- MathUtils.HALF_PI, MathUtils.HALF_PI, IntervalEndpointType.OPEN);

// angle in interval
double result = AngleTools.angleInInterval(angle, angleInterval);
}
catch (MathIllegalArgumentException e) {
// correct catch!
}

</syntaxhighlight>

« result » value is here 0.0 : the modulus of 6PI in ]-PI/2,-PI/2[

==== Comparisons methods ====

The comparison methods available in the AngleTools class are the same as the one for doubles in the « Comparators » class : relative comparisons using a default epsilon. Input angles are only expressed in the input interval before the comparison.

If the computation in the interval of one of the input angles is not possible, a « MathIllegalArgumentException » is thrown.

Use example :

<syntaxhighlight lang="java">
try {
// Angle
double angle1 = 6*FastMath.PI;
double angle2 = 4*FastMath.PI + 0.1;

// Interval creation
AngleInterval angleInterval = new AngleInterval(IntervalEndpointType.OPEN,
- MathUtils.HALF_PI, MathUtils.HALF_PI, IntervalEndpointType.OPEN);

// angle in interval
boolean isLowerOrEqual = AngleTools.lowerOrEqual(angle1, angle2, angleInterval);
}
catch (MathIllegalArgumentException e) {
// correct catch !
}

</syntaxhighlight>

Both angles are here computable in the given interval. The first one is lower than the second once in the interval : the returned result is “true”

==== Supplementary, complementary and opposite angles ====

The tools box AngleTools proposes the methods to compute supplementary (method supplementaryAngle), complementary (method complementaryAngle) and opposite (method oppositeAngle) angles, taking into account an angle interval (of the type AngleInterval previously described)

Those methods first compute a common supplementary, complementary or opposite angle, and then try to express the result in the given interval. If this last operation is not possible, an exception is thrown (MathIllegalArgumentException).

Use example :

<syntaxhighlight lang="java">
try {
// Interval creation
AngleInterval angleInterval = new AngleInterval(IntervalEndpointType.OPEN,
- MathUtils.HALF_PI, MathUtils.HALF_PI, IntervalEndpointType.OPEN);

// computation
double angle = 3.0/4.0*FastMath.PI + 6.0*FastMath.PI;
double res = AngleTools.supplementaryAngle(angle, angleInterval);

}
catch (MathIllegalArgumentException e) {
// correct catch !

}

</syntaxhighlight>

The result is here computable, its value is PI/4.

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

=== Classes ===
Here is a summary of the most important classes :
{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''IntervalEndpointType'''
|Defines an interval end point as OPEN or CLOSED.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/interval/IntervalEndpointType.html ...]
|-
|'''AngleInterval'''
|Implements an interval of angles, taking angles' modulus into account.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/interval/AngleInterval.html ...]
|-
|'''AngleTools'''
|Provides several angle-related utility methods.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/interval/AngleTools.html ...]
|-
|'''GenericInterval'''
|Implements a generic interval.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/interval/GenericInterval.html ...]
|-
|'''AbsoluteDateInterval'''
|This class implements an interval based on the AbsoluteDate class using the ComparableInterval class.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/time/AbsoluteDateInterval.html ...]
|-
|'''AbsoluteDateIntervalsList'''
|The class describe a list of AbsoluteDateInterval.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/time/AbsoluteDateIntervalList.html ...]
|-
|'''ComparableInterval'''
|The class describe an interval of Comparable data.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/interval/ComparableInterval.html ...]
|-
|'''ComparableIntervalsList'''
|The class describe a list of ComparableInterval.
|[{{JavaDoc4.18}}/fr/cnes/sirius/patrius/math/interval/ComparableIntervalsList.html ...]
|}

[[Category:User_Manual_4.18_Mathematics]]