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

.gitignore

@@ -19,6 +19,7 @@
 /.pydevproject
 .vscode
 compile_commands.json
+.venv
 .clangd
 
 # custom test environment setup script
@@ -82,3 +83,7 @@ uberenv_libs
 
 # tools
 /tools/suntools/__pycache__
+
+# python
+.pytest_cache
+__pycache__

doc/shared/nvectors/NVector_Kokkos.rst

@@ -64,14 +64,14 @@ To use the NVECTOR_KOKKOS module, we construct an instance of the ``Vector`` cla
 
 
 Instances of the ``Vector`` class are implicitly or explicitly (using the
-:cpp:func:`~Vector::Convert` method) convertible to a :c:type:`N_Vector`
+:cpp:func:`~Vector::get` method) convertible to a :c:type:`N_Vector`
 e.g.,
 
 .. code-block:: cpp
 
    sundials::kokkos::Vector<> x{length, sunctx};
-   N_Vector x2 = x;           // implicit conversion to N_Vector
-   N_Vector x3 = x.Convert(); // explicit conversion to N_Vector
+   N_Vector x2 = x;       // implicit conversion to N_Vector
+   N_Vector x3 = x.get(); // explicit conversion to N_Vector
 
 No further interaction with a ``Vector`` is required from this point, and
 it is possible to use the :c:type:`N_Vector` API to operate on ``x2`` or ``x3``.
@@ -184,11 +184,11 @@ class.
 
       Implicit conversion to a :c:type:`N_Vector`.
 
-   .. cpp:function:: N_Vector Convert() override
+   .. cpp:function:: N_Vector get() override
 
       Explicit conversion to a :c:type:`N_Vector`.
 
-   .. cpp:function:: N_Vector Convert() const override
+   .. cpp:function:: N_Vector get() const override
 
       Explicit conversion to a :c:type:`N_Vector`.
 

doc/shared/sundials/Fortran.rst

@@ -488,6 +488,11 @@ a C file pointer, SUNDIALS provides two utility functions for creating a
 
 .. c:function:: SUNErrCode SUNDIALSFileOpen(const char* filename, const char* mode, FILE** fp)
 
+   Deprecated alias to :c:func:`SUNFileOpen`.
+
+
+.. c:function:: SUNErrCode SUNFileOpen(const char* filename, const char* mode, FILE** fp)
+
    The function allocates a ``FILE*`` by calling the C function ``fopen`` with
    the provided filename and I/O mode.
 
@@ -522,33 +527,36 @@ a C file pointer, SUNDIALS provides two utility functions for creating a
       type(c_ptr) :: fp
 
       ! Open up the file output.log for writing
-      ierr = FSUNDIALSFileOpen("output.log", "w+", fp)
+      ierr = FSUNFileOpen("output.log", "w+", fp)
 
       ! The C function ARKStepPrintMem takes void* arkode_mem and FILE* fp as arguments
       call FARKStepPrintMem(arkode_mem, fp)
 
       ! Close the file
       ierr = FSUNDIALSFileClose(fp)
 
-   .. versionchanged:: 7.0.0
+   .. versionadded:: X.Y.Z
 
-      The function signature was updated to return a `SUNErrCode` and take a `FILE**` as the last input parameter rather then return a `FILE*`.
 
 .. c:function:: SUNErrCode SUNDIALSFileClose(FILE** fp)
 
+   Deprecated alias to :c:func:`SUNFileOpen`
+
+   .. deprecated:: X.Y.Z
+
+
+.. c:function:: SUNErrCode SUNFileClose(FILE** fp)
+
    The function deallocates a C ``FILE*`` by calling the C function ``fclose``
    with the provided pointer.
 
    :param fp: the C ``FILE*`` that was previously obtained from ``fopen``.
         This should have the Fortran type ``type(c_ptr)``.  Note that if either
-        ``stdout`` or ``stderr`` were opened using :c:func:`SUNDIALSFileOpen()`
+        ``stdout`` or ``stderr`` were opened using :c:func:`SUNFileOpen()`
 
    :return: A :c:type:`SUNErrCode`
-
-   .. versionchanged:: 7.0.0
-
-      The function signature was updated to return a `SUNErrCode` and the `fp` parameter was changed from `FILE*` to `FILE**`.
-
+
+   .. versionadded:: X.Y.Z
 
 
 .. _SUNDIALS.Fortran.Portability:

doc/shared/sundials/SUNContext.rst

@@ -302,11 +302,11 @@ For C++ users a RAII safe class, ``sundials::Context``, is provided:
    Context& operator=(const Context&) = delete;
    Context& operator=(Context&&) = default;
 
-   SUNContext Convert() override
+   SUNContext get() override
    {
       return *sunctx_.get();
    }
-   SUNContext Convert() const override
+   SUNContext get() const override
    {
       return *sunctx_.get();
    }

doc/shared/sundials/Types.rst

@@ -88,6 +88,21 @@ code can use SUNDIALS without modifying the code to use ``sunrealtype``,
 ``SUN_RCONST``, or the ``SUNR`` macros so long as the SUNDIALS libraries are built
 to use the corresponding precision (see :numref:`Installation.Options`).
 
+For implementation reasons, SUNDIALS also defines the types:
+
+.. c:type:: sunrealtype1d
+
+   This is a ``sunrealtype*`` which should be treated as 1D contiguous array.
+
+.. c:type:: sunrealtype2d
+
+   This is a ``sunrealtype**`` which should be treated as 2D contiguous array.
+
+.. c:type:: sunrealtype3d
+
+   This is a ``sunrealtype***`` which should be treated as 3D contiguous array.
+
+
 Integer types used for indexing
 -------------------------------
 
@@ -116,6 +131,20 @@ SUNDIALS without modifying the code to use ``sunindextype``, so long as the
 SUNDIALS libraries use the appropriate index storage type (for details see
 :numref:`Installation.Options`).
 
+For implementation reasons, SUNDIALS also defines the types:
+
+.. c:type:: sunindextype1d
+
+   This is a ``sunindextype*`` which should be treated as 1D contiguous array.
+
+.. c:type:: sunindextype2d
+
+   This is a ``sunindextype**`` which should be treated as 2D contiguous array.
+
+.. c:type:: sunindextype3d
+
+   This is a ``sunindextype***`` which should be treated as 3D contiguous array.
+
 Integer type used for counters
 ------------------------------
 

doc/shared/sunlinsol/SUNLinSol_Ginkgo.rst

@@ -89,7 +89,7 @@ expecting a ``SUNLinearSolver`` object through the implicit conversion operator
 
    // Alternatively with explicit conversion of LS to a SUNLinearSolver
    // and A to a SUNMatrix:
-   CVodeSetLinearSolver(cvode_mem, LS->Convert(), A->Convert());
+   CVodeSetLinearSolver(cvode_mem, LS->get(), A->get());
 
 
 .. warning::
@@ -139,11 +139,11 @@ In this section we list the public API of the :cpp:type:`sundials::ginkgo::Linea
 
       Implicit conversion to a :c:type:`SUNLinearSolver`.
 
-   .. cpp:function:: SUNLinearSolver Convert() override
+   .. cpp:function:: SUNLinearSolver get() override
 
       Explicit conversion to a :c:type:`SUNLinearSolver`.
 
-   .. cpp:function:: SUNLinearSolver Convert() const override
+   .. cpp:function:: SUNLinearSolver get() const override
 
       Explicit conversion to a :c:type:`SUNLinearSolver`.
 

doc/shared/sunlinsol/SUNLinSol_KokkosDense.rst

@@ -55,14 +55,14 @@ instance of a dense linear solver e.g.,
     sundials::kokkos::DenseLinearSolver<> LS{sunctx};
 
 Instances of the ``DenseLinearSolver`` class are implicitly or explicitly (using
-the :cpp:func:`~DenseLinearSolver::Convert` method) convertible to a
+the :cpp:func:`~DenseLinearSolver::get` method) convertible to a
 :c:type:`SUNLinearSolver` e.g.,
 
 .. code-block:: cpp
 
    sundials::kokkos::DenseLinearSolver<> LS{sunctx};
    SUNLinearSolver LSA = LS;           // implicit conversion to SUNLinearSolver
-   SUNLinearSolver LSB = LS.Convert(); // explicit conversion to SUNLinearSolver
+   SUNLinearSolver LSB = LS.get(); // explicit conversion to SUNLinearSolver
 
 .. warning::
 
@@ -118,10 +118,10 @@ In this section we list the public API of the
 
       Implicit conversion to a :c:type:`SUNLinearSolver`.
 
-   .. cpp:function:: SUNLinearSolver Convert() override
+   .. cpp:function:: SUNLinearSolver get() override
 
       Explicit conversion to a :c:type:`SUNLinearSolver`.
 
-   .. cpp:function:: SUNLinearSolver Convert() const override
+   .. cpp:function:: SUNLinearSolver get() const override
 
       Explicit conversion to a :c:type:`SUNLinearSolver`.

doc/shared/sunmatrix/SUNMatrix_Ginkgo.rst

@@ -75,12 +75,12 @@ and then fill the diagonal of the matrix with ones to make an identity matrix:
 
 After we have a Ginkgo matrix object, we wrap it in an instance of the ``sundials::ginkgo::Matrix``
 class. This object can be provided to other SUNDIALS functions that expect a ``SUNMatrix`` object
-via implicit conversion, or the ``Convert()`` method:
+via implicit conversion, or the ``get()`` method:
 
 .. code-block:: cpp
 
   sundials::ginkgo::Matrix<gko::matrix::Csr> matrix{gko_matrix, sunctx};
-  SUNMatrix I1 = matrix.Convert(); // explicit conversion to SUNMatrix
+  SUNMatrix I1 = matrix.get(); // explicit conversion to SUNMatrix
   SUNMatrix I2 = matrix;  // implicit conversion to SUNMatrix
 
 No further interaction with ``matrix`` is required from this point, and it is possible to
@@ -156,10 +156,10 @@ In this section we list the public API of the ``sundials::ginkgo::Matrix`` class
 
       Implicit conversion to a :c:type:`SUNMatrix`.
 
-  .. cpp:function:: SUNMatrix Convert() override
+  .. cpp:function:: SUNMatrix get() override
 
       Explicit conversion to a :c:type:`SUNMatrix`.
 
-  .. cpp:function:: SUNMatrix Convert() const override
+  .. cpp:function:: SUNMatrix get() const override
 
       Explicit conversion to a :c:type:`SUNMatrix`.

doc/shared/sunmatrix/SUNMatrix_KokkosDense.rst

@@ -69,14 +69,14 @@ the Kokkos dense matrix e.g.,
                                                       sunctx};
 
 Instances of the ``DenseMatrix`` class are implicitly or explicitly (using the
-:cpp:func:`~DenseMatrix::Convert` method) convertible to a :c:type:`SUNMatrix`
+:cpp:func:`~DenseMatrix::get` method) convertible to a :c:type:`SUNMatrix`
 e.g.,
 
 .. code-block:: cpp
 
    sundials::kokkos::DenseMatrix<> A{rows, cols, sunctx};
    SUNMatrix B = A;           // implicit conversion to SUNMatrix
-   SUNMatrix C = A.Convert(); // explicit conversion to SUNMatrix
+   SUNMatrix C = A.get(); // explicit conversion to SUNMatrix
 
 No further interaction with a ``DenseMatrix`` is required from this point, and
 it is possible to use the :c:type:`SUNMatrix` API to operate on ``B`` or ``C``.
@@ -232,11 +232,11 @@ class.
 
       Implicit conversion to a :c:type:`SUNMatrix`.
 
-   .. cpp:function:: SUNMatrix Convert() override
+   .. cpp:function:: SUNMatrix get() override
 
       Explicit conversion to a :c:type:`SUNMatrix`.
 
-   .. cpp:function:: SUNMatrix Convert() const override
+   .. cpp:function:: SUNMatrix get() const override
 
       Explicit conversion to a :c:type:`SUNMatrix`.
 

examples/cvode/kokkos/cv_bruss_batched_kokkos.cpp

@@ -243,7 +243,7 @@ int main(int argc, char* argv[])
       LS = std::make_unique<LSType>(sunctx);
 
       // Attach the matrix and linear solver to CVODE
-      retval = CVodeSetLinearSolver(cvode_mem, LS->Convert(), A->Convert());
+      retval = CVodeSetLinearSolver(cvode_mem, LS->get(), A->get());
       if (check_flag(retval, "CVodeSetLinearSolver")) { return 1; }
 
       // Set the user-supplied Jacobian function
@@ -257,7 +257,7 @@ int main(int argc, char* argv[])
         SUNLinSol_SPGMR(y, SUN_PREC_NONE, 0, sunctx));
 
       // Attach the linear solver to CVODE
-      retval = CVodeSetLinearSolver(cvode_mem, LS->Convert(), nullptr);
+      retval = CVodeSetLinearSolver(cvode_mem, LS->get(), nullptr);
       if (check_flag(retval, "CVodeSetLinearSolver")) { return 1; }
     }
 

examples/cvode/kokkos/cv_bruss_batched_kokkos_2D.cpp

@@ -255,7 +255,7 @@ int main(int argc, char* argv[])
       LS = std::make_unique<LSType>(sunctx);
 
       // Attach the matrix and linear solver to CVODE
-      retval = CVodeSetLinearSolver(cvode_mem, LS->Convert(), A->Convert());
+      retval = CVodeSetLinearSolver(cvode_mem, LS->get(), A->get());
       if (check_flag(retval, "CVodeSetLinearSolver")) { return 1; }
 
       // Set the user-supplied Jacobian function
@@ -269,7 +269,7 @@ int main(int argc, char* argv[])
         SUNLinSol_SPGMR(y, SUN_PREC_NONE, 0, sunctx));
 
       // Attach the linear solver to CVODE
-      retval = CVodeSetLinearSolver(cvode_mem, LS->Convert(), nullptr);
+      retval = CVodeSetLinearSolver(cvode_mem, LS->get(), nullptr);
       if (check_flag(retval, "CVodeSetLinearSolver")) { return 1; }
     }
 

include/arkode/arkode.h

@@ -163,7 +163,7 @@ extern "C" {
 typedef int (*ARKRhsFn)(sunrealtype t, N_Vector y, N_Vector ydot,
                         void* user_data);
 
-typedef int (*ARKRootFn)(sunrealtype t, N_Vector y, sunrealtype* gout,
+typedef int (*ARKRootFn)(sunrealtype t, N_Vector y, sunrealtype1d gout,
                          void* user_data);
 
 typedef int (*ARKEwtFn)(N_Vector y, N_Vector ewt, void* user_data);
@@ -197,24 +197,27 @@ typedef _SUNDIALS_STRUCT_ _MRIStepInnerStepper* MRIStepInnerStepper;
 /* --------------------------
  * Relaxation Solver Options
  * -------------------------- */
-
-typedef enum
+enum ARKRelaxSolver_
 {
   ARK_RELAX_BRENT,
   ARK_RELAX_NEWTON
-} ARKRelaxSolver;
+};
+
+typedef enum ARKRelaxSolver_ ARKRelaxSolver;
 
 /* --------------------------
  * Error Accumulation Options
  * -------------------------- */
 
-typedef enum
+enum ARKAccumError_
 {
   ARK_ACCUMERROR_NONE,
   ARK_ACCUMERROR_MAX,
   ARK_ACCUMERROR_SUM,
   ARK_ACCUMERROR_AVG
-} ARKAccumError;
+};
+
+typedef enum ARKAccumError_ ARKAccumError;
 
 /* --------------------------
  * Shared API routines