Skip to content

Reverberation Mapping

Jump to bottom
Knox S. Long edited this page Jan 12, 2021 · 9 revisions

This is superceded by information on ReadTheDocs

Python's new reverberation mapping option is set up to produce a .delay_dump output file containing details of each scattering photon, that can be post-processed by the separate bindata utility to produce velocity-resolved transfer function plots. It calculates delays by tracking photon paths through the wind, and converting the distance into a delay relative to photons travelling directly from the central source to each observer.

Running Python in RV mode

There are 3 optional RV modes included in Python. They are

  • Photon-based reverberation mapping: Delay is calculated from distance travelled on a photon-by-photon basis. Photons generated in the wind are assumed to correlate with photons travelling directly from the central source, and have a starting 'path length' of the direct distance to the central source.
  • Wind-based reverberation mapping: Once a sufficient proportion of the cells have converged (geo.reverb_fraction_converged, 0.9 by default), in all following cycles of the ionisation phase the distribution of paths of photons undergoing continuum absorption in each wind cell is recorded and binned. During the spectral phase, the paths of photons generated in the wind are drawn from this distribution, with the probability of a given bin weighted by the total flux in it, and the position within a bin randomly generated.
  • Macro-atom based reverberation mapping: As with the wind-model, this records the distribution of paths of photons undergoing continuum absorption in each wind cell. It also records the distribution of paths of photons that excite macro-atoms to the upper levels of a range of specified macro-atom lines (i.e. for Ha, activations of Hydrogen matom level 3). When a photon is released in one of the specified macro-atom lines, it draws its initial path from this distribution. In most cases, this gives very similar results to the wind-based mode.

The resulting output file may be large for large runs- for ~1e8 photons, it will be on the order of GB. It is encouraged to make use of the reverb.filter_lines setting to limit file size.

Reverberation now only runs in extract mode. Since we only ever run in extract mode anyway, this isn't much of a problem.

PARAMETERS

The full list of parameters and options follows. It is shown hierarchically- everything at the top level must be included, if an option is selected all mandatory parameters it enables are shown under it.

  • reverb.type int:
    • 0 Off
    • 1 Photon
    • 2 Wind
      • reverb.path_bins: Int. The path distributions in each wind cell have this many bins. Should be on the order of 1000-10000. Higher values may lead to memory issues, lower values result in a characteristic 'striping' effect.
      • reverb.visualisation int: A range of options for visualising reverberation data are available.
        • 0 Off
        • 1 VTK: Outputs to a .vtk 3d visualisation file, openable with software like VisIt or Paraview. This shows the average flux and typical paths to the observers for each cell within the model.
          • reverb.angle_bins int: The cylindrically-symmetric wind is transformed into a 3d model with this angular resolution. 100 is a reasonable value.
        • 2 Dump cells: Outputs a breakdown of the wind path distributions within a list of cells to .csv files. These files have a header with the cell midpoint, and contain the contributions to each path bin from disk, wind and central source photons.
          • reverb.dump_cells int: Number of cells to dump.
          • reverb.dump_cell float:float: X and Z position of each cell to dump, i.e. 1e15:7.1e14
        • 3 Both: Output both to .vtk and to .csv. Requires all the parameters from options 1 and 2.
    • 3 Matom
      • reverb.path_bins int: As above.
      • reverb.visualisation int: As above. If the dump cells mode is chosen, each tracked level distribution in the cell will also be output, again broken down by origin.
      • reverb.matom_lines int: Number of macro-atom lines to track.
      • reverb.matom_line int:int:int:int: Element:Ion:Upper level:Lower level of the transitions to track.
  • reverb.disk_type int: Controls how the starting paths for photons generated in the disk are chosen.
    • 0 Correlated: Disk photons are generated with paths equal to their distance from the origin. This assumes that disk emission is correlated with the central source. Use this unless there is a very good reason not to.
    • 1 Uncorrelated: Disk photons are generated with paths of 0. This assumes disk emission is entirely uncorrelated with the central source.
    • 2 Ignored: Disk photons are generated as option 0, correlated, but are ignored when generating wind path distributions.
      • WIND OR MATOM MODE ONLY
  • reverb.filter_lines int: Whether or not to shrink the size of the output .delay_dump file by excluding some photons.
    • 0 Off
    • -1 Filter continuum: Does not include continuum photons (last scattered resonance of '-1') in the output.delay_dump file. If you are only interested in specific lines, this dramatically shrinks the output file.
    • >0 Filter lines: Include only photons from the lines listed in the output .delay_dump file. Followed by that number of reverb.filter_line entries as below. Automatically includes entries from reverb.matom_lines if present.
      • reverb.filter_line: Int. Uses the Python internal line number.
      • TO DO: Switch to use either frequency or Element:Ion:Upper:Lower notation.

POSTPROCESSING

The output .delay_dump data file is ASCII column data, with titles included in the file. A Python (no relation) library, tfpy, has been produced to make easy use of it- and can be found on git here.

EXAMPLES

Photon Run

A simple reverb run. Photon starting paths are all set to be the distance from the origin, whether they are created at the central source or in the disk or wind. This ignores the effects of multiple scattering on wind emission.

reverb.type 1
reverb.disk_type 1
reverb.filter_lines 0

Wind Run

A more detailed reverb run. The paths of photons being absorbed in the wind are taken, put into 1000 bins per cell, and used to generate the starting paths of wind photons. Disk photons are started with a path of 0, assuming no correlation with the wind. In practise, this will cause them to drop out of the transfer function.

The code will output a .delay_dump file containing only photons that last scattered off of an emission line or were emitted in an emission line and not continuum scattered before reaching the observer. It will also output a .vtk file with the average path in each wind cell recorded, allowing for the creation of iso-average-delay plots.

reverb.type 2
reverb.disk_type 2
reverb.visualisation 2
reverb.angle_bins 100
reverb.path_bins 1000
reverb.filter_lines -1

Matom Run

A much more detailed reverb run. The paths of photons being absorbed in the wind are taken, put into 1000 bins per cell, and used to generate the starting paths of wind photons. The paths of photons activating the hydrogen N=4 and N=3 levels are also taken, and used to generate the starting paths of Ha and Hb photons. Disk photons are generated with a correlated starting path, but do not contribute to the path distributions.

The code will output a .delay_dump file containing only photons that last scattered off or were emitted in the Hα, Hβ and C IV lines (NB: Line indexes vary with your choice of atomic data! This is purely an example). It will also produce files with the path distributions compiled for two cells at the specified locations, for continuum photons and for both lines. For each, it will also break the path distributions down into contributions from disk, wind and continuum photons- so it is possible to tell if, for example, Hα is dominated by photons emitted nearby in the wind. In this particular case, due to disk_type 3 the disk entries will always be 0.

reverb.type 3
reverb.matom_lines 2
reverb.matom_line 1:1:3:2
reverb.matom_line 1:1:4:2
reverb.disk_type 3
reverb.visualisation 1
reverb.dump_cells 2
reverb.dump_cell 1e15:1.4e14
reverb.dump_cell 1.5e15:1.1e14
reverb.path_bins 1000
reverb.filter_lines 1
reverb.filter_line 381

Worked Examples

To see a worked example, all the way from .pf file to output, please check this page.

Clone this wiki locally