2.4.12.1. A skeleton of the user’s main program

While SplittingStep usage generally follows the same pattern as the rest of ARKODE, since it is the composition of other steppers, we summarize the differences in using SplittingStep 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 a stepper object for each problem partition

    • If using an ARKODE stepper module as an partition integrator, create and configure the stepper as normal following the steps detailed in the section for the desired stepper.

      Once the ARKODE stepper object is setup, create a SUNStepper object with ARKodeCreateSUNStepper().

    • If supplying a user-defined partition integrator, create the SUNStepper object as described in section §14.2.

    Note

    When using ARKODE for partition integrators, it is the user’s responsibility to create and configure the integrator. User-specified options regarding how the integration should be performed (e.g., adaptive vs. fixed time step, explicit/implicit/ImEx partitioning, algebraic solvers, etc.) will be respected during evolution of a partition during SplittingStep integration.

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

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

  6. Create a SplittingStep object

    Create the SplittingStep object by calling SplittingStepCreate(). One of the inputs to SplittingStepCreate() is an array of SUNStepper objects with one to evolve each partition.

  7. Set the SplittingStep step size

    Call ARKodeSetFixedStep() on the SplittingStep object to specify the overall time step size.

  8. Set optional inputs

  9. Specify rootfinding problem

  10. Advance solution in time

  11. Get optional outputs

  12. Deallocate memory for solution vector

  13. Free solver memory

    • If an ARKODE stepper module was used as a partition IVP integrator, call SUNStepper_Destroy() and ARKodeFree() to free the memory allocated for that integrator.

    • If a user-defined partition integrator was supplied, free the integrator content and call SUNStepper_Destroy() to free the SUNStepper object.

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

  14. Free the SUNContext object

  15. Finalize MPI, if used