Detailed Description

Module for reading/writing/manipulating SFTs (Short Fourier Transforms)

Author: R. Prix, B. Machenschalk, A.M. Sintes, B. Krishnan, I. Gholami, C. Messenger, K. Wette, P. Covas, D. Keitel, R. Tenorio

This implements the SFT (Short Fourier Transforms) standard defined in [4] . It contains various helper functions to create, handle, combine, and destroy SFTs and related data structures, including SFTtype, SFTVector, SFTCatalog (and their multi-detector generalizations) as well as tools for dealing with SFT timestamps and semicoherent analysis segments.

Overview

Time range/frequency bin convention functions.
SFT types: create/destroy functions, modify functions, property functions.
SFT timestamp types: create/destroy functions, property functions, generation functions.
SFT catalog types: create/destroy functions, property functions, generation functions.
SFT files: file naming convention functions, file reading functions, file writing functions.

Usage: Reading of SFT-files

The basic operation of reading SFTs from files proceeds in two simple steps:

XLALSFTdataFind(): get an SFTCatalog of SFTs matching certain requirements (free with XLALDestroySFTCatalog())
XLALLoadSFTs(): load a frequency-band into a single-IFO SFTVector defined by the catalogue, OR
XLALLoadMultiSFTs(): load a frequency-band into a MultiSFTVector defined by the catalogue

Note 1: currently supported SFT file-formats are (merged or single) SFT files. This might be extended in the future to support further file-formats (frames?). None of the following API depends on the details of the underlying file-format. This will ensure that codes using the following functions will NOT have to be changed irrespective of SFT file-format used.

Note 2: irrespective of the underlying SFT file-format, the returned SFTs (SFTVector) will ALWAYS be normalized according the the LAL-specification for frequency-series (LIGO-T010095-00), that is the pure DFT of the time-series \( x_j \) is multiplied by the time-step \( \Delta t \) :

\[ \mathrm{data}[k] = X^\mathrm{d}_k = \Delta t \,\sum_{j=0}^{N-1} x_j \,e^{-i2\pi \,k \,j / N} \]

Details to 1: find matching SFTs and get the SFTCatalog:

Thes function XLALSFTdataFind() returns an SFTCatalog of matching SFTs for a given file-pattern (e.g. "SFT.*", "SFT.000", "/some/path/some_files_[0-9]?.sft", etc ) and additional, optional SFTConstraints.

The optional constraints are:

detector-prefix (e.g. "H1", "H2", "L1", "G1", "V1", etc..)
GPS start-time + end-time
a list of GPS-timestamps

Note 1: Any constraint can be specified as NULL, all given constraints will be combined by logical AND.

Note 2: if a timestamps-list is given, ALL timestamps within [minStartTime, maxStartTime) MUST be found!]

Note 3: XLALSFTdataFind() will refuse to return any SFTs without their detector-name properly set.

The returned SFTCatalog is a vector of SFTDescriptor describing one SFT, with the fields

locator: an opaque data-type describing where to read this SFT from.
header: the SFts header
comment: the comment-string found in the SFT, if any
numBins: the number of frequency-bins in the SFT
version: version-number of SFT file-format
crc64: the crc64 checksum reported by this SFT

One can use the following catalog-handling API functions:

XLALDestroySFTCatalog(): free up a complete SFTCatalog
XLALSFTtimestampsFromCatalog(): extract the list of SFT timestamps found in the SFTCatalog
XLALDestroyTimestampVector(): free up a timestamps-vector (LIGOTimeGPSVector)
XLALshowSFTLocator(): [debugging only] show a static string describing the 'locator'

NOTE: The SFTs in the returned catalogue are guaranteed to

be sorted in order of increasing GPS-epoch
contain a valid detector-name

Details to 2: load frequency-band from SFTs described in an SFTCatalog

The function XLALLoadSFTs() takes an SFTCatalog and reads the smallest frequency-band containing [fMin, fMax] from the SFTs, returning the resulting SFTVector. Note that this function will return an error if the SFTCatalog contains SFTs from different detectors, for which XLALLoadMultiSFTs() must be used.

The frequency-bounds are optional and -1 can be used to specify an 'open bound', i.e.
[-1, fMax]: read from first frequency-bin in the SFT up to fMax.
[fMin, -1]: read from fMin up to last frequency-bin in the SFTS
[-1, -1]: read ALL frequency-bins from SFT.

The function XLALLoadMultiSFTs() is similar to the above, except that it accepts an SFTCatalog with different detectors, and returns corresponding multi-IFO vector of SFTVectors.

Usage: Writing of SFT-files

For writing SFTs:

XLALWriteSFT2file(): write a single SFT (SFTtype) into an SFT-file following the specification [4] .

Prototypes
static int	read_SFDB_header_from_fp (FILE fp, SFDBHeader header)

static BOOLEAN	CheckIfSFDBInScienceMode (SFDBHeader SFDBHeader, LALStringVector detectors, MultiLIGOTimeGPSVector startingTS, MultiLIGOTimeGPSVector endingTS)

static long	get_file_len (FILE *fp)

static BOOLEAN	consistent_mSFT_header (SFTtype header1, UINT4 version1, UINT4 nsamples1, UINT2 windowspec1, SFTtype header2, UINT4 version2, UINT4 nsamples2, UINT2 windowspec2)

static BOOLEAN	timestamp_in_list (LIGOTimeGPS timestamp, LIGOTimeGPSVector *list)

void	endian_swap (CHAR *pdata, size_t dsize, size_t nelements)

FILE *	fopen_SFTLocator (const struct tagSFTLocator *locator)
	Open an "SFT" defined by the SFT-locator, return a FILE-pointer to the beginning of this SFT. More...

int	read_SFTversion_from_fp (UINT4 version, BOOLEAN need_swap, FILE *fp)
	Read valid SFT version-number at position fp, and determine if we need to endian-swap the data. More...

int	read_sft_header_from_fp (FILE fp, SFTtype header, UINT4 version, UINT8 crc64, UINT2 SFTwindowspec, BOOLEAN swapEndian, CHAR *SFTcomment, UINT4 numBins)

static int	read_header_from_fp (FILE fp, SFTtype header, UINT4 nsamples, UINT8 header_crc64, UINT8 ref_crc64, UINT2 SFTwindowspec, CHAR **SFTcomment, BOOLEAN swapEndian)

UINT4	read_sft_bins_from_fp (SFTtype ret, UINT4 firstBinRead, UINT4 firstBin2read, UINT4 lastBin2read, FILE *fp)

BOOLEAN	has_valid_crc64 (FILE *fp)
	Check the SFT-block starting at fp for valid crc64 checksum. More...

int	build_sft_windowspec (UINT2 windowspec, CHAR(windowspec_str)[9], const char *window_type, REAL8 window_param)
	Build an SFT 2-byte 'windowspec' or filename field 'windowspec_str' for the window given by 'window_type' and 'window_param'. More...

int	parse_sft_windowspec (const UINT2 windowspec, const char *window_type, REAL8 window_param)
	Parse an SFT 2-byte 'windowspec' into a window name 'window_type' and possible parameter 'window_param'. More...

int	parse_sft_windowspec_str (const CHAR windowspec_str, CHAR(window_type)[32], REAL8 *window_param)
	Parse an SFT filename field 'windowspec_str' into a window name 'window_type' and possible parameter 'window_param'. More...

REAL8	TSFTfromDFreq (REAL8 dFreq)

int	compareSFTdesc (const void ptr1, const void ptr2)

int	compareSFTloc (const void ptr1, const void ptr2)

int	compareDetNameCatalogs (const void ptr1, const void ptr2)

int	compareSFTepoch (const void ptr1, const void ptr2)

Data Structures
struct	MultiSFTVector
	A collection of SFT vectors – one for each IFO in a multi-IFO search. More...

struct	LIGOTimeGPSVector
	A vector of 'timestamps' of type LIGOTimeGPS. More...

struct	MultiLIGOTimeGPSVector
	A collection of (multi-IFO) LIGOTimeGPSVector time-stamps vectors. More...

struct	SFTConstraints
	'Constraints' for SFT-matching: which detector, within which time-stretch and which timestamps exactly should be loaded ? Any of the entries is optional, and they will be combined by logical AND. More...

struct	SFTDescriptor
	A 'descriptor' of an SFT: basically containing the header-info plus an opaque description of where exactly to load this SFT from. More...

struct	SFTCatalog
	An "SFT-catalogue": a vector of SFTdescriptors, as returned by XLALSFTdataFind() More...

struct	MultiSFTCatalogView
	A multi-SFT-catalogue "view": a multi-IFO vector of SFT-catalogs. More...

struct	SFTFilenameSpec
	Structure specifying an SFT file name, following the convention in [4] . More...

Typedefs
typedef COMPLEX8FrequencySeries	SFTtype
	A so-called 'SFT' (short-Fourier-transform) will be stored in a COMPLEX8FrequencySeries. More...

typedef COMPLEX8FrequencySeriesVector	SFTVector
	The corresponding vector-type to hold a vector of 'SFTs'. More...

Files
file	SFTinternal.h
	Internal SFT types and functions.

file	SFTfileIOTest.c
	Test-code for SFT-fileIO library.

file	SFTnamingTest.c
	Test the SFT file naming routines.

file	XLALMultiNoiseWeightsTest.c
	Tests for XLALComputeMultiNoiseWeights()

SFT file reading functions

MultiSFTVector *	XLALReadSFDB (REAL8 f_min, REAL8 f_max, const CHAR file_pattern, const CHAR timeStampsStarting, const CHAR *timeStampsFinishing)
	Return a MultiSFTVector struct from an input set of SFDBs, possibly from more than one detector. More...

SFTVector *	XLALLoadSFTs (const SFTCatalog *catalog, REAL8 fMin, REAL8 fMax)
	Load the given frequency-band `[fMin, fMax)` (half-open) from the SFT-files listed in the SFT-'catalogue' ( returned by XLALSFTdataFind() ). More...

MultiSFTVector *	XLALLoadMultiSFTs (const SFTCatalog *inputCatalog, REAL8 fMin, REAL8 fMax)
	Function to load a catalog of SFTs from possibly different detectors. More...

MultiSFTVector *	XLALLoadMultiSFTsFromView (const MultiSFTCatalogView *multiCatalogView, REAL8 fMin, REAL8 fMax)
	This function loads a MultiSFTVector from a given input MultiSFTCatalogView, otherwise the documentation of XLALLoadMultiSFTs() applies. More...

LALStringVector *	XLALFindFiles (const CHAR *globstring)
	Returns a list of filenames matching the input argument, which may be one of the following: More...

SFT catalog create/destroy functions

SFTCatalog *	XLALSFTdataFind (const CHAR file_pattern, const SFTConstraints constraints)
	Find the list of SFTs matching the file_pattern and satisfying the given constraints, return an `SFTCatalog` of the matching SFTs. More...

void	XLALDestroySFTCatalog (SFTCatalog *catalog)
	Free an 'SFT-catalogue'. More...

MultiSFTCatalogView *	XLALGetMultiSFTCatalogView (const SFTCatalog *catalog)
	Return a MultiSFTCatalogView generated from an input SFTCatalog. More...

void	XLALDestroyMultiSFTCatalogView (MultiSFTCatalogView *multiView)
	Destroys a MultiSFTCatalogView, without freeing the original catalog that the 'view' was referring to, which must be destroyed separately using XLALDestroySFTCatalog(). More...

SFT catalog property functions

int	XLALCheckCRCSFTCatalog (BOOLEAN crc_check, SFTCatalog catalog)
	This function reads in the SFTs in the catalog and validates their CRC64 checksums. More...

LALStringVector *	XLALListIFOsInCatalog (const SFTCatalog *catalog)
	Return a sorted string vector listing the unique IFOs in the given catalog. More...

INT4	XLALCountIFOsInCatalog (const SFTCatalog *catalog)
	Count the number of the unique IFOs in the given catalog. More...

const CHAR *	XLALshowSFTLocator (const struct tagSFTLocator *locator)
	Mostly for debugging purposes: provide a user-API to allow inspecting the SFT-locator [which is an OPAQUE entry in the SFTCatalog!]. More...

int	XLALSFTCatalogTimeslice (SFTCatalog slice, const SFTCatalog catalog, const LIGOTimeGPS minStartGPS, const LIGOTimeGPS maxStartGPS)
	Set a SFT catalog 'slice' to a timeslice of a larger SFT catalog 'catalog', with entries restricted to the interval ['minStartGPS','maxStartGPS') according to XLALCWGPSinRange(). More...

SFTCatalog *	XLALReturnSFTCatalogTimeslice (const SFTCatalog catalog, const LIGOTimeGPS minStartGPS, const LIGOTimeGPS *maxStartGPS)

SFT catalog generation functions

SFTCatalog *	XLALAddToFakeSFTCatalog (SFTCatalog catalog, const CHAR detector, const LIGOTimeGPSVector *timestamps)
	Create a 'fake' SFT catalog which contains only detector and timestamp information. More...

SFTCatalog *	XLALMultiAddToFakeSFTCatalog (SFTCatalog catalog, const LALStringVector detectors, const MultiLIGOTimeGPSVector *timestamps)
	Multi-detector and multi-timestamp wrapper of XLALAddToFakeSFTCatalog(). More...

SFT file writing functions

int	XLALWriteSFT2FilePointer (const SFTtype sft, FILE fp, const CHAR SFTwindowtype, const REAL8 SFTwindowparam, const CHAR SFTcomment)
	Write the given SFTtype to a FILE pointer. More...

int	XLALWriteSFT2NamedFile (const SFTtype sft, const CHAR SFTfilename, const CHAR SFTwindowtype, const REAL8 SFTwindowparam, const CHAR SFTcomment)
	Write the given SFTtype to a SFT file with the supplied filename. More...

int	XLALWriteSFT2StandardFile (const SFTtype sft, SFTFilenameSpec SFTfnspec, const CHAR *SFTcomment)
	Write the given SFTtype to a SFT file with a standard ([4]) filename. More...

int	XLALWriteSFTVector2NamedFile (const SFTVector sftVect, const CHAR SFTfilename, const CHAR SFTwindowtype, const REAL8 SFTwindowparam, const CHAR SFTcomment)
	Write the given SFTVector to a single merged SFT file with the supplied filename. More...

int	XLALWriteSFTVector2StandardFile (const SFTVector sftVect, SFTFilenameSpec SFTfnspec, const CHAR *SFTcomment, const BOOLEAN merged)
	Write the given SFTVector to SFT file(s) with a standard ([4]) filename(s). More...

int	XLALCheckSFTFileIsValid (const char *fname)
	Verify that the contents of a SFT file are valid. More...

Time range/frequency bin convention functions

int	XLALCWGPSinRange (const LIGOTimeGPS gps, const LIGOTimeGPS minGPS, const LIGOTimeGPS maxGPS)
	Defines the official CW convention for whether a GPS time is 'within' a given range, defined as the half-open interval [minGPS, maxGPS) More...

UINT4	XLALRoundFrequencyDownToSFTBin (const REAL8 freq, const REAL8 df)
	Round a REAL8 frequency down to the nearest integer SFT bin number. More...

UINT4	XLALRoundFrequencyUpToSFTBin (const REAL8 freq, const REAL8 df)
	Round a REAL8 frequency up to the nearest integer SFT bin number. More...

int	XLALFindCoveringSFTBins (UINT4 firstBin, UINT4 numBins, REAL8 fMinIn, REAL8 BandIn, REAL8 Tsft)
	Return the 'effective' frequency-band [fMinEff, fMaxEff] = [firstBin, lastBin] * 1/Tsft, with numBins = lastBin - firstBin + 1 which is the smallest band of SFT-bins that fully covers a given band [fMin, fMin+Band]. More...

SFT type create/destroy functions

SFTtype *	XLALCreateSFT (UINT4 numBins)
	XLAL function to create one SFT-struct. More...

void	XLALDestroySFT (SFTtype *sft)
	Destructor for one SFT. More...

int	XLALCopySFT (SFTtype dest, const SFTtype src)
	Copy an entire SFT-type into another. More...

SFTVector *	XLALCreateSFTVector (UINT4 numSFTs, UINT4 numBins)
	XLAL function to create an SFTVector of `numSFT` SFTs with `SFTlen` frequency-bins (which will be allocated too). More...

SFTVector *	XLALCreateEmptySFTVector (UINT4 numSFTs)
	XLAL function to create an SFTVector of `numSFT` SFTs (which are not allocated). More...

void	XLALDestroySFTVector (SFTVector *vect)
	XLAL interface to destroy an SFTVector. More...

SFTVector *	XLALDuplicateSFTVector (const SFTVector *sftsIn)
	Create a complete copy of an SFT vector. More...

MultiSFTVector *	XLALCreateMultiSFTVector (UINT4 length, UINT4Vector *numsft)
	Create a multi-IFO SFT vector with a given number of bins per SFT and number of SFTs per IFO (which will be allocated too). More...

MultiSFTVector *	XLALCreateEmptyMultiSFTVector (UINT4Vector *numsft)
	Create an empty multi-IFO SFT vector with a given number of SFTs per IFO (which are not allocated). More...

void	XLALDestroyMultiSFTVector (MultiSFTVector *multvect)
	Destroy a multi SFT-vector. More...

int	XLALExtractBandFromSFT (SFTtype *outSFT, const SFTtype inSFT, REAL8 fMin, REAL8 Band)
	Return an SFTs containing only the bins in [fMin, fMin+Band]. More...

SFTVector *	XLALExtractBandFromSFTVector (const SFTVector *inSFTs, REAL8 fMin, REAL8 Band)
	Return a vector of SFTs containing only the bins in [fMin, fMin+Band]. More...

MultiSFTVector *	XLALExtractBandFromMultiSFTVector (const MultiSFTVector *inSFTs, REAL8 fMin, REAL8 Band)
	Return a MultiSFT vector containing only the bins in [fMin, fMin+Band]. More...

int	XLALExtractStrictBandFromSFT (SFTtype *outSFT, const SFTtype inSFT, REAL8 fMin, REAL8 Band)
	Return a copy of an SFT containing only the bins in [fMin, fMin+Band). More...

SFTVector *	XLALExtractStrictBandFromSFTVector (const SFTVector *inSFTs, REAL8 fMin, REAL8 Band)
	Return a copy of a vector of SFTs containing only the bins in [fMin, fMin+Band). More...

MultiSFTVector *	XLALExtractStrictBandFromMultiSFTVector (const MultiSFTVector *inSFTs, REAL8 fMin, REAL8 Band)
	Return a copy of a MultiSFT vector containing only the bins in [fMin, fMin+Band). More...

SFT type modify functions

int	XLALAppendSFT2Vector (SFTVector vect, const SFTtype sft)
	Append the given SFTtype to the SFT-vector (no SFT-specific checks are done!) More...

int	XLALReorderMultiSFTVector (MultiSFTVector multiSFTs, const LALStringVector IFOs)
	Reorder the MultiSFTVector with specified list of IFOs. More...

int	XLALSFTAdd (SFTtype a, const SFTtype b)
	Adds SFT-data from SFT 'b' to SFT 'a'. More...

int	XLALSFTVectorAdd (SFTVector a, const SFTVector b)
	Adds SFT-data from SFTvector 'b' to elements of SFTVector 'a'. More...

int	XLALMultiSFTVectorAdd (MultiSFTVector a, const MultiSFTVector b)
	Adds SFT-data from MultiSFTvector 'b' to elements of MultiSFTVector 'a'. More...

int	XLALSFTResizeBand (SFTtype *SFT, REAL8 f0, REAL8 Band)
	Resize the frequency-band of a given SFT to [f0, f0+Band]. More...

int	XLALSFTVectorResizeBand (SFTVector *SFTs, REAL8 f0, REAL8 Band)
	Resize the frequency-band of a given SFT vector to [f0, f0+Band]. More...

int	XLALMultiSFTVectorResizeBand (MultiSFTVector *multiSFTs, REAL8 f0, REAL8 Band)
	Resize the frequency-band of a given multi-SFT vector to [f0, f0+Band]. More...

SFT type property functions

int	XLALEarliestMultiSFTsample (LIGOTimeGPS out, const MultiSFTVector multisfts)
	Finds the earliest timestamp in a multi-SFT data structure. More...

int	XLALLatestMultiSFTsample (LIGOTimeGPS out, const MultiSFTVector multisfts)
	Find the time of the end of the latest SFT in a multi-SFT data structure. More...

SFTVector *	XLALExtractSFTVectorWithTimestamps (const SFTVector sfts, const LIGOTimeGPSVector timestamps)
	Extract an SFTVector from another SFTVector but only those timestamps matching. More...

MultiSFTVector *	XLALExtractMultiSFTVectorWithMultiTimestamps (const MultiSFTVector multiSFTs, const MultiLIGOTimeGPSVector multiTimestamps)
	Extract a MultiSFTVector from another MultiSFTVector but only those timestamps matching. More...

SFT timestamp type create/destroy functions

LIGOTimeGPSVector *	XLALCreateTimestampVector (UINT4 length)
	Allocate a LIGOTimeGPSVector. More...

void	XLALDestroyTimestampVector (LIGOTimeGPSVector *vect)
	De-allocate a LIGOTimeGPSVector. More...

LIGOTimeGPSVector *	XLALResizeTimestampVector (LIGOTimeGPSVector *vector, UINT4 length)
	Resize a LIGOTimeGPSVector. More...

MultiLIGOTimeGPSVector *	XLALCreateMultiLIGOTimeGPSVector (UINT4 numDetectors)
	Simple creator function for MultiLIGOTimeGPSVector with numDetectors entries. More...

void	XLALDestroyMultiTimestamps (MultiLIGOTimeGPSVector *multiTS)
	Destroy a MultiLIGOTimeGPSVector timestamps vector. More...

SFT timestamp type property functions

int	XLALFindTimesliceBounds (UINT4 iStart, UINT4 iEnd, const LIGOTimeGPSVector timestamps, const LIGOTimeGPS minStartGPS, const LIGOTimeGPS *maxStartGPS)

SFT timestamp generation functions

LIGOTimeGPSVector *	XLALMakeTimestamps (LIGOTimeGPS tStart, REAL8 Tspan, REAL8 Tsft, REAL8 Toverlap)
	Given a start-time, Tspan, Tsft and Toverlap, returns a list of timestamps covering this time-stretch (allowing for overlapping SFTs). More...

MultiLIGOTimeGPSVector *	XLALMakeMultiTimestamps (LIGOTimeGPS tStart, REAL8 Tspan, REAL8 Tsft, REAL8 Toverlap, UINT4 numDet)
	Same as XLALMakeTimestamps() just for several detectors, additionally specify the number of detectors. More...

LIGOTimeGPSVector *	XLALReadTimestampsFile (const CHAR *fname)
	backwards compatible wrapper to XLALReadTimestampsFileConstrained() without GPS-time constraints More...

MultiLIGOTimeGPSVector *	XLALReadMultiTimestampsFiles (const LALStringVector *fnames)
	backwards compatible wrapper to XLALReadMultiTimestampsFilesConstrained() without GPS-time constraints More...

LIGOTimeGPSVector *	XLALReadTimestampsFileConstrained (const CHAR fname, const LIGOTimeGPS minGPS, const LIGOTimeGPS *maxGPS)
	Load timestamps file 'fname' into LIGOTimeGPSVector struct, allocated here. More...

MultiLIGOTimeGPSVector *	XLALReadMultiTimestampsFilesConstrained (const LALStringVector fnames, const LIGOTimeGPS minGPS, const LIGOTimeGPS *maxGPS)
	Load several timestamps files, return a MultiLIGOTimeGPSVector struct, allocated here. More...

LIGOTimeGPSVector *	XLALExtractTimestampsFromSFTs (const SFTVector *sfts)
	Extract timstamps-vector from the given SFTVector. More...

MultiLIGOTimeGPSVector *	XLALExtractMultiTimestampsFromSFTs (const MultiSFTVector *multiSFTs)
	Given a multi-SFT vector, return a MultiLIGOTimeGPSVector holding the SFT timestamps. More...

LIGOTimeGPSVector *	XLALTimestampsFromSFTCatalog (const SFTCatalog *catalog)
	Extract timestamps-vector of unique timestamps from the given SFTCatalog. More...

MultiLIGOTimeGPSVector *	XLALTimestampsFromMultiSFTCatalogView (const MultiSFTCatalogView *multiView)
	Given a multi-SFTCatalogView, return a MultiLIGOTimeGPSVector holding the SFT timestamps. More...

LALSegList *	XLALReadSegmentsFromFile (const char *fname)
	Function to read a segment list from given filename, returns a sorted LALSegList. More...

LIGOTimeGPSVector *	XLALTimestampsFromSegmentFile (const char *filename, REAL8 Tsft, REAL8 Toverlap, BOOLEAN adjustSegExtraTime, BOOLEAN synchronize)
	Extract timestamps-vector from a segment file, with functionality based on MakeSFTDAG The filename should point to a file containing <GPSstart GPSend> of segments or <GPSstart GPSend segLength numSFTs> where segLength is in hours. More...

SFT file naming convention functions

int	XLALRegisterSpecialCWDetector (const LALDetector *specialDetector)
	Register a special detector for use with CW codes. More...

int	XLALFindCWDetector (CHAR *prefix, INT4 lalCachedIndex, const CHAR *name, const BOOLEAN exactMatch)
	Parses valid CW detector names and prefixes. More...

BOOLEAN	XLALIsValidCWDetector (const CHAR *name)
	Determine if 'name' is a valid detector name or prefix. More...

CHAR *	XLALGetChannelPrefix (const CHAR *name)
	Find the valid CW detector prefix. More...

const LALDetector *	XLALGetSiteInfo (const CHAR *name)
	Find the site geometry-information 'LALDetector' for given a detector name (or prefix). More...

int	XLALFillSFTFilenameSpecStrings (SFTFilenameSpec spec, const CHAR path, const CHAR extn, const CHAR detector, const CHAR window_type, const CHAR privMisc, const CHAR pubObsKind, const CHAR pubChannel)
	Convenience function for filling out the string fields in a SFTFilenameSpec. More...

char *	XLALBuildSFTFilenameFromSpec (const SFTFilenameSpec *spec)
	Build an SFT file name from the given specification. More...

int	XLALParseSFTFilenameIntoSpec (SFTFilenameSpec spec, const char SFTpath)
	Parse a SFT file path and return its specification. More...

int	XLALCheckValidDescriptionField (const char *desc)
	Check whether given string qualifies as a valid 'description' field of a FRAME filename (per [25]) or SFT filename (per [4]) More...

int	XLALCompareSFTWindows (const CHAR type1, const REAL8 param1, const CHAR type2, const REAL8 param2)
	Check whether two SFT windows, each defined by a type name and parameter value, match. More...

Function Documentation

◆ XLALReadSFDB()

MultiSFTVector * XLALReadSFDB	(	REAL8	f_min,
		REAL8	f_max,
		const CHAR *	file_pattern,
		const CHAR *	timeStampsStarting,
		const CHAR *	timeStampsFinishing
	)

Return a MultiSFTVector struct from an input set of SFDBs, possibly from more than one detector.

An SFDB (Short Fourier DataBase) is the frequency-domain data format created by the Rome group. It has a time-domain cleaning, which is described in [2].

In order to only use SFDBs within science segments, it is possible to input files for each detector which have the science segments. Two files for each detector are needed, one with the starting timestamps and the other with the ending timestamps. The format for these files is one timestamp per line. If not needed, the timestamp inputs can be NULL.

The returned SFTs in the standard LALSuite format are sorted by increasing GPS-epochs!

Definition at line 100 of file SFDBfileIO.c.

◆ read_SFDB_header_from_fp()

static int read_SFDB_header_from_fp	(	FILE *	fp,
		SFDBHeader *	header
	)

static

Definition at line 372 of file SFDBfileIO.c.

◆ CheckIfSFDBInScienceMode()

static BOOLEAN CheckIfSFDBInScienceMode	(	SFDBHeader *	SFDBHeader,
		LALStringVector *	detectors,
		MultiLIGOTimeGPSVector *	startingTS,
		MultiLIGOTimeGPSVector *	endingTS
	)

static

Definition at line 415 of file SFDBfileIO.c.

◆ XLALSFTdataFind()

SFTCatalog * XLALSFTdataFind	(	const CHAR *	file_pattern,
		const SFTConstraints *	constraints
	)

Find the list of SFTs matching the file_pattern and satisfying the given constraints, return an SFTCatalog of the matching SFTs.

The optional constraints that can be specified are (type SFTConstraints)

'detector': which detector
'time-span': GPS start- and end-times
'timestamps': list of GPS start-times

==> The returned SFTCatalog can be used directly as input to XLALLoadSFTs() to load a single-IFO SFTVector, or XLALLoadMultiSFTs() to load a multi-IFO vector of SFTVectors

Except for the 'file_pattern' input, all the other constraints are optional and can be passed as NULL (either globally constraings==NULL, or individually).

Note that the constraints are combined by 'AND' and the resulting full constraint MUST be satisfied (in particular: if 'timestamps' is given, all timestamps within [minStartTime, maxStartTime) MUST be found!.

The returned SFTs in the catalogue are sorted by increasing GPS-epochs !

Parameters

file_pattern	which SFT-files
constraints	additional constraints for SFT-selection

Definition at line 71 of file SFTcatalog.c.

◆ XLALDestroySFTCatalog()

void XLALDestroySFTCatalog ( SFTCatalog * catalog )

Free an 'SFT-catalogue'.

Parameters

catalog the 'catalogue' to free

Definition at line 329 of file SFTcatalog.c.

◆ XLALGetMultiSFTCatalogView()

MultiSFTCatalogView * XLALGetMultiSFTCatalogView ( const SFTCatalog * catalog )

Return a MultiSFTCatalogView generated from an input SFTCatalog.

The input catalog can describe SFTs from several IFOs in one vector, while the returned multi-Catalog view contains an array of single-IFO SFTCatalogs.

NOTE: remember that this is only a multi-IFO "view" of the existing SFTCatalog, various allocated memory of the original catalog is only pointed to, not duplicated! This means one must not free the original catalog while this multi-view is still in use!

NOTE2: the returned multi-IFO catalog is sorted alphabetically by detector-name

Definition at line 380 of file SFTcatalog.c.

◆ XLALDestroyMultiSFTCatalogView()

void XLALDestroyMultiSFTCatalogView ( MultiSFTCatalogView * multiView )

Destroys a MultiSFTCatalogView, without freeing the original catalog that the 'view' was referring to, which must be destroyed separately using XLALDestroySFTCatalog().

Definition at line 496 of file SFTcatalog.c.

◆ XLALCheckCRCSFTCatalog()

int XLALCheckCRCSFTCatalog	(	BOOLEAN *	crc_check,
		SFTCatalog *	catalog
	)

This function reads in the SFTs in the catalog and validates their CRC64 checksums.

The result of the validation is returned in '*crc_check'. The function itself returns XLAL_SUCCESS if the operation suceeds (even if the checksums fail to validate), and XLAL_FAILURE otherwise.

Note: : because this function has to read the complete SFT data into memory it is potentially slow and memory-intensive.

Parameters

crc_check	set to true if checksum validation passes
catalog	catalog of SFTs to check

Definition at line 524 of file SFTcatalog.c.

◆ XLALListIFOsInCatalog()

LALStringVector * XLALListIFOsInCatalog ( const SFTCatalog * catalog )

Return a sorted string vector listing the unique IFOs in the given catalog.

Definition at line 562 of file SFTcatalog.c.

◆ XLALCountIFOsInCatalog()

INT4 XLALCountIFOsInCatalog ( const SFTCatalog * catalog )

Count the number of the unique IFOs in the given catalog.

Definition at line 582 of file SFTcatalog.c.

◆ XLALshowSFTLocator()

const CHAR * XLALshowSFTLocator ( const struct tagSFTLocator * locator )

Mostly for debugging purposes: provide a user-API to allow inspecting the SFT-locator [which is an OPAQUE entry in the SFTCatalog!].

NOTE: this returns a STATIC string, so don't try to FREE it, and make a copy if you need to keep it beyond one call of this function!

Definition at line 602 of file SFTcatalog.c.

◆ XLALSFTCatalogTimeslice()

int XLALSFTCatalogTimeslice	(	SFTCatalog *	slice,
		const SFTCatalog *	catalog,
		const LIGOTimeGPS *	minStartGPS,
		const LIGOTimeGPS *	maxStartGPS
	)

Set a SFT catalog 'slice' to a timeslice of a larger SFT catalog 'catalog', with entries restricted to the interval ['minStartGPS','maxStartGPS') according to XLALCWGPSinRange().

The catalog 'slice' just points to existing data in 'catalog', and therefore should not be deallocated.

Parameters

[out]	slice	Timeslice of SFT catalog
[in]	catalog	SFT catalog
[in]	minStartGPS	Minimum starting GPS time
[in]	maxStartGPS	Maximum starting GPS time

Definition at line 624 of file SFTcatalog.c.

◆ XLALReturnSFTCatalogTimeslice()

SFTCatalog * XLALReturnSFTCatalogTimeslice	(	const SFTCatalog *	catalog,
		const LIGOTimeGPS *	minStartGPS,
		const LIGOTimeGPS *	maxStartGPS
	)

Parameters

[in]	catalog	SFT catalog
[in]	minStartGPS	Minimum starting GPS time
[in]	maxStartGPS	Maximum starting GPS time

Definition at line 670 of file SFTcatalog.c.

◆ XLALAddToFakeSFTCatalog()

SFTCatalog * XLALAddToFakeSFTCatalog	(	SFTCatalog *	catalog,
		const CHAR *	detector,
		const LIGOTimeGPSVector *	timestamps
	)

Create a 'fake' SFT catalog which contains only detector and timestamp information.

Parameters

[in]	catalog	SFT catalog; if NULL, a new catalog is created
[in]	detector	Name of detector to set fake catalog entries to
[in]	timestamps	Timestamps of each fake catalog entry

Definition at line 692 of file SFTcatalog.c.

◆ XLALMultiAddToFakeSFTCatalog()

SFTCatalog * XLALMultiAddToFakeSFTCatalog	(	SFTCatalog *	catalog,
		const LALStringVector *	detectors,
		const MultiLIGOTimeGPSVector *	timestamps
	)

Multi-detector and multi-timestamp wrapper of XLALAddToFakeSFTCatalog().

Parameters

[in]	catalog	SFT catalog; if NULL, a new catalog is created
[in]	detectors	Detector names to set fake catalog entries to
[in]	timestamps	Timestamps for each detector of each fake catalog entry

Definition at line 749 of file SFTcatalog.c.

◆ get_file_len()

static long get_file_len ( FILE * fp )

static

Definition at line 774 of file SFTcatalog.c.

◆ consistent_mSFT_header()

static BOOLEAN consistent_mSFT_header	(	SFTtype	header1,
		UINT4	version1,
		UINT4	nsamples1,
		UINT2	windowspec1,
		SFTtype	header2,
		UINT4	version2,
		UINT4	nsamples2,
		UINT2	windowspec2
	)

static

Definition at line 813 of file SFTcatalog.c.

◆ timestamp_in_list()

static BOOLEAN timestamp_in_list	(	LIGOTimeGPS	timestamp,
		LIGOTimeGPSVector *	list
	)

static

Definition at line 863 of file SFTcatalog.c.

◆ XLALLoadSFTs()

SFTVector * XLALLoadSFTs	(	const SFTCatalog *	catalog,
		REAL8	fMin,
		REAL8	fMax
	)

Load the given frequency-band [fMin, fMax) (half-open) from the SFT-files listed in the SFT-'catalogue' ( returned by XLALSFTdataFind() ).

Note: fMin (or fMax) is allowed to be set to -1, which means to read in all Frequency-bins from the lowest (or up to the highest) found in all SFT-files of the catalog.

Note 2: The returned frequency-interval is guaranteed to contain [fMin, fMax), but is allowed to be larger, as it must be an interval of discrete frequency-bins as found in the SFT-file.

Note 3: This function has the capability to read sequences of SFT segments and putting them together to single SFTs while reading.

Note 4: The 'fudge region' allowing for numerical noise is fudge= 10*LAL_REAL8_EPS ~2e-15 relative deviation: ie if the SFT contains a bin at 'fi', then we consider for example "fMin == fi" if fabs(fi - fMin)/fi < fudge.

< current file in catalog

< the first and last bin we want to read

< min and max bin of all SFTs in the catalog

< number of SFTs, i.e. different GPS timestamps

< frequency spacing of SFT

< local copy of the catalog to be sorted by 'locator'

< the vector of SFTs to be returned

< array of segments already read of an SFT

< empty string

< name of currently open file, initially ""

< open file

< SFT to read from file

Parameters

catalog	The 'catalogue' of SFTs to load
fMin	minumum requested frequency (-1 = read from lowest)
fMax	maximum requested frequency (-1 = read up to highest)

Definition at line 87 of file SFTfileIO.c.

◆ XLALLoadMultiSFTs()

MultiSFTVector * XLALLoadMultiSFTs	(	const SFTCatalog *	inputCatalog,
		REAL8	fMin,
		REAL8	fMax
	)

Function to load a catalog of SFTs from possibly different detectors.

This is similar to XLALLoadSFTs except that the input SFT catalog is allowed to contain multiple ifos. The output is the structure MultiSFTVector which is a vector of (pointers to) SFTVectors, one for each ifo found in the catalog. As in XLALLoadSFTs, fMin and fMax can be set to -1 to get the full SFT from the lowest to the highest frequency bin found in the SFT.

output SFTvectors are sorted alphabetically by detector-name

NOTE: this is basically a backwards-compatible API wrapper to XLALLoadMultiSFTsFromView(), which takes a MultiSFTCatalogView as input instead.

Parameters

inputCatalog	The 'catalogue' of SFTs to load
fMin	minumum requested frequency (-1 = read from lowest)
fMax	maximum requested frequency (-1 = read up to highest)

Definition at line 416 of file SFTfileIO.c.

◆ XLALLoadMultiSFTsFromView()

MultiSFTVector * XLALLoadMultiSFTsFromView	(	const MultiSFTCatalogView *	multiCatalogView,
		REAL8	fMin,
		REAL8	fMax
	)

This function loads a MultiSFTVector from a given input MultiSFTCatalogView, otherwise the documentation of XLALLoadMultiSFTs() applies.

Note: this is basically the core-function of XLALLoadMultiSFTs() doing the actual work.

Note2: we keep the IFO sort-order of the input multiCatalogView

Parameters

multiCatalogView	The multi-SFT catalogue view of SFTs to load
fMin	minumum requested frequency (-1 = read from lowest)
fMax	maximum requested frequency (-1 = read up to highest)

Definition at line 449 of file SFTfileIO.c.

◆ XLALWriteSFT2FilePointer()

int XLALWriteSFT2FilePointer	(	const SFTtype *	sft,
		FILE *	fp,
		const CHAR *	SFTwindowtype,
		const REAL8	SFTwindowparam,
		const CHAR *	SFTcomment
	)

Write the given SFTtype to a FILE pointer.

Add the comment to SFT if SFTcomment != NULL.

NOTE: the comment written into the SFT-file contains the 'sft->name' field concatenated with the user-specified 'SFTcomment'

Parameters

sft	SFT to write to disk
fp	pointer to open file
SFTwindowtype	window applied to SFT, if any
SFTwindowparam	parameter of window
SFTcomment	optional comment

Definition at line 488 of file SFTfileIO.c.

◆ XLALWriteSFT2NamedFile()

int XLALWriteSFT2NamedFile	(	const SFTtype *	sft,
		const CHAR *	SFTfilename,
		const CHAR *	SFTwindowtype,
		const REAL8	SFTwindowparam,
		const CHAR *	SFTcomment
	)

Write the given SFTtype to a SFT file with the supplied filename.

Add the comment to SFT if SFTcomment != NULL.

NOTE: the comment written into the SFT-file contains the 'sft->name' field concatenated with the user-specified 'SFTcomment'

Parameters

sft	SFT to write to disk
SFTfilename	SFT filename
SFTwindowtype	window applied to SFT, if any
SFTwindowparam	parameter of window
SFTcomment	optional comment

Definition at line 598 of file SFTfileIO.c.

◆ XLALWriteSFT2StandardFile()

int XLALWriteSFT2StandardFile	(	const SFTtype *	sft,
		SFTFilenameSpec *	SFTfnspec,
		const CHAR *	SFTcomment
	)

Write the given SFTtype to a SFT file with a standard ([4]) filename.

Add the comment to SFT if SFTcomment != NULL.

NOTE: the comment written into the SFT-file contains the 'sft->name' field concatenated with the user-specified 'SFTcomment'

NOTE: The SFT filename spec is updated to reflect the filename of the written SFT, by setting the numSFTs, detector, SFTtimebase, gpsStart, and SFTspan fields. if needed, the SFT filename can be reconstructed with XLALBuildSFTFilenameFromSpec()

Parameters

sft	SFT to write to disk
SFTfnspec	SFT filename specification used to construct filename
SFTcomment	optional comment

Definition at line 656 of file SFTfileIO.c.

◆ XLALWriteSFTVector2NamedFile()

int XLALWriteSFTVector2NamedFile	(	const SFTVector *	sftVect,
		const CHAR *	SFTfilename,
		const CHAR *	SFTwindowtype,
		const REAL8	SFTwindowparam,
		const CHAR *	SFTcomment
	)

Write the given SFTVector to a single merged SFT file with the supplied filename.

Add the comment to SFT if SFTcomment != NULL.

Parameters

sftVect	SFT vector to write to disk
SFTfilename	SFT filename
SFTwindowtype	window applied to SFT, if any
SFTwindowparam	parameter of window
SFTcomment	optional comment

Definition at line 712 of file SFTfileIO.c.

◆ XLALWriteSFTVector2StandardFile()

int XLALWriteSFTVector2StandardFile	(	const SFTVector *	sftVect,
		SFTFilenameSpec *	SFTfnspec,
		const CHAR *	SFTcomment,
		const BOOLEAN	merged
	)

Write the given SFTVector to SFT file(s) with a standard ([4]) filename(s).

Add the comment to SFT if SFTcomment != NULL.

NOTE: The SFT filename spec is updated to reflect the filename of the written SFT, by setting the numSFTs, detector, SFTtimebase, gpsStart, and SFTspan fields. if needed, the SFT filename can be reconstructed with XLALBuildSFTFilenameFromSpec()

Parameters

sftVect	SFT vector to write to disk
SFTfnspec	SFT filename specification used to construct filename(s)
SFTcomment	optional comment
merged	If true, write a single merged SFT file; otherwise, write individual SFT files

Definition at line 755 of file SFTfileIO.c.

◆ XLALCheckSFTFileIsValid()

int XLALCheckSFTFileIsValid ( const char * fname )

Verify that the contents of a SFT file are valid.

This is just an XLAL wrapper to the SFTReferenceLibrary function ValidateSFTFile().

Returns: : XLAL_SUCCESS if no validation errors encountered.

Definition at line 834 of file SFTfileIO.c.

◆ endian_swap()

void endian_swap	(	CHAR *	pdata,
		size_t	dsize,
		size_t	nelements
	)

Definition at line 844 of file SFTfileIO.c.

◆ fopen_SFTLocator()

FILE * fopen_SFTLocator ( const struct tagSFTLocator * locator )

Open an "SFT" defined by the SFT-locator, return a FILE-pointer to the beginning of this SFT.

Note: The returned filepointer could point to an SFT-block within a merged SFT-file, so you should not assume that SEEK_SET takes you to the beginning of this block! (instead you'd have to save the current position returned by this function, which \ points to the beginning of the block!)

NOTE: Ideally this should be the ONLY function using the internal structure of the opaque SFTLocator type

Definition at line 882 of file SFTfileIO.c.

◆ read_SFTversion_from_fp()

int read_SFTversion_from_fp	(	UINT4 *	version,
		BOOLEAN *	need_swap,
		FILE *	fp
	)

Read valid SFT version-number at position fp, and determine if we need to endian-swap the data.

Restores filepointer to original position before returning.

RETURN: 0 = OK, -1 = ERROR

Definition at line 916 of file SFTfileIO.c.

◆ read_sft_header_from_fp()

int read_sft_header_from_fp	(	FILE *	fp,
		SFTtype *	header,
		UINT4 *	version,
		UINT8 *	crc64,
		UINT2 *	SFTwindowspec,
		BOOLEAN *	swapEndian,
		CHAR **	SFTcomment,
		UINT4 *	numBins
	)

Definition at line 992 of file SFTfileIO.c.

◆ read_header_from_fp()

int read_header_from_fp	(	FILE *	fp,
		SFTtype *	header,
		UINT4 *	nsamples,
		UINT8 *	header_crc64,
		UINT8 *	ref_crc64,
		UINT2 *	SFTwindowspec,
		CHAR **	SFTcomment,
		BOOLEAN	swapEndian
	)

static

Definition at line 1102 of file SFTfileIO.c.

◆ read_sft_bins_from_fp()

UINT4 read_sft_bins_from_fp	(	SFTtype *	ret,
		UINT4 *	firstBinRead,
		UINT4	firstBin2read,
		UINT4	lastBin2read,
		FILE *	fp
	)

Definition at line 1282 of file SFTfileIO.c.

◆ has_valid_crc64()

BOOLEAN has_valid_crc64 ( FILE * fp )

Check the SFT-block starting at fp for valid crc64 checksum.

Restores filepointer before leaving.

Definition at line 1409 of file SFTfileIO.c.

◆ XLALCWGPSinRange()

int XLALCWGPSinRange	(	const LIGOTimeGPS	gps,
		const LIGOTimeGPS *	minGPS,
		const LIGOTimeGPS *	maxGPS
	)

Defines the official CW convention for whether a GPS time is 'within' a given range, defined as the half-open interval [minGPS, maxGPS)

This function should be used when dealing with SFTs, segment lists, etc. It returns:

-1 if \( \mathtt{gps} < \mathtt{minGPS} \) , i.e. GPS time is 'below' the range;
0 if \( \mathtt{minGPS} \le \mathtt{gps} < \mathtt{maxGPS} \) , i.e. GPS time is 'within' the range;
1 if \( \mathtt{maxGPS} \le \mathtt{gos} \) , i.e. GPS time is 'above' the range;

If either minGPS or maxGPS are NULL, there are treated as \( -\infty \) or \( +\infty \) respectively.

Definition at line 52 of file SFTtypes.c.

◆ XLALRoundFrequencyDownToSFTBin()

UINT4 XLALRoundFrequencyDownToSFTBin	(	const REAL8	freq,
		const REAL8	df
	)

Round a REAL8 frequency down to the nearest integer SFT bin number.

This function provides an official rounding convention, including a "fudge" factor.

Definition at line 70 of file SFTtypes.c.

◆ XLALRoundFrequencyUpToSFTBin()

UINT4 XLALRoundFrequencyUpToSFTBin	(	const REAL8	freq,
		const REAL8	df
	)

Round a REAL8 frequency up to the nearest integer SFT bin number.

This function provides an official rounding convention, including a "fudge" factor.

Definition at line 82 of file SFTtypes.c.

◆ XLALFindCoveringSFTBins()

int XLALFindCoveringSFTBins	(	UINT4 *	firstBin,
		UINT4 *	numBins,
		REAL8	fMinIn,
		REAL8	BandIn,
		REAL8	Tsft
	)

Return the 'effective' frequency-band [fMinEff, fMaxEff] = [firstBin, lastBin] * 1/Tsft, with numBins = lastBin - firstBin + 1 which is the smallest band of SFT-bins that fully covers a given band [fMin, fMin+Band].

==> calculate "effective" fMinEff by rounding down from fMin to closest (firstBin/Tsft) and rounds up in the same way to fMaxEff = (lastBin/Tsft).

The 'fudge region' allowing for numerical noise is eps= 10*LAL_REAL8_EPS ~2e-15 relative deviation: ie if the SFT contains a bin at 'fi', then we consider for example "fMin == fi" if fabs(fi - fMin)/fi < eps.

Note: this function is most useful for internal operations, e.g. where a generated time series needs to be over-sampled to cover the SFT frequency band of interest. Ultimately SFTs covering a half-open interval [fMinIn,BandIn) should be returned to the user using XLALExtractStrictBandFromSFTVector().

Parameters

[out]	firstBin	effective lower frequency-bin fMinEff = firstBin/Tsft
[out]	numBins	effective Band of SFT-bins, such that BandEff = (numBins-1)/Tsft
[in]	fMinIn	input lower frequency
[in]	BandIn	input frequency band
[in]	Tsft	SFT duration 'Tsft'

Definition at line 106 of file SFTtypes.c.

◆ XLALCreateSFT()

SFTtype * XLALCreateSFT ( UINT4 numBins )

XLAL function to create one SFT-struct.

Note: Allows for numBins == 0, in which case only the header is allocated, with a NULL data pointer.

Definition at line 152 of file SFTtypes.c.

◆ XLALDestroySFT()

void XLALDestroySFT ( SFTtype * sft )

Destructor for one SFT.

Definition at line 176 of file SFTtypes.c.

◆ XLALCopySFT()

int XLALCopySFT	(	SFTtype *	dest,
		const SFTtype *	src
	)

Copy an entire SFT-type into another.

We require the destination-SFT to have a NULL data-entry, as the corresponding data-vector will be allocated here and copied into

Note: the source-SFT is allowed to have a NULL data-entry, in which case only the header is copied.

Parameters

[out]	dest	copied SFT (needs to be allocated already)
	src	input-SFT to be copied

Definition at line 202 of file SFTtypes.c.

◆ XLALCreateSFTVector()

SFTVector * XLALCreateSFTVector	(	UINT4	numSFTs,
		UINT4	numBins
	)

XLAL function to create an SFTVector of numSFT SFTs with SFTlen frequency-bins (which will be allocated too).

Parameters

numSFTs	number of SFTs
numBins	number of frequency-bins per SFT

Definition at line 230 of file SFTtypes.c.

◆ XLALCreateEmptySFTVector()

SFTVector * XLALCreateEmptySFTVector ( UINT4 numSFTs )

XLAL function to create an SFTVector of numSFT SFTs (which are not allocated).

Parameters

numSFTs number of SFTs

Definition at line 276 of file SFTtypes.c.

◆ XLALDestroySFTVector()

void XLALDestroySFTVector ( SFTVector * vect )

XLAL interface to destroy an SFTVector.

Definition at line 300 of file SFTtypes.c.

◆ XLALDuplicateSFTVector()

SFTVector * XLALDuplicateSFTVector ( const SFTVector * sftsIn )

Create a complete copy of an SFT vector.

Definition at line 328 of file SFTtypes.c.

◆ XLALCreateMultiSFTVector()

MultiSFTVector * XLALCreateMultiSFTVector	(	UINT4	length,
		UINT4Vector *	numsft
	)

Create a multi-IFO SFT vector with a given number of bins per SFT and number of SFTs per IFO (which will be allocated too).

Note that the input argument "length" refers to the number of frequency bins in each SFT. The length of the returned MultiSFTVector (i.e. the number of IFOs) is set from the length of the input numsft vector instead.

Parameters

length	number of SFT data points (frequency bins)
numsft	number of SFTs in each per-detector SFTVector

Definition at line 362 of file SFTtypes.c.

◆ XLALCreateEmptyMultiSFTVector()

MultiSFTVector * XLALCreateEmptyMultiSFTVector ( UINT4Vector * numsft )

Create an empty multi-IFO SFT vector with a given number of SFTs per IFO (which are not allocated).

Parameters

numsft number of SFTs in each per-detector SFTVector

Definition at line 394 of file SFTtypes.c.

◆ XLALDestroyMultiSFTVector()

void XLALDestroyMultiSFTVector ( MultiSFTVector * multvect )

Destroy a multi SFT-vector.

Parameters

multvect the SFT-vector to free

Definition at line 424 of file SFTtypes.c.

◆ XLALExtractBandFromSFT()

int XLALExtractBandFromSFT	(	SFTtype **	outSFT,
		const SFTtype *	inSFT,
		REAL8	fMin,
		REAL8	Band
	)

Return an SFTs containing only the bins in [fMin, fMin+Band].

Note: the output SFT is guaranteed to "cover" the input boundaries 'fMin' and 'fMin+Band', ie if necessary the output SFT contains one additional bin on either end of the interval.

This uses the conventions in XLALFindCoveringSFTBins() to determine the 'effective' frequency-band to extract.

Warning: This convention is deprecated. Please use either XLALExtractStrictBandFromSFT(), or else XLALSFTResizeBand() if you really need a covering frequency band.

Parameters

[out]	outSFT	output SFT (alloc'ed or re-alloced as required)
[in]	inSFT	input SFT
[in]	fMin	lower end of frequency interval to return
[in]	Band	band width of frequency interval to return

Definition at line 456 of file SFTtypes.c.

◆ XLALExtractBandFromSFTVector()

SFTVector * XLALExtractBandFromSFTVector	(	const SFTVector *	inSFTs,
		REAL8	fMin,
		REAL8	Band
	)

Return a vector of SFTs containing only the bins in [fMin, fMin+Band].

Note: the output SFT is guaranteed to "cover" the input boundaries 'fMin' and 'fMin+Band', ie if necessary the output SFT contains one additional bin on either end of the interval.

This uses the conventions in XLALFindCoveringSFTBins() to determine the 'effective' frequency-band to extract.

Warning: This convention is deprecated. Please use either XLALExtractStrictBandFromSFTVector(), or else XLALSFTVectorResizeBand() if you really need a covering frequency band.

Parameters

[in]	inSFTs	input SFTs
[in]	fMin	lower end of frequency interval to return
[in]	Band	band width of frequency interval to return

Definition at line 527 of file SFTtypes.c.

◆ XLALExtractBandFromMultiSFTVector()

MultiSFTVector * XLALExtractBandFromMultiSFTVector	(	const MultiSFTVector *	inSFTs,
		REAL8	fMin,
		REAL8	Band
	)

Return a MultiSFT vector containing only the bins in [fMin, fMin+Band].

Note: the output MultiSFT is guaranteed to "cover" the input boundaries 'fMin' and 'fMin+Band', ie if necessary the output SFT contains one additional bin on either end of the interval.

This uses the conventions in XLALFindCoveringSFTBins() to determine the 'effective' frequency-band to extract.

Warning: This convention is deprecated. Please use either XLALExtractStrictBandFromMultiSFTVector(), or else XLALMultiSFTVectorResizeBand() if you really need a covering frequency band.

Parameters

[in]	inSFTs	input MultiSFTs
[in]	fMin	lower end of frequency interval to return
[in]	Band	band width of frequency interval to return

Definition at line 572 of file SFTtypes.c.

◆ XLALExtractStrictBandFromSFT()

int XLALExtractStrictBandFromSFT	(	SFTtype **	outSFT,
		const SFTtype *	inSFT,
		REAL8	fMin,
		REAL8	Band
	)

Return a copy of an SFT containing only the bins in [fMin, fMin+Band).

Parameters

[out]	outSFT	output SFT (alloc'ed or re-alloced as required)
[in]	inSFT	input SFT
[in]	fMin	lower end of frequency interval to return
[in]	Band	band width of frequency interval to return

Definition at line 601 of file SFTtypes.c.

◆ XLALExtractStrictBandFromSFTVector()

SFTVector * XLALExtractStrictBandFromSFTVector	(	const SFTVector *	inSFTs,
		REAL8	fMin,
		REAL8	Band
	)

Return a copy of a vector of SFTs containing only the bins in [fMin, fMin+Band).

Parameters

[in]	inSFTs	input SFTs
[in]	fMin	lower end of frequency interval to return
[in]	Band	band width of frequency interval to return

Definition at line 658 of file SFTtypes.c.

◆ XLALExtractStrictBandFromMultiSFTVector()

MultiSFTVector * XLALExtractStrictBandFromMultiSFTVector	(	const MultiSFTVector *	inSFTs,
		REAL8	fMin,
		REAL8	Band
	)

Return a copy of a MultiSFT vector containing only the bins in [fMin, fMin+Band).

Parameters

[in]	inSFTs	input MultiSFTs
[in]	fMin	lower end of frequency interval to return
[in]	Band	band width of frequency interval to return

Definition at line 691 of file SFTtypes.c.

◆ XLALAppendSFT2Vector()

int XLALAppendSFT2Vector	(	SFTVector *	vect,
		const SFTtype *	sft
	)

Append the given SFTtype to the SFT-vector (no SFT-specific checks are done!)

Parameters

vect	destinatino SFTVector to append to
sft	the SFT to append

Definition at line 716 of file SFTtypes.c.

◆ XLALReorderMultiSFTVector()

int XLALReorderMultiSFTVector	(	MultiSFTVector *	multiSFTs,
		const LALStringVector *	IFOs
	)

Reorder the MultiSFTVector with specified list of IFOs.

Definition at line 738 of file SFTtypes.c.

◆ XLALSFTAdd()

int XLALSFTAdd	(	SFTtype *	a,
		const SFTtype *	b
	)

Adds SFT-data from SFT 'b' to SFT 'a'.

NOTE: the inputs 'a' and 'b' must have consistent start-frequency, frequency-spacing, timestamps, units and number of bins.

The 'name' field of input/output SFTs in 'a' is not modified!

Parameters

	a	[in/out] SFT to be added to
[in]	b	SFT data to be added

Definition at line 775 of file SFTtypes.c.

◆ XLALSFTVectorAdd()

int XLALSFTVectorAdd	(	SFTVector *	a,
		const SFTVector *	b
	)

Adds SFT-data from SFTvector 'b' to elements of SFTVector 'a'.

NOTE: the inputs 'a' and 'b' must have consistent number of SFTs, start-frequency, frequency-spacing, timestamps, units and number of bins.

The 'name' field of input/output SFTs in 'a' is not modified!

Parameters

	a	[in/out] SFTVector to be added to
[in]	b	SFTVector data to be added

Definition at line 811 of file SFTtypes.c.

◆ XLALMultiSFTVectorAdd()

int XLALMultiSFTVectorAdd	(	MultiSFTVector *	a,
		const MultiSFTVector *	b
	)

Adds SFT-data from MultiSFTvector 'b' to elements of MultiSFTVector 'a'.

NOTE: the inputs 'a' and 'b' must have consistent number of IFO, number of SFTs, IFO-names, start-frequency, frequency-spacing, timestamps, units and number of bins.

The 'name' field of input/output SFTs in 'a' is not modified!

Parameters

	a	[in/out] MultiSFTVector to be added to
[in]	b	MultiSFTVector data to be added

Definition at line 842 of file SFTtypes.c.

◆ XLALSFTResizeBand()

int XLALSFTResizeBand	(	SFTtype *	SFT,
		REAL8	f0,
		REAL8	Band
	)

Resize the frequency-band of a given SFT to [f0, f0+Band].

NOTE: If the frequency band is extended in any direction, the corresponding bins will be set to zero

NOTE2: This uses the conventions in XLALFindCoveringSFTBins() to determine the 'effective' frequency-band to resize to, in order to coincide with SFT frequency bins.

Parameters

	SFT	[in/out] SFT to resize
[in]	f0	new start frequency
[in]	Band	new frequency Band

Definition at line 878 of file SFTtypes.c.

◆ XLALSFTVectorResizeBand()

int XLALSFTVectorResizeBand	(	SFTVector *	SFTs,
		REAL8	f0,
		REAL8	Band
	)

Resize the frequency-band of a given SFT vector to [f0, f0+Band].

NOTE: If the frequency band is extended in any direction, the corresponding bins will be set to zero

NOTE2: This uses the conventions in XLALFindCoveringSFTBins() to determine the 'effective' frequency-band to resize to, in order to coincide with SFT frequency bins.

Parameters

	SFTs	[in/out] SFT vector to resize
[in]	f0	new start frequency
[in]	Band	new frequency Band

Definition at line 917 of file SFTtypes.c.

◆ XLALMultiSFTVectorResizeBand()

int XLALMultiSFTVectorResizeBand	(	MultiSFTVector *	multiSFTs,
		REAL8	f0,
		REAL8	Band
	)

Resize the frequency-band of a given multi-SFT vector to [f0, f0+Band].

NOTE: If the frequency band is extended in any direction, the corresponding bins will be set to zero

NOTE2: This uses the conventions in XLALFindCoveringSFTBins() to determine the 'effective' frequency-band to resize to, in order to coincide with SFT frequency bins.

Parameters

	multiSFTs	[in/out] multi-SFT vector to resize
[in]	f0	new start frequency
[in]	Band	new frequency Band

Definition at line 946 of file SFTtypes.c.

◆ XLALEarliestMultiSFTsample()

int XLALEarliestMultiSFTsample	(	LIGOTimeGPS *	out,
		const MultiSFTVector *	multisfts
	)

Finds the earliest timestamp in a multi-SFT data structure.

Parameters

[out]	out	earliest GPS time
[in]	multisfts	multi SFT vector

Definition at line 968 of file SFTtypes.c.

◆ XLALLatestMultiSFTsample()

int XLALLatestMultiSFTsample	(	LIGOTimeGPS *	out,
		const MultiSFTVector *	multisfts
	)

Find the time of the end of the latest SFT in a multi-SFT data structure.

Parameters

[out]	out	latest GPS time
[in]	multisfts	multi SFT vector

Definition at line 1016 of file SFTtypes.c.

◆ XLALExtractSFTVectorWithTimestamps()

SFTVector * XLALExtractSFTVectorWithTimestamps	(	const SFTVector *	sfts,
		const LIGOTimeGPSVector *	timestamps
	)

Extract an SFTVector from another SFTVector but only those timestamps matching.

Timestamps must be a subset of those sfts in the SFTVector or an error occurs

Parameters

sfts	input SFTs
timestamps	timestamps

Definition at line 1076 of file SFTtypes.c.

◆ XLALExtractMultiSFTVectorWithMultiTimestamps()

MultiSFTVector * XLALExtractMultiSFTVectorWithMultiTimestamps	(	const MultiSFTVector *	multiSFTs,
		const MultiLIGOTimeGPSVector *	multiTimestamps
	)

Extract a MultiSFTVector from another MultiSFTVector but only those timestamps matching.

Timestamps in each LIGOTimeGPSVector must be a subset of those sfts in each SFTVector or an error occurs

Parameters

multiSFTs	input SFTs
multiTimestamps	timestamps

Definition at line 1116 of file SFTtypes.c.

◆ XLALCreateTimestampVector()

LIGOTimeGPSVector * XLALCreateTimestampVector ( UINT4 len )

Allocate a LIGOTimeGPSVector.

Definition at line 47 of file SFTtimestamps.c.

◆ XLALDestroyTimestampVector()

void XLALDestroyTimestampVector ( LIGOTimeGPSVector * vect )

De-allocate a LIGOTimeGPSVector.

Definition at line 69 of file SFTtimestamps.c.

◆ XLALResizeTimestampVector()

LIGOTimeGPSVector * XLALResizeTimestampVector	(	LIGOTimeGPSVector *	vector,
		UINT4	length
	)

Resize a LIGOTimeGPSVector.

Definition at line 85 of file SFTtimestamps.c.

◆ XLALCreateMultiLIGOTimeGPSVector()

MultiLIGOTimeGPSVector * XLALCreateMultiLIGOTimeGPSVector ( UINT4 numDetectors )

Simple creator function for MultiLIGOTimeGPSVector with numDetectors entries.

Definition at line 110 of file SFTtimestamps.c.

◆ XLALDestroyMultiTimestamps()

void XLALDestroyMultiTimestamps ( MultiLIGOTimeGPSVector * multiTS )

Destroy a MultiLIGOTimeGPSVector timestamps vector.

Definition at line 135 of file SFTtimestamps.c.

◆ XLALFindTimesliceBounds()

int XLALFindTimesliceBounds	(	UINT4 *	iStart,
		UINT4 *	iEnd,
		const LIGOTimeGPSVector *	timestamps,
		const LIGOTimeGPS *	minStartGPS,
		const LIGOTimeGPS *	maxStartGPS
	)

Definition at line 158 of file SFTtimestamps.c.

◆ XLALMakeTimestamps()

LIGOTimeGPSVector * XLALMakeTimestamps	(	LIGOTimeGPS	tStart,
		REAL8	Tspan,
		REAL8	Tsft,
		REAL8	Toverlap
	)

Given a start-time, Tspan, Tsft and Toverlap, returns a list of timestamps covering this time-stretch (allowing for overlapping SFTs).

NOTE: boundary-handling: the returned list of timestamps fall within the interval [tStart, tStart+Tspan), consistent with the convention defined in XLALCWGPSinRange(). Assuming each SFT covers a stretch of data of length 'Tsft', the returned timestamps correspond to a set of SFTs that is guaranteed to cover all data between 'tStart' and 'tStart+Tspan'. This implies that, while the last timestamp returned will always be 'ret->data[numSFTs-1] < tStart+Tspan', the actual data coverage can extend up to 'Tsft' beyond 'tStart+duration'.

Parameters

tStart	GPS start-time
Tspan	total duration to cover, in seconds
Tsft	length of the SFT corresponding to each timestamp, in seconds
Toverlap	time to overlap successive SFTs by, in seconds

Definition at line 225 of file SFTtimestamps.c.

◆ XLALMakeMultiTimestamps()

MultiLIGOTimeGPSVector * XLALMakeMultiTimestamps	(	LIGOTimeGPS	tStart,
		REAL8	Tspan,
		REAL8	Tsft,
		REAL8	Toverlap,
		UINT4	numDet
	)

Same as XLALMakeTimestamps() just for several detectors, additionally specify the number of detectors.

Parameters

tStart	GPS start-time
Tspan	total duration to cover, in seconds
Tsft	Tsft: SFT length of each timestamp, in seconds
Toverlap	time to overlap successive SFTs by, in seconds
numDet	number of timestamps-vectors to generate

Definition at line 272 of file SFTtimestamps.c.

◆ XLALReadTimestampsFile()

LIGOTimeGPSVector * XLALReadTimestampsFile ( const CHAR * fname )

backwards compatible wrapper to XLALReadTimestampsFileConstrained() without GPS-time constraints

Definition at line 297 of file SFTtimestamps.c.

◆ XLALReadMultiTimestampsFiles()

MultiLIGOTimeGPSVector * XLALReadMultiTimestampsFiles ( const LALStringVector * fnames )

backwards compatible wrapper to XLALReadMultiTimestampsFilesConstrained() without GPS-time constraints

Definition at line 305 of file SFTtimestamps.c.

◆ XLALReadTimestampsFileConstrained()

LIGOTimeGPSVector * XLALReadTimestampsFileConstrained	(	const CHAR *	fname,
		const LIGOTimeGPS *	minGPS,
		const LIGOTimeGPS *	maxGPS
	)

Load timestamps file 'fname' into LIGOTimeGPSVector struct, allocated here.

The timestamps file must contain one GPS time per line, allowing for '%#' as comments, which are ignored. The constraints 'minGPS', 'maxGPS' are applied by returning only timestamps that fall within the range defined by XLALCWGPSinRange(gps, minGPS, maxGPS) == 0.

check input consistency

Definition at line 319 of file SFTtimestamps.c.

◆ XLALReadMultiTimestampsFilesConstrained()

MultiLIGOTimeGPSVector * XLALReadMultiTimestampsFilesConstrained	(	const LALStringVector *	fnames,
		const LIGOTimeGPS *	minGPS,
		const LIGOTimeGPS *	maxGPS
	)

Load several timestamps files, return a MultiLIGOTimeGPSVector struct, allocated here.

The timestamps files must contain one GPS time per line, allowing for '%#' as comments, which are ignored. The constraints 'minGPS', 'maxGPS' are applied by returning only timestamps that fall within the range defined by XLALCWGPSinRange(gps, minGPS, maxGPS) == 0.

Definition at line 388 of file SFTtimestamps.c.

◆ XLALExtractTimestampsFromSFTs()

LIGOTimeGPSVector * XLALExtractTimestampsFromSFTs ( const SFTVector * sfts )

Extract timstamps-vector from the given SFTVector.

Parameters

[in] sfts input SFT-vector

Definition at line 416 of file SFTtimestamps.c.

◆ XLALExtractMultiTimestampsFromSFTs()

MultiLIGOTimeGPSVector * XLALExtractMultiTimestampsFromSFTs ( const MultiSFTVector * multiSFTs )

Given a multi-SFT vector, return a MultiLIGOTimeGPSVector holding the SFT timestamps.

Definition at line 449 of file SFTtimestamps.c.

◆ XLALTimestampsFromSFTCatalog()

LIGOTimeGPSVector * XLALTimestampsFromSFTCatalog ( const SFTCatalog * catalog )

Extract timestamps-vector of unique timestamps from the given SFTCatalog.

NOTE: when dealing with catalogs of frequency-slided SFTs, each timestamp will appear in the catalog multiple times, depending on how many frequency slices have been read in. In such cases this function will return the list of unique timestamps.

NOTE 2: This function will also enfore the multiplicity of each timestamp to be the same through the whole catalog, corresponding to the case of 'frequency-sliced' SFTs, while non-constant multiplicities would indicate a potential problem somewhere.

Parameters

[in] catalog input SFT-catalog

Definition at line 500 of file SFTtimestamps.c.

◆ XLALTimestampsFromMultiSFTCatalogView()

MultiLIGOTimeGPSVector * XLALTimestampsFromMultiSFTCatalogView ( const MultiSFTCatalogView * multiView )

Given a multi-SFTCatalogView, return a MultiLIGOTimeGPSVector holding the SFT timestamps.

Definition at line 560 of file SFTtimestamps.c.

◆ XLALReadSegmentsFromFile()

LALSegList * XLALReadSegmentsFromFile ( const char * fname )

Function to read a segment list from given filename, returns a sorted LALSegList.

The segment list file format is repeated lines (excluding comment lines beginning with % or #) of one of the following forms:

startGPS endGPS
startGPS endGPS NumSFTs (NumSFTs must be a positive integer)
startGPS endGPS duration NumSFTs (DEPRECATED, duration is ignored)

Note: We (ab)use the integer id field in LALSeg to carry the total number of SFTs contained in that segment if NumSFTs was provided in the segment file. This can be used as a consistency check when loading SFTs for these segments.

Parameters

fname name of file containing segment list

Definition at line 598 of file SFTtimestamps.c.

◆ XLALTimestampsFromSegmentFile()

LIGOTimeGPSVector * XLALTimestampsFromSegmentFile	(	const char *	filename,
		REAL8	Tsft,
		REAL8	Toverlap,
		BOOLEAN	adjustSegExtraTime,
		BOOLEAN	synchronize
	)

Extract timestamps-vector from a segment file, with functionality based on MakeSFTDAG The filename should point to a file containing <GPSstart GPSend> of segments or <GPSstart GPSend segLength numSFTs> where segLength is in hours.

adjustSegExtraTime is used in MakeSFTDAG to maximize the number of SFTs in each segement by placing the SFTs in the middle of the segment. synchronize is used to force the start times of the SFTs to be integer multiples of Toverlap from the start time of the first SFT. adjustSegExtraTime and synchronize cannot be used concurrently (synchronize will be preferred if both values are non-zero).

Parameters

filename	filename: Input filename
Tsft	Tsft: SFT length of each timestamp, in seconds
Toverlap	Toverlap: time to overlap successive SFTs by, in seconds
adjustSegExtraTime	adjustSegExtraTime: remove the unused time from beginning and end of the segments (see MakeSFTDAG)
synchronize	synchronize: synchronize SFT start times according to the start time of the first SFT. Start time of first SFT is shifted to next higher integer value of Tsft

Definition at line 694 of file SFTtimestamps.c.

◆ XLALRegisterSpecialCWDetector()

int XLALRegisterSpecialCWDetector ( const LALDetector * specialDetector )

Register a special detector for use with CW codes.

The special detector must have a 2-character prefix of the form "[XYZ][0123456789]".

Definition at line 73 of file SFTnaming.c.

◆ XLALFindCWDetector()

int XLALFindCWDetector	(	CHAR **	prefix,
		INT4 *	lalCachedIndex,
		const CHAR *	name,
		const BOOLEAN	exactMatch
	)

Parses valid CW detector names and prefixes.

'name' input can be either a valid detector name or prefix

Returns: XLAL_SUCCESS if 'name' is a valid detector name/prefix, an XLAL error code on failure

If passed a non-NULL pointer 'prefix', will be set to the Allocated prefix string (2 characters+0) for valid detectors, NULL otherwise.

If passed a non-NULL pointer 'lalCachedIndex', will set to index >= 0 into the lalCachedDetectors[] array if found there, or -1 if it's one of the "CW special" detectors

Note: This should be the only function defining valid CW detector names and prefixes; 'prefix' is allocated here and needs to be free'ed by caller!; Unless 'exactMatch' is true, if first two characters of 'name' match a valid detector prefix, that is accepted, which allows passing longer strings beginning with a detector prefix ('H1:blabla') without extra hassle

Definition at line 118 of file SFTnaming.c.

◆ XLALIsValidCWDetector()

BOOLEAN XLALIsValidCWDetector ( const CHAR * name )

Determine if 'name' is a valid detector name or prefix.

Returns: TRUE if 'name' is a valid detector name/prefix, FALSE otherwise (or if an error is encountered; this function does not raise XLAL errors)

Definition at line 188 of file SFTnaming.c.

◆ XLALGetChannelPrefix()

CHAR * XLALGetChannelPrefix ( const CHAR * name )

Find the valid CW detector prefix.

'name' input can be either a valid detector name or prefix

Note: The returned string is allocated here!

Definition at line 203 of file SFTnaming.c.

◆ XLALGetSiteInfo()

const LALDetector * XLALGetSiteInfo ( const CHAR * name )

Find the site geometry-information 'LALDetector' for given a detector name (or prefix).

Definition at line 218 of file SFTnaming.c.

◆ XLALFillSFTFilenameSpecStrings()

int XLALFillSFTFilenameSpecStrings	(	SFTFilenameSpec *	spec,
		const CHAR *	path,
		const CHAR *	extn,
		const CHAR *	detector,
		const CHAR *	window_type,
		const CHAR *	privMisc,
		const CHAR *	pubObsKind,
		const CHAR *	pubChannel
	)

Convenience function for filling out the string fields in a SFTFilenameSpec.

Parameters

[out]	spec	SFT filename specification
[in]	path	Path to the SFT file
[in]	extn	Extension of the SFT file; defaults to 'sft'
[in]	detector	2-character detector prefix (e.g. 'H1', 'L1', 'V1')
[in]	window_type	window function applied to SFT
[in]	privMisc	For private SFTs: miscellaneous description field
[in]	pubObsKind	For public SFTs: kind of data ('RUN', 'AUX', 'SIM', 'DEV')
[in]	pubChannel	For public SFTs: channel name of data used to make SFTs

Definition at line 257 of file SFTnaming.c.

◆ XLALBuildSFTFilenameFromSpec()

char * XLALBuildSFTFilenameFromSpec ( const SFTFilenameSpec * spec )

Build an SFT file name from the given specification.

Parameters

[in] spec SFT filename specification

Definition at line 302 of file SFTnaming.c.

◆ XLALParseSFTFilenameIntoSpec()

int XLALParseSFTFilenameIntoSpec	(	SFTFilenameSpec *	spec,
		const char *	SFTpath
	)

Parse a SFT file path and return its specification.

Parameters

[out]	spec	SFT filename specification
[in]	SFTpath	SFT file path

Definition at line 463 of file SFTnaming.c.

◆ XLALCheckValidDescriptionField()

int XLALCheckValidDescriptionField ( const char * desc )

Check whether given string qualifies as a valid 'description' field of a FRAME filename (per [25]) or SFT filename (per [4])

Definition at line 639 of file SFTnaming.c.

◆ XLALCompareSFTWindows()

int XLALCompareSFTWindows	(	const CHAR *	type1,
		const REAL8	param1,
		const CHAR *	type2,
		const REAL8	param2
	)

Check whether two SFT windows, each defined by a type name and parameter value, match.

This builds standardized windowspec numbers out of the inputs and compares those, ensuring consistent rounding before the comparison.

Parameters

[in]	type1	type name of the first window
[in]	param1	parameter value of the first window
[in]	type2	type name of the second window
[in]	param2	parameter value of the second window

Definition at line 667 of file SFTnaming.c.

◆ XLALFindFiles()

LALStringVector * XLALFindFiles ( const CHAR * globstring )

Returns a list of filenames matching the input argument, which may be one of the following:

<file>[;<file>;...]: a list of filenames.
<glob>[;<glob>;...]: a list of glob-like pattern(s) such as *.sft, ./dir/*.sft, etc.
list:<filelist>: a file containing a list of filenames. Prefixes of the form file://localhost/ or file:/// are removed.

Note: the list of filenames is returned sorted alphabetically.

Definition at line 61 of file FindFiles.c.

◆ build_sft_windowspec()

int build_sft_windowspec	(	UINT2 *	windowspec,
		CHAR(*)	windowspec_str[9],
		const char *	window_type,
		REAL8	window_param
	)

Build an SFT 2-byte 'windowspec' or filename field 'windowspec_str' for the window given by 'window_type' and 'window_param'.

Definition at line 691 of file SFTnaming.c.

◆ parse_sft_windowspec()

int parse_sft_windowspec	(	const UINT2	windowspec,
		const char **	window_type,
		REAL8 *	window_param
	)

Parse an SFT 2-byte 'windowspec' into a window name 'window_type' and possible parameter 'window_param'.

Definition at line 752 of file SFTnaming.c.

◆ parse_sft_windowspec_str()

int parse_sft_windowspec_str	(	const CHAR *	windowspec_str,
		CHAR(*)	window_type[32],
		REAL8 *	window_param
	)

Parse an SFT filename field 'windowspec_str' into a window name 'window_type' and possible parameter 'window_param'.

Definition at line 802 of file SFTnaming.c.

◆ TSFTfromDFreq()

REAL8 TSFTfromDFreq ( REAL8 dFreq )

Definition at line 1144 of file SFTtypes.c.

◆ compareSFTdesc()

int compareSFTdesc	(	const void *	ptr1,
		const void *	ptr2
	)

Definition at line 1161 of file SFTtypes.c.

◆ compareSFTloc()

int compareSFTloc	(	const void *	ptr1,
		const void *	ptr2
	)

Definition at line 1182 of file SFTtypes.c.

◆ compareDetNameCatalogs()

int compareDetNameCatalogs	(	const void *	ptr1,
		const void *	ptr2
	)

Definition at line 1208 of file SFTtypes.c.

◆ compareSFTepoch()

int compareSFTepoch	(	const void *	ptr1,
		const void *	ptr2
	)

Definition at line 1231 of file SFTtypes.c.

Typedef Documentation

◆ SFTtype

typedef COMPLEX8FrequencySeries SFTtype

A so-called 'SFT' (short-Fourier-transform) will be stored in a COMPLEX8FrequencySeries.

Definition at line 173 of file SFTfileIO.h.

◆ SFTVector

typedef COMPLEX8FrequencySeriesVector SFTVector

The corresponding vector-type to hold a vector of 'SFTs'.

Definition at line 176 of file SFTfileIO.h.

Detailed Description

Overview

Usage: Reading of SFT-files

Details to 1: find matching SFTs and get the SFTCatalog:

Details to 2: load frequency-band from SFTs described in an SFTCatalog

Usage: Writing of SFT-files

Prototypes

Data Structures

Typedefs

Files

SFT file reading functions

SFT catalog create/destroy functions

SFT catalog property functions

SFT catalog generation functions

SFT file writing functions

Time range/frequency bin convention functions

SFT type create/destroy functions

SFT type modify functions

SFT type property functions

SFT timestamp type create/destroy functions

SFT timestamp type property functions

SFT timestamp generation functions

SFT file naming convention functions

Function Documentation

◆ XLALReadSFDB()

◆ read_SFDB_header_from_fp()

◆ CheckIfSFDBInScienceMode()

◆ XLALSFTdataFind()

◆ XLALDestroySFTCatalog()

◆ XLALGetMultiSFTCatalogView()

◆ XLALDestroyMultiSFTCatalogView()

◆ XLALCheckCRCSFTCatalog()

◆ XLALListIFOsInCatalog()

◆ XLALCountIFOsInCatalog()

◆ XLALshowSFTLocator()

◆ XLALSFTCatalogTimeslice()

◆ XLALReturnSFTCatalogTimeslice()

◆ XLALAddToFakeSFTCatalog()

◆ XLALMultiAddToFakeSFTCatalog()

◆ get_file_len()

◆ consistent_mSFT_header()

◆ timestamp_in_list()

◆ XLALLoadSFTs()

◆ XLALLoadMultiSFTs()

◆ XLALLoadMultiSFTsFromView()

◆ XLALWriteSFT2FilePointer()

◆ XLALWriteSFT2NamedFile()

◆ XLALWriteSFT2StandardFile()

◆ XLALWriteSFTVector2NamedFile()

◆ XLALWriteSFTVector2StandardFile()

◆ XLALCheckSFTFileIsValid()

◆ endian_swap()

◆ fopen_SFTLocator()

◆ read_SFTversion_from_fp()

◆ read_sft_header_from_fp()

◆ read_header_from_fp()

◆ read_sft_bins_from_fp()

◆ has_valid_crc64()

◆ XLALCWGPSinRange()

◆ XLALRoundFrequencyDownToSFTBin()

◆ XLALRoundFrequencyUpToSFTBin()

◆ XLALFindCoveringSFTBins()

◆ XLALCreateSFT()

◆ XLALDestroySFT()

◆ XLALCopySFT()

◆ XLALCreateSFTVector()

◆ XLALCreateEmptySFTVector()

◆ XLALDestroySFTVector()

◆ XLALDuplicateSFTVector()

◆ XLALCreateMultiSFTVector()

◆ XLALCreateEmptyMultiSFTVector()

◆ XLALDestroyMultiSFTVector()

◆ XLALExtractBandFromSFT()

◆ XLALExtractBandFromSFTVector()

◆ XLALExtractBandFromMultiSFTVector()

◆ XLALExtractStrictBandFromSFT()

◆ XLALExtractStrictBandFromSFTVector()

◆ XLALExtractStrictBandFromMultiSFTVector()

◆ XLALAppendSFT2Vector()

◆ XLALReorderMultiSFTVector()