A probabilistic earthquake source inversion framework. Designed and crafted in Mordor. https://pyrocko.org/grond
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

369 lines
15 KiB

Grond can be run as a command line tool (recommended) or by calling its library functions
from a Python script.
The command line tool offers several subcommands. To find out what subcommands
are available, run ::
grond --help
To get more information about a subcommand and its options, run ::
grond <subcommand> --help
The basic work-flow when using Grond is as follows:
1. Set up a project folder containing input data and Green's functions.
2. Set up a configuration file for Grond.
3. Check the set-up with :option:`grond check`.
4. Run the optimisation with :option:`grond go`.
5. Create result plots and report with :option:`grond report`.
6. Export results with :option:`grond check`.
Details on these steps are given in the following sections.
.. _project-layout:
Project folder layout
To use Grond with your data and earth model of your choice, we suggest the following folder structure.
Single files and data formats listed here are explained below. The folders ``runs`` and ``reports`` are generated during and after the optimisation, respectively.
.. code-block :: sh
├── config
│ ├── laquila2009_joint.gronf
│ ├── ...
│ :
├── data
│ └── events # several events could be set up here
│ ├── laquila2009
│ │ ├── event.txt
│ │ ├── insar
│ │ │   ├── dsc_insar.npz
│ │ │   ├── dsc_insar.yml
│ │ │ :
│ │ │
│ │ ├── waveforms
│ │ │ ├── raw # contains Mini-SEED files
│ │ │ │ ├── trace_BK-CMB--BHE_2009-04-06_00-38-31.mseed
│ │ │ │ ├── trace_BK-CMB--BHN_2009-04-06_00-38-31.mseed
│ │ │ │   :
│ │ │ └── stations.xml
│ │ │
│ │ └── gnss
│ │ └── gnss.yml
│ :
├── gf_stores # contains Green's functions
│ ├── Abruzzo_Ameri_nearfield # static near-field GF store
│ │ └── ...
│ ├── global_2s_25km # dynamic far-field GF store
│ │ └── ...
│ :
├── runs # created at runtime, contains individual optimisation results
│ └── ...
└── reports
└── ...
Input data (observables)
Grond can combine different observational input data in an earthquake source optimisation:
1. Seismic waveform data
Required input files are:
* raw waveform data (Mini-SEED format or other formats supported by `Pyrocko`_)
* instrument response information (StationXML format)
Various tools exists to download raw waveforms and instrument response information from `FDSN web services`_ (`here is a basic Python script example <https://pyrocko.org/docs/current/library/examples/fdsn_download.html>`_).
Grond can use continuous data (recommended) as well as event-based cut-outs. **If event-based data is used, make sure that the time windows are long enough.** Generously enlarge the window before and after the signal to be analysed. Add at least 5 times the longest period to be analysed to both sides. Add more if pre-event noise should be analysed for data-weighting.
2. InSAR data
Grond uses `Kite`_ containers for surface deformation maps.
`Kite`_ provides an interactive tool for inspection and transport of static displacement maps. It can be used for data noise estimations, easy quadtree data sub-sampling and calculation of data error variance-covariance matrices for proper data weighting.
Grond requires :file:`kite_scene.yml` and :file:`kite_scene.npz` which can be generated by `Kite`_.
3. GNSS data
Required input file is a simple `YAML`_ file containing GNSS station positions, displacement values and measurement uncertainties. The `Pyrocko`_ manual provides more information on the `GNSS data handling`_.
Green's functions stores
A Pyrocko Green's function (GF) store is needed for forward modelling seismograms and surface displacements. Such a GF store holds transfer functions for many possible source-receiver configurations which can be looked up quickly.
You can either download from the online repository (`online GF databases`_) or compute them with the `fomosto`_ module of `Pyrocko`_. Depending on the application, different set-ups of GF stores or methods for calculation are suitable:
.. _fomosto: https://pyrocko.org/docs/current/apps/fomosto/index.html
GFs for global teleseismic waveform data
For the point-source analysis of large global earthquakes, a global GF store with a sampling frequency of 0.5 Hz may suffice. Such a store can be downloaded with Fomosto, using
fomosto download kinherd global_2s store
GFs for regional and local seismic waveform data
Regional analyses may require region-specific GF stores. Given a suitable 1D-layered velocity model, GF stores can be built with the `Fomosto QSEIS backend`_.
GFs for near-field static displacement data (InSAR, GNSS)
Near-field static displacements require high spatial sampling and mostly only little temporal sampling. With the `Fomosto PSGRN/PSCMP backend`_, you can build your on GF store for any given local 1D-layered velocity model.
Grond is a rather large system. The following terminology may help to
understand its configuration and the underlying concepts and implementation
.. glossary::
A seismic event which has a unique name among all events available to a specific configuration of Grond. An event usually has a preliminary origin location and sometimes a reference mechanism attached to it.
Config file
A `YAML`_ file, by convention ending with the suffix ``.gronf``, containing a Grond configuration. The config file can be made to work with multiple events. It can be generated using :option:`grond init`.
The directory, by convention ending with the suffix ``.grun``, where Grond stores intermediate and final results during an optimisation run. The rundir is created by Grond when running the :option:`grond go` subcommand.
The dataset is a section in the config file telling Grond where to look for input data (waveforms, InSAR scenes, GNSS data) and meta-data (station coordinates, instrument responses, blacklists, picks, event catalogues, etc.).
The misfit is the value of the objective function obtained for a given source model proposal. The global misfit may by aggregated from weighted contributions of multiple Grond targets (see below).
In a typical Grond set-up, many modelling targets may contribute to the global misfit. For example, An individual modelling target could be a single component seismogram at a given station, an InSAR scene, or an amplitude ratio at one station. The target knows how to filter, taper, and weight the data. It also contains configuration about how to compare synthetics with the observations to obtain a misfit contribution value (e.g. time-domain traces/amplitude spectra/cross correlations, L1-norm/L2-norm, etc.).
In the context of a Grond set-up, the "problem" groups the choice of source model and parameter bounds to be used in the optimisation.
Before running the optimisation, station weights and other internal parameters may need to be adapted to the observed data and configured set-up of Grond. Such pre-optimisation tasks are done by one or more of Grond's analysers.
This refers to the optimisation strategy, how to sample model space to find solutions in a given Grond set-up.
Refers to Green's functions databases to be used for the forward modelling. In Grond these stores are adressed with paths and an individual ``store_id``.
Forward modelling in Grond is done through the Pyrocko GF engine, which allows fast forward modelling for arbitrary source models based on pre-calculated Green's functions stores (databases). Its configuration may contain information about where to find the pre-calculated Pyrocko Green's function stores.
Initializing a Grond project
Grond ships with two options to quickstart a new project folder structure (see
:ref:`project-layout`), including Grond's YAML configuration files. For real
data, you may use ``grond init <project-folder>`` (section
:ref:`project-init`). For synthetic testing, with ``grond scenario
<project-folder>`` a fully synthetic dataset can be customised and forward
modelled (section :ref:`project-scenario`).
.. _project-init:
Initializing an empty project
An empty project structure can be created with the subcommand :option:`grond init`. Different configurations can be added by flags, see ``grond init --help`` for more information.
.. code-block :: sh
grond init <project-folder>
cd <project-folder>
.. tip::
Existing project folders can be overwritten using ``grond init --force <project-folder>``
You can create an initial Grond configuration file for a centroid moment tensor optimisation based on global seismic waveforms with
.. code-block :: sh
grond init > config/<configfilename>.gronf
This is the default and corresponds to
.. code-block :: sh
grond init --target=waveforms > config/<configfilename>.gronf
Identically, for static near-field displacement (InSAR, GNSS data sets) and finite source optimisation set-ups, initial Grond configuration file can be created with
.. code-block :: sh
grond init --target=insar > config/<configfilename>.gronf
grond init --target=gnss > config/<configfile>.gronf
The ``targets`` (data and misfit setups for seismic waveforms, InSAR and or GNSS data) can be combined and sources types can be exchanged. A Grond configuration file showing all possible options with their default values is given using:
.. code-block :: sh
grond init --full > config/<configfilename>.gronf
.. _project-scenario:
Initializing a scenario project from forward modelling
The subcommand :option:`grond scenario` will forward model observations for a modelled earthquake and create a ready-to-go Grond project. Different observations and source problems can be added by flags - see ``grond scenario --help`` for possible combinations and options.
The scenario can contain the following synthetic observations:
* Seismic waveforms
* InSAR surface displacements
* GNSS surface displacements
.. code-block :: sh
grond scenario --targets=waveforms,insar <project-folder>
A map of the random scenario is plotted in :file:`scenario_map.pdf`.
Grond is configured using YAML files, see section :doc:`/config/index`.
Commented snippets of Grond configuration files explaining many options can be found here for
* point-source optimizations based on waveforms: :download:`config_example_waveforms.yaml </../../examples/config_example_waveforms.yaml>`
* finite source optimizations based on InSAR data: :download:`config_example_static.yaml </../../examples/config_example_static.yaml>`
TODO: update file ending to .gronf, check if these are up to date, maybe replace with examples from the tutorials
Or see the :doc:`/../../examples/index` for a detailed project walk-through.
Before running the optimisation, you may want to check your dataset and configuration file and debug it if needed with the command:
grond check <configfile> <eventname>
Now, you may start the optimization for a given event using
grond go <configfile> <eventname>
During the optimisation, results are aggregated in an output directory, referred to as `<rundir>` in the configuration and documentation.
.. code-block :: sh
├── config
│ └── ...
├── data
│ └── ...
├── gf_stores
│ └── ...
├── runs # contains individual optimisation results
│ ├── laquila2009_joint.grun
│ │ ├── ... # some bookkeeping yaml-files
│ │ ├── optimiser.yaml
│ │ ├── models
│ │ ├── misfits
│ │ └── harvest
│ │ ├── misfits
│ │ └── models
│ :
└── reports
└── ...
You find detailed information on the misfit configuration and model space sampling in the section :doc:`/config/optimisers/index`.
Results and visualisation
Finally, you may run
grond report <rundir>
to aggregate and visualize results to a browsable summary, (by default) under the directory `reports`.
.. code-block :: sh
├── config
│ └── ...
├── data
│ └── ...
├── gf_stores
│ └── ...
├── runs
│ └── ...
└── reports # contains all graphical presentations of the results in 'runs'
├── index.html # open in browser to surf through all 'runs'
├── ... # more bookeeping yaml-files
├── laquila2009 # event-wise organisation of different optimisation runs
│ ├── laquila2009_joint # report information of an optimisation run
│ │ ├── ... # some bookkeeping yaml-files
│ │ └── plots # individual plots sorted by type
│ │ ├── contributions # overview of the target's misfit contributions
│ │ │ └── ...
│ │ ├── sequence # parameter value development in the optimisation
│ │ │ └── ...
│ │ ├── fits_waveforms # visual comparison of data and synthetics
│ │ │ └── ...
│ │ ├── fits_satellite # visual comparison of data and synthetics
│ │ │ └── ...
│ │ :
Please find detailed information on the reports and automatic plots in the section :doc:`/report/index`.
The results can be exported in various ways by running the subcommand
grond export <what> <rundir>
.. _YAML: https://en.wikipedia.org/wiki/YAML .. _Optimisers: ../library/optimisers.html
.. _Result Plots: ./plots_docu.html
.. _Kite: https://pyrocko.org/docs/kite/current/
.. _GNSS data handling: https://pyrocko.org/docs/current/library/examples/gnss_data.html
.. _downloadwave: https://pyrocko.org/docs/current/library/examples/fdsn_download.html
.. _qseis: https://pyrocko.org/docs/current/apps/fomosto/tutorial.html#creating-a-new-green-s-function-store
.. _psgrn: https://pyrocko.org/docs/current/apps/fomosto/tutorial.html#creating-a-new-green-s-function-store
.. _online GF databases: http://kinherd.org:8080/gfws/static/stores/
.. _GF stores: http://kinherd.org:8080/gfws/
.. _Pyrocko: https://pyrocko.org/
.. _Fomosto QSEIS backend: https://pyrocko.org/docs/current/apps/fomosto/backends.html#the-qseis-backend
.. _Fomosto PSGRN/PSCMP backend: https://pyrocko.org/docs/current/apps/fomosto/backends.html#the-psgrn-pscmp-backend
.. _FDSN web services: https://www.fdsn.org/webservices/