Changes to SUNDIALS API and core C/C++ needed for Python interfaces

CHANGELOG.md

@@ -6,7 +6,7 @@
 
 ### New Features and Enhancements
 
-The functions ``CVodeGetUserDataB`` and ``IDAGetUserDataB`` were added to CVODES
+The functions `CVodeGetUserDataB` and `IDAGetUserDataB` were added to CVODES
 and IDAS, respectively.
 
 ### Bug Fixes
@@ -25,6 +25,11 @@ The `Convert` methods on the `sundials::kokkos:Vector`, `sundials::kokkos::Dense
 been deprecated and will be removed in the next major release. The method `get`, should
 be used instead.
 
+The `CSC_MAT` and `CSR_MAT` macros defined in `sunmatrix_sparse.h` will be removed in
+the next major release. Use `SUN_CSC_MAT` and `SUN_CSR_MAT` instead.
+
+The `N_Vector_S` typedef to `N_Vector*` is deprecated and will be removed in the next major release.
+
 ## Changes to SUNDIALS in release 7.5.0
 
 ### Major Features

doc/shared/RecentChanges.rst

@@ -23,3 +23,8 @@ The ``Convert`` methods on the ``sundials::kokkos:Vector``, ``sundials::kokkos::
 ``sundials::ginkgo::LinearSolver``, and ``sundials::ginkgo::BatchLinearSolver`` classes have
 been deprecated and will be removed in the next major release. The method ``get``, should
 be used instead.
+
+The ``CSC_MAT`` and ``CSR_MAT`` macros defined in ``sunmatrix_sparse.h`` will be removed in
+the next major release. Use ``SUN_CSC_MAT`` and ``SUN_CSR_MAT`` instead.
+
+The ``N_Vector_S`` typedef to ``N_Vector*`` is deprecated and will be removed in the next major release.

doc/shared/sunmatrix/SUNMatrix_Sparse.rst

@@ -65,7 +65,7 @@ complete description of the parts of this *content* field is given below:
   variables (of length ``NNZ``), containing the values of the
   nonzero entries in the matrix
 
-* ``sparsetype`` - type of the sparse matrix (``CSC_MAT`` or ``CSR_MAT``)
+* ``sparsetype`` - type of the sparse matrix (``SUN_CSC_MAT`` or ``SUN_CSR_MAT``)
 
 * ``indexvals`` - pointer to a contiguous block of ``int`` variables
   (of length ``NNZ``), containing the row indices (if CSC) or column
@@ -90,16 +90,16 @@ automatically when creating a sparse ``SUNMatrix``, based on the
 sparse matrix storage type.
 
 * ``rowvals`` - pointer to ``indexvals`` when ``sparsetype`` is
-  ``CSC_MAT``, otherwise set to ``NULL``.
+  ``SUN_CSC_MAT``, otherwise set to ``NULL``.
 
 * ``colptrs`` - pointer to ``indexptrs`` when ``sparsetype`` is
-  ``CSC_MAT``, otherwise set to ``NULL``.
+  ``SUN_CSC_MAT``, otherwise set to ``NULL``.
 
 * ``colvals`` - pointer to ``indexvals`` when ``sparsetype`` is
-  ``CSR_MAT``, otherwise set to ``NULL``.
+  ``SUN_CSR_MAT``, otherwise set to ``NULL``.
 
 * ``rowptrs`` - pointer to ``indexptrs`` when ``sparsetype`` is
-  ``CSR_MAT``, otherwise set to ``NULL``.
+  ``SUN_CSR_MAT``, otherwise set to ``NULL``.
 
 For example, the :math:`5\times 4` matrix
 
@@ -121,7 +121,7 @@ could be stored as a CSC matrix in this structure as either
    NNZ = 8;
    NP = N;
    data = {3.0, 1.0, 3.0, 7.0, 1.0, 2.0, 9.0, 5.0};
-   sparsetype = CSC_MAT;
+   sparsetype = SUN_CSC_MAT;
    indexvals = {1, 3, 0, 2, 0, 1, 3, 4};
    indexptrs = {0, 2, 4, 5, 8};
 
@@ -134,7 +134,7 @@ or
    NNZ = 10;
    NP = N;
    data = {3.0, 1.0, 3.0, 7.0, 1.0, 2.0, 9.0, 5.0, *, *};
-   sparsetype = CSC_MAT;
+   sparsetype = SUN_CSC_MAT;
    indexvals = {1, 3, 0, 2, 0, 1, 3, 4, *, *};
    indexptrs = {0, 2, 4, 5, 8};
 
@@ -152,7 +152,7 @@ Similarly, in CSR format, the same matrix could be stored as
    NNZ = 8;
    NP = M;
    data = {3.0, 1.0, 3.0, 2.0, 7.0, 1.0, 9.0, 5.0};
-   sparsetype = CSR_MAT;
+   sparsetype = SUN_CSR_MAT;
    indexvals = {1, 2, 0, 3, 1, 0, 3, 3};
    indexptrs = {0, 2, 4, 5, 7, 8};
 
@@ -335,8 +335,8 @@ following additional user-callable routines:
    ``SUNMatrix``.  Its arguments are the number of rows and columns of
    the matrix, *M* and *N*, the maximum number of nonzeros to be
    stored in the matrix, *NNZ*, and a flag *sparsetype* indicating
-   whether to use CSR or CSC format (valid choices are ``CSR_MAT`` or
-   ``CSC_MAT``).
+   whether to use CSR or CSC format (valid choices are ``SUN_CSR_MAT`` or
+   ``SUN_CSC_MAT``).
 
 
 
@@ -352,7 +352,7 @@ following additional user-callable routines:
 
    * *droptol* must be non-negative
 
-   * *sparsetype* must be either ``CSC_MAT`` or ``CSR_MAT``
+   * *sparsetype* must be either ``SUN_CSC_MAT`` or ``SUN_CSR_MAT``
 
    The function returns ``NULL`` if any requirements are violated, or if
    the matrix storage request cannot be satisfied.
@@ -371,7 +371,7 @@ following additional user-callable routines:
 
    * *droptol* must be non-negative
 
-   * *sparsetype* must be either ``CSC_MAT`` or ``CSR_MAT``.
+   * *sparsetype* must be either ``SUN_CSC_MAT`` or ``SUN_CSR_MAT``.
 
    The function returns ``NULL`` if any requirements are violated, or if
    the matrix storage request cannot be satisfied.
@@ -424,8 +424,8 @@ following additional user-callable routines:
 
 .. c:function:: int SUNSparseMatrix_SparseType(SUNMatrix A)
 
-   This function returns the storage type (``CSR_MAT``
-   or ``CSC_MAT``) for the sparse  ``SUNMatrix``.
+   This function returns the storage type (``SUN_CSR_MAT``
+   or ``SUN_CSC_MAT``) for the sparse  ``SUNMatrix``.
 
 
 .. c:function:: sunrealtype* SUNSparseMatrix_Data(SUNMatrix A)

doc/superbuild/source/developers/source_code/Naming.rst

@@ -86,7 +86,7 @@ When combining the two rules, the ``_ptr`` suffix should come last, e.g.
 
 .. warning::
 
-   The suffixes are **required** for parameters of functions within public header 
+   The suffixes are **required** for parameters of functions within public header
    files because the Python interface generator relies on the suffixes to determine
    the proper way to expose the parameter to Python users. It is preferable to follow
    this convention within other code, but not required.
@@ -114,15 +114,15 @@ Names for Vectors, Matrices, and Solvers
 The SUNDIALS vector, matrix, linear solver, and nonlinear solver classes use the
 naming convention ``<short class name><method>`` for base class methods where
 each component of the name uses Pascal case. See
-:numref:`_SourceCode.Table.OldBaseClassMethodNaming` for examples.
+:numref:`SourceCode.Naming.Table.OldBaseClassMethodNaming` for examples.
 
 .. note::
 
    This naming convention *only* applies to the vector, matrix, and solver
    classes. All other classes should follow the naming convention described in
    :ref:`SourceCode.Naming.NewClasses`.
 
-.. _SourceCode.Table.OldBaseClassMethodNaming:
+.. _SourceCode.Naming.Table.OldBaseClassMethodNaming:
 
 .. Table:: SUNDIALS base class naming convention examples for vectors, matrices,
            linear solvers and nonlinear solvers.
@@ -141,9 +141,9 @@ each component of the name uses Pascal case. See
 
 Derived class implementations of the base class methods should follow the naming
 convention ``<short class name><method>_<implementation>``. See
-:numref:`SourceCode.Table.OldDerivedClassMethodNaming` for examples.
+:numref:`SourceCode.Naming.Table.OldDerivedClassMethodNaming` for examples.
 
-.. _SourceCode.Table.OldDerivedClassMethodNaming:
+.. _SourceCode.Naming.Table.OldDerivedClassMethodNaming:
 
 .. Table:: SUNDIALS derived class naming convention examples for vectors,
            matrices, linear solvers and nonlinear solvers.
@@ -173,7 +173,7 @@ Names for New Classes
 
 All new base classes should use the naming convention ``<class name>_<method>``
 for the base class methods. See
-:numref:`SourceCode.Table.NewBaseClassMethodNaming` for examples.
+:numref:`SourceCode.Naming.Table.NewBaseClassMethodNaming` for examples.
 
 .. _SourceCode.Naming.Table.NewBaseClassMethodNaming:
 
@@ -187,7 +187,7 @@ for the base class methods. See
 
 Derived class implementations of the base class methods should follow the naming
 convention  ``<class name>_<method>_<implementation>``. See
-:numref:`SourceCode.Table.NewDerivedClassMethodNaming` for examples.
+:numref:`SourceCode.Naming.Table.NewDerivedClassMethodNaming` for examples.
 
 .. _SourceCode.Naming.Table.NewDerivedClassMethodNaming:
 

doc/superbuild/source/developers/source_code/Rules.rst

@@ -216,9 +216,9 @@ not adhere to all of these rules.
       int array_length = 10;
       int* array1 = malloc(array_length * sizeof(a)); // Do this
       int* array2 = malloc(array_length * sizeof(int)); // Don't do this
-      
-#. Do not use anonymous ``enum`` s in public header files (the Python interface generator doesn't like it).
-   Wrap typedef statements in SWIG guards, e.g. 
+
+#. Do not use anonymous ``enum`` s in public header files (the Python interface
+   generator doesn't like it). Wrap typedef statements in SWIG guards, e.g.
 
    .. code-block:: c
 

examples/arkode/C_klu/ark_brusselator1D_klu.c

@@ -234,7 +234,7 @@ int main(void)
 
   /* Initialize sparse matrix data structure and KLU solver */
   NNZ = 5 * NEQ;
-  A   = SUNSparseMatrix(NEQ, NEQ, NNZ, CSC_MAT, ctx);
+  A   = SUNSparseMatrix(NEQ, NEQ, NNZ, SUN_CSC_MAT, ctx);
   if (check_flag((void*)A, "SUNSparseMatrix", 0)) { return 1; }
 
   LS = SUNLinSol_KLU(y, A, ctx);
@@ -445,7 +445,7 @@ static int Jac(sunrealtype t, N_Vector y, N_Vector fy, SUNMatrix J,
   {
     udata->R = SUNSparseMatrix(SUNSparseMatrix_Rows(J),
                                SUNSparseMatrix_Columns(J),
-                               SUNSparseMatrix_NNZ(J), CSC_MAT, J->sunctx);
+                               SUNSparseMatrix_NNZ(J), SUN_CSC_MAT, J->sunctx);
     if (udata->R == NULL)
     {
       printf("Jacobian calculation error in allocating R matrix!\n");

examples/arkode/C_superlu-mt/ark_brusselator1D_FEM_slu.c

@@ -306,7 +306,7 @@ int main(int argc, char* argv[])
   /* Initialize sparse matrix data structure and linear solvers (system and mass) */
   NNZ = 15 * NEQ;
 
-  A = SUNSparseMatrix(NEQ, NEQ, NNZ, CSR_MAT, ctx);
+  A = SUNSparseMatrix(NEQ, NEQ, NNZ, SUN_CSR_MAT, ctx);
   if (check_retval((void*)A, "SUNSparseMatrix", 0)) { return (1); }
 
   LS = SUNLinSol_SuperLUMT(y, A, num_threads, ctx);
@@ -742,7 +742,7 @@ static int Jac(sunrealtype t, N_Vector y, N_Vector fy, SUNMatrix J,
   {
     udata->R = SUNSparseMatrix(SUNSparseMatrix_Rows(J),
                                SUNSparseMatrix_Columns(J),
-                               SUNSparseMatrix_NNZ(J), CSR_MAT, J->sunctx);
+                               SUNSparseMatrix_NNZ(J), SUN_CSR_MAT, J->sunctx);
     if (udata->R == NULL)
     {
       printf("Jac: error in allocating R matrix!\n");

examples/cvode/F2003_serial/cv_analytic_sys_klu_f2003.f90

@@ -242,7 +242,7 @@ program main
   end if
 
   ! create a sparse matrix
-  sunmat_A => FSUNSparseMatrix(neq, neq, neq*neq, CSC_MAT, sunctx)
+  sunmat_A => FSUNSparseMatrix(neq, neq, neq*neq, SUN_CSC_MAT, sunctx)
   if (.not. associated(sunmat_A)) then
     print *, 'ERROR: sunmat = NULL'
     stop 1

examples/cvode/F2003_serial/cv_roberts_klu_f2003.f90

@@ -318,7 +318,7 @@ program main
   end if
 
   ! Create sparse SUNMatrix for use in linear solves
-  sunmat_A => FSUNSparseMatrix(neq, neq, nnz, CSC_MAT, sunctx)
+  sunmat_A => FSUNSparseMatrix(neq, neq, nnz, SUN_CSC_MAT, sunctx)
   if (.not. associated(sunmat_A)) then
     print *, 'ERROR: sunmat = NULL'
     stop 1

examples/cvode/serial/cvRoberts_block_klu.c

@@ -184,7 +184,7 @@ int main(int argc, char* argv[])
 
   /* Create sparse SUNMatrix for use in linear solves */
   nnz = GROUPSIZE * GROUPSIZE * ngroups;
-  A   = SUNSparseMatrix(neq, neq, nnz, CSR_MAT, sunctx);
+  A   = SUNSparseMatrix(neq, neq, nnz, SUN_CSR_MAT, sunctx);
   if (check_retval((void*)A, "SUNSparseMatrix", 0)) { return (1); }
 
   /* Create KLU solver object for use by CVode */

examples/cvode/serial/cvRoberts_klu.c

@@ -160,7 +160,7 @@ int main(void)
   if (check_retval(&retval, "CVodeRootInit", 1)) { return (1); }
 
   /* Create sparse SUNMatrix for use in linear solves */
-  A = SUNSparseMatrix(NEQ, NEQ, NNZ, CSC_MAT, sunctx);
+  A = SUNSparseMatrix(NEQ, NEQ, NNZ, SUN_CSC_MAT, sunctx);
   if (check_retval((void*)A, "SUNSparseMatrix", 0)) { return (1); }
 
   /* Create KLU solver object for use by CVode */

examples/cvode/serial/cvRoberts_sps.c

@@ -160,7 +160,7 @@ int main(void)
   if (check_retval(&retval, "CVodeRootInit", 1)) { return (1); }
 
   /* Create sparse SUNMatrix for use in linear solves */
-  A = SUNSparseMatrix(NEQ, NEQ, NNZ, CSC_MAT, sunctx);
+  A = SUNSparseMatrix(NEQ, NEQ, NNZ, SUN_CSC_MAT, sunctx);
   if (check_retval((void*)A, "SUNSparseMatrix", 0)) { return (1); }
 
   /* Create SuperLUMT solver object for use by CVode (one thread) */

examples/cvodes/serial/cvsRoberts_ASAi_klu.c

@@ -229,7 +229,7 @@ int main(int argc, char* argv[])
 
   /* Create sparse SUNMatrix for use in linear solves */
   nnz = NEQ * NEQ; /* max no. of nonzeros entries in the Jac */
-  A   = SUNSparseMatrix(NEQ, NEQ, nnz, CSC_MAT, sunctx);
+  A   = SUNSparseMatrix(NEQ, NEQ, nnz, SUN_CSC_MAT, sunctx);
   if (check_retval((void*)A, "SUNSparseMatrix", 0)) { return (1); }
 
   /* Create KLU SUNLinearSolver object */
@@ -372,7 +372,7 @@ int main(int argc, char* argv[])
   if (check_retval(&retval, "CVodeSetUserDataB", 1)) { return (1); }
 
   /* Create sparse SUNMatrix for use in linear solves */
-  AB = SUNSparseMatrix(NEQ, NEQ, nnz, CSC_MAT, sunctx);
+  AB = SUNSparseMatrix(NEQ, NEQ, nnz, SUN_CSC_MAT, sunctx);
   if (check_retval((void*)A, "SUNSparseMatrix", 0)) { return (1); }
 
   /* Create KLU SUNLinearSolver object */

examples/cvodes/serial/cvsRoberts_ASAi_sps.c

@@ -229,7 +229,7 @@ int main(int argc, char* argv[])
 
   /* Create sparse SUNMatrix for use in linear solves */
   nnz = NEQ * NEQ; /* max no. of nonzeros entries in the Jac */
-  A   = SUNSparseMatrix(NEQ, NEQ, nnz, CSC_MAT, sunctx);
+  A   = SUNSparseMatrix(NEQ, NEQ, nnz, SUN_CSC_MAT, sunctx);
   if (check_retval((void*)A, "SUNSparseMatrix", 0)) { return (1); }
 
   /* Create SuperLUMT SUNLinearSolver object */
@@ -373,7 +373,7 @@ int main(int argc, char* argv[])
   if (check_retval(&retval, "CVodeSetUserDataB", 1)) { return (1); }
 
   /* Create sparse SUNMatrix for use in linear solves */
-  AB = SUNSparseMatrix(NEQ, NEQ, nnz, CSC_MAT, sunctx);
+  AB = SUNSparseMatrix(NEQ, NEQ, nnz, SUN_CSC_MAT, sunctx);
   if (check_retval((void*)A, "SUNSparseMatrix", 0)) { return (1); }
 
   /* Create SuperLUMT SUNLinearSolver object */

examples/cvodes/serial/cvsRoberts_FSA_klu.c

@@ -207,7 +207,7 @@ int main(int argc, char* argv[])
   if (check_retval(&retval, "CVodeSetUserData", 1)) { return (1); }
 
   /* Create sparse SUNMatrix for use in linear solves */
-  A = SUNSparseMatrix(NEQ, NEQ, NNZ, CSC_MAT, sunctx);
+  A = SUNSparseMatrix(NEQ, NEQ, NNZ, SUN_CSC_MAT, sunctx);
   if (check_retval((void*)A, "SUNSparseMatrix", 0)) { return (1); }
 
   /* Create KLU SUNLinearSolver object */

examples/cvodes/serial/cvsRoberts_FSA_sps.c

@@ -207,7 +207,7 @@ int main(int argc, char* argv[])
   if (check_retval(&retval, "CVodeSetUserData", 1)) { return (1); }
 
   /* Create sparse SUNMatrix for use in linear solves */
-  A = SUNSparseMatrix(NEQ, NEQ, NNZ, CSC_MAT, sunctx);
+  A = SUNSparseMatrix(NEQ, NEQ, NNZ, SUN_CSC_MAT, sunctx);
   if (check_retval((void*)A, "SUNSparseMatrix", 0)) { return (1); }
 
   /* Create SuperLUMT solver object for use by CVode (one thread) */

examples/cvodes/serial/cvsRoberts_klu.c

@@ -160,7 +160,7 @@ int main(void)
   if (check_retval(&retval, "CVodeRootInit", 1)) { return (1); }
 
   /* Create sparse SUNMatrix for use in linear solves */
-  A = SUNSparseMatrix(NEQ, NEQ, NNZ, CSC_MAT, sunctx);
+  A = SUNSparseMatrix(NEQ, NEQ, NNZ, SUN_CSC_MAT, sunctx);
   if (check_retval((void*)A, "SUNSparseMatrix", 0)) { return (1); }
 
   /* Create KLU solver object for use by CVode */

examples/cvodes/serial/cvsRoberts_sps.c

@@ -160,7 +160,7 @@ int main(void)
   if (check_retval(&retval, "CVodeRootInit", 1)) { return (1); }
 
   /* Create sparse SUNMatrix for use in linear solves */
-  A = SUNSparseMatrix(NEQ, NEQ, NNZ, CSC_MAT, sunctx);
+  A = SUNSparseMatrix(NEQ, NEQ, NNZ, SUN_CSC_MAT, sunctx);
   if (check_retval((void*)A, "SUNSparseMatrix", 0)) { return (1); }
 
   /* Create SuperLUMT solver object for use by CVode (one thread) */

examples/ida/serial/idaHeat2D_klu.c

@@ -177,7 +177,7 @@ int main(void)
 
   /* Create sparse SUNMatrix for use in linear solves */
   nnz = NEQ * NEQ;
-  A   = SUNSparseMatrix(NEQ, NEQ, nnz, CSC_MAT, ctx);
+  A   = SUNSparseMatrix(NEQ, NEQ, nnz, SUN_CSC_MAT, ctx);
   if (check_retval((void*)A, "SUNSparseMtarix", 0)) { return (1); }
 
   /* Create KLU SUNLinearSolver object */

examples/ida/serial/idaRoberts_klu.c

@@ -153,7 +153,7 @@ int main(void)
 
   /* Create sparse SUNMatrix for use in linear solves */
   nnz = NEQ * NEQ;
-  A   = SUNSparseMatrix(NEQ, NEQ, nnz, CSR_MAT, ctx);
+  A   = SUNSparseMatrix(NEQ, NEQ, nnz, SUN_CSR_MAT, ctx);
   if (check_retval((void*)A, "SUNSparseMatrix", 0)) { return (1); }
 
   /* Create KLU SUNLinearSolver object */

examples/ida/serial/idaRoberts_sps.c

@@ -149,7 +149,7 @@ int main(void)
 
   /* Create sparse SUNMatrix for use in linear solves */
   nnz = NEQ * NEQ;
-  A   = SUNSparseMatrix(NEQ, NEQ, nnz, CSC_MAT, ctx);
+  A   = SUNSparseMatrix(NEQ, NEQ, nnz, SUN_CSC_MAT, ctx);
   if (check_retval((void*)A, "SUNSparseMatrix", 0)) { return (1); }
 
   /* Create SuperLUMT SUNLinearSolver object (one thread) */

examples/idas/serial/idasRoberts_ASAi_klu.c

@@ -229,7 +229,7 @@ int main(int argc, char* argv[])
 
   /* Create sparse SUNMatrix for use in linear solves */
   nnz = NEQ * NEQ;
-  A   = SUNSparseMatrix(NEQ, NEQ, nnz, CSC_MAT, ctx);
+  A   = SUNSparseMatrix(NEQ, NEQ, nnz, SUN_CSC_MAT, ctx);
   if (check_retval((void*)A, "SUNSparseMatrix", 0)) { return (1); }
 
   /* Create KLU SUNLinearSolver object (one thread) */
@@ -373,7 +373,7 @@ int main(int argc, char* argv[])
   if (check_retval(&retval, "IDASetMaxNumStepsB", 1)) { return (1); }
 
   /* Create sparse SUNMatrix for use in linear solves */
-  AB = SUNSparseMatrix(NEQ, NEQ, nnz, CSC_MAT, ctx);
+  AB = SUNSparseMatrix(NEQ, NEQ, nnz, SUN_CSC_MAT, ctx);
   if (check_retval((void*)AB, "SUNSparseMatrix", 0)) { return (1); }
 
   /* Create KLU SUNLinearSolver object (one thread) */