Function:

This function computes the

`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 .`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 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 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 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.