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 @@
package org.orekit #ECEBD8 {
package propagation #DDEBD8 {
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
}
interface Propagator {
+ SpacecraftState propagate(AbsoluteDate target)
+MatrixHarvester setupMatricesComputation(name, initialSTM, initialJacobian)
}
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 {
+void init(SpacecraftState initialState, AbsoluteDate target)
+Gradient[] getMeanElementRate()
+void updateShortPeriodTerms()
}
package integration #DDEBD8 {
class AbstractIntegratedPropagator {
+void addAdditionalDerivativesProvider(AdditionalDerivativesProvider provider)
}
interface AdditionalDerivativesProvider {
+String getName()
+yield()
+void derivatives()
}
AbstractIntegratedPropagator o--> AdditionalDerivativesProvider : providers
Propagator <|.. AbstractIntegratedPropagator
}
class DSSTZonal
DSSTForceModel <|.. DSSTZonal
package semianalytical.dsst #DDEBD8 {
}
class DSSTHarvester
class DSSTPropagator {
+void addForceModel(DSSTForceModel model)
class DSSTStateTransitionMatrixGenerator {
-List<DSSTForceModel> forceModels
}
class DSSTPartialDerivativesEquations {
+void freezeParametersSelection()
+void setInitialJacobians(SpacecraftState s0)
+DSSTJacobiansMapper getMapper()
class DSSTIntegrableJacobianColumnGenerator {
-String columnName
}
class DSSTJacobiansMapper {
+void getStateJacobian(SpacecraftState state, double[][] dYdY0)
+void getParametersJacobian(SpacecraftState state, double[][] dYdP)
}
class DSSTPropagator
AdditionalDerivativesProvider <|.. DSSTPartialDerivativesEquations
DSSTPartialDerivativesEquations *--> DSSTForceModel
AbstractIntegratedPropagator <|-- DSSTPropagator
DSSTPropagator *--> DSSTForceModel
MatricesHarvester <|.. DSSTHarvester
AbstractIntegratedPropagator <|-- DSSTPropagator
DSSTStateTransitionMatrixGenerator <--o DSSTPropagator
DSSTIntegrableJacobianColumnGenerator <--o DSSTPropagator
DSSTHarvester <--o DSSTPropagator
AdditionalDerivativesProvider <|.. DSSTStateTransitionMatrixGenerator
AdditionalDerivativesProvider <|.. DSSTIntegrableJacobianColumnGenerator
}
}
}
......
......@@ -27,76 +27,60 @@
skinparam PackageFontSize 12
skinparam linetype ortho
package org.orekit #ECEBD8 {
package org.orekit.propagation #ECEBD8 {
package forces #DDEBD8 {
interface ForceModel {
+void addContribution()
+FieldVector3D<Gradient> acceleration()
+EventDetector[] getEventsDetectors()
}
package radiation #CBDBC8 {
class SolarRadiationPressure
ForceModel <|.. SolarRadiationPressure
}
interface Propagator {
+ SpacecraftState propagate(AbsoluteDate target)
+MatrixHarvester setupMatricesComputation(name, initialSTM, initialJacobian)
}
interface MatricesHarvester {
+void setReferenceState(SpacecraftState state)
+RealMatrix getStateTransitionMatrix(SpacecraftState state)
+RealMatrix getParametersJacobian(SpacecraftState state)
+List<String> getJacobiansColumnsNames()
}
package propagation #DDEBD8 {
interface Propagator {
+ SpacecraftState propagate(AbsoluteDate target)
}
Propagator -right-> MatricesHarvester
interface MatrixHarvester {
+RealMatrix getStateTransitionMatrix(SpacecraftState state)
+RealMatrix getParametersJacobian(SpacecraftState state)
package integration #DDEBD8 {
class AbstractIntegratedPropagator {
+void addAdditionalDerivativesProvider(AdditionalDerivativesProvider provider)
}
Propagator <|.. AbstractPropagator
package integration #CBDBC8 {
interface AdditionalDerivativesProvider {
+String getName()
+yield()
+void derivatives()
}
class AbstractIntegratedPropagator {
+void addAdditionalDerivativesProvider(AdditionalDerivativesProvider provider)
}
AbstractPropagator <|-- AbstractIntegratedPropagator
AdditionalDerivativesProvider <---o AbstractIntegratedPropagator : provider
interface AdditionalDerivativesProvider {
+String getName()
+yield()
+void derivatives()
}
AbstractIntegratedPropagator o--> AdditionalDerivativesProvider : providers
Propagator <|.. AbstractIntegratedPropagator
}
package numerical #CBDBC8 {
package numerical #DDEBD8 {
interface TimeDerivativesEquations {
+void addKeplerContribution()
+void addNonKeplerianAcceleration()
+void addMassDerivative()
}
class NumericalPropagationHarvester
class NumericalPropagator {
+void addForceModel(ForceModel model)
+MatrixHarvester setupMatricesComputation(name, initialSTM, initialJacobian)
class StateTransitionMatrixGenerator {
-List<ForceModel> forceModels
}
TimeDerivativesEquations <-- ForceModel : contributes
AbstractIntegratedPropagator <|-- NumericalPropagator
NumericalPropagator "1..*" *--> ForceModel
MatrixHarvester <-- NumericalPropagator
NumericalPropagator "1" *--> TimeDerivativesEquations : main
class IntegrableJacobianColumnGenerator {
-String columnName
}
}
}
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
......@@ -49,10 +49,14 @@
+boolean hasAdditionalState(final String name)
+double[] getAdditionalState(final String name)
+DoubleArrayDictionary getAdditionalStates()
+SpacecraftState addAdditionalStateDerivative(final String name, final double ... value)
+boolean hasAdditionalStateDerivative(final String name)
+double[] getAdditionalStateDerivative(final String name)
+DoubleArrayDictionary getAdditionalStatesDerivatives()
}
note bottom
always immutable
addAdditionalState creates new instances
always immutable addAdditionalState and
addAdditionalStateDerivative create new instances
end note
interface BoundedPropagator {
......
......@@ -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
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
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
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
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.
[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
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
and can be used to compute easily operational forecasts,
* a `FieldOfViewDetector` which is triggered when some target enters or exits a satellite
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,
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,
......@@ -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
some beacon as seen by an observer goes below a threshold. The beacon is typically the Sun, the
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.
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
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.
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.
## Additional states
......@@ -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
changes.
Orekit provides a common way to handle both cases: additional equations. Users can register sets
of additional equations alongside with additional initial states. These equations will be propagated
by the numerical integrator. They will not be used for step control, though, so integrating with
or without these 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.
Orekit handle both cases using additional state, which can be either integrated if modeled as additional
derivatives providers (for `NumericalPropagator` and `DSSTPropagator`) or computed analytically
(for analytical propagators). When modelization requires integrating derivatives, the corresponding
equations and states are not be used for step control, though, so integrating with or without these
equations should not change the trajectory and no tolerance setting is needed for them.
![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 numerical propagator provide a way to trigger computation of partial derivatives matrices (State
Transition Matrix and Jacobians with respect to parameters) and provide an opaque `MatrixHarvester`
so users can retrieve these matrices from the propagated states. Internally, the propagator uses
dedicated classes that implement `AdditionalDerivativesProvider` to model the matrices elements evolution
and propagate both the main set 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.
The above class diagram shows how partial derivatives are computed in the case of `NumericalPropagator`.
As can be seen, all propagators provide a way to trigger computation of partial derivatives
matrices (State Transition Matrix and Jacobians with respect to parameters) by providing an providing an
opaque `MatrixHarvester` interface users can call to retrieve these matrices from the propagated states.
Internally, `NumericalPropagator` references a package private implementation of this interface and uses
as well several other package private classes (`StateTransitionMatrixGenerator` and
`IntegrableJacobianColumnGenerator` to populate the matrices. The helper classes implement
`AdditionalDerivativesProvider` to model the matrices elements evolution and propagate both the main set
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
......@@ -418,7 +430,7 @@ propagation. As can be seen, the process is very close the one for the numerical
## 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)
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
......@@ -449,11 +461,8 @@ main uses in space flight dynamics are
* very fast Monte-Carlo analyses
Orekit implementations of field propagators support all features from classical propagators:
propagation modes, events (all events detectors), frames transforms, geodetic points. The
propagators available are Keplerian propagator, Eckstein-Heschler propagator, SGP4/SDP4
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.
propagation modes, events (all events detectors), frames transforms, geodetic points. All
propagators and all attitude modes are supported.
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
......@@ -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
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`
class, which computes the same operation on a number of components of a tuple, hence
......
Markdown is supported
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