Enable Fortran interface for 32-bit sunindextype

.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

@@ -94,6 +94,8 @@ Fixed a bug that caused error messages to be cut off in some cases. Fixes
 Fixed a memory leak when an error handler was added to a `SUNContext`. Fixes
 [GitHub Issue #466](https://github.com/LLNL/sundials/issues/466).
 
+Enabled the Fortran interfaces to build with 32-bit `sunindextype`.
+
 Fixed a bug where `MRIStepEvolve` would not handle a recoverable error produced
 from evolving the inner stepper.
 

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

@@ -93,6 +93,8 @@ Fixed a memory leak when an error handler was added to a
 :c:type:`SUNContext`. Fixes `GitHub Issue #466
 <https://github.com/LLNL/sundials/issues/466>`_.
 
+Enabled the Fortran interfaces to build with 32-bit ``sunindextype``.
+
 Fixed a bug where :c:func:`MRIStepEvolve` would not handle a recoverable error
 produced from evolving the inner stepper.
 

doc/shared/nvectors/NVector_Description.rst

@@ -185,7 +185,7 @@ The functions :c:func:`N_VCloneVectorArray` and
 variables of type :c:type:`N_Vector`, each of the same type as an existing
 ``N_Vector`` input:
 
-.. c:function:: N_Vector *N_VCloneVectorArray(int count, N_Vector w)
+.. c:function:: N_Vector *N_VCloneVectorArray(sunindextype count, N_Vector w)
 
    Clones an array of ``count``  ``N_Vector`` objects, allocating their data arrays (similar to :c:func:`N_VClone`).
 
@@ -198,7 +198,7 @@ variables of type :c:type:`N_Vector`, each of the same type as an existing
       * ``NULL`` pointer on failure.
 
 
-.. c:function:: N_Vector *N_VCloneVectorArrayEmpty(int count, N_Vector w)
+.. c:function:: N_Vector *N_VCloneVectorArrayEmpty(sunindextype count, N_Vector w)
 
    Clones an array of ``count``  ``N_Vector`` objects, leaving their data arrays unallocated (similar to :c:func:`N_VCloneEmpty`).
 
@@ -215,7 +215,7 @@ An array of variables of type :c:type:`N_Vector` can be destroyed
 by calling :c:func:`N_VDestroyVectorArray`:
 
 
-.. c:function:: void N_VDestroyVectorArray(N_Vector *vs, int count)
+.. c:function:: void N_VDestroyVectorArray(N_Vector *vs, sunindextype count)
 
    Destroys an array of ``count``  ``N_Vector`` objects.
 
@@ -243,7 +243,7 @@ that are wrapped as ``FN_NewVectorArray``, ``FN_VGetVecAtIndexVectorArray``, and
 set a vector within this array:
 
 
-.. c:function:: N_Vector *N_VNewVectorArray(int count, SUNContext sunctx)
+.. c:function:: N_Vector *N_VNewVectorArray(sunindextype count, SUNContext sunctx)
 
    Creates an array of ``count``  ``N_Vector`` objects, the pointers to each
    are initialized as ``NULL``.
@@ -261,7 +261,7 @@ set a vector within this array:
       The function signature was updated to add the ``SUNContext`` argument.
 
 
-.. c:function:: N_Vector *N_VGetVecAtIndexVectorArray(N_Vector* vs, int index)
+.. c:function:: N_Vector *N_VGetVecAtIndexVectorArray(N_Vector* vs, sunindextype index)
 
    Accesses the ``N_Vector`` at the location ``index`` within the ``N_Vector`` array ``vs``.
 
@@ -279,7 +279,7 @@ set a vector within this array:
       internally store its allocated length.
 
 
-.. c:function:: void N_VSetVecAtIndexVectorArray(N_Vector* vs, int index, N_Vector w)
+.. c:function:: void N_VSetVecAtIndexVectorArray(N_Vector* vs, sunindextype index, N_Vector w)
 
    Sets a pointer to ``w`` at the location ``index`` within the vector array ``vs``.
 

doc/shared/sundials/Fortran.rst

@@ -175,8 +175,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, dimensions of a matrix, or for the number of vectors.
+   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.
+
 
 .. _Style.Formatting:
 
@@ -353,6 +367,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:
 
@@ -408,3 +432,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

@@ -17,13 +17,16 @@
 
 # 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")
+
+if(SUNDIALS_INDEX_SIZE MATCHES "64")
+  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")
+endif()
 
 # Set-up linker flags and link libraries
 set(SUNDIALS_LIBS sundials_arkode