From b9596c6b55716596405c33dbcf975c2be33249a0 Mon Sep 17 00:00:00 2001 From: Rob Falgout Date: Tue, 20 Dec 2022 13:14:57 -0800 Subject: [PATCH] Updating User Manual to point to the API chapter instead of Reference Manual (#802) --- src/docs/usr-manual/ch-ij.rst | 4 ++-- src/docs/usr-manual/ch-intro.rst | 23 ++++++++++++----------- src/docs/usr-manual/ch-solvers.rst | 6 +++--- src/docs/usr-manual/ch-struct.rst | 2 +- 4 files changed, 18 insertions(+), 17 deletions(-) diff --git a/src/docs/usr-manual/ch-ij.rst b/src/docs/usr-manual/ch-ij.rst index 279bb4e8c..8a1ecd4c4 100644 --- a/src/docs/usr-manual/ch-ij.rst +++ b/src/docs/usr-manual/ch-ij.rst @@ -77,7 +77,7 @@ contiguous, i.e., ``iupper`` for process ``i`` must equal ``ilower``:math:`-1` for process ``i``:math:`+1`. Note that this allows matrices to have 0- or 1-based indexing. The parameters ``jlower`` and ``jupper`` define a column partitioning, and should match ``ilower`` and ``iupper`` when solving square -linear systems. See the Reference Manual for more information. +linear systems. See Chapter :ref:`ch-API` for more information. The ``SetObjectType()`` routine sets the underlying matrix object type to ``HYPRE_PARCSR`` (this is the only object type currently supported). The @@ -85,7 +85,7 @@ The ``SetObjectType()`` routine sets the underlying matrix object type to ready to be set. This routine may or may not involve the allocation of memory for the coefficient data, depending on the implementation. The optional ``SetRowSizes()`` and ``SetDiagOffdSizes()`` routines mentioned later in this -chapter and in the Reference Manual, should be called before this step. +chapter and in Chapter :ref:`ch-API`, should be called before this step. The ``SetValues()`` routine sets matrix values for some number of rows (``nrows``) and some number of columns in each row (``ncols``). The actual row diff --git a/src/docs/usr-manual/ch-intro.rst b/src/docs/usr-manual/ch-intro.rst index a4687975e..30c0619e1 100644 --- a/src/docs/usr-manual/ch-intro.rst +++ b/src/docs/usr-manual/ch-intro.rst @@ -83,15 +83,16 @@ Getting More Information ============================================================================== This user's manual consists of chapters describing each conceptual interface, a -chapter detailing the various linear solver options available, and detailed -installation information. In addition to this manual, a number of other -information sources for hypre are available. +chapter detailing the various linear solver options available, detailed +installation information, and the API reference. In addition to this manual, a +number of other information sources for hypre are available. -* **Reference Manual:** The reference manual comprehensively lists all of the - interface and solver functions available in hypre. The reference manual is - ideal for determining the various options available for a particular solver or - for viewing the functions provided to describe a problem for a particular - interface. +* **Reference Manual:** This is equivalent to Chapter :ref:`ch-API` in this user + manual, but it can also be built as a separate document. The reference manual + comprehensively lists all of the interface and solver functions available in + hypre. It is ideal for determining the various options available for a + particular solver or for viewing the functions provided to describe a problem + for a particular interface. * **Example Problems:** A suite of example problems is provided with the hypre installation. These examples reside in the ``examples`` subdirectory and @@ -213,7 +214,7 @@ algorithm (GMG) listed in the left-most box, for example, can only be used with the left-most conceptual interface. On the other hand, the ILU algorithm in the right-most box may be used with any conceptual interface. Matrix requirements for each solver and preconditioner are provided in Chapter :ref:`ch-Solvers` and -in the hypre Reference Manual. Your desired solver strategy may influence your +in Chapter :ref:`ch-API`. Your desired solver strategy may influence your choice of conceptual interface. A typical user will select a single Krylov method and a single preconditioner to solve their system. @@ -266,7 +267,7 @@ demonstrate the following general structure of the application calls to hypre: The subsequent chapters of this User's Manual provide the details needed to more fully understand the function of each conceptual interface and each solver. -Remember that a comprehensive list of all available functions is provided in the -hypre Reference Manual, and the provided example codes may prove helpful as +Remember that a comprehensive list of all available functions is provided in +Chapter :ref:`ch-API`, and the provided example codes may prove helpful as templates for your specific application. diff --git a/src/docs/usr-manual/ch-solvers.rst b/src/docs/usr-manual/ch-solvers.rst index 927a8d00a..7471591a8 100644 --- a/src/docs/usr-manual/ch-solvers.rst +++ b/src/docs/usr-manual/ch-solvers.rst @@ -76,8 +76,8 @@ side. We comment later on considerations for other usage patterns. parameters depend on the problem to be solved. We give recommendations in the individual sections on how to choose these parameters. Note that in hypre, convergence criteria can be chosen after the preconditioner/solver has been - setup. For a complete set of all available parameters see the Reference - Manual. + setup. For a complete set of all available parameters see Chapter + :ref:`ch-API`. #. **Pass the preconditioner to the solver.** For solvers that are not preconditioned, this step is omitted. The preconditioner is passed through @@ -137,7 +137,7 @@ In the following sections, we will give brief descriptions of the available hypre solvers with some suggestions on how to choose the parameters as well as references for users who are interested in a more detailed description and analysis of the solvers. A complete list of all routines that are available can -be found in the reference manual. +be found in Chapter :ref:`ch-API`. .. toctree:: diff --git a/src/docs/usr-manual/ch-struct.rst b/src/docs/usr-manual/ch-struct.rst index adc091eda..d978fb0da 100644 --- a/src/docs/usr-manual/ch-struct.rst +++ b/src/docs/usr-manual/ch-struct.rst @@ -269,7 +269,7 @@ The ``Create()`` routine creates an empty matrix object. The ``Initialize()`` routine indicates that the matrix coefficients (or values) are ready to be set. This routine may or may not involve the allocation of memory for the coefficient data, depending on the implementation. The optional ``Set`` routines mentioned -later in this chapter and in the Reference Manual, should be called before this +later in this chapter and in Chapter :ref:`ch-API`, should be called before this step. The ``SetBoxValues()`` routine sets the matrix coefficients for some set of stencil entries over the gridpoints in some box. Note that the box need not correspond to any of the boxes used to create the grid, but values should be set