integrator
¶
This module provides the functionality for creating integrator settings.
Functions¶
|
Creates settings step size validation in a variable step-size integrator. |
Creates settings for integrator step-size control, using element-wise analysis for the propagated states. |
|
Creates settings for integrator step-size control, using element-wise analysis for the propagated states. |
|
Creates settings for integrator step-size control, using block-wise analysis for the propagated states. |
|
Creates settings for integrator step-size control, using block-wise analysis for the propagated states. |
|
Creates settings for integrator step-size control, using block-wise analysis for the propagated states. |
|
Creates settings for integrator step-size control, using block-wise analysis for the propagated states. |
|
Function to generate step size control blocks on position and velocity elements for numerical integration |
|
|
Creates the settings for the Runge-Kutta fixed step size integrator. |
|
Creates the settings for the Runge-Kutta fixed step size integrator. |
|
Creates the settings for the fixed time-step Bulirsch-Stoer integrator. |
|
Creates the settings for the variable time-step Bulirsch-Stoer integrator. |
|
Overloaded function. |
|
Creates the settings for the Adams-Bashforth-Moulton integrator of fixed order. |
|
Creates the settings for the Adams-Bashforth-Moulton fixed-step integrator. |
Creates the settings for the Adams-Bashforth-Moulton fixed-step, fixed-order integrator. |
|
|
Print the Butcher tableau of a given coefficient set. |
|
Overloaded function. |
Overloaded function. |
|
|
Overloaded function. |
- step_size_validation(minimum_step: float, maximum_step: float, minimum_step_size_handling: tudatpy.kernel.numerical_simulation.propagation_setup.integrator.MinimumIntegrationTimeStepHandling = <MinimumIntegrationTimeStepHandling.throw_exception_below_minimum: 0>, accept_infinity_step: bool = False, accept_nan_step: bool = False) tudatpy.kernel.numerical_simulation.propagation_setup.integrator.IntegratorStepSizeValidationSettings ¶
Creates settings step size validation in a variable step-size integrator.
Factory function to create settings step size validation in a variable step-size integrator. The validation model takes the proposed new step size \(\Delta t_{rec}\) as input, and checks if it meets predefined conditions, specifically whether the proposed time step falls in a given predefined range \([\Delta t_{\min}, \Delta t_{\max}]\). This function also provides the option of handling recommended step sizes below \(\Delta t_{\min}\) in various ways, and control on how to deal with recommend Inf/NaN step sizes.
- Parameters:
minimum_step (float) – Value of minimum permitted time step \(\Delta t_{\min}\).
maximum_step (float) – Value of maximum permitted time step \(\Delta t_{\max}\).
minimum_step_size_handling (MinimumIntegrationTimeStepHandling, default = throw_exception_below_minimum) – Entry defining the behaviour when \(\Delta t_{rec}<\Delta t_{\min}\).
accept_infinity_step (bool, default = False) – Entry defining whether to accept a step size of infinity (if False, exception is throw in such cases)
accept_nan_step (bool, default = False) – Entry defining whether to accept a step size of NaN (if False, exception is throw in such cases)
- Returns:
Object containing settings for step-size validation.
- Return type:
- step_size_control_elementwise_scalar_tolerance(relative_error_tolerance: float, absolute_error_tolerance: float, safety_factor: float = 0.8, minimum_factor_increase: float = 0.1, maximum_factor_increase: float = 4.0) tudatpy.kernel.numerical_simulation.propagation_setup.integrator.IntegratorStepSizeControlSettings ¶
Creates settings for integrator step-size control, using element-wise analysis for the propagated states.
Function to create settings for integrator step-size control, using element-wise analysis for the propagated states. For a propagated state \(\mathbf{x}\) with entries \(x_{i}\), and an estimate \(\boldsymbol{\epsilon}\) for the current local error, the following algorithm is performed per element \(i\) to calculate the required error \(\epsilon_{i,req}\) on this element:
\[\epsilon_{i,req}=\epsilon_{r}x_{i}+\epsilon_{a}\]A proposed modification to the step size is then computed, using the most constraining of all state elements
\[\begin{split}\bar{\Delta t_{rec.}}&=\Delta t\left(\min_{i}\left(\frac{\epsilon_{i,req}}{\epsilon_{i}}\right)\right)^{p}\\ \Delta t_{rec.}&=K\bar{\Delta t_{rec.}}\end{split}\]with \(p\) the order of the local truncation error of the method for which step-size control is being applied, \(\Delta t_{rec.}\) the new, recommended step size, and \(\Delta t\) the current step size. The factor \(K\) is a safety factor used make the time step slightly smaller than strictly required.
A minimum and maximum change in time step may be provided by the user, such that if \(\Delta t_{rec.}/\Delta t\) is too large or too small, the proposed increase/decrease to the step size is constrained to this limit value. That is, if \(\Delta t_{rec.}/\Delta t\) proposed by the algorithm is 1000, and the
maximum_factor_increase
input is equal to 20, the algorithm will use \(\Delta t_{rec.}/\Delta t=20\) in what follows.For cases where \(\bar{\Delta t_{rec.}}/\Delta t < 1\), the step is recommended to be recomputed with the new proposed step size (e.g. the current step is not accepted, and will be re-attempted with a smaller step size). For cases where \(\bar{\Delta t_{rec.}}/\Delta t > 1\), the step is accepted, and the next step will be performed with the new, higher, step size.
- Parameters:
relative_error_tolerance (float) – Value of relative error tolerance \(\epsilon_{r}\).
absolute_error_tolerance (float) – Value of absolute error tolerance \(\epsilon_{a}\).
safety_factor (float, default = 0.8) – Safety factor \(K\) for step size control
minimum_factor_increase (float, default = 0.1) – Minimum permissible value for \(\Delta t_{rec.}/\Delta t\)
maximum_factor_increase (float, default = 4.0) – Maximum permissible value for \(\Delta t_{rec.}/\Delta t\)
- Returns:
Object containing settings for per-element step-size control.
- Return type:
- step_size_control_elementwise_matrix_tolerance(relative_error_tolerance: numpy.ndarray[numpy.float64[m, n]], absolute_error_tolerance: numpy.ndarray[numpy.float64[m, n]], safety_factor: float = 0.8, minimum_factor_increase: float = 0.1, maximum_factor_increase: float = 4.0) tudatpy.kernel.numerical_simulation.propagation_setup.integrator.IntegratorStepSizeControlSettings ¶
Creates settings for integrator step-size control, using element-wise analysis for the propagated states.
Function to create settings for integrator step-size control, using element-wise analysis for the propagated states. This function is similar to
step_size_control_elementwise_scalar_tolerance()
, with the differences that the tolerances are provided as a vector/matrix (which must be of equal size as the propagates state), such that different tolerances can be provided for each state element. The behaviour of the algorithm is then such that \(\epsilon_{r}\rightarrow\epsilon_{r,i}\) and \(\epsilon_{a}\rightarrow\epsilon_{a,i}\).If the size of the tolerances used as input differ from one another, or differ from the size of the state vector, an exception is thrown
- Parameters:
relative_error_tolerance (numpy.ndarray[numpy.float64[m, n]]) – Values of relative error tolerance \(\boldsymbol{\epsilon}_{r}\).
absolute_error_tolerance (numpy.ndarray[numpy.float64[m, n]]) – Values of absolute error tolerance \(\boldsymbol{\epsilon}_{a}\).
safety_factor (float, default = 0.8) – Safety factor \(K\) for step size control
minimum_factor_increase (float, default = 0.1) – Minimum permissible value for \(\Delta t_{rec.}/\Delta t\)
maximum_factor_increase (float, default = 4.0) – Maximum permissible value for \(\Delta t_{rec.}/\Delta t\)
- Returns:
Object containing settings for per-element step-size control.
- Return type:
- step_size_control_blockwise_scalar_tolerance(block_indices: list[tuple[int, int, int, int]], relative_error_tolerance: float, absolute_error_tolerance: float, safety_factor: float = 0.8, minimum_factor_increase: float = 0.1, maximum_factor_increase: float = 4.0) tudatpy.kernel.numerical_simulation.propagation_setup.integrator.IntegratorStepSizeControlSettings ¶
Creates settings for integrator step-size control, using block-wise analysis for the propagated states.
Function to create settings for integrator step-size control, using block-wise analysis for the propagated states. This function is similar to
step_size_control_elementwise_scalar_tolerance()
, with the difference that the error estimation \(\boldsymbol{\epsilon}\) is not used on an element-by-element basis, but using the norms of user defined matrix blocks. This is for instance very useful when propagating Cartesian states, where the tolerances are then typically applied twice: once to the norm of the position error, and once to the norm of the velocity error.The algorithm is then run, using the modification that \(\epsilon_{i}\rightarrow||\boldsymbol{\epsilon_{[i,k],[j,l]}}||\). Where the indices on the right-hand side denote start row \(i\), start column \(j\), number of rows \(k\) and number of columns \(l\). over which the state error norm is to be taken. For a single Cartesian state vector, the norm is taken on blocks \([0,3],[0,1]\) and \([3,3],[0,1]\)
- Parameters:
block_indices (list[tuple[int,int,int,int]]) – List of matrix blocks over which the norms are to be taken (with entries of the tuple denoting \(i,j,k,l\), in order.
relative_error_tolerance (float) – Value of relative error tolerance \(\epsilon_{r}\).
absolute_error_tolerance (float) – Value of absolute error tolerance \(\epsilon_{a}\).
safety_factor (float, default = 0.8) – Safety factor \(K\) for step size control
minimum_factor_increase (float, default = 0.1) – Minimum permissible value for \(\Delta t_{rec.}/\Delta t\)
maximum_factor_increase (float, default = 4.0) – Maximum permissible value for \(\Delta t_{rec.}/\Delta t\)
- Returns:
Object containing settings for per-element step-size control.
- Return type:
- step_size_control_blockwise_matrix_tolerance(block_indices: list[tuple[int, int, int, int]], relative_error_tolerance: numpy.ndarray[numpy.float64[m, n]], absolute_error_tolerance: numpy.ndarray[numpy.float64[m, n]], safety_factor: float = 0.8, minimum_factor_increase: float = 0.1, maximum_factor_increase: float = 4.0) tudatpy.kernel.numerical_simulation.propagation_setup.integrator.IntegratorStepSizeControlSettings ¶
Creates settings for integrator step-size control, using block-wise analysis for the propagated states.
Function to create settings for integrator step-size control, using block-wise analysis for the propagated states. This function is similar to
step_size_control_blockwise_scalar_tolerance()
, with the differences that the tolerances are provided as a list (which must be of equal size as the number of state blocks used), such that different tolerances can be provided for each state block.If the size of the tolerances used as input differ from one another, or differ from the number of blocks, an exception is thrown
- Parameters:
block_indices (list[tuple[int,int,int,int]]) – List of matrix blocks over which the norms are to be taken (with entries of the tuple denoting \(i,j,k,l\), in order.
relative_error_tolerance (numpy.ndarray[numpy.float64[m, 1]]) – Values of relative error tolerance \(\boldsymbol{\epsilon}_{r}\).
absolute_error_tolerance (numpy.ndarray[numpy.float64[m, 1]]) – Values of absolute error tolerance \(\boldsymbol{\epsilon}_{a}\).
safety_factor (float, default = 0.8) – Safety factor \(K\) for step size control
minimum_factor_increase (float, default = 0.1) – Minimum permissible value for \(\Delta t_{rec.}/\Delta t\)
maximum_factor_increase (float, default = 4.0) – Maximum permissible value for \(\Delta t_{rec.}/\Delta t\)
- Returns:
Object containing settings for per-element step-size control.
- Return type:
- step_size_control_custom_blockwise_scalar_tolerance(block_indices_function: Callable[[int, int], list[tuple[int, int, int, int]]], relative_error_tolerance: float, absolute_error_tolerance: float, safety_factor: float = 0.8, minimum_factor_increase: float = 0.1, maximum_factor_increase: float = 4.0) tudatpy.kernel.numerical_simulation.propagation_setup.integrator.IntegratorStepSizeControlSettings ¶
Creates settings for integrator step-size control, using block-wise analysis for the propagated states.
Function to create settings for integrator step-size control, using block-wise analysis for the propagated states. This function is similar to
step_size_control_blockwise_scalar_tolerance()
, but rather than providing theblock_indices
directly, a function to determine the block indices, based on the size of the propagated state, is provided. For instance, thestandard_cartesian_state_element_blocks()
can be provided to this function (asblock_indices_function
), which will adapt the block indices depending on the size of the propagated state (e.g. regardless of how many bodies are propagated, step size control will always be done on position and velocity element blocks)- Parameters:
block_indices_function (Callable[[int,int],list[tuple[int,int,int,int]]]) – Function returning list of matrix blocks over which the norms are to be taken (with entries of the tuple denoting \(i,j,k,l\), in order, with number of rows and columns of propagated state as input.
relative_error_tolerance (float) – Value of relative error tolerance \(\epsilon_{r}\).
absolute_error_tolerance (float) – Value of absolute error tolerance \(\epsilon_{a}\).
safety_factor (float, default = 0.8) – Safety factor \(K\) for step size control
minimum_factor_increase (float, default = 0.1) – Minimum permissible value for \(\Delta t_{rec.}/\Delta t\)
maximum_factor_increase (float, default = 4.0) – Maximum permissible value for \(\Delta t_{rec.}/\Delta t\)
- Returns:
Object containing settings for per-element step-size control.
- Return type:
- step_size_control_custom_blockwise_matrix_tolerance(block_indices_function: Callable[[int, int], list[tuple[int, int, int, int]]], relative_error_tolerance: numpy.ndarray[numpy.float64[m, n]], absolute_error_tolerance: numpy.ndarray[numpy.float64[m, n]], safety_factor: float = 0.8, minimum_factor_increase: float = 0.1, maximum_factor_increase: float = 4.0) tudatpy.kernel.numerical_simulation.propagation_setup.integrator.IntegratorStepSizeControlSettings ¶
Creates settings for integrator step-size control, using block-wise analysis for the propagated states.
Function to create settings for integrator step-size control, using block-wise analysis for the propagated states. This function is similar to
step_size_control_custom_blockwise_scalar_tolerance()
, but uses blockwise tolerances (as instep_size_control_blockwise_matrix_tolerance()
)- Parameters:
block_indices_function (Callable[[int,int],list[tuple[int,int,int,int]]]) – Function returning list of matrix blocks over which the norms are to be taken (with entries of the tuple denoting \(i,j,k,l\), in order, with number of rows and columns of propagated state as input.
relative_error_tolerance (numpy.ndarray[numpy.float64[m, 1]]) – Values of relative error tolerance \(\boldsymbol{\epsilon}_{r}\).
absolute_error_tolerance (numpy.ndarray[numpy.float64[m, 1]]) – Values of absolute error tolerance \(\boldsymbol{\epsilon}_{a}\).
safety_factor (float, default = 0.8) – Safety factor \(K\) for step size control
minimum_factor_increase (float, default = 0.1) – Minimum permissible value for \(\Delta t_{rec.}/\Delta t\)
maximum_factor_increase (float, default = 4.0) – Maximum permissible value for \(\Delta t_{rec.}/\Delta t\)
- Returns:
Object containing settings for per-element step-size control.
- Return type:
- standard_cartesian_state_element_blocks(number_of_rows: int, number_of_columns: int) list[tuple[int, int, int, int]] ¶
Function to generate step size control blocks on position and velocity elements for numerical integration
Function to generate step size control blocks on position and velocity elements for numerical integration, typically provided to the
step_size_control_custom_blockwise_scalar_tolerance()
orstep_size_control_custom_blockwise_matrix_tolerance()
function. By providing this function to one of these step-size control functions, the final column of the state vector is taken (such that it works both for state-only, and variational equations and state propagation) and combined into \(N\) blocks of size 3. The step-size control is then done on each of these blocks, which will represent the position and velocity blocks.- Parameters:
- Returns:
List of matrix blocks over which the step size control is to be done (see
block_indices_function
input tostep_size_control_custom_blockwise_scalar_tolerance()
)- Return type:
- runge_kutta_fixed_step(time_step: float, coefficient_set: tudatpy.kernel.numerical_simulation.propagation_setup.integrator.CoefficientSets, order_to_use: tudatpy.kernel.numerical_simulation.propagation_setup.integrator.OrderToIntegrate = <OrderToIntegrate.lower: 0>, assess_termination_on_minor_steps: bool = False) tudatpy.kernel.numerical_simulation.propagation_setup.integrator.IntegratorSettings ¶
Creates the settings for the Runge-Kutta fixed step size integrator.
Factory function to create settings for the Runge-Kutta integrator with a constant step size. Different coefficient sets (Butcher’s tableau) can be used (see the CoefficientSets enum).
- Parameters:
time_step (float) – Initial time step to be used.
coefficient_set (CoefficientSets) – Coefficient set (Butcher’s tableau) to be used in the integration.
order_to_use (OrderToIntegrate, default=OrderToIntegrate.lower) – If the coefficient set is supposed to be for variable step sizes (with an embedded method of a different order), this parameter can be used to set the order that will be used.
assess_termination_on_minor_steps (bool, default=false) – Whether the propagation termination conditions should be evaluated during the intermediate sub-steps of the integrator (true) or only at the end of each integration step (false).
- Returns:
Object containing settings for the integrator.
- Return type:
Examples
In this example, settings for the classical RK4 integrator with 30 second time step are created
# Create RK4 settings integrator_settings = integrator.runge_kutta_fixed_step( time_step = 30.0, coefficient_set = integrator.rk_4 )
In this example, settings for fixed-step integration using the higher-order (8th-order) of the two embedded propagators of the RKF7(8) method are created, with a time-step of 120 seconds.
# Create 8th order RKF settings integrator_settings = integrator.runge_kutta_fixed_step( time_step = 120.0, coefficient_set = integrator.rkf_78, order_to_use = integrator.higher )
- runge_kutta_variable_step(initial_time_step: float, coefficient_set: tudatpy.kernel.numerical_simulation.propagation_setup.integrator.CoefficientSets, step_size_control_settings: tudatpy.kernel.numerical_simulation.propagation_setup.integrator.IntegratorStepSizeControlSettings, step_size_validation_settings: tudatpy.kernel.numerical_simulation.propagation_setup.integrator.IntegratorStepSizeValidationSettings, assess_termination_on_minor_steps: bool = False) tudatpy.kernel.numerical_simulation.propagation_setup.integrator.IntegratorSettings ¶
Creates the settings for the Runge-Kutta fixed step size integrator.
Factory function to create settings for the Runge-Kutta variable step size integrator. Different coefficient sets (Butcher’s tableau) can be used (see the CoefficientSets enum). The step-size control algorithm is defined by a
IntegratorStepSizeControlSettings
andIntegratorStepSizeValidationSettings
object, created using one of the factory functions listed above.- Parameters:
initial_time_step (float) – Initial time step to be used.
coefficient_set (CoefficientSets) – Coefficient set (Butcher’s tableau) to be used in the integration.
step_size_control_settings (IntegratorStepSizeControlSettings) – Object used to control the step size, by computing a new step size \(\Delta t_{rec.}\), from the embedded Runge-Kutta integrator pair, and recommending whether the steps is to be accepted, or recomputed with a different time step.
step_size_validation_settings (IntegratorStepSizeValidationSettings) – Object used to validate whether the \(\Delta t_{rec.}\) provided by model defined by the
step_size_control_settings
meets with user-defined criteria (minimum, maximum values, etc.)assess_termination_on_minor_steps (bool, default=false) – Whether the propagation termination conditions should be evaluated during the intermediate sub-steps of the integrator (true) or only at the end of each integration step (false).
- Returns:
Object containing settings for the integrator.
- Return type:
Examples
In this example, settings for the varianle step RK4(5) integrator are created, with the same tolerances (\(10^{-10}\)) applied element-wise on the propagated state. The minimum and maximum time steps are set to 0.001 and 1000 seconds, and the initial step is set to 30 seconds. All other inputs are left on their defaults
# Create RK4(5) settings control_settings = integator.step_size_control_elementwise_scalar_tolerance( 1.0E-10, 1.0E-10 ) validation_settings = integrator.step_size_validation( 0.001, 1000.0 ) integrator_settings = integrator.runge_kutta_variable_step( initial_time_step = 30.0, coefficient_set = integrator.rkf_45, step_size_control_settings = control_settings, step_size_validation_settings = validation_settings )
In this example, the above is modified such that step-size control is applied on position and velocity element blocks.
# Create RK4(5) settings control_settings = integator.step_size_control_custom_blockwise_scalar_tolerance( integrator.standard_cartesian_state_element_blocks 1.0E-10, 1.0E-10 ) validation_settings = integrator.step_size_validation( 0.001, 1000.0 ) integrator_settings = integrator.runge_kutta_variable_step( initial_time_step = 30.0, coefficient_set = integrator.rkf_45, step_size_control_settings = control_settings, step_size_validation_settings = validation_settings )
- bulirsch_stoer_fixed_step(time_step: float, extrapolation_sequence: tudatpy.kernel.numerical_simulation.propagation_setup.integrator.ExtrapolationMethodStepSequences, maximum_number_of_steps: int, assess_termination_on_minor_steps: bool = False) tudatpy.kernel.numerical_simulation.propagation_setup.integrator.IntegratorSettings ¶
Creates the settings for the fixed time-step Bulirsch-Stoer integrator.
Factory function to create settings for the fixed time-step Bulirsch-Stoer integrator. The underlying method is the same as
bulirsch_stoer_variable_step()
, but using a fixed, user-defined, time step.- Parameters:
time_step (float) – Time step to be used.
extrapolation_sequence (ExtrapolationMethodStepSequences) – Extrapolation sequence to be used for the integration (defining the number of substeps in iteration \(i\)).
maximum_number_of_steps (int) – Number of entries from the sequence to be used (e.g., total number of iterations used for a single extrapolation and time step).
assess_termination_on_minor_steps (bool, default=false) – Whether the propagation termination conditions should be evaluated during the intermediate sub-steps of the integrator (true) or only at the end of each integration step (false).
- Returns:
Object containing settings for the integrator.
- Return type:
Examples
In this example, settings for the Bulirsch-Stoer integrator with 600 second time step are created, using the typical sequence, using 6 iterations of the same step. By using the Bulirsch-Stoer sequence, this means that the same step is done using 2, 4, 6, 8, 12 and 16 substeps
# Create BS settings integrator_settings = integrator.bulirsch_stoer_fixed_step( time_step = 300.0, extrapolation_sequence = integrator.bulirsch_stoer_sequence, maximum_number_of_steps = 6 )
- bulirsch_stoer_variable_step(initial_time_step: float, extrapolation_sequence: tudatpy.kernel.numerical_simulation.propagation_setup.integrator.ExtrapolationMethodStepSequences, maximum_number_of_steps: int, step_size_control_settings: tudatpy.kernel.numerical_simulation.propagation_setup.integrator.IntegratorStepSizeControlSettings, step_size_validation_settings: tudatpy.kernel.numerical_simulation.propagation_setup.integrator.IntegratorStepSizeValidationSettings, assess_termination_on_minor_steps: bool = False) tudatpy.kernel.numerical_simulation.propagation_setup.integrator.IntegratorSettings ¶
Creates the settings for the variable time-step Bulirsch-Stoer integrator.
Factory function to create settings for the variable time-step Bulirsch-Stoer integrator. This integrator works by performing the same (typically very large) step multiple times, using an ever increasing number of substeps. Each substep is performed using the modified midpoint method. The succesive integrations from \(t_{i}\) to \(t_{i}+\Delta t\) are (in principle) done using ever increasing accuracy, as the size of the substep decreases. This integrator works by extrapolating the behaviour to a substep length of 0 (e.g. an infinite number of substeps), at which the solution should be perfect. The number of substeps on the \(i^{t}\) iteration are done using the number of substeps defined by entry \(i\) of the
extrapolation_sequence
input. The number of iterations for a single step is defined by themaximum_number_of_steps
entry. For instance, using thebulirsch_stoer_sequence
sequence, and 5 iterations, the same step is done using 2, 4, 6, 8 and 12 substeps, and the results are then extrapolated to an infinite number of steps. Different extrapolation sequences can be used (see the ExtrapolationMethodStepSequences enum).The step-size control algorithm is defined by a
IntegratorStepSizeControlSettings
andIntegratorStepSizeValidationSettings
object, created using one of the factory functions listed above. The time step control uses the result from the final, and second to final iteration to generate an error estimate of the current step.- Parameters:
time_step (float) – Initial time step to be used.
extrapolation_sequence (ExtrapolationMethodStepSequences) – Extrapolation sequence to be used for the integration (defining the number of substeps in iteration \(i\)).
maximum_number_of_steps (int) – Number of entries from the sequence to be used (e.g., total number of iterations used for a single extrapolation and time step).
step_size_control_settings (IntegratorStepSizeControlSettings) – Object used to control the step size, by computing a new step size \(\Delta t_{rec.}\), from the embedded Runge-Kutta integrator pair, and recommending whether the steps is to be accepted, or recomputed with a different time step.
step_size_validation_settings (IntegratorStepSizeValidationSettings) – Object used to validate whether the \(\Delta t_{rec.}\) provided by model defined by the
step_size_control_settings
meets with user-defined criteria (minimum, maximum values, etc.)assess_termination_on_minor_steps (bool, default=false) – Whether the propagation termination conditions should be evaluated during the intermediate sub-steps of the integrator (true) or only at the end of each integration step (false).
- Returns:
Object containing settings for the integrator.
- Return type:
Examples
In this example, settings for the Bulirsch-Stoer integrator with 600 second initial time step are created, using the typical sequence, using 6 iterations of the same step. By using the Bulirsch-Stoer sequence, this means that the same step is done using 2, 4, 6, 8, 12 and 16 substeps. The same tolerances (\(10^{-10}\)) applied element-wise on the propagated state. The minimum and maximum time steps are set to 0.1 and 10000 seconds, and the initial step is set to 600 seconds. All other inputs are left on their defaults
# Create BS settings control_settings = integator.step_size_control_elementwise_scalar_tolerance( 1.0E-10, 1.0E-10 ) validation_settings = integrator.step_size_validation( 0.1, 10000.0 ) integrator_settings = integrator.bulirsch_stoer_variable_step( initial_time_step = 600.0, extrapolation_sequence = integrator.bulirsch_stoer_sequence, maximum_number_of_steps = 6 step_size_control_settings = control_settings, step_size_validation_settings = validation_settings )
- adams_bashforth_moulton(*args, **kwargs)¶
Overloaded function.
adams_bashforth_moulton(initial_time_step: float, minimum_step_size: float, maximum_step_size: float, relative_error_tolerance: float = 1e-12, absolute_error_tolerance: float = 1e-12, minimum_order: int = 6, maximum_order: int = 11, assess_termination_on_minor_steps: bool = False, bandwidth: float = 200.0) -> tudatpy.kernel.numerical_simulation.propagation_setup.integrator.IntegratorSettings
Creates the settings for the Adams-Bashforth-Moulton integrator.
Factory function to create settings for the Adams-Bashforth-Moulton multistep integrator. For this integrator, the step size and order are both according to a control algorithm similar to
step_size_control_elementwise_scalar_tolerance()
. The integrator is initialized using an RKF7(8) integrator.NOTE: this integrator’s step-size and order control algorithm work in a method that is overly simplistic, when increasing/decreasing the order, existing function evaluations are re-used, without any recomputations. Similarly, when halving or doubling the time-step, the existing interpolating polynomial is evaluated at the relevant points. This can lead to unwanted behaviour, where the time-step reduces to unrealistically low values. It is strongly recommended that a reasonable minimum step is provided to this function, to partially mitigate this behaviour.
- Parameters:
initial_time_step (float) – Initial time step to be used.
minimum_step_size (float) – Minimum time step to be used during the integration.
maximum_step_size (float) – Maximum time step to be used during the integration.
relative_error_tolerance (float, default=1.0E-12) – Relative tolerance to adjust the time step.
absolute_error_tolerance (float, default=1.0E-12) – Relative tolerance to adjust the time step.
minimum_order – Minimum order of the integrator.
maximum_order – Maximum order of the integrator.
assess_termination_on_minor_steps (bool, default=false) – Whether the propagation termination conditions should be evaluated during the intermediate sub-steps of the integrator (true) or only at the end of each integration step (false).
bandwidth (float, default=200.0) – Maximum error factor for doubling the step size.
- Returns:
Object containing settings for the integrator.
- Return type:
adams_bashforth_moulton(initial_time: float, initial_time_step: float, minimum_step_size: float, maximum_step_size: float, relative_error_tolerance: float = 1e-12, absolute_error_tolerance: float = 1e-12, minimum_order: int = 6, maximum_order: int = 11, assess_termination_on_minor_steps: bool = False, bandwidth: float = 200.0) -> tudatpy.kernel.numerical_simulation.propagation_setup.integrator.IntegratorSettings
- adams_bashforth_moulton_fixed_order(initial_time_step: float, minimum_step_size: float, maximum_step_size: float, relative_error_tolerance: float = 1e-12, absolute_error_tolerance: float = 1e-12, order: int = 6, assess_termination_on_minor_steps: bool = False, bandwidth: float = 200.0) tudatpy.kernel.numerical_simulation.propagation_setup.integrator.IntegratorSettings ¶
Creates the settings for the Adams-Bashforth-Moulton integrator of fixed order.
Same as
adams_bashforth_moulton()
, but with fixed order and variable step- Parameters:
initial_time_step (float) – Initial time step to be used.
minimum_step_size (float) – Minimum time step to be used during the integration.
maximum_step_size (float) – Maximum time step to be used during the integration.
relative_error_tolerance (float, default=1.0E-12) – Relative tolerance to adjust the time step.
absolute_error_tolerance (float, default=1.0E-12) – Relative tolerance to adjust the time step.
order – Order of the integrator.
assess_termination_on_minor_steps (bool, default=false) – Whether the propagation termination conditions should be evaluated during the intermediate sub-steps of the integrator (true) or only at the end of each integration step (false).
bandwidth (float, default=200.0) – Maximum error factor for doubling the step size.
- Returns:
Object containing settings for the integrator.
- Return type:
- adams_bashforth_moulton_fixed_step(time_step: float, relative_error_tolerance: float = 1e-12, absolute_error_tolerance: float = 1e-12, minimum_order: int = 6, maximum_order: int = 11, assess_termination_on_minor_steps: bool = False, bandwidth: float = 200.0) tudatpy.kernel.numerical_simulation.propagation_setup.integrator.IntegratorSettings ¶
Creates the settings for the Adams-Bashforth-Moulton fixed-step integrator.
Same as
adams_bashforth_moulton()
, but with fixed step and variable order- Parameters:
time_step (float) – Initial time step to be used.
relative_error_tolerance (float, default=1.0E-12) – Relative tolerance to adjust the time step.
absolute_error_tolerance (float, default=1.0E-12) – Relative tolerance to adjust the time step.
minimum_order – Minimum order of the integrator.
maximum_order – Maximum order of the integrator.
assess_termination_on_minor_steps (bool, default=false) – Whether the propagation termination conditions should be evaluated during the intermediate sub-steps of the integrator (true) or only at the end of each integration step (false).
bandwidth (float, default=200.0) – Maximum error factor for doubling the step size.
- Returns:
Object containing settings for the integrator.
- Return type:
- adams_bashforth_moulton_fixed_step_fixed_order(time_step: float, order: int = 6, assess_termination_on_minor_steps: bool = False) tudatpy.kernel.numerical_simulation.propagation_setup.integrator.IntegratorSettings ¶
Creates the settings for the Adams-Bashforth-Moulton fixed-step, fixed-order integrator.
Same as
adams_bashforth_moulton()
, but with fixed step and fixed order- Parameters:
time_step (float) – Initial time step to be used.
order – Order of the integrator.
assess_termination_on_minor_steps (bool, default=false) – Whether the propagation termination conditions should be evaluated during the intermediate sub-steps of the integrator (true) or only at the end of each integration step (false).
- Returns:
Object containing settings for the integrator.
- Return type:
- print_butcher_tableau(arg0: tudatpy.kernel.numerical_simulation.propagation_setup.integrator.CoefficientSets) None ¶
Print the Butcher tableau of a given coefficient set.
- Parameters:
coefficient_set (CoefficientSets) – Coefficient set of which the Butcher tableau will be printed.
- runge_kutta_variable_step_size(*args, **kwargs)¶
Overloaded function.
runge_kutta_variable_step_size(initial_time_step: float, coefficient_set: tudatpy.kernel.numerical_simulation.propagation_setup.integrator.CoefficientSets, minimum_step_size: float, maximum_step_size: float, relative_error_tolerance: float, absolute_error_tolerance: float, assess_termination_on_minor_steps: bool = False, safety_factor: float = 0.8, maximum_factor_increase: float = 4.0, minimum_factor_increase: float = 0.1, throw_exception_if_minimum_step_exceeded: bool = True) -> tudatpy.kernel.numerical_simulation.propagation_setup.integrator.IntegratorSettings
Creates the settings for the Runge-Kutta variable step size integrator with scalar tolerances.
NOTE: THIS FUNCTION IS DEPRECATED, IT IS RECOMMENDED TO USE THE NEW
runge_kutta_variable_step()
INTERFACE INSTEADFactory function to create settings for the Runge-Kutta variable step size integrator with scalar tolerances. For this integrator, the step size is varied based on the tolerances and safety factor provided. The tolerance is composed of an absolute and a relative part. Different coefficient sets (Butcher’s tableau) can be used (see the CoefficientSets enum).
- Parameters:
initial_time_step (float) – Initial time step to be used.
coefficient_set (CoefficientSets) – Coefficient set (Butcher’s tableau) to be used in the integration.
minimum_step_size (float) – Minimum time step to be used during the integration.
maximum_step_size (float) – Maximum time step to be used during the integration.
relative_error_tolerance (numpy.ndarray[numpy.float64[m, n]]) – Relative vector tolerance to adjust the time step.
absolute_error_tolerance (numpy.ndarray[numpy.float64[m, n]]) – Absolute vector tolerance to adjust the time step.
assess_termination_on_minor_steps (bool, default=false) – Whether the propagation termination conditions should be evaluated during the intermediate sub-steps of the integrator (true) or only at the end of each integration step (false).
safety_factor (float, default=0.8) – Safety factor used in the step size control.
maximum_factor_increase (float, default=4.0) – Maximum increase between consecutive time steps, expressed as the factor between new and old step size.
minimum_factor_increase (float, default=0.1) – Minimum increase between consecutive time steps, expressed as the factor between new and old step size.
throw_exception_if_minimum_step_exceeded (bool, default=true) – If set to false, the variable step integrator will use the minimum step size specified when the algorithm computes the optimum one to be lower, instead of throwing an exception.
- Returns:
RungeKuttaVariableStepSettingsScalarTolerances object.
- Return type:
RungeKuttaVariableStepSettingsScalarTolerances
runge_kutta_variable_step_size(initial_time: float, initial_time_step: float, coefficient_set: tudatpy.kernel.numerical_simulation.propagation_setup.integrator.CoefficientSets, minimum_step_size: float, maximum_step_size: float, relative_error_tolerance: float, absolute_error_tolerance: float, assess_termination_on_minor_steps: bool = False, safety_factor: float = 0.8, maximum_factor_increase: float = 4.0, minimum_factor_increase: float = 0.1, throw_exception_if_minimum_step_exceeded: bool = True) -> tudatpy.kernel.numerical_simulation.propagation_setup.integrator.IntegratorSettings
- runge_kutta_variable_step_size_vector_tolerances(*args, **kwargs)¶
Overloaded function.
runge_kutta_variable_step_size_vector_tolerances(initial_time_step: float, coefficient_set: tudatpy.kernel.numerical_simulation.propagation_setup.integrator.CoefficientSets, minimum_step_size: float, maximum_step_size: float, relative_error_tolerance: numpy.ndarray[numpy.float64[m, n]], absolute_error_tolerance: numpy.ndarray[numpy.float64[m, n]], assess_termination_on_minor_steps: bool = False, safety_factor: float = 0.8, maximum_factor_increase: float = 4.0, minimum_factor_increase: float = 0.1, throw_exception_if_minimum_step_exceeded: bool = True) -> tudatpy.kernel.numerical_simulation.propagation_setup.integrator.IntegratorSettings
Creates the settings for the Runge-Kutta variable step size integrator with vector tolerances.
NOTE: THIS FUNCTION IS DEPRECATED, IT IS RECOMMENDED TO USE THE NEW
runge_kutta_variable_step()
INTERFACE INSTEADFactory function to create settings for the Runge-Kutta variable step size integrator with vector tolerances. For this integrator, the step size is varied based on the tolerances and safety factor provided. The tolerance is composed of an absolute and a relative part. Different coefficient sets (Butcher’s tableau) can be used (see the CoefficientSets enum).
- Parameters:
initial_time_step (float) – Initial time step to be used.
coefficient_set (CoefficientSets) – Coefficient set (Butcher’s tableau) to be used in the integration.
minimum_step_size (float) – Minimum time step to be used during the integration.
maximum_step_size (float) – Maximum time step to be used during the integration.
relative_error_tolerance (numpy.ndarray[numpy.float64[m, n]]) – Relative vector tolerance to adjust the time step.
absolute_error_tolerance (numpy.ndarray[numpy.float64[m, n]]) – Absolute vector tolerance to adjust the time step.
assess_termination_on_minor_steps (bool, default=false) – Whether the propagation termination conditions should be evaluated during the intermediate sub-steps of the integrator (true) or only at the end of each integration step (false).
safety_factor (float, default=0.8) – Safety factor used in the step size control.
maximum_factor_increase (float, default=4.0) – Maximum increase between consecutive time steps, expressed as the factor between new and old step size.
minimum_factor_increase (float, default=0.1) – Minimum increase between consecutive time steps, expressed as the factor between new and old step size.
throw_exception_if_minimum_step_exceeded (bool, default=true) – If set to false, the variable step integrator will use the minimum step size specified when the algorithm computes the optimum one to be lower, instead of throwing an exception.
- Returns:
RungeKuttaVariableStepSizeSettingsVectorTolerances object.
- Return type:
RungeKuttaVariableStepSizeSettingsVectorTolerances
runge_kutta_variable_step_size_vector_tolerances(initial_time: float, initial_time_step: float, coefficient_set: tudatpy.kernel.numerical_simulation.propagation_setup.integrator.CoefficientSets, minimum_step_size: float, maximum_step_size: float, relative_error_tolerance: numpy.ndarray[numpy.float64[m, n]], absolute_error_tolerance: numpy.ndarray[numpy.float64[m, n]], assess_termination_on_minor_steps: bool = False, safety_factor: float = 0.8, maximum_factor_increase: float = 4.0, minimum_factor_increase: float = 0.1, throw_exception_if_minimum_step_exceeded: bool = True) -> tudatpy.kernel.numerical_simulation.propagation_setup.integrator.IntegratorSettings
- bulirsch_stoer(*args, **kwargs)¶
Overloaded function.
bulirsch_stoer(initial_time: float, initial_time_step: float, extrapolation_sequence: tudatpy.kernel.numerical_simulation.propagation_setup.integrator.ExtrapolationMethodStepSequences, maximum_number_of_steps: int, minimum_step_size: float, maximum_step_size: float, relative_error_tolerance: float = 1e-12, absolute_error_tolerance: float = 1e-12, assess_termination_on_minor_steps: bool = False, safety_factor: float = 0.7, maximum_factor_increase: float = 10.0, minimum_factor_increase: float = 0.1) -> tudatpy.kernel.numerical_simulation.propagation_setup.integrator.IntegratorSettings
bulirsch_stoer(initial_time_step: float, extrapolation_sequence: tudatpy.kernel.numerical_simulation.propagation_setup.integrator.ExtrapolationMethodStepSequences, maximum_number_of_steps: int, minimum_step_size: float, maximum_step_size: float, relative_error_tolerance: float = 1e-12, absolute_error_tolerance: float = 1e-12, assess_termination_on_minor_steps: bool = False, safety_factor: float = 0.7, maximum_factor_increase: float = 10.0, minimum_factor_increase: float = 0.1) -> tudatpy.kernel.numerical_simulation.propagation_setup.integrator.IntegratorSettings
Creates the settings for the Bulirsch-Stoer integrator.
NOTE: THIS FUNCTION IS DEPRECATED, IT IS RECOMMENDED TO USE THE NEW
bulirsch_stoer_variable_step()
INTERFACE INSTEADFactory function to create settings for the Bulirsch-Stoer integrator. For this integrator, the step size is varied based on the tolerances and safety factor provided. The tolerance is composed of an absolute and a relative part. Different extrapolation sequences can be used (see the ExtrapolationMethodStepSequences enum).
- Parameters:
initial_time_step (float) – Initial time step to be used.
extrapolation_sequence (ExtrapolationMethodStepSequences) – Extrapolation sequence to be used in the integration.
maximum_number_of_steps (int) – Number of entries in the sequence (e.g., number of integrations used for a single extrapolation).
minimum_step_size (float) – Minimum time step to be used during the integration.
maximum_step_size (float) – Maximum time step to be used during the integration.
relative_error_tolerance (float, default=1.0E-12) – Relative tolerance to adjust the time step.
absolute_error_tolerance (float, default=1.0E-12) – Relative tolerance to adjust the time step.
assess_termination_on_minor_steps (bool, default=false) – Whether the propagation termination conditions should be evaluated during the intermediate sub-steps of the integrator (true) or only at the end of each integration step (false).
safety_factor (float, default=0.7) – Safety factor used in the step size control.
maximum_factor_increase (float, default=10.0) – Maximum increase between consecutive time steps, expressed as the factor between new and old step size.
minimum_factor_increase (float, default=0.1) – Minimum increase between consecutive time steps, expressed as the factor between new and old step size.
- Returns:
BulirschStoerIntegratorSettings object.
- Return type:
Enumerations¶
Enumeration of integrators available with tudat. |
|
Coefficient sets for Runge-Kutta-type integrators. |
|
Enumeration defining Which integrator order needs to be integrated, only used for coefficient sets with an embedded order. |
|
Enumeration of available extrapolation method substep sequences, with \(n_{j}\) defining the number of substeps in iteration \(j\). |
|
Enumeration defining possible behaviours when \(\Delta t_{rec}<\Delta t_{\min}\). in step-size control (e.g. recommended time step is smaller than minimum time step) |
- class AvailableIntegrators¶
Enumeration of integrators available with tudat.
Members:
runge_kutta_fixed_step_size_type
runge_kutta_variable_step_size_type
bulirsch_stoer_type
adams_bashforth_moulton_type
- property name¶
- class CoefficientSets¶
Coefficient sets for Runge-Kutta-type integrators.
Coefficient sets for Runge-Kutta-type integrators. The coefficients are defined in a Butcher Tableau, with an coefficient set yielding an x(y) method yielding an integrator with global truncation error of \(O(\Delta t^{x})\). Some of these coefficients also contain an embedded integrator of \(O(\Delta t^{y})\) for step size control.
Members:
euler_forward :
Coefficients for the classic forward Euler method
rk_4 :
Coefficients for the original Runge-Kutta method of order 4
explicit_mid_point :
Coefficients for the explicit midpoint method
explicit_trapezoid_rule :
Coefficients for the explicit trapezoid rule, also called Heun’s method or improved Euler’s method
ralston :
Coefficients for Ralston’s method
rk_3 :
Coefficients for the Runge-Kutta method of order 3
ralston_3 :
Coefficients for Ralston’s third-order method
SSPRK3 :
Coefficients for the Strong Stability Preserving Runge-Kutta third-order method
ralston_4 :
Coefficients for Ralston’s fourth-order method
three_eight_rule_rk_4 :
Coefficients for the classic Runge Kutta 3/8-rule fourth-order method
heun_euler :
Coefficients for the Heun’s method of order 2 with an embedded Euler method of order 1
rkf_12 :
Coefficients for the Runge-Kutta-Fehlberg method of order 2 with an embedded 1st order
rkf_45 :
Coefficients for the Runge-Kutta-Fehlberg method of order 5 with an embedded 4th order
rkf_56 :
Coefficients for the Runge-Kutta-Fehlberg method of order 6 with an embedded 5th order
rkf_78 :
Coefficients for the Runge-Kutta-Fehlberg method of order 8 with an embedded 7th order
rkdp_87 :
Coefficients for the Dormand-Prince method of order 7 with an embedded 8th order
rkf_89 :
Coefficients for the Runge-Kutta-Fehlberg method of order 9 with an embedded 8th order
rkv_89 :
Coefficients for the Runge-Kutta-Verner method of order 9 with an embedded 8th order
rkf_108 :
Coefficients for the Runge-Kutta-Feagin method of order 8 with an embedded 10th order
rkf_1210 :
Coefficients for the Runge-Kutta-Feagin method of order 10 with an embedded 12ve order
rkf_1412 :
Coefficients for the Runge-Kutta-Feagin method of order 12 with an embedded 14th order
- property name¶
- class OrderToIntegrate¶
Enumeration defining Which integrator order needs to be integrated, only used for coefficient sets with an embedded order.
Members:
lower :
For a method of order \(p\), with embedded method of order \(q\), the step is taken using the method with order \(\min(p,q)\)
higher :
For a method of order \(p\), with embedded method of order \(q\), the step is taken using the method with order \(\max(p,q)\)
- property name¶
- class ExtrapolationMethodStepSequences¶
Enumeration of available extrapolation method substep sequences, with \(n_{j}\) defining the number of substeps in iteration \(j\).
Members:
bulirsch_stoer_sequence :
Sequence for which \(n_{j}=2n_{j-2}\) (2, 4, 6, 8, 12, 16, 24, ….)
deufelhard_sequence :
Sequence for which \(n_{j}=2(j+1)\) (2, 4, 6, 8, 10, 12, 14, ….)
- property name¶
- class MinimumIntegrationTimeStepHandling¶
Enumeration defining possible behaviours when \(\Delta t_{rec}<\Delta t_{\min}\). in step-size control (e.g. recommended time step is smaller than minimum time step)
Members:
throw_exception_below_minimum :
Exception is throw, and propagation is terminated
set_to_minimum_step_silently :
The final time step is set to \(\Delta t=\Delta t_{\min}\), violating requirements of step-size control algorithm, without any message to user”
set_to_minimum_step_single_warning :
The final time step is set to \(\Delta t=\Delta t_{\min}\), violating requirements of step-size control algorithm, a warning is printed to the terminal the first time this happens during a propagation”
set_to_minimum_step_every_time_warning :
The final time step is set to \(\Delta t=\Delta t_{\min}\), violating requirements of step-size control algorithm, a warning is printed to the terminal every time this happens during a propagation”
- property name¶
Classes¶
Base class to define settings for step-size control algorithm. |
|
Base class to define settings for step-size validation algorithm. |
|
Functional base class to define settings for integrators. |
|
IntegratorSettings-derived class to define settings for Runge Kutta integrators with a fixed step size |
|
IntegratorSettings-derived class to define settings for Bulirsch-Stoer integrator settings. |
|
IntegratorSettings-derived class to define settings for Adams-Bashforth-Moulton integrator settings. |
- class IntegratorStepSizeControlSettings¶
Base class to define settings for step-size control algorithm.
Base class to define settings for step-size control algorithm, typically created by one of the factory functions provided in this module
- class IntegratorStepSizeValidationSettings¶
Base class to define settings for step-size validation algorithm.
Base class to define settings for step-size validation algorithm, typically created by one of the factory functions provided in this module
- class IntegratorSettings¶
Functional base class to define settings for integrators.
Class to define settings for numerical integrators, for instance for use in numerical integration of equations of motion/ variational equations. This class can be used for simple integrators such as fixed step RK and Euler. Integrators that require more settings to define have their own derived class.
- class RungeKuttaFixedStepSizeSettings¶
IntegratorSettings-derived class to define settings for Runge Kutta integrators with a fixed step size
- class BulirschStoerIntegratorSettings¶
IntegratorSettings-derived class to define settings for Bulirsch-Stoer integrator settings.
- class AdamsBashforthMoultonSettings¶
IntegratorSettings-derived class to define settings for Adams-Bashforth-Moulton integrator settings.