IRIS DMC IRISWS syngine Web Service Documentation

Description

The IRIS Synthetics Engine (syngine) service uses Instaseis to generate synthetics from 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

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] [fformat-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) — 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.

Sample Queries

Seismograms (SEIS):

Custom Source Time Function (CSTF):

Finite Fault Model (FFM):

  • Same as the above except as a text file to POST to Syngine:

Green’s Function (GF):

Detailed Descriptions of each Query Parameter

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

parameters request type examples discussion default type
Model parameters
model All iasp91 Specify the model. List of models prem string
Output parameters
format All miniseed Specify output file to be either miniSEED or a ZIP archive of SAC files, either miniseed or saczip. saczip string
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. Only upsampling is allowed so this value must be larger than the instrinsic interval of the database. varies by model float
scale SEIS, CSTF, FFM 3.3 Specify an amplitude scaling factor. The default amplitude length is 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
Time parameters
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 parameters: at least one receiver required, either (a) receiverlatitude and receiverlongitude or with (b) network and station
receiverlatitudea 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 network 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 parameters: for SEIS & CSTF a source location is required, either (a) eventid or (b) sourcelatitude, sourcelongitude and sourcedepthinmeters
Note: defining sourcelatitude, sourcelongitude, sourcedepthinmeters or origintime, in addition to eventid, will override the corresponding parameter obtained via eventid.
eventida 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 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. int
sourcedistanceindegrees GF 20 Specify the epicentral disctance 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, (b) sourcemomenttensor, (c) sourcedoublecouple or (d) sourceforce
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. 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.
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. comma-separated floats

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

IRISWS syngine web service