core.ConvergenceController module

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

Bases: object

Base abstract class for convergence controller, which is plugged into the controller to determine the iteration count and time step size.

Recv(comm, source, buffer, **kwargs)[source]

Receive some data

Parameters:

  • comm (mpi4py.MPI.Intracomm) – Communicator

  • source (int) – Where to look for receiving

Returns:

whatever has been received

Send(comm, dest, buffer, blocking=False, **kwargs)[source]

Send data to a different rank

Parameters:

  • comm (mpi4py.MPI.Intracomm) – Communicator

  • dest (int) – The target rank

  • buffer – Buffer for the data

  • blocking (bool) – Whether the communication is blocking or not

Returns:

request handle of the communication

add_variable(controller, name, MPI=False, place=None, where=None, init=None, allow_overwrite=False)[source]

Add a variable to a frozen class.

This function goes through the path to the destination of the variable recursively and adds it to all instances that are possible in the path. For example, giving where = [“MS”, “levels”, “status”] will result in adding a variable to the status object of all levels of all steps of the controller.

Part of the functionality of the frozen class is to separate initialization and setting of variables. By enforcing this, you can make sure not to overwrite already existing variables. Since this function is called outside of the __init__ function of the status objects, this can otherwise lead to bugs that are hard to find. For this reason, you need to specifically set allow_overwrite = True if you want to forgo the check if the variable already exists. This can be useful when resetting variables between steps, but make sure to set it to allow_overwrite = False the first time you add a variable.

Parameters:

  • controller (pySDC.Controller) – The controller

  • name (str) – The name of the variable

  • MPI (bool) – Whether to use MPI controller

  • place (object) – The object you want to add the variable to

  • where (list) – List of strings containing a path to where you want to add the variable

  • init – Initial value of the variable

  • allow_overwrite (bool) – Allow overwriting the variables if they already exist or raise an exception

Returns:

None

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

Determine whether to keep iterating or not in this function.

Parameters:

  • controller (pySDC.Controller) – The controller

  • S (pySDC.Step) – The current step

Returns:

None

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

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

Call all the functions related to convergence control. This is called in it_check in the controller after every iteration just after post_iteration_processing. :param controller: The controller :type controller: pySDC.Controller :param S: The current step :type S: pySDC.Step

Returns:

None

debug(msg, S, **kwargs)[source]

Shortcut to pass messages at debug level to the logger.

Parameters:

  • msg (str) – Message you want to log

  • S (pySDC.step) – The current step

Returns:

None

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

Load dependencies on other convergence controllers here.

Parameters:

  • controller (pySDC.Controller) – The controller

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

Returns:

None

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

Determine for each step separately if it wants to be restarted for whatever reason.

Parameters:

  • controller (pySDC.Controller) – The controller

  • S (pySDC.Step) – The current step

Returns:

None

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

This function allows to set a step size with arbitrary criteria. Make sure to give an order to the convergence controller by setting the control_order variable in the params. This variable is an integer and you can see what the current order is by using controller.print_convergence_controllers().

Parameters:

  • controller (pySDC.Controller) – The controller

  • S (pySDC.Step) – The current step

Returns:

None

log(msg, S, level=15, **kwargs)[source]

Shortcut that has a default level for the logger. 15 is above debug but below info.

Parameters:

  • msg (str) – Message you want to log

  • S (pySDC.step) – The current step

  • level (int) – the level passed to the logger

Returns:

None

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

Do whatever you want to after each iteration here.

Parameters:

  • controller (pySDC.Controller) – The controller

  • S (pySDC.Step) – The current step

Returns:

None

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

This function is called at the end of the SPREAD stage in the controller

Parameters:

  • controller (pySDC.Controller) – The controller

  • S (pySDC.Step) – The current step

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

Do whatever you want to after each step here.

Parameters:

  • controller (pySDC.Controller) – The controller

  • S (pySDC.Step) – The current step

Returns:

None

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

Do whatever you want to before each iteration here.

Parameters:

  • controller (pySDC.Controller) – The controller

  • S (pySDC.Step) – The current step

Returns:

None

prepare_MPI_datatypes()[source]

Prepare MPI datatypes so we don’t need to import mpi4py all the time

prepare_MPI_logical_operations()[source]

Prepare MPI logical operations so we don’t need to import mpi4py all the time

prepare_next_block(controller, S, size, time, Tend, **kwargs)[source]

Prepare stuff like spreading step sizes or whatever.

Parameters:

  • controller (pySDC.Controller) – The controller

  • S (pySDC.Step) – The current step

  • size (int) – The number of ranks

  • time (float) – The current time will be list in nonMPI controller implementation

  • Tend (float) – The final time

Returns:

None

recv(comm, source, **kwargs)[source]

Receive some data

Parameters:

  • comm (mpi4py.MPI.Intracomm) – Communicator

  • source (int) – Where to look for receiving

Returns:

whatever has been received

reset_buffers_nonMPI(controller, **kwargs)[source]

Buffers refer to variables used across multiple steps that are stored in the convergence controller classes to imitate communication in non MPI versions. These have to be reset in order to replicate availability of variables in MPI versions.

For instance, if step 0 sets self.buffers.x = 1 from self.buffers.x = 0, when the same MPI rank uses the variable with step 1, it will still carry the value of self.buffers.x = 1, equivalent to a send from the rank computing step 0 to the rank computing step 1.

However, you can only receive what somebody sent and in order to make sure that is true for the non MPI versions, we reset after each iteration so you cannot use this function to communicate backwards from the last step to the first one for instance.

This function is called both at the end of instantiating the controller, as well as after each iteration.

Parameters:

controller (pySDC.Controller) – The controller

Returns:

None

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

reset_variable(controller, name, MPI=False, place=None, where=None, init=None)[source]

Utility function for resetting variables. This function will call the add_variable function with all the same arguments, but with allow_overwrite = True.

Parameters:

  • controller (pySDC.Controller) – The controller

  • name (str) – The name of the variable

  • MPI (bool) – Whether to use MPI controller

  • place (object) – The object you want to reset the variable of

  • where (list) – List of strings containing a path to where you want to reset the variable

  • init – Initial value of the variable

Returns:

None

send(comm, dest, data, blocking=False, **kwargs)[source]

Send data to a different rank

Parameters:

  • comm (mpi4py.MPI.Intracomm) – Communicator

  • dest (int) – The target rank

  • data – Data to be sent

  • blocking (bool) – Whether the communication is blocking or not

Returns:

request handle of the communication

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

Setup various variables that only need to be set once in the beginning. If the convergence controller is added automatically, you can give it params by adding it manually. It will be instantiated only once with the manually supplied parameters overriding automatically added parameters.

This function scans the convergence controllers supplied to the description object for instances of itself. This corresponds to the convergence controller being added manually by the user. If something is found, this function will then return a composite dictionary from the params passed to this function as well as the params passed manually, with priority to manually added parameters. If you added the convergence controller manually, that is of course the same and nothing happens. If, on the other hand, the convergence controller was added automatically, the params passed here will come from whatever added it and you can now override parameters by adding the convergence controller manually. This relies on children classes to return a composite dictionary from their defaults and from the result of this function, so you should write ` return {**defaults, **super().setup(controller, params, description, **kwargs)} ` when overloading this method in a child class, with defaults a dictionary containing default parameters.

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 after setup

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 Pars(params)[source]

Bases: FrozenClass

class Status(status_variabes)[source]

Bases: FrozenClass

Initialize status variables with None, since at the time of instantiation of the convergence controllers, not all relevant information about the controller are known.