GW Response
GW interface
Module with interface for GW link responses
This provides the GW response information needed in Instrument class. The interface is based on numpy arrays, written to support chunked processing needs handled on a higher level. The main GW interface is named GWSource. It provides a method that returns the GW response of a given link as a function of time, which accepts and returns numpy arrays.
There are several implementations. The main one GWSourceSplines, interpolates sampled data using spline interpolation. The sampled data needs to be provided by a callback function that returns time series for a requested time window. The methods from the gw_file.GWFile interface can be used as such a source. GWSourceSplines has an option to construct interpolators on the fly for the time range it is evaluated on. This is to support chunked evaluation without the need to read all GW data at once, allowing to be used during chunked data processing. The GWSourceSplines implementation is used in the Instrument class to set up the GW data from GW files.
Another implementation is GWSourceNumpyArrays. Here, spline interpolators are set up once from samples provided as numpy arrays. This is intended to support the user-supplied GW data in the Instrument class, for GW data that fits into memory.
Finally, there is a trivial implementation GWSourceZero that returns all zero GW response.
The GW functions are of type ArrayFuncOrScalar, which is either a scalar or a function of time, accepting and returning a 1D numpy array. The scalar option exists to represents constant functions more efficiently.
- class lisainstrument.gwsource.gw_source.GWSource[source]
Abstract interface for obtaining GW data for links
This does not return GW data for a given link directly, but in form of a univariate function of time that can be sampled in turn.
- abstract link_gw(mosa: MosaID) FuncOfTime | ConstFuncOfTime[source]
GW data as function of time for given link
For the case of constant data, a scalar can be returned instead of a function.
- Parameters:
mosa – Return GW for the link belonging to this MOSA
- Returns:
GW as scalar or function accepting numpy array
- class lisainstrument.gwsource.gw_source.GWSourceNumpyArrays(times: ndarray, data: dict[MosaID, ndarray], spline_order: int = 5)[source]
Implementation of GWSource based on gw data in numpy arrays
This sets up global interpolation splines from time series provided as numpy arrays.
- class lisainstrument.gwsource.gw_source.GWSourceSplines(src: Callable[[float, float, MosaID, int], TimeSeriesNumpy | None], tmin: float, tmax: float, chunked: bool = True, margin_size: int = 100, spline_order: int = 5)[source]
Implementation of GWSource based on spline interpolating time series
This constructs interpolation splines using a user-provided callable function which returns time series covering a given time interval. There are two options for interpolation, global and chunked.
Chunked interpolation splines are constructed each time GW on a time interval are computed, using only points covering the interval plus an additional margin. This causes interpolation errors dependent on the chunk size. The magnitude of those compared to the usual interpolation error decays exponentially with margin size. For 5th order splines and regularly spaced data, the contribution from a sample 20 points away from a given location is around 10^-8 lower than for an adjacent sample.
Global spline interpolation is constructed once during instance creation, covering a user-provided time interval.
Evaluating times not covered by the data source results in zeros.
GW files
Module with interface and implementations for reading GW files
The main interface is named GWFile. It provides GW data as time series represented by the TimeSeriesNumpy class. The interface only returns time series covering a specified time interval, to allow reading large data sets chunk by chunk. Implementations should be optimized for the case that all data is read sequentially in chunks.
There are two sets of methods, one referring to TCP time and the other to TPS. Data may be available for both or only one, and there are methods to query availability.
The methods for loading a dataset of a given type can be directly used by the gw_source.GWSourceSplines class, turning the low level file reader interface GWFile into a high level GWSource interface suitable for sampling.
There is an GWFile implementation for each supported file format. The function gw_file returns the appropriate implementation for a file with any supported format. Currently, only format version 2.* is supported. The corresponding implementation is GWFileV2.
- class lisainstrument.gwsource.gw_file.GWFile[source]
Abstract interface for reading GW response files.
The interface allows reading subsets of the data directly from file, where the subsets are specified as time intervals. The purpose is to support interpolation of GW data use chunked processing The chunked processing is handled on a higher level, this interface is a low-level numpy-based representation of the files.
- abstract property end_time_tcb: float
End time (TCB) of available data [s]
- abstract property end_time_tps: float
End time (TPS) of available data [s]
- abstract property format_version: Version
Version number of the file format
- abstract property has_tcbltt_dataset: bool
Whether the file has a dataset sampled w.r.t. TCB
- abstract property has_tpsppr_dataset: bool
Whether the file has a dataset sampled w.r.t. TPS
- abstract load_segment_tcbltt(tbegin: float, tend: float, mosa: MosaID, margin_points: int) TimeSeriesNumpy | None[source]
Load a segment of GW data covering a given TCB time interval
This is the same as load_segment_tpsppr but with respect to TCB times.
- abstract load_segment_tpsppr(tbegin: float, tend: float, mosa: MosaID, margin_points: int) TimeSeriesNumpy | None[source]
Load a segment of GW data covering a given TPS time interval
The data is sampled with respect to TPS. If the dataset is unavailable, an exception is raised.
The data to be read is selected using a time interval, including the minimum range of samples such that the time interval is fully covered. One can optionally ask to include additional data points left and right of the specified interval. The margin size is specified in terms of the number of samples.
If the requested time interval (not including the margins) has no overlap with the available data, None is returned.
If the requested time interval has any overlap, at least the available data points are returned. In addition, as many of the margin points as available are also included. If the total number of available points is less than the margin size, an exception is raised.
- Parameters:
tbegin – Start of interval to be covered [s]
tend – End of interval to be covered [s]
mosa – For which link to obtain response
margin_points – Number of margin points (>=0)
- Returns:
Time series with data points or None
- abstract property start_time_tcb: float
Start time (TCB) of available data [s]
- abstract property start_time_tps: float
Start time (TPS) of available data [s]
- class lisainstrument.gwsource.gw_file.GWFileV2(path: str | Path, chunk_size=None)[source]
Implements GWFile interface for file format versions 2.*
- property end_time_tcb: float
See GWFile interface
- property end_time_tps: float
See GWFile interface
- property format_version: Version
See GWFile interface
- property has_tcbltt_dataset: bool
See GWFile interface
- property has_tpsppr_dataset: bool
See GWFile interface
- load_segment(dataset: str, tbegin: float, tend: float, mosa: MosaID, margin_points: int) TimeSeriesNumpy | None[source]
Load segment of dataset covering given time interval
This is the same as the load_segment_tpsppr and load_segment_tcbltt methods of the GWFile interface, only that the dataset type is selected with an additional first parameter.
- Parameters:
dataset – Name of dataset name to load from file
tbegin – Start of time interval to cover
tend – End of time interval to cover
mosa – Load link belonging to this MOSA
- Returns:
Time series with segment data or None
- load_segment_tcbltt(tbegin: float, tend: float, mosa: MosaID, margin_points: int) TimeSeriesNumpy | None[source]
See GWFile interface
- load_segment_tpsppr(tbegin: float, tend: float, mosa: MosaID, margin_points: int) TimeSeriesNumpy | None[source]
See GWFile interface
- property start_time_tcb: float
See GWFile interface
- property start_time_tps: float
See GWFile interface