README.md 9.88 KB
Newer Older
Sebastian Heimann's avatar
Sebastian Heimann committed
1
2
# Grond

Sebastian Heimann's avatar
Sebastian Heimann committed
3
4
5
6
7
8
A bootstrap-based probabilistic battering ram to explore solution spaces in
earthquake source parameter estimation problems.


## Installation

9
First, install [Pyrocko](http://pyrocko.org/docs/current/install/),
Sebastian Heimann's avatar
Sebastian Heimann committed
10
11
12
13
14
15
16
17
18
then install Grond:

```bash
git clone https://gitext.gfz-potsdam.de/heimann/grond.git
cd grond
sudo python setup.py install
```


Sebastian Heimann's avatar
Sebastian Heimann committed
19
20
21
## Updating an existing installation

```bash
Sebastian Heimann's avatar
Sebastian Heimann committed
22
cd grond  # change to the directory to where you cloned grond initially
Sebastian Heimann's avatar
Sebastian Heimann committed
23
24
25
26
git pull origin master
sudo python setup.py install
```

Henriette Sudhaus's avatar
Henriette Sudhaus committed
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
## Basic setup of data

To use grond with your data we suggest the following folder stucture:

```
data
└── events
    ├── laquila2009
    │   ├── event.txt
    │   ├── insar
    │   │   ├── dsc_LAquila2009_Envisat.npz
    │   │   └── dsc_LAquila2009_Envisat.yml
    │   └── waveforms
    │       ├── raw
    │       │   └── 2009-04-06_MW6.3_Central_Italy.421793.seed
    │       └── stations.xml
```
Sebastian Heimann's avatar
Sebastian Heimann committed
44

Sebastian Heimann's avatar
Sebastian Heimann committed
45
## Basic usage
Sebastian Heimann's avatar
Sebastian Heimann committed
46
47
48
49

Grond can be run as a command line tool or by calling Grond's library functions
from a Python script. To get a brief description on available options of
Grond's command line tool, run `grond --help` or `grond <subcommand> --help`.
Sebastian Heimann's avatar
Sebastian Heimann committed
50
51
52
53
54
55
56
57
58
59
60
Once dataset and configuration are ready, the command
`grond go <configfile> <eventname>` starts the optimization algorithm for a
selected event. Before running the optimization, to debug problems with the
dataset and configuration, use `grond check <configfile> <eventname>`. To get a
list of event names available in a configured setup, run
`grond events <configfile>`. During the optimization, results are aggregated in
a directory, referred to in the configuration as `<rundir>`. To visualize the
results run `grond plot <plotnames> <rundir>`. The results can be exported in
various ways by running the subcommand `grond export <what> <rundir>`. Finally,
you may run `grond report <rundir>` to aggregate results to a browsable
summary, (by default) under the directory `reports`.
Sebastian Heimann's avatar
Sebastian Heimann committed
61

62
63
64
65
66
67
68
69

## Example configuration file

```yaml
%YAML 1.1
--- !grond.Config

# Path, where to store output (run-directories)
Sebastian Heimann's avatar
Sebastian Heimann committed
70
rundir_template: 'gruns/${problem_name}.run'
71
72
73
74
75
76
77
78

# -----------------------------------------------------------------------------
# Configuration section for dataset (input data)
# -----------------------------------------------------------------------------

dataset_config: !grond.DatasetConfig

  # List of files with station coordinates
Sebastian Heimann's avatar
Sebastian Heimann committed
79
  stations_stationxml_paths:
Sebastian Heimann's avatar
Sebastian Heimann committed
80
81
  - 'events/${event_name}/responses-geofon.stationxml'
  - 'events/${event_name}/responses-iris.stationxml'
82
83

  # File with hypocenter information and possibly reference solution
Sebastian Heimann's avatar
Sebastian Heimann committed
84
  events_path: 'events/${event_name}/prepared/event.txt'
85
86

  # List of directories with raw waveform data
Sebastian Heimann's avatar
Sebastian Heimann committed
87
  waveform_paths:
Sebastian Heimann's avatar
Sebastian Heimann committed
88
  - 'events/${event_name}/raw'
89
90

  # List of files with instrument response information
Sebastian Heimann's avatar
Sebastian Heimann committed
91
  responses_stationxml_paths:
Sebastian Heimann's avatar
Sebastian Heimann committed
92
93
  - 'events/${event_name}/responses-geofon.stationxml'
  - 'events/${event_name}/responses-iris.stationxml'
94
95

  # List with station/channel codes to exclude
Sebastian Heimann's avatar
Sebastian Heimann committed
96
97
98
99
100
101
102
103
104
  #blacklist: ['STA','NET.STA', 'NET.STA.LOC', 'NET.STA.LOC.CHA']

  # Same but using a file, one exclusion entry per line
  blacklist_paths:
  - 'events/${event_name}/blacklist.txt'

  # Make available picks for forced trace alignment, file must be in Pyrocko's
  # marker file format
  #picks_paths: ['events/${event_name}/picks.markers']
105
106
107
108
109
110
111
112
113
114
115
116
117


# -----------------------------------------------------------------------------
# Configuration section for synthetic seismogram engine (configures where
# to look for GF stores)
# -----------------------------------------------------------------------------

engine_config: !grond.EngineConfig

  # Whether to use GF store directories listed in ~/.pyrocko/config.pf
  gf_stores_from_pyrocko_config: false

  # List of directories with GF stores
Sebastian Heimann's avatar
Sebastian Heimann committed
118
119
  gf_store_superdirs:
  - 'gf_stores'
120
121
122
123
124
125
126
127
128


# -----------------------------------------------------------------------------
# Configuration section selecting data to be included in the data fitting
# procedure. This defines the objective function to be minimized in the
# optimization procedure. It can be composed of one or more contributions, each
# represented by a !grond.TargetConfig section.
# -----------------------------------------------------------------------------

Sebastian Heimann's avatar
Sebastian Heimann committed
129
target_groups:
130

Sebastian Heimann's avatar
Sebastian Heimann committed
131
- !grond.WaveformTargetGroup
132

Sebastian Heimann's avatar
Sebastian Heimann committed
133
134
  # misfits are normalized within each normalization_family separately
  normalization_family: 'td'
135
136

  # Name of the group to which this contribution belongs
Sebastian Heimann's avatar
Sebastian Heimann committed
137
  path: 'td.rayleigh'
138
139

  # Minimum distance of stations to be considered
Sebastian Heimann's avatar
Sebastian Heimann committed
140
  distance_min: 0e3
141
142

  # Maximum distance of stations to be considered
Sebastian Heimann's avatar
Sebastian Heimann committed
143
  distance_max: 1000e3
144
145

  # List with names of channels to be considered
Sebastian Heimann's avatar
Sebastian Heimann committed
146
  channels: ['Z']
147
148
149
150
151

  # How to weight stations from this contribution in the global misfit
  weight: 1.0

  # Subsection on how to fit the traces
Sebastian Heimann's avatar
Sebastian Heimann committed
152
  misfit_config: !grond.WaveformMisfitConfig
153
154

    # Frequency band [Hz] of acausal filter (flat part of frequency taper)
Sebastian Heimann's avatar
Sebastian Heimann committed
155
156
    fmin: 0.01
    fmax: 0.05
157
158
159
160
161
162

    # Factor defining fall-off of frequency taper
    # (zero at fmin/ffactor, fmax*ffactor)
    ffactor: 1.5

    # Time window to include in the data fitting. Times can be defined offset
Sebastian Heimann's avatar
Sebastian Heimann committed
163
164
    # to given phase arrivals. E.g. '{stored:begin}-100' would mean 100 s
    # before arrival of the phase named 'begin', which must be defined in the
Sebastian Heimann's avatar
Sebastian Heimann committed
165
166
167
168
169
    # travel time tables in the GF store.

    tmin: '{stored:anyP_no_Pdiff}'
    tmax: '{vel_surface:2.5}'

Sebastian Heimann's avatar
Sebastian Heimann committed
170
171
172
    # Align traces by picks (will lose some control on origin time and
    # location). Define the synthetic phasename, for which a travel time table
    # must be available in the GF store,
Sebastian Heimann's avatar
Sebastian Heimann committed
173
    #pick_synthetic_traveltime: 'anyP_no_Pdiff'
Sebastian Heimann's avatar
Sebastian Heimann committed
174
    # and the name of the picks to use in the picks file (defined in
Sebastian Heimann's avatar
Sebastian Heimann committed
175
176
    # dataset_config)
    #pick_phasename: 'P'
177
178
179

    # How to fit the data (available choices: 'time_domain',
    # 'frequency_domain', 'absolute', 'envelope', 'cc_max_norm')
Sebastian Heimann's avatar
Sebastian Heimann committed
180
    domain: 'time_domain'
181

Sebastian Heimann's avatar
Sebastian Heimann committed
182
183
184
185
186
187
188
189
190
    # allow for some time-shifting of individual traces, maximum shift [s]
    tautoshift_max: 4.0

    # whether to penalise time-shifting (0.0 for no penalty)
    autoshift_penalty_max: 0.0

    # exponent of the norm used when comparing traces, 1 or 2
    norm_exponent: 1

191
  # How to interpolate the Green's functions (available choices:
Sebastian Heimann's avatar
Sebastian Heimann committed
192
  # 'nearest_neighbor', 'multilinear'). Note that the GFs have to be densely
Sebastian Heimann's avatar
Sebastian Heimann committed
193
  # sampled when using interpolation other than nearest_neighbor.
Sebastian Heimann's avatar
Sebastian Heimann committed
194
  interpolation: 'nearest_neighbor'
195
196

  # Name of GF store to use
Sebastian Heimann's avatar
Sebastian Heimann committed
197
  store_id: 'global_2s'
198
199
200


# A second contribution to the misfit function (for descriptions, see above)
Sebastian Heimann's avatar
Sebastian Heimann committed
201
202
203
204
205
206
- !grond.WaveformTargetGroup
  normalisation_family: 'td'
  path: 'td.love'
  distance_min: 0e3
  distance_max: 1000e3
  channels: [T]
207
  weight: 1.0
Sebastian Heimann's avatar
Sebastian Heimann committed
208
209
210
211
  #limit: 20
  misfit_config: !grond.WaveformMisfitConfig
    fmin: 0.01
    fmax: 0.05
212
    ffactor: 1.5
Sebastian Heimann's avatar
Sebastian Heimann committed
213
214
215
216
217
218
219
220
    tmin: 'stored:anyP_no_Pdiff'
    tmax: 'vel_surface:2.5'
    domain: time_domain
    tautoshift_max: 4.0
    autoshift_penalty_max: 0.0
    norm_exponent: 1
  interpolation: nearest_neighbor
  store_id: 'global_2s'
221
222
223
224
225
226
227
228
229
230


# -----------------------------------------------------------------------------
# Definition of the problem to be solved - source model, parameter space, and
# global misfit configuration settings.
# -----------------------------------------------------------------------------

problem_config: !grond.CMTProblemConfig

  # Name used when creating output directory
Sebastian Heimann's avatar
Sebastian Heimann committed
231
  name_template: 'timedomain_${event_name}'
232
233
234
235

  # Definition of model parameter space to be searched in the optimization
  ranges:
    # Time relative to hypocenter origin time [s]
Sebastian Heimann's avatar
Sebastian Heimann committed
236
    time: '-10 .. 10 | add'
237
238

    # Centroid location with respect to hypocenter origin [m]
Sebastian Heimann's avatar
Sebastian Heimann committed
239
240
    north_shift: '-40e3 .. 40e3'
    east_shift: '-40e3 .. 40e3'
241
242
243
    depth: '0 .. 50e3'

    # Range of magnitudes to allow
Sebastian Heimann's avatar
Sebastian Heimann committed
244
    magnitude: '4.0 .. 7.0'
245
246
247
248
249
250
251
252
253
254

    # Relative moment tensor component ranges (don't touch)
    rmnn: '-1.41421 .. 1.41421'
    rmee: '-1.41421 .. 1.41421'
    rmdd: '-1.41421 .. 1.41421'
    rmne: '-1 .. 1'
    rmnd: '-1 .. 1'
    rmed: '-1 .. 1'

    # Source duration range [s]
Sebastian Heimann's avatar
Sebastian Heimann committed
255
    duration: '0. .. 0.'
256
257
258
259
260
261

  # Clearance distance around stations (no models with origin closer than this
  # distance to any station are produced by the sampler)
  distance_min: 0.

  # Type of moment tensor to restrict to (choices: 'full', 'deviatoric')
Sebastian Heimann's avatar
Sebastian Heimann committed
262
  mt_type: 'deviatoric'
263
264
265
266
267

  # Whether to apply automatic weighting to balance the effects of geometric
  # spreading etc.
  apply_balancing_weights: true

Sebastian Heimann's avatar
Sebastian Heimann committed
268
  # Under what norm to combine targets into the global misfit
Sebastian Heimann's avatar
Sebastian Heimann committed
269
270
271
272
  # (exponent of norm, 1 or 2)
  norm_exponent: 1


273
# -----------------------------------------------------------------------------
Sebastian Heimann's avatar
Sebastian Heimann committed
274
275
# Configuration of the optimization procedure. The following example setup will
# run a Bayesian bootstrap optimization (BABO).
276
277
# -----------------------------------------------------------------------------

Sebastian Heimann's avatar
Sebastian Heimann committed
278
279
280
281
282
283
284
optimizer_config: !grond.HighScoreOptimizerConfig

  # Number of bootstrap realizations to be tracked simultaneously in the
  # optimization
  nbootstrap: 100

  sampler_phases:
285

Sebastian Heimann's avatar
Sebastian Heimann committed
286
  - !grond.UniformSamplerPhase
287

Sebastian Heimann's avatar
Sebastian Heimann committed
288
289
      # Number of iterations to operate in 'uniform' phase
      niterations: 1000
290

Sebastian Heimann's avatar
Sebastian Heimann committed
291
  - !grond.DirectedSamplerPhase
292

Sebastian Heimann's avatar
Sebastian Heimann committed
293
294
      # Number of iterations to operate in 'directed' phase
      niterations: 10000
295

Sebastian Heimann's avatar
Sebastian Heimann committed
296
      # Multiplicator for width of sampler distribution to start with
Sebastian Heimann's avatar
Sebastian Heimann committed
297
      scatter_scale_begin: 2.0
298

Sebastian Heimann's avatar
Sebastian Heimann committed
299
      # Multiplicator for width of sampler distribution at end of this phase
Sebastian Heimann's avatar
Sebastian Heimann committed
300
      scatter_scale_end: 0.5
301
302
303
304
305
306
307
308
309
310
311


# -----------------------------------------------------------------------------
# Configuration of pre-optimization analysis phase. E.g. balancing weights are
# determined during this phase.
# -----------------------------------------------------------------------------

analyser_config: !grond.AnalyserConfig

  # Number of iterations (number of models to forward model in the analysis,
  # larger number -> better statistics)
Sebastian Heimann's avatar
Sebastian Heimann committed
312
  niterations: 1000
313
```