From 4affbfce960b94ad2b512c43ceb6c5d8b61e8770 Mon Sep 17 00:00:00 2001 From: Cameron Hummels Date: Tue, 12 Oct 2021 20:30:43 -0700 Subject: [PATCH 1/3] Updating Light Ray Docs --- doc/source/index.rst | 3 +- doc/source/light_ray_generator.rst | 192 ++++++++++++++++------------- 2 files changed, 107 insertions(+), 88 deletions(-) diff --git a/doc/source/index.rst b/doc/source/index.rst index 4d61429c5..eaca3a4fa 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -18,8 +18,9 @@ information, see :ref:`versions`. installation.rst annotated_example.rst - advanced_spectra.rst ion_balance.rst + light_ray_generator.rst + advanced_spectra.rst absorption_spectrum_fit.rst internals.rst testing.rst diff --git a/doc/source/light_ray_generator.rst b/doc/source/light_ray_generator.rst index 2093bcee6..4562142b0 100644 --- a/doc/source/light_ray_generator.rst +++ b/doc/source/light_ray_generator.rst @@ -10,95 +10,113 @@ larger than the simulation box. .. image:: _images/lightray.png -A ray segment records the information of all grid cells intersected by the -ray as well as the path length, ``dl``, of the ray through the cell. Column -densities can be calculated by multiplying physical densities by the path -length. - -.. _multi-ray: - -Configuring the Light Ray Generator ------------------------------------ - -Below follows the creation of a light ray from multiple datasets stacked -together. The primary Trident interface to this is covered in -:ref:`compound-ray`. A light ray can also be made from a single dataset. -For information on this, see :ref:`single-ray`. - -The arguments required to instantiate a :class:`~trident.light_ray.LightRay` are -the simulation parameter file, the simulation type, the nearest redshift, -and the furthest redshift. - -.. code-block:: python - - from trident import LightRay - lr = LightRay("enzo_tiny_cosmology/32Mpc_32.enzo", - simulation_type="Enzo", - near_redshift=0.0, far_redshift=0.1) - -Making Light Ray Data ---------------------- - -Once the LightRay object has been instantiated, the -:func:`~trident.light_ray.LightRay.make_light_ray` -function will trace out the rays in each dataset and collect information for all the -fields requested. The output file will be an yt-loadable dataset containing all the -cell field values for all the cells that were intersected by the ray. A -single LightRay object can be used over and over to make multiple -randomizations, simply by changing the value of the random seed with the -``seed`` keyword. - -.. code-block:: python - - lr.make_light_ray(seed=8675309, - fields=['temperature', 'density'], - use_peculiar_velocity=True) - - # Optionally, we can now overplot the part of this ray that intersects - # one output from the source dataset in a ProjectionPlot - ds = yt.load('enzo_tiny_cosmology/RD0004/RD0004') - p = yt.ProjectionPlot(ds, 'z', 'density') - p.annotate_ray(lr) - p.save() - -.. _single-ray: - -Light Rays Through Single Datasets ----------------------------------- - -LightRays can also be configured for use with single datasets. In this case, -one must specify the ray's trajectory explicitly. The main Trident interface -to this functionality is covered in :ref:`simple-ray`. - -.. code-block:: python - - from trident import LightRay - import yt - - ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030") - lr = LightRay(ds) - - lr.make_light_ray(start_position=ds.domain_left_edge, - end_position=ds.domain_right_edge, - solution_filename='lightraysolution.txt', - data_filename='lightray.h5', - fields=['temperature', 'density']) - - # Overplot the ray on a projection. - p = yt.ProjectionPlot(ds, 'z', 'density') - p.annotate_ray(lr) - p.save() - -Alternately, the ``trajectory`` keyword can be used in place of `end_position` -to specify the (r, theta, phi) direction of the ray. - -Useful Tips for Making LightRays +The preferred manner for generating rays uses the +:func:`~trident.ray_generator.make_simple_ray` for +:class:`~trident.light_ray.LightRay` 's spanning a single dataset +and +:func:`~trident.ray_generator.make_compound_ray` for +:class:`~trident.light_ray.LightRay` 's spanning multiple datasets. + +Simple Rays +----------- + +For a simple ray, you specify the dataset to use, the start and end coordinates +of your 1D line, and then optionally any additional fields you want stored on the +:class:`~trident.light_ray.LightRay` or optionally any ionic species you will want to +use with this ray:: + + import yt + import trident + ds = yt.load('FIRE_M12i_ref11/snapshot_600.hdf5') + ray = trident.make_simple_ray(ds, + start_position=[0, 0, 0], + end_position=[60000, 60000, 60000], + lines=['H', 'Mg', 'O'], + fields=[('gas', 'temperature'), ('gas', 'metallicity')]) + +Compound Rays +------------- + +For a compound ray, you specify the simulation parameter filename, the simulation code, +the start and end redshifts of the :class:`~trident.light_ray.LightRay`, and optionally +any additional fields you want stored or any ionic species you will want to use with +this ray:: + + import trident + fn = 'enzo_cosmology_plus/AMRCosmology.enzo' + ray = trident.make_compound_ray(fn, + simulation_type='Enzo', + near_redshift=0.0, + far_redshift=0.1, + lines=['H', 'Mg', 'O'], + fields=[('gas', 'temperature'), ('gas', 'metallicity')]) + +Ray Fields +---------- + +The resulting ``ray`` is a :class:`~trident.light_ray.LightRay` object, consisting of a series +of arrays representing the different fields it probes in the original dataset along +its length. Each element in the arrays represents a different resolution element +along the path of the ray. The ray also possesses some special fields not originally +present in the original dataset: + + * ``('gas', 'l')`` Location along the LightRay length from 0 to 1. + * ``('gas', 'dl')`` Pathlength of resolution element (not a *true* pathlength for particle-based codes) + * ``('gas', 'redshift')`` Cosmological redshift of resolution element + * ``('gas', 'redshift_dopp')`` Doppler redshift of resolution element + * ``('gas', 'redshift_eff')`` Effective redshift (combined cosmological and Doppler) + +Like any dataset, you can see what fields are present on the ray by examining its +``derived_field_list`` (e.g., ``print(ds.derived_field_list``). If you want more ions +present on this ray than are currently available, you can add them with +:class:`~trident.ion_balance.add_ion_fields` (see: :ref:`ion-balance`). + +This ``ray`` object is also saved to disk as an HDF5 file, which can later be loaded +into ``yt`` as a stand-alone dataset. By default it is saved as ``ray.h5``, but you +can specify other filenames when you create it. To later access this file and +load it into yt, load it like any other dataset: ``ds = yt.load('ray.h5')``. + +Calculating Column Densities +---------------------------- + +Perhaps we wish to know the total column density of a particular ion present along +this :class:`~trident.light_ray.LightRay`. This can easily be done by multiplying the desired +ion number density field by the pathlength field, ``dl``, to yield an array of +column densities for each resolution element, and then summing them together:: + + column_density_HI = ray.r[('gas', 'H_p0_number_density')] * ray.r[('gas', 'dl')] + print('HI Column Density = %g' % column_density_HI.sum()) + +Examining LightRay Solution Data -------------------------------- -Below are some tips that may come in handy for creating proper LightRays. - -How many snapshots do I need? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +When a :class:`~trident.light_ray.LightRay` is created, it saves the source information +from the dataset that produced it in a dictionary, including its filename, its start +and end points in the original dataset, etc. This is all accessible when +you load up the :class:`~trident.light_ray.LightRay` again through the +``light_ray_solution``:: + + import yt + ds = yt.load('ray.h5') + print(ds.light_ray_solution) + + [{'end': unyt_array([1., 1., 1.], 'unitary'), + 'filename': 'snapshot_600.hdf5', + 'redshift': 0.05, + 'start': unyt_array([0.48810148, 0.51748806, 0.54316002], 'unitary'), + 'traversal_box_fraction': unyt_quantity(0.83878521, 'unitary'), + 'unique_identifier': '1436307563512020127'}] + +Useful Tips for Making Compound LightRays +----------------------------------------- + +Below are some tips that may come in handy for creating proper LightRays. For full +use of these, you may have to create the :class:`~trident.light_ray.LightRay` +by hand instead of using the :func:`~trident.ray_generator.make_compound_ray` helper +function. + +How many snapshots do I need for a compound ray? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The number of snapshots required to traverse some redshift interval depends on the simulation box size and cosmological parameters. Before running an From 34414bc3a62a50400a6cee82079085c5321195bf Mon Sep 17 00:00:00 2001 From: Cameron Hummels Date: Tue, 12 Oct 2021 20:31:14 -0700 Subject: [PATCH 2/3] Fixing typos --- doc/source/annotated_example.rst | 2 +- doc/source/ion_balance.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/annotated_example.rst b/doc/source/annotated_example.rst index 4a9fd946e..c1a6393eb 100644 --- a/doc/source/annotated_example.rst +++ b/doc/source/annotated_example.rst @@ -33,7 +33,7 @@ Simple LightRay Generation A :class:`~trident.light_ray.LightRay` is a 1D object representing the path a ray of light takes through a simulation volume on its way from some bright background object to the observer. It records all of the gas fields it intersects along -the way for use in construction of a spectrum. +the way for use in many tasks, including construction of a spectrum. In order to generate a :class:`~trident.light_ray.LightRay` from your data, you need to first make sure that you've imported both the yt and Trident packages, and diff --git a/doc/source/ion_balance.rst b/doc/source/ion_balance.rst index 3e9e610b1..26a090678 100644 --- a/doc/source/ion_balance.rst +++ b/doc/source/ion_balance.rst @@ -3,7 +3,7 @@ Adding Ion Fields ================= -In addition to being able to create absorption spectra, Trident +In addition to being able to create absorption spectra, Trident can be used to postprocess datasets to add fields for ions not explicitly tracked in the simulation. These can later be analyzed using the standard yt analysis packages. This page provides some examples From 7d1e439e204131b18acde50a666c051b929f9aae Mon Sep 17 00:00:00 2001 From: Cameron Hummels Date: Wed, 13 Oct 2021 05:39:02 -0700 Subject: [PATCH 3/3] Fixing RTD API docs --- environment.yml | 39 --------------------------------------- readthedocs.yml | 2 -- 2 files changed, 41 deletions(-) delete mode 100644 environment.yml diff --git a/environment.yml b/environment.yml deleted file mode 100644 index d76a0eb77..000000000 --- a/environment.yml +++ /dev/null @@ -1,39 +0,0 @@ -name: trident -dependencies: - - pip=19.1.1=py36_0 - - setuptools=41.0.1=py36_0 - - wheel=0.33.4=py36_0 - - pip: - - appnope==0.1.0 - - astropy==3.2.1 - - backcall==0.1.0 - - chardet==3.0.4 - - cycler==0.10.0 - - cython==0.29.13 - - decorator==4.4.0 - - h5py==2.9.0 - - idna==2.8 - - ipython==7.7.0 - - ipython-genutils==0.2.0 - - jedi==0.14.1 - - kiwisolver==1.1.0 - - matplotlib==3.1.1 - - mpmath==1.1.0 - - numpy==1.17.0 - - parso==0.5.1 - - pexpect==4.7.0 - - pickleshare==0.7.5 - - prompt-toolkit==2.0.9 - - ptyprocess==0.6.0 - - pygments==2.4.2 - - pyparsing==2.4.2 - - python-dateutil==2.8.0 - - requests==2.22.0 - - scipy==1.0.1 - - sphinx==4.2.0 - - sympy==1.4 - - traitlets==4.3.2 - - urllib3==1.25.3 - - wcwidth==0.1.7 - - yt==4.0.1 - - yt-astro-analysis==1.0.0 diff --git a/readthedocs.yml b/readthedocs.yml index 989659fe6..dda01ea06 100644 --- a/readthedocs.yml +++ b/readthedocs.yml @@ -1,5 +1,3 @@ -conda: - file: environment.yml python: setup_py_install: false pip_install: true