= Fault System Solution Zip File Format Documentation =

UCERF3 (and potentially other forecast) data is stored in a zip file format, this page describes how to parse these zip files. If you are using Java, a parser is already written in OpenSHA via the [source:trunk/dev/scratch/UCERF3/utils/FaultSystemIO.java scratch.UCERF3.utils.FaultSystemIO] class.

== File Formats Used ==

You must write a parser for each of the following file formats in order to load in a fault system solution.

=== Double array binary file ===

These files contain an array of double values in a binary format. These files simply contain a series of big endian 8 bit double precision floating point numbers. The size of this file will be equal to the number of values x 8 bits.

=== Integer array list binary file ===

These files contain a list of integer arrays in a binary format. All file entries are 4-bit big endian integer values. The first value in the file is the number of integer arrays stored in the file. Then each array is written to the file by first writing the number of elements in the array, then each value in the array. For example, consider the following 3 arrays:

{{{
[ 0 6 2 4 ]
[ 3 6 2 ]
[ 3 7 9 1 4 7 ]
}}}

This would be written as (all stored as big endian 4-bit integers):

'''[[span(style=color: #FF0000, 3)]] [[span(style=color: #0000FF, 4)]] 0 6 2 4 [[span(style=color: #0000FF, 3)]] 3 6 2 [[span(style=color: #0000FF, 6)]] 3 7 9 1 4 7'''

In this example, '''[[span(style=color: #FF0000, the number of arrays is in red)]]''', '''[[span(style=color: #0000FF, each array's size in blue)]]''', '''and array data is in black'''.

=== Fault section data XML file ===

Each fault subsection is stored in an XML file, an example of which is shown below.

{{{
<?xml version="1.0" encoding="UTF-8"?>

<OpenSHA>
  <FaultSectionPrefDataList>
    <!--- Each fault subsection is listed in it's own element so ensure correct ordering.
Each subsection element name will be i0, i1, i2, ... i[N-1] for N subsections. Note that
some fields may be NaN for certain solutions. -->
    <i0 sectionId="0" sectionName="Los Alamos extension, Subsection 0" aveLongTermSlipRate="NaN"
slipRateStdDev="0.0" aveDip="30.0" aveRake="NaN" aveUpperDepth="0.0" aveLowerDepth="12.0"
aseismicSlipFactor="0.1" couplingCoeff="1.0" dipDirection="205.15857"
parentSectionName="Los Alamos extension" parentSectionId="780" connector="false">
      <!-- This defines a polygon representing the geologic fault zone. Note that UCERF3 uses
a combination of this polygon and a buffered fault trace as described in UCERF3 Appendix O. -->
      <ZonePolygon name="Unnamed Region">
        <LocationList>
          <Location Latitude="34.562639" Longitude="-119.867803" Depth="0.0"/>
          <Location Latitude="34.54856" Longitude="-119.878996" Depth="0.0"/>
          <Location Latitude="34.586297" Longitude="-119.926461" Depth="0.0"/>
          <Location Latitude="34.630493" Longitude="-120.091308" Depth="0.0"/>
          <Location Latitude="34.647866" Longitude="-120.086651" Depth="0.0"/>
          <Location Latitude="34.60288" Longitude="-119.919064" Depth="0.0"/>
        </LocationList>
      </ZonePolygon>
      <!-- This is the actual fault trace. Note that order is important and should follow the
Aki-Richards definition -->
      <FaultTrace name="Los Alamos extension 1">
        <Location Latitude="34.63918" Longitude="-120.08897999999999" Depth="0.0"/>
        <Location Latitude="34.608190666873426" Longitude="-119.97328407378366" Depth="0.0"/>
      </FaultTrace>
    </i0>
    <i1 sectionId="1" ...>
        ...
    </i1>
    ...
    <i[N-1] sectionId="[N-1]" ...>
        ...
    </i[N-1]>
  </FaultSectionPrefDataList>
</OpenSHA>
}}}

=== Grid Sources XML file ===

Some solutions will contain gridded seismicity magnitude frequency distributions. Here is an example XML file:

NOTE: UCERF3 uses the RELM region evenly discretized at 0.1 degrees for gridded seismicity. Due to the complexities involved in reproducing our gridding exactly, a file is posted here with grid node indexes and locations for this region: http://opensha.usc.edu/ftp/kmilner/ucerf3/relm_gridded_region.csv

{{{
<?xml version="1.0" encoding="UTF-8"?>

<OpenSHA>
  <!-- this explains the evenly gridded region for on which gridded seismicity is distributed. See
class javadocs here for more information: http://opensha.usc.edu/JavaDocs/org/opensha/commons/geo/GriddedRegion.html -->
  <evenlyGriddedGeographicRegion spacing="0.1" numPoints="7636">
    <anchor>
      <Location Latitude="31.5" Longitude="-125.4" Depth="0.0"/>
    </anchor>
    <Region name="RELM_TESTING Region">
      <LocationList>
        <Location Latitude="43.0" Longitude="-125.2" Depth="0.0"/>
        <Location Latitude="43.0" Longitude="-119.0" Depth="0.0"/>
        <Location Latitude="39.4" Longitude="-119.0" Depth="0.0"/>
        <Location Latitude="35.7" Longitude="-114.00000000000001" Depth="0.0"/>
        <Location Latitude="34.3" Longitude="-113.1" Depth="0.0"/>
        <Location Latitude="32.9" Longitude="-113.5" Depth="0.0"/>
        <Location Latitude="32.2" Longitude="-113.6" Depth="0.0"/>
        <Location Latitude="31.7" Longitude="-114.5" Depth="0.0"/>
        <Location Latitude="31.5" Longitude="-117.1" Depth="0.0"/>
        <Location Latitude="31.900000000000002" Longitude="-117.90000000000002" Depth="0.0"/>
        <Location Latitude="32.8" Longitude="-118.40000000000002" Depth="0.0"/>
        <Location Latitude="33.7" Longitude="-121.0" Depth="0.0"/>
        <Location Latitude="34.2" Longitude="-121.6" Depth="0.0"/>
        <Location Latitude="37.7" Longitude="-123.80000000000001" Depth="0.0"/>
        <Location Latitude="40.2" Longitude="-125.4" Depth="0.0"/>
        <Location Latitude="40.5" Longitude="-125.4" Depth="0.0"/>
      </LocationList>
    </Region>
  </evenlyGriddedGeographicRegion>
  <!-- this gives magnitude frequency distributions for each grid node. Each node can have an Unassociated MFD (seismicity at
that node that is not associated with a mapped fault), and a sub seismogenic MFD if a fault crosses the node. Num is the total
number of grid nodes.-->
  <MFDNodeList num="7636">
    <MFDNode index="0">
      <!-- this describes the discretization of the MFD function -->
      <UnassociatedFD name="Incremental Mag Freq Dist" tolerance="1.0000000000000001E-7" num="90" minX="0.05" maxX="8.950000000000001" delta="0.1">
        <Points>
          <!-- points on the MFD function -->
          <Point x="0.05" y="9.218866335939037"/>
          <Point x="0.15000000000000002" y="7.322805822785568"/>
          <Point x="0.25" y="5.816711422441951"/>
          <Point x="0.35000000000000003" y="4.620378116088878"/>
          <Point x="0.45" y="3.6700967927115817"/>
          ...
        </Points>
      </UnassociatedFD>
    </MFDNode>
    <MFDNode index="1">
      <!-- only some nodes have sub seismogenic MFDs -->
      <SubSeisMFD name="Incremental Mag Freq Dist" tolerance="1.0000000000000001E-7" num="90" minX="0.05" maxX="8.950000000000001" delta="0.1">
        <Points>
          <Point x="0.05" y="7.173882325337919"/>
          <Point x="0.15000000000000002" y="5.69841728360539"/>
          ...
        </Points>
      </SubSeisMFD>
      <UnassociatedFD name="Incremental Mag Freq Dist" tolerance="1.0000000000000001E-7" num="90" minX="0.05" maxX="8.950000000000001" delta="0.1">
        <Points>
          <Point x="0.05" y="9.51974524882418"/>
          <Point x="0.15000000000000002" y="7.561802438523384"/>
          <Point x="0.25" y="6.006553182326047"/>
          ...
        </Points>
      </UnassociatedFD>
    </MFDNode>
    ...
  </MFDNodeList>
</OpenSHA>
}}}

== Zip File Contents ==

The following files constitute a Fault System Solution

||= File Name =||= File Format =||= Optional? =||= Description =||
||'''fault_sections.xml'''||XML (see above)||no||This XML file describes each sub section in the Fault System. These indexes will be referred to in the rup_sections.bin file when defining ruptures.||
||'''grid_sources.xml'''||XML (see above)||yes||This XML file, if present, gives gridded seismicity MFDs at each node in the region that this solution covers.||
||'''info.txt'''||ASCII||yes||This text file, if present, contains metadata describing the solution.||
||'''mags.bin'''||Double array binary||no||This file gives magnitudes for each rupture. It contains one double value for each rupture index, in order.||
||'''rakes.bin'''||Double array binary||no||This file gives average rakes for each rupture. It contains one double value for each rupture index, in order.||
||'''rates.bin'''||Double array binary||no||This file gives annualized rates for each rupture. It contains one double value for each rupture index, in order.||
||'''rup_areas.bin'''||Double array binary||no||This file gives areas for each rupture in SI units (square meters). It contains one double value for each rupture index, in order.||
||'''rup_lengths.bin'''||Double array binary||yes||This file, if present, gives lengths for each rupture in SI units (meters). It contains one double value for each rupture index, in order.||
||'''rup_sections.bin'''||Integer array list binary||no||This lists the sub sections involved in each rupture. It consists of numRuptures arrays, each of which lists the sub sections indexes (as defined in fault_sections.xml) for that rupture||
||'''sect_areas.bin'''||Double array binary||yes||This file gives areas for each fault sub section in SI units (square meters). It contains one double value for each sub section index, in order.||