.. highlight:: rst .. _kermadec: ######## kermadec ######## **GNS Science threat model database simulation plugin** Description =========== The Kermadec simulation plugin **simkermadec** selects scenarios based on incident magnitude from a Kermadec scenario database provided in the form of a CSV file and provides them via the tsunami plugin interface. Scenario database ================= The Kermadec scenario database is provided by GNS as a CSV file. The file structure/format is very similar to the one of the GNS Threat plugin (see respective documentation). Starting from the seventh row, the first column contains the New Zealand forecast zone ID (1-43), and the following columns the simulation results associated with the scenarios described in the first 6 rows. In the example file `KermadecThreatLevel.csv.example` there are four scenarios corresponding to different magnitudes and the simulation results are either 0.5 (under assessment) or 1.5 (threat). Matching -------- The scenario matching algorithm takes the coordinate and the magnitude of the given incident into account. A scenario matches if * the incident magnitude is between the minimum and maximum magnitude value of the scenario and * the incident location is inside the defined region. As proposed by GNS, the magnitude of a scenario is the average value of the minimum and maximum magnitude value. The location of the scenario is the center of the configured region. Configuration ============= In order to be loaded by TOAST, the simkermadec 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},simkermadec Scenario database ------------------ Configuration of the scenario database which stores the simulation results: :: # File in CSV format from which the simulation results are read. kermadec.database.runupFile = @DATADIR@/simkermadec/KermadecThreatLevel.csv **simkermadec** is delivered with an example csv file. Copy this file and remove the ending in order to avoid overwriting during a TOAST update: .. code-block:: sh cp $SEISCOMP_ROOT/share/simkermadec/KermadecThreatLevel.csv.example $SEISCOMP_ROOT/share/simkermadec/KermadecThreatLevel.csv Area of interest ---------------- The area of interest defines for which area manual and automatic simulations are returned by the simulation backend. No simulations are generated for events outside of this area. It is defined in a bna text file. :: kermadec.areaOfInterest = @DATADIR@/simkermadec/kermadec.bna **simkermadec** is delivered with a default area file *kermadec.bna.example* limited by: 177°E ~ 191°E (169°W) & 33°S ~ 25°S (Kermadec region). In order to avoid overwriting during a TOAST update, the file has to be copied before usage: .. code-block:: sh cp $SEISCOMP_ROOT/share/simkermadec/kermadec.bna.example $SEISCOMP_ROOT/share/simkermadec/kermadec.bna .. note:: To show the area of interest in map view, copy or link the bna file to either of two locations: * $SEISCOMP_ROOT/share/bna * ~/.seiscomp/bna Magnitude modifiers ------------------- The magnitude of events received by messaging can be automatically increased, see: :confval:`kermadec.magnitudeModifiers`. Forecast points --------------- Forecast point profiles can be registered as follows: :: # Registration of a forecast point profile. kermadec.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 kermadec.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/kermadec.cfg` | :file:`etc/global.cfg` | :file:`etc/kermadec.cfg` | :file:`~/.seiscomp/global.cfg` | :file:`~/.seiscomp/kermadec.cfg` kermadec 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:: kermadec.forecastPoints Type: *list:string* Registration of forecast points. .. confval:: kermadec.maxScenarios Default: ``3`` Type: *int* Maximum number of returned scenarios. Use \-1 to disable the restriction. .. confval:: kermadec.magnitudeModifiers Type: *list:double* With this option the magnitude of events which are received via messaging can be increased\/decreased by a fixed value. For each entry of the list the plugin creates an extra simulation. For instance for mangitude 8.0 and the modifiers 0.2 and 0.4 the plugin creates three simulations. One simulation for magnitude 8, one for magnitude 8.2 and one for mangitude 8.4. Note that this feature applies only for incidents which are received by messaging, and not for manual import or creation. .. confval:: kermadec.areaOfInterest Type: *string* Absolute filename of the area of interest file in BNA format. If the earthquake parameters are outside of the defined range, TOAST displays a warning in the manual simulation dialog. The default area of interest file spans 177°E \~ 169°W and 33°S \~ 25°S. .. confval:: kermadec.database.runupFile Default: ``@DATADIR@/simkermadec/KermadecThreatLevel.csv`` Type: *string* Path to file with simulation results in CSV format .. note:: **kermadec.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 kermadec.forecastPoints.a.value1 = ... kermadec.forecastPoints.b.value1 = ... # c is not active because it has not been added # to the list of forecastPoints kermadec.forecastPoints.c.value1 = ... .. confval:: kermadec.forecastPoints.$name.filename Type: *string* Absolute filename of the forecast point file in dBase format.