lightcurvelynx.models.physical_model

The base classes for all models.

The code supports two types of models: 1) SEDModels define recipes for computing SEDs at given times and wavelengths, accounting for redshift and other effects. 2) BandfluxModels only compute band fluxes for specific passbands instead of the SEDs. This is used for models that are empirically fit from observed band fluxes.

We strongly recommend using the full SED models (SEDModels) whenever possible since they more accurately simulate aspects such as the impact of redshift on rest frame effects.

Classes

`BasePhysicalModel`	The abstract base class used to represent a physical model of a source of flux. This includes
`SEDModel`	A model of a source of flux that is defined at the SED level.
`BandfluxModel`	A model of a source of flux that is only defined by band pass values

Module Contents

class BasePhysicalModel(*, ra=None, dec=None, redshift=None, t0=None, distance=None, node_label=None, seed=None, **kwargs)[source]

Bases: lightcurvelynx.base_models.ParameterizedNode, abc.ABC

The abstract base class used to represent a physical model of a source of flux. This includes basic attributes, such as right ascension, declination, redshift, and distance.

Physical models can have fixed attributes (where you need to create a new model or use a setter function to change them) and settable model parameters that can be passed functions or constants and are stored in the graph’s (external) graph_state dictionary.

Physical models also support adding and applying a variety of effects, such as redshift.

Parameterized values include:

dec - The object’s declination in degrees.
distance - The object’s luminosity distance in pc.
ra - The object’s right ascension in degrees.
redshift - The object’s redshift.
t0 - The t0 of the zero phase (if applicable), date.

Parameters:

ra (float) – The object’s right ascension (in degrees)
dec (float) – The object’s declination (in degrees)
redshift (float) – The object’s redshift.
t0 (float) – The phase offset in MJD. For non-time-varying phenomena, this has no effect.
distance (float) – The object’s luminosity distance (in pc). If no value is provided and a cosmology parameter is given, the model will try to derive from the redshift and the cosmology.
node_label (str, optional) – The label for the node in the model graph.
seed (int, optional) – The seed for a random number generator.
**kwargs (dict, optional) – Any additional keyword arguments.

minwave(**kwargs)[source]

Get the minimum supported wavelength of the model.

Parameters:: **kwargs (dict) – Additional keyword arguments, not used in this method.
Returns:: minwave – The minimum wavelength of the model (in angstroms) or None if the model does not have a defined minimum wavelength.
Return type:: float or None

maxwave(**kwargs)[source]

Get the maximum supported wavelength of the model.

Parameters:: **kwargs (dict) – Additional keyword arguments, not used in this method.
Returns:: maximum – The maximum wavelength of the model (in angstroms) or None if the model does not have a defined maximum wavelength.
Return type:: float or None

minphase(**kwargs)[source]

Get the minimum supported phase of the model in days.

Parameters:: **kwargs (dict) – Additional keyword arguments, not used in this method.
Returns:: minphase – The minimum phase of the model (in days) or None if the model does not have a defined minimum phase.
Return type:: float or None

maxphase(**kwargs)[source]

Get the maximum supported phase of the model in days.

Parameters:: **kwargs (dict) – Additional keyword arguments, not used in this method.
Returns:: maximum – The maximum phase of the model (in days) or None if the model does not have a defined maximum phase.
Return type:: float or None

abstractmethod add_effect(effect)[source]

Add an effect to the model. This effect will be applied to all fluxes densities simulated by the model.

Any effect parameters that are not already in the model will be added to this node’s parameters.

Parameters:: effect (EffectModel) – The effect to add.

evaluate_bandfluxes(passband_or_group, times, filters, state, rng_info=None) → numpy.ndarray[source]

Get the band fluxes for a given Passband or PassbandGroup.

Parameters:

passband_or_group (Passband or PassbandGroup) – The passband (or passband group) to use.
times (numpy.ndarray) – A length T array of observer frame timestamps in MJD.
filters (numpy.ndarray or None) – A length T array of filter names. It may be None if passband_or_group is a Passband.
state (GraphState) – An object mapping graph parameters to their values.
rng_info (numpy.random._generator.Generator, optional) – A given numpy random number generator to use for this computation. If not provided, the function uses the node’s random number generator.

Returns:

bandfluxes – A matrix of the band fluxes. If only one sample is provided in the GraphState, then returns a length T array. Otherwise returns a size S x T array where S is the number of samples in the graph state.

Return type:

numpy.ndarray

evaluate_spectra(times, spectrograph, state, rng_info=None) → numpy.ndarray[source]

Get the band fluxes for a given Passband or PassbandGroup.

Parameters:

times (numpy.ndarray) – A length T array of observer frame timestamps in MJD.
spectrograph (Spectrograph) – The information about the spectrograph to use.
state (GraphState) – An object mapping graph parameters to their values.
rng_info (numpy.random._generator.Generator, optional) – A given numpy random number generator to use for this computation. If not provided, the function uses the node’s random number generator.

Returns:

fluxes – A matrix of the band fluxes. If only one sample is provided in the GraphState, then returns a length T x B array where B is the number of spectrograph bins. Otherwise returns a size S x T x B array where S is the number of samples in the graph state.

Return type:

numpy.ndarray

class SEDModel(wave_extrapolation=None, time_extrapolation=None, *args, **kwargs)[source]

Bases: BasePhysicalModel

A model of a source of flux that is defined at the SED level.

rest_frame_effects[source]

A list of effects to apply in the rest frame.

Type:: list of EffectModel

obs_frame_effects[source]

A list of effects to apply in the observer frame.

Type:: list of EffectModel

apply_redshift[source]

Whether to apply redshift to the model.

Type:: bool

Parameters:

wave_extrapolation (FluxExtrapolationModel or tuple, optional) – The extrapolation model(s) to use for wavelengths that fall outside the model’s defined bounds. If a tuple is provided, then it is expected to be of the form (before_model, after_model) where before_model is the model for before the first valid wavelength and after_model is the model for after the last valid wavelength. If None is provided the model will not try to extrapolate, but rather call compute_sed() for all wavelengths.
time_extrapolation (FluxExtrapolationModel or tuple, optional) – The extrapolation model(s) to use for times that fall outside the model’s defined bounds. If a tuple is provided, then it is expected to be of the form (before_model, after_model) where before_model is the model for before the first valid time and after_model is the model for after the last valid time. If None is provided the model will not try to extrapolate, but rather call compute_sed() for all times.

apply_redshift[source]

rest_frame_effects = [][source]

obs_frame_effects = [][source]

set_apply_redshift(apply_redshift)[source]

Toggles the apply_redshift setting. If set to True, the model will apply redshift during the flux density computation including applying wavelength and time transformations.

Parameters:: apply_redshift (bool) – The new value for apply_redshift.

add_effect(effect, skip_params=False)[source]

Add an effect to the model. This effect will be applied to all fluxes densities simulated by the model.

Any effect parameters that are not already in the model will be added to this node’s parameters.

Parameters:

effect (EffectModel) – The effect to add.
skip_params (bool) – Skip adding the parameters to the model. This should only be done in very limited cases where the parameters are added via another mechanism. Most users should NOT change this setting. Default: False

list_effects()[source]: Return a list of all effects in the order in which they are applied.

abstractmethod compute_sed(times, wavelengths, graph_state, **kwargs)[source]

Draw effect-free rest frame flux densities. The rest-frame flux is defined as:

F_nu = L_nu / 4*pi*D_L**2,

where D_L is the luminosity distance.

Parameters:

times (numpy.ndarray) – A length T array of rest frame timestamps in MJD.
wavelengths (numpy.ndarray, optional) – A length N array of rest frame wavelengths (in angstroms).
graph_state (GraphState) – An object mapping graph parameters to their values.
**kwargs (dict, optional) – Any additional keyword arguments.

Returns:

flux_density – A length T x N matrix of rest frame SED values (in nJy).

Return type:

numpy.ndarray

compute_sed_with_extrapolation(times, wavelengths, graph_state, **kwargs)[source]

Draw effect-free observations for this object, extrapolating to times and wavelengths where the model is not defined.

Parameters:

times (numpy.ndarray) – A length T array of rest frame timestamps.
wavelengths (numpy.ndarray, optional) – A length N array of wavelengths (in angstroms).
graph_state (GraphState) – An object mapping graph parameters to their values.
**kwargs (dict, optional) – Any additional keyword arguments.

Returns:

flux_density – A length T x N matrix of SED values (in nJy).

Return type:

numpy.ndarray

evaluate_sed(times, wavelengths, graph_state=None, given_args=None, rng_info=None, **kwargs)[source]

Draw observations for this object and apply the noise.

Parameters:

times (numpy.ndarray) – A length T array of observer frame timestamps in MJD.
wavelengths (numpy.ndarray) – A length N array of wavelengths (in angstroms).
graph_state (GraphState, optional) – An object mapping graph parameters to their values.
given_args (dict, optional) – A dictionary representing the given arguments for this sample run. This can be used as the JAX PyTree for differentiation.
rng_info (numpy.random._generator.Generator, optional) – A given numpy random number generator to use for this computation. If not provided, the function uses the node’s random number generator.
**kwargs (dict, optional) – All the other keyword arguments.

Returns:

flux_density – A length S x T x N matrix of SED values (in nJy), where S is the number of samples, T is the number of time steps, and N is the number of wavelengths. If S=1 then the function returns a T x N matrix.

Return type:

numpy.ndarray

class BandfluxModel(*args, time_extrapolation=None, **kwargs)[source]

Bases: BasePhysicalModel, abc.ABC

A model of a source of flux that is only defined by band pass values in the observer frame (instead of a full SED).

Instead of calling compute_sed() the model calls compute_bandflux() for each filter during its computation.

Note

We strongly recommend using the full SED models (SEDModel) whenever possible since they more accurately simulate aspects such as the impact of redshift on rest frame effects.

band_pass_effects[source]

A list of effects to apply in to the band pass fluxes.

Type:: list of EffectModel

Parameters:: time_extrapolation (FluxExtrapolationModel or tuple, optional) – The extrapolation model(s) to use for times that fall outside the model’s defined bounds. If a tuple is provided, then it is expected to be of the form (before_model, after_model) where before_model is the model for before the first valid time and after_model is the model for after the last valid time. If None is provided the model will not try to extrapolate, but rather call compute_bandflux() for all times.

band_pass_effects = [][source]

abstractmethod set_apply_redshift(apply_redshift)[source]

Toggles the apply_redshift setting.

Parameters:: apply_redshift (bool) – The new value for apply_redshift.

add_effect(effect, skip_params=False)[source]

Add an effect to the model.

Parameters:

effect (EffectModel) – The effect to add.
skip_params (bool) – Skip adding the parameters to the model. This should only be done in very limited cases where the parameters are added via another mechanism. Most users should NOT change this setting. Default: False

list_effects()[source]: Return a list of all effects in the order in which they are applied.

abstractmethod compute_bandflux(times, filter, state)[source]

Evaluate the model at the passband level for a single, given graph state and filter.

Parameters:

times (numpy.ndarray) – A length T array of observer frame timestamps in MJD.
filter (str) – The name of the filter.
state (GraphState) – An object mapping graph parameters to their values with num_samples=1.

Returns:

bandflux – A length T array of band fluxes for this model in this filter.

Return type:

numpy.ndarray

compute_bandflux_with_extrapolation(times, filter, state)[source]

Evaluate the model at the passband level for a single, given graph state and filter, extrapolating to times where the model is not defined.

Parameters:

times (numpy.ndarray) – A length T array of observer frame timestamps in MJD.
filter (str) – The name of the filter.
state (GraphState) – An object mapping graph parameters to their values with num_samples=1.

Returns:

bandflux – A length T array of band fluxes for this model in this filter.

Return type:

numpy.ndarray

abstractmethod evaluate_spectra(spectrograph, times, state, rng_info=None) → numpy.ndarray[source]

Get the band fluxes for a given Passband or PassbandGroup.

Parameters:

spectrograph (Spectrograph) – The information about the spectrograph to use.
times (numpy.ndarray) – A length T array of observer frame timestamps in MJD.
state (GraphState) – An object mapping graph parameters to their values.
rng_info (numpy.random._generator.Generator, optional) – A given numpy random number generator to use for this computation. If not provided, the function uses the node’s random number generator.

Returns:

fluxes – A matrix of the band fluxes. If only one sample is provided in the GraphState, then returns a length T x B array where B is the number of spectrograph bins. Otherwise returns a size S x T x B array where S is the number of samples in the graph state.

Return type:

numpy.ndarray