Command-line control over scalar-valued set routines (#662)

Add functions to set options from command line args

---------

Co-authored-by: Steven Roberts <roberts115@llnl.gov>
Co-authored-by: David J. Gardner <gardner48@llnl.gov>

Author: 3 people

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

@@ -1255,6 +1255,8 @@ Set additive RK tables via their names    :c:func:`ARKStepSetTableName()`    int
       pointers *fe* or *fi* passed to :c:func:`ARKStepCreate` are
       ``NULL``, but may be set directly by the user if desired.
 
+      This routine will be called by :c:func:`ARKodeSetOptions`
+      when using the key "arkid.imex".
 
 
 .. c:function:: int ARKStepSetExplicit(void* arkode_mem)
@@ -1279,6 +1281,8 @@ Set additive RK tables via their names    :c:func:`ARKStepSetTableName()`    int
       f(t,y)`, then we recommend that the ERKStep time-stepper module be
       used instead.
 
+      This routine will be called by :c:func:`ARKodeSetOptions`
+      when using the key "arkid.explicit".
 
 .. c:function:: int ARKStepSetImplicit(void* arkode_mem)
 
@@ -1298,6 +1302,9 @@ Set additive RK tables via their names    :c:func:`ARKStepSetTableName()`    int
       passed to :c:func:`ARKStepCreate` is ``NULL``, but may be set
       directly by the user if desired.
 
+      This routine will be called by :c:func:`ARKodeSetOptions`
+      when using the key "arkid.implicit".
+
 
 
 .. c:function:: int ARKStepSetTables(void* arkode_mem, int q, int p, ARKodeButcherTable Bi, ARKodeButcherTable Be)
@@ -1437,6 +1444,10 @@ Set additive RK tables via their names    :c:func:`ARKStepSetTableName()`    int
       In all cases, error-checking is performed to ensure that the tables
       exist.
 
+      This routine will be called by :c:func:`ARKodeSetOptions`
+      when using the key "arkid.table_names".
+
+
    **Warning:**
       This should not be used with :c:func:`ARKodeSetOrder`.
 
@@ -1623,7 +1634,7 @@ Optional inputs for time step adaptivity
    .. deprecated:: 5.7.0
 
       Use the SUNAdaptController infrastructure instead (see :numref:`SUNAdaptController.Description`).
-      
+
    .. versionchanged:: 6.3.0
 
       The default value was changed from 1.5 to 1.0
@@ -1649,7 +1660,7 @@ Optional inputs for time step adaptivity
    .. deprecated:: 6.1.0
 
       Use :c:func:`ARKodeSetFixedStepBounds` instead.
-      
+
    .. versionchanged:: 6.3.0
 
       The default upper bound was changed from 1.5 to 1.0
@@ -1793,7 +1804,7 @@ Optional inputs for time step adaptivity
    .. deprecated:: 6.1.0
 
       Use :c:func:`ARKodeSetSafetyFactor` instead.
-      
+
    .. versionchanged:: 6.3.0
 
       The default default was changed from 0.96 to 0.9. The maximum value is now

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

@@ -934,7 +934,10 @@ Optional inputs for IVP method selection
    **Warning:**
       This should not be used with :c:func:`ARKodeSetOrder`.
 
+   .. note::
 
+      This routine will be called by :c:func:`ARKodeSetOptions`
+      when using the key "arkid.table_name".
 
 
 .. _ARKODE.Usage.ERKStep.ERKStepAdaptivityInput:
@@ -1122,7 +1125,7 @@ the code, is provided in :numref:`ARKODE.Mathematics.Adaptivity`.
    .. deprecated:: 5.7.0
 
       Use the SUNAdaptController infrastructure instead (see :numref:`SUNAdaptController.Description`).
-      
+
    .. versionchanged:: 6.3.0
 
       The default value was changed from 1.5 to 1.0
@@ -1149,7 +1152,7 @@ the code, is provided in :numref:`ARKODE.Mathematics.Adaptivity`.
    .. deprecated:: 6.1.0
 
       Use :c:func:`ARKodeSetFixedStepBounds` instead.
-      
+
    .. versionchanged:: 6.3.0
 
       The default upper bound was changed from 1.5 to 1.0
@@ -1274,7 +1277,7 @@ the code, is provided in :numref:`ARKODE.Mathematics.Adaptivity`.
    .. deprecated:: 6.1.0
 
       Use :c:func:`ARKodeSetSafetyFactor` instead.
-      
+
    .. versionchanged:: 6.3.0
 
       The default default was changed from 0.96 to 0.9. The maximum value is now

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

@@ -156,6 +156,10 @@ Allowable Method Families
       * *ARK_SUCCESS* if successful
       * *ARK_ILL_INPUT* if an argument had an illegal value (e.g. typo in the method name).
 
+   .. note::
+
+      This routine will be called by :c:func:`ARKodeSetOptions`
+      when using the key "arkid.sts_method_name".
 
 .. c:function:: int LSRKStepSetSSPMethodByName(void* arkode_mem, const char* emethod);
 
@@ -171,6 +175,10 @@ Allowable Method Families
       * *ARK_SUCCESS* if successful
       * *ARK_ILL_INPUT* if an argument had an illegal value (e.g. typo in the method name).
 
+   .. note::
+
+      This routine will be called by :c:func:`ARKodeSetOptions`
+      when using the key "arkid.ssp_method_name".
 
 .. c:function:: int LSRKStepSetDomEigFn(void* arkode_mem, ARKDomEigFn dom_eig);
 
@@ -187,7 +195,9 @@ Allowable Method Families
       * *ARKLS_MEM_NULL* if ``arkode_mem`` was ``NULL``.
       * *ARK_ILL_INPUT* ``dom_eig = NULL`` and LSRKStep does not currently estimate this internally.
 
-   .. note:: This function is currently required when either the RKC or RKL methods are used.
+   .. note::
+
+      This function is currently required when either the RKC or RKL methods are used.
 
 
 .. c:function:: int LSRKStepSetDomEigFrequency(void* arkode_mem, long int nsteps);
@@ -203,9 +213,16 @@ Allowable Method Families
       * *ARK_SUCCESS* if successful
       * *ARKLS_MEM_NULL* if ``arkode_mem`` was ``NULL``.
 
-.. note:: If LSRKStepSetDomEigFrequency routine is not called, then the default ``nsteps`` is set to :math:`25` as recommended in :cite:p:`VSH:04`.
-   Calling this function with ``nsteps < 0`` resets the default value while ``nsteps = 0`` refers to constant dominant eigenvalue.
+   .. note::
+
+      If LSRKStepSetDomEigFrequency routine is not called, then the default ``nsteps``
+      is set to :math:`25` as recommended in :cite:p:`VSH:04`.
+
+      Calling this function with ``nsteps < 0`` resets the default value while
+      ``nsteps = 0`` refers to constant dominant eigenvalue.
 
+      This routine will be called by :c:func:`ARKodeSetOptions`
+      when using the key "arkid.dom_eig_frequency".
 
 .. c:function:: int LSRKStepSetMaxNumStages(void* arkode_mem, int stage_max_limit);
 
@@ -220,10 +237,18 @@ Allowable Method Families
       * *ARK_SUCCESS* if successful
       * *ARKLS_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.
-   This limit should be chosen with consideration of the following proportionality: :math:`s^2 \sim - h\lambda`,
-   where :math:`s` is the number of stages used, :math:`h` is the current step size and :math:`\lambda` is the dominant eigenvalue.
+   .. 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.
+
+      This limit should be chosen with consideration of the following proportionality:
+      :math:`s^2 \sim - h\lambda`,  where :math:`s` is the number of stages used, :math:`h`
+      is the current step size and :math:`\lambda` is the dominant eigenvalue.
+
+      This routine will be called by :c:func:`ARKodeSetOptions`
+      when using the key "arkid.max_num_stages".
 
 
 .. c:function:: int LSRKStepSetDomEigSafetyFactor(void* arkode_mem, sunrealtype dom_eig_safety);
@@ -241,8 +266,14 @@ Allowable Method Families
       * *ARK_SUCCESS* if successful
       * *ARKLS_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.
+   .. 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.
+
+      This routine will be called by :c:func:`ARKodeSetOptions`
+      when using the key "arkid.dom_eig_safety_factor".
 
 
 .. c:function:: int LSRKStepSetNumSSPStages(void* arkode_mem, int num_of_stages);
@@ -262,12 +293,17 @@ Allowable Method Families
       * *ARKLS_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
-   set. Calling this function with ``num_of_stages <= 0`` resets the default values:
+   .. note::
+
+      If LSRKStepSetNumSSPStages routine is not called, then the default ``num_of_stages``
+      is set. Calling this function with ``num_of_stages <= 0`` resets the default values:
+
+      * ``num_of_stages = 10`` for :c:enumerator:`ARKODE_LSRK_SSP_S_2`
+      * ``num_of_stages = 9`` for :c:enumerator:`ARKODE_LSRK_SSP_S_3`
+      * ``num_of_stages = 10`` for :c:enumerator:`ARKODE_LSRK_SSP_10_4`
 
-   * ``num_of_stages = 10`` for :c:enumerator:`ARKODE_LSRK_SSP_S_2`
-   * ``num_of_stages = 9`` for :c:enumerator:`ARKODE_LSRK_SSP_S_3`
-   * ``num_of_stages = 10`` for :c:enumerator:`ARKODE_LSRK_SSP_10_4`
+      This routine will be called by :c:func:`ARKodeSetOptions`
+      when using the key "arkid.num_ssp_stages".
 
 .. _ARKODE.Usage.LSRKStep.OptionalOutputs:
 
@@ -359,6 +395,7 @@ dependent variable vector.
       * *ARK_ILL_INPUT* if an argument had an illegal value.
 
    .. note::
+
       All previously set options are retained but may be updated by calling
       the appropriate "Set" functions.
 
@@ -386,6 +423,7 @@ dependent variable vector.
       * *ARK_ILL_INPUT* if an argument had an illegal value.
 
    .. note::
+
       All previously set options are retained but may be updated by calling
       the appropriate "Set" functions.
 

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

@@ -800,6 +800,11 @@ Optional inputs for IVP method selection
       For a description of the :c:type:`MRIStepCoupling` type and related
       functions for creating Butcher tables see :numref:`ARKODE.Usage.MRIStep.MRIStepCoupling`.
 
+      This routine will be called by :c:func:`ARKodeSetOptions`
+      when using the key "arkid.coupling_table_name", where ``C``
+      is itself constructed by passing the command-line option to
+      :c:func:`MRIStepCoupling_LoadTableByName`.
+
    .. warning::
 
       This should not be used with :c:func:`ARKodeSetOrder`.

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

@@ -479,6 +479,11 @@ Optional inputs for IVP method selection
    :retval ARK_MEM_NULL: if the SPRKStep memory is ``NULL``
    :retval ARK_ILL_INPUT: if an argument had an illegal value
 
+   .. note::
+
+      This routine will be called by :c:func:`ARKodeSetOptions`
+      when using the key "arkid.method_name".
+
    .. warning::
 
       This should not be used with :c:func:`ARKodeSetOrder`.
@@ -506,7 +511,6 @@ Optional inputs for IVP method selection
       Use :c:func:`ARKodeSetUseCompensatedSums` instead.
 
 
-
 .. _ARKODE.Usage.SPRKStep.SPRKStepRootfindingInput:
 
 

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

@@ -82,7 +82,7 @@ SplittingStep initialization functions
    **Example codes:**
       * ``examples/arkode/C_serial/ark_advection_diffusion_reaction_splitting.c``
       * ``examples/arkode/C_serial/ark_analytic_partitioned.c``
-   
+
    .. versionadded:: 6.2.0
 
 
@@ -106,10 +106,15 @@ Optional inputs for IVP method selection
       related functions for creating splitting coefficients see
       :numref:`ARKODE.Usage.SplittingStep.SplittingStepCoefficients`.
 
+      This routine will be called by :c:func:`ARKodeSetOptions`
+      when using the key "arkid.coefficients_name", where ``coefficients``
+      is itself constructed by passing the command-line option to
+      :c:func:`SplittingStepCoefficients_LoadCoefficientsByName`.
+
    .. warning::
 
       This should not be used with :c:func:`ARKodeSetOrder`.
-   
+
    .. versionadded:: 6.2.0
 
 
@@ -133,7 +138,7 @@ Optional output functions
    :retval ARK_SUCCESS: if successful
    :retval ARK_MEM_NULL: if the SplittingStep memory was ``NULL``
    :retval ARK_ILL_INPUT: if *partition* was out of bounds
-   
+
    .. versionadded:: 6.2.0
 
 
@@ -208,5 +213,5 @@ the ODE and the :c:type:`SUNStepper` objects used to evolve each partition.
       will be reset since they are no longer compatible. Otherwise, all
       previously set options are retained but may be updated by calling the
       appropriate "Set" functions.
-   
+
    .. versionadded:: 6.2.0