pyrocko.gf.store

Storage, retrieval and summation of Green’s functions.

Classes

BaseStore(store_dir[, mode, use_memmap])	Low-level part of Green's function store implementation.
GFTrace([data, itmin, deltat, is_zero, ...])	Green's Function trace class for handling traces from the GF store.
Store(store_dir[, mode, use_memmap])	Green's function disk storage and summation machine.

class GFTrace(data=None, itmin=None, deltat=1.0, is_zero=False, begin_value=None, end_value=None, tmin=None)

Bases: object

Green’s Function trace class for handling traces from the GF store.

property t

Time vector of the GF trace.

Returns:

Time vector

Return type:

numpy.ndarray

class BaseStore(store_dir, mode='r', use_memmap=True)

Bases: object

Low-level part of Green’s function store implementation.

See Store.

class Store(store_dir, mode='r', use_memmap=True)

Bases: BaseStore

Green’s function disk storage and summation machine.

The Store can be used to efficiently store, retrieve, and sum Green’s function traces. A Store contains many 1D time traces sampled at even multiples of a global sampling rate, where each time trace has an individual start and end time. The traces are treated as having repeating end points, so the functions they represent can be non-constant only between begin and end time. It provides capabilities to retrieve decimated traces and to extract parts of the traces. The main purpose of this class is to provide a fast, easy to use, and flexible machanism to compute weighted delay-and-sum stacks with many Green’s function traces involved.

Individual Green’s functions are accessed through a single integer index at low level. On top of that, various indexing schemes can be implemented by providing a mapping from physical coordinates to the low level index i. E.g. for a problem with cylindrical symmetry, one might define a mapping from the coordinates (receiver_depth, source_depth, distance) to the low level index. Index translation is done in the pyrocko.gf.meta.Config subclass object associated with the Store. It is accessible through the store’s config attribute, and contains all meta information about the store, including physical extent, geometry, sampling rate, and information about the type of the stored Green’s functions. Information about the underlying earth model can also be found there.

A GF store can also contain tabulated phase arrivals. In basic cases, these can be created with the make_travel_time_tables() and evaluated with the t() methods.

config

The pyrocko.gf.meta.Config derived object associated with the store which contains all meta information about the store and provides the high-level to low-level index mapping.

store_dir

Path to the store’s data directory.

mode

The mode in which the store is opened: 'r': read-only, 'w': writeable.

classmethod create(store_dir, config, force=False, extra=None)

Create new GF store.

Creates a new GF store at path store_dir. The layout of the GF is defined with the parameters given in config, which should be an object of a subclass of Config. This function will refuse to overwrite an existing GF store, unless force is set to True. If more information, e.g. parameters used for the modelling code, earth models or other, should be saved along with the GF store, these may be provided though a dict given to extra. The keys of this dict must be names and the values must be guts type objects.

Parameters:

• store_dir (str) – GF store path

• config (Config) – GF store Config

• force (bool) – Force overwrite, defaults to False

• extra (dict or None) – Extra information

get_extra(key)

Get extra information stored under given key.

upgrade()

Upgrade store config and files to latest Pyrocko version.

put(args, trace)

Insert trace into GF store.

Store a single GF trace at (high-level) index args.

Parameters:

args (tuple) – Config index tuple, e.g. (source_depth, distance, component) as in ConfigTypeA.

Returns:

GF trace at args

Return type:

GFTrace

get(args, itmin=None, nsamples=None, decimate=1, interpolation='nearest_neighbor', implementation='c')

Retrieve GF trace from store.

Retrieve a single GF trace from the store at (high-level) index args. By default, the full trace is retrieved. Given itmin and nsamples, only the selected portion of the trace is extracted. If decimate is an integer in the range [2,8], the trace is decimated on the fly or, if available, the trace is read from a decimated version of the GF store.

Parameters:

• args (tuple) – Config index tuple, e.g. (source_depth, distance, component) as in ConfigTypeA.

• itmin (int or None) – Start time index (start time is itmin * dt), defaults to None

• nsamples (int or None) – Number of samples, defaults to None

• decimate (int) – Decimatation factor, defaults to 1

• interpolation (str) – Interpolation method ['nearest_neighbor', 'multilinear', 'off'], defaults to 'nearest_neighbor'

• implementation (str) – Implementation to use ['c', 'reference'], defaults to 'c'.

Returns:

GF trace at args

Return type:

GFTrace

sum(args, delays, weights, itmin=None, nsamples=None, decimate=1, interpolation='nearest_neighbor', implementation='c', optimization='enable')

Sum delayed and weighted GF traces.

Calculate sum of delayed and weighted GF traces. args is a tuple of arrays forming the (high-level) indices of the GF traces to be selected. Delays and weights for the summation are given in the arrays delays and weights. itmin and nsamples can be given to restrict to computation to a given time interval. If decimate is an integer in the range [2,8], decimated traces are used in the summation.

Parameters:

• args (tuple(numpy.ndarray)) – Config index tuple, e.g. (source_depth, distance, component) as in ConfigTypeA.

• delays (numpy.ndarray) – Delay times

• weights (numpy.ndarray) – Trace weights

• itmin (int or None) – Start time index (start time is itmin * dt), defaults to None

• nsamples (int or None) – Number of samples, defaults to None

• decimate (int) – Decimatation factor, defaults to 1

• interpolation (str) – Interpolation method ['nearest_neighbor', 'multilinear', 'off'], defaults to 'nearest_neighbor'

• implementation (str) – Implementation to use, ['c', 'alternative', 'reference'], where 'alternative' and 'reference' use a Python implementation, defaults to ‘c’

• optimization (str) – Optimization mode ['enable', 'disable'], defaults to 'enable'

Returns:

Stacked GF trace.

Return type:

GFTrace

make_decimated(decimate, config=None, force=False, show_progress=False)

Create decimated version of GF store.

Create a downsampled version of the GF store. Downsampling is done for the integer factor decimate which should be in the range [2,8]. If config is None, all traces of the GF store are decimated and held available (i.e. the index mapping of the original store is used), otherwise, a different spacial stepping can be specified by giving a modified GF store configuration in config (see create()). Decimated GF sub-stores are created under the decimated subdirectory within the GF store directory. Holding available decimated versions of the GF store can save computation time, IO bandwidth, or decrease memory footprint at the cost of increased disk space usage, when computation are done for lower frequency signals.

Parameters:

• decimate (int) – Decimate factor

• config (Config or None) – GF store config object, defaults to None

• force (bool) – Force overwrite, defaults to False

• show_progress (bool) – Show progress, defaults to False

get_stored_phase(phase_def, attribute='phase')

Get stored phase from GF store.

Returns:

Phase information

Return type:

pyrocko.spit.SPTree

t(timing, *args, attributes=None)

Compute interpolated phase arrivals.

Examples:

If test_store is a Type A store:

test_store.t('stored:p', (1000, 10000))
test_store.t('last{stored:P|stored:Pdiff}', (1000, 10000))
                                 # The latter arrival
                                 # of P or diffracted
                                 # P phase

If test_store is a Type B store:

test_store.t('S', (1000, 1000, 10000))
test_store.t('first{P|p|Pdiff|sP}', (1000, 1000, 10000))
                                 # The first arrival of
                                 # the given phases is
                                 # selected

Independent of the store type, it is also possible to specify two location objects and the GF index tuple is calculated internally:

test_store.t('p', source, target)

Parameters:

• timing (str or Timing) – travel-time definition

• *args ((tuple,) or (Location, Location)) – if len(args) == 1, args[0] must be a GF index tuple, e.g. (source_depth, distance, component) for a Type A store. If len(args) == 2, two location objects are expected, e.g. (source, receiver) and the appropriate GF index is computed internally.

• attributes (list of str) – additional attributes to return along with the time. Requires the attribute to be either stored or it must be supported by the phase calculation backend. E.g. ['takeoff_angle'].

Returns:

Phase arrival according to timing

Return type:

float or None

get_stored_attribute(phase_def, attribute, *args)

Return interpolated store attribute

Parameters:

• attribute (str) – takeoff_angle / incidence_angle [deg]

• *args (tuple) – Config index tuple, e.g. (source_depth, distance, component) as in ConfigTypeA.

get_many_stored_attributes(phase_def, attribute, coords)

Return interpolated store attribute

Parameters:

• attribute (str) – takeoff_angle / incidence_angle [deg]

• coords (numpy.ndarray) – numpy.ndarray, with columns being (source_depth, distance, component) as in ConfigTypeA.

make_stored_table(attribute, force=False)

Compute tables for selected ray attributes.

Parameters:

attribute (str) – phase / takeoff_angle [deg]/ incidence_angle [deg]

Tables are computed using the 1D earth model defined in earthmodel_1d for each defined phase in tabulated_phases.

make_timing_params(begin, end, snap_vred=True, force=False)

Compute tight parameterized time ranges to include given timings.

Calculates appropriate time ranges to cover given begin and end timings over all GF points in the store. A dict with the following keys is returned:

• 'tmin': time [s], minimum of begin timing over all GF points

• 'tmax': time [s], maximum of end timing over all GF points

• 'vred', 'tmin_vred': slope [m/s] and offset [s] of reduction velocity [m/s] appropriate to catch begin timing over all GF points

• 'tlenmax_vred': maximum time length needed to cover all end timings, when using linear slope given with (vred, tmin_vred) as start

make_travel_time_tables(force=False)

Compute travel time tables.

Travel time tables are computed using the 1D earth model defined in earthmodel_1d for each defined phase in tabulated_phases. The accuracy of the tablulated times is adjusted to the sampling rate of the store.

make_takeoff_angle_tables(force=False)

Compute takeoff-angle tables.

Takeoff-angle tables [deg] are computed using the 1D earth model defined in earthmodel_1d for each defined phase in tabulated_phases. The accuracy of the tablulated times is adjusted to 0.01 times the sampling rate of the store.

make_incidence_angle_tables(force=False)

Compute incidence-angle tables.

Incidence-angle tables [deg] are computed using the 1D earth model defined in earthmodel_1d for each defined phase in tabulated_phases. The accuracy of the tablulated times is adjusted to 0.01 times the sampling rate of the store.