Feature: define task reqs for typical openquake job

[chrisbc]

We want to run openquake tasks using nzshm-runzi (automation) and collect job metadata, inputs, outputs etc in toshi-api

So that we have history etc avail to the team.

Epic: https://github.com/orgs/GNS-Science/projects/9#card-67029920

Needed:

• list of inputs for a typical openquake task
• list of cmd-line arguments that are supplied to run the job
• list any environment settings needed?
• list of typical outputs
• supply examples of input/outputs

[thingbaijam]

List of inputs for a typical OQ task

Input	Format	Remarks
Configuration	*.ini	This file informs OQ of metadata, where to locate the inputs (as listed below), where/how to generate outputs, and other specifications (viz., those relevant to site conditions, maximum source-to-site distance, intensity measure types, etc) . The format follows OQ specification.Instead of an input file, sites can be alternatively specified as a polygon with grid-spacing. But, using *.csv file is preferable.
Sites (or locations)	*. csv	Comma separated rows of longitude and latitudes (both in degrees).  Sites can be grid locations or some selected ones. The generation of spatial hazard maps would optimally require grids. Some sites could be identified according to perceptible significant risk such as those in Christchurch, Wellington, Auckland, etc. That would facilitate examining site-targeted evaluation.
Source model	*.xml	An xml file containing the description of the source models. It incorporate an hierarchical sort of representation such that source model is given in another *.xml file.
Ground motion model	*.xml	This file contains the list of ground motion models (GMMs). The details include assigned weight and which type of tectonic region to apply for each GMM.
Site parameters	*.csv	This input file can be used for spatially varying soil properties. This is an alternative to specifying uniform site conditions in the configuration file.   The file has the structure:lon, lat, vs30, z1pt0, z2pt5, vs30measured, backarc

List of cmd-line arguments that are supplied to run the job

The simplest command API on a terminal is:
oq engine --run [some_input_file.ini]

Often, we use --export flag to specify output format.

List any environment settings needed
Main dependencies are:
Python 3.6+ (3.7+ is preferable)
Django - Used by the OQ API server and the WebUI
HDF5 - Used for storing and managing data
numpy and scipy - Fundamental packages for scientific computing with Python
pyzmq - Used for internal inter-process communications

A few useful links
Hardware considerations
https://github.com/gem/oq-engine/blob/master/doc/adv-manual/oq-commands.rst
https://github.com/gem/oq-engine/blob/master/doc/hardware-suggestions.md

Installing on Linux Cluster
A guide can be found here:
https://github.com/gem/oq-engine/blob/master/doc/installing/cluster.md

Software stack for OQ
https://github.com/gem/oq-engine/blob/master/doc/requirements.md

Document for advanced users
https://docs.openquake.org/oq-engine/advanced/

List of typical outputs

The results from the OQ engine can be obtained directly or by exporting them from the internal oq-engine database (HDF5) after the calculation is completed. The former approach involves the “-exports” flag in the command.

Output	Format	Remarks
Hazard curve	*.csv	This file contains the hazard curve computed at each site. The contents are described in a two-lines header.
Hazard Map	*.csv	The file provides the calculated hazard for each site. As with hazard curves, the contents are described in a two-lines header.

Note: outputs can be also exported in XML (or NRML) formats. As outputs can be quite large, **HDF5** might be preferable format to store/manage the data.

Example Files

Sample input files uploaded in the repo:
https://github.com/GNS-Science/nzshm-runzi/tree/main/samples/oq/inputs

Sample output files uploaded in the repo:
https://github.com/GNS-Science/nzshm-runzi/tree/main/samples/oq/outputs

---

A working document on these topics can be accessed:
https://docs.google.com/document/d/1UfuLudr0Hbhx-macxg-xoOwWr_APBJ1EVnO1NrNnkmU/edit?usp=sharing