HowManyPhotons 0.3.0

Tiny repo to calculate astronomical photon counts for various instruments

[!NOTE] The python package must be called using the abbreviation hmbp.

The abbreviation ("how many bloody photons") is an expression of the authors frustration with the various convoluted legacy units still used in modern day Astronomy.

Install

pip install HowManyPhotons

Basic usage

HowManyPhotons is mainly used to determine how many photons fall within the wavelength range of any instrument filter contained in the spanish VO filter database.

from astropy import units as u
import hmbp

hmbp.for_flux_in_filter("V", 10*u.ABmag)
hmbp.convert(from_quantity=10*u.mJy, to_unit=u.mag, filter_name="J", 
             instrument="HAWKI", observatory="Paranal")

Input and output units

hmbp accepts and converts between u.mag (Vega), u.ABmag and u.Jy.

ALL functions return photons counts in units of [ph s-1 m-2].

[!WARNING] ONLY the filter curve is included in the calclutation. The following instrumental transmission profiles are NOT included in the photon flux calculation:

• atmospheric transmission
• mirror reflection
• detector quantum efficiency

These spectral profiles may be included in later releases of HowManyBloodyPhotons, but they are currently NOT considered.

Main functions

The are two main functions: for_flux_in_filter and convert:

hmbp.for_flux_in_filter

Returns the number of incoming photons through a specific filter. If no instrument and observatory are provided, hmbp looks for a corresponding filter_name in the dictionary hmbp.FILTER_DEFAULTS.

The result is an astropy.Quantity with the units [ph s-1 m-2].

Function signature:

hmbp.for_flux_in_filter(filter_name, flux, instrument=None, observatory=None)

Some short examples:

hmbp.for_flux_in_filter("V", 10*u.ABmag)
hmbp.for_flux_in_filter("Ks", 20*u.mag, instrument="HAWKI", observatory="Paranal")
hmbp.for_flux_in_filter("Si6", 1*u.Jy, instrument="Michelle", observatory="Gemini")

hmbp.convert

Converts one common flux unit into another common flux: (mag, ABmag, Jy)

Function signature:

hmbp.convert(from_quantity, to_unit, filter_name, instrument=None, observatory=None)

Some short examples:

hmbp.convert(10*u.mag, u.Jy, "BrGamma")
hmbp.convert(from_quantity=0*u.mag, to_unit=u.ABmag, filter_name="J",
             instrument="HAWKI", observatory="Paranal")

Convenience functions

We have also provided a few helper functions for several common flux conversions:

• hmbp.in_zero_vega_mags
• hmbp.in_zero_AB_mags
• hmbp.in_one_jansky
• hmbp.in_skycalc_background

The function signatures follow the same pattern as hmbp.for_flux_in_filter, just without needing to explicitly specify the flux parameter.

Returned units are [ph s-1 m-2]

Some short examples:

hmbp.in_zero_vega_mags("V")
hmbp.in_zero_AB_mags("Ks", "HAWKI", "Paranal")
hmbp.in_one_jansky("NeII", instrument="VISIR", observatory="Paranal")
hmbp.in_skycalc_background("M", airmass=2.0, pwv=5.0)