Behavior of extrapolation integrators

Hi! First of all, thank you for all the work put into the library! It's very much appreciated.

I have run into some behavior when attempting to create fixed-step size extrapolation sequence integrators using Tudat.

Table of contents:

Initial step size not respected unless setting large tolerances
Effect of maximum_factor_increase and minimum_factor_increase
Suggestions to improve the documentation

Initial step size not respected unless setting large tolerances

I first attempted to constrain the step size used by the extrapolation sequence integrators by setting the initial_time_step, maximum_step_size and minimum_step_size equal to my desired, fixed step size, as follows:

# Create integrator settings
integrator = propagation_setup.integrator

integrator_settings = integrator.bulirsch_stoer(
    initial_time_step        = step_size,
    extrapolation_sequence   = integrator_coefficient_set,
    maximum_number_of_steps  = 3,
    minimum_step_size        = step_size,
    maximum_step_size        = step_size)

Doing this causes an error however, because the integrators will not use the provided initial_time_step unless the relative_error_tolerance and absolute_error_tolerance are set to large values (np.inf, see the solution below).

While the main Tudat library site instructs us to do this1 to force the integrators to use a constant step size, this behavior is rather unintuitive and could be changed or better documented, as currently

The user does not know whether their chosen initial_time_step will actually be used by the integrator,
The API docs entry on bulirsch_stoer extrapolation sequence integrators2 does not indicate that the relative_error_tolerance and absolute_error_tolerance determine whether the chosen initial_time_step will be used

For the sake of completeness, the desired behavior can be achieved as follows:

# Create integrator settings
integrator = propagation_setup.integrator

integrator_settings = integrator.bulirsch_stoer(
    initial_time_step        = step_size,
    extrapolation_sequence   = integrator_coefficient_set,
    maximum_number_of_steps  = 3,
    minimum_step_size        = step_size,
    maximum_step_size        = step_size,
    relative_error_tolerance = np.inf,
    absolute_error_tolerance = np.inf)

Effect of `maximum_factor_increase` and `minimum_factor_increase`

I attempted to force the extrapolation integrators to use a constant step size as well by setting the maximum_factor_increase and minimum_factor_increase to 1.0, as follows.

# Create integrator settings
integrator = propagation_setup.integrator

integrator_settings = integrator.bulirsch_stoer(
    initial_time_step        = step_size,
    extrapolation_sequence   = integrator_coefficient_set,
    maximum_number_of_steps  = 3,
    maximum_factor_increase  = 1.0,
    minimum_factor_increase  = 1.0)

This did not have the desired effect, but it did seem to somewhat constrain the step sizes used by the integrators, as can be seen in the figures below:

While I can understand that these factors could be used for the intermediate steps instead, I could find no information in the API documentation on extrapolation integrators that could explain how the large step size changes seen in figure above come to be, and why the step size would stabilize to an almost constant value as it does.

Suggestions to improve the documentation

I believe it would be beneficial to add some sort of warning, similar to that issued by Tudat interpolators when extrapolating values, when an extrapolation integrator does not use the provided initial_time_step to satisfy the default or provided relative_error_tolerance and absolute_error_tolerance
Similarly, it would be very welcome to have a more in depth discussion in the API docs on extrapolation integrators of the effect that maximum_factor_increase and minimum_factor_increase have on the chosen step size.

Thank you very much for your time and have a nice day!

tudat-team / tudat-space