FlareGenerator

class vspec_vsm.FlareGenerator(dist_teff_mean: ~astropy.units.quantity.Quantity, dist_teff_sigma: ~astropy.units.quantity.Quantity, dist_fwhm_mean: ~astropy.units.quantity.Quantity, dist_fwhm_logsigma: float, alpha: float = -0.829, beta: float = 26.87, min_energy: ~astropy.units.quantity.Quantity = <Quantity 1.e+33 erg>, cluster_size: int = 2, rng: ~numpy.random._generator.Generator = Generator(PCG64) at 0x7F5F71E16CE0)

Bases: object

Generator for flare events and their characteristics.

Parameters:

  • dist_teff_mean (astropy.units.Quantity) – The mean of the temperature distribution.

  • dist_teff_sigma (astropy.units.Quantity) – The standard deviation of the temperature distribution.

  • dist_fwhm_mean (astropy.units.Quantity) – The mean of the FWHM distribution.

  • dist_fwhm_logsigma (float) – The standard deviation of the logorithm of the FWHM distribution in dex.

  • alpha (float, default=-0.829) – The slope of the log frequency - log energy relationship.

  • beta (float, default=26.87) – The y-intercept of the log frequency - log energy relationship.

  • min_energy (astropy.units.Quantity, default=1e33 erg) – The minimum energy to consider. Set to np.inf*u.erg to disable flares.

  • cluster_size (int, default=2) – The typical size of flare clusters.

  • rng (numpy.random.Generator, default=numpy.random.default_rng()) – The random number generator instance to use.

energy_unit
time_unit
temperature_unit
dist_teff_mean

The mean of the temperature distribution.

Type:

astropy.units.Quantity

dist_teff_sigma

The standard deviation of the temperature distribution.

Type:

astropy.units.Quantity

dist_fwhm_mean

The mean of the FWHM distribution.

Type:

astropy.units.Quantity

dist_fwhm_logsigma

The standard deviation of the logorithm of the FWHM distribution in dex.

Type:

float

alpha

The slope of the log frequency - log energy relationship.

Type:

float

beta

The y-intercept of the log frequency - log energy relationship.

Type:

float

min_energy

The minimum energy to consider. Set to np.inf*u.erg to disable flares.

Type:

astropy.units.Quantity

cluster_size

The typical size of flare clusters.

Type:

int

rng

The random number generator instance to use.

Type:

numpy.random.Generator

Notes

Relationship between flare frequency is defined as

\[\log{(f(E \ge E_0)~\text{[day]})} = \beta + \alpha \log{(E_0/\text{[erg]})}\]

by Gao et al. [2022]. Their study of TESS flare rates fits \(\alpha = -0.829\) and \(\beta = 26.87\), which we use as the default values. This relationship is valid for \(E > 10^{33}\) erg, which we use as the default minimum considered energy.

To disable flares, set min_energy to infinity so that the expected number of flares is 0.

Methods

cdf(energy)

Get the cumulative density function.

frequency_greater_than(energy)

The frequency of flares greater than an energy.

gen_coords(n_flares)

Generate a set of random coordinates.

gen_fwhm(n_flares)

Generate a FWHM set in a lognormal distribution.

gen_teffs(n_flares)

Generate a random set of flare temperatures.

generate_flare_series(time)

Generate a series of flares based on the distribution parameters of this generator.

get_nexp_greater_than(energy, time)

Get the expected number of flares with energy greater than energy in a time period time

get_ntotal(time)

Get the total number of flares in a time period.

get_peaks(n_flares)

Generate the times at which each flare reaches its peak.

off([rng])

An instance that does not generate anything.

pdf(energy)

The probability density function of flare energies.

quantile_func(X)

The quantile function of this flare energy distribution.

Attributes Summary

energy_unit

The energy unit to standardize coversions to floats and logs.

temperature_unit

The temperature unit to standardize coversions to floats and logs.

time_unit

The time unit to standardize coversions to floats and logs.

Methods Summary

cdf(energy)

Get the cumulative density function.

frequency_greater_than(energy)

The frequency of flares greater than an energy.

gen_coords(n_flares)

Generate a set of random coordinates.

gen_fwhm(n_flares)

Generate a FWHM set in a lognormal distribution.

gen_teffs(n_flares)

Generate a random set of flare temperatures.

generate_flare_series(time)

Generate a series of flares based on the distribution parameters of this generator.

get_nexp_greater_than(energy, time)

Get the expected number of flares with energy greater than energy in a time period time

get_ntotal(time)

Get the total number of flares in a time period.

get_peaks(n_flares)

Generate the times at which each flare reaches its peak.

off([rng])

An instance that does not generate anything.

pdf(energy)

The probability density function of flare energies.

quantile_func(X)

The quantile function of this flare energy distribution.

Attributes Documentation

energy_unit = Unit("erg")

The energy unit to standardize coversions to floats and logs.

Type:

astropy.units.Quantity

temperature_unit = Unit("K")

The temperature unit to standardize coversions to floats and logs.

Type:

astropy.units.Quantity

time_unit = Unit("d")

The time unit to standardize coversions to floats and logs.

Type:

astropy.units.Quantity

Methods Documentation

cdf(energy: astropy.units.Quantity)

Get the cumulative density function.

Parameters:

energy (astropy.units.Quantity) – The energies at which to sample the cdf.

Returns:

cdf – The cumulative density of energy

Return type:

float or np.ndarray

frequency_greater_than(energy: astropy.units.Quantity)

The frequency of flares greater than an energy.

Parameters:

energy (astropy.units.Quantity) – The energy to compute the frequency of.

Returns:

The frequency of flares with energy greater than energy.

Return type:

astropy.units.Quantity

gen_coords(n_flares)

Generate a set of random coordinates.

Parameters:

n_flares (int) – The number of random temperatures to generate.

Returns:

  • lats (astropy.units.Quantity) – The stellar latitudes of the flares.

  • lons (astropy.units.Quantity) – The stellar longitudes of the flares.

Notes

lats is generated using a quantile function for latitude.

\[\text{lat} = \arcsin(2X - 1)\]

For a random variable \(X\) on [0,1).

gen_fwhm(n_flares: int)

Generate a FWHM set in a lognormal distribution.

Parameters:

n_flares (int) – The number of random FWHM lengths to generate.

Returns:

fwhm – The FWHMs of the flares

Return type:

astropy.units.Quantity

gen_teffs(n_flares)

Generate a random set of flare temperatures.

Parameters:

n_flares (int) – The number of random temperatures to generate.

Returns:

teffs – The temperatures of the flares

Return type:

astropy.units.Quantity

generate_flare_series(time: astropy.units.Quantity)

Generate a series of flares based on the distribution parameters of this generator.

Parameters:

time (astropy.units.Quantity) – The time over which the flares are observed.

Returns:

flares – The flares that occur over time.

Return type:

list of StellarFlare

get_nexp_greater_than(energy: astropy.units.Quantity, time: astropy.units.Quantity) → float

Get the expected number of flares with energy greater than energy in a time period time

Parameters:
Returns:

The number of flares with energy greater than energy.

Return type:

float

get_ntotal(time) → float

Get the total number of flares in a time period.

Parameters:

time (astropy.units.Quantity) – The time duration.

Returns:

The number of flares.

Return type:

float

get_peaks(n_flares) → ndarray

Generate the times at which each flare reaches its peak.

Parameters:

n_flares (int) – The number of peak times to generate.

Returns:

tpeaks – The times that the flares reach their peak in units of the total observation time.

Return type:

np.ndarray

classmethod off(rng: ~numpy.random._generator.Generator = Generator(PCG64) at 0x7F5F71E166C0)

An instance that does not generate anything.

Parameters:

rng (numpy.random.Generator) – The random number generator to use.

pdf(energy: astropy.units.Quantity)

The probability density function of flare energies.

Parameters:

energy (astropy.units.Quantity) – The energies at which to sample the pdf.

Returns:

pdf – The probability density of energy

Return type:

float or np.ndarray

quantile_func(X: ndarray)

The quantile function of this flare energy distribution.

This function maps a variable on the range [0,1) to the distribution defined by \(\beta\) and \(\alpha\).

Parameters:

X (numpy.ndarray) – A random variable with domain [0,1)

Returns:

energy – The energies represented by X.

Return type:

astropy.Units.Quantity