File Formats

This page documents the various file formats used by Salvus.

Output File Formats

Salvus can directly output point, surface, and volumetric data to HDF5 files. Of these, surface and volumetric data are stored with the same layout, while two different options exists for the point data.

Point Receiver Output File Formats

Salvus has some built-in utilities to conveniently work with receiver files. This works, independent of the chosen receiver file format, as follows:

Copy
# When directly using the Salvus API:
j = sn.api.run(input_file=..., ...)
event_data = j.get_as_event()

# When using SalvusProject:
event_data = p.waveforms.get(data_name="...", events=...)[0]

# Get a receiver as an ObsPy Stream object.
st = ed.get_receiver_data("receiver_name", receiver_field="displacement")

If you want to know about the actual file layouts on disk, please read on.

HDF5 Block Receivers

By selecting hdf5 as the point output format Salvus will store all receiver data in a single HDF5 file:

Copy
w.output.point_data.format = "hdf5"

These files should be easy to read in any data processing software package. Please let us know if you need assistance. We recommend to use this file format in most cases.

The internal HDF5 data structure is the same in 2-D and 3-D:

Copy
# Meta-data for receivers in acoustic media.
coordinates_ACOUSTIC_point
names_ACOUSTIC_point
receiver_ids_ACOUSTIC_point

# Meta-data for receivers in elastic media.
coordinates_ELASTIC_point
names_ELASTIC_point
receiver_ids_ELASTIC_point

# Point data.
point/
    # Time-series meta-data.
    reference_time_in_seconds
    sampling_rate_in_hertz
    start_time_in_seconds

    # The actual point data, per field.
    displacement
    phi
    ...

For PHYSICS being either ELASTIC or ACOUSTIC the following data sets are defined if at least one receiver of the given physics is part of a simulation:

• coordinates_PHYSICS_point: An array of coordinates, one for each receiver of the given physics.
• names_PHYSICS_point: An array of receiver names, one for each receiver of the given physics.
• receiver_ids_PHYSICS_point: Indices to map the receivers back to the order in the original input file. For reasons of efficiency Salvus does not retain the order of the receivers when running simulations in parallel.

The point/ group contains the actual time series together with some meta-information:

• reference_time_in_seconds: What time zero refers to. Useful to absolutely locate samples in time. Will be zero if you did not explicitly set this.
• sampling_rate_in_hertz: The sampling rate in Hertz.
• start_time_in_seconds: The time of the first sample relative to time zero. Might be negative.

The actual receiver data, depending on the output field, will be stored in hypercubes, one per output field, e.g.: displacement, phi, stress, ...

The dimension of each hypercube will be (#receivers_with_that_physics, #components, #samples).

ASDF

The Adaptable Seismic Data Format (ASDF) is a modern HDF5-based data format capable of efficiently handling large amounts of heterogeneous time series data (e.g. varying length, sampling rates, ... for each trace) including comprehensive meta data, especially suitable for use in earthquake seismology. Salvus can directly output to it by selecting asdf as the point data output format.

Copy
w.output.point_data.format = "asdf"

Please refer to the ASDF documentation for details on the internal data structure and for libraries able to work with it.

Compared to the HDF5 block receiver output it is a bit slower to work with it but it is worth it for many applications. We recommend to use this when working with recorded seismological data.

Surface/Volume Output File Formats

Salvus currently only supports hdf5 as the output format for surface and volume data.

Copy
w.output.surface_data.format = "hdf5"
w.output.volume_data.format = "hdf5"

These files are always accompanied by one or more .xdmf files that can used to visualize the HDF5 files directly in ParaView as described in the visualization section.

Salvus, independent of the number of cores used to run it in parallel, will always only output to a single surface or volume data output file.

Data is stored per output field and per element:

Copy
# Meta-data for output of acoustic media.
connectivity_ACOUSTIC(_surface)
coordinates_ACOUSTIC(_surface)

# Meta-data for output of elastic media.
connectivity_ELASTIC(_surface)
coordinates_ELASTIC(_surface)

# Surface/Volume data.
volume/ or surface/
    # Surface/Volume data meta-data.
    reference_time_in_seconds
    sampling_rate_in_hertz
    start_time_in_seconds

    # The actual surface/volume data, per field.
    displacement
    phi

For PHYSICS being either ELASTIC or ACOUSTIC the following data sets are defined if at least one output field of the corresponding physics was chosen:

• connectivity_PHYSICS(_surface): The element connectivity for output of that physics.
• coordinates_PHYSICS(_surface): The actual coordinates for all control notes of that physics.

The volume/ or surface/ group contains the actual volume/surface data together with some meta-information:

• reference_time_in_seconds: What time zero refers to. Useful to absolutely locate samples in time. Will be zero if you did not explicitly set this.
• sampling_rate_in_hertz: The sampling rate in Hertz.
• start_time_in_seconds: The time of the first sample relative to time zero. Might be negative.

The actual surface/volume data, depending on the output field, will be stored in hypercubes, one per output field, e.g.: displacement, phi, stress, ...

The dimension of each hypercube will be (#time_step, #element_index, #component, #indices_in_element).

The last dimension might be padded with zeros.