Function: chirp_filters()

0 int chirp_filters(float m1, float m2, float spin1, float spin2, int n_phaseterms, float *phaseterms, float Initial_Freq, float Max_Freq_Rqst, float *Max_Freq_Actual, float Sample_Time, float **ptrptrCos, float **ptrptrSin, int *steps_alloc, int *steps_filld, int err_cd_sprs)
This function is a basic stripped-down chirp generator. It computes two - nearly orthogonal - chirp waveforms for an inspiraling binary. The two chirps differ in phase by $\pi/2$ radians. The chirp values are given by Eqs.() and (). Just as the phase and frequency calculator phase_frequency() returns an integer number which describes how the chirp calculation was terminated, this routine does also.

The arguments are:

m1: Input. The mass of body-1 in solar masses.

m2: Input. The mass of body-2 in solar masses.

spin1: Input. The dimensionless spin parameter of body-1. See section on spin effects.

spin2: Input. The dimensionless spin parameter of body-2. See section on spin effects.

n_phaseterms: Input. Integer describing the number of terms implemented in the phase and frequency calculations. In the present implementation this should be set to $5$.

phaseterms: Input. The array phase_terms[0..n_phaseterms-1] describes which terms will be included in the phase frequency calculations. Setting phase_terms[i]=0 nullifys the term. Setting phase_terms[i]=1 includes the term. This allows for easy run-time nullification of any term in the phase and frequency evolution, e.g. setting phase_terms[4]=0 eliminates the second post-Newtonian terms from the calculation.

Initial_Freq: Input. The starting orbital frequency of the chirp in Hz.

Max_Freq_Rqst: Input. The requested orbital frequency where the chirp will stop. However, the actual calculation may not proceed all the way to this orbital frequency.

Max_Freq_Actual: Output. The floating number *Max_Freq_Actual is the orbital frequency in Hz where the chirp actually terminated.

Sample_Time: Input. The time interval between points in seconds.

ptrptrCos: Input/Output. The chirp corresponding to Eq.() is stored in
[4]*ptrptrCos[0..steps_filld-1]. Input in the sense that much of the internal logic of chirp_filters() depends on how the pointers *ptrptrCos (and *ptrptrSin below) are set. If either is set to NULL memory allocation will be performed inside chirp_filters(). If both are not NULL then it is assumed the calling routine has allocated the memory before calling chirp_filters().

ptrptrSin: Input/Output. Similar to ptrptrCos above. The chirp corresponding to Eq.() is stored in *ptrptrSin[0..steps_filld-1].

steps_alloc: Input/Output. The integer *steps_alloc is the number of floating point entries allocated for storing the two chirps, i.e. the number of valid subscripts in the arrays **ptrptrCos and **ptrptrSin. This integer should be set in the calling routine if memory is allocated there, or it will be set inside chirp_filters() if memory is to be allocated there. If both of the pointers *ptrptrCos and *ptrptrSin are not NULL then chirp_filters() understands that the calling routine is taking responsibility for allocating the memory for the chirp, and the calling routine must set *steps_alloc accordingly. In this case chirp_filters() will fill up the arrays **ptrptrCos and **ptrptrSin until the memory is full ( i.e fill them with *steps_alloc of floats) or until the chirp terminates, whichever is less.

steps_filld: Output. The integer *steps_filld is the number of time steps (sample values) actually computed for this evolution. It is less than or equal to *steps_alloc.

clscnc_time: Output. The float *clscnc_time is the time to coalescence in seconds, measured from the instant when the orbital frequency is Initial_Freq given by $t_c$ in Eqs.() and ().

err_cd_sprs: Input. Error code suppression. This integer specifies the level of disaster encountered in the computation of the chirp for which the user will be explicitly warned with a printed message. Set to 0: prints all the termination messages. Set to 4000: suppresses all but a few messages which are harbingers of true disaster. The termination messages are numbered from 0 to 3999 loosely in accordance with their severity (the larger numbers corresponding to more severe warnings). Any message with a number less than err_cd_sprs will not be printed. A termination code of 0 means the chirp calculation was executed as requested. A termination code in the 1000's means the chirp was terminated early because the post-Newtonian approximation was deemed no longer valid. A termination code in the 2000's generally indicates some problem with memory allocation. A termination code in the 3000's generally indicates a serious logic fault. Many of these ``3000'' errors result in the termination of the program. If you get an error message number it is easy to find the portion of source code where the fault occurred; just do a character string search on the four digit number.

Authors: Alan Wiseman, agw@tapir.caltech.edu and Bruce Allen, ballen@dirac.phys.uwm.edu

Comments: None.