seisflows.solver.specfem3d_globe

This class provides utilities for the Seisflows solver interactions with Specfem3D Globe. It is built on top of the Specfem base class.

Some key differences between 3D and 3D_GLOBE implementations:

1. SPECFEM3D_GLOBE does not require ‘xgenerate_databases’ which is

   required for Cartesian.

2. Related to (1), we do NOT want to re-run the mesher, event at

   the very beginning. The Solver will simply re-load GLL model when run with a valid GLL model

3. 3DGLOBE cannot toggle attenuation on/off. If it was on to create

   the model, it MUST be on for the solver (otherwise throws a weird ‘recompile solver’ error)

4. Does not allow SU seismogram outputs, only ASCII, SAC, ASDF, 3D_Array

5. SPECFEM3D_GLOBE ASCII synthetics have extension ‘.ascii’, but

   the adjoint sources are NOT supposed to have this, i.e., they should have extension ‘.adj’

6. 3DGLOBE breaks its files into 3 regions (reg1: mantle, reg2: outer core,

   reg3: inner core) which affects file bookkeeping

Classes

Specfem3DGlobe

Solver SPECFEM3D_GLOBE

Module Contents

class seisflows.solver.specfem3d_globe.Specfem3DGlobe(source_prefix='CMTSOLUTION', export_vtk=True, prune_scratch=True, regions='123', mask_source=False, scale_mask_region=False, **kwargs)

Bases: seisflows.solver.specfem.Specfem

Solver SPECFEM3D_GLOBE

SPECFEM3D_Globe-specific alterations to the base SPECFEM module

Parameters

type source_prefix:

str

param source_prefix:

Prefix of source files in path SPECFEM_DATA. Must be in [‘CMTSOLUTION’, ‘FORCESOLUTION’]. Defaults to ‘CMTSOLUTION’

type export_vtk:

bool

param export_vtk:

at the finalization step of each iteration, convert all eligible model and gradient directories in the path_output to .vtk files for visualization using ParaView (or similar programs). Files are exported to path_output/VTK

type prune_scratch:

bool

param prune_scratch:

prune/remove database files as soon as they are used, to keep overall filesystem burden down - removes *.vt? files after they’re generated by a forward simulation - removes proc*_absorb_field.bin and proc*_save_forward_array.bin

files after adjoint simulations

type regions:

str

param regions:

which regions of the chunk to consider in your ‘model’. Valid regions are 1, 2 and 3. If you want all regions, set as ‘123’. If you only want region 1, set as ‘1’, etc. Order insensitive.

type mask_source:

bool

param mask_source:

mask the source region of the gradient to avoid high amplitude updates around source region. If True, uses the SPECFEM parameter ‘SAVE_SOURCE_MASK’ to output source mask files and applies source mask to event kernel during gradient calculation.

type scale_mask_source:

float

param scale_mask_region:

only used if mask_source == True. the output source mask from SPECFEM3D_GLOBE is an array of ones (1) with a 3D gaussian ceneterd on the source region which approaches 0 at the hypocenter. However, for kernels that have very small amplitudes (<1E-5) the amplitudes of the mask may not be sufficient to suppress the high amplitude source region kernel. This fudge factor allows the User to scale the source mask to better suppress the source region. ONLY the source mask region will be multiplied by this value. Defaults to False (no modification), if set to 0, entire source mask region will act as a cutout. Trial and error will be required to determine a useful value that is not 0 or 1. Note that this parameter is not actually used by the solver, it is used by the Migration workflow, but it is kept here for consistency.

Paths

***

__doc__ = Multiline-String

Show Value

"""
    Solver SPECFEM [Solver Base]
    ----------------------------
    Defines foundational structure for Specfem-based solver module.
    Generalized SPECFEM interface to manipulate SPECFEM2D/3D/3D_GLOBE w/ Python

    Parameters
    ----------
    :type syn_data_format: str
    :param syn_data_format: data format for reading synthetic traces into memory.
        Available: ['SU': seismic unix format, 'ASCII': human-readable ascii]
    :type materials: str or list
    :param materials: Material name used to define the model parameters that
        will be updated during an Inversion workflow. Available options
        (case-insensitive):
        - `type: list` (2D, 3D, 3D_GLOBE): User-defined list of lower-case
            parameters (e.g., ['vp', 'vs'] to mimic 'ELASTIC')
            NOTE: User is responsible for understanding if their chosen
            parameters are actually represented in SPECFEM, there are no guard
            rails here to protect incorrect parameter naming
        - ACOUSTIC (2D, 3D, 3D_GLOBE): vp
        - ELASTIC (2D, 3D, 3D_GLOBE): vp, vs
        - TRANSVERSE_ISOTROPIC (3D, 3D_GLOBE): vpv, vph, vsv, vsh, eta
        - 2D_ANISOTROPIC (2D): c11 c13 c15 c33 c35 c55 c12 c23 c25 c22
        - ANISOTROPIC (3D, 3D_GLOBE): c_ij  (21 parameter anisotropy)

    :type update_density: bool
    :param update_density: How to treat density during inversion. If True,
        updates density during inversion. If False, keeps it constant.
        TODO allow density scaling during an inversion
    :type attenuation: bool
    :param attenuation: How to treat attenuation during inversion.
        if True, turns on attenuation during forward simulations only. If
        False, attenuation is always set to False. Requires underlying
        attenution (Q_mu, Q_kappa) model
    :type smooth_h: float
    :param smooth_h: Gaussian half-width for horizontal smoothing in units
        of meters. If 0., no smoothing applied. Only applicable for workflows:
        ['migration', 'inversion'], ignored for 'forward' workflow.
        SPECFEM3D_GLOBE only: if `smooth_type`=='laplacian' then this is just
        the X and Y extent of the applied smoothing
    :type smooth_v: float
    :param smooth_v: Gaussian half-width for vertical smoothing in units
        of meters. Only applicable for workflows: ['migration', 'inversion'],
        ignored for 'forward' workflow.
        SPECFEM3D_GLOBE only: if `smooth_type`=='laplacian' then this is just
        the Z extent of the applied smoothing
    :type smooth_type: str
    :param smooth_type: choose how smoothing is performed for gradients.
        these are tied to the internal smoothing functions available, and only
        certain code flavors have certain smoothing functions available:
        - 'gaussian' [2D/3D/3D_GLOBE]: Default, convolve with a 3D gaussian,
            slow and computationally intensive. Only option for 2D.
        - 'laplacian' [3D_GLOBE]: RECOMMENDED FOR 3D_GLOBE. Average points
            around vertex to smooth. Much faster than Gaussian.
        - 'pde' [3D]: RECOMMENDED for 3D. Diffusion-based PDE smoothing.
            Much faster than Gaussian. See SPECFEM3D PR#1725
    :type components: str
    :param components: components to search for synthetic data with. None by
        default which uses a wildcard when searching for synthetics. If
        provided, User only wants to use a subset of components generated by
        SPECFEM. In that case, `components` should be string of letters such
        as 'ZN' (for up and north components)
    :type solver_io: str
    :param solver_io: format of model/kernel/gradient files expected by the
        numerical solver. Available: ['fortran_binary': default .bin files].
        TODO: ['adios': ADIOS formatted files]
    :type source_prefix: str
    :param source_prefix: prefix of source/event/earthquake files. If None,
        will attempt to guess based on the specific solver chosen.
    :type mpiexec: str
    :param mpiexec: MPI executable used to run parallel processes. Should also
        be defined for the system module

    Paths
    -----
    :type path_data: str
    :param path_data: path to any externally stored waveform data required for
        data-synthetic comparison
    :type path_specfem_bin: str
    :param path_specfem_bin: path to SPECFEM bin/ directory which
        contains binary executables for running SPECFEM
    :type path_specfem_data: str
    :param path_specfem_data: path to SPECFEM DATA/ directory which must
        contain the CMTSOLUTION, STATIONS and Par_file files used for
        running SPECFEM
    ***

This class provides utilities for the Seisflows solver interactions with
Specfem3D Globe. It is built on top of the Specfem base class.

Some key differences between 3D and 3D_GLOBE implementations:

    1) SPECFEM3D_GLOBE does not require 'xgenerate_databases' which is
        required for Cartesian.
    2) Related to (1), we do NOT want to re-run the mesher, event at
        the very beginning. The Solver will simply re-load GLL model
        when run with a valid GLL model
    3) 3DGLOBE cannot toggle attenuation on/off. If it was on to create
        the model, it MUST be on for the solver (otherwise throws
        a weird 'recompile solver' error)
    4) Does not allow SU seismogram outputs, only ASCII, SAC, ASDF, 3D_Array
    5) SPECFEM3D_GLOBE ASCII synthetics have extension '.ascii', but
        the adjoint sources are NOT supposed to have this, i.e., they
        should have extension '.adj'
    6) 3DGLOBE breaks its files into 3 regions (reg1: mantle, reg2: outer core,
        reg3: inner core) which affects file bookkeeping
"""

prune_scratch = True

mask_source = False

scale_mask_region = False

export_vtk = True

_export_vtk = True

regions = ''

_regions

_parameters

_available_materials = ['ACOUSTIC', 'ELASTIC', 'TRANSVERSE_ISOTROPIC', 'ANISOTROPIC']

_syn_available_data_formats = ['ASCII']

_acceptable_source_prefixes = ['CMTSOLUTION', 'FORCESOLUTION']

_acceptable_smooth_types = ['laplacian', 'gaussian']

_required_binaries = ['xspecfem3D', 'xmeshfem3D', 'xcombine_sem', 'xcombine_vol_data_vtk']

_fwd_simulation_executables = ['bin/xmeshfem3D', 'bin/xspecfem3D']

_adj_simulation_executables = ['bin/xspecfem3D']

_absorb_wildcard = 'proc??????_reg?_absorb_buffer*'

_forward_array_wildcard = 'proc??????_save_forward_arrays*'

_model_databases = None

_kernel_databases = None

check()

Checks parameter validity for SPECFEM3D_GLOBE parameters

data_wildcard(comp='?')

Returns a wildcard identifier for synthetic data Currently only support for ASCII seismograms

Return type:

str

Returns:

wildcard identifier for channels

property kernel_databases

The location of kernel output files, for 3DGLOBE usually DATABASES_MPI. This can be determined by ‘LOCAL_PATH’ in the Par_file. Points to model_databases as it is assumed they are the same path

property model_databases

The location of model output files, for 3DGLOBE usually DATABASES_MPI. This can be determined by ‘LOCAL_PATH’ in the Par_file and must be defined relative to the main directory

adjoint_simulation(**kwargs)

Supers SPECFEM for adjoint solver and removes GLOBE-specific fwd files Also deals with anisotropic kernels (or lack thereof)

combine(input_paths, output_path, parameters=None)

Overwrite of xcombine_sem with an additional file check as SPECFEM3D_GLOBE requires file ‘mesh_parameters.bin’

Parameters:

• input_paths (str) – list of paths to directories containing binary files to be combined

• output_path (str) – path to export the outputs of xcombine_sem

• parameters (list) – optional list of parameters, defaults to self._parameters

smooth(input_path, output_path, parameters=None, span_h=None, span_v=None, use_gpu=False)

Override the smooth command to strip off part of the parameters that are not accepted for 3D_GLOBE smoothing.

Parameters:

• input_path (str) – path to data

• output_path (str) – path to export the outputs of xcombine_sem

• parameters (list) – optional list of parameters, defaults to self._parameters

• span_h (float) – horizontal smoothing length in meters

• span_v (float) – vertical smoothing length in meters

• use_gpu (bool) – whether to use GPU acceleration for smoothing. Requires GPU compiled binaries and GPU compute node.

combine_vol_data_vtk(input_path, output_path, hi_res=False, parameters=None)

Wrapper for ‘xcombine_vol_data_vtk’. Combines binary files together to generate a single .VTK file that can be visualized by external software like ParaView. Different call structure from Cartesian version.

Note

It is ASSUMED that this function is being called by system.run(single=True) so that we can use the main solver directory to perform the kernel summation task

Parameters:

• input_path (str) – path to files that are to be summed, can be different from the database files of the solver (e.g., if kernel files have been moved to another destination)

• output_path (strs) – path to export the outputs of xcombine_sem

• hi_res (bool) – Set the high resolution flag to 1 or True, which will generate .vtk files with data at EACH GLL point, rather than at each nodal vertex. These files are LARGE, and we discourage using `hi_res`==True unless you know you want these files.

• parameters (list) – list of parameter names that should be combined to get individual VTK files. Parameter names do NOT require the ‘reg’ prefix, e.g., submit ‘vsh_kernel’, not ‘reg1_vsh_kernel’

import_model(path_model)

SPECFEM3D_GLOBE acts differently than the Cartesian version when running GLL models. The User must put the GLL model files in directory DATA/GLL (default, manually set PATHNAME_GLL_modeldir in constants.h), and run the mesher to incorporate any model updates.

The updated GLL model files for iterative inversions need to be stored in a specific directory. Here it is hardcoded to the default value for SPECFEM3D_GLOBE constant PATHNAME_GLL_modeldir, which is specified in src/constants.h as “DATA/GLL”

Parameters:

path_model (str) – path to an existing starting model