hwinject.c File Reference

Multipulsar injection routine. More...

Prototypes
void	syserror (int showerrno, const char *fmt,...)
void	sighandler (int sig)
void	usage (FILE *filep)
int	parseinput (int argc, char **argv)
int	main (int argc, char *argv[])

Detailed Description

Multipulsar injection routine.

Author

Bruce Allen, Peter Shawhan

How it works

(adapted from README.s3inject by Bruce Allen)

There are two executables: lalpulsar_Makefakedata_v4 and lalpulsar_hwinject.

lalpulsar_Makefakedata_v4 generates a continuous stream of data for a single pulsar, using a file called Pulsar.N to get the pulsar's parameters, and command line arguments to get the starting GPS time and detector name. It can write either to files or to stdout.

lalpulsar_hwinject starts up M copies of lalpulsar_Makefakedata_v4, each with a different set of parameters, gathers their output, and adds it together, writing it to stdout.

Both of these executables support a -h command-line argument that will give you a command-line argument summary description. Try it before reading further:

lalpulsar_Makefakedata_v4 -h
lalpulsar_hwinject -h

In this document we assume you will inject 5 pulsar signals total.

Create pulsar parameter files

Create a files called Pulsar.0 to Pulsar.4 containing the parameters of the pulsars that you wish the inject. These files should be "almost" identical at the different sites. They only differ because the Actuation function differs between the sites.

I have included five files - but note that the parameters to be used "for real" still need to be determined. People who should help creating these parameter files include: Riles, S. Anderson, G. Mendell, X. Siemens, G. Woan and M. Landry. These files, once created, should be made read-only, and should only be modified if the instrument Actuation function changes. Be sure to save a copy of them someplace safe.

Note: Each pulsar's parameters are defined at a particular fiducial Solar System Barycenter (SSB) time. In this document, I call this time \( t_S \) . The actual choice of this time is not important, but it should be fixed and invariant. The team defining pulsar parameters may wish to change the value to something that they find convenient.

At the end of this document is a more detailed description of the Pulsar.N parameter files.

Create command-line argument files

Create files called in.0 to in.4. Each file should contain one line. This is used to construct the command-line arguments for lalpulsar_Makefakedata_v4.

The file in.0 should look like this:

lalpulsar_Makefakedata_v4 @Pulsar.0 -I LHO -S 751680013 -b

and the other in.N files should be identical except that they should contain Pulsar.N. The in.N files at LLO should contain LLO rather than LHO.

Verify setup

To test your setup, do the following:

lalpulsar_hwinject -n 5 -G 751680013 -s

The -s option is a show option. It makes lalpulsar_hwinject read the command line files in.N and show you the exact commands it would actually run (preceeded by an integer count of the form [XX]). The -G command line argument is the GPS time at which to start producing data.

Now let's make some output (but just from one pulsar):

lalpulsar_hwinject -n 1 -G 751680013 -T -X 2> infolog  | head -20

The 2> infolog redirects stderr into an information log. Have a look.

The -T option makes lalpulsar_hwinject output in human readable text rather than binary

The -X option makes lalpulsar_hwinject output an X axis as well.

Notice that the first number output by lalpulsar_hwinject is always 1234.5, which is a key to use in checking endian ordering and general sanity.

Now let's go "whole hog":

lalpulsar_hwinject -n 5 -G 751680013 2> infolog  | od -w4 -f | more

This shows you the raw binary output in single column format

CPU and resource use

On my 1 GHz PIII laptop, this job:

lalpulsar_hwinject -n 5 -G 751680013 2> infolog  > /dev/null

runs at five time real time speed, has a starup latency of around 1 second, and uses 11 MB of memory per pulsar (55 MB total).

Defining Pulsar.* files

Here is a typical file:

refTime          = 751680013            ## pulsar reference time in SSB frame
aPlus            = 4.996981857609109e-26        ## plus-polarization signal amplitude
aCross           = 4.868177666869495e-26        ## cross-polarization signal amplitude
psi              = 0.770087086          ## polarization angle psi (radians)
phi0             = 2.66                 ## phase at reference time
Freq             = 265.5771052          ## GW frequency at reference time
Delta            = -0.981180225         ## declination (radians)
Alpha            = 1.248816734          ## right ascension (radians)
f1dot            = -4.15E-12            ## 1st frequency derivative
f2dot            = 0.0                  ## 2nd frequency derivative
f3dot            = 0.0                  ## 3rd frequency derivative

This structure contains gravitational wave source position (in Equatorial coordinates), and orientation angle. Equatorial coordinates are the standard sky-fixed coordinate system. The z-axis is defined as for geographic coordinates, above; the plane orthogonal to this passing through the Earth's centre is called the equator. The x-axis is defined to be the direction, as viewed from the centre of the Earth, where the Sun appears to cross the equator moving north in spring. This is called the vernal equinox, and is shown in Fig. 16.6. In this coordinate system, the latitude coordinate is called the declination \( \delta \) and the longitude coordinate is called the right ascension \( \alpha \) . (See also Header SkyCoordinates.h.)

aPlus and aCross set the amplitude of the two polarizations. This is where you can insert an amplitude calibration factor.

The only other value to note is phi0. This is where you can insert a phase calibration offset, if needed. Note: phi0 is not scaled by a factor of two. In other words, if you set phi=PI, you'll find the output inverted. If you set phi=PI/2, you'll see the output phase retarted. In other words, the peak of a particular cycle occurs one quarter of a cycle earlier.

To see this clearly, just do something like:

lalpulsar_hwinject -n 1 -G 751680013 -T | head -100 > junk1

Then change the value of phi0 in Pulsar.0, and do it again:

lalpulsar_hwinject -n 1 -G 751680013 -T | head -100 > junk2

Comparing junk1 and junk2 should make the sign convention of phi0 very clear.

Calibration lines

The lalpulsar_hwinject executable can inject up to three calibration lines. Here they are denoted by L==low, M==medium and H==high to indicate the frequency. They are defined by:

DARM = A_L sin(2 pi f_L (GPS-GPS_0)) +
       A_M sin(2 pi f_M (GPS-GPS_0)) +
       A_H sin(2 pi f_H (GPS-GPS_0))

where GPS_0 = 751680013. In the code, the frequencies are hardwired to:

f_L = 52.296875 = 52+1/4+1/32+1/64 Hz
f_M = 166.6875  = 166+1/2+1/8+1/16 Hz
f_H = 927.6875  = 927+1/2+1/8+1/16 Hz

These can be changed, but (1) MUST be exactly represented as IEEE754 floats (not doubles) and (2) MUST be positive.

The amplitudes of the injected lines are defined by three arguments (-L, -M and -H) to lalpulsar_hwinject which set the amplitudes of the three lines. The arguments are, for example:

lalpulsar_hwinject -n 0 -T  -G 12345678 -L 17.76 | more

will inject a calibration line at low frequency with an amplitude of 17.76. You can include any combination of -L, -M and -H. If one of these arguments is not present, then its assumed amplitude is zero.

You can inject five pulsars plus three calibration lines with:

lalpulsar_hwinject -n 5 -L 0.003 -M 0.0006 -H 0.8 -G 751680013 -T | more

Note: a good check that the calibration line injection code works correctly is to compare the output with GPS times offset by integer multiples of 64 seconds. Since the smallest fractional part of the frequencies above is 1/64 Hz, the calibration signal should repeat exactly every 64 seconds.

The -p option to lalpulsar_hwinject prints out the built-in calibration line frequencies.

Comments

I've tried to make lalpulsar_hwinject fairly robust. In particular, it catches SIGCHLD and if a child has been terminated (rather than just being stopped) it tries to say why. System related errors print errno and it's interpretation. Most error messages should come with a PID to help figure out which process is going bad.

Note that under Solaris, the pid returned with these error messages appears to be the PID of the shell (started by popen) under which the child was started. This is usually one less than the PID of the associated lalpulsar_Makefakedata_v4 process.

If you send SIGUSR1 to lalpulsar_hwinject:

kill -SIGUSR1 PID

then it will report to stderr the amount of simulated data that it has made (days/hours/minutes/seconds). Be careful not to send the signal to the entire process group, since the children don't catch this signal and will respond to it by terminating!

The lalpulsar_hwinject program can be used to inject signals from sources other than pulsars. To use it in this way, your code must do the following:

1. write data to stdout, errors to stderr
2. take a command line argument which is GPS seconds and start its output at that time: -G secs
3. be able to run faster than real time under Solaris. It should produce data at a sample rate of 16384 Hz in blocks of an integer number of seconds (called S below).
4. have the following internal structure. Here S is the number of seconds, for example, 30, that your code uses internally to compute the next block of output.

   main() {
    
       int length=S*16384;
    
       float magic=1234.5;
       fwrite(&magic,  sizeof(float), 1, stdout);
    
       while (1) {
    
           // compute next output data, may be time-consuming ...
    
           fwrite(&data, sizeof(float), length, stdout);
    
           fflush(stdout);
       }
   }

   The fflush(stdout) is very important. It ensures that your program will have time to compute its next block of data before it is needed by lalpulsar_hwinject.
5. create an in.N file for your executable. See description above.

Changelog

• Multipulsar injection routine, written for E10/S3 by Bruce Allen, 10/2003.
• Calls to Signal Injection Library added by Peter Shawhan.
• 2005/02: Duncan Brown renamed variable to avoid Condor conflict.
• 2005/02: Reinhard Prix removed the actuation scaling options.
• 28 May 2009: renamed this code from 's3inject' to 'psinject' in lalsuite-GIT
• 19 March - 10 August: Bruce Allen, added ability to output FRAME format files for VIRGO real-time hardware injections.
• 2022/07: Karl Wette added test script, ported FRAME writing to LALFrame, add '–fmin' and '–Band' options to command line, moved code to LALPulsar, renamed lalpulsar_hwinject, RPM packaging

Definition in file hwinject.c.

Go to the source code of this file.

Macros
#define	_GNU_SOURCE   /* for SA_RESTART */
#define	MAXPULSARS   64
#define	BLOCKSIZE   16384
#define	MAXLINE   1024

Variables
volatile int	shutdown_pulsar_injection = 0
int	npulsars = 0
float	data [BLOCKSIZE]
float	total [BLOCKSIZE]
float	testval = 1234.5
char *	directory
char *	channel = NULL
int	gpstime = 0
char *	programname
int	show = 0
int	do_axis = 0
int	do_text = 0
int	write_frames = 0
long long	count = 0
long	blocks = 0
const char *	ifo_name = NULL
const char *	actuation = NULL
int	sampling_rate = 16384
double	starttime_offset_eff = 0
int	bufflen [MAXPULSARS]
int	readfrombuff [MAXPULSARS]
float *	buffs [MAXPULSARS]
double	calamp [3] = {0.0, 0.0, 0.0}
double	calfreq [3]
int	tfiducial = 751680013
FILE *	fp [MAXPULSARS]

Macro Definition Documentation

_GNU_SOURCE

#define _GNU_SOURCE   /* for SA_RESTART */

Definition at line 313 of file hwinject.c.

MAXPULSARS

#define MAXPULSARS   64

Definition at line 353 of file hwinject.c.

BLOCKSIZE

#define BLOCKSIZE   16384

Definition at line 355 of file hwinject.c.

MAXLINE

#define MAXLINE   1024

Definition at line 736 of file hwinject.c.

Function Documentation

syserror()

void syserror	(	int	showerrno,
		const char *	fmt,
			...
	)

Definition at line 464 of file hwinject.c.

sighandler()

void sighandler

(

int

sig

)

Definition at line 415 of file hwinject.c.

usage()

void usage

(

FILE *

filep

)

Definition at line 485 of file hwinject.c.

parseinput()

int parseinput	(	int	argc,
		char **	argv
	)

Definition at line 524 of file hwinject.c.

main()

int main	(	int	argc,
		char *	argv[]
	)

Definition at line 737 of file hwinject.c.

Variable Documentation

shutdown_pulsar_injection

volatile int shutdown_pulsar_injection = 0

Definition at line 358 of file hwinject.c.

npulsars

int npulsars = 0

Definition at line 359 of file hwinject.c.

data

float data[BLOCKSIZE]

Definition at line 360 of file hwinject.c.

total

float total[BLOCKSIZE]

Definition at line 361 of file hwinject.c.

testval

float testval = 1234.5

Definition at line 362 of file hwinject.c.

directory

char* directory

Definition at line 363 of file hwinject.c.

channel

char* channel = NULL

Definition at line 364 of file hwinject.c.

gpstime

int gpstime = 0

Definition at line 365 of file hwinject.c.

programname

char* programname

Definition at line 366 of file hwinject.c.

show

int show = 0

Definition at line 367 of file hwinject.c.

do_axis

int do_axis = 0

Definition at line 368 of file hwinject.c.

do_text

int do_text = 0

Definition at line 369 of file hwinject.c.

write_frames

int write_frames = 0

Definition at line 370 of file hwinject.c.

count

long long count = 0

Definition at line 371 of file hwinject.c.

blocks

long blocks = 0

Definition at line 372 of file hwinject.c.

ifo_name

const char* ifo_name = NULL

Definition at line 373 of file hwinject.c.

actuation

const char* actuation = NULL

Definition at line 374 of file hwinject.c.

sampling_rate

int sampling_rate = 16384

Definition at line 375 of file hwinject.c.

starttime_offset_eff

double starttime_offset_eff = 0

Definition at line 376 of file hwinject.c.

bufflen

int bufflen[MAXPULSARS]

Definition at line 382 of file hwinject.c.

readfrombuff

int readfrombuff[MAXPULSARS]

Definition at line 383 of file hwinject.c.

buffs

float* buffs[MAXPULSARS]

Definition at line 384 of file hwinject.c.

calamp

double calamp[3] = {0.0, 0.0, 0.0}

Definition at line 386 of file hwinject.c.

calfreq

double calfreq[3]

Initial value:

= {
  52.296875,         
  166.6875,          
  927.6875           
}

Definition at line 395 of file hwinject.c.

tfiducial

int tfiducial = 751680013

Definition at line 404 of file hwinject.c.

fp

FILE* fp[MAXPULSARS]

Definition at line 406 of file hwinject.c.