View source for CyberShake output data formats

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.