Pull request #522: Bugfix/fortran mristepcoupling

Merge in SUNDIALS/sunrepo from bugfix/fortran-mristepcoupling to develop

Squashed commit of the following:

commit dd4522bcd1e920ea22a0ed939d27b8fc95e9b39f
Author: David J. Gardner <gardner48@llnl.gov>
Date:   Mon Feb 7 13:27:41 2022 -0800

    remove unused vars

commit 4338fd6a2e99f59d510acb0c00637446891da64b
Merge: 7a09ab055 4fd3124
Author: David J. Gardner <gardner48@llnl.gov>
Date:   Mon Feb 7 13:13:32 2022 -0800

    Merge branch 'develop' into bugfix/fortran-mristepcoupling

commit 7a09ab055b582f4dfb49b5ba864a44f869af2a47
Author: Balos, Cody Joe <balos1@llnl.gov>
Date:   Mon Feb 7 09:14:31 2022 -0800

    doc fixes

commit 500d50c2a0e5964780dce5c40f8057a887b1794a
Author: Balos, Cody Joe <balos1@llnl.gov>
Date:   Thu Feb 3 16:28:13 2022 -0800

    fix output files

commit 5b116061152fa1000908665e9616e1a3816d0ff3
Author: Balos, Cody Joe <balos1@llnl.gov>
Date:   Thu Feb 3 16:25:12 2022 -0800

    fix typos in Butcher tables

commit 9da43d9dc8fc5a54dbfc58cc36c864ad282c7b7d
Author: Balos, Cody Joe <balos1@llnl.gov>
Date:   Thu Feb 3 15:58:57 2022 -0800

    all cases running now

commit ab578967cf223197014d61cb4480ee9a9578a462
Author: Balos, Cody Joe <balos1@llnl.gov>
Date:   Wed Feb 2 17:30:45 2022 -0800

    translate ark_kpr_mri.c to Fortran 2003

commit 5d99f2f014ea3a72aaaf5250868d76f1574e7059
Author: Balos, Cody Joe <balos1@llnl.gov>
Date:   Wed Jan 26 12:46:33 2022 -0800

    treat MRIStepCoupling and MRIStepInnerStepper as void* in fortran

CHANGELOG.md

@@ -4,6 +4,13 @@
 
 Fixed exported `SUNDIALSConfig.cmake`.
 
+Fixed Fortran interface to `MRIStepInnerStepper` and ``MRIStepCoupling`
+structures and functions.
+
+Added new Fortran example program,
+`examples/arkode/F2003_serial/ark_kpr_mri_f2003.f90` demonstrating MRI
+capabilities.
+
 ## Changes to SUNDIALS in release 6.1.0
 
 Added new reduction implementations for the CUDA and HIP NVECTORs that use

doc/arkode/guide/source/ARKodeButcherTable.rst

@@ -165,6 +165,10 @@ ARKodeButcherTable functions
       If the method does not have an embedding then *d* should be
       ``NULL`` and *p* should be equal to zero.
 
+      .. warning::
+         When calling this function from Fortran, it is important to note that ``A`` is expected
+         to be in row-major ordering.
+
 .. c:function:: ARKodeButcherTable ARKodeButcherTable_Copy(ARKodeButcherTable B)
 
    Creates copy of the given Butcher table.

doc/arkode/guide/source/Introduction.rst

@@ -123,6 +123,13 @@ Changes in vx.x.x
 
 Fixed exported ``SUNDIALSConfig.cmake``.
 
+Fixed Fortran interface to :c:type:`MRIStepInnerStepper` and :c:type:`MRIStepCoupling`
+structures and functions.
+
+Added new Fortran example program,
+``examples/arkode/F2003_serial/ark_kpr_mri_f2003.f90`` demonstrating MRI
+capabilities.
+
 Changes in v5.1.0
 -----------------
 

doc/shared/sundials/Fortran.rst

@@ -533,3 +533,70 @@ Upon compilation of SUNDIALS, Fortran module (``.mod``) files are generated for
 each Fortran 2003 interface. These files are highly compiler specific, and thus
 it is almost always necessary to compile a consuming application with the same
 compiler that was used to generate the modules.
+
+
+.. _SUNDIALS.Fortran.CommonIssues:
+
+Common Issues
+-------------
+
+In this subsection, we list some common issues users run into when using the Fortran
+interfaces.
+
+
+**Strange Segmentation Fault in User-Supplied Functions**
+
+One common issue we have seen trip up users (and even ourselves) has the symptom
+of segmentation fault in a user-supplied function (such as the RHS) when trying
+to use one of the callback arguments. For example, in the following RHS
+function, we will get a segfault on line 21:
+
+.. code-block:: fortran
+   :linenos:
+   :emphasize-lines: 8, 21
+
+   integer(c_int) function ff(t, yvec, ydotvec, user_data) &
+      result(ierr) bind(C)
+
+      use, intrinsic :: iso_c_binding
+      use fsundials_nvector_mod
+      implicit none
+
+      real(c_double) :: t ! <===== Missing value attribute
+      type(N_Vector) :: yvec
+      type(N_Vector) :: ydotvec
+      type(c_ptr)    :: user_data
+
+      real(c_double) :: e
+      real(c_double) :: u, v
+      real(c_double) :: tmp1, tmp2
+      real(c_double), pointer :: yarr(:)
+      real(c_double), pointer :: ydotarr(:)
+
+      ! get N_Vector data arrays
+      yarr => FN_VGetArrayPointer(yvec)
+      ydotarr => FN_VGetArrayPointer(ydotvec) ! <===== SEGFAULTS HERE
+
+      ! extract variables
+      u = yarr(1)
+      v = yarr(2)
+
+      ! fill in the RHS function:
+      !  [0  0]*[(-1+u^2-r(t))/(2*u)] + [         0          ]
+      !  [e -1] [(-2+v^2-s(t))/(2*v)]   [sdot(t)/(2*vtrue(t))]
+      tmp1 = (-ONE+u*u-r(t))/(TWO*u)
+      tmp2 = (-TWO+v*v-s(t))/(TWO*v)
+      ydotarr(1) = ZERO
+      ydotarr(2) = e*tmp1 - tmp2 + sdot(t)/(TWO*vtrue(t))
+
+      ! return success
+      ierr = 0
+      return
+
+   end function
+
+
+The subtle bug in the code causing the segfault is on line 8. It should read
+``real(c_double), value :: t`` instead of ``real(c_double) :: t`` (notice the
+``value`` attribute). Fundamental types that are passed by value in C need
+the ``value`` attribute.

examples/arkode/C_serial/ark_kpr_mri.c

@@ -772,7 +772,7 @@ static int fn(realtype t, N_Vector y, N_Vector ydot, void *user_data)
 
 static int f0(realtype t, N_Vector y, N_Vector ydot, void *user_data)
 {
-  N_VConst(ZERO,ydot);
+  N_VConst(ZERO, ydot);
   return(0);
 }
 
@@ -789,7 +789,7 @@ static int Js(realtype t, N_Vector y, N_Vector fy, SUNMatrix J, void *user_data,
      [G/2 + (G*(1+r(t))-rdot(t))/(2*u^2)   e/2+e*(2+s(t))/(2*v^2)]
      [                 0                             0           ] */
   SM_ELEMENT_D(J,0,0) = G/TWO + (G*(ONE+r(t,rpar))-rdot(t,rpar))/(2*u*u);
-  SM_ELEMENT_D(J,0,1) = e/TWO+e*(TWO+s(t,rpar))/(TWO*v*v);
+  SM_ELEMENT_D(J,0,1) = e/TWO + e*(TWO+s(t,rpar))/(TWO*v*v);
   SM_ELEMENT_D(J,1,0) = ZERO;
   SM_ELEMENT_D(J,1,1) = ZERO;
 
@@ -807,10 +807,10 @@ static int Jsi(realtype t, N_Vector y, N_Vector fy, SUNMatrix J, void *user_data
   const realtype v = NV_Ith_S(y,1);
 
   /* fill in the Jacobian:
-     [G/2 + (G*(1+r(t)))/(2*u^2)   e/2+e*(2+s(t))/(2*v^2)]
-     [                 0                             0           ] */
+     [G/2 + (G*(1+r(t)))/(2*u^2)   e/2 + e*(2+s(t))/(2*v^2)]
+     [                 0                       0           ] */
   SM_ELEMENT_D(J,0,0) = G/TWO + (G*(ONE+r(t,rpar)))/(2*u*u);
-  SM_ELEMENT_D(J,0,1) = e/TWO+e*(TWO+s(t,rpar))/(TWO*v*v);
+  SM_ELEMENT_D(J,0,1) = e/TWO + e*(TWO+s(t,rpar))/(TWO*v*v);
   SM_ELEMENT_D(J,1,0) = ZERO;
   SM_ELEMENT_D(J,1,1) = ZERO;
 
@@ -828,11 +828,11 @@ static int Jn(realtype t, N_Vector y, N_Vector fy, SUNMatrix J, void *user_data,
   const realtype v = NV_Ith_S(y,1);
 
   /* fill in the Jacobian:
-     [G/2 + (G*(1+r(t))-rdot(t))/(2*u^2)     e/2+e*(2+s(t))/(2*v^2)]
-     [e/2+e*(1+r(t))/(2*u^2)                -1/2 - (2+s(t))/(2*v^2)] */
+     [G/2 + (G*(1+r(t))-rdot(t))/(2*u^2)     e/2 + e*(2+s(t))/(2*v^2)]
+     [e/2+e*(1+r(t))/(2*u^2)                -1/2 - (2+s(t))/(2*v^2)  ] */
   SM_ELEMENT_D(J,0,0) = G/TWO + (G*(ONE+r(t,rpar))-rdot(t,rpar))/(2*u*u);
-  SM_ELEMENT_D(J,0,1) = e/TWO+e*(TWO+s(t,rpar))/(TWO*v*v);
-  SM_ELEMENT_D(J,1,0) = e/TWO+e*(ONE+r(t,rpar))/(TWO*u*u);
+  SM_ELEMENT_D(J,0,1) = e/TWO + e*(TWO+s(t,rpar))/(TWO*v*v);
+  SM_ELEMENT_D(J,1,0) = e/TWO + e*(ONE+r(t,rpar))/(TWO*u*u);
   SM_ELEMENT_D(J,1,1) = -ONE/TWO - (TWO+s(t,rpar))/(TWO*v*v);
 
   /* Return with success */

examples/arkode/F2003_serial/CMakeLists.txt

@@ -19,7 +19,18 @@
 
 # Examples using SUNDIALS linear solvers
 set(FARKODE_examples
-  "ark_analytic_f2003\;develop"
+  "ark_analytic_f2003\;\;develop"
+  "ark_kpr_mri_f2003\;\;develop"
+  "ark_kpr_mri_f2003\;0 0.002\;develop"
+  "ark_kpr_mri_f2003\;1 0.002\;develop"
+  "ark_kpr_mri_f2003\;2 0.005\;develop"
+  "ark_kpr_mri_f2003\;3 0.01\;develop"
+  "ark_kpr_mri_f2003\;4 0.002\;develop"
+  "ark_kpr_mri_f2003\;5 0.002\;develop"
+  "ark_kpr_mri_f2003\;6 0.005\;develop"
+  "ark_kpr_mri_f2003\;7 0.001\;develop"
+  "ark_kpr_mri_f2003\;8 0.001\;develop"
+  "ark_kpr_mri_f2003\;9 0.001\;develop"
   )
 
 set(FARKODE_tests
@@ -38,31 +49,42 @@ foreach(example_tuple ${FARKODE_examples})
 
   # parse the example tuple
   list(GET example_tuple 0 example)
-  list(GET example_tuple 1 example_type)
+  list(GET example_tuple 1 example_args)
+  list(GET example_tuple 2 example_type)
 
-  # Install fortran modules to a unique directory to avoid naming collisions
-  set(CMAKE_Fortran_MODULE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/CMakeFiles/${example}.dir)
+  if (NOT TARGET ${example})
+    # example source files
+    add_executable(${example} ${example}.f90)
 
-  # example source files
-  add_executable(${example} ${example}.f90)
+    # folder for IDEs
+    set_target_properties(${example} PROPERTIES FOLDER "Examples")
 
-  set_target_properties(${example} PROPERTIES FOLDER "Examples")
+    # libraries to link against
+    target_link_libraries(${example} ${SUNDIALS_LIBS})
+
+    # Install fortran modules to a unique directory to avoid naming collisions
+    set(CMAKE_Fortran_MODULE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/CMakeFiles/${example}.dir)
+  endif()
+
+  # check if example args are provided and set the test name
+  if("${example_args}" STREQUAL "")
+    set(test_name ${example})
+  else()
+    string(REGEX REPLACE " " "_" test_name ${example}_${example_args})
+  endif()
 
   # add example to regression tests
-  sundials_add_test(${example} ${example}
+  sundials_add_test(${test_name} ${example}
+    TEST_ARGS ${example_args}
     ANSWER_DIR ${CMAKE_CURRENT_SOURCE_DIR}
-    ANSWER_FILE ${example}.out
+    ANSWER_FILE ${test_name}.out
     EXAMPLE_TYPE ${example_type})
 
-  # libraries to link against
-  target_link_libraries(${example} ${SUNDIALS_LIBS})
-
-   # install example source and out files
+  # install example source and out files
   if(EXAMPLES_INSTALL)
-    install(FILES ${example}.f90 ${example}.out
-      DESTINATION ${EXAMPLES_INSTALL_PATH}/arkode/F2003_serial)
+    install(FILES ${example}.f90 ${test_name}.out
+    DESTINATION ${EXAMPLES_INSTALL_PATH}/arkode/F2003_serial)
   endif()
-
 endforeach(example_tuple ${FARKODE_examples})
 
 # Add the build and install targets for regression test