SFTutils.h File Reference

Author:
Reinhard Prix, Badri Krishnan Utility functions for handling of SFTtype and SFTVectors
More...

#include <stdarg.h>
#include <lal/LALDatatypes.h>
#include <lal/DetectorSite.h>
#include <lal/Date.h>
#include <lal/SkyCoordinates.h>
#include <lal/RngMedBias.h>
#include <lal/LALRunningMedian.h>

Include dependency graph for SFTutils.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  COMPLEX8FrequencySeriesVector
 A vector of COMPLEX8FrequencySeries. More...
struct  REAL8FrequencySeriesVector
 A vector of REAL8FrequencySeries. More...
struct  tagMultiSFTVector
 A collection of SFT vectors -- one for each IFO in a multi-IFO search. More...
struct  MultiPSDVector
 A collection of PSD vectors -- one for each IFO in a multi-IFO search. More...
struct  MultiNoiseWeights
 One noise-weight (number) per SFT (therefore indexed over IFOs and SFTs. More...
struct  MultiREAL4TimeSeries
 A collection of (multi-IFO) time-series. More...
struct  LIGOTimeGPSVector
 A vector of 'timestamps' of type LIGOTimeGPS. More...
struct  MultiLIGOTimeGPSVector
 A vector of 'timestamps' of type LIGOTimeGPS. More...

Defines

#define SFTUTILS_ENULL   1
#define SFTUTILS_ENONULL   2
#define SFTUTILS_EMEM   3
#define SFTUTILS_EINPUT   4
#define SFTUTILS_EFUNC   6
#define SFTUTILS_MSGENULL   "Arguments contained an unexpected null pointer"
#define SFTUTILS_MSGENONULL   "Output pointer is not NULL"
#define SFTUTILS_MSGEMEM   "Out of memory"
#define SFTUTILS_MSGEINPUT   "Invald input parameter"
#define SFTUTILS_MSGEFUNC   "Sub-routine failed"

Typedefs

typedef COMPLEX8FrequencySeries SFTtype
 A so-called 'SFT' (short-Fourier-transform) will be stored in a COMPLEX8FrequencySeries.
typedef COMPLEX8FrequencySeriesVector SFTVector
 The corresponding vector-type to hold a vector of 'SFTs'.
typedef REAL8FrequencySeriesVector PSDVector
 Special type for holding a PSD vector (over several SFTs).
typedef tagMultiSFTVector MultiSFTVector
 A collection of SFT vectors -- one for each IFO in a multi-IFO search.

Functions

 NRCSID (SFTUTILSH,"$Id: SFTutils.h,v 1.35 2008/05/29 21:21:24 whelan Exp $")
void LALCreateSFTtype (LALStatus *status, SFTtype **sft, UINT4 SFTlen)
 Create one SFT-struct.
void LALCreateSFTVector (LALStatus *status, SFTVector **sftvect, UINT4 numSFTs, UINT4 SFTlen)
 Create a whole vector of numSFT SFTs with SFTlen frequency-bins.
void LALCreateMultiSFTVector (LALStatus *status, MultiSFTVector **out, UINT4 length, UINT4Vector *numsft)
SFTVectorXLALCreateSFTVector (UINT4 numSFTs, UINT4 numBins)
 XLAL function to create an SFTVector of numSFT SFTs with SFTlen frequency-bins.
COMPLEX8VectorXLALrefineCOMPLEX8Vector (const COMPLEX8Vector *in, UINT4 refineby, UINT4 Dterms)
 Interpolate frequency-series to newLen frequency-bins.
void upsampleMultiSFTVector (LALStatus *, MultiSFTVector *inout, UINT4 upsample, UINT4 Dterms)
 upsample a given multi-SFTvector by the given (integer) factor, _replacing_ the original SFTs
void upsampleSFTVector (LALStatus *, SFTVector *inout, UINT4 upsample, UINT4 Dterms)
void XLALDestroySFTVector (SFTVector *vect)
 XLAL interface to destroy an SFTVector.
void LALDestroySFTtype (LALStatus *status, SFTtype **sft)
 Destroy an SFT-struct.
void LALDestroySFTVector (LALStatus *status, SFTVector **sftvect)
 Destroy an SFT-vector.
void LALDestroyPSDVector (LALStatus *status, PSDVector **vect)
 Destroy a PSD-vector.
void LALDestroyMultiSFTVector (LALStatus *status, MultiSFTVector **multvect)
 Destroy a multi SFT-vector.
void LALDestroyMultiPSDVector (LALStatus *status, MultiPSDVector **multvect)
 Destroy a multi PSD-vector.
SFTVectorXLALExtractBandfromSFTs (const SFTVector *sfts, REAL8 fMin, REAL8 fMax)
 Extract a frequency band from an SFTVector, returning a new SFTvector Note: fMin < 0 implies to start from lowest frequency bin, fMax < 0 implies to include up to highest frequency bin.
void LALCopySFT (LALStatus *status, SFTtype *dest, const SFTtype *src)
 Copy an entire SFT-type into another.
void LALSubtractSFTVectors (LALStatus *, SFTVector **outVect, const SFTVector *inVect1, const SFTVector *inVect2)
 Subtract two SFT-vectors and put the results in a new one (which it allocates).
void LALLinearlyCombineSFTVectors (LALStatus *, SFTVector **outVect, SFTVector **inVects, const COMPLEX16Vector *weights, const CHAR *outName)
 Linearly combine two or more SFT-vectors and put the results in a new one (which it allocates).
void LALAppendSFT2Vector (LALStatus *, SFTVector *vect, const SFTtype *sft)
 Append the given SFTtype to the SFT-vector (no SFT-specific checks are done!).
LIGOTimeGPSVectorXLALCreateTimestampVector (UINT4 len)
 Allocate a LIGOTimeGPSVector.
void XLALDestroyTimestampVector (LIGOTimeGPSVector *vect)
 De-allocate a LIGOTimeGPSVector.
void LALCreateTimestampVector (LALStatus *status, LIGOTimeGPSVector **vect, UINT4 len)
 LAL-interface: Allocate a LIGOTimeGPSVector.
void LALDestroyTimestampVector (LALStatus *status, LIGOTimeGPSVector **vect)
 De-allocate a LIGOTimeGPSVector.
void LALMakeTimestamps (LALStatus *, LIGOTimeGPSVector **timestamps, const LIGOTimeGPS tStart, REAL8 duration, REAL8 Tsft)
 Given a start-time, duration and 'stepsize' tStep, returns a list of timestamps covering this time-stretch.
void LALGetSFTtimestamps (LALStatus *, LIGOTimeGPSVector **timestamps, const SFTVector *sfts)
 Extract timstamps-vector from the given SFTVector.
CHARXLALGetChannelPrefix (const CHAR *name)
 Extract/construct the unique 2-character "channel prefix" from the given "detector-name", which unfortunately will not always follow any of the official detector-naming conventions given in the Frames-Spec LIGO-T970130-F-E This function therefore sometime has to do some creative guessing:.
LALDetectorXLALGetSiteInfo (const CHAR *name)
 Find the site geometry-information 'LALDetector' (mis-nomer!) given a detector-name.
void LALComputeNoiseWeights (LALStatus *status, REAL8Vector *weightV, const SFTVector *sftVect, INT4 blkSize, UINT4 excludePercentile)
 Computes weight factors arising from SFTs with different noise floors -- it multiplies an existing weight vector.
void LALComputeMultiNoiseWeights (LALStatus *status, MultiNoiseWeights **weightsV, const MultiPSDVector *multipsd, UINT4 blocksRngMed, UINT4 excludePercentile)
 Computes weight factors arising from MultiSFTs with different noise floors -- it multiplies an existing weight vector.
void LALDestroyMultiNoiseWeights (LALStatus *status, MultiNoiseWeights **weights)

Variables

const SFTtype empty_SFTtype
const SFTVector empty_SFTVector
const PSDVector empty_PSDVector
const MultiSFTVector empty_MultiSFTVector
const MultiPSDVector empty_MultiPSDVector
const MultiNoiseWeights empty_MultiNoiseWeights
const MultiREAL4TimeSeries empty_MultiREAL4TimeSeries
const LIGOTimeGPSVector empty_LIGOTimeGPSVector
const MultiLIGOTimeGPSVector empty_MultiLIGOTimeGPSVector


Detailed Description

Author:
Reinhard Prix, Badri Krishnan Utility functions for handling of SFTtype and SFTVectors

Date:
2005
Id
SFTutils.h,v 1.35 2008/05/29 21:21:24 whelan Exp

The helper functions LALCreateSFTtype(), LALDestroySFTtype(), LALCreateSFTVector() and LALDestroySFTVector() respectively allocate and free SFT-structs and SFT-vectors. Similarly, LALCreateTimestampVector() and LALDestroyTimestampVector() allocate and free a bunch of GPS-timestamps.

Definition in file SFTutils.h.


Define Documentation

#define SFTUTILS_ENULL   1

Definition at line 62 of file SFTutils.h.

#define SFTUTILS_ENONULL   2

Definition at line 63 of file SFTutils.h.

#define SFTUTILS_EMEM   3

Definition at line 64 of file SFTutils.h.

#define SFTUTILS_EINPUT   4

Definition at line 65 of file SFTutils.h.

#define SFTUTILS_EFUNC   6

Definition at line 66 of file SFTutils.h.

#define SFTUTILS_MSGENULL   "Arguments contained an unexpected null pointer"

Definition at line 68 of file SFTutils.h.

#define SFTUTILS_MSGENONULL   "Output pointer is not NULL"

Definition at line 69 of file SFTutils.h.

#define SFTUTILS_MSGEMEM   "Out of memory"

Definition at line 70 of file SFTutils.h.

#define SFTUTILS_MSGEINPUT   "Invald input parameter"

Definition at line 71 of file SFTutils.h.

#define SFTUTILS_MSGEFUNC   "Sub-routine failed"

Definition at line 72 of file SFTutils.h.


Typedef Documentation

typedef COMPLEX8FrequencySeries SFTtype

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

Definition at line 90 of file SFTutils.h.

typedef COMPLEX8FrequencySeriesVector SFTVector

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

Definition at line 94 of file SFTutils.h.

typedef REAL8FrequencySeriesVector PSDVector

Special type for holding a PSD vector (over several SFTs).

Definition at line 97 of file SFTutils.h.

typedef struct tagMultiSFTVector MultiSFTVector

A collection of SFT vectors -- one for each IFO in a multi-IFO search.


Function Documentation

NRCSID ( SFTUTILSH  ,
"$Id: SFTutils.  h,
v 1.35 2008/05/29 21:21:24 whelan Exp $"   
)

void LALCreateSFTtype ( LALStatus status,
SFTtype **  output,
UINT4  numBins 
)

Create one SFT-struct.

Allows for numBins == 0.

Parameters:
output  [out] allocated SFT-struct
numBins  number of frequency-bins

Definition at line 152 of file SFTutils.c.

void LALCreateSFTVector ( LALStatus status,
SFTVector **  sftvect,
UINT4  numSFTs,
UINT4  SFTlen 
)

Create a whole vector of numSFT SFTs with SFTlen frequency-bins.

Parameters:
sftvect  [out] allocated SFT-vector
numSFTs  number of SFTs
SFTlen  number of frequency-bins per SFT

Definition at line 190 of file SFTutils.c.

void LALCreateMultiSFTVector ( LALStatus status,
MultiSFTVector **  out,
UINT4  length,
UINT4Vector numsft 
)

Parameters:
out  [out] multi sft vector created
length  number of sft data points
numsft  number of sfts in each sftvect

Definition at line 264 of file SFTutils.c.

SFTVector* XLALCreateSFTVector ( UINT4  numSFTs,
UINT4  numBins 
)

XLAL function to create an SFTVector of numSFT SFTs with SFTlen frequency-bins.

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

Definition at line 218 of file SFTutils.c.

COMPLEX8Vector* XLALrefineCOMPLEX8Vector ( const COMPLEX8Vector in,
UINT4  refineby,
UINT4  Dterms 
)

Interpolate frequency-series to newLen frequency-bins.

This is using DFT-interpolation (derived from zero-padding).

Definition at line 1455 of file SFTutils.c.

void upsampleMultiSFTVector ( LALStatus ,
MultiSFTVector inout,
UINT4  upsample,
UINT4  Dterms 
)

upsample a given multi-SFTvector by the given (integer) factor, _replacing_ the original SFTs

Parameters:
inout  [in,out]: upsampled multi SFT-vector
upsample  integer factor to upsample by
Dterms  number of terms in Dirichlet kernel [on each side]

Definition at line 1375 of file SFTutils.c.

void upsampleSFTVector ( LALStatus ,
SFTVector inout,
UINT4  upsample,
UINT4  Dterms 
)

Parameters:
inout  [in,out]: upsampled SFT-vector
upsample  integer factor to upsample by
Dterms  number of terms in Dirichlet kernel [on each side]

Definition at line 1408 of file SFTutils.c.

void XLALDestroySFTVector ( SFTVector vect  ) 

XLAL interface to destroy an SFTVector.

Definition at line 368 of file SFTutils.c.

void LALDestroySFTtype ( LALStatus status,
SFTtype **  sft 
)

Destroy an SFT-struct.

Parameters:
sft  SFT-struct to free

Definition at line 316 of file SFTutils.c.

void LALDestroySFTVector ( LALStatus status,
SFTVector **  sftvect 
)

Destroy an SFT-vector.

Parameters:
sftvect  the SFT-vector to free

Definition at line 349 of file SFTutils.c.

void LALDestroyPSDVector ( LALStatus status,
PSDVector **  vect 
)

Destroy a PSD-vector.

Parameters:
vect  the SFT-vector to free

Definition at line 399 of file SFTutils.c.

void LALDestroyMultiSFTVector ( LALStatus status,
MultiSFTVector **  multvect 
)

Destroy a multi SFT-vector.

Parameters:
multvect  the SFT-vector to free

Definition at line 439 of file SFTutils.c.

void LALDestroyMultiPSDVector ( LALStatus status,
MultiPSDVector **  multvect 
)

Destroy a multi PSD-vector.

Parameters:
multvect  the SFT-vector to free

Definition at line 471 of file SFTutils.c.

SFTVector* XLALExtractBandfromSFTs ( const SFTVector sfts,
REAL8  fMin,
REAL8  fMax 
)

Extract a frequency band from an SFTVector, returning a new SFTvector Note: fMin < 0 implies to start from lowest frequency bin, fMax < 0 implies to include up to highest frequency bin.

if fMin, fMax > 0, the corresponding frequency MUST be contained in the input SFT, otherwise an error is returned.

We guarantee that both fMin and fMax will be *contained* in the returned SFT, which means the actual min(f) can be < fMin, and max(f) > fMax is possible.

Definition at line 85 of file SFTutils.c.

void LALCopySFT ( LALStatus status,
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:
dest  [out] copied SFT (needs to be allocated already)
src  input-SFT to be copied

Definition at line 509 of file SFTutils.c.

void LALSubtractSFTVectors ( LALStatus ,
SFTVector **  outVect,
const SFTVector inVect1,
const SFTVector inVect2 
)

Subtract two SFT-vectors and put the results in a new one (which it allocates).

Parameters:
outVect  [out] difference of SFT-vectors
inVect1  input-vector 1
inVect2  input-vector 2

Definition at line 546 of file SFTutils.c.

void LALLinearlyCombineSFTVectors ( LALStatus ,
SFTVector **  outVect,
SFTVector **  inVects,
const COMPLEX16Vector weights,
const CHAR outName 
)

Linearly combine two or more SFT-vectors and put the results in a new one (which it allocates).

Parameters:
outVect  [out] linear combo of SFT-vectors
inVects  array of SFT-vectors
weights  vector of SFT-weights
outName  name for output vector

Definition at line 647 of file SFTutils.c.

void LALAppendSFT2Vector ( LALStatus ,
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 760 of file SFTutils.c.

LIGOTimeGPSVector* XLALCreateTimestampVector ( UINT4  len  ) 

Allocate a LIGOTimeGPSVector.

Definition at line 790 of file SFTutils.c.

void XLALDestroyTimestampVector ( LIGOTimeGPSVector vect  ) 

De-allocate a LIGOTimeGPSVector.

Definition at line 838 of file SFTutils.c.

void LALCreateTimestampVector ( LALStatus status,
LIGOTimeGPSVector **  vect,
UINT4  len 
)

LAL-interface: Allocate a LIGOTimeGPSVector.

Parameters:
vect  [out] allocated timestamp-vector
len  number of elements

Definition at line 813 of file SFTutils.c.

void LALDestroyTimestampVector ( LALStatus status,
LIGOTimeGPSVector **  vect 
)

De-allocate a LIGOTimeGPSVector.

Parameters:
vect  timestamps-vector to be freed

Definition at line 854 of file SFTutils.c.

void LALMakeTimestamps ( LALStatus ,
LIGOTimeGPSVector **  timestamps,
const LIGOTimeGPS  tStart,
REAL8  duration,
REAL8  Tsft 
)

Given a start-time, duration and 'stepsize' tStep, returns a list of timestamps covering this time-stretch.

Parameters:
timestamps  [out] timestamps-vector
tStart  GPS start-time
duration  duration in seconds
Tsft  length of one (SFT) timestretch in seconds

Definition at line 879 of file SFTutils.c.

void LALGetSFTtimestamps ( LALStatus ,
LIGOTimeGPSVector **  timestamps,
const SFTVector sfts 
)

Extract timstamps-vector from the given SFTVector.

Parameters:
timestamps  [out] extracted timestamps
sfts  input SFT-vector

Definition at line 932 of file SFTutils.c.

CHAR* XLALGetChannelPrefix ( const CHAR name  ) 

Extract/construct the unique 2-character "channel prefix" from the given "detector-name", which unfortunately will not always follow any of the official detector-naming conventions given in the Frames-Spec LIGO-T970130-F-E This function therefore sometime has to do some creative guessing:.

NOTE: in case the channel-number can not be deduced from the name, it is set to '1', and a warning will be printed if lalDebugLevel > 0.

NOTE2: the returned string is allocated here!

Definition at line 977 of file SFTutils.c.

LALDetector* XLALGetSiteInfo ( const CHAR name  ) 

Find the site geometry-information 'LALDetector' (mis-nomer!) given a detector-name.

The LALDetector struct is allocated here.

Definition at line 1058 of file SFTutils.c.

void LALComputeNoiseWeights ( LALStatus status,
REAL8Vector weightV,
const SFTVector sftVect,
INT4  blkSize,
UINT4  excludePercentile 
)

Computes weight factors arising from SFTs with different noise floors -- it multiplies an existing weight vector.

Definition at line 1126 of file SFTutils.c.

void LALComputeMultiNoiseWeights ( LALStatus status,
MultiNoiseWeights **  weightsV,
const MultiPSDVector multipsd,
UINT4  blocksRngMed,
UINT4  excludePercentile 
)

Computes weight factors arising from MultiSFTs with different noise floors -- it multiplies an existing weight vector.

Definition at line 1235 of file SFTutils.c.

void LALDestroyMultiNoiseWeights ( LALStatus status,
MultiNoiseWeights **  weights 
)

Definition at line 1337 of file SFTutils.c.


Variable Documentation

const SFTtype empty_SFTtype

Definition at line 59 of file SFTutils.c.

const SFTVector empty_SFTVector

Definition at line 60 of file SFTutils.c.

const PSDVector empty_PSDVector

Definition at line 61 of file SFTutils.c.

const MultiSFTVector empty_MultiSFTVector

Definition at line 62 of file SFTutils.c.

const MultiPSDVector empty_MultiPSDVector

Definition at line 63 of file SFTutils.c.

const MultiNoiseWeights empty_MultiNoiseWeights

Definition at line 64 of file SFTutils.c.

const MultiREAL4TimeSeries empty_MultiREAL4TimeSeries

Definition at line 65 of file SFTutils.c.

const LIGOTimeGPSVector empty_LIGOTimeGPSVector

Definition at line 66 of file SFTutils.c.

const MultiLIGOTimeGPSVector empty_MultiLIGOTimeGPSVector

Definition at line 67 of file SFTutils.c.


Generated on Tue Oct 14 02:33:21 2008 for LAL by  doxygen 1.5.2