synthesizer.emission_models.base_model¶

A module defining the emission model from which spectra are constructed.

Generating spectra involves the following steps: 1. Extraction from a Grid. 2. Generation of spectra. 3. Attenuation due to dust in the ISM/nebular. 4. Masking for different types of emission. 5. Combination of different types of emission.

An emission model defines the parameters necessary to perform these steps and gives an interface for simply defining the construction of complex spectra.

Example usage:

# Define the grid
grid = Grid(...)

# Define the dust curve
dust_curve = dust.attenuation.PowerLaw(...)

# Define the emergent emission model
emergent_emission_model = EmissionModel(
    label="emergent",
    grid=grid,
    dust_curve=dust_curve,
    apply_to=dust_emission_model,
    tau_v=tau_v,
    fesc=fesc,
    emitter="stellar",
)

# Generate the spectra
spectra = stars.get_spectra(emergent_emission_model)

# Generate the lines
lines = stars.get_lines(
    line_ids=("Ne 4 1601.45A, He 2 1640.41A", "O3 1660.81A"),
    emission_model=emergent_emission_model
)

Classes

class synthesizer.emission_models.base_model.BlackHoleEmissionModel(*args, **kwargs)[source]¶

An emission model for black hole components.

This is a simple wrapper to quickly apply that the emitter a model should act on is a black hole.

emitter¶

The emitter this model is for.

Type:: str

class synthesizer.emission_models.base_model.EmissionModel(label, grid=None, extract=None, combine=None, apply_to=None, dust_curve=None, igm=None, generator=None, transformer=None, mask_attr=None, mask_thresh=None, mask_op=None, lam_mask=None, related_models=None, emitter=None, scale_by=None, post_processing=(), save=True, per_particle=False, vel_shift=False, **fixed_parameters)[source]¶

A class to define the construction of an emission from a grid.

An emission can either be a spectra (Sed) or a set of lines (LineCollection).

An emission model describes the steps necessary to construct a emissions from an emitter (a galaxy or one of its components). These steps can be: - Extracting an emission from a grid. - Combining multiple emissions. - Transforming an emission (e.g. applying a dust curve). - Generating an emission (e.g. dust emission).

All of these stages can also have masks applied to them to remove certain elements from the emission (e.g. if you want to eliminate young stars). Note that regardless of any masks all emissions will be the same shape (i.e. have the same number of elements but with some set to zero based on the mask).

By chaining together multiple emission models, complex emissions can be constructed from parametric of particle based inputs. This chained together network of models we call the tree. The tree has a single model at it’s root which is the model that will be used directly called from by the user. Each model in the tree is connected to at least one other model in the tree. Each node can also have related models which may not be directly connected to the root model but can still be used to generate an emission.

Note: Every time a property is changed anywhere in the model tree the tree must be reconstructed. This is a cheap process but must happen to ensure the expected properties are used when the model is used. This means most attributes are accessed through properties and set via setters to ensure the tree remains consistent.

A number of attributes are defined as properties to protect their values and ensure the tree is correctly reconstructed when they are changed.

label¶

The key for the spectra that will be produced.

Type:: str

lam¶

The wavelength array.

Type:: unyt_array

masks¶

A list of masks to apply.

Type:: list

parents¶

A list of models which depend on this model.

Type:: list

children¶

A list of models this model depends on.

Type:: list

related_models¶

A list of related models to this model. A related model is a model that is connected somewhere within the model tree but is required in the construction of the “root” model encapsulated by self.

Type:: list

fixed_parameters¶

A dictionary of component attributes/parameters which should be fixed and thus ignore the value of the component attribute. This should take the form {<parameter_name>: <value>}.

Type:: dict

emitter¶

The emitter this emission model acts on.

Type:: str

apply_to¶

The model to apply the dust curve to.

Type:: EmissionModel

dust_curve¶

The dust curve to apply.

Type:: emission_models.attenuation.*

generator¶

The emission generation model. This must inherit from a Generator base class and thus define _generate_spectra and _generate_lines.

Type:: EmissionModel

mask_attr¶

The component attribute to mask on.

Type:: str

mask_thresh¶

The threshold for the mask.

Type:: unyt_quantity

mask_op¶

The operation to apply. Can be “<”, “>”, “<=”, “>=”, “==”, or “!=”.

Type:: str

lam_mask¶

The mask to apply to the wavelength array.

Type:: ndarray

scale_by¶

A list of attributes to scale the spectra by.

Type:: list

post_processing¶

A list of post processing functions to apply to the emission after it has been generated. Each function must take a dict containing the spectra/lines, the emitters, and the emission model, and return the same dict with the post processing applied.

Type:: list

save¶

A flag for whether the emission produced by this model should be “saved”, i.e. attached to the emitter. If False, the emission will be discarded after it has been used. Default is True.

Type:: bool

per_particle¶

A flag for whether the emission produced by this model should be “per particle”. If True, the spectra and lines will be stored per particle. Integrated spectra are made automatically by summing the per particle spectra. Default is False.

Type:: bool

vel_shift¶

A flag for whether the emission produced by this model should take into account the velocity shift due to peculiar velocities. Only applicable to particle based emitters. Default is False.

Type:: bool

add_label_prefix(prefix)[source]¶

Re-labels spectra by adding a prefix.

This will relabel all spectra in the model by adding a prefix.

Parameters:: prefix (str) – The prefix to use when relabelling.

add_label_suffix(suffix)[source]¶

Re-label all models in the tree by adding a suffix.

This is the counterpart to add_label_prefix. Where a prefix is typically used to namespace a whole model (e.g. “stellar” vs “agn”), a suffix is typically used to distinguish variations of a model (e.g. a particular escape fraction).

Parameters:: suffix (str) – The suffix to append to every label. An underscore is inserted between the label and the suffix.

add_label_suffix_downstream(label, suffix)[source]¶

Re-label a model and everything depending on it by adding a suffix.

Only the given model and the models which consume its emission (directly or indirectly) are relabelled. Anything the model depends on keeps its label, and is therefore still shared with the unmodified tree rather than duplicated.

This is the relabelling behaviour needed when varying a parameter on a single model: the varied model produces a different emission, so everything downstream of it does too, but everything upstream is unaffected.

Parameters:

label (str) – The label of the model to start from.
suffix (str) – The suffix to append to the affected labels. An underscore is inserted between the label and the suffix.

add_mask(attr, op, thresh, set_all=False)[source]¶

Add a mask.

Parameters:

attr (str) – The component attribute to mask on.
op (str) – The operation to apply. Can be “<”, “>”, “<=”, “>=”, “==”, or “!=”.
thresh (unyt_quantity) – The threshold for the mask.
set_all (bool) – Whether to add the mask to all models.

property apply_to¶: Get the spectra to apply the dust curve to.

clear_fixed_parameter(param_name)[source]¶

Clear a fixed parameter.

This method will clear a fixed parameter on the model, allowing get_param to access the parameter on the emitter again.

Parameters:: param_name (str) – The name of the parameter to clear.

clear_fixed_parameters()[source]¶: Clear all fixed parameters on the model.

clear_masks(set_all=False)[source]¶

Clear all masks.

Parameters:: set_all (bool) – Whether to clear the masks on all models.

property combine¶: Get the models to combine.

property dust_curve¶: Get the dust curve to apply.

property emitter¶: Get the emitter this emission model acts on.

expand_models()[source]¶

Expand any parameter variations in this tree into new models.

Passing a ParameterList or ParameterDistribution as a model parameter declares that the model should be varied over a set of values. This method turns those declarations into models: the varied model, and everything which depends on it, is duplicated once per value, with each copy labelled using the variation’s label_modifier. Models which the varied model depends on are shared between the copies rather than duplicated, so the parts of the tree unaffected by the variation are only ever computed once.

This model is not modified. The expansion is performed on a copy.

The returned root has the other root variants attached as related models, so a single get_spectra call generates every variant. Each variant’s emission is stored on the emitter under its own label.

Returns:: The root of the expanded tree. If nothing in the tree declared a variation this is just a copy of this model.
Return type:: EmissionModel

property extract¶: Get the key for the spectra to extract.

fix_parameters(**kwargs)[source]¶

Fix parameters of the model.

Parameters:: **kwargs – The parameters to fix.

property generator¶: Get the emission generation model.

property grid¶: Get the Grid object used for extraction.

property igm¶: Get the IGM model to apply.

items()[source]¶: Return the items in the model.

property lam_mask¶: Get the wavelength mask.

property per_particle¶: Get the per particle flag.

plot_emission_graph(root=None, show=True, fontsize=10, figsize=None, layout='layered', show_variants=False, min_fontsize=6.0)[source]¶

Plot the network of models defining the emission.

The whole network is drawn, including related models, which are roots in their own right. Grid extractions sit along the bottom row with each model above everything it depends on, and arrows point in the direction the emission flows.

Parameters:

root (str) – If not None only this model and the models it depends on are drawn.
show (bool) – Whether to show the plot.
fontsize (int) – The fontsize to use for the labels.
figsize (tuple) – The size of the figure to plot (width, height). By default the figure is sized to fit the network.
layout (str) – Either “layered” (the default), which needs only networkx, or “dot”, which lays the network out with graphviz and needs pydot and the graphviz binary.
show_variants (bool) – Whether to draw every parameter variant as its own node. By default each family of variants is collapsed into a single node badged with the number of models it stands for, since an expansion of any size produces more models than can be read at once. This has no effect on a model which was never expanded.
min_fontsize (float) – The size below which labels stop being readable. A network which cannot fit the figure with labels this big grows the figure rather than shrinking them further, so a large network stays as readable as a small one. Pass 0 to let the labels shrink as far as they need to.

Returns:

The figure containing the plot. ax (matplotlib.axes.Axes):

The axis containing the plot.

Return type:

fig (matplotlib.figure.Figure)

plot_emission_tree(*args, **kwargs)[source]¶

Plot the network of models defining the emission.

Deprecated alias for plot_emission_graph.

Parameters:

*args – Positional arguments passed to plot_emission_graph.
**kwargs – Keyword arguments passed to plot_emission_graph.

Returns:

The figure containing the plot. ax (matplotlib.axes.Axes):

The axis containing the plot.

Return type:

fig (matplotlib.figure.Figure)

property post_processing¶: Get the post processing functions.

relabel(old_label, new_label)[source]¶

Change the label associated to an existing spectra.

Parameters:

old_label (str) – The current label of the spectra.
new_label (str) – The new label to assign to the spectra.

replace_model(replace_label, *replacements, new_label=None)[source]¶

Remove a child model from this model.

Parameters:

replace_label (str) – The label of the model to replace.
replacements (EmissionModel) – The models to replace the model with.
new_label (str) – The label for the new combination step if multiple replacements have been passed (ignored otherwise).

property save¶: Get the flag for whether to save the emission.

save_emission(*args)[source]¶

Set the save flag to True for the given emission.

Parameters:: args (str) – The emission to save. Glob patterns are accepted, so “*_fesc_0.10” will save that variant of every model.

save_lines(*args)[source]¶

Set the save flag to True for the given lines.

This is just a friendly alias for save_emission.

Parameters:: args (str) – The lines to save. Glob patterns are accepted.

save_spectra(*args)[source]¶

Set the save flag to True for the given spectra.

This is just a friendly alias for save_emission.

Parameters:: args (str) – The spectra to save. Glob patterns are accepted.

property saved_labels¶: Return a list of model labels that are set to be saved.

property scale_by¶: Get the attribute to scale the spectra by.

select(*patterns)[source]¶

Return the models whose labels match the given glob patterns.

This is the bulk counterpart to indexing a model by label, useful for applying a change to a family of models at once. It is particularly handy after expanding parameter variations, where the variants of a model all share a label prefix or suffix:

for model in expanded.select("*_fesc_0.10"):
    model.set_save(False)

Parameters:: patterns (str) – Labels, or glob patterns matching labels. A plain label with no wildcard matches only itself.
Returns:: The matching models, ordered by label. Empty if nothing matches, since this is a query rather than a change.
Return type:: list

set_apply_to(apply_to)[source]¶

Set the spectra to apply the dust curve to.

Parameters:: apply_to (EmissionModel) – The model to apply the dust curve to.

set_attribute_overload(attr_str, overload_str)[source]¶

Redirect a model attribute to read a different attribute.

This function is useful for redirecting get_param to read a different attribute from the one the model would expect. This is particularly, useful when redirecting a grid axis to read from a different attribute on the emitter.

For example, if we have a grid that contains “ages” and “metallicities” axes but we want to instead use “special_ages” and “special_metallicities” attributes on the emitter, we can use this function which will cause get_param to first attempt to extract “ages” and “metallicities” from the model, see the overload_str string, recurse and attempt to extract “special_ages” and “special_metallicities” from the model, find they are not there, and then look for “special_ages” and “special_metallicities” on the emitter and return them.

This same behaviour can be achieved by passing kwargs at init but this function enables retroactive redirection, especially useful when using premade models.

Parameters:

attr_str (str) – The attribute to redirect.
overload_str (str) – The attribute to redirect to.

set_combine(combine)[source]¶

Set the models to combine on this model.

Parameters:: combine (list) – A list of models to combine.

set_dust_curve(dust_curve)[source]¶: Set the dust curve to apply.

set_dust_props(dust_curve=None, apply_to=None, set_all=False)[source]¶

Set the dust attenuation properties on this model.

Parameters:

dust_curve (emission_models.attenuation.*) – A dust curve instance to apply.
apply_to (EmissionModel) – The model to apply the dust curve to.
set_all (bool) – Whether to set the properties on all models.

set_emitter(emitter, set_all=False)[source]¶

Set the emitter this emission model acts on.

Parameters:

emitter (str) – The emitter this emission model acts on.
set_all (bool) – Whether to set the emitter on all models.

set_extract(extract)[source]¶

Set the spectra to extract from the grid.

Parameters:: extract (str) – The key of the spectra to extract.

set_fixed_parameter(param_name, value)[source]¶

Set a fixed parameter.

This method will set a fixed parameter on the model. This parameter will take precedence over any parameter of the same name on an emitter.

When get_param is called to access a parameter, it will first check the fixed_parameters dictionary on the model, prior to looking for the parameter on the emitter.

Parameters:

param_name (str) – The name of the parameter to fix.
value (Any) – The value to fix the parameter to.

set_generator(generator)[source]¶

Set the dust emission model on this model.

Parameters:

generator (EmissionModel) – The emission generation model to set.
label (str) – The label of the model to set the dust emission model on. If None, sets the dust emission model on this model.

set_grid(grid, set_all=False)[source]¶

Set the grid to extract from.

Parameters:

grid (Grid) – The grid to extract from.
set_all (bool) – Whether to set the grid on all models.

set_igm(igm)[source]¶: Set the IGM model to apply.

set_lam_mask(lam_mask, set_all=False)[source]¶

Set the wavelength mask.

Parameters:

lam_mask (array_like) – The wavelength mask to apply.
set_all (bool) – Whether to set the wavelength mask on all models.

set_per_particle(per_particle)[source]¶

Set the per particle flag.

For per particle spectra we need all children to also be per particle.

Parameters:

per_particle (bool) – Whether to set the per particle flag.
set_all (bool) – Whether to set the per particle flag on all models.

set_post_processing(post_processing, set_all=False)[source]¶

Set the post processing functions on this model.

Parameters:

post_processing (list) – A list of post processing functions to apply to the emission after it has been generated. Each function must take a dict containing the spectra/lines and return the same dict with the post processing applied.
set_all (bool) – Whether to set the post processing functions on all models.

set_save(save, set_all=False)[source]¶

Set the flag for whether to save the emission.

Parameters:

save (bool) – Whether to save the emission.
set_all (bool) – Whether to set the save flag on all models.

set_scale_by(scale_by, set_all=False)[source]¶

Set the attribute to scale the spectra by.

Parameters:

scale_by (str/list/tuple/EmissionModel) – Either a component attribute to scale the resultant spectra by, a spectra key to scale by (based on the bolometric luminosity). or a tuple/list containing strings defining either of the former two options. Instead of a string, an EmissionModel can be passed to scale by the luminosity of that model.
set_all (bool) – Whether to set the scale by attribute on all models.

set_transformer(transformer)[source]¶: Set the transformer to apply.

set_vel_shift(vel_shift, set_all=False)[source]¶

Set whether we should apply velocity shifts to the spectra.

Only applicable to particle emitters.

Particle based vel_shift is incompatible with scalar velocity dispersion broadening transformations, so this function will raise an error if both are set.

Parameters:

vel_shift (bool) – Whether to set the velocity shift flag.
set_all (bool) – Whether to set the emitter on all models.

to_hdf5(group)[source]¶

Save the model to an HDF5 group.

Parameters:: group (h5py.Group) – The group to save the model to.

property transformer¶: Get the transformer to apply.

unpack_model()[source]¶: Unpack the model tree to get the order of operations.

property variant_base¶

Return the label this model’s variant family was expanded from.

Expanding a parameter variation appends a suffix to the label of every affected model. This is the label before any of those suffixes were added, so the variants of a model can be grouped back together.

Returns:: The original label, or None for any model which isn’t the product of an expansion.
Return type:: str or None

property variant_params¶

Return the parameter values which distinguish this model variant.

A model produced by expanding a parameter variation records the values which were varied to produce it, so which variant a model (and thus its emission) belongs to can be recovered without parsing its label.

Returns:: A dictionary of the form {<param_name>: <value>}. Empty for any model which isn’t the product of an expansion.
Return type:: dict

property vel_shift¶: Get the velocity shift flag.

class synthesizer.emission_models.base_model.GalaxyEmissionModel(*args, **kwargs)[source]¶

An emission model for whole galaxy.

A galaxy model sets emitter to “galaxy” to flag to the get_spectra method that the model is for a galaxy. By definition a galaxy level spectra can only be a combination of component spectra.

emitter¶

The emitter this model is for.

Type:: str

class synthesizer.emission_models.base_model.StellarEmissionModel(*args, **kwargs)[source]¶

An emission model for stellar components.

This is a simple wrapper to quickly apply that the emitter a model should act on is stellar.

emitter¶

The emitter this model is for.

Type:: str