Fixed documentation

PrincetonUniversity · Oct 10, 2024 · 0cef356 · 0cef356
1 parent 6190048
commit 0cef356
Show file tree

Hide file tree

Showing 34 changed files with 60 additions and 67 deletions.
diff --git a/docs/api/assembly/index.rst b/docs/api/assembly/index.rst
@@ -19,7 +19,7 @@ Finite Element Assembly
     2. Receivers
     3. Coupled interfaces
 
-    If you'd like to work on this, please see `issue tracker <https://github.com/PrincetonUniversity/SPECFEMPP/issues/110>_` for more details.
+    If you'd like to work on this, please see `issue tracker <https://github.com/PrincetonUniversity/SPECFEMPP/issues/110>`_ for more details.
 
 .. toctree::
     :maxdepth: 1

diff --git a/docs/api/datatypes/index.rst b/docs/api/datatypes/index.rst
@@ -12,7 +12,7 @@ SPECFEM++ datatypes
     1. Edge element (datatype for storing values at quadrature points on a 1D edge)
     2. Chunk edge element (datatype for storing values at quadrature points on a chunk of 1D edges)
 
-    If you'd like to work on this, please see `issue tracker <https://github.com/PrincetonUniversity/SPECFEMPP/issues/111>_` for more details.
+    If you'd like to work on this, please see `issue tracker <https://github.com/PrincetonUniversity/SPECFEMPP/issues/111>`_ for more details.
 
 .. toctree::
     :maxdepth: 1

diff --git a/docs/api/policies/chunk_element/iterator.rst b/docs/api/policies/chunk_element/iterator.rst
@@ -6,13 +6,13 @@ Chunk Element Iterator
 
 Chunk element iterator to generate indices for quadrature points defined by :ref:`policy_chunk_element` policy.
 
-.. doxygenstruct:: specfem::iterator::chunk
+.. doxygenclass:: specfem::iterator::chunk
     :members:
 
 Implementation details
 ----------------------
 
-.. doxygenstruct:: specfem::iterator::impl::chunk< ViewType, specfem::dimension::type::dim2, SIMD>
+.. doxygenclass:: specfem::iterator::chunk< ViewType, specfem::dimension::type::dim2, SIMD>
     :members:
 
 .. _iterator_chunk_element_index:
@@ -22,14 +22,14 @@ Chunk element index types
 
 Index types generated by the chunk element iterator.
 
-.. doxygenstruct:: specfem::iterator::impl::chunk_index_type
+.. doxygenclass:: specfem::iterator::impl::chunk_index_type
     :members:
 
 Implementation details
 ----------------------
 
-.. doxygenstruct:: specfem::iterator::impl::chunk_index_type< true, DimensionType >
+.. doxygenclass:: specfem::iterator::impl::chunk_index_type< true, DimensionType >
     :members:
 
-.. doxygenstruct:: specfem::iterator::impl::chunk_index_type< false, DimensionType >
+.. doxygenclass:: specfem::iterator::impl::chunk_index_type< false, DimensionType >
     :members:
diff --git a/docs/api/policies/chunk_element/policy.rst b/docs/api/policies/chunk_element/policy.rst
@@ -6,5 +6,5 @@ Chunk Element Policy
 
 Policy to chunk a range of elements into chunks assigned to Kokkos teams and iterate over quadrature points within each chunk.
 
-.. doxygenstruct:: specfem::policy::chunk_element
+.. doxygenclass:: specfem::policy::element_chunk
     :members:
diff --git a/docs/api/policies/edge/iterator.rst b/docs/api/policies/edge/iterator.rst
@@ -6,13 +6,13 @@ Edge Iterator
 
 Edge iterator to generate indices for quadrature points defined by :ref:`policy_edge` policy.
 
-.. doxygenstruct:: specfem::iterator::edge
+.. doxygenclass:: specfem::iterator::edge
     :members:
 
 Implementation details
 ----------------------
 
-.. doxygenstruct:: specfem::iterator::edge< specfem::dimension::type::dim2 >
+.. doxygenclass:: specfem::iterator::edge< specfem::dimension::type::dim2 >
     :members:
 
 .. _iterator_edge_index:
@@ -22,5 +22,5 @@ Edge index types
 
 Index types generated by the edge iterator.
 
-.. doxygenstruct:: specfem::iterator::impl::edge_index_type
+.. doxygenclass:: specfem::iterator::impl::edge_index_type
     :members:
diff --git a/docs/api/policies/edge/policy.rst b/docs/api/policies/edge/policy.rst
@@ -6,5 +6,5 @@ Edge Policy
 
 Policy to iterator over shared edges between elements in a mesh.
 
-.. doxygenstruct:: specfem::policy::edge
+.. doxygenclass:: specfem::policy::element_edge
     :members:
diff --git a/docs/api/setup_parameters/database_configuration.rst b/docs/api/setup_parameters/database_configuration.rst
@@ -6,5 +6,3 @@ Methods to parse database information from configuration file.
 
 .. doxygenclass:: specfem::runtime_configuration::database_configuration
     :members:
-    :undoc-members:
-    :private-members:
diff --git a/docs/api/setup_parameters/header.rst b/docs/api/setup_parameters/header.rst
@@ -6,5 +6,3 @@ Methods to read header information from configuration file.
 
 .. doxygenclass:: specfem::runtime_configuration::header
     :members:
-    :undoc-members:
-    :private-members:
diff --git a/docs/api/setup_parameters/quadrature.rst b/docs/api/setup_parameters/quadrature.rst
@@ -6,5 +6,3 @@ Methods to read quadrature information from configuration file and instantiate q
 
 .. doxygenclass:: specfem::runtime_configuration::quadrature
     :members:
-    :undoc-members:
-    :private-members:
diff --git a/docs/api/setup_parameters/receivers.rst b/docs/api/setup_parameters/receivers.rst
@@ -6,5 +6,3 @@ Methods to parse receiver information from the configuration file.
 
 .. doxygenclass:: specfem::runtime_configuration::receivers
     :members:
-    :undoc-members:
-    :private-members:
diff --git a/docs/api/setup_parameters/run_setup.rst b/docs/api/setup_parameters/run_setup.rst
@@ -6,5 +6,3 @@ Methods to parse runtime setup node from configuration file.
 
 .. doxygenclass:: specfem::runtime_configuration::run_setup
     :members:
-    :undoc-members:
-    :private-members:
diff --git a/docs/api/setup_parameters/seismogram.rst b/docs/api/setup_parameters/seismogram.rst
@@ -6,5 +6,3 @@ Methods to parse seismogram information from runtime configuration.
 
 .. doxygenclass:: specfem::runtime_configuration::seismogram
     :members:
-    :undoc-members:
-    :private-members:
diff --git a/docs/api/setup_parameters/setup.rst b/docs/api/setup_parameters/setup.rst
@@ -6,5 +6,3 @@ The ``setup`` class serves as the primary driver to parse the configuration file
 
 .. doxygenclass:: specfem::runtime_configuration::setup
    :members:
-   :undoc-members:
-   :private-members:
diff --git a/docs/api/setup_parameters/solver/index.rst b/docs/api/setup_parameters/solver/index.rst
@@ -6,13 +6,3 @@ Methods to read solver information from the configuration file and instantiate a
 
 .. doxygenclass:: specfem::runtime_configuration::solver:solver
     :members:
-    :undoc-members:
-    :private-members:
-
-Types of solvers
-----------------
-
-.. toctree::
-    :maxdepth: 1
-
-    time_marching
diff --git a/docs/api/setup_parameters/solver/time_marching.rst b/docs/api/setup_parameters/solver/time_marching.rst
diff --git a/docs/api/solver/time_marching.rst b/docs/api/solver/time_marching.rst
@@ -12,8 +12,8 @@ Time marching explicit solver
 Implementation Details
 ----------------------
 
-.. doxygenclass:: specfem::solver::time_marching< specfem::simulation::type::forward >
+.. doxygenclass:: specfem::solver::time_marching< specfem::simulation::type::forward, DimensionType, qp_type >
     :members:
 
-.. doxygenclass:: specfem::solver::time_marching< specfem::simulation::type::combined >
+.. doxygenclass:: specfem::solver::time_marching< specfem::simulation::type::combined, DimensionType, qp_type >
     :members:
diff --git a/docs/api/timescheme/index.rst b/docs/api/timescheme/index.rst
@@ -8,8 +8,6 @@ The ``TimeScheme`` class provides methods to compute the time evolution of a wav
 
 .. doxygenclass:: specfem::time_scheme::time_scheme
    :members:
-   :undoc-members:
-   :private-members:
 
 Types of Time Schemes
 ---------------------

diff --git a/docs/cookbooks/example_01.rst b/docs/cookbooks/example_01.rst
@@ -3,7 +3,7 @@
 Wave propagration through homogeneous media
 ===========================================
 
-In this `example <https://github.com/PrincetonUniversity/SPECFEMPP/tree/main/examples/homogeneous-medium-flat-topography>_` we simulate wave propagation through a 2-dimensional homogeneous medium.
+In this `example <https://github.com/PrincetonUniversity/SPECFEMPP/tree/main/examples/homogeneous-medium-flat-topography>`_ we simulate wave propagation through a 2-dimensional homogeneous medium.
 
 Generating a mesh
 -----------------

diff --git a/docs/cookbooks/example_02.rst b/docs/cookbooks/example_02.rst
@@ -1,7 +1,7 @@
 Wave propagration through fluid-solid interface
 ===============================================
 
-This `example <https://github.com/PrincetonUniversity/SPECFEMPP/tree/main/examples/fluid-solid-interface>_` simulates the fluid-solid example with flat ocean bottom from `Komatitsch et. al. <https://doi.org/10.1190/1.1444758>`_. This example demonstrates the use of the ``xmeshfem2D`` mesher to generate interface between 2 conforming material systems and the setting up absorbing boundary conditions.
+This `example <https://github.com/PrincetonUniversity/SPECFEMPP/tree/main/examples/fluid-solid-interface>`_ simulates the fluid-solid example with flat ocean bottom from `Komatitsch et. al. <https://doi.org/10.1190/1.1444758>`_. This example demonstrates the use of the ``xmeshfem2D`` mesher to generate interface between 2 conforming material systems and the setting up absorbing boundary conditions.
 
 Meshing the domain
 ------------------

diff --git a/docs/cookbooks/example_03.rst b/docs/cookbooks/example_03.rst
@@ -3,7 +3,7 @@
 Adjoint Simulations and Banana Donut Kernels
 ============================================
 
-This `example <https://github.com/PrincetonUniversity/SPECFEMPP/tree/main/examples/Tromp_2005>_` demonstrates how to setup forward and adjoint simulations to compute the banana donut kernels. We will reproduce the results from Fig 9 of `Tromp et al. 2005 <https://doi.org/10.1111/j.1365-246X.2004.02453.x>`_.
+This `example <https://github.com/PrincetonUniversity/SPECFEMPP/tree/main/examples/Tromp_2005>`_ demonstrates how to setup forward and adjoint simulations to compute the banana donut kernels. We will reproduce the results from Fig 9 of `Tromp et al. 2005 <https://doi.org/10.1111/j.1365-246X.2004.02453.x>`_.
 
 Setting up the forward simulation
 ---------------------------------

diff --git a/docs/cookbooks/index.rst b/docs/cookbooks/index.rst
@@ -3,7 +3,7 @@
 Cookbooks
 =========
 
-Cookbooks are a collection of examples that demonstrate how to use the package to solve various problems. Each of the cookbook is present with the `example <https://github.com/PrincetonUniversity/SPECFEMPP/tree/main/examples>_` directory in the repository.
+Cookbooks are a collection of examples that demonstrate how to use the package to solve various problems. Each of the cookbook is present with the `example <https://github.com/PrincetonUniversity/SPECFEMPP/tree/main/examples>`_ directory in the repository.
 
 .. note::
 

diff --git a/docs/developer_documentation/tutorials/tutorial1/Chapter1/gridfile.png b/docs/developer_documentation/tutorials/tutorial1/Chapter1/gridfile.png
diff --git a/docs/developer_documentation/tutorials/tutorial1/Chapter1/index.rst b/docs/developer_documentation/tutorials/tutorial1/Chapter1/index.rst
@@ -192,6 +192,6 @@ Now that we have the mesh and receiver locations, we can define the sources. We
 Final mesh
 ----------
 
-.. image:: gridfile.ps
-    :alt: gridfile.ps
+.. image:: gridfile.png
+    :alt: gridfile.png
     :align: center
diff --git a/docs/developer_documentation/tutorials/tutorial1/Chapter4/index.rst b/docs/developer_documentation/tutorials/tutorial1/Chapter4/index.rst
@@ -96,14 +96,14 @@ Data Containers and Access Functions in SPECFEM++
     2. Receivers
     3. Coupled interfaces
 
-    If you'd like to work on this, please see `issue tracker <https://github.com/PrincetonUniversity/SPECFEMPP/issues/110>_` for more details.
+    If you'd like to work on this, please see `issue tracker <https://github.com/PrincetonUniversity/SPECFEMPP/issues/110>`_ for more details.
 
 1. :ref:`Assembled mesh information <assembly_mesh>`
 2. :ref:`Partial derivatives <assembly_partial_derivatives>`
 3. :ref:`Material properties <assembly_properties>`
 4. :ref:`Wavefield <assembly_fields>`
 5. :ref:`Misfit Kernels <assembly_kernels>`
 6. :ref:`Coupled Interfaces <assembly_coupled_interfaces>`
-8. :ref:`Boundary Conditions <assembly_boundary>`
-9. :ref:`Source Information <assembly_sources>`
-10. :ref:`Receiver Information <assembly_receivers>`
+7. :ref:`Boundary Conditions <assembly_boundary>`
+8. :ref:`Source Information <assembly_sources>`
+9. :ref:`Receiver Information <assembly_receivers>`
diff --git a/docs/developer_documentation/tutorials/tutorial1/Chapter5/index.rst b/docs/developer_documentation/tutorials/tutorial1/Chapter5/index.rst
@@ -29,7 +29,7 @@ We begin with defining elementary datatype. Since SPECFEM++ is an extension of a
     1. Edge element (datatype for storing values at quadrature points on a 1D edge)
     2. Chunk edge element (datatype for storing values at quadrature points on a chunk of 1D edges)
 
-    If you'd like to work on this, please see `issue tracker <https://github.com/PrincetonUniversity/SPECFEMPP/issues/111>_` for more details.
+    If you'd like to work on this, please see `issue tracker <https://github.com/PrincetonUniversity/SPECFEMPP/issues/111>`_ for more details.
 
 1. :ref:`Point datatype <datatype_base_point>`
 2. :ref:`Element datatype <datatype_base_element>`

diff --git a/docs/developer_documentation/tutorials/tutorial1/Chapter9/index.rst b/docs/developer_documentation/tutorials/tutorial1/Chapter9/index.rst
@@ -38,13 +38,11 @@ The time-scheme is divided into 2 phases: 1. Predictor phase and 2. Corrector ph
 .. math::
 
     \begin{align*}
-
     u^{n+1} &= u^n + \Delta t v^n + \frac{1}{2} \Delta t^2 a^n
 
     v^{n+1} &= v^n + \frac{1}{2} \Delta t a^n
 
     M u^{n+1} + C v^{n+1} + K u^{n+1} &= F^{n+1}
-
     \end{align*}
 
 Here, the 3rd equation is the discretized form of the equation of motion solved by the spectral element method. The corrector phase is given by:

diff --git a/docs/developer_documentation/tutorials/tutorial2/Chapter1/index.rst b/docs/developer_documentation/tutorials/tutorial2/Chapter1/index.rst
@@ -1,8 +1,8 @@
 
 .. _tutorial2_Chapter1:
 
-Understanding stored fields
-===========================
+Chapter1 : Understanding stored fields
+======================================
 
 Let's start by understanding how the fields are stored in SPECFEM++. The ``fields`` C++ struct stores 4 types of wavefields:
 

diff --git a/docs/developer_documentation/tutorials/tutorial2/Chapter2/index.rst b/docs/developer_documentation/tutorials/tutorial2/Chapter2/index.rst
@@ -59,4 +59,4 @@ The writer class is templated on the output library. Since, all the IO libraries
 SPECFEM++ Implementation Details
 --------------------------------
 
-The actual SPECFEM++ implementation details can be found :ref:`here <IO_wavefield_writer>`.
+The actual SPECFEM++ implementation details can be found :ref:`here <IO_write_wavefield>`.
diff --git a/docs/index.rst b/docs/index.rst
@@ -163,6 +163,7 @@ Table below shows various features available and tested in this package on vario
     * needed for consistent HTML-PDF-EPUB chapters
     */
    section#getting-started,
+   section#user-documentation,
    section#cookbooks,
    section#contribution,
    section#api-documentation,
@@ -180,7 +181,7 @@ Getting Started
     :maxdepth: 1
     :hidden:
 
-    getting-started/index
+    getting_started/index
     cookbooks/index
 
 User Documentation

diff --git a/docs/parameter_documentation/index.rst b/docs/parameter_documentation/index.rst
@@ -6,6 +6,8 @@ SPECFEM++ Parameter Documentation
 The run-time behaviour of the code is controlled by YAML parameter files. The parameter file is split into a heirarchical structure of YAML nodes.
 
 .. toctree::
+    :maxdepth: 1
+
     header
     simulation_setup
     receivers

diff --git a/docs/source_description/index.rst b/docs/source_description/index.rst
@@ -28,6 +28,7 @@ Parameter Description
 
 
 .. toctree::
+   :maxdepth: 1
 
    source_discription
    source_time_function_description
diff --git a/...tion/source_time_function_discription.rst → ...tion/source_time_function_description.rst b/...tion/source_time_function_discription.rst → ...tion/source_time_function_description.rst
diff --git a/...s/Tromp_2005/Refrence_Kernels/Kernels.png → .../Tromp_2005/Reference_Kernels/Kernels.png b/...s/Tromp_2005/Refrence_Kernels/Kernels.png → .../Tromp_2005/Reference_Kernels/Kernels.png
diff --git a/include/parameter_parser/solver/solver.hpp b/include/parameter_parser/solver/solver.hpp
@@ -10,13 +10,38 @@
 namespace specfem {
 namespace runtime_configuration {
 namespace solver {
-
+/**
+ * @brief Solver class to instantiate the correct solver based on the simulation
+ * parameters
+ *
+ */
 class solver {
 public:
+  /**
+   * @brief Construct a new solver object
+   *
+   * @param simulation_type Type of the simulation (forward or combined)
+   */
   solver(const char *simulation_type) : simulation_type(simulation_type) {}
+  /**
+   * @brief Construct a new solver object
+   *
+   * @param simulation_type Type of the simulation (forward or combined)
+   */
   solver(const std::string simulation_type)
       : simulation_type(simulation_type) {}
 
+  /**
+   * @brief Instantiate the solver based on the simulation parameters
+   *
+   * @tparam qp_type Quadrature points type defining compile time or runtime
+   * quadrature points
+   * @param dt Time step
+   * @param assembly Assembly object
+   * @param time_scheme Time scheme object
+   * @param quadrature Quadrature points object
+   * @return std::shared_ptr<specfem::solver::solver> Solver object
+   */
   template <typename qp_type>
   std::shared_ptr<specfem::solver::solver>
   instantiate(const type_real dt, const specfem::compute::assembly &assembly,
@@ -34,7 +59,7 @@ class solver {
   }
 
 private:
-  std::string simulation_type;
+  std::string simulation_type; ///< Type of the simulation (forward or combined)
 };
 } // namespace solver
 } // namespace runtime_configuration