Feature: Fortran interface for 32-bit sunindextype (#447)

Update the the SWIG generation and CMake build system to support
Fortran interfaces for 32-bit or 64-bit sunindextype.

---------

Co-authored-by: David Gardner <[email protected]>
Co-authored-by: Daniel R. Reynolds <[email protected]>

.github/workflows/check-clang-format.yml

@@ -1,7 +1,6 @@
 name: Checks - clang-format
 
 on:
-  push:
   pull_request:
   workflow_dispatch:
 
@@ -36,12 +35,12 @@ jobs:
 
       - name: Run git diff if we failed
         if: failure()
-        run:  /usr/bin/git diff > diff
+        run:  /usr/bin/git diff > clang_format.patch
 
-      - name: Archive diff if we failed
+      - name: Archive diff as a patch if we failed
         uses: actions/upload-artifact@v3
         if: failure()
         with:
-          name: diff
+          name: clang_format.patch
           path: |
-            ${{ github.workspace }}/diff
+            ${{ github.workspace }}/clang_format.patch

.github/workflows/check-swig.yml

@@ -0,0 +1,49 @@
+name: Checks - swig
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  swig:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Install swig
+        run: |
+          git clone https://github.com/sundials-codes/swig
+          cd swig
+          ./autogen.sh
+          ./configure --prefix=/usr/
+          make 
+          sudo make install
+          swig -version
+
+      - name: Check out repository code
+        uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - name: Add safe directory
+        run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
+
+      - name: Run swig on code
+        run: |
+          cd swig
+          make all32
+          make all64
+
+      - name: Run git diff to see if anything changed
+        run: /usr/bin/git diff --name-only --exit-code
+
+      - name: Run git diff if we failed
+        if: failure()
+        run:  /usr/bin/git diff > swig.patch
+
+      - name: Archive diff as a patch if we failed
+        uses: actions/upload-artifact@v3
+        if: failure()
+        with:
+          name: swig.patch
+          path: |
+            ${{ github.workspace }}/swig.patch

CHANGELOG.md

@@ -59,6 +59,8 @@ integrator with an MRI method.
 
 Added "Resize" capability to ARKODE's SPRKStep time-stepping module.
 
+Enabled the Fortran interfaces to build with 32-bit `sunindextype`.
+
 ### Bug Fixes
 
 Updated the CMake variable `HIP_PLATFORM` default to `amd` as the previous

cmake/SundialsBuildOptionsPre.cmake

@@ -185,11 +185,6 @@ if(BUILD_FORTRAN_MODULE_INTERFACE)
     print_error("F2003 interface is not compatible with ${SUNDIALS_PRECISION} precision")
   endif()
 
-  # F2003 interface only supports 64-bit indices
-  if(NOT (SUNDIALS_INDEX_SIZE MATCHES "64"))
-    print_error("F2003 interface is not compatible with ${SUNDIALS_INDEX_SIZE}-bit indicies")
-  endif()
-
   # Allow a user to set where the Fortran modules will be installed
   set(DOCSTR "Directory where Fortran module files are installed")
   sundials_option(Fortran_INSTALL_MODDIR STRING "${DOCSTR}" "fortran")

cmake/SundialsExampleOptions.cmake

@@ -38,23 +38,14 @@ endif()
 # Fortran 2003 interface is enabled.
 set(DOCSTR "Build SUNDIALS Fortran 2003 examples")
 if(BUILD_FORTRAN_MODULE_INTERFACE)
-
-  sundials_option(EXAMPLES_ENABLE_F2003 BOOL "${DOCSTR}" ON)
+  set(EXAMPLES_ENABLE_F2003 ON CACHE BOOL "${DOCSTR}")
 
   # Fortran 2003 examples only support double precision
   if(EXAMPLES_ENABLE_F2003 AND (NOT (SUNDIALS_PRECISION MATCHES "DOUBLE")))
     print_warning("F2003 examples are not compatible with ${SUNDIALS_PRECISION} precision. "
                   "Setting EXAMPLES_ENABLE_F2003 to OFF.")
     force_variable(EXAMPLES_ENABLE_F2003 BOOL "${DOCSTR}" OFF)
   endif()
-
-  # Fortran 2003 examples only support 64-bit indices
-  if(EXAMPLES_ENABLE_F2003 AND (NOT (SUNDIALS_INDEX_SIZE MATCHES "64")))
-    print_warning("F2003 examples are not compatible with ${SUNDIALS_INDEX_SIZE}-bit indices. "
-                  "Setting EXAMPLES_ENABLE_F2003 to OFF.")
-    force_variable(EXAMPLES_ENABLE_F2003 BOOL "${DOCSTR}" OFF)
-  endif()
-
 else()
 
   # set back to OFF (in case it was ON)

cmake/macros/SundialsAddLibrary.cmake

@@ -458,6 +458,7 @@ macro(sundials_add_f2003_library target)
       ${sundials_add_f2003_library_INCLUDE_DIRECTORIES}
       ${_includes}
     COMPILE_DEFINITIONS ${sundials_add_f2003_library_COMPILE_DEFINITIONS}
+                        PUBLIC "SUNDIALS_INT${SUNDIALS_INDEX_SIZE}_T"
     COMPILE_OPTIONS ${sundials_add_f2003_library_COMPILE_OPTIONS}
     PROPERTIES ${sundials_add_f2003_library_PROPERTIES} ${_properties}
     OUTPUT_NAME ${sundials_add_f2003_library_OUTPUT_NAME}

cmake/tpl/FindKLU.cmake

@@ -33,7 +33,11 @@
 if (NOT (KLU_INCLUDE_DIR OR KLU_LIBRARY_DIR OR KLU_LIBRARY))
   # Prefer the import target from upstream SuiteSparse if it is available
   # and the user didn't point to a specific (different) version.
+  find_package(AMD CONFIG)
+  find_package(BTF CONFIG)
+  find_package(COLAMD CONFIG)
   find_package(KLU CONFIG)
+  find_package(SuiteSparse_config CONFIG)
 
   if(TARGET SuiteSparse::KLU)
     if(NOT TARGET SUNDIALS::KLU)

doc/shared/RecentChanges.rst

@@ -57,6 +57,8 @@ an explicit fast time scale integrator with an MRI method.
 
 Added "Resize" capability to ARKODE's SPRKStep time-stepping module.
 
+Enabled the Fortran interfaces to build with 32-bit ``sunindextype``.
+
 **Bug Fixes**
 
 Updated the CMake variable ``HIP_PLATFORM`` default to ``amd`` as the previous

doc/shared/sundials/Fortran.rst

@@ -162,8 +162,13 @@ equivalencies with the parameter direction in mind.
 .. warning::
 
    Currently, the Fortran 2003 interfaces are only compatible with SUNDIALS
-   builds where the ``sunrealtype`` is double-precision the ``sunindextype`` size
-   is 64-bits.
+   builds where the ``sunrealtype`` is double-precision.
+
+.. versionchanged:: x.y.z
+
+   The Fortran interfaces can now be built with 32-bit ``sunindextype`` in
+   addition to 64-bit ``sunindextype``.
+
 
 .. _SUNDIALS.Fortran.DataTypes.Table:
 .. table:: C/Fortran-2003 Equivalent Types

doc/superbuild/source/developers/getting_started/Checklist.rst

@@ -27,10 +27,11 @@ system, etc. developers should adhere to the following checklist.
    third party libraries to ensure that these files are only included when
    SUNDIALS is configured to use that library.
 
-#. Configure SUNDIALS using the C flags ``-Wall -ansi -pedantic``, to aid in
-   catching compatibility issues on other platforms (Windows). When building,
-   modify your file to remove any error/warning messages output during
-   compilation of your code.
+#. It can be helpful to configure SUNDIALS using the C flags ``-Wall -Werror``.
+   When building, modify your file to remove any error/warning messages output
+   during compilation of your code. This can be done automatically with the
+   advanced CMake options ``ENABLE_ALL_WARNINGS`` and
+   ``ENABLE_WARNINGS_AS_ERRORS``.
 
 #. Configure your build with a minimal set of configuration options enabled
    (serial). Run ``make``, ``make test``, ``make install``, and
@@ -52,8 +53,7 @@ system, etc. developers should adhere to the following checklist.
 
 #. When adding new solvers or new solver options:
 
-   * Update the documentation to include descriptions of your work. Ensure that
-     the documentation also compiles (``make ug`` in the relevant directory).
+   * Update the documentation to include descriptions of your work.
    * Add a new example problem (or multiple problems) to the ``examples/``
      directory to demonstrate how to use your solver/option, and to include in
      SUNDIALS' automated nightly tests.
@@ -68,20 +68,20 @@ system, etc. developers should adhere to the following checklist.
      directory and ensure that ``make`` succeeds, since the CMake-generated
      Makefile system differs from how the examples are built within SUNDIALS.
    * Ensure that the reference output is included e.g., if a file ``foo.c`` is
-     added, also add ``foo.out``.
+     added, also add ``foo.out``. 
    * Update the example problem documentation for to include a description of
      the new problem.
 
 #. When adding any new files, update the corresponding package script in the
    ``scripts/`` directory to include your file(s) within the distribution.
 
-#. Use the debugging macros defined in ``src/sundials/sundials_debug.h`` where
-   relevant and internal to SUNDIALS. Use the ``SUNDIALS_DEBUG`` macro to
-   ``#ifdef`` out calls the sections of code which are for debugging purposes
-   only. Additionally, the ``SUNDIALS_DEBUG_PRINTVEC`` macro should be used to
-   ``#ifdef`` out calls to the generic vector print functions ``N_VPrint`` and
-   ``N_VPrintFile`` used for debugging purposes.
-
 #. If answer files changed, and it is expected/desired, then update the `.out` files
    that are embedded in the `examples/` directory AND the
    `"answers" repository <https://github.com/sundials-codes/answers>`_. 
+
+#. If you changed any header files, re-run SWIG to generate updated fortran interfaces.
+   This is done by navigating to the `swig/` directory and running `make all32 all64`.
+   If you do not have `swig` installed on your system, you can obtain a git patch file
+   from the SWIG GitHub action that we run on all pull requests. The patch can be found
+   under the job artifacts (if there were in fact changes that required updates
+   to the Fortran).

doc/superbuild/source/developers/releases/Checklist.rst

@@ -73,6 +73,7 @@ web pages.
    that they are deprecated).
 
 #. Regenerate the Fortran 2003 interfaces. It is possible nothing will be updated.
+   This is done by running ``make all32 all64`` in the ``swig/`` directory.
 
 #. Update the "Changes in ..." sections in all user guides. The changes should be
    sorted so that major new features are above bug fixes.

doc/superbuild/source/developers/style_guide/SourceCode.rst

@@ -176,6 +176,9 @@ C++ private class members should use snake case with a trailing underscore
 Coding Conventions and Rules
 ============================
 
+These rules should be followed for all new code. Unfortunately, old code might
+not adhere to all of these rules.
+
 #. Do not use language features that are not compatible with C99, C++14,
    and MSVC v1900+ (Visual Studio 2015). Examples of such features include
    variable-length arrays. Exceptions are allowed when interfacing with a
@@ -338,6 +341,17 @@ Coding Conventions and Rules
    x;`` to ``return(x);``. Note, however, lots of older SUNDIALS source code
    uses ``return(x);``.
 
+#. Always use ``sunindextype`` for variables that are related to problem dimensions.
+   E.g., use it for the length of a vector, or dimensions of a matrix.
+   The only exception is when interfacing with a third party library requires a different
+   variable type.
+
+#. Conversely, never use ``sunindextype`` for variables that are not specifically related to
+   the dimensions of a vector, matrix, etc.. E.g., if you have a variable that
+   represents the number of integer "words" allocated in a workspace do not use
+   ``sunindextype`` for it. Instead use the appropriate integer type (e.g., ``uint64_t``) directly.
+   Do not use ``sunindextype`` for counters either.
+
 #. ``SUNLogger`` statements must be in the format:
 
    .. code-block:: c
@@ -371,6 +385,16 @@ for the tools respectively. To apply clang-format you can run:
 
    ./scripts/format.sh <path to directories to format>
 
+
+.. warning::
+
+   The output of ``clang-format`` is sensitive to the ``clang-format`` version. We recommend
+   that you use version ``17.0.4``, which can be installed from source or with Spack. Alternatively,
+   when you open a pull request on GitHub, an action will run ``clang-format`` on the code. If any
+   formatting is required, the action will fail and produce a git patch artifact that you can download
+   (from the job artifacts section) and apply with `git apply`.
+
+
 If clang-format breaks lines in a way that is unreadable, use ``//`` to break the line. For example,
 sometimes (mostly in C++ code) you may have code like this:
 
@@ -426,3 +450,4 @@ There are other scenarios (e.g., a function call with a lot of parameters) where
 ..   };
 
 .. See the clang-tidy documentation for more details.
+

examples/arkode/F2003_custom/CMakeLists.txt

@@ -17,18 +17,22 @@
 # Example lists are tuples "name\;type" where the type is
 # 'develop' for examples excluded from 'make test' in releases
 
-# Examples using SUNDIALS linear solvers
-set(FARKODE_examples
-  "ark_brusselator1D_f2003\;develop"
-  "ark_analytic_complex_f2003\;develop"
-  )
+if(SUNDIALS_INDEX_SIZE MATCHES "64")
 
-set(FARKODE_tests
-  "test_fnvector_complex_mod\;develop"
-  "test_fnvector_fortran_mod\;develop"
-  "test_fsunmatrix_fortran_mod\;develop"
-  "test_fsunlinsol_fortran_mod\;develop"
-  )
+  # Examples using SUNDIALS linear solvers
+  set(FARKODE_examples
+    "ark_brusselator1D_f2003\;develop"
+    "ark_analytic_complex_f2003\;develop"
+    )
+
+  set(FARKODE_tests
+    "test_fnvector_complex_mod\;develop"
+    "test_fnvector_fortran_mod\;develop"
+    "test_fsunmatrix_fortran_mod\;develop"
+    "test_fsunlinsol_fortran_mod\;develop"
+    )
+
+endif()
 
 # note the order matters when auto-generating the installed Makefile
 set(FARKODEsources

examples/arkode/F2003_parallel/CMakeLists.txt

@@ -18,12 +18,17 @@
 # Example lists are tuples "name\;nodes\;tasks\;type" where the
 # type is develop for examples excluded from 'make test' in releases
 set(FARKODE_examples
-    "ark_brusselator1D_task_local_nls_f2003\;--monitor\;1\;4\;develop\;2"
-    "ark_brusselator1D_task_local_nls_f2003\;--monitor --global-nls\;1\;4\;develop\;2"
-    "ark_brusselator1D_task_local_nls_f2003\;--monitor --explicit --tf 3\;1\;4\;develop\;2"
-    "ark_diag_kry_bbd_f2003\;\;1\;4\;develop\;2"
-    "ark_diag_non_f2003\;\;1\;4\;develop\;2"
-    "ark_heat2D_f2003\;\;1\;4\;develop\;2")
+  "ark_brusselator1D_task_local_nls_f2003\;--monitor\;1\;4\;develop\;2"
+  "ark_brusselator1D_task_local_nls_f2003\;--monitor --global-nls\;1\;4\;develop\;2"
+  "ark_brusselator1D_task_local_nls_f2003\;--monitor --explicit --tf 3\;1\;4\;develop\;2"
+)
+
+if(SUNDIALS_INDEX_SIZE MATCHES "64")
+  list(APPEND FARKODE_examples
+      "ark_diag_kry_bbd_f2003\;\;1\;4\;develop\;2"
+      "ark_diag_non_f2003\;\;1\;4\;develop\;2"
+      "ark_heat2D_f2003\;\;1\;4\;develop\;2")
+endif()
 
 # Set-up linker flags and link libraries
 set(SUNDIALS_LIBS sundials_arkode