Merge pull request #133 from PrincetonUniversity/devel

SPECFEM++ 0.2.0 Release

Author: Rohit-Kakodkar

.github/workflows/docs.yml

@@ -51,6 +51,7 @@ Parameter file
 ~~~~~~~~~~~~~
 
 .. code-block:: bash
+    :caption: Par_File
 
     #-----------------------------------------------------------
     #
@@ -199,6 +200,7 @@ Defining the topography of the domain
 We define the topography of the domain using the following topography file
 
 .. code-block:: bash
+    :caption: topography_file.dat
 
     #
     # number of interfaces
@@ -260,7 +262,7 @@ Defining the source
 We define the source location and the source time function in the source file.
 
 .. code-block:: yaml
-    :linenos:
+    :caption: single_source.yaml
 
     number-of-sources: 1
     sources:
@@ -282,7 +284,6 @@ Running the simulation
 To run the solver, we first need to define a configuration file ``specfem_config.yaml``.
 
 .. code-block:: yaml
-    :linenos:
     :caption: specfem_config.yaml
 
     parameters:

docs/cookbooks/example_02.rst

@@ -216,7 +216,7 @@ With the above input files, we can run the mesher to generate the mesh database.
 
 .. code:: bash
 
-    xmeshfem2D -p Par_file
+    xmeshfem2D -p Par_File
 
 Running the forward simulation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -321,7 +321,7 @@ With the above input files, we can run the forward simulation.
 Generating adjoint sources
 --------------------------
 
-The next step is to generate the adjoint sources. We can generate the adjoint sources using ``./xadj_seismogram`` utility which models Eq. 45 of `Tromp et al. 2005 <https://doi.org/10.1111/j.1365-246X.2004.02453.x>`_. The utility requires synthetic seismograms and does not depend on the observed data.
+The next step is to generate the adjoint sources. In this example, we are computing sensitivity kernels for travel-time measurements. The adjoint source required for this kernel is defined by Eq. 45 of `Tromp et al. 2005 <https://doi.org/10.1111/j.1365-246X.2004.02453.x>`_, and relies only the synthetic velocity seismogram. Here we use the utility ``xadj_seismogram``, which computes this adjoint source from the displacement synthetics computed during forward run i.e. by numerically differentiating the displacements.
 
 .. code:: bash
 
@@ -483,7 +483,7 @@ Lastly if the kernels are stored in ASCII format, we can use numpy to read the k
 
 .. note::
 
-    An python code for reading ASCII kernels and plotting them is provided `here <https://github.com/PrincetonUniversity/SPECFEMPP/blob/latest/examples/Tromp_2005/plot.py>`_.
+    An python code for reading ASCII kernels and plotting them is provided `here <https://github.com/PrincetonUniversity/SPECFEMPP/blob/main/examples/Tromp_2005/plot.py>`_.
 
 .. figure:: ../../examples/Tromp_2005/Reference_Kernels/Kernels.png
     :alt: Kernels

docs/cookbooks/example_03.rst

@@ -117,7 +117,7 @@ SPECFEM++ inherits several architecure specific cmake configuration keywords fro
 .. code-block:: bash
 
     # cd into SPECFEM root directory
-    cmake3 -S . -B build -D CMAKE_BUILD_TYPE=Release -D BUILD_TESTS=ON -D Kokkos_ENABLE_CUDA=ON -D Kokkos_ARCH_<architecture>=ON -D BUILD_EXAMPLES=ON
+    cmake3 -S . -B build -D CMAKE_BUILD_TYPE=Release -D BUILD_TESTS=ON -D Kokkos_ENABLE_CUDA=ON -D Kokkos_ARCH_<architecture>=ON
     cmake --build build
 
 .. note::
@@ -127,11 +127,11 @@ SPECFEM++ inherits several architecure specific cmake configuration keywords fro
 Adding SPECFEM to PATH
 ----------------------
 
-Finally, once compiled you could run SPECFEM++ from inside the build directory, by running the executible ``./specfem``. However, we recommend you add SPECFEM++ build directory to your ``PATH`` using
+Finally, once compiled you could run SPECFEM++ from inside the build directory, by running the executible ``./specfem2d``. However, we recommend you add SPECFEM++ build directory to your ``PATH`` using
 
 .. code-block:: bash
 
-    export $PATH=$(pwd)/build:$PATH
+    export PATH=$(pwd)/build:$PATH
 
 Running the solver
 ------------------
@@ -145,12 +145,14 @@ Lets run a simple example to test the installation. We will use the ``example\ho
 .. code-block:: bash
 
   cd examples/homogeneous-medium-flat-topography
-  xmeshfem2D -p Par_file
+  mkdir -p OUTPUT_FILES
+  xmeshfem2D -p Par_File
 
 This will generate the mesh files. Next, we will run the solver using
 
 .. code-block:: bash
 
+  mkdir -p OUTPUT_FILES/results
   specfem2d -p specfem_config.yaml
 
 This will run the solver and generate synthetic seismograms at the receiver locations specified in ``STATIONS`` file.

docs/getting_started/index.rst

@@ -140,19 +140,19 @@ Table below shows various features available and tested in this package on vario
       -
       -
 
-    * - displacement
+    * - Displacement
       - ✔
       - ✔
       - ✔
       -
 
-    * - velocity
+    * - Velocity
       - ✔
       - ✔
       - ✔
       -
 
-    * - acceleration
+    * - Acceleration
       - ✔
       - ✔
       - ✔

docs/index.rst

@@ -1,4 +1,5 @@
 
 CMAKE_MINIMUM_REQUIRED(VERSION 3.17.5)
 
-configure_file(Snakefile.in ${CMAKE_SOURCE_DIR}/examples/Tromp_2005/Snakefile)
+configure_file(CMakeFiles/Par_File.in ${CMAKE_SOURCE_DIR}/examples/Tromp_2005/Par_File)
+configure_file(CMakeFiles/Snakefile.in ${CMAKE_SOURCE_DIR}/examples/Tromp_2005/Snakefile)

examples/Tromp_2005/Par_File.in renamed to examples/Tromp_2005/CMakeFiles/Par_File.in

@@ -1,6 +1,6 @@
 # Wave propagation through homogeneous medium with no interfaces
 
-This example reproduces the results from Fig 9 of [Tromp et al. 2005](https://doi.org/10.1111/j.1365-246X.2004.02453.x).
+This example reproduces the results from Fig 9 of [Tromp et al. 2005](https://doi.org/10.1111/j.1365-246X.2004.02453.x). For a step-by-step guide on this example, please refer to the [documentation](https://specfem2d-kokkos.readthedocs.io/en/latest/cookbooks/example_03.html).
 
 ## Running the examples