Skip to content

Commit

Permalink
Updated the cookbooks for new format of SPECFEM params
Browse files Browse the repository at this point in the history
  • Loading branch information
@Rohit-Kakodkar
Rohit-Kakodkar committed Oct 30, 2024
1 parent 43d9abf commit 65327a8
Show file tree
Hide file tree
Showing 3 changed files with 136 additions and 43 deletions.
48 changes: 35 additions & 13 deletions docs/cookbooks/example_01.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -151,6 +151,8 @@ Parameter File
xmax = 4000.d0 # abscissa of right side of the model
nx = 80 # number of elements along X

STACEY_ABSORBING_CONDITIONS = .false.

# absorbing boundary parameters (see absorbing_conditions above)
absorbbottom = .false.
absorbright = .false.
Expand Down Expand Up @@ -289,23 +291,25 @@ Now that we have generated a mesh and defined the sources, we need to set up the
## Solver setup
solver:
time-marching:
type-of-simulation: forward
time-scheme:
type: Newmark
dt: 1.1e-3
nstep: 1600

simulation-mode:
forward:
writer:
seismogram:
format: "ascii"
directory: <output-folder-to-store-synthetic-seismograms>

receivers:
stations-file: <PATH TO STATIONS FILE>
angle: 0.0
seismogram-type:
- velocity
nstep_between_samples: 1

seismogram:
seismogram-format: ascii
output-folder: <PATH TO DIRECTORY FOR STORING OUTPUTS>

## Runtime setup
run-setup:
number-of-processors: 1
Expand All @@ -318,6 +322,32 @@ Now that we have generated a mesh and defined the sources, we need to set up the

At this point lets focus on a few sections in this file:

- Configure the solver using ``simulation-setup`` section.

.. code:: yaml

simulation-setup:
## quadrature setup
quadrature:
quadrature-type: GLL4
## Solver setup
solver:
time-marching:
time-scheme:
type: Newmark
dt: 1.1e-3
nstep: 1600
simulation-mode:
forward:
writer:
seismogram:
format: "ascii"
directory: <output-folder-to-store-synthetic-seismograms>

* We first define the integration quadrature to be used in the simulation. At this moment, the code supports a 4th order Gauss-Lobatto-Legendre quadrature with 5 GLL points (``GLL4``) & a 7th order Gauss-Lobatto-Legendre quadrature with 8 GLL points (``GLL7``).
* Define the solver scheme using the ``time-scheme`` parameter.
* Define the simulation mode to be forward and the output format for synthetic seismograms seismograms.

- Define the path to the meshfem generated database file using the ``mesh-database`` parameter and the path to source description file using ``source-file`` parameter. Relevant parameter values:

.. code:: yaml
Expand All @@ -327,14 +357,6 @@ At this point lets focus on a few sections in this file:
mesh-database: <PATH TO MESHFEM DATABASE FILE>
source-file: <PATH TO SOURCES YAML FILE>

- Define the path to :ref:`stations_file` and a directory to store output. If an output directory is not specified the seismogram outputs will be stored in the current working directory. Relevant parameter values:

.. code:: yaml

seismogram:
stations-file: <PATH TO STATIONS FILE>
output-folder: <PATH TO DIRECTORY FOR STORING OUTPUTS>

- It is good practice to have distinct header section for you simulation. These sections will be printed to standard output during runtime helping the you to distinguish between runs using standard strings. Relevant paramter values

.. code:: yaml
Expand Down
43 changes: 23 additions & 20 deletions docs/cookbooks/example_02.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -60,11 +60,11 @@ Parameter file
rec_normal_to_surface = .false. # base anglerec normal to surface (external mesh and curve file needed)

# first receiver set (repeat these 6 lines and adjust nreceiversets accordingly)
nrec = 110 # number of receivers
xdeb = 2500.d0 # first receiver x in meters
zdeb = 2933.33333d0 # first receiver z in meters
xfin = 6000.d0 # last receiver x in meters (ignored if only one receiver)
zfin = 2933.33333d0 # last receiver z in meters (ignored if only one receiver)
nrec = 11 # number of receivers
xdeb = 1450.d0 # first receiver x in meters
zdeb = 2400 # first receiver z in meters
xfin = 1575.d0 # last receiver x in meters (ignored if only one receiver)
zfin = 3400 # last receiver z in meters (ignored if only one receiver)
record_at_surface_same_vertical = .false. # receivers inside the medium or at the surface

# filename to store stations file
Expand Down Expand Up @@ -125,6 +125,8 @@ Parameter file
xmax = 6400.d0 # abscissa of right side of the model
nx = 144 # number of elements along X

STACEY_ABSORBING_BOUNDARY = .true. # use Stacey absorbing boundary conditions

# absorbing boundary parameters (see absorbing_conditions above)
absorbbottom = .true.
absorbright = .true.
Expand All @@ -150,7 +152,7 @@ Parameter file
- Firstly, ``nbmodels`` defines the number of material systems in the simulation domain.
- We then define the velocity model for each material system using the following format: ``model_number rho Vp Vs 0 0 QKappa Qmu 0 0 0 0 0 0``.

- We define stacey absorbing boundary conditions on all the edges of the domain using the ``absorbbottom``, ``absorbright``, ``absorbtop`` and ``absorbleft`` parameters.
- We define stacey absorbing boundary conditions on all the edges of the domain using the ``STACEY_ABSORBING_BOUNDARY``, ``absorbbottom``, ``absorbright``, ``absorbtop`` and ``absorbleft`` parameters.

Defining the topography of the domain
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand Down Expand Up @@ -248,21 +250,20 @@ To run the solver, we first need to define a configuration file ``specfem_config

header:
## Header information is used for logging. It is good practice to give your simulations explicit names
title: Heterogeneous acoustic-elastic medium with 1 acoustic-elastic interface # name for your simulation
title: Heterogeneous acoustic-elastic medium with 1 acoustic-elastic interface (orientation horizontal) # name for your simulation
# A detailed description for your simulation
description: |
Material systems : Elastic domain (1), Acoustic domain (1)
Interfaces : Acoustic-elastic interface (1)
Interfaces : Acoustic-elastic interface (1) (orientation horizontal with acoustic domain on top)
Sources : Force source (1)
Boundary conditions : Neumann BCs on all edges
Debugging comments: This tests checks coupling acoustic-elastic interface implementation.
The orientation of the interface is horizontal with acoustic domain on top.

simulation-setup:
## quadrature setup
quadrature:
alpha: 0.0
beta: 0.0
ngllx: 5
ngllz: 5
quadrature-type: GLL4

## Solver setup
solver:
Expand All @@ -271,14 +272,20 @@ To run the solver, we first need to define a configuration file ``specfem_config
time-scheme:
type: Newmark
dt: 0.85e-3
nstep: 800
nstep: 600

simulation-mode:
forward:
writer:
seismogram:
format: ascii
directory: "<output-directory-to-store-synthetic_seismograms>"

receivers:
stations-file: <Location of Stations file>
stations-file: <Location to stations file>
angle: 0.0
seismogram-type:
- displacement
- velocity
nstep_between_samples: 1

## Runtime setup
Expand All @@ -288,9 +295,5 @@ To run the solver, we first need to define a configuration file ``specfem_config

## databases
databases:
mesh-database: <Location to mesh database file>
mesh-database: <Location to database file>
source-file: <Location to source file>

seismogram:
seismogram-format: ascii
output-folder: "."
88 changes: 78 additions & 10 deletions docs/cookbooks/example_03.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -125,6 +125,8 @@ Setting up the Mesh
xmax = 200000.d0 # abscissa of right side of the model
nx = 80 # number of elements along X

STACEY_ABSORBING_CONDITIONS = .true.

# absorbing boundary parameters (see absorbing_conditions above)
absorbbottom = .true.
absorbright = .false.
Expand Down Expand Up @@ -180,7 +182,7 @@ Running the forward simulation
Now that we have the mesh database, we can run the forward simulation. Lets set up the runtime behaviour of the solver using the following input file.

.. code-block:: yaml
:caption: specfem-config.yaml
:caption: forward-config.yaml

parameters:

Expand Down Expand Up @@ -212,12 +214,12 @@ Now that we have the mesh database, we can run the forward simulation. Lets set
forward:
writer:
wavefield:
output-format: HDF5
output-folder: <output folder name>
format: HDF5
directory: <output folder name>

seismogram:
output-format: ascii # output seismograms in HDF5 format
output-folder: <output folder name>
format: ascii # output seismograms in HDF5 format
directory: <output folder name>

receivers:
stations-file: <Location to stations file>
Expand All @@ -244,8 +246,8 @@ To store the wavefield at the last time step, we need to set the following param

writer:
wavefield:
output-format: HDF5
output-folder: <output folder name>
format: HDF5
directory: <output folder name>

2. Saving the synthetics: We need to save the synthetics at the receiver locations. It is import that we save the synthetics in ASCII format for displacement seismograms.

Expand All @@ -272,7 +274,7 @@ With the above input files, we can run the forward simulation.

.. code:: bash

./specfem2d -p <specfem-config.yaml>
./specfem2d -p <forward-config.yaml>

Generating adjoint sources
--------------------------
Expand Down Expand Up @@ -340,7 +342,69 @@ Now finally we can run the adjoint simulation. We use the same mesh database as
format: ascii
stf-file: /scratch/gpfs/rk9481/specfem2d_kokkos/examples/Tromp_2005/OUTPUT_FILES/AA.S0001

1. To set up the a combined simulation, we need to replace the forward YAML node with a combined node.
1. Set up the configuration file for the adjoint simulation.

.. code-block:: yaml
:caption: adjoint-config.yaml


.. code-block:: yaml
:caption: specfem-config.yaml

parameters:

header:
title: "Tromp-Tape-Liu (GJI 2005)"
description: |
Material systems : Elastic domain (1)
Interfaces : None
Sources : Force source (1)
Boundary conditions : Free surface (1)
Mesh : 2D Cartesian grid (1)
Receiver : Displacement seismogram (1)
Output : Wavefield at the last time step (1)
Output : Seismograms in ASCII format (1)

simulation-setup:
quadrature:
quadrature-type: GLL4

solver:
time-marching:
time-scheme:
type: Newmark
dt: 0.02
nstep: 3000
t0: 8.0

simulation-mode:
combined:
reader:
wavefield:
format: HDF5
directory: <Directory containing the forward wavefield>

writer:
kernels:
format: ASCII
directory: <Directory to store the kernels>

receivers:
stations-file: <Location to stations file>
angle: 0.0
seismogram-type:
- displacement
nstep_between_samples: 1

run-setup:
number-of-processors: 1
number-of-runs: 1

databases:
mesh-database: <Location to mesh database>
source-file: <Location to sources file>

Note the change to the ``simulation-mode`` section, where we've replaced the forward ``section`` with the ``combined`` section. The ``combined`` section requires a ``reader`` section defining where the forward wavefield was stored during the forward simulation and a ``writer`` section defining where the kernels are to be stored.

.. code-block:: yaml
:caption: combined YAML node
Expand All @@ -360,7 +424,7 @@ With the above input files, we can run the adjoint simulation.

.. code:: bash

./specfem2d -p <specfem-config.yaml>
./specfem2d -p <adjoint-config.yaml>

The kernels are stored in the directory specified in the input file. We can now plot the kernels to visualize the banana donut kernels.

Expand All @@ -369,6 +433,10 @@ Visualizing the kernels

Lastly if the kernels are stored in ASCII format, we can use numpy to read the kernels and plot them.

.. 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>`_.

.. figure:: ../../examples/Tromp_2005/Reference_Kernels/Kernels.png
:alt: Kernels
:width: 800
Expand Down

0 comments on commit 65327a8

Please sign in to comment.