trident.ion_balance.add_ion_fields

trident.ion_balance.add_ion_fields(ds, ions, ftype='gas', ionization_table=None, field_suffix=False, line_database=None, sampling_type='local', particle_type=None)[source]

Preferred method for adding ion fields to a yt dataset.

Select ions based on the selection indexing set up in parse_subset_to_ions function, that is, by specifying a list of strings where each string represents an ion or line. Strings are of one of three forms:

  • <element>

  • <element> <ion state>

  • <element> <ion state> <line_wavelength>

If a line_database is selected, then the ions chosen will be a subset of the ions present in the equivalent LineDatabase, nominally located in trident.__path__/data/line_lists.

For each ion species selected, four fields will be added (example for Mg II):

  • Ion fraction field. e.g. (“gas”, ‘Mg_p1_ion_fraction’)

  • Number density field. e.g. (“gas”, ‘Mg_p1_number_density’)

  • Density field. e.g. (“gas”, ‘Mg_p1_density’)

  • Mass field. e.g. (“gas”, ‘Mg_p1_mass’)

This function is the preferred method for adding ion fields to one’s dataset, but for more fine-grained control, one can also employ the add_ion_fraction_field, add_ion_number_density_field, add_ion_density_field, add_ion_mass_field functions individually.

Fields are added assuming collisional ionization equilibrium and photoionization in the optically thin limit from a redshift-dependent metagalactic ionizing background using the ionization_table specified.

Parameters

Ds:

yt dataset object

This is the dataset to which the ion fraction field will be added.

Ions:

list of strings

List of strings matching possible lines. Strings can be of the form: * Atom - Examples: “H”, “C”, “Mg” * Ion - Examples: “H I”, “H II”, “C IV”, “Mg II” * Line - Examples: “H I 1216”, “C II 1336”, “Mg II 1240”

If set to ‘all’, creates all ions for the first 30 elements: (ie hydrogen to zinc). If set to ‘all’ with line_database keyword set, then creates all ions associated with the lines specified in the equivalent LineDatabase.

Ionization_table:

string, optional

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_suffix:

boolean, optional

Determines whether or not to append a suffix to the field name that indicates what ionization table was used. Useful when using generating ion_fields that already exist in a dataset.

Line_database:

string, optional

Ions are selected out of the set of ions present in the line_database constructed from the line list filename specified here. See LineDatabase for more information.

Ftype:

string, optional

This is deprecated and no longer necessary since all relevant fields are aliased to the ‘gas’ ftype. Default: ‘gas’

Sampling_type:

string, optional

This is deprecated and no longer necessary. Default: ‘local’

Particle_type:

boolean, optional

This is deprecated and no longer necessary. Default: ‘auto’

Example

To add ionized hydrogen, doubly-ionized Carbon, and all of the Magnesium species fields to a dataset, you would run:

>>> import yt
>>> import trident
>>> ds = yt.load('path/to/file')
>>> trident.add_ion_fields(ds, ions=['H II', 'C III', 'Mg'])