Commit 056e774d authored by Luc Maisonobe's avatar Luc Maisonobe
Browse files

Updated documentation.

parent b4032207
Pipeline #1632 passed with stages
in 21 minutes and 51 seconds
...@@ -29,65 +29,56 @@ ...@@ -29,65 +29,56 @@
package org.orekit #ECEBD8 { package org.orekit #ECEBD8 {
interface Propagator {
package propagation #DDEBD8 { + SpacecraftState propagate(AbsoluteDate target)
+MatrixHarvester setupMatricesComputation(name, initialSTM, initialJacobian)
interface Propagator { }
+ SpacecraftState propagate(AbsoluteDate target)
}
Propagator <|.. AbstractPropagator
package integration #CBDBC8 {
interface AdditionalDerivativesProvider {
+String getName()
+boolean yield()
+void derivatives()
}
class AbstractIntegratedPropagator {
+void addAdditionalDerivativesProvider(AdditionalDerivativesProvider provider)
}
AbstractPropagator <|-- AbstractIntegratedPropagator
AdditionalDerivativesProvider <---o AbstractIntegratedPropagator : provider
}
package semianalytical.dsst #CBDBC8 { interface MatricesHarvester {
+void setReferenceState(SpacecraftState state)
+RealMatrix getStateTransitionMatrix(SpacecraftState state)
+RealMatrix getParametersJacobian(SpacecraftState state)
+List<String> getJacobiansColumnsNames()
}
package forces #CCCCC7 { Propagator -right-> MatricesHarvester
interface DSSTForceModel { package integration #DDEBD8 {
+void init(SpacecraftState initialState, AbsoluteDate target) class AbstractIntegratedPropagator {
+Gradient[] getMeanElementRate() +void addAdditionalDerivativesProvider(AdditionalDerivativesProvider provider)
+void updateShortPeriodTerms() }
} interface AdditionalDerivativesProvider {
+String getName()
+yield()
+void derivatives()
}
AbstractIntegratedPropagator o--> AdditionalDerivativesProvider : providers
Propagator <|.. AbstractIntegratedPropagator
}
class DSSTZonal package semianalytical.dsst #DDEBD8 {
DSSTForceModel <|.. DSSTZonal
} class DSSTHarvester
class DSSTPropagator { class DSSTStateTransitionMatrixGenerator {
+void addForceModel(DSSTForceModel model) -List<DSSTForceModel> forceModels
} }
class DSSTPartialDerivativesEquations { class DSSTIntegrableJacobianColumnGenerator {
+void freezeParametersSelection() -String columnName
+void setInitialJacobians(SpacecraftState s0)
+DSSTJacobiansMapper getMapper()
} }
class DSSTJacobiansMapper { class DSSTPropagator
+void getStateJacobian(SpacecraftState state, double[][] dYdY0)
+void getParametersJacobian(SpacecraftState state, double[][] dYdP)
}
AdditionalDerivativesProvider <|.. DSSTPartialDerivativesEquations MatricesHarvester <|.. DSSTHarvester
DSSTPartialDerivativesEquations *--> DSSTForceModel AbstractIntegratedPropagator <|-- DSSTPropagator
AbstractIntegratedPropagator <|-- DSSTPropagator DSSTStateTransitionMatrixGenerator <--o DSSTPropagator
DSSTPropagator *--> DSSTForceModel DSSTIntegrableJacobianColumnGenerator <--o DSSTPropagator
DSSTHarvester <--o DSSTPropagator
AdditionalDerivativesProvider <|.. DSSTStateTransitionMatrixGenerator
AdditionalDerivativesProvider <|.. DSSTIntegrableJacobianColumnGenerator
}
} }
} }
......
...@@ -27,76 +27,60 @@ ...@@ -27,76 +27,60 @@
skinparam PackageFontSize 12 skinparam PackageFontSize 12
skinparam linetype ortho skinparam linetype ortho
package org.orekit #ECEBD8 { package org.orekit.propagation #ECEBD8 {
package forces #DDEBD8 { interface Propagator {
+ SpacecraftState propagate(AbsoluteDate target)
interface ForceModel { +MatrixHarvester setupMatricesComputation(name, initialSTM, initialJacobian)
+void addContribution() }
+FieldVector3D<Gradient> acceleration()
+EventDetector[] getEventsDetectors()
}
package radiation #CBDBC8 {
class SolarRadiationPressure
ForceModel <|.. SolarRadiationPressure
}
interface MatricesHarvester {
+void setReferenceState(SpacecraftState state)
+RealMatrix getStateTransitionMatrix(SpacecraftState state)
+RealMatrix getParametersJacobian(SpacecraftState state)
+List<String> getJacobiansColumnsNames()
} }
package propagation #DDEBD8 {
interface Propagator { Propagator -right-> MatricesHarvester
+ SpacecraftState propagate(AbsoluteDate target)
}
interface MatrixHarvester { package integration #DDEBD8 {
+RealMatrix getStateTransitionMatrix(SpacecraftState state) class AbstractIntegratedPropagator {
+RealMatrix getParametersJacobian(SpacecraftState state) +void addAdditionalDerivativesProvider(AdditionalDerivativesProvider provider)
} }
interface AdditionalDerivativesProvider {
Propagator <|.. AbstractPropagator +String getName()
+yield()
package integration #CBDBC8 { +void derivatives()
interface AdditionalDerivativesProvider {
+String getName()
+yield()
+void derivatives()
}
class AbstractIntegratedPropagator {
+void addAdditionalDerivativesProvider(AdditionalDerivativesProvider provider)
}
AbstractPropagator <|-- AbstractIntegratedPropagator
AdditionalDerivativesProvider <---o AbstractIntegratedPropagator : provider
} }
AbstractIntegratedPropagator o--> AdditionalDerivativesProvider : providers
Propagator <|.. AbstractIntegratedPropagator
}
package numerical #CBDBC8 { package numerical #DDEBD8 {
interface TimeDerivativesEquations { class NumericalPropagationHarvester
+void addKeplerContribution()
+void addNonKeplerianAcceleration()
+void addMassDerivative()
}
class NumericalPropagator { class StateTransitionMatrixGenerator {
+void addForceModel(ForceModel model) -List<ForceModel> forceModels
+MatrixHarvester setupMatricesComputation(name, initialSTM, initialJacobian)
} }
TimeDerivativesEquations <-- ForceModel : contributes class IntegrableJacobianColumnGenerator {
AbstractIntegratedPropagator <|-- NumericalPropagator -String columnName
NumericalPropagator "1..*" *--> ForceModel }
MatrixHarvester <-- NumericalPropagator
NumericalPropagator "1" *--> TimeDerivativesEquations : main
} class NumericalPropagator
}
} MatricesHarvester <|.. NumericalPropagationHarvester
AbstractIntegratedPropagator <|-- NumericalPropagator
StateTransitionMatrixGenerator <--o NumericalPropagator
IntegrableJacobianColumnGenerator <--o NumericalPropagator
NumericalPropagationHarvester <--o NumericalPropagator
AdditionalDerivativesProvider <|.. StateTransitionMatrixGenerator
AdditionalDerivativesProvider <|.. IntegrableJacobianColumnGenerator
package user.application #F3EDF7 { }
class ComplexForceModel #EAE6F7/B9B3D2
ComplexForceModel ..|> ForceModel
} }
@enduml @enduml
...@@ -49,10 +49,14 @@ ...@@ -49,10 +49,14 @@
+boolean hasAdditionalState(final String name) +boolean hasAdditionalState(final String name)
+double[] getAdditionalState(final String name) +double[] getAdditionalState(final String name)
+DoubleArrayDictionary getAdditionalStates() +DoubleArrayDictionary getAdditionalStates()
+SpacecraftState addAdditionalStateDerivative(final String name, final double ... value)
+boolean hasAdditionalStateDerivative(final String name)
+double[] getAdditionalStateDerivative(final String name)
+DoubleArrayDictionary getAdditionalStatesDerivatives()
} }
note bottom note bottom
always immutable always immutable addAdditionalState and
addAdditionalState creates new instances addAdditionalStateDerivative create new instances
end note end note
interface BoundedPropagator { interface BoundedPropagator {
......
...@@ -43,7 +43,7 @@ it can provide only the final state. ...@@ -43,7 +43,7 @@ it can provide only the final state.
step handlers at each finalized step. Users often use this mode with only a single step handlers at each finalized step. Users often use this mode with only a single
call to propagation with the target propagation time representing the end final date. call to propagation with the target propagation time representing the end final date.
The core business of the application is in the step handlers, and the application The core business of the application is in the step handlers, and the application
does not really handle time by itself, it let the propagator do it. does not really handle time by itself, it lets the propagator do it.
* final state only: This method is used when the user wants to completely control the * final state only: This method is used when the user wants to completely control the
evolution of time. The application gives a target time and no step handlers at all. evolution of time. The application gives a target time and no step handlers at all.
...@@ -98,7 +98,7 @@ The next sequence diagram shows a case where users want to control the time loop ...@@ -98,7 +98,7 @@ The next sequence diagram shows a case where users want to control the time loop
from within their application. In this case, the step handlers multiplexer is cleared, from within their application. In this case, the step handlers multiplexer is cleared,
the propagator is called multiple time, and returns states at requested target times. the propagator is called multiple time, and returns states at requested target times.
[without step handlers sequence diagram](../images/design/without-step-handlers-sequence-diagram.png) ![without step handlers sequence diagram](../images/design/without-step-handlers-sequence-diagram.png)
Controlling the time loop at application level by ignoring step handlers and just getting Controlling the time loop at application level by ignoring step handlers and just getting
states at specified times may seem appealing and more natural to most first time Orekit states at specified times may seem appealing and more natural to most first time Orekit
...@@ -161,8 +161,6 @@ There are also several predefined events detectors already available, amongst wh ...@@ -161,8 +161,6 @@ There are also several predefined events detectors already available, amongst wh
and can be used to compute easily operational forecasts, and can be used to compute easily operational forecasts,
* a `FieldOfViewDetector` which is triggered when some target enters or exits a satellite * a `FieldOfViewDetector` which is triggered when some target enters or exits a satellite
sensor Field Of View (any shape), sensor Field Of View (any shape),
* a `CircularFieldOfViewDetector` which is triggered when some target enters or exits a satellite
sensor Field Of View (circular shape),
* a `FootprintOverlapDetector` which is triggered when a sensor Field Of View (any shape, * a `FootprintOverlapDetector` which is triggered when a sensor Field Of View (any shape,
even split in non-connected parts or containing holes) overlaps a geographic zone, which even split in non-connected parts or containing holes) overlaps a geographic zone, which
can be non-convex, split in different sub-zones, have holes, contain the pole, can be non-convex, split in different sub-zones, have holes, contain the pole,
...@@ -186,6 +184,19 @@ There are also several predefined events detectors already available, amongst wh ...@@ -186,6 +184,19 @@ There are also several predefined events detectors already available, amongst wh
* an `AngularSeparationDetector`, which is triggered when angular separation between satellite and * an `AngularSeparationDetector`, which is triggered when angular separation between satellite and
some beacon as seen by an observer goes below a threshold. The beacon is typically the Sun, the some beacon as seen by an observer goes below a threshold. The beacon is typically the Sun, the
observer is typically a ground station observer is typically a ground station
* an `AngularSeparationFromSatelliteDetector`, which is triggered when two moving objects come
close to each other, as seen from spacecraft
* a `FunctionalDetector`, which is triggered according to a user-supplied function, which can
be a simple lambda-expression
* a `GroundAtNightDetector`, which is triggered when at civil, nautical or astronomical
down/dusk times (this is mainly useful for scheduling optical measurements from ground telescopes)
* a `HaloXZPlaneCrossingDetector`, which is triggered when a spacecraft on a halo orbit
crosses the XZ plane
* an `IntersatDirectViewDetector`, which is triggered when two spacecraft are in direct view,
i.e. when the central body limb does not obstruct view
* a `MagneticFieldDetector`, which is triggered when South-Atlantic anomaly frontier is crossed
* a `ParameterDrivenDateIntervalDetector`, which is triggered at time interval boundaries, with
the additional feature that these boundaries can be offset thanks to parameter drivers
An `EventShifter` is also provided in order to slightly shift the events occurrences times. An `EventShifter` is also provided in order to slightly shift the events occurrences times.
A typical use case is for handling operational delays before or after some physical event A typical use case is for handling operational delays before or after some physical event
...@@ -211,6 +222,8 @@ A `BooleanDetector` is provided to combine several other detectors with boolean ...@@ -211,6 +222,8 @@ A `BooleanDetector` is provided to combine several other detectors with boolean
operators `and`, `or` and `not`. This allows for example to detect when a satellite operators `and`, `or` and `not`. This allows for example to detect when a satellite
is both visible from a ground station and out of eclipse. is both visible from a ground station and out of eclipse.
A `NegateDetector` is provided to negate the sign of the switching function `g` of another detector.
Event occurring can be automatically logged using the `EventsLogger` class. Event occurring can be automatically logged using the `EventsLogger` class.
## Additional states ## Additional states
...@@ -377,27 +390,26 @@ called state-transition matrices). This second case especially useful for comput ...@@ -377,27 +390,26 @@ called state-transition matrices). This second case especially useful for comput
of a trajectory with respect to initial state changes or with respect to force models parameters of a trajectory with respect to initial state changes or with respect to force models parameters
changes. changes.
Orekit provides a common way to handle both cases: additional equations. Users can register sets Orekit handle both cases using additional state, which can be either integrated if modeled as additional
of additional equations alongside with additional initial states. These equations will be propagated derivatives providers (for `NumericalPropagator` and `DSSTPropagator`) or computed analytically
by the numerical integrator. They will not be used for step control, though, so integrating with (for analytical propagators). When modelization requires integrating derivatives, the corresponding
or without these equations should not change the trajectory and no tolerance setting is needed for equations and states are not be used for step control, though, so integrating with or without these
them. equations should not change the trajectory and no tolerance setting is needed for them.
One specific implementation of additional equations is the partial derivatives equations which
propagate Jacobian matrices, both with respect to initial state and with respect to force model
parameters.
![partial derivatives class diagram](../images/design/partial-derivatives-class-diagram.png) ![partial derivatives class diagram](../images/design/partial-derivatives-class-diagram.png)
The above class diagram shows the design of the partial derivatives equations. As can be seen, The above class diagram shows how partial derivatives are computed in the case of `NumericalPropagator`.
the numerical propagator provide a way to trigger computation of partial derivatives matrices (State As can be seen, all propagators provide a way to trigger computation of partial derivatives
Transition Matrix and Jacobians with respect to parameters) and provide an opaque `MatrixHarvester` matrices (State Transition Matrix and Jacobians with respect to parameters) by providing an providing an
so users can retrieve these matrices from the propagated states. Internally, the propagator uses opaque `MatrixHarvester` interface users can call to retrieve these matrices from the propagated states.
dedicated classes that implement `AdditionalDerivativesProvider` to model the matrices elements evolution Internally, `NumericalPropagator` references a package private implementation of this interface and uses
and propagate both the main set of equations corresponding to the equations of motion and the as well several other package private classes (`StateTransitionMatrixGenerator` and
additional set corresponding to the Jacobians of the main set. This additional set is therefore `IntegrableJacobianColumnGenerator` to populate the matrices. The helper classes implement
tightly linked to the main set and in particular depends on the selected force models. The various `AdditionalDerivativesProvider` to model the matrices elements evolution and propagate both the main set
force models add their direct contribution directly to the main set, just as in simple propagation. of equations corresponding to the equations of motion and the additional set corresponding to the Jacobians
of the main set. This additional set is therefore tightly linked to the main set and in particular depends
on the selected force models. The various force models add their direct contribution directly to the main
set, just as in simple propagation.
## Semianalytical propagation ## Semianalytical propagation
...@@ -418,7 +430,7 @@ propagation. As can be seen, the process is very close the one for the numerical ...@@ -418,7 +430,7 @@ propagation. As can be seen, the process is very close the one for the numerical
## Field propagation ## Field propagation
Since 9.0, most of the Orekit propagators (in fact all of them except DSST) have both a regular Since 10.0, all of the Orekit propagators have both a regular
version the propagates states based on classical real numbers (i.e. double precision numbers) version the propagates states based on classical real numbers (i.e. double precision numbers)
and a more general version that propagates states based on any class that implements the and a more general version that propagates states based on any class that implements the
`CalculusFieldElement` interface from Hipparchus. Such classes mimic real numbers in the way they `CalculusFieldElement` interface from Hipparchus. Such classes mimic real numbers in the way they
...@@ -449,11 +461,8 @@ main uses in space flight dynamics are ...@@ -449,11 +461,8 @@ main uses in space flight dynamics are
* very fast Monte-Carlo analyses * very fast Monte-Carlo analyses
Orekit implementations of field propagators support all features from classical propagators: Orekit implementations of field propagators support all features from classical propagators:
propagation modes, events (all events detectors), frames transforms, geodetic points. The propagation modes, events (all events detectors), frames transforms, geodetic points. All
propagators available are Keplerian propagator, Eckstein-Heschler propagator, SGP4/SDP4 propagators and all attitude modes are supported.
propagator, and numerical propagator with all Hipparchus integrators (fixed steps or adaptive
stepsizes) and all force models (including all atmosphere models). All attitude modes are
supported.
One must be aware however of the combinatorial explosion of computation size. For p derivation One must be aware however of the combinatorial explosion of computation size. For p derivation
parameters and o order, the number of components computed for each value is given by the parameters and o order, the number of components computed for each value is given by the
...@@ -469,7 +478,7 @@ hundred of times slower than regular propagation, depending on the number of der ...@@ -469,7 +478,7 @@ hundred of times slower than regular propagation, depending on the number of der
payoff is still very important as soon as we evaluate a few hundreds of points. As Monte-Carlo payoff is still very important as soon as we evaluate a few hundreds of points. As Monte-Carlo
analyses more often use several thousands of evaluations, the payoff is really interesting. analyses more often use several thousands of evaluations, the payoff is really interesting.
### Parallel computation ### Tuple computation
Another important implementation of the `CalculusFieldElement` interface is the `Tuple` Another important implementation of the `CalculusFieldElement` interface is the `Tuple`
class, which computes the same operation on a number of components of a tuple, hence class, which computes the same operation on a number of components of a tuple, hence
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment