Simulation result files

The simulator produces HDF5 files containing metadata and simulated time series for various quantities. Below we only describe the file format. We strongly discourage interacting directly with the raw HDF5 format as it may change in the future. It is preferable to use the provided file reader interface. See Interface to simulator result files for instructions.

Warning

The format has changed after the switch to chunked processing in preparation of the Mojito common dataset.

Time series

We distinguish two categories of sampled data:

• “actual” data that the real instrument would send to earth

• “debug” quantities computed by the simulator but not available in actual data

There are two variants of the file format, differing in the included quantities.

• “basic” contains the “actual” datasets as well as a small selection of “debug” data which is frequently used for testing and analysis

• “extended” contains the above as well as many intermediate results produced during the simulation

Actual data is stored in a group named as the quantity, as a continuous 1D HDF5 dataset named as the MOSA or spacecraft the data refers to. Debug data is organized the same but stored in a subgroup “debug” of the file. Examples for dataset paths are

/sci_dws_phis/12
/moc_time_correlations/3
/debug/sci_carrier_offsets/23

Time grids

The samples for a given dataset correspond to one of four regularly spaced time grids

• Sample rate for actual data (“Regular”)

• Higher sample rate used internally for the simulation (“Physics”)

• Same as “Physics” but covering a larger range to include telemetry (“Extended”)

• Low sample rate telemetry updates (“Telemetry”)

The sample times are not stored explicitly but have to be recovered from the metadata according to the relations \(t = t_0 + i \Delta t\), where \(\Delta t\) is given by the metadata items dt, physics_dt, or telemetry_dt for regular, physics/extended, or telemetry grids. \(t_0\) is given by metadata item t0 for all grids. The indices \(i\) for the samples cover a range given by HDF5 attributes index_start and index_stop of a given dataset, i.e. index_start <= i < index_stop. The start indices for datasets for the basic and physics grid are zero, whereas they can be negative for extended and telemetry grids. Redundantly, the metadata item telemetry_t0 provides the first element of the telemetry time grid.

All times are defined with respect to the LISA_EPOCH_TCB defined in the Lisaconstants package. Note however that this is only by convention, there is nothing stopping users from using different conventions. For example, using orbit and GW files version 2.* will lead to results also using the same time conventions. Producing such result files is strongly discouraged and only allowed for reasons of backward compatibility.

Actual data

Name	Time grid	MOSA or SC	Units
sci_dws_phis	Regular	Per MOSA	rad/s
sci_dws_etas	Regular	Per MOSA	rad/s
sci_carriers	Regular	Per MOSA	Hz
sci_usbs	Regular	Per MOSA	Hz
tmi_carriers	Regular	Per MOSA	Hz
tmi_usbs	Regular	Per MOSA	Hz
ref_carriers	Regular	Per MOSA	Hz
ref_usbs	Regular	Per MOSA	Hz
mprs	Regular	Per MOSA	s
moc_time_correlations	Telemetry	Per SC	s

Basic debug data

Name	Time grid	MOSA or SC	Units
sci_carrier_offsets	Regular	Per MOSA	Hz
sci_carrier_fluctuations	Regular	Per MOSA	Hz
sci_usb_offsets	Regular	Per MOSA	Hz
sci_usb_fluctuations	Regular	Per MOSA	Hz
tmi_carrier_offsets	Regular	Per MOSA	Hz
tmi_carrier_fluctuations	Regular	Per MOSA	Hz
tmi_usb_offsets	Regular	Per MOSA	Hz
tmi_usb_fluctuations	Regular	Per MOSA	Hz
ref_carrier_offsets	Regular	Per MOSA	Hz
ref_carrier_fluctuations	Regular	Per MOSA	Hz
ref_usb_offsets	Regular	Per MOSA	Hz
ref_usb_fluctuations	Regular	Per MOSA	Hz

Extended debug data

Name	Time grid	MOSA or SC	Units
clock_noise_offsets	Physics	Per SC	s/s
clock_noise_fluctuations	Physics	Per SC	s/s
clock_noise_fluctuations_withinitial	Extended	Per SC	s/s
integrated_clock_noise_fluctuations_withinitial	Extended	Per SC	s
integrated_clock_noise_fluctuations	Physics	Per SC	s
sc_jitter_phis	Physics	Per SC	rad/s
sc_jitter_etas	Physics	Per SC	rad/s
sc_jitter_thetas	Physics	Per SC	rad/s
tps_wrt_scet	Physics	Per SC	s
tps_wrt_tcb	Physics	Per SC	s
moc_time_correlation_noises	Telemetry	Per SC	s
scet_wrt_tps_local	Physics	Per SC	s
scet_wrt_tcb_withinitial	Extended	Per SC	s
pprs	Physics	Per MOSA	s
d_pprs	Physics	Per MOSA	s/s
gws	Physics	Per MOSA	s/s
glitch_tms	Physics	Per MOSA	m/s
glitch_lasers	Physics	Per MOSA	Hz
tdir_modulations_tseries	Physics	Per MOSA	Hz
laser_noises	Physics	Per MOSA	Hz
modulation_noises	Physics	Per MOSA	s/s
backlink_noises	Physics	Per MOSA	s/s
testmass_noises	Physics	Per MOSA	m/s
ranging_noises	Physics	Per MOSA	s
oms_sci_carrier_noises	Physics	Per MOSA	s/s
oms_sci_usb_noises	Physics	Per MOSA	s/s
oms_tmi_carrier_noises	Physics	Per MOSA	s/s
oms_tmi_usb_noises	Physics	Per MOSA	s/s
oms_ref_carrier_noises	Physics	Per MOSA	s/s
oms_ref_usb_noises	Physics	Per MOSA	s/s
mosa_jitter_phis	Physics	Per MOSA	rad/s
mosa_jitter_etas	Physics	Per MOSA	rad/s
mosa_jitter_xs	Physics	Per MOSA	m/s
dws_phi_noises	Physics	Per MOSA	rad/s
dws_eta_noises	Physics	Per MOSA	rad/s
mosa_total_jitter_phis	Physics	Per MOSA	rad/s
mosa_total_jitter_etas	Physics	Per MOSA	rad/s
local_carrier_offsets	Physics	Per MOSA	Hz
local_carrier_fluctuations	Physics	Per MOSA	Hz
local_usb_offsets	Physics	Per MOSA	Hz
local_usb_fluctuations	Physics	Per MOSA	Hz
local_ttls	Physics	Per MOSA	m/s
distant_ttls	Physics	Per MOSA	m/s
distant_carrier_offsets	Physics	Per MOSA	Hz
distant_carrier_fluctuations	Physics	Per MOSA	Hz
distant_usb_offsets	Physics	Per MOSA	Hz
distant_usb_fluctuations	Physics	Per MOSA	Hz
adjacent_carrier_offsets	Physics	Per MOSA	Hz
adjacent_carrier_fluctuations	Physics	Per MOSA	Hz
adjacent_usb_offsets	Physics	Per MOSA	Hz
adjacent_usb_fluctuations	Physics	Per MOSA	Hz
local_sci_carrier_offsets	Physics	Per MOSA	Hz
local_sci_carrier_fluctuations	Physics	Per MOSA	Hz
local_sci_usb_offsets	Physics	Per MOSA	Hz
local_sci_usb_fluctuations	Physics	Per MOSA	Hz
distant_sci_carrier_offsets	Physics	Per MOSA	Hz
distant_sci_carrier_fluctuations	Physics	Per MOSA	Hz
distant_sci_usb_offsets	Physics	Per MOSA	Hz
distant_sci_usb_fluctuations	Physics	Per MOSA	Hz
tps_sci_carrier_offsets	Physics	Per MOSA	Hz
tps_sci_carrier_fluctuations	Physics	Per MOSA	Hz
tps_sci_usb_offsets	Physics	Per MOSA	Hz
tps_sci_usb_fluctuations	Physics	Per MOSA	Hz
tps_sci_dws_phis	Physics	Per MOSA	rad/s
tps_sci_dws_etas	Physics	Per MOSA	rad/s
local_tmi_carrier_offsets	Physics	Per MOSA	Hz
local_tmi_carrier_fluctuations	Physics	Per MOSA	Hz
local_tmi_usb_offsets	Physics	Per MOSA	Hz
local_tmi_usb_fluctuations	Physics	Per MOSA	Hz
adjacent_tmi_carrier_offsets	Physics	Per MOSA	Hz
adjacent_tmi_carrier_fluctuations	Physics	Per MOSA	Hz
adjacent_tmi_usb_offsets	Physics	Per MOSA	Hz
adjacent_tmi_usb_fluctuations	Physics	Per MOSA	Hz
tps_tmi_carrier_offsets	Physics	Per MOSA	Hz
tps_tmi_carrier_fluctuations	Physics	Per MOSA	Hz
tps_tmi_usb_offsets	Physics	Per MOSA	Hz
tps_tmi_usb_fluctuations	Physics	Per MOSA	Hz
local_ref_carrier_offsets	Physics	Per MOSA	Hz
local_ref_carrier_fluctuations	Physics	Per MOSA	Hz
local_ref_usb_offsets	Physics	Per MOSA	Hz
local_ref_usb_fluctuations	Physics	Per MOSA	Hz
adjacent_ref_carrier_offsets	Physics	Per MOSA	Hz
adjacent_ref_carrier_fluctuations	Physics	Per MOSA	Hz
adjacent_ref_usb_offsets	Physics	Per MOSA	Hz
adjacent_ref_usb_fluctuations	Physics	Per MOSA	Hz
tps_ref_carrier_offsets	Physics	Per MOSA	Hz
tps_ref_carrier_fluctuations	Physics	Per MOSA	Hz
tps_ref_usb_offsets	Physics	Per MOSA	Hz
tps_ref_usb_fluctuations	Physics	Per MOSA	Hz
scet_sci_carrier_offsets	Physics	Per MOSA	Hz
scet_sci_carrier_fluctuations	Physics	Per MOSA	Hz
scet_sci_usb_offsets	Physics	Per MOSA	Hz
scet_sci_usb_fluctuations	Physics	Per MOSA	Hz
scet_sci_dws_phis	Physics	Per MOSA	rad/s
scet_sci_dws_etas	Physics	Per MOSA	rad/s
scet_tmi_carrier_offsets	Physics	Per MOSA	Hz
scet_tmi_carrier_fluctuations	Physics	Per MOSA	Hz
scet_tmi_usb_offsets	Physics	Per MOSA	Hz
scet_tmi_usb_fluctuations	Physics	Per MOSA	Hz
scet_ref_carrier_offsets	Physics	Per MOSA	Hz
scet_ref_carrier_fluctuations	Physics	Per MOSA	Hz
scet_ref_usb_offsets	Physics	Per MOSA	Hz
scet_ref_usb_fluctuations	Physics	Per MOSA	Hz
electro_sci_carrier_offsets	Physics	Per MOSA	Hz
electro_sci_carrier_fluctuations	Physics	Per MOSA	Hz
electro_sci_usb_offsets	Physics	Per MOSA	Hz
electro_sci_usb_fluctuations	Physics	Per MOSA	Hz
electro_tmi_carrier_offsets	Physics	Per MOSA	Hz
electro_tmi_carrier_fluctuations	Physics	Per MOSA	Hz
electro_tmi_usb_offsets	Physics	Per MOSA	Hz
electro_tmi_usb_fluctuations	Physics	Per MOSA	Hz
electro_ref_carrier_offsets	Physics	Per MOSA	Hz
electro_ref_carrier_fluctuations	Physics	Per MOSA	Hz
electro_ref_usb_offsets	Physics	Per MOSA	Hz
electro_ref_usb_fluctuations	Physics	Per MOSA	Hz
filtered_sci_carrier_offsets	Physics	Per MOSA	Hz
filtered_sci_carrier_fluctuations	Physics	Per MOSA	Hz
filtered_sci_usb_offsets	Physics	Per MOSA	Hz
filtered_sci_usb_fluctuations	Physics	Per MOSA	Hz
filtered_sci_dws_phis	Physics	Per MOSA	rad/s
filtered_sci_dws_etas	Physics	Per MOSA	rad/s
filtered_tmi_carrier_offsets	Physics	Per MOSA	Hz
filtered_tmi_carrier_fluctuations	Physics	Per MOSA	Hz
filtered_tmi_usb_offsets	Physics	Per MOSA	Hz
filtered_tmi_usb_fluctuations	Physics	Per MOSA	Hz
filtered_ref_carrier_offsets	Physics	Per MOSA	Hz
filtered_ref_carrier_fluctuations	Physics	Per MOSA	Hz
filtered_ref_usb_offsets	Physics	Per MOSA	Hz
filtered_ref_usb_fluctuations	Physics	Per MOSA	Hz
scet_mprs	Physics	Per MOSA	s
tps_mprs	Physics	Per MOSA	s
filtered_mprs	Physics	Per MOSA	s
scet_wrt_tps_distant	Physics	Per MOSA	s
fplan_ts	Physics	Per MOSA	Hz
mprs_unambiguous	Regular	Per MOSA	s
iprs	Regular	Per MOSA	s

Metadata

The root group of the files has the following attributes

• version Version number of the simulator

• version_format Version of the file format

• git_url URL of the simulator code repository

• metadata_json JSON string storing dictionary of simulation metadata

• description optional free-form text description

Currently, version and version_format are identical but for the future it is planned that the latter will only be synced to the former when the format changes.

The simulation metadata is stored as a flat dictionary with the following entries

seed: int
dt: float
t0: float
size: int
fs: float
duration: float
initial_telemetry_size: int
telemetry_downsampling: int
telemetry_fs: float
telemetry_dt: float
telemetry_size: int
telemetry_t0: float
physics_upsampling: int
physics_size: int
physics_dt: float
physics_fs: float
aafilter_coeffs: list[float] | None
aafilter_group_delay: float
central_freq: float
offset_freqs: dict[str, float]
lock_config: str | None
lock: dict[str, str]
fplan_file: str | None
fplan: dict[str, float | None] | None
laser_asds: dict[str, float]
modulation_asds: dict[str, float]
modulation_freqs: dict[str, float]
tdir_modulations: str
clock_asds: dict[str, float]
clock_offsets: dict[str, float]
clock_freqoffsets: dict[str, float]
clock_freqlindrifts: dict[str, float]
clock_freqquaddrifts: dict[str, float]
clockinv_tolerance: float
clockinv_maxiter: int
ranging_biases: dict[str, float]
ranging_asds: dict[str, float]
prn_ambiguity: float | None
backlink_asds: dict[str, float]
backlink_fknees: dict[str, float]
testmass_asds: dict[str, float]
testmass_fknees: dict[str, float]
testmass_fbreak: dict[str, float]
testmass_frelax: dict[str, float]
testmass_shape: str
oms_sci_carrier_asds: dict[str, float]
oms_sci_usb_asds: dict[str, float]
oms_tmi_carrier_asds: dict[str, float]
oms_tmi_usb_asds: dict[str, float]
oms_ref_carrier_asds: dict[str, float]
oms_ref_usb_asds: dict[str, float]
oms_fknees: dict[str, float]
ttl_coeffs_local_phis: dict[str, float]
ttl_coeffs_distant_phis: dict[str, float]
ttl_coeffs_local_etas: dict[str, float]
ttl_coeffs_distant_etas: dict[str, float]
sc_jitter_phi_asds: dict[str, float]
sc_jitter_eta_asds: dict[str, float]
sc_jitter_theta_asds: dict[str, float]
mosa_jitter_x_asds: dict[str, float]
mosa_jitter_phi_asds: dict[str, float]
mosa_jitter_eta_asds: dict[str, float]
dws_asds: dict[str, float]
laser_shape: str
moc_time_correlation_asds: dict[str, float]
sc_jitter_phi_fknees: dict[str, float]
sc_jitter_eta_fknees: dict[str, float]
sc_jitter_theta_fknees: dict[str, float]
mosa_jitter_phi_fknees: dict[str, float]
mosa_jitter_eta_fknees: dict[str, float]
delay_isc_min: float
delay_isc_max: float
delay_clock_max: float
mosa_angles: dict[str, float]
orbit_file: str | None
orbit_dataset: str | None
orbit_t0: float
gw_file: str | None
gw_group: str | None
glitch_file: str | None
interpolation_order: int
electro_delays_scis: dict[str, float]
electro_delays_tmis: dict[str, float]
electro_delays_refs: dict[str, float]