Function: phase_frequency()

0 int phase_frequency(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 **phase, float **frequency, int *steps_alloc, int *steps_filld, int err_cd_sprs)
This function computes the orbital phase and orbital frequency evolution of an inspiraling binary. It returns an integer termination code indicating how and why the chirp calculation terminated. This routine is the engine that powers the other chirp generation routines. 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 post-Newtonian (pN) approximation 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] specifies which pN approximation terms will be included in the phase frequency calculations. Setting phase_terms[i]=0.0 nullifys the term. Setting phase_terms[i]=1.0 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.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. This is discussed at length below.

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 successive samples, in seconds.

phase: Input/Output. The phase ephemeris $\Omega$ in radians is stored in the array *phase[0..steps_filld-1]. Input in the sense that much of the internal logic of phase_frequency() depends on how the pointers *phase (and *frequency below) are set. If either is set to NULL memory allocation will be performed inside phase_frequency(). If both are not NULL then it is assumed the calling routine has allocated the memory before calling phase_frequency().

frequency: Input/Output. Similar to phase above. The frequency ephemeris $f=d\Omega/dt$ is stored in the array *frequency[0..steps_filld-1].

steps_alloc: Input/Output. The integer *steps_alloc is the number of floating point entries allocated for storing the phase and frequency evolution, i.e. the length of **phase and **frequency. This integer should be set in the calling routine if memory is allocated there, or it will be set inside phase_frequency() if memory is to be allocated there. If both of the pointers *phase and *frequency are not NULL then phase_frequency() 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 phase_frequency() will fill up the arrays **phase and **frequency 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 integer number of time steps 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 determines at what level of disaster encountered in the computation of the chirp the user will be explicitly warned about 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 complete 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 routine. 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.

This phase and frequency generator has a number of very specialized features which will be discussed later. However, before we proceed further, we show a simple example of how phase_frequency() can be used.

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

Comments: This function will need to be extended when results of order 2.5 and 3 post-Newtonian calculations have been reported and published.