trident.ray_generator.make_compound_ray

trident.ray_generator.make_compound_ray(parameter_filename, simulation_type, near_redshift, far_redshift, lines=None, ftype='gas', fields=None, solution_filename=None, data_filename=None, use_minimum_datasets=True, max_box_fraction=1.0, deltaz_min=0.0, minimum_coherent_box_fraction=0.0, find_outputs=False, seed=None, setup_function=None, load_kwargs=None, line_database=None, ionization_table=None, field_parameters=None)

Create a yt LightRay object for multiple consecutive datasets (eg IGM). This is a wrapper function around yt’s LightRay interface to reduce some of the complexity there.

Note

The compound ray functionality has only been implemented for the Enzo and Gadget/Gizmo codes. If you would like to help us implement this functionality for your simulation code, please contact us about this on the mailing list.

A compound ray is a series of straight lines passing through multiple consecutive outputs from a single cosmological simulation to approximate a continuous line of sight to high redshift.

Because a single continuous ray traversing a simulated volume can only cover a small range in redshift space (e.g. 100 Mpc only covers the redshift range from z=0 to z=0.023), the compound ray passes rays through multiple consecutive outputs from the same simulation to approximate the path of a single line of sight to high redshift. By probing all of the foreground material out to any given redshift, the compound ray is appropriate for studies of the intergalactic medium and circumgalactic medium.

By default, it selects a random starting location and trajectory in each dataset it traverses, to assure that the same cosmological structures are not being probed multiple times from the same direction. In doing this, the ray becomes discontinuous across each dataset.

The compound ray requires the parameter_filename of the simulation run. This is not the dataset filename from a single output, but the parameter file that was used to run the simulation itself. It is in this parameter file that the output frequency, simulation volume, and cosmological parameters are described to assure full redshift coverage can be achieved for a compound ray. It also requires the simulation_type of the simulation.

Unlike the simple ray, which is specified by its start and end positions in the dataset volume, the compound ray requires the near_redshift and far_redshift to determine which datasets to use to get full coverage in redshift space as the ray propagates from near_redshift to far_redshift.

Like the simple ray produced by make_simple_ray, each gas cell intersected by the LightRay is sampled for the desired fields and stored. Several additional fields are created and stored including dl to represent the path length in space for each element in the ray, v_los to represent the line of sight velocity along the ray, and redshift, redshift_dopp, and redshift_eff to represent the cosmological redshift, doppler redshift and effective redshift (combined doppler and cosmological) for each element of the ray.

The :lines: keyword can be set to automatically add all fields to the resulting ray necessary for later use with the SpectrumGenerator class.

Parameters

Parameter_filename

string

The simulation parameter file not the dataset filename

Simulation_type

string

The simulation type of the parameter file. At present, this functionality only works with “Enzo” and “Gadget” yt frontends.

Near_redshift, far_redshift

floats

The near and far redshift bounds of the LightRay through the simulation datasets.

Lines

list of strings, optional

List of strings that determine which fields will be added to the ray to support line deposition to an absorption line spectrum. List can include things like “C”, “O VI”, or “Mg II ####”, where #### would be the integer wavelength value of the desired line. If set to ‘all’, includes all possible ions from H to Zn. :lines: can be used in conjunction with :fields: as they will not override each other. Default: None

Ftype

string, optional

This is now deprecated and unnecessary. Default: “gas”

Fields

list of strings, optional

The list of which fields to store in the output LightRay. See :lines: keyword for additional functionality that will add fields necessary for creating absorption line spectra for certain line features. Default: None

Solution_filename

string, optional

Output filename of text file containing trajectory of LightRay through the dataset. Default: None

Data_filename

string, optional

Output filename for ray data stored as an HDF5 file. Note that at present, you must save a ray to disk in order for it to be returned by this function. If set to None, defaults to ‘ray.h5’. Default: None

Use_minimum_datasets

bool, optional

Use the minimum number of datasets to make the ray continuous through the supplied datasets from the near_redshift to the far_redshift. If false, the LightRay solution will contain as many datasets as possible to enable the light ray to traverse the desired redshift interval. Default: True

Max_box_fraction

float, optional

The maximum length a light ray segment can be in order to span the redshift interval from one dataset to another in units of the domain size. Values larger than 1.0 will result in LightRays crossing the domain of a given dataset more than once, which is generally undesired. Zoom-in simulations can use a value equal to the length of the high-resolution region so as to limit ray segments to that size. If the high-resolution region is not cubical, the smallest size should b used. Default: 1.0 (the size of the box)

Deltaz_min

float, optional

The minimum delta-redshift value between consecutive datasets used in the LightRay solution. Default: 0.0

Minimum_coherent_box_fraction

float, optional

When use_minimum_datasets is set to False, this parameter specifies the fraction of the total box width to be traversed before rerandomizing the ray location and trajectory. Default: 0.0

Find_outputs

optional, bool

Whether or not to search for datasets in the current directory. This is useful if the number of existing datasets is different than what would be predicted by the simulation parameter file. Default: False.

Seed

int, optional

Sets the seed for the random number generator used to determine the location and trajectory of the LightRay as it traverses the simulation datasets. For consistent results between LightRays, use the same seed value. Default: None

Setup_function

function, optional

A function that will be called on the dataset as it is loaded but before the LightRay is generated. Very useful for adding derived fields and other manipulations of the dataset prior to LightRay creation. Default: None

Load_kwargs

dict, optional

Dictionary of kwargs to be passed to the yt “load” function prior to creating the LightRay. Very useful for many frontends like Gadget, Tipsy, etc. for passing in “bounding_box”, “unit_base”, etc. Default: None

Line_database

string, optional

For use with the :lines: keyword. If you want to limit the available ion fields to be added to those available in a particular subset, you can use a LineDatabase. This means when you set :lines:=’all’, it will only use those ions present in the corresponding LineDatabase. If :LineDatabase: is set to None, and :lines:=’all’, it will add every ion of every element up to Zinc. Default: None

Ionization_table

string, optional

For use with the :lines: keyword. Path to an appropriately formatted HDF5 table that can be used to compute the ion fraction as a function of density, temperature, metallicity, and redshift. When set to None, it uses the table specified in ~/.trident/config Default: None

Field_parameters

optional, dict Used to set field parameters in light rays. For example, if the ‘bulk_velocity’ field parameter is set, the relative velocities used to calculate peculiar velocity will be adjusted accordingly. Default: None.

Example

Generate a compound ray passing from the redshift 0 to redshift 0.05 through a multi-output enzo simulation.

>>> import trident
>>> fn = 'path/to/simulation/parameter/file'
>>> ray = trident.make_compound_ray(fn, simulation_type='Enzo',
... near_redshift=0.0, far_redshift=0.05, lines=['H', 'O', 'Mg II'])

Generate a compound ray passing from the redshift 0 to redshift 0.05 through a multi-output gadget simulation.

>>> import trident
>>> fn = 'path/to/simulation/parameter/file'
>>> ray = trident.make_compound_ray(fn, simulation_type='Gadget',
... near_redshift=0.0, far_redshift=0.05, lines=['H', 'O', 'Mg II'])