Help: syngine v.1

Description

To retrieve synthetic seismograms, submit a request by either of two methods:

• via HTTP GET : Provide a series of parameter-value pairs in the URL that specify the required and optional parameters. Please visit the irisws-syngine service interface for parameter usage details. NOTE: With GET, extremely long URLs (often over 2,000 characters) may not work. For such long requests, POST method should be used.
• via HTTP POST: Submit a pre-fomatted request (e.g. a file) to the service potentially containing an arbitrary list of receivers. The POSTing method is described in more detail on this page.

Request types

Currently the following request types are supported by Syngine. Request type is implicitly determined by the combination of submitted required parameters, except for the Green’s Function where the request type is indicated explicitly using the greensfunction parameter. Please note that the defaults for Syngine (for parameters and SAC header variables) may not be the same as those documented by Instaseis in the followng links.

• Seismograms (SEIS) — to retrieve Instaseis seismograms. These synthetic seismograms are produced by calling the seismograms route of Instaseis. For more information see the Instaseis seismograms documentation.

• Custom Source Time Function (CSTF) — to retrieve seismograms convolved with a custom source time function. This request type is activated in Syngine when user provides cstf-relative-origin-time-in-sec, cstf-sample-spacing-in-sec and cstf-data required CSTF parameters. In turn, Syngine bundles the value of these parameters as a JSON block and submits it to Instaseis. For more information see the Instaseis seismograms documentation.

• Finite Fault Model (FFM) — available only for the Earth models and generates Instaseis seismograms for a finite source defined in the USGS finite fault model PARAM file format. This request type is activated in Syngine when user provides information on a USGS finite fault model PARAM file as either a USGS event identifier through the ffmeventid parameter or by placing the USGS FFM PARAM file content between STARTUSGSFFM and ENDUSGSFFM labels. Syngine then verifies the format of the PARAM file and submits it to finite_source route of Instaseis. By default the FFM allows at most 1000 point sources for a single finite source. For more information see the Instaseis finite_source documentation.

• Green’s Function (GF) — Instaseis Green’s function can be retrieved by providing the sourcedepthinmeters, sourcedistanceindegrees and greensfunction required parammeters to Syngine. The sourcedepthinmeters and sourcedistanceindegrees parameters along with the default parameters are then submitted to the greens_function route of Instaseis. For more information see the Instaseis greens_function documentation.

Technical model and synthetic generation details

Most technical details of the irisws-syngine service are documented as the syngine data product page.

Formatting a request for POSTing

Pre-formatted requests are simply a list of parameter-value pairs followed by a list of one or more receivers. The general form is:

parameter=value
parameter=value
...
latitude longitude [NETCODE=XX] [STACODE=SYN] [LOCCODE=SE]
netcode stacode
...

where the parameter=value lines set parameters, e.g. model=prem_i_2s, and one or more receivers may be specified as latitude and longitude pairs (with optional output station code assignments) or as real network and station codes.

An example request:

model=prem_i_2s
sourcelatitude=-31.570
sourcelongitude=-71.654
sourcedepthinmeters=25000
sourcemomenttensor=1.95e28,-0.049e28,-1.9e28,0.531e28,-2.04e28,0.079e28
IU COLA
II KURK
43.07 -89.38
47.6616 -122.3127 STACODE=DMC

The location of receivers specified as a network and station codes will be resolved using the DMC’s fedcatalog service for stations in FDSN data centers. Both network and station may wildcards. Virtual network codes may be used.

For flexibility, the entire request block may be URL-encoded and submitted as the value of a request field and submitted as if from a form.

wget example request using POST

Requests can be made with a request file and the wget command line utility.

Create a file named ‘synthetics.request’ containing the example request above and submit it using wget like this:

$ wget --post-file=synthetics.request -O Synthetics.zip http://service.iris.edu/irisws/syngine/1/query

This will send the request to the server and save the results in a file named Synthetics.zip.

cURL example request using POST

Requests can also be made with a request file and the cURL command line utility.

Create a file named ‘synthetics.request’ containing the example request above and submit it using curl like this:

$ curl -L --data-binary @synthetics.request -o Synthetics.zip http://service.iris.edu/irisws/syngine/1/query

This will send the request to the server and save the results in a file named Synthetics.zip.

We recommend always using the -L option to allow curl to follow HTTP redirections specified by our systems. The DMC uses HTTP redirection during maintenance to keep servicing requests.

You may wish to use the -f option. This will cause curl to return an exit code of 22 if data is not found or the request is improperly formatted.

Encoding special values, in particular + (plus)

Special values in HTTP query content must be encoded or otherwise it may be misinterpreted by the server. Usually HTTP client software does this automatically. One particular special value, the plus (+), can cause confusion with this service. In a URL, the plus (+) is translated to a space character. To avoid this translation and properly submit a plus sign using the encoded value: %2B in place of plus signs.

Problems with this service?