implementations.convergence_controller_classes.adaptivity module

class Adaptivity(controller, params, description, **kwargs)[source]

Bases: AdaptivityBase

Class to compute time step size adaptively based on embedded error estimate.

We have a version working in non-MPI pipelined SDC, but Adaptivity requires you to know the order of the scheme, which you can also know for block-Jacobi, but it works differently and it is only implemented for block Gauss-Seidel so far.

There is an option to reduce restarts if continued iterations could yield convergence in fewer iterations than restarting based on an estimate of the contraction factor. Since often only one or two more iterations suffice, this can boost efficiency of adaptivity significantly. Notice that the computed step size is not effected. Be aware that this does not work when Hot Rod is enabled, since that requires us to know the order of the scheme in more detail. Since we reset to the second to last sweep before moving on, we cannot continue to iterate. Set the reduced restart up by setting a boolean value for “avoid_restarts” in the parameters for the convergence controller. The behaviour in multi-step SDC is not well studied and it is unclear if anything useful happens there.

check_parameters(controller, params, description, **kwargs)[source]

Check whether parameters are compatible with whatever assumptions went into the step size functions etc. For adaptivity, we need to know the order of the scheme.

Parameters:

  • controller (pySDC.Controller) – The controller

  • params (dict) – The params passed for this specific convergence controller

  • description (dict) – The description object used to instantiate the controller

Returns:

Whether the parameters are compatible str: The error message

Return type:

bool

dependencies(controller, description, **kwargs)[source]

Load the embedded error estimator.

Parameters:

  • controller (pySDC.Controller) – The controller

  • description (dict) – The description object used to instantiate the controller

Returns:

None

get_local_error_estimate(controller, S, **kwargs)[source]

Get the embedded error estimate of the finest level of the step.

Parameters:

  • controller (pySDC.Controller) – The controller

  • S (pySDC.Step) – The current step

Returns:

Embedded error estimate

Return type:

float

get_new_step_size(controller, S, **kwargs)[source]

Determine a step size for the next step from an embedded estimate of the local error of the current step.

Parameters:

  • controller (pySDC.Controller) – The controller

  • S (pySDC.Step) – The current step

Returns:

None

setup(controller, params, description, **kwargs)[source]

Define default parameters here.

Default parameters are:

  • control_order (int): The order relative to other convergence controllers

  • beta (float): The safety factor

Parameters:

  • controller (pySDC.Controller) – The controller

  • params (dict) – The params passed for this specific convergence controller

  • description (dict) – The description object used to instantiate the controller

Returns:

The updated params dictionary

Return type:

(dict)

class AdaptivityBase(controller, params, description, **kwargs)[source]

Bases: ConvergenceController

Abstract base class for convergence controllers that implement adaptivity based on arbitrary local error estimates and update rules.

compute_optimal_step_size(beta, dt, e_tol, e_est, order)[source]

Compute the optimal step size for the current step based on the order of the scheme. This function can be called from get_new_step_size for various implementations of adaptivity, but notably not all! We require to know the order of the error estimate and if we do adaptivity based on the residual, for instance, we do not know that and we can’t use this function.

Parameters:

  • beta (float) – Safety factor

  • dt (float) – Current step size

  • e_tol (float) – The desired tolerance

  • e_est (float) – The estimated local error

  • order (int) – The order of the local error estimate

Returns:

The optimal step size

Return type:

float

dependencies(controller, description, **kwargs)[source]

Load step size limiters here, if they are desired.

Parameters:

  • controller (pySDC.Controller) – The controller

  • description (dict) – The description object used to instantiate the controller

Returns:

None

determine_restart(controller, S, **kwargs)[source]

Check if the step wants to be restarted by comparing the estimate of the local error to a preset tolerance

Parameters:

  • controller (pySDC.Controller) – The controller

  • S (pySDC.Step) – The current step

Returns:

None

get_local_error_estimate(controller, S, **kwargs)[source]

Get the local error estimate for updating the step size. It does not have to be an error estimate, but could be the residual or something else.

Parameters:

  • controller (pySDC.Controller) – The controller

  • S (pySDC.Step) – The current step

Returns:

The error estimate

Return type:

float

get_new_step_size(controller, S, **kwargs)[source]

Determine a step size for the next step from an estimate of the local error of the current step.

Parameters:

  • controller (pySDC.Controller) – The controller

  • S (pySDC.Step) – The current step

Returns:

None

setup(controller, params, description, **kwargs)[source]

Define default parameters here.

Default parameters are:

  • control_order (int): The order relative to other convergence controllers

  • beta (float): The safety factor

Parameters:

  • controller (pySDC.Controller) – The controller

  • params (dict) – The params passed for this specific convergence controller

  • description (dict) – The description object used to instantiate the controller

Returns:

The updated params dictionary

Return type:

(dict)

class AdaptivityCollocation(controller, params, description, **kwargs)[source]

Bases: AdaptivityForConvergedCollocationProblems

Control the step size via a collocation based estimate of the local error. The error estimate works by subtracting two solutions to collocation problems with different order. You can interpolate between collocation methods as much as you want but the adaptive step size selection will always be based on the last switch of quadrature.

check_parameters(controller, params, description, **kwargs)[source]

Check whether parameters are compatible with whatever assumptions went into the step size functions etc. For adaptivity, we need to know the order of the scheme.

Parameters:

  • controller (pySDC.Controller) – The controller

  • params (dict) – The params passed for this specific convergence controller

  • description (dict) – The description object used to instantiate the controller

Returns:

Whether the parameters are compatible str: The error message

Return type:

bool

dependencies(controller, description, **kwargs)[source]

Load the EstimateEmbeddedErrorCollocation convergence controller to estimate the local error by switching between collocation problems between iterations.

Parameters:

  • controller (pySDC.Controller) – The controller

  • description (dict) – The description object used to instantiate the controller

determine_restart(controller, S, **kwargs)[source]

Check if the step wants to be restarted by comparing the estimate of the local error to a preset tolerance

Parameters:

  • controller (pySDC.Controller) – The controller

  • S (pySDC.Step) – The current step

Returns:

None

get_convergence(controller, S, **kwargs)[source]
get_local_error_estimate(controller, S, **kwargs)[source]

Get the collocation based embedded error estimate.

Parameters:

  • controller (pySDC.Controller) – The controller

  • S (pySDC.Step) – The current step

Returns:

Embedded error estimate

Return type:

float

get_new_step_size(controller, S, **kwargs)[source]

Determine a step size for the next step from an estimate of the local error of the current step.

Parameters:

  • controller (pySDC.Controller) – The controller

  • S (pySDC.Step) – The current step

Returns:

None

post_iteration_processing(controller, step, **kwargs)[source]

Get the error estimate and its order if available.

Parameters:

  • controller (pySDC.Controller.controller) – The controller

  • step (pySDC.Step.step) – The current step

reset_status_variables(controller, **kwargs)[source]

Reset status variables. This is called in the restart_block function. :param controller: The controller :type controller: pySDC.Controller

Returns:

None

setup(controller, params, description, **kwargs)[source]

Add a default value for control order to the parameters.

Parameters:

  • controller (pySDC.Controller) – The controller

  • params (dict) – Parameters for the convergence controller

  • description (dict) – The description object used to instantiate the controller

Returns:

Updated parameters

Return type:

dict

setup_status_variables(controller, **kwargs)[source]

Setup status variables. This is not done at the time of instantiation, since the controller is not fully instantiated at that time and hence not all information are available. Instead, this function is called after the controller has been fully instantiated.

Parameters:

controller (pySDC.Controller) – The controller

Returns:

None

class AdaptivityExtrapolationWithinQ(controller, params, description, **kwargs)[source]

Bases: AdaptivityForConvergedCollocationProblems

Class to compute time step size adaptively based on error estimate obtained from extrapolation within the quadrature nodes.

This error estimate depends on solving the collocation problem exactly, so make sure you set a sufficient stopping criterion.

dependencies(controller, description, **kwargs)[source]

Load the error estimator.

Parameters:

  • controller (pySDC.Controller) – The controller

  • description (dict) – The description object used to instantiate the controller

Returns:

None

get_convergence(controller, S, **kwargs)[source]
get_local_error_estimate(controller, S, **kwargs)[source]

Get the embedded error estimate of the finest level of the step.

Parameters:

  • controller (pySDC.Controller) – The controller

  • S (pySDC.Step) – The current step

Returns:

Embedded error estimate

Return type:

float

get_new_step_size(controller, S, **kwargs)[source]

Determine a step size for the next step from the error estimate.

Parameters:

  • controller (pySDC.Controller) – The controller

  • S (pySDC.Step) – The current step

Returns:

None

setup(controller, params, description, **kwargs)[source]

Add a default value for control order to the parameters.

Parameters:

  • controller (pySDC.Controller) – The controller

  • params (dict) – Parameters for the convergence controller

  • description (dict) – The description object used to instantiate the controller

Returns:

Updated parameters

Return type:

dict

class AdaptivityForConvergedCollocationProblems(controller, params, description, **kwargs)[source]

Bases: AdaptivityBase

dependencies(controller, description, **kwargs)[source]

Load interpolation between restarts.

Parameters:

  • controller (pySDC.Controller) – The controller

  • description (dict) – The description object used to instantiate the controller

Returns:

None

determine_restart(controller, S, **kwargs)[source]

Check if the step wants to be restarted by comparing the estimate of the local error to a preset tolerance

Parameters:

  • controller (pySDC.Controller) – The controller

  • S (pySDC.Step) – The current step

Returns:

None

get_convergence(controller, S, **kwargs)[source]
setup(controller, params, description, **kwargs)[source]

Add a default value for control order to the parameters.

Parameters:

  • controller (pySDC.Controller) – The controller

  • params (dict) – Parameters for the convergence controller

  • description (dict) – The description object used to instantiate the controller

Returns:

Updated parameters

Return type:

dict

trigger_restart_upon_nonconvergence(S)[source]
class AdaptivityPolynomialError(controller, params, description, **kwargs)[source]

Bases: AdaptivityForConvergedCollocationProblems

Class to compute time step size adaptively based on error estimate obtained from interpolation within the quadrature nodes.

This error estimate depends on solving the collocation problem exactly, so make sure you set a sufficient stopping criterion.

dependencies(controller, description, **kwargs)[source]

Load the error estimator.

Parameters:

  • controller (pySDC.Controller) – The controller

  • description (dict) – The description object used to instantiate the controller

Returns:

None

get_convergence(controller, S, **kwargs)[source]
get_local_error_estimate(controller, S, **kwargs)[source]

Get the embedded error estimate of the finest level of the step.

Parameters:

  • controller (pySDC.Controller) – The controller

  • S (pySDC.Step) – The current step

Returns:

Embedded error estimate

Return type:

float

get_new_step_size(controller, S, **kwargs)[source]

Determine a step size for the next step from the error estimate.

Parameters:

  • controller (pySDC.Controller) – The controller

  • S (pySDC.Step) – The current step

Returns:

None

setup(controller, params, description, **kwargs)[source]

Add a default value for control order to the parameters.

Parameters:

  • controller (pySDC.Controller) – The controller

  • params (dict) – Parameters for the convergence controller

  • description (dict) – The description object used to instantiate the controller

Returns:

Updated parameters

Return type:

dict

class AdaptivityRK(controller, params, description, **kwargs)[source]

Bases: Adaptivity

Adaptivity for Runge-Kutta methods. Basically, we need to change the order in the step size update

get_new_step_size(controller, S, **kwargs)[source]

Determine a step size for the next step from an embedded estimate of the local error of the current step.

Parameters:

  • controller (pySDC.Controller) – The controller

  • S (pySDC.Step) – The current step

Returns:

None

setup(controller, params, description, **kwargs)[source]

Define default parameters here.

Default parameters are:

  • control_order (int): The order relative to other convergence controllers

  • beta (float): The safety factor

Parameters:

  • controller (pySDC.Controller) – The controller

  • params (dict) – The params passed for this specific convergence controller

  • description (dict) – The description object used to instantiate the controller

Returns:

The updated params dictionary

Return type:

(dict)

class AdaptivityResidual(controller, params, description, **kwargs)[source]

Bases: AdaptivityBase

Do adaptivity based on residual.

Since we don’t know a correlation between the residual and the error (for nonlinear problems), we employ a simpler rule to update the step size. Instead of giving a local tolerance that we try to hit as closely as possible, we set two thresholds for the residual. When we exceed the upper one, we reduce the step size by a factor of 2 and if the residual falls below the lower threshold, we double the step size. Please setup these parameters as “e_tol” and “e_tol_low”.

check_parameters(controller, params, description, **kwargs)[source]

Check whether parameters are compatible with whatever assumptions went into the step size functions etc.

Parameters:

  • controller (pySDC.Controller) – The controller

  • params (dict) – The params passed for this specific convergence controller

  • description (dict) – The description object used to instantiate the controller

Returns:

Whether the parameters are compatible str: The error message

Return type:

bool

get_local_error_estimate(controller, S, **kwargs)[source]

Get the residual of the finest level of the step.

Parameters:

  • controller (pySDC.Controller) – The controller

  • S (pySDC.Step) – The current step

Returns:

Embedded error estimate

Return type:

float

get_new_step_size(controller, S, **kwargs)[source]

Determine a step size for the next step. If we exceed the absolute tolerance of the residual in either direction, we either double or halve the step size.

Parameters:

  • controller (pySDC.Controller) – The controller

  • S (pySDC.Step) – The current step

Returns:

None

setup(controller, params, description, **kwargs)[source]

Define default parameters here.

Default parameters are:

  • control_order (int): The order relative to other convergence controllers

  • e_tol_low (float): Lower absolute threshold for the residual

  • e_tol (float): Upper absolute threshold for the residual

  • use_restol (bool): Restart if the residual tolerance was not reached

  • max_restarts: Override maximum number of restarts

Parameters:

  • controller (pySDC.Controller) – The controller

  • params (dict) – The params passed for this specific convergence controller

  • description (dict) – The description object used to instantiate the controller

Returns:

The updated params dictionary

Return type:

(dict)

setup_status_variables(controller, **kwargs)[source]

Change maximum number of allowed restarts here.

Parameters:

controller (pySDC.Controller) – The controller

Reutrns:

None