2.4.10.1. A skeleton of the user’s main program

While MRIStep usage generally follows the same pattern as the rest of ARKODE, since it involves the solution of both MRIStep for the slow time scale and another time integrator for the fast time scale, we summarize the differences in using MRIStep here. Steps that are unchanged from the skeleton program presented in §2.4.2 are italicized.

  1. Initialize parallel or multi-threaded environment, if appropriate.

  2. Create the SUNDIALS simulation context object

  3. Set problem dimensions, etc.

  4. Set vector of initial values

  5. Create an inner stepper object to solve the fast (inner) IVP

    • If using ARKStep as the fast (inner) integrator, create the ARKStep object with ARKStepCreate() and configure the integrator as desired for evolving the fast time scale. See sections §2.4.2, §2.4.3.7, and §2.4.7.1.8 for details on configuring ARKStep.

      Once the ARKStep object is setup, create an MRIStepInnerStepper object with ARKStepCreateMRIStepInnerStepper().

    • If supplying a user-defined fast (inner) integrator, create the MRIStepInnerStepper object as described in section §2.4.10.4.

    Note

    When using ARKStep as a fast (inner) integrator it is the user’s responsibility to create, configure, and attach the integrator to the MRIStep module. User-specified options regarding how this fast integration should be performed (e.g., adaptive vs. fixed time step, explicit/implicit/ImEx partitioning, algebraic solvers, etc.) will be respected during evolution of the fast time scale during MRIStep integration.

    Due to the algorithms supported in MRIStep, the ARKStep module used for the fast time scale must be configured with an identity mass matrix.

    If a user_data pointer needs to be passed to user functions called by the fast (inner) integrator then it should be attached here by calling ARKodeSetUserData(). This user_data pointer will only be passed to user-supplied functions that are attached to the fast (inner) integrator. To supply a user_data pointer to user-supplied functions called by the slow (outer) integrator the desired pointer should be attached by calling ARKodeSetUserData() after creating the MRIStep memory below. The user_data pointers attached to the inner and outer integrators may be the same or different depending on what is required by the user code.

    Specifying a rootfinding problem for the fast integration is not supported. Rootfinding problems should be created and initialized with the slow integrator. See the steps below and ARKodeRootInit() for more details.

  6. Create an MRIStep object for the slow (outer) integration

    Create the MRIStep object by calling MRIStepCreate(). One of the inputs to MRIStepCreate() is the MRIStepInnerStepper object for solving the fast (inner) IVP created in the previous step.

  7. Set the slow step size

    Call ARKodeSetFixedStep() on the MRIStep object to specify the slow time step size.

  8. Create and configure implicit solvers (as appropriate)

    Specifically, if MRIStep is configured with an implicit slow right-hand side function in the prior step, then the following steps are recommended:

    1. Specify integration tolerances

    2. Create matrix object

    3. Create linear solver object

    4. Set linear solver optional inputs

    5. Attach linear solver module

    6. Create nonlinear solver object

    7. Attach nonlinear solver module

    8. Set nonlinear solver optional inputs

  9. Set optional inputs

  10. Specify rootfinding problem

  11. Advance solution in time

  12. Get optional outputs

  13. Deallocate memory for solution vector

  14. Free solver memory

    • If ARKStep was used as the fast (inner) IVP integrator, call MRIStepInnerStepper_Free() and ARKodeFree() to free the memory allocated for the fast (inner) integrator.

    • If a user-defined fast (inner) integrator was supplied, free the integrator content and call MRIStepInnerStepper_Free() to free the MRIStepInnerStepper object.

    • Call ARKodeFree() to free the memory allocated for the MRIStep slow integration object.

  15. Free linear solver and matrix memory (as appropriate)

  16. Free nonlinear solver memory (as appropriate)

  17. Free the SUNContext object

  18. Finalize MPI, if used