Home

DESCRIPTION

Bindata is a utility designed to manipulate the .delay_dump files output by PYTHON in reverberation mode.

DISCLAIMER

Why is this in Fortran? Because I thought it would just be a small little tool and wanted to keep in-practise with using Fortran. By the time it was apparent the files would be a lot larger and the work a lot more intensive than the setup was designed for, it was too late to switch. I've started a rewrite of it in Python (bindata.py in this repository) but want to integrate that with a switch from ASCII to SQL for the delay dump files.

INPUTS

Bindata takes .delay_dump files These files record every photon that contributes to each spectrum in the run, along with some data on its properties:

1. Frequency (Hz)
2. Wavelength (A)
3. Weight
4. Last scatter position (X, cm)
5. Last scatter position (Y, cm)
6. Last scatter position (Z, cm)
7. Number of resonant and continuum scatters
8. Number of resonant scatters
9. Lag behind the continuum (days)
10. ??? [may be removed]
11. Spectrum
12. Photon origin
13. Last scattering line (-1 is continuum) Bindata processes these files into transfer function plots.

ARGUMENTS

File arguments

By default, bindata will take the first argument-less parameter as the input file, and output using the same root and a variety of suffixes as required. This behaviour can be over-ridden.

• -i [STRING]: File to input. No suffix.
• -o [STRING]: File root to output to. No suffix.

Filter arguments

By default, transfer functions will include all photons from observer index 0 that have scattered at least once. If no delay range is provided, the range is set to .9-3.25x the maximum wind radius (see optional arguments).

• -s INT INT: Minimum and maximum total scatters.
• -sc INT INT: Minimum and maximum continuum scatters.
• -v FLOAT FLOAT: Minimum and maximum wavelengths to include (in A).
• -p FLOAT FLOAT: Minimum and maximum delays to plot (in days).
• -obs INT [INT] [...]: List of observers to include. Each will produce its own set of outputs with a .INT. affix indicating the observer.
• -l INT [INT] [...]: List of lines to include. May be arbitrarily long. Uses line indexes as PYTHON. WARNING: These will differ based on the choice of input data.
• -o INT [INT] [...]: List of photon origins to include. May be arbitrarily long. Uses origin indexes as PYTHON.
  • 2 = Disk
  • 3 = Wind
  • 4 = AGN

Optional arguments

By default, the data is binned in a 100x100 grid in wavelength-delay space. If the minimum or maximum wind radius is required by another argument or default setting, it is taken from the .pf file corresponding to the file root.

• -d INT INT: Wavelength and delay bin numbers.
• -m: Messy mode, do not delete intermediate files.
• -r FLOAT FLOAT: Minimum and maximum radius of the wind. Used in
  • Default delay mode (no -p provided)
  • Reweighting mode

Virial mass estimate mode arguments

It is possible to make a virial mass estimate for a system from the width and delay of a given line. The width is calculated from the line FWHM. The estimate is made using an f-factor of 5 and the centroid of the delay for that line. Upper and lower errors are given using f-factors of 3 and 7, and the 2 sigma upper and lower delays for the line.

• -lw FLOAT: Calculate a virial mass estimate for a line of a given wavelength.
  • Requires -l to specify the line
• -rms: RMS mode. Calculate the line width from the RMS error, not the FWHM.

Reweighting mode arguments

In order to calibrate pseudo-disk PYTHON models to L_line = k*r^a relationships, it is possible to reweight all photons scattering from the disk at a given radius to ensure they obey this relationship. By default, if reweight mode is used this reweighting is done in 100 linearly-spaced radial bins.

• -rwp INT: Reweight mode. Provides the power a in the k*r^a relationship.
• -rwb INT: Number of bins to use when reweighting.
• -bl: ?????
• -bg: ?????

Centroid delay mode arguments

By default, bindata plots the transfer function of the photons, showing the response in each wavelength-delay bin. Centroid delay mode plots instead the centroid of the delay distribution in each wavelength bin, with the 2 sigma upper and lower bounds (i.e. the delays by which either 5% or 95% of the photons have arrived).

• -x: Overlay a centroid plot on a standard transfer function plot.
• -xo: Plot only the centroid delays.

Visualisation arguments

By default, the transfer function is shown in wavelength-delay space with a logarithmic color scale for response, spanning 4 orders of magnitude. It is normalised to the highest response.

• -c FLOAT FLOAT: Minimum and maximum response color scale values.
• -vel: Velocity mode, plot in velocity-delay space.
  • Requires -l to specify the line
  • Requires -lw to specify the line wavelength
• -nt: No ticks mode, remove tics from the plot.
• -nl: No log mode, use a linear colour key for the TF intensity.
• -nk: No key mode, do not display the colour key.

EXAMPLES OF USE

bindata -l 381 -lw 1550 -vel -v 1400 1600 -p 0 30 file_in -obs 3 -o file_out

Produces a transfer function in velocity-delay space for photons in spectrum 3 from file_in.delay_dump in the C-IV line, from 0-30 days, and writes it to file_out.eps. Will also produce an estimate of the virial mass from this line.

bindata -v 6000 7000 -rwp 1.5 -rwb 50 -r 1e14 1e16 -bl -s 1 1 -sc 0 0 -i file_in -r 1e14 1e16

Produce a transfer function in wavelength-delay space for all photons in spectrum 0 that have resonantly scattered once in the range 6000-7000 A, These photons are eweighted as if emitted from a disk with radius 1e14-1e16cm emission proportional to r^(3/2), via 50 logarithmic bins. The transfer function delay range will cover 0 to (3.251e16C)/(seconds per day)

bindata -v 4200 4800 -xo -d 20 200 -obs 0 3 -p 0 5 -i file_in

Produce a centroid plot binned in 20 wavelength bins from 4200-4800 A, from 0-5 days, for observers 0,1,2 and 3. These will be output to files file_in.[0-3].eps.

• TO DO: CONVERT -v to work in velocity mode.