skyllh.physics package

Submodules

skyllh.physics.flux module

The flux module contains all standard flux models for a source. The abstract class FluxModel serves as a base class for all flux model classes. The unit of the resulting flux value must be [energy]^-1 [length]^-2 [time]^-1. The units are defined using the astropy.units module and can be set through the properties energy_unit, length_unit, and time_unit. The default units are [energy] = GeV, [length] = cm, [time] = s.

skyllh.physics.flux.get_conversion_factor_to_internal_flux_unit(fluxmodel)

Calculates the unit conversion factor for converting the used flux unit of the given flux model into the skyllh internally used flux unit 1/(GeV cm2 s).

Parameters:

fluxmodel (FluxModel) – The flux model instance for which to calculate the unit conversion factor.

Returns:

unit_conversion_factor (float) – The unit conversion factor.

class skyllh.physics.flux.FluxModel

Bases: object

Abstract base class for all flux models. This base class defines the units used for the flux calculation. At this point the function form of the flux model is not yet defined.

energy_unit

The used unit of energy.

Type:

str

length_unit

The used unit of length.

Type:

str

time_unit

The used unit of time.

Type:

str

math_function_str

The string showing the mathematical function of the flux calculation.

Type:

str

property energy_unit

The unit of energy used for the flux calculation.

property length_unit

The unit of length used for the flux calculation.

property time_unit

The unit of length used for the flux calculation.

property unit_str

The string representation of the flux unit.

property unit_latex_str

The latex string representation of the flux unit.

abstract property math_function_str

The string showing the mathematical function of the flux calculation.

abstract __call__(E)

The call operator to retrieve a flux value for a given energy.

Parameters:

E (float | 1d numpy.ndarray of float) – The energy for which to retrieve the flux value.

Returns:

flux (ndarray of float) – Flux at energy E in unit [energy]^-1 [length]^-2 [time]^-1. By default that is GeV^-1 cm^-2 s^-1.

copy(newprop=None)

Copies this flux model object by calling the copy.deepcopy function, and sets new properties if requested.

Parameters:

newprop (dict | None) – The dictionary with the new property values to set, where the dictionary key is the property name and the dictionary value is the new value of the property.

set_properties(propdict)

Sets the properties of the flux model to the given property values.

Parameters:

propdict (dict (name: value)) – The dictionary holding the names of the properties and their new values.

class skyllh.physics.flux.NormedFluxModel(Phi0, E0)

Bases: FluxModel

Abstract base class for all normalized flux models of the form

dN/(dEdAdt) = Phi0 * f(E/E0),

where Phi0 is the flux normalization at E=E0 in the flux unit [energy]^-1 [length]^-2 [time]^-1, and f(E/E0) is the unit-less energy dependence of the flux.

The unit of dN/(dEdAdt) is [energy]^-1 [length]^-2 [time]^-1. By default the unit is GeV^-1 cm^-2 s^-1.

Phi0

Flux value (dN/(dEdAdt)) at E0 in unit [energy]^-1 [length]^-2 [time]^-1.

Type:

float

E0

Normalization energy in unit of energy.

Type:

float

property Phi0

The flux value (dN/(dEdAdt)) at energy E0 in unit [energy]^-1 [length]^-2 [time]^-1.

property E0

The normalization energy.

class skyllh.physics.flux.PowerLawFlux(Phi0, E0, gamma)

Bases: NormedFluxModel

Power law flux of the form

dN/(dEdAdt) = Phi0 * (E / E0)^(-gamma)

The unit of dN/(dEdAdt) is [energy]^-1 [length]^-2 [time]^-1. By default the unit is GeV^-1 cm^-2 s^-1.

Creates a new power law flux object.

Parameters:

  • Phi0 (float) – Flux value (dN/(dEdAdt)) at E0 in unit [energy]^-1 [length]^-2 [time]^-1. By default that is GeV^-1 cm^-2 s^-1.

  • E0 (float) – Normalization energy.

  • gamma (float) – Spectral index

property gamma
property math_function_str

The string showing the mathematical function of the flux calculation.

__call__(E)

The flux value dN/dE at energy E.

Parameters:

E (float | 1d numpy.ndarray of float) – Evaluation energy [GeV]

Returns:

flux (float | 1d ndarray of float) – Flux at energy E in unit [energy]^-1 [length]^-2 [time]^-1. By default in GeV^-1 cm^-2 s^-1.

class skyllh.physics.flux.CutoffPowerLawFlux(Phi0, E0, gamma, Ecut)

Bases: PowerLawFlux

Cut-off power law flux of the form

dN/(dEdAdt) = Phi0 * (E / E0)^(-gamma) * exp(-E/Ecut)

The unit of dN/(dEdAdt) is [energy]^-1 [length]^-2 [time]^-1. By default the unit is GeV^-1 cm^-2 s^-1.

Creates a new cut-off power law flux object.

Parameters:

  • Phi0 (float) – Flux value (dN/(dEdAdt)) at E0 in unit [energy]^-1 [length]^-2 [time]^-1. By default the unit is GeV^-1 cm^-2 s^-1.

  • E0 (float) – Normalization energy [GeV]

  • gamma (float) – Spectral index

  • Ecut (float) – Cut-off energy [GeV]

property Ecut
property math_function_str

The string showing the mathematical function of the flux calculation.

__call__(E)

The flux value dN/(dEdAdt) at energy E.

Parameters:

E (float | 1d numpy.ndarray of float) – Evaluation energy.

Returns:

flux (float | 1d ndarray of float) – Flux at energy E in unit [energy]^-1 [length]^-2 [time]^-1. By default that is GeV^-1 cm^-2 s^-1.

class skyllh.physics.flux.LogParabolaPowerLawFlux(Phi0, E0, alpha, beta)

Bases: NormedFluxModel

Power law flux with an index which varies as a log parabola in energy of the form

dN/(dEdAdt) = Phi0 * (E / E0)^(-(alpha + beta*log(E / E0)))

The unit of dN/(dEdAdt) is [energy]^-1 [length]^-2 [time]^-1. By default the unit is GeV^-1 cm^-2 s^-1.

property alpha
property beta
property math_function_str

The string showing the mathematical function of the flux calculation.

__call__(E)

The flux value dN/(dEdAdt) at energy E.

Parameters:

E (float | 1d numpy.ndarray of float) – The evaluation energy.

Returns:

flux (float | 1d ndarray of float) – Flux at energy E in unit [energy]^-1 [length]^-2 [time]^-1. By default that is GeV^-1 cm^-2 s^-1.

skyllh.physics.flux_model module

The flux_model module contains classes for different flux models. The class for the most generic flux model is FluxModel, which is an abstract base class. It describes a mathematical function for the differential flux:

\[d^4\Phi_S(\alpha,\delta,E,t | \vec{x}_s,\vec{p}_s) / (dA d\Omega dE dt)\]
class skyllh.physics.flux_model.FluxProfile

Bases: MathFunction

The abstract base class for a flux profile math function.

class skyllh.physics.flux_model.SpatialFluxProfile(angle_unit=None)

Bases: FluxProfile

The abstract base class for a spatial flux profile function.

Creates a new SpatialFluxProfile instance.

Parameters:

angle_unit (instance of astropy.units.UnitBase | None) – The used unit for angles. If set to Ǹone, the configured default angle unit for fluxes is used.

property angle_unit

The set unit of angle used for this spatial flux profile. If set to Ǹone the configured default angle unit for fluxes is used.

abstract __call__(alpha, delta, unit=None)

This method is supposed to return the spatial profile value for the given celestrial coordinates.

Parameters:

  • alpha (float | 1d numpy ndarray of float) – The right-ascention coordinate.

  • delta (float | 1d numpy ndarray of float) – The declination coordinate.

  • unit (instance of astropy.units.UnitBase | None) – The unit of the given celestrial angles. If None, the set angle unit of this SpatialFluxProfile is assumed.

Returns:

values (1D numpy ndarray) – The spatial profile values.

class skyllh.physics.flux_model.UnitySpatialFluxProfile(angle_unit=None)

Bases: SpatialFluxProfile

Spatial flux profile for the constant profile function 1 for any spatial coordinates.

Creates a new UnitySpatialFluxProfile instance.

Parameters:

angle_unit (instance of astropy.units.UnitBase | None) – The used unit for angles. If set to Ǹone, the configured default angle unit for fluxes is used.

property math_function_str

The string showing the mathematical function of this MathFunction.

__call__(alpha, delta, unit=None)

Returns 1 as numpy ndarray in same shape as alpha and delta.

Parameters:

  • alpha (float | 1d numpy ndarray of float) – The right-ascention coordinate.

  • delta (float | 1d numpy ndarray of float) – The declination coordinate.

  • unit (instance of astropy.units.UnitBase | None) – The unit of the given celestrial angles. By the definition of this class this argument is ignored.

Returns:

values (1D numpy ndarray) – 1 in same shape as alpha and delta.

class skyllh.physics.flux_model.PointSpatialFluxProfile(alpha_s, delta_s, angle_unit=None)

Bases: SpatialFluxProfile

Spatial flux profile for a delta function at the celestrical coordinate (alpha_s, delta_s).

Creates a new spatial flux profile for a point.

Parameters:

  • alpha_s (float) – The right-ascention of the point-like source.

  • delta_s (float) – The declination of the point-like source.

  • angle_unit (instance of astropy.units.UnitBase | None) – The used unit for angles. If set to Ǹone, the configured default angle unit for fluxes is used.

property alpha_s

The right-ascention of the point-like source. The unit is the set angle unit of this SpatialFluxProfile instance.

property delta_s

The declination of the point-like source. The unit is the set angle unit of this SpatialFluxProfile instance.

property math_function_str

(read-only) The string representation of the mathematical function of this spatial flux profile instance.

__call__(alpha, delta, unit=None)

Returns a numpy ndarray in same shape as alpha and delta with 1 if alpha equals alpha_s and delta equals delta_s, and 0 otherwise.

Parameters:

  • alpha (float | 1d numpy ndarray of float) – The right-ascention coordinate at which to evaluate the spatial flux profile. The unit must be the internally used angle unit.

  • delta (float | 1d numpy ndarray of float) – The declination coordinate at which to evaluate the spatial flux profile. The unit must be the internally used angle unit.

  • unit (instance of astropy.units.UnitBase | None) – The unit of the given celestrial angles. If set to None, the set angle unit of this SpatialFluxProfile instance is assumed.

Returns:

value (1D numpy ndarray of int8) – A numpy ndarray in same shape as alpha and delta with 1 if alpha equals alpha_s and delta equals delta_s, and 0 otherwise.

class skyllh.physics.flux_model.EnergyFluxProfile(energy_unit=None)

Bases: FluxProfile

The abstract base class for an energy flux profile function.

Creates a new energy flux profile with a given energy unit to be used for flux calculation.

Parameters:

energy_unit (instance of astropy.units.UnitBase | None) – The used unit for energy. If set to None, the configured default energy unit for fluxes is used.

property energy_unit

The unit of energy used for the flux profile calculation.

abstract __call__(E, unit=None)

This method is supposed to return the energy profile value for the given energy value.

Parameters:

  • E (float | 1d numpy ndarray of float) – The energy value for which to retrieve the energy profile value.

  • unit (instance of astropy.units.UnitBase | None) – The unit of the given energy. If set to None, the set energy unit of this EnergyFluxProfile is assumed.

Returns:

values (1D numpy ndarray of float) – The energy profile values for the given energies.

class skyllh.physics.flux_model.UnityEnergyFluxProfile(energy_unit=None)

Bases: EnergyFluxProfile

Energy flux profile for the constant function 1.

Creates a new UnityEnergyFluxProfile instance.

Parameters:

energy_unit (instance of astropy.units.UnitBase | None) – The used unit for energy. If set to None, the configured default energy unit for fluxes is used.

property math_function_str

The string representation of the mathematical function of this energy flux profile.

__call__(E, unit=None)

Returns 1 as numpy ndarray in some shape as E.

Parameters:

  • E (float | 1D numpy ndarray of float) – The energy value for which to retrieve the energy profile value.

  • unit (instance of astropy.units.UnitBase | None) – The unit of the given energies. By definition of this specific class, this argument is ignored.

Returns:

values (1D numpy ndarray of int8) – 1 in same shape as E.

class skyllh.physics.flux_model.PowerLawEnergyFluxProfile(E0, gamma, energy_unit=None)

Bases: EnergyFluxProfile

Energy flux profile for a power law profile with a reference energy E0 and a spectral index gamma.

\[(E / E_0)^{-\gamma}\]

Creates a new power law flux profile with the reference energy E0 and spectral index gamma.

Parameters:

  • E0 (castable to float) – The reference energy.

  • gamma (castable to float) – The spectral index.

  • energy_unit (instance of astropy.units.UnitBase | None) – The used unit for energy. If set to None, the configured default energy unit for fluxes is used.

property E0

The reference energy in the set energy unit of this EnergyFluxProfile instance.

property gamma

The spectral index.

property math_function_str

The string representation of this EnergyFluxProfile instance.

__call__(E, unit=None)

Returns the power law values for the given energies as numpy ndarray in same shape as E.

Parameters:

  • E (float | 1D numpy ndarray of float) – The energy value for which to retrieve the energy profile value.

  • unit (instance of astropy.units.UnitBase | None) – The unit of the given energies. If set to None, the set energy unit of this EnergyFluxProfile instance is assumed.

Returns:

values (1D numpy ndarray of float) – The energy profile values for the given energies.

class skyllh.physics.flux_model.TimeFluxProfile(t_start=-inf, t_end=inf, time_unit=None)

Bases: FluxProfile

The abstract base class for a time flux profile function.

Creates a new time flux profile instance.

Parameters:

  • t_start (float) – The start time of the time profile. If set to -inf, it means, that the profile starts at the beginning of the entire time-span of the dataset.

  • t_end (float) – The end time of the time profile. If set to +inf, it means, that the profile ends at the end of the entire time-span of the dataset.

  • time_unit (instance of astropy.units.UnitBase | None) – The used unit for time. If set to None, the configured default time unit for fluxes is used.

property t_start

The start time of the time profile. Can be -inf which means, that the profile starts at the beginning of the entire dataset.

property t_end

The end time of the time profile. Can be +inf which means, that the profile ends at the end of the entire dataset.

property duration

(read-only) The duration of the time profile.

property time_unit

The unit of time used for the flux profile calculation.

get_total_integral()

Calculates the total integral of the time profile from t_start to t_end.

Returns:

integral (float) – The integral value of the entire time profile. The value is in the set time unit of this TimeFluxProfile instance.

abstract __call__(t, unit=None)

This method is supposed to return the time profile value for the given times.

Parameters:

  • t (float | 1D numpy ndarray of float) – The time(s) for which to get the time flux profile values.

  • unit (instance of astropy.units.UnitBase | None) – The unit of the given times. If set to None, the set time unit of this TimeFluxProfile instance is assumed.

Returns:

values (1D numpy ndarray of float) – The time profile values.

abstract move(dt, unit=None)

Abstract method to move the time profile by the given amount of time.

Parameters:

  • dt (float) – The time difference of how far to move the time profile in time. This can be a positive or negative time shift value.

  • unit (instance of astropy.units.UnitBase | None) – The unit of the given time difference. If set to Ǹone, the set time unit of this TimeFluxProfile instance is assumed.

abstract get_integral(t1, t2, unit=None)

This method is supposed to calculate the integral of the time profile from time t1 to time t2.

Parameters:

  • t1 (float | array of float) – The start time of the integration.

  • t2 (float | array of float) – The end time of the integration.

  • unit (instance of astropy.units.UnitBase | None) – The unit of the given times. If set to Ǹone, the set time unit of this TimeFluxProfile instance is assumed.

Returns:

integral (array of float) – The integral value(s) of the time profile. The values are in the set time unit of this TimeFluxProfile instance.

class skyllh.physics.flux_model.UnityTimeFluxProfile(time_unit=None)

Bases: TimeFluxProfile

Time flux profile for the constant profile function 1.

Creates a new time flux profile instance.

Parameters:

  • t_start (float) – The start time of the time profile. If set to -inf, it means, that the profile starts at the beginning of the entire time-span of the dataset.

  • t_end (float) – The end time of the time profile. If set to +inf, it means, that the profile ends at the end of the entire time-span of the dataset.

  • time_unit (instance of astropy.units.UnitBase | None) – The used unit for time. If set to None, the configured default time unit for fluxes is used.

property math_function_str

The string showing the mathematical function of this MathFunction.

__call__(t, unit=None)

Returns 1 as numpy ndarray in same shape as t.

Parameters:

  • t (float | 1D numpy ndarray of float) – The time(s) for which to get the time flux profile values.

  • unit (instance of astropy.units.UnitBase | None) – The unit of the given times. By definition of this specific class, this argument is ignored.

Returns:

values (1D numpy ndarray of int8) – 1 in same shape as t.

move(dt, unit=None)

Moves the time profile by the given amount of time. By definition this method does nothing, because the profile is 1 over the entire dataset time range.

Parameters:

  • dt (float) – The time difference of how far to move the time profile in time. This can be a positive or negative time shift value.

  • unit (instance of astropy.units.UnitBase | None) – The unit of the given time difference. If set to None, the set time unit of this TimeFluxProfile instance is assumed.

get_integral(t1, t2, unit=None)

Calculates the integral of the time profile from time t1 to time t2.

Parameters:

  • t1 (float | array of float) – The start time of the integration.

  • t2 (float | array of float) – The end time of the integration.

  • unit (instance of astropy.units.UnitBase | None) – The unit of the given times. If set to None, the set time unit of this TimeFluxProfile instance is assumed.

Returns:

integral (array of float) – The integral value(s) of the time profile. The values are in the set time unit of this TimeFluxProfile instance.

class skyllh.physics.flux_model.BoxTimeFluxProfile(t0, tw, time_unit=None)

Bases: TimeFluxProfile

This class describes a box-shaped time flux profile. It has the following parameters:

t0float

The mid time of the box profile.

twfloat

The width of the box profile.

The box is centered at t0 and extends to +/-tw/2 around t0.

Creates a new box-shaped time profile instance.

Parameters:

  • t0 (float) – The mid time of the box profile.

  • tw (float) – The width of the box profile.

  • time_unit (instance of astropy.units.UnitBase | None) – The used unit for time. If set to None, the configured default time unit for fluxes is used.

property t0

The time of the mid point of the box. The value is in the set time unit of this TimeFluxProfile instance.

property tw

The time width of the box. The value is in the set time unit of this TimeFluxProfile instance.

property math_function_str

The string showing the mathematical function of this MathFunction.

__call__(t, unit=None)

Returns 1 for all t within the interval [t0-tw/2; t0+tw/2], and 0 otherwise.

Parameters:

  • t (float | 1D numpy ndarray of float) – The time(s) for which to get the time flux profile values.

  • unit (instance of astropy.units.UnitBase | None) – The unit of the given times. If set to None, the set time unit of this TimeFluxProfile instance is assumed.

Returns:

values (1D numpy ndarray of int8) – The value(s) of the time flux profile for the given time(s).

move(dt, unit=None)

Moves the box-shaped time profile by the time difference dt.

Parameters:

  • dt (float) – The time difference of how far to move the time profile in time. This can be a positive or negative time shift value.

  • unit (instance of astropy.units.UnitBase | None) – The unit of dt. If set to None, the set time unit of this TimeFluxProfile instance is assumed.

get_integral(t1, t2, unit=None)

Calculates the integral of the box-shaped time flux profile from time t1 to time t2.

Parameters:

  • t1 (float | array of float) – The start time(s) of the integration.

  • t2 (float | array of float) – The end time(s) of the integration.

  • unit (instance of astropy.units.UnitBase | None) – The unit of the given times. If set to None, the set time unit of this TimeFluxProfile instance is assumed.

Returns:

integral (array of float) – The integral value(s). The values are in the set time unit of this TimeFluxProfile instance.

class skyllh.physics.flux_model.GaussianTimeFluxProfile(t0, sigma_t, tol=1e-12, time_unit=None)

Bases: TimeFluxProfile

This class describes a gaussian-shaped time flux profile. It has the following parameters:

t0float

The mid time of the gaussian profile.

sigma_tfloat

The one-sigma width of the gaussian profile.

Creates a new gaussian-shaped time profile instance.

Parameters:

  • t0 (float) – The mid time of the gaussian profile.

  • sigma_t (float) – The one-sigma width of the gaussian profile.

  • tol (float) – The tolerance of the gaussian value. This defines the start and end time of the gaussian profile.

  • time_unit (instance of astropy.units.UnitBase | None) – The used unit for time. If set to None, the configured default time unit for fluxes is used.

property t0

The time of the mid point of the gaussian profile. The unit of the value is the set time unit of this TimeFluxProfile instance.

property sigma_t

The one-sigma width of the gaussian profile. The unit of the value is the set time unit of this TimeFluxProfile instance.

__call__(t, unit=None)

Returns the gaussian profile value for the given time t.

Parameters:

  • t (float | 1D numpy ndarray of float) – The time(s) for which to get the time flux profile values.

  • unit (instance of astropy.units.UnitBase | None) – The unit of the given times. If set to None, the set time unit of this TimeFluxProfile is assumed.

Returns:

values (1D numpy ndarray of float) – The value(s) of the time flux profile for the given time(s).

move(dt, unit=None)

Moves the gaussian time profile by the given amount of time.

Parameters:

  • dt (float) – The time difference of how far to move the time profile in time. This can be a positive or negative time shift value.

  • unit (instance of astropy.units.UnitBase | None) – The unit of the given time difference. If set to None, the set time unit of this TimeFluxProfile is assumed.

get_integral(t1, t2, unit=None)

Calculates the integral of the gaussian time profile from time t1 to time t2.

Parameters:

  • t1 (float | array of float) – The start time(s) of the integration.

  • t2 (float | array of float) – The end time(s) of the integration.

  • unit (instance of astropy.units.UnitBase | None) – The unit of the given times. If set to None, the set time unit of this TimeFluxProfile instance is assumed.

Returns:

integral (array of float) – The integral value(s). The values are in the set time unit of this TimeFluxProfile instance.

class skyllh.physics.flux_model.FluxModel(angle_unit=None, energy_unit=None, length_unit=None, time_unit=None, **kwargs)

Bases: MathFunction, Model

Abstract base class for all flux models \(\Phi_S(\alpha,\delta,E,t | \vec{x}_s,\vec{p}_s)\).

This base class defines the units used for the flux calculation. The unit of the flux is ([angle]^{-2} [energy]^{-1} [length]^{-2} [time]^{-1}).

At this point the functional form of the flux model is not yet defined.

Creates a new FluxModel instance and defines the user-defined units.

Parameters:

  • angle_unit (instance of astropy.units.UnitBase | None) – The used unit for angles. If set to None, the configured default angle unit for fluxes is used.

  • energy_unit (instance of astropy.units.UnitBase | None) – The used unit for energy. If set to None, the configured default energy unit for fluxes is used.

  • length_unit (instance of astropy.units.UnitBase | None) – The used unit for length. If set to None, the configured default length unit for fluxes is used.

  • time_unit (instance of astropy.units.UnitBase | None) – The used unit for time. If set to None, the configured default time unit for fluxes is used.

property angle_unit

The unit of angle used for the flux calculation.

property energy_unit

The unit of energy used for the flux calculation.

property length_unit

The unit of length used for the flux calculation.

property time_unit

The unit of time used for the flux calculation.

property unit_str

The string representation of the flux unit.

property unit_latex_str

The latex string representation of the flux unit.

abstract __call__(alpha, delta, E, t, angle_unit=None, energy_unit=None, time_unit=None)

The call operator to retrieve a flux value for a given celestrial position, energy, and observation time.

Parameters:

  • alpha (float | (Ncoord,)-shaped 1D numpy ndarray of float) – The right-ascention coordinate for which to retrieve the flux value.

  • delta (float | (Ncoord,)-shaped 1D numpy ndarray of float) – The declination coordinate for which to retrieve the flux value.

  • E (float | (Nenergy,)-shaped 1D numpy ndarray of float) – The energy for which to retrieve the flux value.

  • t (float | (Ntime,)-shaped 1D numpy ndarray of float) – The observation time for which to retrieve the flux value.

  • angle_unit (instance of astropy.units.UnitBase | None) – The unit of the given angles. If None, the set angle unit of the flux model is assumed.

  • energy_unit (instance of astropy.units.UnitBase | None) – The unit of the given energies. If None, the set energy unit of the flux model is assumed.

  • time_unit (instance of astropy.units.UnitBase | None) – The unit of the given times. If None, the set time unit of the flux model is assumed.

Returns:

flux ((Ncoord,Nenergy,Ntime)-shaped ndarray of float) – The flux values are in unit of the set flux model units [energy]^{-1} [angle]^{-2} [length]^{-2} [time]^{-1}.

class skyllh.physics.flux_model.FactorizedFluxModel(Phi0, spatial_profile, energy_profile, time_profile, length_unit=None, **kwargs)

Bases: FluxModel

This class describes a flux model where the spatial, energy, and time profiles of the source factorize. That means the flux can be written as:

\[\Phi_S(\alpha,\delta,E,t | \vec{x}_s,\vec{p}_s) = \Phi_0 \Psi_{\mathrm{S}}(\alpha,\delta|\vec{p}_s) \epsilon_{\mathrm{S}}(E|\vec{p}_s) T_{\mathrm{S}}(t|\vec{p}_s)\]

where, \(\Phi_0\) is the normalization constant of the flux, and \(\Psi_{\mathrm{S}}\), \(\epsilon_{\mathrm{S}}\), and \(T_{\mathrm{S}}\) are the spatial, energy, and time profiles of the flux, respectively.

Creates a new factorized flux model.

Parameters:

  • Phi0 (float) – The flux normalization constant.

  • spatial_profile (SpatialFluxProfile instance | None) – The SpatialFluxProfile instance providing the spatial profile function of the flux. If set to None, an instance of UnitySpatialFluxProfile will be used, which represents the constant function 1.

  • energy_profile (EnergyFluxProfile instance | None) – The EnergyFluxProfile instance providing the energy profile function of the flux. If set to None, an instance of UnityEnergyFluxProfile will be used, which represents the constant function 1.

  • time_profile (TimeFluxProfile instance | None) – The TimeFluxProfile instance providing the time profile function of the flux. If set to None, an instance of UnityTimeFluxProfile will be used, which represents the constant function 1.

  • length_unit (instance of astropy.units.UnitBase | None) – The used unit for length. If set to None, the configured default length unit for fluxes is used.

property Phi0

The flux normalization constant. The unit of this normalization constant is ([angle]^{-2} [energy]^{-1} [length]^{-2} [time]^{-1}).

property spatial_profile

Instance of SpatialFluxProfile describing the spatial profile of the flux.

property energy_profile

Instance of EnergyFluxProfile describing the energy profile of the flux.

property time_profile

Instance of TimeFluxProfile describing the time profile of the flux.

property math_function_str

The string showing the mathematical function of the flux.

property angle_unit

The unit of angle used for the flux calculation. The unit is taken and set from and to the set spatial flux profile, respectively.

property energy_unit

The unit of energy used for the flux calculation. The unit is taken and set from and to the set energy flux profile, respectively.

property time_unit

The unit of time used for the flux calculation. The unit is taken and set from and to the set time flux profile, respectively.

property parameter_names

The tuple holding the names of the math function’s parameters. This is the total set of parameter names for all flux profiles of this FactorizedFluxModel instance.

__call__(alpha, delta, E, t, angle_unit=None, energy_unit=None, time_unit=None)

Calculates the flux values for the given celestrial positions, energies, and observation times.

Parameters:

  • alpha (float | (Ncoord,)-shaped 1d numpy ndarray of float) – The right-ascention coordinate for which to retrieve the flux value.

  • delta (float | (Ncoord,)-shaped 1d numpy ndarray of float) – The declination coordinate for which to retrieve the flux value.

  • E (float | (Nenergy,)-shaped 1d numpy ndarray of float) – The energy for which to retrieve the flux value.

  • t (float | (Ntime,)-shaped 1d numpy ndarray of float) – The observation time for which to retrieve the flux value.

  • angle_unit (instance of astropy.units.UnitBase | None) – The unit of the given angles. If None, the set angle unit of the spatial flux profile is assumed.

  • energy_unit (instance of astropy.units.UnitBase | None) – The unit of the given energies. If None, the set energy unit of the energy flux profile is assumed.

  • time_unit (instance of astropy.units.UnitBase | None) – The unit of the given times. If None, the set time unit of the time flux profile is assumed.

Returns:

flux ((Ncoord,Nenergy,Ntime)-shaped ndarray of float) – The flux values are in unit [energy]^{-1} [angle]^{-2} [length]^{-2} [time]^{-1}.

set_parameters(pdict)

Sets the parameters of the flux model. For this factorized flux model it means that it sets the parameters of the spatial, energy, and time profiles.

Parameters:

pdict (dict) – The flux parameter dictionary.

Returns:

updated (bool) – Flag if parameter values were actually updated.

class skyllh.physics.flux_model.IsPointlikeSource(ra_func_instance=None, get_ra_func=None, set_ra_func=None, dec_func_instance=None, get_dec_func=None, set_dec_func=None, **kwargs)

Bases: object

This is a classifier class that can be used by other classes to indicate that the specific class describes a point-like source.

Constructor method. Gets called when the an instance of a class is created which derives from this IsPointlikeSource class.

property ra

The right-ascention coordinate of the point-like source.

property dec

The declination coordinate of the point-like source.

class skyllh.physics.flux_model.PointlikeSourceFFM(alpha_s, delta_s, Phi0, energy_profile, time_profile, angle_unit=None, length_unit=None)

Bases: FactorizedFluxModel, IsPointlikeSource

This class describes a factorized flux model (FFM), where the spatial profile is modeled as a point. This class provides the base class for a flux model of a point-like source.

Creates a new factorized flux model for a point-like source.

Parameters:

  • alpha_s (float) – The right-ascention of the point-like source.

  • delta_s (float) – The declination of the point-like source.

  • Phi0 (float) – The flux normalization constant in unit of flux.

  • energy_profile (EnergyFluxProfile instance | None) – The EnergyFluxProfile instance providing the energy profile function of the flux. If set to None, an instance of UnityEnergyFluxProfile will be used, which represents the constant function 1.

  • time_profile (TimeFluxProfile instance | None) – The TimeFluxProfile instance providing the time profile function of the flux. If set to None, an instance of UnityTimeFluxProfile will be used, which represents the constant function 1.

  • angle_unit (instance of astropy.units.UnitBase | None) – The unit for angles used for the flux unit. If set to None, the configured internal angle unit is used.

  • length_unit (instance of astropy.units.UnitBase | None) – The unit for length used for the flux unit. If set to None, the configured internal length unit is used.

class skyllh.physics.flux_model.SteadyPointlikeSourceFFM(alpha_s, delta_s, Phi0, energy_profile, angle_unit=None, length_unit=None, time_unit=None)

Bases: PointlikeSourceFFM

This class describes a factorized flux model (FFM), where the spatial profile is modeled as a point and the time profile as constant 1. It is derived from the PointlikeSourceFFM class.

Creates a new factorized flux model for a point-like source with no time dependance.

Parameters:

  • alpha_s (float) – The right-ascention of the point-like source.

  • delta_s (float) – The declination of the point-like source.

  • Phi0 (float) – The flux normalization constant.

  • energy_profile (EnergyFluxProfile instance | None) – The EnergyFluxProfile instance providing the energy profile function of the flux. If set to None, an instance of UnityEnergyFluxProfile will be used, which represents the constant function 1.

__call__(alpha, delta, E, angle_unit=None, energy_unit=None)

Calculates the flux values for the given celestrial positions, and energies.

Parameters:

  • alpha (float | (Ncoord,)-shaped 1d numpy ndarray of float) – The right-ascention coordinate for which to retrieve the flux value.

  • delta (float | (Ncoord,)-shaped 1d numpy ndarray of float) – The declination coordinate for which to retrieve the flux value.

  • E (float | (Nenergy,)-shaped 1d numpy ndarray of float) – The energy for which to retrieve the flux value.

  • angle_unit (instance of astropy.units.UnitBase | None) – The unit of the given angles. If None, the set angle unit of the spatial flux profile is assumed.

  • energy_unit (instance of astropy.units.UnitBase | None) – The unit of the given energies. If None, the set energy unit of the energy flux profile is assumed.

Returns:

flux ((Ncoord,Nenergy)-shaped ndarray of float) – The flux values are in unit [energy]^{-1} [angle]^{-2} [length]^{-2} [time]^{-1}.

skyllh.physics.model module

This module defines the base classes for any physics models used by SkyLLH.

class skyllh.physics.model.PhysicsModel(name=None)

Bases: object

This class provides a base class for all physics models like source models or background models.

Creates a new PhysicsModel instance.

Parameters:

name (str | None) – The name of the physics model. If set to None, the id of the object is taken as name.

property name

The name of the physics model.

property id

(read-only) The ID of the physics model. It’s an integer generated with Python’s id function. Hence, it’s related to the memory address of the object.

class skyllh.physics.model.PhysicsModelCollection(model_type=None, models=None)

Bases: ObjectCollection

This class describes a collection of PhysicsModel instances. It can be used to group several physics models into a single object.

Creates a new PhysicsModel collection. The type of the physics model instances the collection holds can be restricted, by setting the model_type parameter.

Parameters:

  • model_type (type | None) – The type of the physics model. If set to None (default), PhysicsModel will be used.

  • models (sequence of model_type instances | None) – The sequence of physics models this collection should be initalized with.

static cast(obj, errmsg)

Casts the given object to a PhysicsModelCollection object. If the cast fails, a TypeError with the given error message is raised.

Parameters:

  • obj (PhysicsModel instance | sequence of PhysicsModel instances |) – PhysicsModelCollection | None The object that should be casted to PhysicsModelCollection.

  • errmsg (str) – The error message if the cast fails.

Raises:

TypeError – If the cast fails.

Returns:

physmodelcollection (instance of PhysicsModelCollection) – The created PhysicsModelCollection instance. If obj is already a PhysicsModelCollection instance, it will be returned.

property model_type

(read-only) The type of the physics model.

property models

(read-only) The list of models of type model_type.

skyllh.physics.source module

The source module contains the base class SourceModel for modelling a source in the sky. What kind of properties this source has is modeled by a derived class. The most common one is the PointLikeSource source model for a point-like source at a given location in the sky with a given flux model.

class skyllh.physics.source.SourceLocation(ra, dec)

Bases: object

Stores the location of a source, i.e. right-ascention and declination.

property ra

The right-ascention angle in radian of the source position.

property dec

The declination angle in radian of the source position.

class skyllh.physics.source.SourceWeights(src_w=None, src_w_grad=None, src_w_W=None)

Bases: object

Stores the relative weights of a source, i.e. weights and gradients. There are two weights that should be included. one is the detector weight, which is declination dependent, and the other is a hypothesis weight, and that is provided by the user.

property src_w

The relative weight of the source(s).

property src_w_grad

The relative weight gradients of the source(s).

property src_w_W

The hypothesis weight of the source(s).

class skyllh.physics.source.SourceModel(ra, dec, src_w=None, src_w_grad=None, src_w_W=None)

Bases: object

The base class for all source models in Skyllh. Each source has a central location given by a right-ascention and declination location.

property loc

The location of the source.

property weight

The weight of the source.

property id

(read-only) The ID of the source. It’s an integer generated with the id() function. Hence, it’s related to the memory address of the object.

class skyllh.physics.source.SourceCollection(source_type=None, sources=None)

Bases: ObjectCollection

This class describes a collection of sources. It can be used to group sources into a single object, for instance for a stacking analysis.

Creates a new source collection.

Parameters:

  • source_type (type | None) – The type of the source. If set to None (default), SourceModel will be used.

  • sources (sequence of source_type instances | None) – The sequence of sources this collection should be initalized with.

static cast(obj, errmsg)

Casts the given object to a SourceCollection object. If the cast fails, a TypeError with the given error message is raised.

Parameters:
Raises:

TypeError – If the cast fails.

property source_type

(read-only) The type of the source model.

property sources

(read-only) The list of sources of type source_type.

class skyllh.physics.source.Catalog(name, source_type=None, sources=None)

Bases: SourceCollection

This class describes a catalog of sources. It is derived from SourceCollection. A catalog has a name.

Creates a new source catalog.

Parameters:

  • name (str) – The name of the catalog.

  • source_type (type | None) – The type of the source. If set to None (default), the default type defined by SourceCollection will be used.

  • sources (sequence of source_type | None) – The sequence of sources this catalog should be initalized with.

property name

The name of the catalog.

as_source_collection()

Creates a SourceCollection object for this catalog and returns it.

class skyllh.physics.source.PointLikeSource(ra, dec, src_w=None, src_w_grad=None, src_w_W=None)

Bases: SourceModel

The PointLikeSource class is a source model for a point-like source object in the sky at a given location (right-ascention and declination).

property ra

(read-only) The right-ascention angle in radian of the source position. This is a short-cut for self.loc.ra.

property dec

(read-only) The declination angle in radian of the source position. This is a short-cut for self.loc.dec.

class skyllh.physics.source.PointLikeSourceCollection(sources=None)

Bases: SourceCollection

Describes a collection of point-like sources.

Creates a new collection of PointLikeSource objects.

Parameters:

sources (sequence of PointLikeSource instances | None) – The sequence of PointLikeSource objects this collection should be initalized with.

property ra

(read-only) The ndarray with the right-ascention of all the sources.

property dec

(read-only) The ndarray with the declination of all the sources.

class skyllh.physics.source.PointLikeSourceCatalog(name, sources=None)

Bases: Catalog

Describes a catalog of point-like sources. The difference to a PointLikeSourceCollection is the additional properties of a catalog, e.g. the name.

Creates a new point source catalog of the given name.

Parameters:

  • name (str) – The name of the point-like source catalog.

  • sources (sequence of PointLikeSource instances | None) – The sequence of PointLikeSource instances this catalog should be initalized with.

skyllh.physics.time_profile module

class skyllh.physics.time_profile.TimeProfileModel(t_start, t_end)

Bases: object

Abstract base class for an emission time profile of a source.

Creates a new time profile instance.

Parameters:

  • t_start (float) – The MJD start time of the box profile.

  • t_end (float) – The MJD end time of the box profile.

property t_start

The MJD start time of the box profile.

property t_end

The MJD end time of the box profile.

property duration

The duration (in days) of the time profile.

abstract move(dt)

Abstract method to move the time profile by the given amount of time.

Parameters:

dt (float) – The MJD time difference of how far to move the time profile in time. This can be a positive or negative time shift.

abstract update(fitparams)

This method is supposed to update the time profile based on new fit parameter values. This method should return a boolean flag if an update was actually performed.

Returns:

updated (bool) – Flag if the time profile actually got updated because of new fit parameter values.

abstract get_integral(t1, t2)

This method is supposed to calculate the integral of the time profile from time t1 to time t2.

Parameters:

  • t1 (float | array of float) – The MJD start time of the integration.

  • t2 (float | array of float) – The MJD end time of the integration.

Returns:

integral (array of float) – The integral value(s) of the time profile.

abstract get_total_integral()

This method is supposed to calculate the total integral of the time profile from t_start to t_end.

Returns:

integral (float) – The integral value of the entire time profile.

abstract get_value(t)

Retrieves the value of the time profile at time t.

Parameters:

t (float) – The MJD time for which the time profile value should get retrieved.

Returns:

value (float) – The time profile value at the given time.

class skyllh.physics.time_profile.BoxTimeProfile(T0, Tw)

Bases: TimeProfileModel

The BoxTimeProfile describes a box-shaped emission time profile of a source. It has the following fit parameters:

T0float

The mid MJD time of the box profile.

Twfloat

The width (days) of the box profile.

Creates a new box-shaped time profile instance.

Parameters:

  • T0 (float) – The mid MJD time of the box profile.

  • Tw (float) – The width (days) of the box profile.

move(dt)

Moves the box-shaped time profile by the time difference dt.

Parameters:

dt (float) – The MJD time difference of how far to move the time profile in time. This can be a positive or negative time shift.

property T0

The time of the mid point of the box.

property Tw

The time width (in days) of the box.

update(fitparams)

Updates the box-shaped time profile with the new fit parameter values.

Parameters:

fitparams (dict) – The dictionary with the new fit parameter values. The key must be the name of the fit parameter and the value the new parameter value.

Returns:

updated (bool) – Flag if the time profile actually got updated because of new fit parameter values.

get_integral(t1, t2)

Calculates the integral of the box-shaped time profile from MJD time t1 to time t2.

Parameters:

  • t1 (float | array of float) – The MJD start time(s) of the integration.

  • t2 (float | array of float) – The MJD end time(s) of the integration.

Returns:

integral (array of float) – The integral value(s).

get_total_integral()

Calculates the the total integral of the box-shaped time profile from t_start to t_end. By definition it is 1.

Returns:

integral (float) – The integral value of the entire time profile.

get_value(t)

Retrieves the value of the box-shaped time profile at time t. For a box-shaped time profile the values are all equal to 1/duration for times within the time duration and zero otherwise.

Parameters:

t (float | array of float) – The MJD time(s) for which the time profile value(s) should get retrieved.

Returns:

values (array of float) – The time profile value(s) at the given time(s).