Input Parameters

The SpecFWAT employs a YAML file to define the parameters for forward simulation, adjoint simulation, post-processing, and optimization. This file is typically named fwat_params.yml and is located in the DATA directory of your SpecFWAT project. Below shows section of the fwat_params.yml file:

NOISE Section

This section defines the noise parameters for the forward simulation and measurements of adjoint sources.

NOISE:
  MESH_PAR_FILE: DATA/meshfem3D_files/Mesh_Par_file # Mesh file
  RCOMPS: ['Z'] # Components of the receiver
  CH_CODE: BX # Channel code
  NSTEP: 4500 # Number of time steps
  DT: 0.06 # Time step for the noise data
  IMEAS: 5
  ITAPER: 2
  SHORT_P: [6, 10, 20] # Short period of filters
  LONG_P: [15, 25, 40] # Long period of filters
  GROUPVEL_MIN: [2.3, 2.3, 2.5] # Approximate minimum group velocity
  GROUPVEL_MAX: [3.2, 3.5, 4.0] # Approximate maximum group velocity
  ADJ_SRC_NORM: False # Set the following to .true. to normalize adjoint sources across different bands
  USE_NEAR_OFFSET: False # Set the following to false if use only data > 1 average wavelength
  SUPPRESS_EGF: False # Set to .false. when the data are cross-correlation functions
  PRECOND_TYPE: 1 # 1: inner product of acceleration
  SIGMA_H: 5000
  SIGMA_V: 5000

Mesh Parameters

• MESH_PAR_FILE: Path to the mesh parameter file with the same format as meshfem3D. SpecFWAT uses internal mesh generator of Specfem3D to create the mesh based on the model parameters, but allow users to specify the mesh file rathar than a fixed mesh file DATA/meshfem3D_files/Mesh_Par_file of Specfem3D.

Solver Parameters

• RCOMPS: Components of the receiver, For tomography of isotropic media, it is usually set to ['Z'] for vertical component.

• CH_CODE: Channel code, which is used to identify the channel in the data. It is usually set to BX for broadband data.

• NSTEP: Number of time steps for the forward/adjoint simulation. It overrides the NSTEP in DATA/Par_file, which allow users to specify the number of time steps for different data types.

• DT: Time step for the noise data, It overrides the DT in DATA/Par_file, which allow users to specify the time step for different data types.

Adjoint source

• IMEAS: Option of adjoint source measurements. It is used to determine the objective function. See measure_adj manual for more details of adjoint source measurements. The default value is 5, which means the adjoint source are time shift based on cross-correlation.

• ITAPER: Option of tapering for adjoint source. The default value is 2, which means the Cosine tapering.

• SHORT_P: Short cut-off period of filters for the adjoint source measurements. It is a list of values, which are used to filter the data in different frequency bands.

• LONG_P: Long cut-off period of filters for the adjoint source measurements. It is a list of values with the same length as SHORT_P.

• GROUPVEL_MIN: Approximate minimum group velocity to determine the time window for the adjoint source measurements. It is a list of values with the same length as SHORT_P.

• GROUPVEL_MAX: Approximate maximum group velocity to determine the time window for the adjoint source measurements. It is a list of values with the same length as SHORT_P.

• ADJ_SRC_NORM: Set to True to normalize the adjoint sources across different bands.

• USE_NEAR_OFFSET: Set to False if you want to use only data with distance greater than 0.5 * wavelength in each period band. It is usually set to False in practice.

• SUPPRESS_EGF: Whether calculate difference to obtain empirical Green’s functions (EGF). Set to False if the data are cross-correlation functions.

Post-processing parameters of noise data

• PRECOND_TYPE: Type of preconditioning for gradient. 0 ($P_0$) or 1 ($P_1$) are accepted value based on inner product of acceleration, The default value is 1.

• SIGMA_H: Horizontal smoothing length in meter of gradient.
• SIGMA_V: Vertical smoothing length in meter of gradient.

TELE Section

This section defines the parameters for the teleseismic FWAT.

TELE:
  MESH_PAR_FILE: DATA/meshfem3D_files/Mesh_Par_file # Mesh file
  TELE_TYPE: 2 # 1: teleseismic data, 2: receiver function, 3: Teleseismic cross-convolution
  RCOMPS: ['Z', 'R'] # Components of the receiver
  CH_CODE: BX # Channel code
  SAVE_FK: True # Save the FK wavefield
  COMPRESS_LEVEL: 0
  NSTEP: 2500 # Number of time steps
  DT: 0.025 # Time step for the teleseismic data
  SHORT_P: [1] # Short period of filters
  LONG_P: [20] # Long period of filters
  TIME_WIN: [-5, 25] # Time window for the teleseismic data
  PRECOND_TYPE: 3 # 2: abs(Z); 3: root squared z
  SIGMA_H: 5000
  SIGMA_V: 5000
  RF:
    F0: [1.5] # Gaussian width for the RF
    MAXIT: 200 # Maximum number of iterations
    MINDERR: 0.001 # Minimum residual error when the RF converges
    TSHIFT: 5.0 # Time shift before P

Adjoint Source

The parameters in the TELE section with the same name as in the NOISE section are similar, but with different values. The following parameters are specific to the TELE section:

• TELE_TYPE: Type of objective function for teleseismic data. It can be

  • 1 for teleseismic waveform difference (Wang et al., 2021 ).
  • 2 for receiver function difference (Xu et al., 2023 ).
  • 3 for teleseismic cross-convolution difference.

• SAVE_FK: Set to True to save the FK wavefield for teleseismic data. The FK wavefield will be checked in the LOCAL_PATH (Set in DATA/Par_file) before running the forward simulation. If the FK wavefield is not found, it will be generated and saved in the LOCAL_PATH/FK_{event_name} directory, otherwise, it will be loaded from the existing FK wavefield directory to reduce time consumption. It will be useful for GPU acceleration.

• COMPRESS_LEVEL: Compression level of the saved FK wavefield in hdf5 format. same as compression_opts in h5py.File. It can be set to 0 (no compression), 1 (fastest), 2, 3, 4, 5, 6, 7, or 9 (best compression). The default value is 0.

• TIME_WIN: Time window for the teleseismic data. It is a list of two values, which are the start and end time before and after direct P arrival.

• PRECOND_TYPE: Type of preconditioning for gradient. 2 ($P_2$) or 3 ($P_3$) are accepted value based on Z-precondition The default value is 3.

Receiver function parameters

For Receiver function adjoint tomography, the synthetic receiver function is calculated based on the iterative deconvolution method. The following parameters are used to control the receiver function inversion:

• RF.F0: Gaussian width for the receiver function. It is a list of values, which are used to filter the data in different frequency bands.

• RF.MAXIT: Maximum number of iterations for the receiver function inversion.

• RF.MINDERR: Minimum residual error when the receiver function converges.

• RF.TSHIFT: Time shift before P arrival for the receiver function inversion. It is used to align the receiver function with the direct P arrival.

MEASURE_ADJ Section

SpecFWAT 0.4.0 employs measure_adj to measure adjoint sources of ambient noise data. Following parameters inherited from measure_adj for adjoint source measurements:

MEASURE_ADJ:
  TSHIFT_MIN: -5.000
  TSHIFT_MAX: 5.000
  DLNA_MIN: -1.5000
  DLNA_MAX: 1.5000
  CC_MIN: 0.800
  ERROR_TYPE: 1
  DT_SIGMA_MIN: 1.000
  DLNA_SIGMA_MIN: 0.500
  WTR: 0.020
  NPI: 2.50
  DT_FAC: 2.000
  ERR_FAC: 2.500
  DT_MAX_SCALE: 3.500 
  NCYCLE_IN_WINDOW: 1.500
  USE_PHYSICAL_DISPERSION: .false.

See measure_adj manual  for more details about these parameters.

MODEL_GRID Section

SpecFWAT update model parameters on a regular grid, which is easily to take sum of gradients of different data sets with different mesh. The size of each regular grid should be small to ensure the accuracy of gradient information. We recommended set the size of each regular grid to be at least half of element size of the mesh.

MODEL_GRID:
  REGULAR_GRID_MIN_COORD: [833950, -44274.0, -80000]
  REGULAR_GRID_INTERVAL: [2000, 2000, 1000]
  REGULAR_GRID_SIZE: [104, 48, 81]

• REGULAR_GRID_MIN_COORD: Minimum coordinate of the regular grid in meter. It is a list of three values, which are the minimum x, y, and z coordinates of the regular grid.

• REGULAR_GRID_INTERVAL: Interval of the regular grid in meter. It is a list of three values, which are the interval in x, y, and z directions.

• REGULAR_GRID_SIZE: Number of regular grid. It is a list of three values, which are the number of grid points in x, y, and z directions.

POSTPROC Section

This section defines the common parameters for the post-processing of the gradient after the adjoint simulation.

POSTPROC:
  INV_TYPE: [False, True] # Inversion type of noise and teleseismic data
  JOINT_WEIGHT: [0.5, 0.5]
  TAPER_H_SUPPRESS: 5000
  TAPER_H_BUFFER: 10000
  TAPER_V_SUPPRESS: 0
  TAPER_V_BUFFER: 0
  IS_PRECOND: True

• INV_TYPE: Inversion type of ambient noise and teleseismic data. It is a list of two boolean values, which are used to determine whether to perform inversion for noise and teleseismic data, respectively. The first value is for noise data, and the second value is for teleseismic data.

• JOINT_WEIGHT: Weight between ambient noise and teleseismic data. It is a list of two values, which are used to weight the gradients of ambient noise and teleseismic data, respectively.

• TAPER_H_SUPPRESS: Horizontal tapering length in meter to suppress the gradient at the margin of the mesh.

• TAPER_H_BUFFER: Horizontal tapering length in meter to buffer the gradient at the margin of the mesh.

• TAPER_V_SUPPRESS: Vertical tapering length in meter to suppress the gradient at the margin of the mesh.

• TAPER_V_BUFFER: Vertical tapering length in meter to buffer the gradient at the margin of the mesh.

• IS_PRECOND: Whether directly apply preconditioning to the gradient. If set to False, the preconditioner will be saved and apply on L-BFGS as rescale vector (Modrak and Tromp 2016 ).

MODEL_UPDATE Section

This section defines the parameters for the model update based on the gradient and optimization method.

MODEL_UPDATE:
  INIT_MODEL_PATH: initial_model.h5
  MODEL_TYPE: 1 # 1: vp,vs,rho; 2: L,Gc,Gs
  OPT_METHOD: 2 # Optimization method, 1: SD; 2: LBFGS 
  ITER_START: 0
  LBFGS_M_STORE: 5
  MAX_SLEN: 0.02 # Maximum step length
  MAX_SHRINK: 0.618 # Maximum shrink factor
  MAX_SUB_ITER: 6
  DO_LS: True # Do line search
  C1: 0.1
  VPVS_RATIO_RANGE: [1.3, 2.5] # Min and max limitation of Vp/Vs ratio

• INIT_MODEL_PATH: Path to the initial model file. It should be a HDF5 file with the same format as DATA/tomo_files/tomography_model.h5, but the size could be different from the MODEL_GRID section. An interpolation will be performed to interpolate INIT_MODEL_PATH to MODEL_GRID size and save to optimize/model_M00.h5.

• MODEL_TYPE: Type of model parameters to be updated. It can be

  • 1 for updating Vp, Vs, and Rho.
  • 2 for updating azimuthal anisotropy parameters (L, Gc, Gs).

• OPT_METHOD: Optimization method for model update. It can be

  • 1 for steepest descent (SD).
  • 2 for L-BFGS.
  • 3 for conjugate gradient (CG).

• ITER_START: Starting iteration number of L-BFGS optimization.

• LBFGS_M_STORE: Number of previous iterations to store in L-BFGS optimization.

• MAX_SLEN: Maximum step length for model update.

• MAX_SHRINK: Maximum shrink factor for model update. It is used to control the step length reduce when the model update does not decrease the objective function.

• MAX_SUB_ITER: Maximum number of sub-iterations for model update.

• DO_LS: Whether to perform line search for model update. If set to True, the line search will be performed to find the optimal step length for model update, otherwise, the step length will be fixed to MAX_SLEN.

• C1: Constant for the Armijo condition in line search. It is used to determine whether the step length is sufficient to decrease the objective function.

OUTPUT Section

This section controls the verbose output of the SpecFWAT workflow

OUTPUT:
  IS_OUTPUT_PREPROC: True # Output preprocessed data
  IS_OUTPUT_ADJ_SRC: False # Output adjoint sources
  IS_OUTPUT_EVENT_KERNEL: True # Output kernels
  IS_OUTPUT_SUM_KERNEL: True # Output sum of kernels
  IS_OUTPUT_HESS_INV: False # Output inverse Hessian when precond_type = 1
  IS_OUTPUT_DIRECTION: False

• IS_OUTPUT_PREPROC: Whether to output the preprocessed data in SAC format. If set to True, the preprocessed data will be saved in the solver/{model}.{simu_type}/{event_name}/OUTPUT_FILES/ directory.

• IS_OUTPUT_ADJ_SRC: Whether to output the adjoint sources in SAC format. If set to True, the adjoint sources will be saved in the solver/{model}.{simu_type}/{event_name}/SEM/ directory.

• IS_OUTPUT_EVENT_KERNEL: Whether to output the kernels for each event. If set to True, the kernels will be kept in the solver/{model}.{simu_type}/{event_name}/EKERNEL/ directory, otherwise, the kernels will be deleted after the post-processing step.

• IS_OUTPUT_SUM_KERNEL: Whether to output the sum of kernels after post-processing. If set to True, the sum of kernels will be saved in the optimize/SUM_KERNEL_{model}/ directory.

• IS_OUTPUT_HESS_INV: Whether to output the inverse Hessian. If set to True, the inverse Hessian will be saved in the optimize/SUM_KERNEL_{model}/ directory.

• IS_OUTPUT_DIRECTION: Whether to output the final descent direction of each iteration. If set to True, the direction will be saved in the optimize/ directory.