SPECFEM++ Parameter Documentation

On this page, we first show an example of a parameter file for SPECFEM++ and then provide detailed documentation for each parameter in the file in a collapsible format since a lot of the parameters are optional and only required if parent parameters are defined.

Example parameter file

specfem_config.yaml

parameters:

  header:
    ## Header information is used for logging. It is good practice to give your simulations explicit names
    title: Isotropic Elastic simulation # name for your simulation
    # A detailed description for your simulation
    description: |
      Material systems : Elastic domain (1)
      Interfaces : None
      Sources : Force source (1)
      Boundary conditions : Neumann BCs on all edges

  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: path/to/output/folder

  receivers:
    stations: path/to/stations_file
    angle: 0.0
    seismogram-type:
      - velocity
    nstep_between_samples: 1

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

  ## databases
  databases:
    mesh-database: /path/to/mesh_database.bin

  ## sources
  sources: path/to/sources.yaml

Parameter definitions

parameters

header

Define header section for your simulation. This section is used for naming the run. but has no impact on the simulation itself.

title

Brief name for this simulation

default value:

None

possible values:

[string]

Example

title: Isotropic Elastic simulation

description

Detailed description for this run.

default value:

None

possible values:

[string]

Example

description: |
  Material systems : Elastic domain (1)
  Interfaces : None
  Sources : Force source (1)
  Boundary conditions : Neumann BCs on all edges

simulation-setup

Section to define the simulation parameters

quadrature [optional]

Type of quadrature used for the simulation. There are 2 ways to define the 4th order GLL quadrature

1. Using predefined quadrature type

   quadrature:
     quadrature-type: GLL4
   

2. Using individual parameters

   quadrature:
     alpha: 0.0
     beta: 0.0
     ngllx: 5
     ngllz: 5
   

quadrature-type [optional]

Predefined quadrature types.

1. GLL4 defines 4th order GLL quadrature with 5 GLL points.

2. GLL7 defines 7th order GLL quadrature with 8 GLL points.

default value:

GLL4

possible values:

[GLL4, GLL7]

alpha

Alpha value of the Gauss-Jacobi quadrature. For GLL quadrature alpha = 0.0

default value:

None

possible values:

[float, double]

Example

quadrature:
  alpha: 0.0

beta

Beta value of the Gauss-Jacobi quadrature. For GLL quadrature beta = 0.0, and for GLJ quadrature beta = 1.0

default value:

None

possible values:

[float, double]

Example

quadrature:
  beta: 0.0

ngllx

Number of GLL points in X dimension.

default value:

None

possible values:

[int]

Example

quadrature:
  ngllx: 5

ngllz

Number of GLL points in X dimension.

default value:

None

possible values:

[int]

Example

quadrature:
    ngllz: 5

elastic-wave

Parameter to set the system to solve the elastic wave equation for in 2D

default value:

“P_SV”

possible values:

“P_SV” || “SH”

Example

elastic-wave: "P_SV"

solver

Section to define the type of solver to use for the simulation.

Example solver section

solver:
    time-marching:
        time-scheme:
            type: Newmark
            dt: 0.001
            nstep: 1000
            t0: 0.0

time-marching

Select either a time-marching or an explicit solver. Only time-marching solver is implemented currently.

time-scheme

Section to define the time scheme for the solver.

type

Select time scheme for the solver

default value:

None

possible values:

[Newmark]

Example

time-scheme:
    type: Newmark

dt

Value of time step in seconds

default value:

None

possible values:

[float, double]

Example

time-scheme:
    dt: 0.001

nstep

Total number of time steps in the simulation.

default value:

None

possible values:

[int]

Example

time-scheme:
    nstep: 1000

t0 [optional]

Start time of the simulation.

default value:

0.0

possible values:

[float, double]

Example

time-scheme:
    t0: 0.0

simulation-mode

Defines the type of simulation to run (e.g. forward, adjoint, combined, etc.)

Example

simulation-mode:
    forward:
        ...
    # or
    combined:
        ...

Note

Exactly one of forward or combined simulation nodes should be defined.

forward

Section to define the forward solver simulation parameters.

Example forward simulation node

forward:
    writer:
        seismogram:
            format: ASCII
            directory: /path/to/output/folder

        wavefield:
            format: HDF5
            directory: /path/to/output/folder
            time-interval: 10

        display:
            format: PNG
            directory: /path/to/output/folder
            field: displacement
            simulation-field: forward
            time-interval: 10

Note

At least one writer node should be defined in the forward simulation node.

writer

Defines the outputs to be stored to disk during the forward simulation.

seismogram

Seismogram writer parameters.

writer:
    seismogram:
        format: ASCII
        directory: /path/to/output/folder

format [optional]

Output format of the seismogram.

default value:

ASCII

possible values:

[ASCII]

directory [optional]

Output folder for the seismogram.

default value:

Current working directory

possible values:

[string]

wavefield

Forward wavefield writer parameters.

Example

writer:
  wavefield:
    format: HDF5
    directory: /path/to/output/folder

format [optional]

Output format of the wavefield.

default value:

ASCII

possible values:

[ASCII, HDF5]

directory [optional]

Output folder for the wavefield.

default value:

Current working directory

possible values:

[string]

time-interval [optional]

Time step interval for writing the wavefield.

default value:

1 (-> every time step)

possible values:

[int]

include-last-step [optional]

Flag to indicate if the last time step should be included when writing the wavefield.

default value:

True

possible values:

[bool]

display

Plot the wavefield during the forward simulation. Note that plotting the wavefield is only enabled for 2D simulations and requires specfem to be compiled with VTK support, -D SPECFEM_ENABLE_VTK=ON CMake option. For, 3D simulations can write the wavefield to disk in VTKHDF format, for which both VTK and HDF5 support must be enabled, and -D SPECFEM_ENABLE_VTK=ON -D SPECFEM_ENABLE_HDF5=ON CMake options.

Example

writer:
  display:
    format: PNG
    directory: /path/to/output/folder
    field: displacement
    simulation-field: forward
    time-interval: 10

format [optional]

Output format for resulting plots. The option on_screen is only available with a display of course.

default value:

PNG

possible values:

[PNG, JPG, on_screen, vtkhdf]

directory [optional]

Output folder for the plots (not applicable for on_screen).

default value:

Current working directory

possible values:

[string]

component [optional]

Component of the wavefield to be plotted.

default value:

None

possible values:

[x, y, z, magnitude]

the component parameter is ignored if the requested field is a scalar field, such as pressure. magnitude option plots the magnitude of the vector field, and if the domain has acoustic elements the potential is plotted. y is only available in 2D SH simulations and 3D simulations.

field

Component of the wavefield to be plotted.

default value:

None

possible values:

[displacement, velocity, acceleration, pressure]

simulation-field

Type of wavefield to be plotted.

default value:

None

possible values:

[forward]

time-interval

Time step interval for plotting the wavefield.

default value:

None

possible values:

[int]

combined [optional]

Combined (forward + adjoint) simulation parameters.

Example combined simulation node

simulation-mode:
  combined:
    reader:
      wavefield:
        format: HDF5
        directory: /path/to/input/folder

    ## This example avoids writing seismograms
    writer:
      kernels:
        format: HDF5
        directory: /path/to/output/folder

    display:
      format: PNG
      directory: /path/to/output/folder
      field: displacement
      simulation-field: adjoint
      time-interval: 10

Note

Exactly one of forward or combined simulation nodes should be defined.

reader [optional]

Defines the inputs to be read from disk during the combined simulation.

wavefield

Wavefield reader parameters.

default value:

None

possible values:

[YAML Node]

format [optional]

Format of the wavefield to be read.

default value:

ASCII

possible values:

[ASCII, HDF5]

directory [optional]

Folder containing the wavefield to be read.

default value:

Current working directory

possible values:

[string]

writer [optional]

Defines the outputs to be stored to disk during the combined simulation.

seismogram [optional]

Seismogram writer parameters.

format [optional]

Output format of the seismogram.

default value:

ASCII

possible values:

[ASCII]

directory [optional]

Output folder for the seismogram.

default value:

Current working directory

possible values:

[string]

kernels

Kernel writer parameters.

format [optional]

Output format of the kernels.

default value:

ASCII

possible values:

[ASCII, HDF5]

directory [optional]

Output folder for the kernels.

default value:

Current working directory

possible values:

[string]

display [optional]

Plot the wavefield during the combined simulation. See forward section for details.

format [optional]

Output format for resulting plots.

default value:

PNG

possible values:

[PNG, JPG, on_screen]

directory [optional]

Output folder for the plots (not applicable for on_screen).

default value:

Current working directory

possible values:

[string]

field

Component of the wavefield to be plotted.

default value:

None

possible values:

displacement | velocity | acceleration | pressure | rotation | intrinsic-rotation | curl

Note that the curl, rotation and intrinsic-rotation fields are only available in Cosserat/micropolar media.

simulation-field

Type of wavefield to be plotted.

default value:

None

possible values:

[adjoint, backward]

time-interval

Time step interval for plotting the wavefield.

default value:

None

possible values:

[int]

receivers

Parameter file section that contains the receiver information required to calculate seismograms.

Example receivers section

receivers:
    stations: /path/to/stations_file
    angle: 0.0
    seismogram-type:
        - velocity
        - displacement
    nstep_between_samples: 1

Note

Please note that the stations_file is generated using SPECFEM2D mesh generator i.e. xmeshfem2d

stations

Path to stations_file.

default value:

None

possible values:

[string]

Example

stations: /path/to/stations_file

angle

Angle to rotate components at receivers

default value:

None

possible values:

[float]

Example

angle: 0.0

seismogram-type

Type of seismograms to be written.

default value:

None

possible values:

[YAML list]

Example

seismogram-type:
    - velocity
    - displacement

Seismogram	SPECFEM Par_file seismotype value	receivers.seismogram-type value
Displacement	1	displacement
Velocity	2	velocity
Acceleration	3	acceleration
Pressure	4	pressure
Displacement Curl	5	curl Cosserat only
Fluid Potential	6	✘ Unsupported
Rotation	✘ Unsupported	rotation Cosserat only
Intrinsic-Rotation	✘ Unsupported	intrinsic-rotation Cosserat only

nstep_between_samples

Number of time steps between sampling the wavefield at station locations for writing seismogram.

default value:

None

possible values:

[int]

Example

nstep_between_samples: 1

run-setup

Define run-time configuration for your simulation.

Example run-setup section

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

number-of-processors

Number of MPI processes used in the simulation. MPI version is not enabled in this version of the package. number-of-processors == 1

default value:

1

possible values:

[int]

Example

number-of-processors: 1

number-of-runs

Number of runs in this simulation. Only single run implemented in this version of the package. number-of-runs == 1

default value:

1

possible values:

[int]

Example

number-of-runs: 1

databases

The databases section defines the location of files to be read by the solver.

Example of databases section

databases:
    mesh-database: /path/to/mesh_database.bin

mesh-database

Location of the fortran binary database file defining the mesh

default value:

None

possible values:

[string]

Example

mesh-database: /path/to/mesh_database.bin

mesh-parameters

Location of the fortran binary database file defining the mesh parameters.

Note

This parameter is only relevant for 3D simulations. For 2D, the solver generates the databases in memory.

default value:

None

possible values:

[string]

Example

mesh-parameters: /path/to/mesh_parameters.bin

sources

Define sources

default value:

None

possible values:

[string, YAML Node]

Example sources section

The sources is a path to a YAML file.

sources: path/to/sources.yaml

The sources section is a YAML node that contains the source information

sources:
  number-of-sources: 1
  sources:
    - force:
        x : 2500.0
        z : 2500.0
        source_surf: false
        angle : 0.0
        vx : 0.0
        vz : 0.0
        Ricker:
          factor: 1e10
          tshift: 0.0
          f0: 10.0

Note

The parameters below are only relevant if the sources section is defined as a YAML node.

number-of-sources

Number of sources in the simulation

default value:

None

possible values:

[int]

Example

number-of-sources: 1

sources

List of sources

default value:

None

possible values:

[YAML Node]

Example

sources:
  - force:
      x : 2500.0
      z : 2500.0
      source_surf: false
      angle : 0.0
      vx : 0.0
      vz : 0.0
      Ricker:
        factor: 1e10
        tshift: 0.0
        f0: 10.0