superbol package

superbol.bc_polynomial module

superbol.bc_polynomial.calc_bolometric_correction(color_value, color_err, color_type)

Calculates the bolometric correction, using a polynomial fit.

Parameters:

• color_value (float) – B-V, V-I, or B-I color of the supernova in magnitudes (corrected for reddening and extinction from the host and MWG.)
• color_err (float) – Uncertainty in the photometric color.
• color_type (str) – String signifying which color color_value represents. Valid values are “BminusV” for B-V, “VminusI” for V-I, and “BminusI” for B-I.

Returns:

A tuple containing the bolometric correction for use in calculating the bolometric luminosity of the supernova, and the uncertainty in that bolometric correction (if the color given is within the valid range of the polynomial fit.)

(bolometric_correction, uncertainty)

(-999, -999) if the color is outside the valid range.

Return type:

tuple

superbol.bc_polynomial.calc_bolometric_correction_err(color_value, color_err, color_type)

Calculates the uncertainty in the bolometric correction.

Two uncertainties are added in quadrature to get the total uncertainty in the bolometric correction. The first is uncertainty in the BC due to uncertainties in the measured color value (simple error propagation using a derivative.) The second is the RMS error inherent in the polynomial fit to the template data as reported in Bersten & Hamuy (2009.)

Parameters:

• color_value (float) – B-V, V-I, or B-I color of the supernova in magnitudes (corrected for reddening and extinction from the host and MWG.)
• color_err (float) – Uncertainty in the photometric color.
• color_type (str) – String signifying which color color_value represents.

Returns:

Uncertainty in the value of the bolometric correction

Return type:

float

superbol.bc_polynomial.calculate_polynomial(coefficients, variable)

Calculates a polynomial.

Parameters:

• coefficients (list) – list of polynomial coefficients. The length of the list will be used as the order of the polynomial.
• variable (float) – float to plug in for the variable in the polynomial.

Returns:

The result of summing the polynomial terms calculated from the coefficients and variable given.

Return type:

float

superbol.bc_polynomial.calculate_polynomial_derivative(coefficients, variable)

Calculates the derivative of a polynomial.

Parameters:

• coefficients (list) – List of polynomial coefficients. The length of the list will be used as the order of the polynomial.
• variable (float) – Value to plug in for the variable in the polynomial.

Returns:

The result of summing the derivatives of the polynomial terms calculated from the coefficients and variable given.

Return type:

float

superbol.bc_polynomial.calculate_polynomial_derivative_term(coefficient, variable, order)

Calculates the derivative of the nth order term of a polynomial.

Parameters:

• coefficient (float) – The coefficient of the nth order term in the polynomial
• variable (float) – float to plug in for the variable in the polynomial
• order (int) – order of the nth order term in the polynomial (so, n.)

Returns:

The result of taking the derivative of the nth order term a polynomial,

\(n \cdot \text{coefficient} \cdot \text{variable}^{n-1}\)

So, the edge case of taking the derivative of the zeroth-order term is taken care of, since you explicity multiply by the order of the polynomial (which is zero in the n = 0 case.)

Return type:

float

Raises:

TypeError – A non-integer was passed as the order.

superbol.bc_polynomial.calculate_polynomial_term(coefficient, variable, order)

Calculates a term in a polynomial.

Parameters:

• coefficient (float) – The coefficient to use in calculating the polynomial term.
• variable (float) – Value to plug in for the variable in the polynomial term.
• order (int) – Integer to use as the order of the polynomial term.

Returns:

The result of coefficient * variable**(order)

Return type:

float

Raises:

TypeError – A non-integer order is given.

superbol.bc_polynomial.quadrature_sum(x, y)

Calculate the quadrature sum of two variables x and y.

Parameters:

• x (float) – Variable to include in the quadrature sum
• y (float) – Variable to include in the quadrature sum

Returns:

Result of calculating \(\sqrt{x^2 + y^2}\)

Return type:

float

superbol.bc_polynomial.set_constants(color_type)

Sets the coefficients, validty range, and rms error of fit.

Parameters:

color_type (str) – A string specifying the color combination. Must be “BminusV” for B-V, “VminusI” for V-I, or “BminusI” for B-I.

Returns:

A tuple containing the list of coefficients for the polynomial fit which correspond to the supplied color, the minimum value of the color for which the polynomial is valid, the maximum value of the color for which the polynomial is valid, and the rms error of the polynomial fit for the supplied color.

([coefficients], min, max, rms_error)

Return type:

tuple

Raises:

• TypeError – The argument given is not a string
• ValueError – The argument given is not one of the three valid strings.

superbol.bc_polynomial.valid_color(color_value, range_min, range_max)

Checks that the color value is within the range of validity.

Each polynomial fit has a different range of validity. We need to make sure that the color we are feeding in is inside that range.

Parameters:

• color_value (float) – B-V, V-I, or B-I color of the supernova in magnitudes (corrected for reddening and extinction from the host and MWG.)
• range_min (float) – Minumum value of the color range over which the fit is valid
• range_max (float) – Maxumum value of the color range over which the fit is valid

Returns:

True if the color value is within the valid range. False if the volor value is outside the valid range.

Return type:

bool

superbol.constants module

Constants for use by the bolometric correction routine

superbol.fbol module

superbol.fbol.integrate_fqbol(wavelengths, fluxes, flux_uncertainties)

Calculate the trapezoidal rule integral of the observed fluxes.

The trapezoidal rule integrates the data by assuming the function is linear between observed points, and then integrates under those line segments. The numpy function trapz is used to perform the integration, but the uncertainty in the integral due to uncertainties in the observed flux is calculated by hand using standard error propagation techniques.

Parameters:

• wavelengths (list) – List of wavelengths at which the flux was observed.
• fluxes (list) – List of observed fluxes.
• flux_uncertainties (list) – List of uncertainties in each observed flux.

Returns:

2-tuple of floats.

• The value of the integral
• The uncertainty in the integral due to uncertainties in the fluxes.

(fqbol, fqbol_uncertainty)

Return type:

tuple

superbol.fbol.ir_correction(temperature, T_err, angular_radius, rad_err, longest_wl)

Apply correction for unobserved flux in the IR.

After the temperature and angular radius has been found through fitting a blackbody to the observed fluxes, this function takes those values and integrates under the fitted blackbody function from the longest observed wavelength out to \(\lambda = \infty\).

Parameters:

• temperature (float) – Best fit blackbody temperature in Kelvin
• T_err (float) – Uncertainty in best fit blackbody temperature in Kelvin
• angular_radius (float) – Best fit blackbody angular radius
• rad_err (float) – Uncertainty in best fit blackbody angular radius
• longest_wl (float) – Longest observed wavelength

Returns:

2-tuple

• (float): The IR correction in \(erg \; s^{-1} cm^{-2}\)
• (float): The uncertainty in the IR correction in the same units

Return type:

tuple

superbol.fbol.uv_correction_blackbody(temperature, T_err, angular_radius, rad_err, shortest_wl)

Apply correction for unobserved flux in the UV using the blackbody fit.

After the temperature and angular radius have been found through fitting a blackbody to the observed fluxes, this function takes those values and integrates under the fitted blackbody from the shortest observed wavelength down to \(\lambda = 0\).

Parameters:

• temperature (float) – Best fit blackbody temperature in Kelvin
• T_err (float) – Uncertainty in best fit blackbody temperature in Kelvin
• angular_radius (float) – Best fit blackbody angular radius
• rad_err (float) – Uncertainty in best fit blackbody angular radius
• shortest_wl (float) – Shortest observed wavelength

Returns:

2-tuple

• (float): The UV correction in \(erg \; s^{-1} cm^{-2}\)
• (float): The uncertainty in the UV correction in the same units

Return type:

tuple

superbol.fbol.uv_correction_linear(shortest_wl, shortest_flux, shortest_flux_err)

Apply correction for unobserved flux in the UV using a linear function.

This function integrates under a straight line from the shortest observed wavelength down to \(f(\lambda) = 0\) at \(\lambda = 2000\) Angstroms. This approximates the effects of line blanketing in the UV as in Bersten & Hamuy (2009).

Parameters:

• shortest_wl (float) – Shortest observed wavelength
• shortest_flux (float) – Flux at shortest observed wavelength
• shortest_flux_err (float) – Uncertainty in the shortest observed flux

Returns:

2-tuple

• (float): The UV correction in \(erg \; s^{-1} cm^{-2}\)
• (float): The uncertainty in the UV correction in the same units

Return type:

tuple

superbol.fit_blackbody module

superbol.fit_blackbody.bb_fit_parameters(wavelengths, fluxes, flux_uncertainties)

Fit a blackbody to observed wavelengths and fluxes.

The initial guesses for the temperature and angular_radius are \(T = 5000\) K and \(\theta = 1.0 \times 10^{-10}\). These are typical for an extragalactic supernovae, but should be used with caution for any other objects.

Parameters:

• wavelengths (list) – List of wavelengths at which the fluxes were observed.
• fluxes (list) – List of observed monochromatic fluxes.

Returns:

Tuple containing the best fit temperature, angular_radius, as well as perr, a 2-tuple containing the temperature error and the angular_radius error.

(temperature, angular_radius, perr)

Return type:

tuple

superbol.fit_blackbody.bb_flux(wavelength, temperature, angular_radius)

Observed flux at wavelength from a blackbody of temperature and angular_radius in cgs units

Parameters:

• wavelength (float) – Wavelength in Angstroms
• temperature (float) – Temperature in Kelvin
• angular_radius (float) – Angular radius \((\theta = \frac{R}{D})\)

Returns:

blackbody flux in \(erg \; s^{-1} cm^{-2} Anstrom^{-1}\)

Return type:

Astropy Quantity

superbol.fit_blackbody.bb_flux_integrated(wavelength, temperature, angular_radius)

Integrate the planck function from \(\lambda = 0\) to \(\lambda =\) wavelength, then convert result to observed flux

Parameters:

• wavelength (float) – Wavelength in Angstroms
• temperature (float) – Temperature in Kelvin
• angular_radius (float) – Angular radius \((\theta = \frac{R}{D})\)

Returns:

Value of the integrated flux in \(erg \; s^{-1} cm^{-2}\)

Return type:

float

superbol.fit_blackbody.bb_flux_nounits(wavelength, temperature, angular_radius)

Identical to bb_flux, but returns the value rather than the Astropy Quantity.

This function is needed because curve_fit() does not play nice with functions that return Astropy quantities.

superbol.fit_blackbody.bb_total_flux(temperature, angular_radius)

Integrate the planck function from \(\lambda = 0\) to \(\lambda = \infty\), then convert result to observed flux.

The calculation is done using the Stefan-Boltxmann law, rather than performing an actual integral using numerical integration. The angular_radius is included to convert the result to an observed flux.

Parameters:

• temperature (float) – Temperature in Kelvin
• angular_radius (float) – Angular radius \((\theta = \frac{R}{D})\)

Returns:

The value of \(\sigma \frac{R^2}{D^2} T^4\)

Return type:

float

superbol.fit_blackbody.dbb_flux_integrated_dT(wavelength, temperature, angular_radius)

Take the derivative of the integrated planck function, then convert result to observed flux. This is used in error propagation calculations.

Parameters:

• wavelength (float) – Wavelength in Angstroms
• temperature (float) – Temperature in Kelvin
• angular_radius (float) – Angular radius \((\theta = \frac{R}{D})\)

Returns:

Derivative of the integrated blackbody flux at wavelength with respect to temperature

Return type:

float

superbol.fit_blackbody.dbb_total_flux_dT(temperature, angular_radius)

Take the derivative of the total blackbody flux with respect to temperature

The calculation takes a derivative of the Stefan-Boltzmann law with respect to temperature. The angular_radius is present to convert the result to an observed flux.

Parameters:

• temperature (float) – Temperature in Kelvin
• angular_radius (float) – Angular radius \((\theta = \frac{R}{D})\)

Returns:

The value of \(4 \sigma \frac{R^2}{D^2} T^3\)

Return type:

float

superbol.luminosity module

superbol.luminosity.calc_4piDsquared(distance, distance_err)

Calculates \(4\pi D^2\), to convert flux to luminosity.

Parameters:

• distance (float) – The distance to the supernova in centimeters.
• distance_err (float) – The uncertainty in the distance to the supernova.

Returns:

A tuple containing the \(4 \pi D^2\), and the uncertainty of this number.

(4piDsquared, uncertainty)

Return type:

tuple

superbol.luminosity.calc_Fbol(color_value, color_err, color_type, v_magnitude, v_magnitude_err)

Calculates the bolometric flux of a Type II-P supernova.

Parameters:

• color_value (float) – B-V, V-I, or B-I color of the supernova in magnitudes (corrected for reddening and extinction from the host and MWG.)
• color_err (float) – Uncertainty in the photometric color.
• color_type (str) – String signifying which color color_value represents. Valid values are “BminusV” for B-V, “VminusI” for V-I, and “BminusI” for B-I.
• v_magnitude (float) – Photometric magnitude in the V band, corrected for host + MWG extinction.
• v_magnitude_err (float) – Uncertainty in the V band magnitude after correction for host + MWG extinction.

Returns:

A tuple containing the bolometric flux used when calculating the bolometric luminosity, and the uncertainty in that number.

(Fbol, uncertainty)

(-999, -999) if the bolometric correction calculated from the color_value and color_type is -999 (which means the observed color is outside the range of validity of the polynomial fit.)

Return type:

tuple

superbol.luminosity.calc_Lbol(color_value, color_err, color_type, v_magnitude, v_magnitude_err, distance, distance_err)

Calculates the bolometric luminosity of a Type II-P Supernova.

Parameters:

• color_value (float) – B-V, V-I, or B-I color of the supernova in magnitudes (corrected for reddening and extinction from the host and MWG.)
• color_err (float) – Uncertainty in the photometric color.
• color_type (str) – String signifying which color color_value represents. Valid values are “BminusV” for B-V, “VminusI” for V-I, and “BminusI” for B-I.
• v_magnitude (float) – Photometric magnitude in the V band, corrected for host + MWG extinction.
• v_magnitude_err (float) – Uncertainty in the V band magnitude after correction for host + MWG extinction.
• distance (float) – The distance to the supernova in centimeters.
• distance_err (float) – The uncertainty in the distance to the supernova.

Returns:

A tuple containing the bolometric luminosity in ergs per second, and the uncertainty in that value.

(Lbol, uncertainty)

(-999, -999) if the bolometric correction is -999 (which means the observed color value is outside the range of vaidity of the polynomial fit used to determine the bolometric correction.)

Return type:

tuple

superbol.mag2flux module

superbol.mag2flux.mag2flux(magnitude, uncertainty, effective_wl, flux_at_zero_mag)

Converts an observed magnitude in a filter band to an average flux.

Parameters:

• magnitude (float) – Apparent magnitude.
• uncertainty (float) – Apparent magnitude uncertainty.
• effective_wl (float) – Effective wavelength of the filter.
• flux_at_zero_mag (float) – Flux at zero magnitude of the filter.

Returns:

A tuple of two floats:

• the flux in \(erg \; s^{-1} cm^{-2} Angstrom^{-1}\)
• the flux uncertainty in \(erg \; s^{-1} cm^{-2} Angstrom^{-1}\)

(flux, flux_uncertainty)

Return type:

tuple

superbol.planck module

superbol.planck.d_planck_integral_dT(wavelength, temperature)

Derivative of the integrated Planck function from \(\lambda = 0\) to \(\lambda =\) wavelength using the infinite series approximation of the integral. This is used in the error propagation calculation.

Parameters:

• wavelength (float) – Upper bound for the wavelength in Angstrom.
• temperature (float) – Temperature in Kelvin.

Returns:

Derivative of the integral of the planck function with respect to T in \(erg \; s^{-1} cm^{-2} sterad^{-1} K^{-1}\)

Return type:

Astropy Quantity

superbol.planck.planck_function(wavelength, temperature)

Planck function at given wavelength and temperature in cgs.

The specific intensity of radiation from a blackbody source is given by:

\(B_{\lambda}(\lambda, T) = \displaystyle\frac{C_1}{\lambda^5} \frac{1}{e^{\frac{C_2}{\lambda T}} - 1}\)

where \(C_1 = 2hc^2\) and \(C_2 = hc/k_B\) are the first and second radiation constants.

Parameters:

• wavelength (float) – Wavelength in Angstrom
• tempereature (float) – Temperature in Kelvin

Returns:

The specific intensity of the Planck function in \(erg \; s^{-1} cm^{-2} sterad^{-1} Angstrom^{-1}\)

Return type:

Astropy Quantity

superbol.planck.planck_integral(wavelength, temperature)

Integrate the Planck function over a finite wavelength interval.

The integral is taken from \(\lambda = 0\) to \(\lambda =\) wavelength using the infinite series approximation of the integral:

\(\displaystyle\int_{0}^{\lambda_1} B_{\lambda}(\lambda, T) \; d\lambda = \frac{C_1 T^4}{C_2^4} \sum_{n = 1}^{\infty}\left(\frac{x_1^3}{n} + \frac{3x_1^2}{n^2} + \frac{6x_1}{n^3} + \frac{6}{n^4}\right) e^{-nx_1}\)

where \(C_1 = 2hc^2\) and \(C_2 = hc/k_B\) are the first and second radiation constants, and \(x_1 = C_2/\lambda_1 T\) is a change of variables to make the integral easier to represent in this series form.

Parameters:

• wavelength (float) – Upper bound for the wavelength in Angstrom.
• temperature (float) – Temperature in Kelvin.

Returns:

Integral of the planck function in \(erg \; s^{-1} cm^{-2} sterad^{-1}\)

Return type:

Astropy Quantity

superbol.sn module

class superbol.sn.SN(name)

Bases: object

A supernova is the explosion that ends the life of a star

The SN needs to be conatained within the HDF5 database before it is used by SNoBoL. Once there, simply create a supernova by calling the constructor with the name of the SN as a string of the form “sn[YEAR][Letter(s)]”

name

str

Name of the supernova, “sn” followed by the year of first observation along with a letter designating the order of observation in that year. “sn1987a” was the first SN observed in 1987. “sn2000cb” was the eightieth SN observed in 2000.

Examples

An example which calculates the quasi-bolometric luminosity using trapezoidal integration:

>>> my_supernova = SN('sn1998a')
>>> my_supernova.lqbol()

In order to coorect for unobserved flux in the UV and IR, using the method of Bersten & Hamuy (2009), do the following:

>>> my_supernova.lbol_direct_bh09()

Finally, to calculate the bolometric luminosity using bolometric corrections based on two-filter colors as in Bersten & Hamuy (2009):

>>> my_supernova.lbol_bc_bh09(filter1, filter2)

where filter1 and filter2 are strings designating the filter to use. The acceptable filter combinations at this time are limited to

Color	filter1	filter2
B-V	“B”	“V”
V-I	“V”	“I”
B-I	“B”	“I”

convert_magnitudes_to_fluxes()

Perform the magnitude to flux conversion.

Creates an array of [jd, name, wavelength, flux, uncertainty]

deredden_UBVRI_magnitudes()

Apply the corrections from CCM89 (1989ApJ...345..245C), Table 3 to the observed photometric magnitudes.

IMPORTANT: This will only deredden the UBVRI magnitudes at the moment

deredden_fluxes()

Deredden the observed fluxes using the ccm89 model

The dereddening procedure is handled by the extinction.reddening method from specutils.

get_bc_color(jd, filter1, filter2)

Make an array of filter1 - filter2 on each of the bc_epochs

Parameters:

• jd (float) – Julian Date of the observation
• filter1 (str) – Sring designation for filter 1 (“B”, for example)
• filter2 (str) – String designation for filter 2 (“V”, for example)

Returns:

Magnitude of filter 1 minus the magnitude of filter 2.

Return type:

float

get_bc_color_uncertainty(jd, filter1, filter2)

Make an array of \(\sqrt{(\delta \text{filter1})^2 - (\delta \text{filter2})^2}\) on each of the bc_epochs

Parameters:

• jd (float) – Julian Date of the observation
• filter1 (str) – Sring designation for filter 1 (“B”, for example)
• filter2 (str) – String designation for filter 2 (“V”, for example)

Returns:

Quadrature sum of the uncertainties in the magnitudes of filter 1 and filter 2.

Return type:

float

get_bc_epochs(filter1, filter2)

Get epochs for which observations of both filter1 and filter2 exist

get_distance_cm()

Get the distance to the supernova in centimeters from the HDF5 file.

Returns:2-tuple

• (float) distance to the supernova in cm
• (float) uncertainty in the distance to the supernova in cm

Return type:tuple

get_lbol_epochs()

Get only epochs with enough photometric data to calculate Lbol

The minimum number of filters needed to calculate a luminosity is set in the __init__ mehod.

get_magnitudes()

Build a numpy array of [jd, name, magnitude, uncertainty] from the data contained within the HDF5 file.

lbol_bc_bh09(filter1, filter2)

Calculate the bolometric lightcurve using the bolometric corrections found in Bersten & Hamuy 2009 (2009ApJ...701..200B). These require specifying a color, taken to be filter1 - filter2

lbol_direct_bh09()

Calculate the bolometric lightcurve using the direct integration method published in Bersten & Hamuy 2009 (2009ApJ...701..200B)

lqbol()

Calculate the quasi-bolometric lightcurve using direct integration with trapezoidal integration of the fluxes

read_hdf5()

Reads the hdf5 file and returns data on supernova matching [name]

write_lbol_plaintext(lightcurve, suffix)

Write the lightcurve to a file. Append suffix to filename