SUNDomEigEst_Destroy

Author: maggul

doc/arkode/guide/source/Usage/LSRKStep/User_callable.rst

@@ -263,7 +263,7 @@ Allowable Method Families
 
    **Return value:**
       * *ARK_SUCCESS* if successful
-      * *ARKLS_MEM_NULL* if ``arkode_mem`` was ``NULL``.
+      * *ARK_MEM_NULL* if ``arkode_mem`` was ``NULL``.
 
 .. note:: If LSRKStepSetMaxNumStages routine is not called, then the default ``stage_max_limit`` is
    set to :math:`200`. Calling this function with ``stage_max_limit < 2`` resets the default value.
@@ -284,7 +284,7 @@ Allowable Method Families
 
    **Return value:**
       * *ARK_SUCCESS* if successful
-      * *ARKLS_MEM_NULL* if ``arkode_mem`` was ``NULL``.
+      * *ARK_MEM_NULL* if ``arkode_mem`` was ``NULL``.
 
 .. note:: If LSRKStepSetDomEigSafetyFactor routine is not called, then the default ``dom_eig_safety`` is
    set to :math:`1.01`. Calling this function with ``dom_eig_safety < 1`` resets the default value.
@@ -304,7 +304,7 @@ Allowable Method Families
 
    **Return value:**
       * *ARK_SUCCESS* if successful
-      * *ARKLS_MEM_NULL* if ``arkode_mem`` was ``NULL``.
+      * *ARK_MEM_NULL* if ``arkode_mem`` was ``NULL``.
       * *ARK_ILL_INPUT* if an argument had an illegal value (e.g. SSP method is not declared)
 
 .. note:: If LSRKStepSetNumSSPStages routine is not called, then the default ``num_of_stages`` is

doc/arkode/guide/source/sundomeigest/ARKODE_interface.rst

@@ -63,7 +63,7 @@ the interested reader.
    +----------------------------------------------------+---------------------+---------------------+
    | :c:func:`SUNDomEigEst_PrintStats`                  |          O          |          O          |
    +----------------------------------------------------+---------------------+---------------------+
-   | :c:func:`SUNDomEigEstFree`\ :sup:`4`               |                     |                     |
+   | :c:func:`SUNDomEigEst_Destroy`\ :sup:`4`           |                     |                     |
    +----------------------------------------------------+---------------------+---------------------+
 
 
@@ -83,6 +83,6 @@ Notes:
    implemented by the ``SUNDomEigEstimator`` then ARKDEE will consider all
    estimates as requiring zero iterations.
 
-4. Although ARKDEE does not call :c:func:`SUNDomEigEstFree()`
+4. Although ARKDEE does not call :c:func:`SUNDomEigEst_Destroy()`
    directly, this routine should be available for users to call when
    cleaning up from a simulation.

doc/shared/sundomeigest/SUNDomEigEst_API.rst

@@ -32,16 +32,38 @@ SUNDomEigEstimator core functions
 -----------------------------------------------------
 
 The core dominant eigenvalue estimator functions consist of several **required**
-functions: :c:func:`SUNDomEigEst_SetATimes` provides a :c:type:`SUNATimesFn` function pointer,
+functions: :c:func:`SUNDomEigEst_NewEmpty` creates a new empty ``SUNDomEigEstimator`` 
+object, :c:func:`SUNDomEigEst_SetATimes` provides a :c:type:`SUNATimesFn` function pointer,
 as well as a ``void*`` pointer to a data structure used by this routine,
 :c:func:`SUNDomEigEst_Initialize` initializes the estimator object once all estimator-specific
 options have been set, :c:func:`SUNDomEigEst_ComputeHess` computes Hessenberg matrix
-(if the estimator requires), :c:func:`SUNDomEig_Estimate` estimates the dominant eigenvalue, and
-:c:func:`SUNDomEigEstFree` destroys an estimator object.
+(if the estimator requires), :c:func:`SUNDomEig_Estimate` estimates the dominant eigenvalue,
+:c:func:`SUNDomEigEst_FreeEmpty` an empty estimator and :c:func:`SUNDomEigEst_Destroy` destroys 
+an estimator object.
 
 The remaining **optional** function, :c:func:`SUNDomEigEst_PreProcess` preprocesses the estimator object 
 to "warm-up" the estimator for a more appropriate initial vector before starting iterations.
 
+
+.. c:function:: SUNDomEigEstimator SUNDomEigEst_NewEmpty(SUNContext sunctx)
+
+   *Required.*
+
+   This function allocates a new ``SUNDomEigEstimator`` object and
+   initializes its content pointer and the function pointers in the operations
+   structure to ``NULL``.
+
+   **Arguments:**
+
+      * *sunctx* -- the :c:type:`SUNContext` object (see :numref:`SUNDIALS.SUNContext`)
+
+   **Return value:**
+
+      If successful, this function returns a ``SUNDomEigEstimator`` object.
+      If an error occurs when allocating the object, then this routine will
+      return ``NULL``.
+
+
 .. c:function:: SUNErrCode SUNDomEigEst_SetATimes(SUNDomEigEstimator DEE, void* A_data, SUNATimesFn ATimes)
 
    *Required.*
@@ -104,10 +126,8 @@ to "warm-up" the estimator for a more appropriate initial vector before starting
 
    **Return value:**
 
-      Zero for a successful call, a positive value for a recoverable failure,
-      and a negative value for an unrecoverable failure.  Ideally this should
-      return one of the generic error codes listed in
-      :numref:`SUNDomEigEst.ErrorCodes`.
+      `SUN_SUCCESS` for a successful call, or a relevant error code from  
+      :numref:`SUNDomEigEst.ErrorCodes` upon failure.  
 
    **Usage:**
 
@@ -147,20 +167,36 @@ to "warm-up" the estimator for a more appropriate initial vector before starting
          retval = SUNDomEig_Estimate(DEE, dom_eig);
 
 
+.. c:function:: SUNErrCode SUNDomEigEst_FreeEmpty(SUNDomEigEstimator DEE)
 
-.. c:function:: SUNErrCode SUNDomEigEstFree(SUNDomEigEstimator DEE)
+   This routine frees the ``SUNDomEigEstimator`` object, under the
+   assumption that any implementation-specific data that was allocated
+   within the underlying content structure has already been freed.
+   It will additionally test whether the ops pointer is ``NULL``,
+   and, if it is not, it will free it as well.
+
+   **Arguments:**
+
+      * *DEE* -- a SUNDomEigEstimator object
+
+   **Return value:**
+
+      A :c:type:`SUNErrCode`.
+
+
+.. c:function:: SUNErrCode SUNDomEigEst_Destroy(SUNDomEigEstimator* DEEptr)
 
    Frees memory allocated by the dominant eigenvalue estimatimator.
 
    **Arguments:**
 
-      * *DEE* -- a SUNDomEigEst object.
+      * *DEEptr* -- a SUNDomEigEst object pointer.
 
    **Usage:**
 
       .. code-block:: c
 
-         retval = SUNDomEigEstFree(DEE);
+         retval = SUNDomEigEst_Destroy(&DEE);
 
 
 .. _SUNDomEigEst.SetFn:
@@ -199,7 +235,7 @@ function pointer ``NULL`` instead of supplying a dummy routine.
 
 .. c:function:: SUNErrCode SUNDomEigEst_SetTol(SUNDomEigEstimator DEE, sunrealtype tol)
 
-   This *optional* routine sets the estimator tolerance.
+   This *optional* routine sets the estimator's :ref:`relative tolerance <pi_rel_tol>`.
 
    **Arguments:**
 
@@ -545,7 +581,7 @@ The virtual table structure is defined as
       
    .. c:member:: SUNErrCode (*free)(SUNDomEigEstimator)
 
-      The function implementing :c:func:`SUNDomEigEstFree`
+      The function implementing :c:func:`SUNDomEigEst_Destroy`
 
 The generic SUNDomEigEst class defines and implements the dominant eigenvalue estimator
 operations defined in :numref:`SUNDomEigEst.CoreFn` -- :numref:`SUNDomEigEst.GetFn`.
@@ -566,75 +602,6 @@ operation:
    }
 
 
-.. _SUNDomEigEst.API.Custom:
-
-Implementing a custom SUNDomEigEstimator module
---------------------------------------------------
-
-A particular implementation of the ``SUNDomEigEstimator`` module must:
-
-* Specify the *content* field of the SUNDomEigEst module.
-
-* Define and implement the required dominant eigenvalue estimator operations.
-
-  .. note::
-
-     The names of these routines should be unique to that
-     implementation in order to permit using more than one
-     SUNDomEigEst module (each with different ``SUNDomEigEstimator``
-     internal data representations) in the same code.
-
-* Define and implement user-callable constructor and destructor
-  routines to create and free a ``SUNDomEigEstimator`` with
-  the new *content* field and with *ops* pointing to the
-  new dominant eigenvalue estimator operations.
-
-We note that the function pointers for all unsupported optional
-routines should be set to ``NULL`` in the *ops* structure.  This
-allows the SUNDIALS package that is using the SUNDomEigEst object
-to know whether the associated functionality is supported.
-
-To aid in the creation of custom ``SUNDomEigEstimator`` modules the generic
-``SUNDomEigEstimator`` module provides the utility function
-:c:func:`SUNDomEigEst_NewEmpty`.  When used in custom ``SUNDomEigEstimator``
-constructors this function will ease the introduction of any new optional dominant
-eigenvalue estimator operations to the ``SUNDomEigEstimator`` API by ensuring that only required
-operations need to be set.
-
-.. c:function:: SUNDomEigEstimator SUNDomEigEst_NewEmpty(SUNContext sunctx)
-
-   This function allocates a new generic ``SUNDomEigEstimator`` object and
-   initializes its content pointer and the function pointers in the operations
-   structure to ``NULL``.
-
-   **Arguments:**
-
-      * *sunctx* -- the :c:type:`SUNContext` object (see :numref:`SUNDIALS.SUNContext`)
-
-   **Return value:**
-
-      If successful, this function returns a ``SUNDomEigEstimator`` object.
-      If an error occurs when allocating the object, then this routine will
-      return ``NULL``.
-
-
-.. c:function:: SUNErrCode SUNDomEigEst_FreeEmpty(SUNDomEigEstimator DEE)
-
-   This routine frees the generic ``SUNDomEigEstimator`` object, under the
-   assumption that any implementation-specific data that was allocated
-   within the underlying content structure has already been freed.
-   It will additionally test whether the ops pointer is ``NULL``,
-   and, if it is not, it will free it as well.
-
-   **Arguments:**
-
-      * *DEE* -- a SUNDomEigEstimator object
-
-   **Return value:**
-
-      A :c:type:`SUNErrCode`.
-
-
 Additionally, a ``SUNDomEigEstimator`` implementation *may* do the following:
 
 * Define and implement additional user-callable "set" routines

doc/shared/sundomeigest/SUNDomEigEst_ARNI.rst

@@ -148,7 +148,8 @@ This estimator is constructed to perform the following operations:
   that interfaces with SUNDomEigEst_ARNI to supply the ``ATimes``
   function pointer and the related data ``ATData``.
 * In the "initialize" call, the estimator parameters are checked
-  for validity and ARNI estimator memory is allocated.
+  for validity and the remaining ARNI estimator memory such as LAPACK 
+  workspace is allocated.
 
 * In the "preprocess" call, the initial nonzero vector :math:`q_0` is warmed up
   :math:`k=` ``numwarmups`` times as
@@ -175,4 +176,4 @@ dominant eigenvalue estimator operations listed in
 
 * ``SUNDomEig_Estimate_ArnI``
 
-* ``SUNDomEigEstFree_ArnI``
+* ``SUNDomEigEst_Destroy_ArnI``

doc/shared/sundomeigest/SUNDomEigEst_Introduction.rst

@@ -39,11 +39,12 @@ provide their own ``N_Vector`` and/or ``SUNMatrix`` modules.
 While Krylov-based estimators preset the number of Krylov subspace
 dimensions, resulting in a tolerance-free estimation, SUNDIALS requires
 that iterative estimators stop when the residual meets a prescribed
-tolerance, i.e.,
+tolerance, :math:`\tau`,
 
 .. math::
-
-   ||\lambda_{k+1} - \lambda_k|| < \text{tol}.
+  :name: pi_rel_tol
+  
+  \frac{\left|\lambda_k - \lambda_{k-1}\right|}{\left|\lambda_k \right|} < \tau.
 
 For users interested in providing their own SUNDomEigEst module, the
 following section presents the SUNDomEigEst API and its implementation
@@ -53,11 +54,7 @@ the definition of functions supplied to an estimator implementation in
 :numref:`SUNDomEigEst.SUNSuppliedFn`. The estimator return codes are described
 in :numref:`SUNDomEigEst.ErrorCodes`. The ``SUNDomEigEstimator`` type and the
 generic SUNDomEigEst module are defined in :numref:`SUNDomEigEst.Generic`.
-:numref:`SUNDomEigEst.API.Custom` lists the requirements for supplying a custom
-SUNDomEigEst module and discusses some intended use cases. Users wishing to
-supply their own SUNDomEigEst module are encouraged to use the SUNDomEigEst
-implementations provided with SUNDIALS as a template for supplying custom
-dominant eigenvalue estimator modules. The section that then follows describes
+The section that then follows describes
 the SUNDomEigEst functions required by this SUNDIALS package, and provides
 additional package specific details. Then the remaining sections of this
 chapter present the SUNDomEigEst modules provided with SUNDIALS.

doc/shared/sundomeigest/SUNDomEigEst_PI.rst

@@ -41,13 +41,7 @@ can be approximated using the Rayleigh quotient
     \lambda_k = \frac{\mathbf{v}_k^T A \mathbf{v}_k}{\|\mathbf{v}_k\|^2}.
 
 The iteration continues until the two successive eigenvalue approximations are
-relatively close enough to one another.  That is, for some relative tolerance
-:math:`\tau`,
-enough to one another.  That is, for some relative tolerance :math:`\tau`,
-
-.. math::
-
-    \frac{\left|\lambda_k - \lambda_{k-1}\right|}{\left|\lambda_k \right|} < \tau.
+relatively close enough to one another.  That is, for some :ref:`relative tolerance <pi_rel_tol>`.
 
 PI works for the matrices that have a **real** dominant eigenvalue.  If it is strictly
 greater than all others (in magnitude), convergence is guaranteed.  The speed of convergence
@@ -167,7 +161,7 @@ This estimator is constructed to perform the following operations:
   function pointer and the related data ``ATData``.
 
 * In the "initialize" call, the estimator parameters are checked
-  for validity and PI estimator memory is allocated.
+  for validity and the initial eigenvector is normalized.
 
 * In the "preprocess" call, the initial vector :math:`q_0` is warmed up
   :math:`k=` ``numwarmups`` times as
@@ -208,4 +202,4 @@ eigenvalue estimator operations listed in
 
 * ``SUNDomEigEst_PrintStats_PI``
 
-* ``SUNDomEigEstFree_PI``
+* ``SUNDomEigEst_Destroy_PI``

examples/arkode/CXX_serial/ark_heat2D_lsrk_internal_domeig.cpp

@@ -451,12 +451,12 @@ int main(int argc, char* argv[])
   // Clean up and return
   // --------------------
 
-  ARKodeFree(&arkode_mem); // Free integrator memory
-  N_VDestroy(u);           // Free vectors
-  SUNDomEigEstFree(DEE);   /* Free DEE object */
-  FreeUserData(udata);     // Free user data
+  ARKodeFree(&arkode_mem);   // Free integrator memory
+  N_VDestroy(u);             // Free vectors
+  SUNDomEigEst_Destroy(&DEE); /* Free DEE object */
+  FreeUserData(udata);       // Free user data
   delete udata;
-  SUNContext_Free(&ctx); // Free context
+  SUNContext_Free(&ctx);     // Free context
 
   return 0;
 }

examples/arkode/C_serial/ark_analytic_lsrk_internal_domeig.c

@@ -277,10 +277,10 @@ int main(void)
   flag = compute_error(y, t);
 
   /* Clean up and return */
-  N_VDestroy(y);           /* Free y vector */
-  ARKodeFree(&arkode_mem); /* Free integrator memory */
-  SUNDomEigEstFree(DEE);   /* Free DEE object */
-  SUNContext_Free(&ctx);   /* Free context */
+  N_VDestroy(y);              /* Free y vector */
+  ARKodeFree(&arkode_mem);    /* Free integrator memory */
+  SUNDomEigEst_Destroy(&DEE); /* Free DEE object */
+  SUNContext_Free(&ctx);      /* Free context */
 
   return flag;
 }

include/sundials/sundials_domeigestimator.h

@@ -17,7 +17,6 @@
 #ifndef _SUNDOMEIGEST_H
 #define _SUNDOMEIGEST_H
 
-/* TODO: Check to see if they are all required */
 #include <sundials/priv/sundials_errors_impl.h>
 #include <sundials/sundials_config.h>
 #include <sundials/sundials_context.h>
@@ -70,7 +69,7 @@ struct _generic_SUNDomEigEstimator_Ops
   SUNErrCode (*getminniters)(SUNDomEigEstimator, int*);
   SUNErrCode (*getnumatimescalls)(SUNDomEigEstimator, long int*);
   SUNErrCode (*printstats)(SUNDomEigEstimator, FILE*);
-  SUNErrCode (*free)(SUNDomEigEstimator);
+  SUNErrCode (*free)(SUNDomEigEstimator*);
 };
 
 /* An estimator is a structure with an implementation-dependent
@@ -140,7 +139,7 @@ SUNDIALS_EXPORT
 SUNErrCode SUNDomEigEst_PrintStats(SUNDomEigEstimator DEE, FILE* outfile);
 
 SUNDIALS_EXPORT
-SUNErrCode SUNDomEigEstFree(SUNDomEigEstimator DEE);
+SUNErrCode SUNDomEigEst_Destroy(SUNDomEigEstimator* DEEptr);
 
 #ifdef __cplusplus
 }

include/sundomeigest/sundomeigest_arni.h

@@ -92,7 +92,7 @@ SUNDIALS_EXPORT
 SUNErrCode SUNDomEigEst_PrintStats_ArnI(SUNDomEigEstimator DEE, FILE* outfile);
 
 SUNDIALS_EXPORT
-SUNErrCode SUNDomEigEstFree_ArnI(SUNDomEigEstimator DEE);
+SUNErrCode SUNDomEigEst_Destroy_ArnI(SUNDomEigEstimator* DEEptr);
 
 #ifdef __cplusplus
 }