NSF SAGE Facility IRISWS syngine Web Service Documentation

Description

The IRIS Synthetics Engine (syngine) service uses Instaseis to generate synthetics from Earth and Mars model databases pre-computed by AxiSEM. The service provides custom tailored synthetic seismograms or Instaseis Green’s function. For each single-source and single-model request, all traces will be returned in a ZIP archive containing SAC files or miniSEED. The product detail page provides an overview of Syngine, tutorials for usage and links to download model databases.

Below is a full list of service parameters and their usage.

Query Usage

/models GET usage:

To retrieve a list of current Syngine models in JSON format that includes model parameters:

/models

/info GET usage:

To retrieve information on a Syngine model in JSON format:

/info? (model-options) 

/query GET and POST usages:

To retrieve data from the syngine service, submit a request by either of the methods below:

  • via HTTP GET: Provide a series of parameter-value pairs in the URL. Please refer to the table below titled Detailed Descriptions of each Query Parameter for usage details. Each parameter-value pair should be separated by an ampersand &, and with no space. NOTE: With GET, extremely long URLs (often over 2,000 characters) may not work. For such long requests, POST method should be used. A GET request may take the following general form:
    /query? (date-range-options) (source-options) (receiver-options) (model-options) (format-options) (misc-options) (nodata=404)

  • via HTTP POST: Submit parameters and an arbitrary list of receivers to the service. All parameters used for GET queries are also valid for POST queries.
    For additional details on constructing and submitting POST selection files, visit the POST Examples in the Help section.

Currently the following request types are supported (request types are implicitly defined by the required parameters submitted, except for the Green’s Function where the request type is indicated explicitly using the greensfunction parameter):

  • Seismograms (SEIS) — to retrieve Instaseis seismograms.
  • Custom Source Time Function (CSTF) — seismograms are convolved with a custom source time function.
  • Finite Fault Model (FFM) — is only available for the Earth models to retrieve Instaseis seismograms for finite sources defined in the USGS Finite Fault model PARAM file format. By default the FFM allows at most 1000 point sources for a single finite source.
  • Green’s Function (GF) — to retrieve Instaseis Green’s function.

The required and optional parameters for the above request types are listed in the Query Parameter table below.

Notes on the use of event identifier (eventid) with the Mars models:

  • Specifying an event identifier in the form MARS:[eventid] (e.g. MARS:mqs2019onhx) is supported for the Mars models.
  • eventid must correspond to those provided by the Mars-event Web Service
  • locationquality of each event (more information) will determine how the event information could be used:
    • for events with location quality “A”, event time, latitude, and longitude could be used to retrieve Instaseis seismograms (SEIS)
    • for events with location quality “B”, event distance in degrees could be used to retrieve Instaseis Green’s function (GF)
    • for events with location qualities “C” or “D”, an errors will be returned as these events do not contain event location information

Sample Queries

/models

Retrieve a list of current Syngine models in JSON format (note: Mars model names start with mars_):
…/models

/info

/query

Notes:

  • For the Mars models, both input and output latitude represents geocentric latitude.

Seismograms (SEIS):

- Earth models:

- Mars models:

Custom Source Time Function (CSTF):

- Earth models:

- Mars models:

Finite Fault Model (FFM, only available for the Earth models):
  • Same as the above except as a text file to POST to Syngine:

Green’s Function (GF):

- Earth models:

- Mars models:

Detailed Descriptions of each Query Parameter

(parameters with bold underlined text are required for that request type)

parameters request type examples discussion default type
model-options
model All iasp91 Specify the model. List of models prem string
format-options
format All miniseed Specify output file to be either miniSEED or a ZIP archive of SAC files, either miniseed or saczip. saczip string
misc-options
label All Tohoku Specify a label to be included in file names and HTTP file name suggestions. string
components SEIS, CSTF, FFM ZRT Specify the orientation of the synthetic seismograms as a list of any combination of Z (vertical), N (north), E (east), R (radial), T (transverse) ZNE string
units All velocity Specify either displacement, velocity or acceleration for the synthetics. displacement string
dt All 0.2 Specify the sampling interval in seconds. In order to avoid aliasing, downsampling from the database dt is not allowed by Instaseis, only upsampling. If a model has a database dt=0.5, dt=0.1 is allowed, dt=1.0 is not allowed. varies by model float
scale SEIS, CSTF, FFM 3.3 Specify an amplitude scaling factor. Amplitude length is specified in nanometers. 1 float
kernelwidth All Specify the width of the sinc kernel used for resampling to requested sample interval (dt), relative to the original sampling rate. 12 integer
sourcewidth SEIS Optionally convolve the seismograms with a Gaussian source time function (moment rate) of approximately the given sourcewidth in seconds. 15 integer
date-range-options
origintime All 2010-02-27T06:34:14 Specify the source origin time. This must be specified as an absolute date and time. 1900-01-01 day/time
starttime All 2010-02-27T06:30:00 Specifies the desired start time for the synthetic trace(s). This may be specified as either:
  1. an absolute date and time
  2. a phase-relative offset
  3. an offset from origin time in seconds

If the value is recognized as a date and time, it is interpreted as an absolute time. If the value is in the form phase[+-]offset it is interpreted as a phase-relative time, for example P-10 (meaning Pwave arrival time minus 10 seconds). Use of a phase-relative time requires the specification of an origintime. If the value is a numerical value it is interpreted as an offset, in seconds, from the origintime.
origintime day/time
endtime All 2010-02-27T07:34:14 Specify the end time for the synthetic trace(s). This may be specified as either:
  1. an absolute date and time
  2. a phase-relative offset
  3. an offset (duration) from start time in seconds

If the value is recognized as a date and time, it is interpreted as an absolute time. If the value is in the form phase[+-]offset it is interpreted as a phase-relative time. If the value is a positive numerical value it is interpreted as an offset, in seconds, from the starttime.
[end of model database] day/time
receiver-options: at least one receiver required, either (a) receiverlatitude and receiverlongitude or with (b) network and station
Note: for Mars models, latitude represents geocentric latitude
receiverlatitudea
Note: geocentric latitude for Mars
SEIS, CSTF, FFM 47.6 Specify the receiver latitude in degreess. float
receiverlongitudea SEIS, CSTF, FFM -122.3 Specify the receiver longitude in degrees. float
networkb SEIS, CSTF, FFM IU Specify a network code combined with station to identify receiver coordinates of a operating station. string
stationb SEIS, CSTF, FFM ANMO Specify a network code combined with station to identify receiver coordinates of a operating station. string
networkcode SEIS, CSTF, FFM YY Specify the network code for synthetic. Any value specified with network will take precedence to this. XX string, 2 characters maximum
stationcode SEIS, CSTF, FFM D1Z1 Specify the station code for synthetic. Any value specified with station will take precedence to this. SYN string, 5 characters maximum
locationcode SEIS, CSTF, FFM A1 Specify the location code for synthetic. SE string, 2 characters maximum
source-options: for SEIS & CSTF a source location is required, either (a) eventid or (b) sourcelatitude, sourcelongitude and sourcedepthinmeters
Notes:
- defining sourcelatitude, sourcelongitude, sourcedepthinmeters or origintime, in addition to eventid, will override the corresponding parameter obtained via eventid.
- for Mars models, only eventid from Mars events with location quality “A” may be used to retrieve Instaseis seismograms (SEIS)
- for Mars models, latitude represents geocentric latitude
eventida
Note: for use with the Earth models only
SEIS, CSTF GCMT:C201002270634A Specify an event identifier in the form [catalog]:[eventid]. The centroid time and location and moment tensor of the solution will be used as the source. The catalog supported is Global CMT. Search for GCMTs string
sourcelatitudeb
Note: geocentric latitude for Mars
SEIS, CSTF -89.99 Specify the source latitude. float
sourcelongitudeb SEIS, CSTF -179.99 Specify the source longitude. float
sourcedepthinmetersb SEIS, CSTF, GF 699000 Specify the source depth in meters from 0 to 700000. integer
sourcedistanceindegrees GF 20 Specify the epicentral distance of source – receiver in degrees (computed on the surface of a sphere). floats
greensfunction GF 1 Specify the request type as Green’s function (>0). integer
for SEIS & CSTF the source mechanism must be specified, either with (a) eventid (Earth models only) , (b) sourcemomenttensor, (c) sourcedoublecouple or (d) sourceforce
Note:*
- for Mars models, only eventid from Mars events with location quality “A” or “B” may be used to retrieve Instaseis Green’s function (GF)
Source mechanism as a moment tensor
sourcemomenttensorb SEIS, CSTF 1.04e22,-0.039e22,-1e22,0.304e22,-1.52e22,-0.119e22 Specify a source in moment tensor components as a list: Mrr,Mtt,Mpp,Mrt,Mrp,Mtp with values in Newton meters (Nm). floats
Source mechanism as a double couple
sourcedoublecouplec SEIS, CSTF 19,18,116,1e19 Specify a source as a double couple. The list of values are strike,dip,rake[,M0], where strike, dip and rake are in degrees and M0 is the scalar seismic moment in Newton meters (Nm). If not specified, a value of 1e19 will be used as the scalar moment. 1e19 floats
Source mechanism as forces
sourceforced SEIS, CSTF 1e22,1e22,1e22 Specify a force source as a list of Fr,Ft,Fp in units of Newtons (N). floats
USGS Finite Fault Model param file: should be provided either via event ID (e) ffmeventid or by placing the PARAM file text between two (f) STARTUSGSFFM and ENDUSGSFFM labels. By default the FFM allows at most 1000 point sources for a single finite source.
Note: FFM option is only available for the Earth models
ffmeventide FFM USGS:us20002926 Specify a USGS event identifier in the form USGS:[eventid] to retrieve the USGS FFM PARAM file. NOTE: USGS sometimes offers more than one FFM solution for an event. In such cases, by default Syngine selects the first solution but logs URL to both solutions in the Syngine download log file. string
STARTUSGSFFM ENDUSGSFFMf FFM STARTUSGSFFM
#Total number of fault_segments= 1
#Fault_segment = 1 nx(Along-strike)= 11 Dx= 20.00km ny(downdip)= 11 Dy= 15.00km
#Boundary of Fault_segment 1. EQ in cell 9,6. Lon: 84.7251 Lat: 28.1654
#Lon. Lat. Depth
85.94160 26.86900 0.86010
. . .
ENDUSGSFFM
place the content of the USGS FFM param file between the STARTUSGSFFM and ENDUSGSFFM labels. text
Custom Source Time Function (CSTF)
cstf-relative-origin-time-in-sec CSTF 5.0 Specify offset in seconds from the first sample which should be considered the origin time of the resulting seismogram (0s-600s). floats
cstf-sample-spacing-in-sec CSTF 10.0 Specify the sample interval in seconds. floats
cstf-data CSTF 0.0,0.2,0.5,0.2,0.0,0.0,0.0 Specify the CSTF data array as comma-separated list. Note: (1) The custom STF must always start and end with 0. (2) The custom STF is always normalized by dividing it by its total area. comma-separated floats
nodata
nodata1 All 404 Specify which HTTP status code is returned when no data is found.3 204 204 or 404

1 By default, the service returns a HTTP response code 204, which means the request was successful, but no data (no content) was retrieved. However, because there was no “error”, no error message is generated and it may appear that the browser did nothing. To force an empty query response to display an error message, add nodata=404 to the URL.


Date and Time Formats

Year, Month, Day in Month — Time:

YYYY-MM-DDThh:mm:ss[.ssssss] ex. 1997-01-31T12:04:32.123

YYYY-MM-DD ex. 1997-01-31 a time of 00:00:00 is assumed

Where:

YYYY	:: four-digit year
MM	:: two-digit month (01=January, etc.)
DD	:: two-digit day of month (01 through 31)
T	:: date-time separator
hh	:: two digits of hour (00 through 23) (AM/PM NOT allowed)
mm	:: two digits of minute (00 through 59)
ss	:: two digits of second (00 through 59)
ssssss	:: one to six digits representing decimal fractions of a second, down to microseconds

Problems with this service?

Please send an email report of which service you were using, your URL query, and any error feedback to:
data-help@earthscope.org
We will address your issue as soon as possible.

IRISWS syngine web service