Function:

`void whiten(char *whiten_file, int n, float delta_f,
double *whiten_out)`

This function calculates the real and imaginary parts of the spectrum
of the whitening filter of a detector at a given set of
discrete frequency values, using information contained in a data file.

The arguments of `whiten()` are:

`whiten_file:`Input. A character string that specifies the name of a data file containing information about the spectrum of the whitening filter of a detector. Like the`detectors.dat`and noise power spectrum data files described in Secs. and , the whitening filter data file should reside in the directory pointed to by the`GRASP_PARAMETERS`environment variable (which you may set as you wish). If you want to use the whitening filter data files distributed with GRASP, use a command like:`setenv GRASP_PARAMETERS /usr/local/GRASP/parameters`

to point to the directory containing these files. If you want to use your own whitening filter data files, then simply set the`GRASP_PARAMETERS`environment variable to point to the directory containing these files. Note, however, that if a program also needs to access either detector site information or noise power spectrum data, then all of the files containing this information should reside in the*same*directory.`n`: Input. The number of discrete frequency values at which the real and imaginary parts of the spectrum of the whitening filter are to be evaluated.`delta_f:`Input. The spacing (in Hz) between two adjacent discrete frequency values: .`whiten_out:`Output.`whiten_out[0..2*n-1]`is an array of double precision variables containing the values of the real and imaginary parts of the spectrum of the whitening filter. These variables have units (or ), which are inverse to the units of the square root of the noise power spectrum .`whiten_out[2*i]`and`whiten_out[2*i+1]`contain, respectively, the values of the real and imaginary parts of evaluated at the discrete frequency , where .

The input data file specified by `whiten_file` contains information
about the spectrum of the whitening filter of a detector.
The data contained in this file is formatted as follows:
Any line beginning with a `#` is regarded as a comment.
All other lines are assumed to consist of three floating point numbers,
each separated by white space.
The first floating point number is a frequency (in Hz).
The second and third floating point numbers are, respectively, the real
and imaginary parts of the spectrum , evaluated at .
These last two numbers have units of
(or
).
This is because the whitening filter is, effectively, the inverse of
the amplitude of the noise power spectrum.

Since the frequency values contained in the input data file need not
agree with the desired frequencies , `whiten()`
must determine the desired values of the real and imaginary parts of the
spectrum of the whitening filter by doing an
interpolation/extrapolation on the input data.
Similar to `noise_power()` (see Sec. ),
`whiten()` performs a cubic spline interpolation,
using the `spline()` and `splint()` routines from
*Numerical Recipes in C.*
Like `noise_power()`, `whiten()` assumes that the length of
the input data is , and it uses boundary conditions for a
natural spline.
Unlike `noise_power()`, `whiten()` does not
have to square the output of the `splint()`
routine, since the data contained in the input file and the desired
output data both have the same form (i.e., both involve just the real
and imaginary parts of ).

- Authors: Bruce Allen, ballen@dirac.phys.uwm.edu, and Joseph Romano, romano@csd.uwm.edu
- Comments:
In order for the cubic spline interpolation routines to
yield approximations to that are not contaminated by spurious
DC or low frequency (e.g., approximately 1 Hz) components, it is important
that the input data file specified by
`whiten_file`contain information about the whitening filter down to, and including, zero Hz. This information can be added in ``by hand,'' for example, if the experimental data for the spectrum of the whitening filter only goes down to 1 Hz. In this case, setting the values of at Hz equal to their 1 Hz values seems to be sufficient. (See Sec. for a similar comment regarding`noise_power()`.)Also, for the initial and advanced LIGO detector noise models, the spectra of the whitening filters contained in the input data files were constructed by simply inverting the square roots of the corresponding noise power spectra . The spectra of the whitening filters thus constructed are

*real*. Although this method of obtaining information about the spectra of the whitening filters is fine for simulation purposes, the data contained in the actual whitening filter input data files will be obtained*independently*from that contained in the noise power spectra data files, and the spectra will in general be complex. The function`whiten()`described above--and all other stochastic background routines--allow for this more general form of whitening filter data.