SUNDIALS Documentation

repository·main·Indexed 20 days ago

https://github.com/llnl/sundials

A suite of high-performance software packages for solving ordinary differential equations (ODEs), differential-algebraic equations (DAEs), and nonlinear algebraic systems. The suite includes ARKODE for stiff, nonstiff, and multirate ODEs; CVODE for explicit ODEs; IDA for DAEs; and KINSOL for nonlinear algebraic systems. It supports serial, threaded, distributed, and GPU accelerated computing (CUDA, HIP) and provides official Python bindings via sundials4py.

Tokens
241.1K
Snippets
737
Records
965
Agent score
70%

What's inside SUNDIALS

  1. Overview of KINSOL nonlinear solver

    main

    KINSOL is a package designed to solve nonlinear algebraic systems of the form:

    F(u) = 0

    It supports several nonlinear solver methods:

    • Newton-Krylov
    • Picard
    • Fixed-point

    Both Picard and fixed-point methods can be enhanced using Anderson acceleration.

    KINSOL is built with a modular design that leverages shared vector, matrix, and linear solver APIs used across the SUNDIALS suite. This allows it to run in various computing environments, including serial, shared memory, distributed memory, and accelerator-based (e.g., GPU) systems.

  2. Overview of CVODE for ODE systems

    main

    CVODE is a package designed to solve stiff and nonstiff ordinary differential equation (ODE) systems (initial value problems) provided in the explicit form:

    dy/dt = f(t,y), y(t0) = y0.

    It offers two primary variable-order, variable-coefficient multistep methods:

    1. Adams-Moulton methods: Optimized for non-stiff problems.
    2. BDF (Backward Differentiation Formula) methods: Optimized for stiff problems (using fixed-leading-coefficient form).

    CVODE is written in ANSI standard C and is part of the SUNDIALS suite. Its modular design allows it to run in various environments, including serial, shared memory, distributed memory, and accelerator-based (e.g., GPU) systems by leveraging shared APIs for vectors, matrices, linear solvers, and nonlinear solvers.

  3. Overview of CVODES for ODE systems with sensitivity analysis

    main

    CVODES is a package designed to solve stiff and nonstiff ordinary differential equation (ODE) systems (initial value problems) provided in the explicit form:

    dy/dt = f(t,y,p), y(t0) = y0(p)

    Key features include:

    • Sensitivity Analysis: Supports both forward and adjoint modes.
    • Solver Methods:
      • Adams-Moulton methods: For non-stiff problems.
      • BDF (Backward Differentiation Formula) methods: In fixed-leading-coefficient form for stiff problems.
    • Modular Design: Leverages shared SUNDIALS APIs for vectors, matrices, linear solvers, and nonlinear solvers, allowing it to run on serial, shared memory, distributed memory, and accelerator-based (e.g., GPU) systems.
    dy/dt = f(t,y,p), y(t0) = y0(p)
  4. Overview of IDA for Differential-Algebraic Equation (DAE) systems

    main

    IDA is a package designed to solve differential-algebraic equation (DAE) systems of the form:

    F(t, y, y') = 0, y(t0) = y0, y'(t0) = y0'

    It utilizes variable-order, variable-coefficient BDF (Backward Differentiation Formula) methods in fixed-leading-coefficient form.

    As part of the SUNDIALS suite, IDA features a modular design that allows it to run in various computing environments, including:

    • Serial
    • Shared memory
    • Distributed memory
    • Accelerator-based systems (e.g., GPU)

    This modularity is achieved by leveraging shared vector, matrix, linear solver, and nonlinear solver APIs used across other SUNDIALS packages like ARKode, CVODE, and KINSOL.

  5. Overview of IDAS for DAE systems

    main

    IDAS is a package designed for solving differential-algebraic equation (DAE) systems of the form:

    F(t, y, y', p) = 0, y(t0) = y0(p), y'(t0) = y0'(p)

    It includes sensitivity analysis capabilities in both forward and adjoint modes. The solver utilizes variable-order, variable-coefficient BDF (Backward Differentiation Formula) methods in fixed-leading-coefficient form.

    IDAS is part of the SUNDIALS suite and is written in ANSI standard C. It is designed to be modular, leveraging shared APIs for vectors, matrices, linear solvers, and nonlinear solvers, allowing it to run in serial, shared memory, distributed memory, and accelerator-based (e.g., GPU) environments.

  6. Using IDA for IVP Solution

    main

    IDA is used for the integration of Differential-Algebraic Equations (DAEs). When using IDA, users must ensure compatibility between different SUNDIALS objects. Specifically, not all SUNLinearSolver and SUNMatrix objects are compatible with all N_Vector implementations.

    Key Compatibility Notes:

    • NVECTOR_PARALLEL is not compatible with dense, banded, or sparse SUNMatrix types or their corresponding SUNLinearSolver objects.
    • The IDABBDPRE preconditioner can only be used with NVECTOR_PARALLEL.
    • When using SuperLU_MT, it is not recommended to use a threaded vector object unless it is the NVECTOR_OPENMP module and SuperLU_MT is also compiled with OpenMP.
  7. What is the ARKBBDPRE preconditioner module?

    main

    ARKBBDPRE is a parallel Band-Block-Diagonal preconditioner module designed for PDE-based problems solved with parallel ODE solvers like ARKODE. It is intended for use with the NVECTOR_PARALLEL vector module and any Krylov iterative linear solvers via the ARKLS interface.

    How it works:

    1. Domain Decomposition: The computational domain is subdivided into $Q$ non-overlapping subdomains, each assigned to an MPI task.
    2. Local Preconditioning: It generates a block-diagonal preconditioner $P$ where each block $P_q$ is a banded matrix approximating $I - \gamma J_q$. $J_q$ is a difference quotient approximation of the local Jacobian block.
    3. Efficiency: The module uses user-defined bandwidth parameters (mudq, mldq, mukeep, mlkeep) to control the width of the approximation and the storage, allowing for a more efficient preconditioner than the full Jacobian.
    4. Solving: The global system $Px = b$ is reduced to solving $Q$ independent local banded systems $P_q x_q = b_q$ using banded LU factorization and backsolve.
  8. Overview of SUNDIALS packages

    main

    SUNDIALS is a suite of software packages providing robust and efficient time integrators and nonlinear solvers. It is primarily written in C with interfaces for C++, Fortran, and Python, supporting serial, threaded, distributed, and GPU accelerated computing. The suite is divided into specialized packages based on the mathematical problem type:

    • ARKODE: Integrates stiff, nonstiff, and multirate ODEs of the form $M(t) y' = f_1(t,y) + f_2(t,y)$.
    • CVODE: Integrates stiff and nonstiff ODEs of the form $y' = f(t,y)$.
    • CVODES: Integrates ODEs and performs sensitivity analysis (forward and adjoint) of the form $y' = f(t,y,p)$.
    • IDA: Integrates DAEs of the form $F(t,y,y') = 0$.
    • IDAS: Integrates DAEs and performs sensitivity analysis (forward and adjoint) of the form $F(t,y,y',p) = 0$.
    • KINSOL: Solves nonlinear algebraic systems of the form $F(u) = 0$ or $G(u) = u$.
  9. What is ARKODE and when to use it

    main

    ARKODE is a package within the SUNDIALS suite designed for solving stiff, nonstiff, and multirate ordinary differential equation (ODE) systems (initial value problems). It is specifically designed for systems given in the linearly implicit form:

    M y' = f1(t,y) + f2(t,y), y(t0) = y0.

    ARKODE supports several integration methods:

    • Explicit and implicit Runge-Kutta methods for standard ODEs.
    • Implicit-explicit (IMEX) additive Runge-Kutta methods for systems where different parts of the vector field have different stiffness levels.
    • Multirate infinitesimal (MRI) methods for multirate problems.

    It is written in ANSI standard C and is highly portable, supporting serial, shared memory, distributed memory, and accelerator-based (e.g., GPU) computing environments due to its modular design.

  10. Using CVODES for Initial Value Problem (IVP) Solutions

    main

    CVODES is used to solve Initial Value Problems (IVPs) and provides linear multistep methods with sensitivity analysis. When building applications with CVODES, you must ensure compatibility between your chosen N_Vector implementation and your SUNLinearSolver or SUNMatrix modules.

    Compatibility Notes:

    • NVECTOR_PARALLEL is not compatible with dense, banded, or sparse SUNMatrix types or their corresponding SUNLinearSolver modules.
    • The CVBANDPRE preconditioning module is only compatible with NVECTOR_SERIAL, NVECTOR_OPENMP, and NVECTOR_PTHREADS.
    • The CVBBDPRE preconditioner module can only be used with NVECTOR_PARALLEL.
    • If using SuperLU_MT, it is recommended to use the NVECTOR_OPENMP module, provided SuperLU_MT is also compiled with OpenMP.
  11. Required history data for CVodeResizeHistory

    main

    The amount of history required for CVodeResizeHistory depends on the integration method and the current order $q$. Let $k = \min{q+1, q_{\text{max}}}$.

    MethodRequired Solution Vectors ($y$)Required RHS Vectors ($f$)
    Adams$y(t_n), y(t_{n-1})$$f(t_n, y(t_n)), \dots, f(t_{n-k}, y(t_{n-k}))$
    BDF$y(t_n), y(t_{n-1}), \dots, y(t_{n-k})$$f(t_n, y(t_n)), f(t_{n-1}, y(t_{n-1}))$

    Note on History Ordering: Time values in t_hist must be ordered from most recent to oldest ($t_n > t_{n-1} > \dots$ for forward integration; $t_n < t_{n-1} < \dots$ for backward integration).

  12. How sensitivity variables affect step size selection in CVODES

    main

    When performing Forward Sensitivity Analysis (FSA), users can choose to exclude sensitivities from the error control test using CVodeSetSensErrCon. However, even with partial error control, sensitivity variables can still influence the step size selection through the nonlinear solver's convergence mechanism.

    Mechanisms of Influence

    1. Nonlinear Solver Convergence: Even with partial error control, sensitivity variables are included in the convergence tests of the nonlinear solver. The step size selection is based on the magnitude of the correction calculated by the nonlinear solver.
    2. Simultaneous Corrector Method: When using the simultaneous corrector method, the nonlinear system solved at each step involves both state and sensitivity equations. The convergence rate of the sensitivity equations directly affects the step size.
    3. Staggered Corrector Method: In staggered approaches (CV_STAGGERED or CV_STAGGERED1), sensitivities are computed after the state equations converge. However, if the sensitivity nonlinear system has convergence problems, CVODES may reduce the step size to improve the initial guess. Additionally, solving the sensitivity system may trigger calls to the linear solver's setup routine (e.g., reevaluating Jacobian information in CVDENSE/CVBAND or preconditioner data in Krylov solvers), which affects subsequent state equation steps.

    Monitoring Sensitivity Impact

    If using a staggered corrector method, you can determine if sensitivities are affecting step size by monitoring diagnostic information. If there are no convergence failures in the sensitivity nonlinear solver and no calls to the linear solver setup routine were made by the sensitivity solver, then the step size selection is not being affected by the sensitivity variables.

    Performance Warning

    Appending sensitivity equations to an ODE system can either increase or decrease the total number of steps taken by CVODES. While more up-to-date Jacobian information might suggest larger steps, a larger step taken at one point can lead to step size reductions later due to nonlinear solver convergence failures or error test failures.