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.
eventidmust correspond to those provided by the Mars-event Web Servicelocationqualityof 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
- Retrieve information on the Syngine model prem_a_20s in JSON format:
…/info?model=prem_a_20s
- Retrieve information on the Syngine Mars model mars_tayak_5s in JSON format:
…/info?model=mars_tayak_5s
/query
Notes:
- For the Mars models, both input and output latitude represents geocentric latitude.
Seismograms (SEIS):
- Earth models:
- Vertical radial and tangential synthetics for a receiver at the IU.ANMO station using the 2002 Denali earthquake (GCMT solution) as a source:
- Vertical, radial and tangential synthetics for all stations in the GSN virtual network, starting at origin time and ending 30 minutes after origin time:
- Explicitly specifying source origin time, location & moment tensor and receiver location:
- Mars models:
- Explicitly specifying source origin time, location & moment tensor and receiver location for the Mars model mars_eh45tcold_1s:
- Z synthetic for a receiver at the XB.ELYSE station using the Mars event mqs2019onhx that has a location quality “A”:
- NOTE: the above request with Mars event mqs2020yvsr that has a location quality “B” will result in an error:
- Explicitly specifying source origin time, location, and source mechanism as a double couple and use the Mars station XB.ELYSE as the receiver location:
Custom Source Time Function (CSTF):
- Earth models:
- Vertical radial and tangential synthetics for a receiver at the IU.ANMO station using the 2002 Denali earthquake (GCMT solution) as a source and a custom source time function:
- Mars models:
- ZNE synthetics for a receiver at the XB.ELYSE station using a custom source time function and the Mars model mars_tayak_1s:
Finite Fault Model (FFM, only available for the Earth models):
- Vertical synthetics for finite sources defined in the USGS Finite Fault model for M 7.8 – 36km E of Khudi, Nepal
- Same as the above except as a text file to POST to Syngine:
- FFM_us20002926.txt
- wget —post-file=FFM_us20002926.txt -O FFM_us20002926.zip
Green’s Function (GF):
- Earth models:
- Instaseis Green’s function for model ak135f_5s at a distance of 10 degrees for a source 1000 meters deep:
- Mars models:
- Instaseis Green’s function for model mars_tayak_1s at a distance of 10 degrees for a source 1000 meters deep:
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:
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:
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 stationNote: 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) sourceforceNote:* - 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:
[email protected]
We will address your issue as soon as possible.
