Add SUNDIALS + hypre example

Docs/source/SUNDIALS_Tutorial.rst

@@ -22,7 +22,19 @@ user-supplied reaction and diffusion coefficients:
 
 The inputs file contains a template for MRI approaches, where the diffusion process
 can be treated as a "fast" partition relative to the reaction process.
-Please see each respective inputs file or
+
+The third example code at ``amrex-tutorials/ExampleCodes/SUNDIALS/AdvDiff-MLMGPrecon``
+solves the advection-diffusion equation, where :math:`A` and :math:`D` are
+user-supplied advection and diffusion coefficients:
+
+.. math:: \frac{\partial\phi}{\partial t} = D \nabla^2\phi - A \nabla\phi.
+
+The inputs file contains a template for IMEX approaches, where diffusion is
+treated implicitly with a SUNDIALS preconditioner that uses AMReX MLMG. The
+example can also use MLMG's HYPRE bottom solver interface when AMReX is built
+with HYPRE support.
+
+Please see the inputs file or
 `AMReX User Guide:Time Integration`_ for more details.
 
 .. _`AMReX User Guide:Time Integration`: https://amrex-codes.github.io/amrex/docs_html/TimeIntegration_Chapter.html#

ExampleCodes/SUNDIALS/AdvDiff-MLMGPrecon/CMakeLists.txt

@@ -0,0 +1,15 @@
+if (AMReX_SPACEDIM EQUAL 1 OR NOT AMReX_LINEAR_SOLVERS)
+   return()
+endif ()
+
+# List of source files
+set(_sources main.cpp myfunc.H)
+list(TRANSFORM _sources PREPEND "Source/")
+
+# List of input files
+file( GLOB_RECURSE _input_files LIST_DIRECTORIES false Exec/input* )
+
+setup_tutorial(_sources _input_files)
+
+unset( _sources )
+unset( _input_files   )

ExampleCodes/SUNDIALS/AdvDiff-MLMGPrecon/Exec/GNUmakefile

@@ -0,0 +1,23 @@
+# AMREX_HOME defines the directory in which we will find all the AMReX code.
+AMREX_HOME ?= ../../../../../amrex
+
+DEBUG        = FALSE
+USE_MPI      = TRUE
+USE_OMP      = FALSE
+COMP         = gnu
+DIM          = 2
+USE_SUNDIALS = TRUE
+USE_HYPRE   ?= FALSE
+SUNDIALS_HOME ?= ../../../../../sundials/instdir
+
+include $(AMREX_HOME)/Tools/GNUMake/Make.defs
+
+include ../Source/Make.package
+VPATH_LOCATIONS  += ../Source
+INCLUDE_LOCATIONS += ../Source
+
+Pdirs := Base Boundary LinearSolvers/MLMG
+Ppack += $(foreach dir, $(Pdirs), $(AMREX_HOME)/Src/$(dir)/Make.package)
+include $(Ppack)
+
+include $(AMREX_HOME)/Tools/GNUMake/Make.rules

ExampleCodes/SUNDIALS/AdvDiff-MLMGPrecon/Exec/README_sundials

@@ -0,0 +1,11 @@
+Refer to https://amrex-codes.github.io/amrex/docs_html/TimeIntegration_Chapter.html
+for SUNDIALS installation, build, and usage instructions.
+
+Make sure that SUNDIALS_HOME in the GNUmakefile points to the installation directory.
+This tutorial also requires AMReX to be built with MLMG linear solver support.
+The default inputs use a SUNDIALS IMEX-RK method with GMRES and an AMReX MLMG
+preconditioner for the implicit diffusion solve.
+
+Set USE_HYPRE=TRUE when building and mlmg.use_hypre=1 in inputs_sundials to use
+MLMG's HYPRE bottom solver interface. The HYPRE interface and options namespace
+are controlled by mlmg.hypre_interface and mlmg.hypre_options_namespace.

ExampleCodes/SUNDIALS/AdvDiff-MLMGPrecon/Exec/inputs_sundials

@@ -0,0 +1,57 @@
+n_cell = 256
+max_grid_size = 128
+
+dt = 1.e-5
+nsteps = 100
+plot_int = 100
+
+advCoeffx = 100.
+advCoeffy = 100.
+
+diffCoeffx = 1.
+diffCoeffy = 1.
+
+# Use adaptive time stepping (multi-stage integrators only!) and set integrator relative and absolute tolerances
+# adapt_dt = true
+# reltol   = 1.0e-4
+# abstol   = 1.0e-9
+
+# INTEGRATION
+## integration.type can take on the following values:
+## 0 or "ForwardEuler" => Native AMReX Forward Euler integrator
+## 1 or "RungeKutta"   => Native AMReX Explicit Runge Kutta controlled by integration.rk.type
+## 2 or "SUNDIALS"     => SUNDIALS backend controlled by integration.sundials.type
+#integration.type = ForwardEuler
+#integration.type = RungeKutta
+integration.type = SUNDIALS
+
+# Set the SUNDIALS method type:
+# ERK      = Explicit Runge-Kutta method
+# DIRK     = Diagonally Implicit Runge-Kutta method
+# IMEX-RK  = Implicit-Explicit Additive Runge-Kutta method
+# EX-MRI   = Explicit Multirate Infatesimal method
+# IM-MRI   = Implicit Multirate Infatesimal method
+# IMEX-MRI = Implicit-Explicit Multirate Infatesimal method
+#
+# Optionally select a specific SUNDIALS method by name, see the SUNDIALS
+# documentation for the supported method names
+integration.sundials.type = IMEX-RK
+integration.sundials.method_i = ARKODE_ARK2_DIRK_3_1_2
+integration.sundials.method_e = ARKODE_ARK2_ERK_3_1_2
+integration.sundials.linear_solver = GMRES
+integration.sundials.linear_solver_preconditioning = LEFT
+integration.sundials.max_linear_iters = 20
+
+# MLMG settings for the SUNDIALS preconditioner solve
+mlmg.max_iter = 100
+mlmg.max_fmg_iter = 0
+mlmg.verbose = 0
+mlmg.bottom_verbose = 0
+mlmg.use_hypre = 0
+mlmg.hypre_interface = 3  # 1 = structed, 2 = semi_structed, 3 = ij
+mlmg.hypre_options_namespace = hypre
+mlmg.reltol = 1.e-10
+mlmg.abstol = 0.0
+
+# HYPRE settings used when mlmg.use_hypre = 1 and mlmg.hypre_interface = 3
+hypre.hypre_solver = BoomerAMG

ExampleCodes/SUNDIALS/AdvDiff-MLMGPrecon/Source/Make.package

@@ -0,0 +1,2 @@
+CEXE_sources += main.cpp
+CEXE_headers += myfunc.H