Instrument

Instrumental simulation for the LISA mission. See [1] for a more detailed description of the underlying physical models.

class lisainstrument.instrument.Instrument(*, size: int = 1200, dt: float = 0.25, t0: float | str = 'orbits', seed: int | None = None, physics_upsampling: int = 4, aafilter: None | tuple[str, float, float, float] | list[float] | ndarray = ('kaiser', 240, 1.1, 2.9), telemetry_downsampling: int = 345600, initial_telemetry_size: int = 0, orbits: str | dict[str, float] = 'static', orbit_dataset: str = 'tps/ppr', gws: str | None | dict[str, ndarray] = None, interpolation: None | tuple[str, int] = ('lagrange', 31), glitches: str | None = None, lock: str | dict[str, str] = 'N1-12', fplan: str | float | dict[str, float] | ndarray = 'static', laser_asds: float | dict[str, float] = 30.0, laser_shape: str = 'white+infrared', central_freq: float = 281600000000000.0, offset_freqs='default', modulation_asds: None | str | float | dict[str, float] = 'default', modulation_freqs: str | float | dict[str, float] = 'default', tdir_modulations: None | dict[str, Callable] = None, clock_asds: float | dict[str, float] = 6.32e-14, clock_offsets: float | dict[str, float] = 0.0, clock_freqoffsets: str | float | dict[str, float] = 'default', clock_freqlindrifts: str | float | dict[str, float] = 'default', clock_freqquaddrifts: str | float | dict[str, float] = 'default', clockinv_tolerance: float = 1e-10, clockinv_maxiter: int = 5, backlink_asds: float | dict[str, float] = 3e-12, backlink_fknees: float | dict[str, float] = 0.002, testmass_asds: float | dict[str, float] = 2.4e-15, testmass_fknees: float | dict[str, float] = 0.0004, testmass_fbreak: float | dict[str, float] = 0.008, testmass_shape: str = 'original', testmass_frelax: float | dict[str, float] = 8e-05, oms_asds: tuple[float | dict[str, float], ...] = (6.35e-12, 1.25e-11, 1.42e-12, 3.38e-12, 3.32e-12, 7.9e-12), oms_fknees: float | dict[str, float] = 0.002, moc_time_correlation_asds: float | dict[str, float] = 0.42, mosa_longitudinal_jitter_asds: float | dict[str, float] = 2e-09, sc_angular_jitter_asds: tuple[float | dict[str, float], ...] = (5e-09, 5e-09, 5e-09), sc_angular_jitter_fknees: tuple[float | dict[str, float], ...] = (0.0008, 0.0008, 0.0008), mosa_angular_jitter_asds: tuple[float | dict[str, float], ...] = (2e-09, 2e-09), mosa_angular_jitter_fknees: tuple[float | dict[str, float], ...] = (0.0008, 0.0008), mosa_angles: str | float | dict[str, float] = 'default', ttl_coeffs='default', dws_asds: float | dict[str, float] = 2.0895522388059703e-10, ranging_biases: float | dict[str, float] = 0.0, ranging_asds: float | dict[str, float] = 3e-09, prn_ambiguity: None | int | float = None, electro_delays: tuple[float | dict[str, float], ...] = (0, 0, 0), delay_isc_min: float = 6.0, delay_isc_max: float = 12.0, delay_clock_max: float = 50.0, chunk_gw_files: bool = False, noises_f_min_hz: float | None = 5e-05, clock_f_min_hz: float = 1e-05, orbit_t0_margin: float = 75.0)

User interface for running an instrumental simulation.

Parameters:

• size – number of measurement samples to generate

• dt – sampling period [s]

• t0 – initial time [s], or ‘orbits’ to match that of the orbits (see also orbit_t0_margin)

• seed – seed for random noise generators, or None to generate a random seed

• physics_upsampling – ratio of sampling frequencies for physics vs. measurement simulation

• aafilter – antialiasing filter coefficients, tuple specifying Kaiser filter method, or None for no filter; to design a filter from a Kaiser window, use a tuple (‘kaiser’, attenuation [dB], f1 [Hz], f2 [Hz]) with f1 < f2 the frequencies defining the transition band

• telemetry_downsampling – ratio of sampling frequencies for measurements vs. telemetry events

• initial_telemetry_size – number of telemetry samples before lisainstrument.Instrument.t0

• orbits – path to orbit file, dictionary of constant PPRs for static arms, ‘static’ for a set of static PPRs corresponding to a fit of Keplerian orbits around t = 0, or dictionary of PPR time series

• orbit_dataset – datasets to read from orbit file, must be ‘tps/ppr’ or ‘tcb/ltt’; if set to ‘tps/ppr’ (default), read proper pseudo-ranges (PPRs) in TPSs (proper times), if set to ‘tcb/ltt’, read light travel times (LTTs) in TCB (coordinate time). If orbits are not read from file orbit_dataset is unused and only default value is allowed.

• gws – path to gravitational-wave file. If orbit_dataset is 'tps/ppr', we try to read link responses as functions of the TPS instead of link responses in the TCB (fallback behavior)

• interpolation – interpolation method and parameters; use a tuple (‘lagrange’, order) where order is the Lagrange interpolation order, or None for no interpolation.

• glitches – path to glitch file

• lock – pre-defined laser locking configuration (e.g., ‘N1-12’ is configuration N1 with 12 as primary laser), or ‘six’ for 6 lasers locked on cavities, or a dictionary of locking conditions

• fplan – path to frequency-plan file, dictionary of locking beatnote frequencies [Hz], or ‘static’ for a default set of constant locking beatnote frequencies

• laser_asds – dictionary of amplitude spectral densities for laser noise [Hz/sqrt(Hz)]

• laser_shape – laser noise spectral shape, either ‘white’ or ‘white+infrared’

• central_freq – laser central frequency from which all offsets are computed [Hz]

• offset_freqs – dictionary of laser frequency offsets for unlocked lasers [Hz], defined with respect to lisainstrument.Instrument.central_freq, or ‘default’ for a default set of frequency offsets that yield valid beatnote frequencies for ‘six’ lasers locked on cavity and default set of constant PPRs

• modulation_asds – dictionary of amplitude spectral densities for modulation noise on each MOSA [s/sqrt(Hz)], or ‘default’ for a default set of levels with a factor 10 higher on right-sided MOSAs to account for the frequency distribution system

• modulation_freqs – dictionary of modulation frequencies [Hz], or ‘default’

• tdir_modulations – dictionary of callable generators of TDIR assistance modulations that take an array of TPS times as argument, or None

• clock_asds – dictionary of clock noise amplitude spectral densities [/sqrt(Hz)]

• clock_offsets – dictionary of clock offsets from TPS [s]

• clock_freqoffsets – dictionary of clock frequency offsets [s/s], or ‘default’

• clock_freqlindrifts – dictionary of clock frequency linear drifts [s/s^2], or ‘default’

• clock_freqquaddrifts – dictionary of clock frequency quadratic drifts [s/s^3], or ‘default’

• clockinv_tolerance – convergence tolerance for clock noise inversion [s]

• clockinv_maxiter – maximum number of iterations for clock noise inversion

• backlink_asds – dictionary of amplitude spectral densities for backlink noise [m/sqrt(Hz)]

• backlink_fknees – dictionary of cutoff frequencied for backlink noise [Hz]

• testmass_asds – dictionary of amplitude spectral densities for test-mass noise [ms^(-2)/sqrt(Hz)]

• testmass_fknees – dictionary of low-frequency cutoff frequencies for test-mass noise [Hz]

• testmass_fbreak – dictionary of high-frequency break frequencies for test-mass noise [Hz]

• testmass_shape – test-mass noise spectral shape, either ‘original’ or ‘lowfreq-relax’

• testmass_frelax – dictionary of low-frequency relaxation frequencies for test-mass noise [Hz]

• oms_asds – tuple of dictionaries of amplitude spectral densities for OMS noise [m/sqrt(Hz)], ordered as (sci_carrier, sci_usb, tmi_carrier, tmi_usb, ref_carrier, ref_usb)

• moc_time_correlation_asds – dictionary of amplitude spectral densities for MOC time correlation noise [s/sqrt(Hz)], the default ASD seems rather high, this is due to the small sampling rate (default 1 / 86400s)

• oms_fknees – dictionary of cutoff frequencies for OMS noise

• ttl_coeffs – tuple (local_phi, distant_phi, local_eta, distant_eta) of dictionaries of tilt-to-length coefficients on each MOSA [m/rad], ‘default’ for a default set of coefficients, or ‘random’ to draw a set of coefficients from uniform distributions (LISA-UKOB-INST-ML-0001-i2 LISA TTL STOP Model, summary table, 2.4 mm/rad and 2.2mm/rad for distant and local coefficients, respectively)

• mosa_longitudinal_jitter_asds – dictionary of amplitude spectral densities for MOSA longitudinal jitter on the sensitive axis [m/sqrt(Hz)]

• sc_angular_jitter_asds – tuple of dictionaries of angular jitter amplitude spectral densities for spacecraft, ordered as (yaw, pitch, roll) [rad/sqrt(Hz)]

• sc_angular_jitter_fknees – tuple of dictionaries of cutoff frequencies for spacecraft angular jitter, ordered as (yaw, pitch, roll) [Hz]

• mosa_angular_jitter_asds – tuple of dictionaries of angular jitter amplitude spectral densities for MOSA, ordered as (yaw, pitch) [rad/sqrt(Hz)]

• mosa_angular_jitter_fknees – tuple of dictionaries of cutoff frequencies for MOSA angular jitter, ordered as (yaw, pitch) [Hz]

• mosa_angles – dictionary of oriented MOSA opening angles [deg], or ‘default’

• dws_asds – dictionary of amplitude spectral densities for DWS measurement noise [rad/sqrt(Hz)]

• ranging_biases – dictionary of ranging noise bias [s]

• ranging_asds – dictionary of ranging noise amplitude spectral densities [s/sqrt(Hz)]

• prn_ambiguity – distance after which PRN code repeats itself [m] (reasonable value is 300 km), None or 0 for no ambiguities

• electro_delays – tuple (sci, tmi, ref) of dictionaries for electronic delays [s]

• delay_isc_min (float) – minimum interspacecraft delay [s] that can occur in the simulation

• delay_isc_max (float) – maximum interspacecraft delay [s] that can occur in the simulation

• delay_clock_max (float) – maximum absolute clock delays [s] that can occur in the simulation

• chunk_gw_files (bool) – whether to interpolate gw files in chunked fashion or globally

• noises_f_min_hz (float|None) – cutoff frequency used for noises or None for inverse simulation length

• clock_f_min_hz (float) – cutoff frequency used for clock noise

• orbit_t0_margin (float) – Margin to be added to t0 for case t0=”orbits”

MOSAS = frozenset({'12', '13', '21', '23', '31', '32'})

MOSA indices.

SCS = frozenset({'1', '2', '3'})

Spacecraft indices.

disable_all_noises(excluding: set[str] | list[str] | str | None = None) → None

Turn off all instrumental noises.

Use excluding to specify a list of noises to keep.

Note that Doppler effect is not considered as a noise, and won’t be turned off by this method. Use disable_dopplers() to turn off Doppler effects.

Parameters:

excluding – noises to keep on, to be chosen in (‘laser’, ‘modulation’, ‘clock’, ‘test-mass’, ‘backlink’, ‘oms’, ‘ranging’, ‘angular-jitters’, ‘dws’, ‘moc-time-correlation’, ‘longitudinal-jitters’)

disable_angular_jitters()

Turn off all angular jitters.

disable_backlink_noise()

Turn off all backlink noise.

disable_clock_noise()

Turn off all imperfections on clocks.

This includes the in-band clock noise, as well as clock offsets, frequency offsets, and frequency linear and quadratic drifts.

disable_dopplers()

Set proper pseudo-range derivatives to zero to turn off Doppler effects.

disable_dws_noise()

Turn off DWS measurement noise.

disable_laser_noise()

Turn off laser noise.

disable_longitudinal_jitters()

Turn off all longitudinal jitters.

disable_moc_time_correlation_noise()

Turn off MOC time correlation noise.

disable_modulation_noise()

Turn off sideband modulation noise.

disable_oms_noise()

Turn off OMS noise in all interferometers.

disable_ranging_noises()

Turn off all pseudo-ranging noises.

disable_testmass_noise()

Turn off all test-mass noise.

export_hdf5(path='measurements.h5', *, description: str | None = None, overwrite=False, keep_all=False, cfgscheduler: SchedulerConfigParallel | SchedulerConfigSerial | None = None)

Compute simulation and store results in a hdf5 file.

This will create an HDF5 file with the time series and metadata of the simulation. By default, only a standard set of time series is included.

By default, the streams are evaluated with conservative resource usage. The number of CPUs and memory usage can be adjusted with cfgscheduler parameter (see streams.scheduler).

Parameters:

• path – Path of the file to use

• overwrite – If True, any existing file will be overwritten.

• keep_all – store all time series, not just the standard set.

• cfgscheduler – Parameters for the scheduling

export_metadata() → SimMetaData

SimMetaData data class containing all metadata

export_numpy(*, keep_all: bool, cfgscheduler: SchedulerConfigParallel | SchedulerConfigSerial | None = None) → SimResultsNumpyCore | SimResultsNumpyFull

Compute simulation and store all results in memory as numpy arrays

This returns either the full or a core set of simulation results, see export_numpy_core and export_numpy_full methods.

Note: Using this method hinders static type checking for attributes of the resulting object. Use export_numpy_core or export_numpy_full if possible.

Parameters:

• keep_all – If True, store all time series, else just the standard set.

• cfgscheduler – Parameters for the scheduling

Returns:

Simulation results

export_numpy_core(cfgscheduler: SchedulerConfigParallel | SchedulerConfigSerial | None = None) → SimResultsNumpyCore

Compute simulation and store all results in memory as numpy arrays

The resulting object has the core data data attributes for results of the simulation evaluated as numpy arrays, as well as the metadata.

This should only be called if the data is expected to fit the available memory.

By default, the streams are evaluated with conservative resource usage. The number of CPUs and memory usage can be adjusted with cfgscheduler parameter (see streams.scheduler).

Parameters:

cfgscheduler – Parameters for the scheduling

Returns:

SimResultsNumpyCore instance with simulation core results

export_numpy_full(cfgscheduler: SchedulerConfigParallel | SchedulerConfigSerial | None = None) → SimResultsNumpyFull

Compute simulation and store all results in memory as numpy arrays

The resulting object has the full set of data attributes for results of the simulation evaluated as numpy arrays, as well as the metadata.

This should only be called if the data is expected to fit the available memory.

By default, the streams are evaluated with conservative resource usage. The number of CPUs and memory usage can be adjusted with cfgscheduler parameter (see streams.scheduler).

Parameters:

cfgscheduler – Parameters for the scheduling

Returns:

SimResultsNumpyFull instance with simulation full results

get_model() → ModelConstellation

Obtain constellation model for given Instrument parameters

Returns:

ModelConstellation

get_noise_defs() → InstruNoises

Return object defining all instrumental noises

metadata_dict() → dict[str, int | float | str | dict | list | ndarray | None]

Dictionary containing all metadata

metadata_value(name: str) → int | float | str | dict | list | ndarray | None

Get a metadata item by name

The purpose of this method is to convert the internal variables such that they can be stored in SimMetaData objects. Filter coefficients are stored as list. The tdir_modulations attribute is replaced by its string representation.

To avoid confusion: this method has nothing to do with translating data into types that can be stored as HDF5 attributes when exporting to file. This sort of mapping happens in the streams.store_hdf5 module, for example, converting None to “None”.

This method was created to support transitioning the handling of user-facing metadata. Before the refactoring, there was no distinction between internal variables of the Instrument class and public metadata, users were just directly using the internals. There was a selected set that gets written to HDF5 attributes though. Those variables were mostly container objects holding float vaues for each MOSA or spacecraft, but also some variables that could be time series (fplan, ranging_bias) and one function object (lambda expression for tdir_modulations). When writing to hdf5, container and function objects were converted to strings.

After the refactoring, user-facing metadata is provided as SimMetaData objects. This holds only simple short data, not time series or functions. In particular, it contains no streams. SimMetaData contains all metadata that would also be saved to HDF5. To keep the format changes to the minimum required to work with streams/long simulations, we still include all attributes that were exported originally, but replace data with problematic types with placeholder values. If there is any need to access those variables that suffer information loss, one still needs to use Instrument directly, keeping up with internal changes.

simulate()

Deprecated method which is not needed anymore

This used to do the computation, but since the switch to chunked processing that happens when exporting the data

stream_bundle() → StreamBundle

Present simulation model as StreamBundle

This is used when exporting to HDF5 or numpy arrays.

Returns:

StreamBundle from which one compute the simulation results

write(output='measurements.h5', mode: Literal['w', 'w-'] = 'w-', keep_all=False)

Deprecated interface, use export_hdf5 instead in new code.

This will create an HDF5 file with the time series and metadata of the simulation. By default, only a standard set of time series is included.

Note: it is not required anymore to call simulation before using this.

Parameters:

• output – path of the file to use

• mode – truncate existing files (‘w’) or fail (‘w-‘)

• keep_all – store all time series, not just the standard set.