CyberShake output data formats

From SCECpedia

As of 2016, CyberShake runs output up to 4 different data files: seismograms, peak spectral accelerations, rotD values, and duration metrics.

All 4 file formats share the same header format.

Common header

All 4 formats use a common header. This header is used once for each rupture variation in a file. It's defined in C syntax below:

 char version[8];
 char site_name[8];
 char padding[8];
 int source_id;
 int rupture_id;
 int rup_var_id;
 float dt;
 int nt;
 int comps;
 float det_max_freq;
 float stoch_max_freq;
  • version: An 8-character string representing the version of the header. 12.10 is the current (and only so far) version.
  • site_name: An 8-character string representing the short name of the CyberShake site; good for checking the right
  • padding: 8 bytes of padding, saved in case we have a need for them later. They're here instead of at the end of the header because Fortran (used in the PSA code) likes structures with decreasing-size elements.
  • source_id: The source ID of this rupture from the ERF.
  • rupture_id: The rupture ID of this rupture from the ERF.
  • rup_var_id: The rupture variation ID of the rupture variation whose data follows this header.
  • dt: The timestep size used in producing the seismogram data
  • nt: The number of timesteps in the seismogram
  • comps: A flag which indicates which components are represented in the file. X_COMP = 1, Y_COMP = 2, Z_COMP = 4, then the values are ANDed.
  • det_max_freq: A float with the maximum frequency of the deterministic results in this seismogram.
  • stoch_max_freq: A float with the maximum frequency of the stochastic results. Stochastic results are assumed to run from det_max_freq to stoch_max_freq. If there is no stochastic data, stoch_max_freq = -1.

This header is 56 bytes long.

Seismogram files

CyberShake produces one binary velocity seismogram file per rupture. The units are cm/s. The first component, the X, is oriented north, and the 2nd, the Y, is east. The file format is:

<RV 1 header>
<RV 1, comp 1 seismogram>
...
<RV 1, comp c seismogram>
<RV 2 header>
<RV 2, comp 1 seismogram>
...
<RV 2, comp c seismogram>
...
<RV n header>
<RV n, comp 1 seismogram>
...
<RV n, comp c seismogram>

Note that the rupture variations are NOT required to be in numerical order. You should parse them rather than assuming any particular order.

The rupture variation data is sizeof(float) x nt bytes long for each component. So for a seismogram which contains 2 components and 3000 timesteps, the entry for each rupture variation is 56 bytes (header) + 4 (bytes/float) x 3000 (timesteps) x 2 (components) = 24056 bytes.

Peak Spectral Acceleration (PSA) files

The file format for the PSA files is the same as the seismogram files. The units are cm/s^2:

<RV 1 header>
<RV 1, comp 1 PSA>
...
<RV 1, comp c PSA>
<RV 2 header>
<RV 2, comp 1 PSA>
...
<RV 2, comp c PSA>
...
<RV n header>
<RV n, comp 1 PSA>
...
<RV n, comp c PSA>

Again, the rupture variations are NOT required to be in numerical order.

There is data for 44 periods represented in a PSA file; the periods are in the following order: 10 sec, 9.5, 9.0, 8.5, 8.0, 7.5, 7.0, 6.5, 6.0, 5.5, 5.0, 4.8, 4.6, 4.4, 4.2, 4.0, 3.8, 3.6, 3.4, 3.2, 3.0, 2.8, 2.6, 2.4, 2.2, 2.0, 1.6667, 1.42857, 1.25, 1.111, 1.0, .6667, .5, .4, .3333, .285714, .25, .2222, .2, .1667, .142857, .125, .111, .1

For a typical CyberShake run, the size of the PSA data per rupture variation is: 56 bytes (header) + 4 (bytes/float) x 44 (PSA periods) x 2 (components) = 408 bytes.

RotD files

RotD data is stored in rotD records, 1 record per period. Their definition in C syntax is:

struct rotD_record {
 float period;
 float rotD100;
 int rotD100_angle;
 float rotD50;
};
  • period: The period this RotD data is for
  • rotD100: RotD100, in units of g.
  • rotD100_angle: The angle (0-360) associated with rotD100
  • rotD50: RotD50, in units of g.

The file format for the RotD files is:

<RV 1 header>
<RV 1 number of RotD records>
<RV 1, record 1>
<RV 1, record 2>
...
<RV 1, record R>
<RV 2 header>
<RV 2 number of RotD records>
<RV 2, record 1>
<RV 2, record 2>
...
<RV 2, record R>
<RV n header>
<RV n number of RotD records>
<RV n, record 1>
...
<RV n, record R>

Again, the rupture variations are NOT required to be in numerical order.

Typically, for a deterministic-only run we calculate RotD data at the following 22 periods: 1.0 sec, 1.2, 1.4, 1.5, 1.6, 1.8, 2.0, 2.2, 2.4, 2.6, 2.8, 3.0, 3.5, 4.0, 4.4, 5.0, 5.5, 6.0, 6.5, 7.5, 8.5, 10.0. For a hybrid stochastic/deterministic run we calculate RotD at 30 periods: 0.1 sec, 0.125, 0.1666667, 0.2, 0.25, 0.3333333, 0.5, 0.6666667, 1.0, 1.2, 1.4, 1.5, 1.6, 1.8, 2.0, 2.2, 2.4, 2.6, 2.8, 3.0, 3.5, 4.0, 4.4, 5.0, 5.5, 6.0, 6.5, 7.5, 8.5, 10.0. However, it is best to parse the RotD records to be sure, rather than assuming.

For a typical CyberShake deterministic run, the size of the RotD data per rupture variation is: 56 bytes (header) + 4 bytes (int number of records) + 16 bytes (RotD record) x 22 (periods) = 412 bytes.

Duration files

Duration data is stored in duration records, defined in C as:

#define ARIAS_INTENSITY 0
#define ENERGY_INTEGRAL 1
#define CAV 2
#define DV 3
#define DA 4
#define D5_75 5
#define D5_95 6
#define D20_80 7

#define X_COMP 0
#define Y_COMP 1

struct duration_record {
 int type;
 int type_value;
 int component;
 float value;
};
  • type: Type of the duration metric. Can take the values ARIAS_INTENSITY (0), ENERGY_INTEGRAL (1), CAV (2), DV (3), or DA (4).
  • type_value: An additional modifier of the duration metric - only makes sense for DV or DA. Can take values D5_75 (5), D5_95 (6), or D20_80 (7).
  • component: X (0) or Y (1).
  • value: The value of this duration metric.

The format for the duration files is:

<RV 1 header>
<RV 1 number of duration records>
<RV 1, record 1>
<RV 1, record 2>
...
<RV 1, record D>
<RV 2 header>
<RV 2 number of duration records>
<RV 2, record 1>
<RV 2, record 2>
...
<RV 2, record D>
<RV n header>
<RV n number of duration records>
<RV n, record 1>
...
<RV n, record D>

Again, the rupture variations are NOT required to be in numerical order.

Typically, we calculate 9 duration metrics: energy integral, DV5-75, DV5-95, DV20-80, arias intensity, DA5-75, DA5-95, DA20-80, CAV.

For a typical CyberShake deterministic run, the size of the duration data per rupture variation is: 56 bytes (header) + 4 bytes (int number of records) + 16 bytes (RotD record) x 9 (duration metrics) = 204 bytes.