.. _toast_simulations: Simulations =========== There are several ways to create new simulations: * :ref:`Automatically ` via |scname| messaging connection, * :ref:`Manually ` via CTRL+N, * :ref:`Interactively ` by the user. .. _toast_sim_automatic: Automatic Simulation and Configuration -------------------------------------- .. TODO:: Done by toastd now. Update accordingly. Confvals not availiable in |toastg| anymore but in trigger of |toastd| queue. :term:`Incidents ` and simulations are automatically triggered for events and event updates received via messaging connection to a |scname| system. They are initiated if passing multiple filters and thresholds. .. _fig-sim_flowchart: .. figure:: media/toast/sim/sim_flowchart.png :align: center :width: 20 cm Flowchart for the automatic generation of simulations First, it is checked whether the earthquake magnitude is larger than :confval:`incidentMinimumMagnitude` and whether the earthquake depth is shallower than :confval:`incidentMaximumDepth`. If a new event was received, then a new incident is created, if an event update was received, the incident is updated. Next, following settings are checked: * :confval:`trigger.maximumAge` * :confval:`trigger.minimumMagnitude` * :confval:`trigger.origin.mode` * :confval:`sourceRegions` See also: :ref:`toast_source_regions`. Then, depending on availability of a Moment Tensor (MT) solution and the configured faults, either 1, 2 or 3 simulations are proposed. 3 simulations are proposed if the normalized minimum rotation angle (see also: :term:`Kagan angle`) between the model from the configured faults and the 2 models corresponding to the nodal planes of the MT solution is larger than 0.7, otherwise it is assumed that the 2 solutions from the MT are sufficient. The simulations are finally started after checking that no similar simulations are already present according to the criteria defined in: * :confval:`matching.magnitude.variance` * :confval:`matching.depth.variance` * :confval:`matching.location.variance` * :confval:`matching.faultPlane.variance` (:term:`Kagan angle`). Enable :confval:`processAutoMT` to use automatically generated moment tensors and set the mode of the origin (manual, automatic or both) in :confval:`trigger.origin.mode`. As input, simulations use default values, which can be configured using: :program:`scconfig` :menuselection:`--> Modules --> gempa --> easywave2 --> easywave2`: Consult hovertips in :program:`scconfig` for more information. By default, :confval:`easywave2.patches.strikeAlign` and :confval:`easywave2.patches.dipAlign` are set to 0.5, which means that the generated patches are centered around the epicenter. They can be set to a list, for example: 0,0.5,1, which means that additional 2 simulations are generated, shifted by half length (or width). .. _note-number_sim: .. note:: The number of simulations that are generated according to: :ref:`fig-sim_flowchart` is multiplied by the number of registered automatic :ref:`toast_sim_profiles` and by the length of :confval:`easywave2.patches.strikeAlign` and :confval:`easywave2.patches.dipAlign`. In case no moment tensor and fault information is available or if the automatic patch generation doesn't deliver optimal results, the simulation dialog can be used to initiate a simulation interactively (see: :ref:`toast_sim_interactive`). .. TODO:: * Suggestion: always generate simulation using fault info if present! (and simplify flow) * Because one would always like to see the "expected" source * Current criterium is hard coded: Rotation angle residual > 0.7 => 3 sim * Bernd: Generally agree but first check that for updated FM solution not always Fault sim best fit, maybe adapt total residual weights .. _toast_sim_profiles: Simulation Profiles ~~~~~~~~~~~~~~~~~~~ Automatic simulation generation produces results based on default parameters. Multiple simulation profiles can be added and used. All available profiles are listed in :menuselection:`Menu --> Simulation` after definition and registration in :confval:`easywave2.profiles`. Each simulation profile is executed when triggering the automatic simulations (if *automatic* is set in the profile). Note that the same thresholds and filters are applied as mentioned in :ref:`toast_sim_automatic`. If a profile is configured to start automatically, the default automatic simulation is not triggered. .. _toast_sim_manual: Start simulations for events imported from database --------------------------------------------------- If an event is not received by messaging but imported from the database by the user, simulations are not triggered automatically. But they can be initiated using CTRL+N. In this case the processing starts at the point as indicated in :ref:`fig-sim_flowchart`. .. _toast_sim_interactive: Create simulations interactively -------------------------------- In order to add simulations manually to an :term:`incident `, open the *Simulation Dialog* via: :menuselection:`Menu --> Simulation --> Start interactive` or with Ctrl+Shift+N. The dialog opens with a set of predefined settings for the earthquake model and its geometry as well as for the simulation backend to be used. See :ref:`toast_rupture_settings` and :ref:`toast_backend_settings` for a description. After adjusting the settings, click *Generate patches* for automatic, or *Draw patches* for :ref:`manual patch creation `. Click *Start* to compute the simulation. During computation, the progress is indicated in the :ref:`database panel `. Double click the simulation to turn it :ref:`active ` (also possible during computation). .. _toast_rupture_settings: Rupture settings ~~~~~~~~~~~~~~~~ .. _fig-sim_rupture: .. figure:: media/toast/sim/sim_dialog_rupture.png :align: center :width: 14 cm Simulation setup - Rupture * Latitude / Longitude. Select between *Event*, *Focal Mechanism*, *Origin* or *Custom* by clicking the icon on the left of the latitude value. * Magnitude: Adjust or select the requested value as above. * Depth: Use value from *Event*, *Fault*, *Focal Mechanism*, *Origin* or *Custom*. * Length, Width: Default values are computed using scaling relations by *Wells & Coppersmith (1994)*. If you manually change one of the two, the behavior of the other one and of the resulting slip depends on the selection below * [L]ength and [W]idth independent: Manual modification of L or W is compensated by adjusting [S]lip (L x W x S remains constant for given magnitude) * Fix Area: Change of L is automatically compensated by change of W and vice versa * Fix Ratio: Change of L results in change of W and adjustment of S (and vice versa) * Fault plane: * From fault: Strike, dip and rake are interpolated automatically from the predefined :ref:`toast_fault_geometry_configuration`. * Strike from fault: Set dip and rake values manually. * Manual: Set all values manually. * Moment tensor: When available strike, dip and rake of the first or second nodal plane can be selected. * Strike and Dip align: By default, the automatically generated fault patches are centered around the epicenter. Use the sliders to shift the patches along strike and dip direction up to half total length and width. * # Patches: The number of patches to be generated or drawn. Corresponding patch length is shown below. .. _toast_gen_patches_auto: Generate patches automatically ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Click *Generate patches* to use above settings for the automatic generation of the rupture patches of the earthquake fault model. .. _toast_draw_patches: Draw patches manually ^^^^^^^^^^^^^^^^^^^^^ .. _fig-draw_patches: .. figure:: media/toast/sim/draw_patches.png :align: center :width: 11 cm Simulation setup - Draw patches manually Click *Draw patches* to enter the location and strike direction of the rupture patches manually on the map. Other parameters are according to the values in the dialog. Use left mouse click to add patches one by one up to the defined number of patches. While drawing, the dashed white circle has as radius the total rupture length, while the dotted white circle has half that radius. It can be used as visualization guide to place the epicenter in the middle of the patches. The green circle has as radius one patch length and the next end point is indicated by the red dot on the circle. Dipping of the patches is always to the right side. For example, if the starting point is in the South and the end point is in the North, the dipping direction is East. It can be changed during drawing by SHIFT+mouse clicking on the end point of a patch (only if more than 1 patch in total). .. note:: Make sure that the green edge of a patch, which is the lower edge, is in accordance with to the local tectonic setting (e.g. compare to configured faults). .. _toast_backend_settings: Simulation backend settings ~~~~~~~~~~~~~~~~~~~~~~~~~~~ The *Simulations* tab is used to select and configure the plugin which is used as simulation backend. .. _fig-sim_simulations: .. figure:: media/toast/sim/sim_dialog_backends.png :align: center :width: 14 cm Simulation setup - Simulations The standard plugin which is delivered with |toast| is :ref:`EasyWave2 `. The settings are: * step * sshMax: Simulation time step in min for the output of the sshMax grid during computation (same file is overwritten). * ssh: Simulation time step in min for the output of ssh grids (new file for every time step). * poi: Simulation time step in seconds for the output of time series. * arrival times: Simulation time step for the output of the arrival grid during computation (same file is overwritten). * maxTime: Total duration of the simulation in minutes. * grid: Select the bathymetry which is used for the simulation, see also: :ref:`toast_bathymetry_files_configuration`. The green rectangle in :ref:`toast_map_perspective` corresponds to the borders of the selected bathymetry. * gpu: Select if the simulation is computed using GPU. See also: :ref:`toast_gpu`. Click on the *+* tab to add another plugin configuration. For instance for *TsunAWI*, you can set the values for *Azimuth* and *Magnitude uncertainty*. .. note:: |ewname| does not compute tides, this is why in the :ref:`toast_waveform_picker` the *Tsunami* waveform filter should be applied to observations for comparison. .. _toast_display_simulation_results: Display simulation results -------------------------- The results of the :ref:`active simulations(s) ` are used in various :ref:`perspectives `, like the Map-, Arrivals- and Forecast Zones perspective as well as the :ref:`toast_live_tabs_perspective`. Use the :ref:`toast_map_layers_panel`, under *Wave propagation*, to enable the display of simulation results in the :ref:`toast_map_perspective` and the :ref:`toast_wave_propagation_panel`. Select 'Legends' to turn on legend color bars in :ref:`toast_map_perspective`. See also: :ref:`toast_color_profiles`. .. _toast_arrival_lines: Arrival lines ~~~~~~~~~~~~~ Show the propagation of the tsunami wave after event time as contour lines. Solid lines have one hour interval and are labeled. Dashed lines are half-hour intervals in-between. .. _fig-arrival_lines_times: .. figure:: media/toast/same_size/arrival_lines_times.png :align: center :width: 18 cm Map perspective with Arrival lines and times features selected .. _toast_arrival_times: Arrival times ~~~~~~~~~~~~~ Display the arrival of the tsunami wave as color coded areas see figure above). By default, arrival within 1 hour is red, between 1 and 3 hours is orange, and between 3 and 6 hours is yellow (see legend). .. _toast_bathymetry: Bathymetry ~~~~~~~~~~ Turns on display of the Ocean model which was used for the simulation (currently only for binary grids for |ewname|). This can be very useful for instance if results in small harbors are not as expected, as the bathymetry and topography used for the simulations depends on resolution and is not identical to the one shown as map background. Use right mouse click -> Filter -> Nearest on the map to switch off interpolation and get a sharper image. .. _fig-bathymetry: .. figure:: media/toast/same_size/bathymetry.png :align: center :width: 18 cm Left: bathymetry used for simulation, right: map background. .. _toast_isochrones: Isochrones ~~~~~~~~~~ Show the extent of the tsunami at a certain time as red line. Use the :ref:`toast_sim_player` to select the time. .. _toast_ssh: SSH ~~~ Display wave height according to :ref:`active ` simulations at certain time. Use the :ref:`toast_sim_player` to select the time. .. _fig-ssh: .. figure:: media/toast/same_size/ssh.png :align: center :width: 18 cm Map perspective with SSH feature selected, at time zero (initial sea floor deformation) .. _toast_sshmax: SSH max ~~~~~~~ Display maximum wave height according to :ref:`active ` simulations. It is updated while a simulation is being computed. .. _fig-ssh_max: .. figure:: media/toast/same_size/ssh_max.png :align: center :width: 18 cm Map perspective with SSH max feature selected .. _toast_residual: Residual -------- The residual is used to rank simulations based on the comparison of incident parameters and observations with simulation data. Each simulation is assigned one total or overall residual. In *Icons view*, it is shown in form of the color of the left and lower bars, in *Details view*, it is show in the column *Residual* and the partial residual. The residual is a measure of misfit. A value of 0 represents perfect fit. There is no upper limit. The color range is from green to red based on following definitions: For residual 0 -> green; 0.5 -> yellow; 1 -> red. .. _toast_residual_total: Total residual ~~~~~~~~~~~~~~ The total (or overall) residual is computed as weighted root mean square (RMS) over the source, focal mechanism, expected plane, arrival and displacement residuals. .. math:: R_{total} = \sqrt{\frac{W_s * R_{source}^2 + W_{fm} * R_{fm}^2 + W_{ep} * R_{ep}^2 + W_{arr} * R_{arr}^2 + W_{displ} * R_{displ}^2}{N_{sr}}} The weights are configurable. :math:`N_{sr}` is the number of available sub-residuals. .. _toast_residual_source: Source residual ~~~~~~~~~~~~~~~ The source (or event) residual is computed as root mean square over the distance, magnitude and depth residuals. .. math:: R_{source} = \sqrt{\frac{R_{dist}^2 + R_{mag}^2 + R_{depth}^2}{N_{rc}}} :math:`N_{rc}` is the number of available source residual components. For backwards compatibility, the former definition of the source, distance, magnitude and depth residuals can be used by setting the configuration variable :confval:`residuals.useLegacyDefinition`. .. _toast_residual_dist: Distance residual ~~~~~~~~~~~~~~~~~ If only either the hypocenter or the centroid location is given, then the distance residual is computed as distance between the location and the location of the simulation divided by a characteristic length. .. math:: R_{dist} = \frac{d(incident, simulation)}{L_{char}} The characteristic length is derived by scaling relations (Wells and Coppersmith 1994) from the incident magnitude. .. math:: L_{char} = 10^{-2.42 + 0.58 * M} If the incident has no magnitude, then the characteristic length is derived for M=7, which results in about 44 km. At a distance of :math:`L_{char}` from the origin, the residual is 1. If both hypocenter and centroid are given, then the distance is computed as weighted distance of the simulation to the centroid and the hypocenter. .. math:: R^W_{dist} = \frac{cw * d(centr, simu) + (1-cw) * d(hypo, simu) - min(cw, (1-cw) * d(cent, hypo)}{L_{char}} with centroid weight :math:`cw=0.75`. A simulation has the lowest residual (best match) at the centroid location, but the residual is extended in the direction of the hypocenter (egg-shaped contour). .. _toast_residual_mag: Magnitude residual ~~~~~~~~~~~~~~~~~~ It is computed as absolute magnitude difference divided by a characteristic magnitude difference. .. math:: R_{mag} = \frac{|M_{incident} - M_{simulation}|}{M^\textit{diff}_{char}} with :math:`M^\textit{diff}_{char}=0.4`. If the incident has no magnitude, the magnitude residual is 0. If the simulation has no magnitude, the magnitude residual is set to 1. .. _toast_residual_depth: Depth residual ~~~~~~~~~~~~~~ It is computed as absolute depth difference divided by a characteristic depth difference. .. math:: R_{depth} = \frac{|D_{incident} - D_{simulation}|}{D^\textit{diff}_{char}} with :math:`D^\textit{diff}_{char}=80 \text{ km}`. If the incident has no depth, the depth residual is 0. If the simulation has no depth, the depth residual is set to 1. .. _toast_residual_fm: Focal mechanism residual ~~~~~~~~~~~~~~~~~~~~~~~~ The focal mechanism (or moment tensor) residual is computed based on the rotation angle between the fault plane of the simulation and the fault plane of the focal mechanism. .. _toast_residual_fault: Fault residual ~~~~~~~~~~~~~~ The fault (or exected plane) residual is computed based on the rotation angle between the fault plane of the simulation and the expected fault plane from the faults. .. _toast_residual_arr: Arrival residual ~~~~~~~~~~~~~~~~ The arrival (or tide gauge) residual is computed as root mean square between observed and simulated arrrivals. .. _toast_residual_displ: Displacement residual ~~~~~~~~~~~~~~~~~~~~~ If displacements were computed by simulations and if for at least one GNSS station either both the east and north components or the up component of the observed displacement are present, then the mismatch between observed and simulated displacements is computed in form of the displacement residual and shown in the :ref:`database panel `. The residual is computed in following way: .. math:: Misfit &= \sqrt{\sum_{i}^{Stations} \sum_{j=E,N,U}^{Components} a_{ij} \cdot (d_{ij}^{o}-d_{ij}^{s})^2} \\[10pt] Totlen &= \sqrt{\sum_{i}^{Stations} \sum_{j=E,N,U}^{Components} a_{ij} \cdot (d_{ij}^{o})^2} \\[10pt] R_{displ} &= \frac{Misfit}{\max \left( Totlen, \varepsilon \right)} The misfit is the root of the sum of the vector difference lengths between observations and simulations. The total length is the root of the sum of all observation vector lengths. :math:`a_{ij}^{}=1^{{}}` if observed as well as simulated vertical components or both horizontal components are present and :math:`a_{ij}=0^{{}}` otherwise. The constant :math:`\boldsymbol\varepsilon` is set 0.1 m. It relaxes the computation of the residual if the total length is smaller than 10 cm and also avoids division by zero. In practice this would rarely be the case, as the observations typically have noise of a couple of centimeters. The displacement corresponds to the misfit divided by (normalized by) the minimum of total length and :math:`\boldsymbol\varepsilon`. .. _toast_residual_wr: Wave radar residual ~~~~~~~~~~~~~~~~~~~ The wave radar residual has not been implemented. .. _toast_sim_pb: Simulation playback ------------------- |toast| has the builtin feature to export simulated sea level observation time series and event metadata from a simulation. The exported data can be used in a playback for training or testing purposes. .. note:: Do not confound the *simulation playback* with the :ref:`toast_sim_player`! .. note:: To run the simulation playback, the *quakelink* package is required. .. _create_sim_pb: Create playback ~~~~~~~~~~~~~~~ To create a playback, right-click on a simulation and select *Create playback...*. The default path for export is */tmp/+sim-id*. .. _fig-sim_export: .. figure:: media/toast/sim/sim_export.png :align: center :width: 8 cm Create playback in simulation context menu The playback directory contains the following information: * The incident meta data in XML format, e.g., the incident event type in the file *incident.xml*. * The simulation meta data in XML format, e.g., the magnitude or depth of the simulation in the file *simulation.xml*. * The simulated time series of all triggered stations in MSEED format in the file *data.mseed*. * The time series are padded with zeros from origin time to the start of the simulated data. * Uniform noise of configurable amplitude is added to the time series. An external script is called after export to finalize the data for the playback tool *toast-playback*. The script can be configured via :confval:`playbackExternalScript`. By default the script *eqscenegenerator.sh* is executed which in turn calls the Python script *eqscenegenerator.py*. Both are part of the |toast| package. It adds the directory *event*, with several |scname| event XML files with randomized magnitudes and locations which converge to the final value. They are used as event updates when running the playback. The zipped files are used for playback while the unzipped files can easily be inspected using a browser. It also creates the file *event.log* which is required by *toast-playback* and contains the information when the event updates are to be sent. Look at the external script for more details. .. _fig-sim_create_playback_dialog: .. figure:: media/toast/sim/sim_create_playback_dialog.png :align: center :width: 9 cm Create playback dialog .. note:: The export works only for |ewname| simulations, as currently only those contain the required time series. If one of the 3 steps for the creation fails, place to mouse pointer on top of the warning icon to get more information as tooltip. .. _ run_sim_pb: Run playback ~~~~~~~~~~~~ The playback is started with the commad-line tool *toast-playback*. It sends the events to *quakelink* and the simulated sea level observation time series to *caps*. Before starting the playback: * The normal sea level data acquisition has to be stopped (e.g. *rs2caps*, *caps2caps*, *bomslo2caps*). * The *ql2sc* module has to be running so that the event parameters are forwarded to the messaging and thus the |toasts|. * Make sure that *ql2sc.cfg* points to the queue which is the source for the TOAST daemon, e.g. .. code-block:: sh connection.server = localhost/seiscomp * Adapt the routing table in *ql2sc.cfg*: .. code-block:: sh host.proc.routingTable = Pick:IMPORT_GROUP,Amplitude:IMPORT_GROUP,FocalMechanism:EVENT,Origin:EVENT,Event:EVENT * Avoid unnecessary processing by *scevent* by appending the agency to the blacklist in the global section of *scevent.cfg*: .. code-block:: sh processing.blacklist.agencies=PLAYBACK Start the playback with: .. code-block:: sh sysop@host:~$ toast-playback sim-directory-name The *quakelink* and *caps* targets for *toast-playback* can be specified on command line using the options *-Q* and *-C* respectively. The option *-T* or *-\-event-lead-time* can be used to define when the first event should be played back. Its default value is 300 seconds, negative values are also possible to omit the first part of the playback where the wave is far from impact. When using the option *-\-test* no data is sent. As usual, *-h* or *-\-help* list all options.