.. highlight:: rst .. _gnsthreat: ######### gnsthreat ######### **GNS Science threat model database simulation plugin** Description =========== The **simgnsthreat** simulation plugin reads precalculated simulation data from threat level files in CSV format and provides them via the tsunami plugin interface. Matching between incident and precomputed scenarios is done based on magnitude (plus/minus matching.magnitudeUncertainty) and search area. First, scenarios are searched for in an elliptical area whose orientation and size corresponds to fault geometry. If less than gnsthreat.matching.maxScenarios are found, then the search is continued in a circular area with radius as configured in gnsthreat.matching.fallbackSearchRadius and the additionally found sceanrios are appended. Ellipse orientation, Fallback search radius and Magnitude uncertainty can be adapted in the interactive simulation dialog. If more than maxScenarios are found, they are sorted and the first maxScenarios are returned. Sorting is done as follows: first by distance, then by magnitude difference (for same magnitude difference larger magnitude first). Note: this sorting has not to be confounded with the sorting as shown in the TOAST Database - Simulations panel, where sorting can be done according to Residual with configurable weighting parameters (see TOAST Configuration Parameters). Threat level files ================== Threat level files store simulation results. The plugin supports the following file types: * Time of arrival of the minimum detectable positive amplitude wave (T1 - 1cm) * Time of first exceedance of the threat level threshold (T2 - 30 cm) * Maximum positive wave amplitude at shoreline (Runup) Structure --------- Threat level files are stored in CSV format. The fist lines of a file contain the following meta information: * Scenario ID * Code * Lon * Lat * Mag * Slip From there on each line contains the results for a particular forecast zone, starting with the forecast zone ID (1-43) followed by the values for the different scenarios. Unset values are represented as **NAN**. Configuration ============= In order to be loaded by TOAST, the simgnsthreat plugin has to be added either in the global module configuration (global.cfg) or in the global section of the toast module (toast.cfg). :: plugins = ${plugins},simgnsthreat Threat level files ------------------ Configuration of the 1 cm threat level file :: # File in CSV format from which the tmin1cm values are read. gnsthreat.files.min1cm = @DATADIR@/csv/Header_Tmin_1cmThreatLevel.csv Configuration of the 30 cm threat level file :: # File in CSV format from which the tmin30cm values are read. gnsthreat.files.min30cm = @DATADIR@/csv/Header_Tmin_30cmThreatLevel.csv Configuration of the runup threat level file :: # File in CSV format from which the hpct99 values are read. gnsthreat.files.hpct99 = @DATADIR@/csv/Header_Hpct99ThreatLevel.csv Forecast points --------------- Forecast point profiles can be registered as follows: :: # Registration of forecast points. gnsthreat.forecastPoints = nz For each entry of the list (comma-separated) there has to be a forecast point profile. The profile sets the filename of the forecast point file in DBF format. :: # Absolute filename of the forecast point file in dBase format gnsthreat.forecastPoints.nz.filename = @DATADIR@/toast/forecast/points/NZ_CFP.dbf The threat level files contain forecast zones from 1 to 43 whereas TOAST uses the New Zealand forecast zones which have IDs starting with 7000. That is why a fix offset of 7000 is added to the threat level indices. Module Configuration ==================== | :file:`etc/defaults/global.cfg` | :file:`etc/defaults/gnsthreat.cfg` | :file:`etc/global.cfg` | :file:`etc/gnsthreat.cfg` | :file:`~/.seiscomp/global.cfg` | :file:`~/.seiscomp/gnsthreat.cfg` gnsthreat inherits :ref:`global options`. .. note:: Modules/plugins may require a license file. The default path to license files is :file:`@DATADIR@/licenses/` which can be overridden by global configuration of the parameter :confval:`gempa.licensePath`. Example: :: gempa.licensePath = @CONFIGDIR@/licenses .. confval:: gnsthreat.forecastPoints Type: *list:string* Registration of forecast points. .. confval:: gnsthreat.files.min1cm Default: ``@DATADIR@/simgnsthreat/Header_Tmin_1cmThreatLevel.csv`` Type: *string* File in CSV format from which the tmin1cm values are read. .. confval:: gnsthreat.files.min30cm Default: ``@DATADIR@/simgnsthreat/Header_Tmin_30cmThreatLevel.csv`` Type: *string* File in CSV format from which the tmin30cm values are read. .. confval:: gnsthreat.files.hpct99 Default: ``@DATADIR@/simgnsthreat/Header_Hpct99ThreatLevel.csv`` Type: *string* File in CSV format from which the hpct99 values are read. .. confval:: gnsthreat.matching.magnitudeUncertainty Default: ``0.2`` Type: *float* Maximum allowed magnitude difference. .. confval:: gnsthreat.matching.maxScenarios Default: ``3`` Type: *int* Maximum number of returned scenarios. Use 0 to disable the restriction. .. confval:: gnsthreat.matching.fallbackSearchRadius Default: ``200`` Unit: *km* Type: *float* Continue the search within a circular area if the number of found scenarios is smaller than configured in gnsthreat.maxScenarios. .. note:: **gnsthreat.forecastPoints.$name.\*** $name is a placeholder for the name to be used and needs to be added to :confval:`forecastPoints` to become active. .. code-block:: sh forecastPoints = a,b gnsthreat.forecastPoints.a.value1 = ... gnsthreat.forecastPoints.b.value1 = ... # c is not active because it has not been added # to the list of forecastPoints gnsthreat.forecastPoints.c.value1 = ... .. confval:: gnsthreat.forecastPoints.$name.filename Type: *string* Absolute filename of the forecast point file in dBase format.