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:/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:/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:/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:/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