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__

CHANGELOG.md

@@ -6,10 +6,22 @@
 
 ### New Features and Enhancements
 
+The functions ``CVodeGetUserDataB`` and ``IDAGetUserDataB`` were added to CVODES
+and IDAS, respectively.
+
 ### Bug Fixes
 
 ### Deprecation Notices
 
+`SUNDIALSFileOpen` and `SUNDIALSFileClose` will be removed in the next major release. 
+Use `SUNFileOpen` and `SUNFileClose` instead.
+
+The `Convert` methods on the `sundials::kokkos:Vector`, `sundials::kokkos::DenseMatrix`,
+`sundials::ginkgo::Matrix`, `sundials::ginkgo::BatchMatrix`, `sundials::kokkos::DenseLinearSolver`,
+`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.
+
 ## Changes to SUNDIALS in release 7.5.0
 
 ### Major Features

doc/shared/RecentChanges.rst

@@ -5,6 +5,18 @@
 
 **New Features and Enhancements**
 
+The functions ``CVodeGetUserDataB`` and ``IDAGetUserDataB`` were added to CVODES
+and IDAS, respectively.
+
 **Bug Fixes**
 
 **Deprecation Notices**
+
+:c:func:`SUNDIALSFileOpen` and :c:func:`SUNDIALSFileClose` will be removed in the next major release. 
+Use :c:func:`SUNFileOpen` and :c:func:`SUNFileClose` instead.
+
+The ``Convert`` methods on the ``sundials::kokkos:Vector``, ``sundials::kokkos::DenseMatrix``,
+``sundials::ginkgo::Matrix``, ``sundials::ginkgo::BatchMatrix``, ``sundials::kokkos::DenseLinearSolver``,
+``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.

doc/shared/nvectors/NVector_Kokkos.rst

@@ -67,14 +67,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``.
@@ -187,13 +187,21 @@ 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`.
+
+      .. versionadded:: x.y.z
+
+         Replaces the ``Convert`` method which was deprecated and moved to the ``ConvertibleTo`` class.
 
-   .. cpp:function:: N_Vector Convert() const override
+   .. cpp:function:: N_Vector get() const override
 
       Explicit conversion to a :c:type:`N_Vector`.
+
+      .. versionadded:: x.y.z
+
+         Replaces the ``Convert`` method which was deprecated and moved to the ``ConvertibleTo`` class.
 
 
 .. cpp:function:: template<class VectorType> inline VectorType* GetVec(N_Vector v)

doc/shared/sundials/Fortran.rst

@@ -491,6 +491,13 @@ 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:: x.y.z
+
+      See :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.
 
@@ -525,33 +532,40 @@ 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
+   
+      Replaces ``SUNDIALSFileOpen``
 
-      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:: X.Y.Z
+
+      See :c:func:`SUNFileClose`
+
+
+.. 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
+   
+      Replaces ``SUNDIALSFileClose``
 
 
 .. _SUNDIALS.Fortran.Portability:

doc/shared/sundials/SUNContext.rst

@@ -305,11 +305,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/sunlinsol/SUNLinSol_Ginkgo.rst

@@ -92,7 +92,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::
@@ -142,14 +142,22 @@ 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
+      .. versionadded:: x.y.z
+
+         Replaces the ``Convert`` method which was deprecated and moved to the ``ConvertibleTo`` class.
+
+   .. cpp:function:: SUNLinearSolver get() const override
 
       Explicit conversion to a :c:type:`SUNLinearSolver`.
 
+      .. versionadded:: x.y.z
+
+         Replaces the ``Convert`` method which was deprecated and moved to the ``ConvertibleTo`` class.
+
    .. cpp:function:: std::shared_ptr<const gko::Executor> GkoExec() const
 
       Get the ``gko::Executor`` associated with the Ginkgo solver.

doc/shared/sunlinsol/SUNLinSol_GinkgoBatch.rst

@@ -72,7 +72,7 @@ For example,
 
    // 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());
 
 After attaching the linear solver to the SUNDIALS integrator, one must change the norm factor the integrator uses
 since the Ginkgo linear solver will take norms over individual batches, not the entire system.
@@ -222,14 +222,22 @@ The public API of the :cpp:type:`sundials::ginkgo::BatchLinearSolver` class is a
 
       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
+      .. versionadded:: x.y.z
+      
+         Replaces the ``Convert`` method which was deprecated and moved to the ``ConvertibleTo`` class.
+
+   .. cpp:function:: SUNLinearSolver get() const override
 
       Explicit conversion to a :c:type:`SUNLinearSolver`.
 
+      .. versionadded:: x.y.z
+      
+         Replaces the ``Convert`` method which was deprecated and moved to the ``ConvertibleTo`` class.
+
    .. cpp:function:: std::shared_ptr<const gko::Executor> GkoExec() const
 
       Get the ``gko::Executor`` associated with the Ginkgo solver.

doc/shared/sunlinsol/SUNLinSol_KokkosDense.rst

@@ -58,14 +58,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::
 
@@ -121,10 +121,18 @@ 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
+      .. versionadded:: x.y.z
+
+         Replaces the ``Convert`` method which was deprecated and moved to the ``ConvertibleTo`` class.
+
+   .. cpp:function:: SUNLinearSolver get() const override
 
       Explicit conversion to a :c:type:`SUNLinearSolver`.
+
+      .. versionadded:: x.y.z
+
+         Replaces the ``Convert`` method which was deprecated and moved to the ``ConvertibleTo`` class.

doc/shared/sunmatrix/SUNMatrix_Ginkgo.rst

@@ -78,12 +78,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
@@ -159,10 +159,18 @@ 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
+      .. versionadded:: x.y.z
+
+         Replaces the ``Convert`` method which was deprecated and moved to the ``ConvertibleTo`` class.
+
+  .. cpp:function:: SUNMatrix get() const override
 
       Explicit conversion to a :c:type:`SUNMatrix`.
+
+      .. versionadded:: x.y.z
+
+         Replaces the ``Convert`` method which was deprecated and moved to the ``ConvertibleTo`` class.

doc/shared/sunmatrix/SUNMatrix_GinkgoBatch.rst

@@ -121,10 +121,18 @@ In this section we list the public API of the
 
       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
+      .. versionadded:: x.y.z
+
+         Replaces the ``Convert`` method which was deprecated and moved to the ``ConvertibleTo`` class.
+
+   .. cpp:function:: SUNMatrix get() const override
 
       Explicit conversion to a :c:type:`SUNMatrix`.
+
+      .. versionadded:: x.y.z
+
+         Replaces the ``Convert`` method which was deprecated and moved to the ``ConvertibleTo`` class.

doc/shared/sunmatrix/SUNMatrix_KokkosDense.rst

@@ -72,14 +72,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``.
@@ -235,14 +235,22 @@ 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
+      .. versionadded:: x.y.z
+
+         Replaces the ``Convert`` method which was deprecated and moved to the ``ConvertibleTo`` class.
+
+   .. cpp:function:: SUNMatrix get() const override
 
       Explicit conversion to a :c:type:`SUNMatrix`.
 
+      .. versionadded:: x.y.z
+
+         Replaces the ``Convert`` method which was deprecated and moved to the ``ConvertibleTo`` class.
+
 .. cpp:function:: template<class ExecutionSpace = Kokkos::DefaultExecutionSpace, \
                            class MemorySpace = typename ExecutionSpace::memory_space> \
                   inline DenseMatrix<MatrixType>* GetDenseMat(SUNMatrix A)