Fix fortran interface to MPI_Comm, address calls to MPI functions bef…

…ore MPI_Init, and fix docs

CHANGELOG.md

@@ -47,11 +47,28 @@ method `ARKODE_VERNER_16_8_9`.
 Changed the `SUNProfiler` so that it does not rely on `MPI_WTime` in any case.
 This fixes https://github.com/LLNL/sundials/issues/312. 
 
-Updated the `N_VGetCommunicator`, `SUNLogger_Create`, and `SUNProfiler_Create`
-functions to use a `SUNComm` rather than `void*`. `SUNComm` simply is a
-typedef to an `int` for builds without MPI and a `MPI_Comm` for builds with MPI.
-This allows for `MPI_Comm` to be passed and returned by value which solves
-issues like the one described in https://github.com/LLNL/sundials/issues/275.   
+**Breaking change** 
+We have replaced the use of a type-erased (i.e., `void*`) pointer to a
+communicator in place of `MPI_Comm` throughout the SUNDIALS API with a
+:c:type:`SUNComm`, which is just a typedef to a `int` in builds without MPI
+and a typedef to a `MPI_Comm` in builds with MPI. Here is what this means:
+
+- All users will need to update their codes because the call to 
+  `SUNContext_Create` now takes a :c:type:`SUNComm` instead
+  of type-erased pointer to a communicator. For non-MPI codes,
+  pass :c:type:`SUN_COMM_NULL` to the `comm` argument instead of
+  `NULL`. For MPI codes, pass the `MPI_Comm` directly. 
+  The required change should be doable with a find-and-replace. 
+
+- The same change must be made for calls to 
+  `SUNLogger_Create` or `SUNProfiler_Create`. 
+
+- Some users will need to update their calls to `N_VGetCommunicator`, and 
+  update any custom `N_Vector` implementations tht provide 
+  `N_VGetCommunicator`, since it now returns a `SUNComm`. 
+
+The change away from type-erased pointers for `SUNComm` fixes problems like the 
+one described in `GitHub Issue #275 <https://github.com/LLNL/sundials/issues/275>`.
 
 
 ## Changes to SUNDIALS in release 6.6.1

benchmarks/nvector/cuda/test_nvector_performance_cuda.cu

@@ -132,7 +132,7 @@ int main(int argc, char *argv[])
   printf("  number of tests       %d  \n", ntests);
   printf("  timing on/off         %d  \n", print_timing);
 
-  flag = SUNContext_Create(NULL, &ctx);
+  flag = SUNContext_Create(SUN_COMM_NULL, &ctx);
   if (flag) return flag;
 
   /* Create vectors */

benchmarks/nvector/hip/test_nvector_performance_hip.cpp

@@ -132,7 +132,7 @@ int main(int argc, char *argv[])
   printf("  number of tests       %d  \n", ntests);
   printf("  timing on/off         %d  \n", print_timing);
 
-  flag = SUNContext_Create(NULL, &ctx);
+  flag = SUNContext_Create(SUN_COMM_NULL, &ctx);
   if (flag) return flag;
 
   /* Create vectors */

benchmarks/nvector/openmp/test_nvector_performance_openmp.c

@@ -108,7 +108,7 @@ int main(int argc, char *argv[])
   printf("  timing on/off         %d  \n", print_timing);
   printf("  number of threads     %d  \n", nthreads);
 
-  flag = SUNContext_Create(NULL, &ctx);
+  flag = SUNContext_Create(SUN_COMM_NULL, &ctx);
   if (flag) return flag;
 
   /* Create vectors */

benchmarks/nvector/pthreads/test_nvector_performance_pthreads.c

@@ -106,7 +106,7 @@ int main(int argc, char *argv[])
   printf("  timing on/off         %d  \n", print_timing);
   printf("  number of threads     %d  \n", nthreads);
 
-  flag = SUNContext_Create(NULL, &ctx);
+  flag = SUNContext_Create(SUN_COMM_NULL, &ctx);
   if (flag) return flag;
 
   /* Create vectors */

benchmarks/nvector/serial/test_nvector_performance_serial.c

@@ -99,7 +99,7 @@ int main(int argc, char *argv[])
   printf("  number of tests       %d  \n", ntests);
   printf("  timing on/off         %d  \n", print_timing);
 
-  flag = SUNContext_Create(NULL, &ctx);
+  flag = SUNContext_Create(SUN_COMM_NULL, &ctx);
   if (flag) return flag;
 
   /* Create vectors */

doc/arkode/guide/source/Introduction.rst

@@ -167,16 +167,28 @@ This fixes `GitHub Issue #312 <https://github.com/LLNL/sundials/issues/312>`_.
 
 Added Fortran support for the LAPACK  dense ``SUNLinearSolver`` implementation.
 
-Updated the ``N_VGetCommunicator``, :c:func:`SUNLogger_Create`, and
-:c:func:`SUNProfiler_Create` functions to use a :c:type:`SUNComm` rather than
-``void*``. :c:type:`SUNComm` simply is a ``typedef`` to an ``int`` for builds
-without MPI and a ``MPI_Comm`` for builds with MPI. This allows for ``MPI_Comm``
-to be passed and returned by value which solves issues like the one described in
-`GitHub Issue #275 <https://github.com/LLNL/sundials/issues/275>`. **This is a
-breaking change** that will require users to update their calls to
-``N_VGetCommunicator`` and update any custom ``N_Vector`` implementations that
-provide ``N_VGetCommunicator``.
-
+**Breaking change** 
+We have replaced the use of a type-erased (i.e., ``void*``) pointer to a
+communicator in place of ``MPI_Comm`` throughout the SUNDIALS API with a
+:c:type:`SUNComm`, which is just a typedef to a ``int`` in builds without MPI
+and a typedef to a ``MPI_Comm`` in builds with MPI. Here is what this means:
+
+- All users will need to update their codes because the call to 
+  :c:func:`SUNContext_Create` now takes a :c:type:`SUNComm` instead
+  of type-erased pointer to a communicator. For non-MPI codes,
+  pass :c:type:`SUN_COMM_NULL` to the ``comm`` argument instead of
+  ``NULL``. For MPI codes, pass the ``MPI_Comm`` directly. 
+  The required change should be doable with a find-and-replace. 
+
+- The same change must be made for calls to 
+  :c:func:`SUNLogger_Create` or :c:func:`SUNProfiler_Create`. 
+
+- Some users will need to update their calls to ``N_VGetCommunicator``, and 
+  update any custom ``N_Vector`` implementations tht provide 
+  ``N_VGetCommunicator``, since it now returns a ``SUNComm``. 
+
+The change away from type-erased pointers for :c:type:`SUNComm` fixes problems like the 
+one described in `GitHub Issue #275 <https://github.com/LLNL/sundials/issues/275>`.
 
 
 Changes in v5.6.1

doc/cvode/guide/source/Introduction.rst

@@ -134,15 +134,28 @@ This fixes `GitHub Issue #312 <https://github.com/LLNL/sundials/issues/312>`_.
 
 Added Fortran support for the LAPACK  dense ``SUNLinearSolver`` implementation.
 
-Updated the ``N_VGetCommunicator``, :c:func:`SUNLogger_Create`, and
-:c:func:`SUNProfiler_Create` functions to use a :c:type:`SUNComm` rather than
-``void*``. :c:type:`SUNComm` simply is a ``typedef`` to an ``int`` for builds
-without MPI and a ``MPI_Comm`` for builds with MPI. This allows for ``MPI_Comm``
-to be passed and returned by value which solves issues like the one described in
-`GitHub Issue #275 <https://github.com/LLNL/sundials/issues/275>`. **This is a
-breaking change** that will require users to update their calls to
-``N_VGetCommunicator`` and update any custom ``N_Vector`` implementations that
-provide ``N_VGetCommunicator``. 
+**Breaking change** 
+We have replaced the use of a type-erased (i.e., ``void*``) pointer to a
+communicator in place of ``MPI_Comm`` throughout the SUNDIALS API with a
+:c:type:`SUNComm`, which is just a typedef to a ``int`` in builds without MPI
+and a typedef to a ``MPI_Comm`` in builds with MPI. Here is what this means:
+
+- All users will need to update their codes because the call to 
+  :c:func:`SUNContext_Create` now takes a :c:type:`SUNComm` instead
+  of type-erased pointer to a communicator. For non-MPI codes,
+  pass :c:type:`SUN_COMM_NULL` to the ``comm`` argument instead of
+  ``NULL``. For MPI codes, pass the ``MPI_Comm`` directly. 
+  The required change should be doable with a find-and-replace. 
+
+- The same change must be made for calls to 
+  :c:func:`SUNLogger_Create` or :c:func:`SUNProfiler_Create`. 
+
+- Some users will need to update their calls to ``N_VGetCommunicator``, and 
+  update any custom ``N_Vector`` implementations tht provide 
+  ``N_VGetCommunicator``, since it now returns a ``SUNComm``. 
+
+The change away from type-erased pointers for :c:type:`SUNComm` fixes problems like the 
+one described in `GitHub Issue #275 <https://github.com/LLNL/sundials/issues/275>`.
 
 Changes in v6.6.1
 -----------------

doc/cvodes/guide/source/Introduction.rst

@@ -137,15 +137,28 @@ This fixes `GitHub Issue #312 <https://github.com/LLNL/sundials/issues/312>`_.
 
 Added Fortran support for the LAPACK  dense ``SUNLinearSolver`` implementation.
 
-Updated the ``N_VGetCommunicator``, :c:func:`SUNLogger_Create`, and
-:c:func:`SUNProfiler_Create` functions to use a :c:type:`SUNComm` rather than
-``void*``. :c:type:`SUNComm` simply is a ``typedef`` to an ``int`` for builds
-without MPI and a ``MPI_Comm`` for builds with MPI. This allows for ``MPI_Comm``
-to be passed and returned by value which solves issues like the one described in
-`GitHub Issue #275 <https://github.com/LLNL/sundials/issues/275>`. **This is a
-breaking change** that will require users to update their calls to
-``N_VGetCommunicator`` and update any custom ``N_Vector`` implementations that
-provide ``N_VGetCommunicator``. 
+**Breaking change** 
+We have replaced the use of a type-erased (i.e., ``void*``) pointer to a
+communicator in place of ``MPI_Comm`` throughout the SUNDIALS API with a
+:c:type:`SUNComm`, which is just a typedef to a ``int`` in builds without MPI
+and a typedef to a ``MPI_Comm`` in builds with MPI. Here is what this means:
+
+- All users will need to update their codes because the call to 
+  :c:func:`SUNContext_Create` now takes a :c:type:`SUNComm` instead
+  of type-erased pointer to a communicator. For non-MPI codes,
+  pass :c:type:`SUN_COMM_NULL` to the ``comm`` argument instead of
+  ``NULL``. For MPI codes, pass the ``MPI_Comm`` directly. 
+  The required change should be doable with a find-and-replace. 
+
+- The same change must be made for calls to 
+  :c:func:`SUNLogger_Create` or :c:func:`SUNProfiler_Create`. 
+
+- Some users will need to update their calls to ``N_VGetCommunicator``, and 
+  update any custom ``N_Vector`` implementations tht provide 
+  ``N_VGetCommunicator``, since it now returns a ``SUNComm``. 
+
+The change away from type-erased pointers for :c:type:`SUNComm` fixes problems like the 
+one described in `GitHub Issue #275 <https://github.com/LLNL/sundials/issues/275>`.
 
 Changes in v6.6.1
 -----------------

doc/ida/guide/source/Introduction.rst

@@ -95,15 +95,28 @@ This fixes `GitHub Issue #312 <https://github.com/LLNL/sundials/issues/312>`_.
 
 Added Fortran support for the LAPACK  dense ``SUNLinearSolver`` implementation.
 
-Updated the ``N_VGetCommunicator``, :c:func:`SUNLogger_Create`, and
-:c:func:`SUNProfiler_Create` functions to use a :c:type:`SUNComm` rather than
-``void*``. :c:type:`SUNComm` simply is a ``typedef`` to an ``int`` for builds
-without MPI and a ``MPI_Comm`` for builds with MPI. This allows for ``MPI_Comm``
-to be passed and returned by value which solves issues like the one described in
-`GitHub Issue #275 <https://github.com/LLNL/sundials/issues/275>`. **This is a
-breaking change** that will require users to update their calls to
-``N_VGetCommunicator`` and update any custom ``N_Vector`` implementations that
-provide ``N_VGetCommunicator``. 
+**Breaking change** 
+We have replaced the use of a type-erased (i.e., ``void*``) pointer to a
+communicator in place of ``MPI_Comm`` throughout the SUNDIALS API with a
+:c:type:`SUNComm`, which is just a typedef to a ``int`` in builds without MPI
+and a typedef to a ``MPI_Comm`` in builds with MPI. Here is what this means:
+
+- All users will need to update their codes because the call to 
+  :c:func:`SUNContext_Create` now takes a :c:type:`SUNComm` instead
+  of type-erased pointer to a communicator. For non-MPI codes,
+  pass :c:type:`SUN_COMM_NULL` to the ``comm`` argument instead of
+  ``NULL``. For MPI codes, pass the ``MPI_Comm`` directly. 
+  The required change should be doable with a find-and-replace. 
+
+- The same change must be made for calls to 
+  :c:func:`SUNLogger_Create` or :c:func:`SUNProfiler_Create`. 
+
+- Some users will need to update their calls to ``N_VGetCommunicator``, and 
+  update any custom ``N_Vector`` implementations tht provide 
+  ``N_VGetCommunicator``, since it now returns a ``SUNComm``. 
+
+The change away from type-erased pointers for :c:type:`SUNComm` fixes problems like the 
+one described in `GitHub Issue #275 <https://github.com/LLNL/sundials/issues/275>`.
 
 Changes in v6.6.1
 -----------------

doc/idas/guide/source/Introduction.rst

@@ -112,15 +112,28 @@ This fixes `GitHub Issue #312 <https://github.com/LLNL/sundials/issues/312>`_.
 
 Added Fortran support for the LAPACK  dense ``SUNLinearSolver`` implementation.
 
-Updated the ``N_VGetCommunicator``, :c:func:`SUNLogger_Create`, and
-:c:func:`SUNProfiler_Create` functions to use a :c:type:`SUNComm` rather than
-``void*``. :c:type:`SUNComm` simply is a ``typedef`` to an ``int`` for builds
-without MPI and a ``MPI_Comm`` for builds with MPI. This allows for ``MPI_Comm``
-to be passed and returned by value which solves issues like the one described in
-`GitHub Issue #275 <https://github.com/LLNL/sundials/issues/275>`. **This is a
-breaking change** that will require users to update their calls to
-``N_VGetCommunicator`` and update any custom ``N_Vector`` implementations that
-provide ``N_VGetCommunicator``. 
+**Breaking change** 
+We have replaced the use of a type-erased (i.e., ``void*``) pointer to a
+communicator in place of ``MPI_Comm`` throughout the SUNDIALS API with a
+:c:type:`SUNComm`, which is just a typedef to a ``int`` in builds without MPI
+and a typedef to a ``MPI_Comm`` in builds with MPI. Here is what this means:
+
+- All users will need to update their codes because the call to 
+  :c:func:`SUNContext_Create` now takes a :c:type:`SUNComm` instead
+  of type-erased pointer to a communicator. For non-MPI codes,
+  pass :c:type:`SUN_COMM_NULL` to the ``comm`` argument instead of
+  ``NULL``. For MPI codes, pass the ``MPI_Comm`` directly. 
+  The required change should be doable with a find-and-replace. 
+
+- The same change must be made for calls to 
+  :c:func:`SUNLogger_Create` or :c:func:`SUNProfiler_Create`. 
+
+- Some users will need to update their calls to ``N_VGetCommunicator``, and 
+  update any custom ``N_Vector`` implementations tht provide 
+  ``N_VGetCommunicator``, since it now returns a ``SUNComm``. 
+
+The change away from type-erased pointers for :c:type:`SUNComm` fixes problems like the 
+one described in `GitHub Issue #275 <https://github.com/LLNL/sundials/issues/275>`.
 
 Changes in v5.6.1
 -----------------

doc/kinsol/guide/source/Introduction.rst

@@ -104,15 +104,28 @@ CMake targets.
 
 Added Fortran support for the LAPACK  dense ``SUNLinearSolver`` implementation.
 
-Updated the ``N_VGetCommunicator``, :c:func:`SUNLogger_Create`, and
-:c:func:`SUNProfiler_Create` functions to use a :c:type:`SUNComm` rather than
-``void*``. :c:type:`SUNComm` simply is a ``typedef`` to an ``int`` for builds
-without MPI and a ``MPI_Comm`` for builds with MPI. This allows for ``MPI_Comm``
-to be passed and returned by value which solves issues like the one described in
-`GitHub Issue #275 <https://github.com/LLNL/sundials/issues/275>`. **This is a
-breaking change** that will require users to update their calls to
-``N_VGetCommunicator`` and update any custom ``N_Vector`` implementations that
-provide ``N_VGetCommunicator``. 
+**Breaking change** 
+We have replaced the use of a type-erased (i.e., ``void*``) pointer to a
+communicator in place of ``MPI_Comm`` throughout the SUNDIALS API with a
+:c:type:`SUNComm`, which is just a typedef to a ``int`` in builds without MPI
+and a typedef to a ``MPI_Comm`` in builds with MPI. Here is what this means:
+
+- All users will need to update their codes because the call to 
+  :c:func:`SUNContext_Create` now takes a :c:type:`SUNComm` instead
+  of type-erased pointer to a communicator. For non-MPI codes,
+  pass :c:type:`SUN_COMM_NULL` to the ``comm`` argument instead of
+  ``NULL``. For MPI codes, pass the ``MPI_Comm`` directly. 
+  The required change should be doable with a find-and-replace. 
+
+- The same change must be made for calls to 
+  :c:func:`SUNLogger_Create` or :c:func:`SUNProfiler_Create`. 
+
+- Some users will need to update their calls to ``N_VGetCommunicator``, and 
+  update any custom ``N_Vector`` implementations tht provide 
+  ``N_VGetCommunicator``, since it now returns a ``SUNComm``. 
+
+The change away from type-erased pointers for :c:type:`SUNComm` fixes problems like the 
+one described in `GitHub Issue #275 <https://github.com/LLNL/sundials/issues/275>`.
 
 Changes in v6.6.1
 -----------------

doc/shared/sundials/Profiling.rst

@@ -218,7 +218,7 @@ It is applicable to any of the SUNDIALS solver packages.
    SUNProfiler profobj;
 
    /* Create the SUNDIALS context */
-   retval = SUNContext_Create(NULL, &ctx);
+   retval = SUNContext_Create(SUN_COMM_NULL, &ctx);
 
    /* Get a reference to the profiler */
    retval = SUNContext_GetProfiler(ctx, &profobj);

doc/shared/sundials/SUNContext.rst

@@ -51,7 +51,7 @@ routines for different SUNDIALS classes/modules e.g.,
    void* package_mem;
    N_Vector x;
 
-   SUNContext_Create(NULL, &sunctx);
+   SUNContext_Create(SUN_COMM_NULL, &sunctx);
 
    package_mem = CVodeCreate(..., sunctx);
    package_mem = IDACreate(..., sunctx);

examples/arkode/CXX_parallel/ark_brusselator1D_task_local_nls.cpp

@@ -122,7 +122,7 @@ int main(int argc, char *argv[])
 
   /* Create SUNDIALS context */
   SUNContext ctx;
-  retval = SUNContext_Create(&comm, &ctx);
+  retval = SUNContext_Create(comm, &ctx);
   if (check_retval(&retval, "SUNContext_Create", 1)) MPI_Abort(comm, 1);
 
   /* Add scope to destroy objects before MPIFinalize */

examples/arkode/CXX_parhyp/ark_heat2D_hypre_ls.cpp

@@ -379,7 +379,7 @@ int main(int argc, char* argv[])
 
   // Create the SUNDIALS context object for this simulation
   SUNContext ctx;
-  flag = SUNContext_Create(&comm_w, &ctx);
+  flag = SUNContext_Create(comm_w, &ctx);
   if (check_flag(&flag, "SUNContext_Create", 1)) return 1;
 
   // Set output process flag

examples/arkode/CXX_parhyp/ark_heat2D_hypre_pfmg.cpp

@@ -337,7 +337,7 @@ int main(int argc, char* argv[])
 
   // Create the SUNDIALS context object for this simulation
   SUNContext ctx;
-  flag = SUNContext_Create(&comm_w, &ctx);
+  flag = SUNContext_Create(comm_w, &ctx);
   if (check_flag(&flag, "SUNContext_Create", 1)) return 1;
 
   // Set output process flag

examples/arkode/CXX_xbraid/ark_heat2D_hypre_pfmg_xbraid.cpp

@@ -373,7 +373,7 @@ int main(int argc, char* argv[])
 
   // Create the SUNDIALS context object for this simulation
   SUNContext ctx;
-  flag = SUNContext_Create(&comm_w, &ctx);
+  flag = SUNContext_Create(comm_w, &ctx);
   if (check_flag(&flag, "SUNContext_Create", 1)) return 1;
 
   // Set output process flag

examples/arkode/CXX_xbraid/ark_heat2D_p_xbraid.cpp

@@ -330,7 +330,7 @@ int main(int argc, char* argv[])
 
   // Create the SUNDIALS context object for this simulation
   SUNContext ctx;
-  flag = SUNContext_Create(&comm_w, &ctx);
+  flag = SUNContext_Create(comm_w, &ctx);
   if (check_flag(&flag, "SUNContext_Create", 1)) return 1;
 
   // Set output process flag

examples/arkode/C_parallel/ark_brusselator1D_task_local_nls.c

@@ -369,7 +369,6 @@ int EvolveProblemIMEX(N_Vector y, UserData udata, UserOptions uopt,
   long int nfe, nfi;          /* RHS stats                    */
   long int nni, ncnf;         /* nonlinear solver stats       */
   long int nli, npre, npsol;  /* linear solver stats          */
-  char     fname[MXSTR];
 
   /* Create the ARK timestepper module */
   arkode_mem = ARKStepCreate(Advection, Reaction, uopt->t0, y, ctx);
@@ -520,7 +519,6 @@ int EvolveProblemExplicit(N_Vector y, UserData udata, UserOptions uopt,
   int      iout;              /* output counter                */
   long int nst, nst_a, netf;  /* step stats                    */
   long int nfe;               /* RHS stats                     */
-  char     fname[MXSTR];
 
   /* Create the ERK timestepper module */
   arkode_mem = ERKStepCreate(AdvectionReaction, uopt->t0, y, ctx);

examples/arkode/C_parhyp/ark_diurnal_kry_ph.c

@@ -213,7 +213,7 @@ int main(int argc, char *argv[])
   }
 
   /* Create the SUNDIALS context object for this simulation */
-  flag = SUNContext_Create(&comm, &sunctx);
+  flag = SUNContext_Create(comm, &sunctx);
   if (check_flag(&flag, "SUNContext_Create", 1, my_pe)) return 1;
 
   /* Set local length */