Units#

Units of the scene components, and the conversion to one internal unit.

Two families:

physical   a brightness: any unit astropy converts to Jy (per pixel) or Jy/sr (per solid
           angle) with the spectral_density equivalency, e.g. Jy/arcsec^2, MJy/sr, W/m^2
           per pixel (nu F_nu), erg/s/cm^2/nm per pixel; and photons/s/cm^2/pixel over a band
relative   a fraction of the star's total flux: "contrast_pixel" (per pixel) or
           "contrast/arcsec^2"

The link between them is the star’s flux density F_star (Jy) at the wavelength.

Every component is first put per pixel of its own grid (so that resampling conserves the flux): Jy per pixel, or the fraction of F_star per pixel. The scene’s internal unit is then Jy/arcsec^2 when F_star is known (or every component is physical), else contrast_pixel.

exception toycoronagraph.units.UnitError[source]#

Bases: ValueError

A unit that is unknown, not convertible, or missing information (band, star’s flux) to be converted.

class toycoronagraph.units.SourceImage(data, unit=None, pixel_scale=None, wavelength=None, band=None, origin='', notes=())[source]#

Bases: object

What a source module’s render() returns: an image, its unit and how to place it on the scene grid.

The image must be square and centred on the star (pixel (N-1)/2, rows = +y as in FITS).

Variables:

  • data (np.ndarray or astropy.units.Quantity) – (N, N) image; converted to float64 on creation. A Quantity’s unit replaces unit.

  • unit (str or astropy.units.UnitBase) – a NAMED unit (e.g. “contrast_pixel”, “Jy/arcsec^2”), PHOTONS, or anything astropy reads as a unit; a bare astropy unit without “/pixel” or a solid angle (e.g. u.Jy, dimensionless) is per pixel.

  • pixel_scale (float) – arcsec per pixel of data; None = already on the scene grid (the scene then sets it to the grid’s pixel scale).

  • wavelength (float) – m, the wavelength of a physical image (used by the spectral_density conversions); None = the scene’s wavelength.

  • band (tuple) – (lambda_min, lambda_max) in m, needed only for photon counts (PHOTONS).

  • origin (str) – text naming the image in messages (e.g. the file name).

  • notes (tuple of str) – messages for the user (shown with the scene’s notes).

Raises:

UnitError – when the unit is None and data is not a Quantity.

toycoronagraph.units.per_pixel(img, wavelength)[source]#

The image per pixel of its own grid, in the base unit of its family.

The unit is tried, in order, as a contrast per pixel, a contrast per solid angle (multiplied by the pixel area), a brightness per pixel (-> Jy with the spectral_density equivalency at the wavelength), and a brightness per solid angle (x pixel area -> Jy). Photon counts (PHOTONS) become Jy as F_nu = N h c / lambda / (c/lambda_min - c/lambda_max), i.e. the photons’ energy at the wavelength spread evenly over the band in frequency.

Parameters:

  • img (SourceImage) – with pixel_scale set (arcsec).

  • wavelength (float) – m, used when img.wavelength is None.

Returns:

(family, values): family is “physical” (values in Jy per pixel) or “relative” (values as the fraction of the star’s flux per pixel); values is a float64 array of the shape of img.data.

Return type:

tuple

Raises:

UnitError – photon counts without a band, an unknown unit, or a unit of neither family.

toycoronagraph.units.family(unit)[source]#

The family of a unit, found by converting a dummy image with per_pixel.

Parameters:

unit (str or astropy.units.UnitBase) – a NAMED unit, PHOTONS, or an astropy unit.

Returns:

“physical” or “relative”.

Return type:

str

Raises:

UnitError – for an unknown unit or a unit of neither family.

toycoronagraph.units.choose_internal(families, star_flux)[source]#

The scene’s internal unit.

Parameters:

  • families (dict) – {component name: “physical” or “relative”}.

  • star_flux (float) – the star’s flux density in Jy, or None if unknown.

Returns:

“Jy/arcsec^2” when the star’s flux is known or every component is physical; “contrast_pixel” when every component is relative and the flux is unknown.

Return type:

str

Raises:

UnitError – physical and relative components together without the star’s flux.

toycoronagraph.units.to_internal(fam, values, internal, pixel_area, star_flux)[source]#

Per-pixel values on the scene grid -> the internal unit.

Parameters:

  • fam (str) – “physical” (values in Jy per pixel) or “relative” (fraction of the star’s flux per pixel), as returned by per_pixel.

  • values (np.ndarray or float) – per-pixel values (any shape; also the fluxes of point sources).

  • internal (str) – “Jy/arcsec^2” or “contrast_pixel” (choose_internal).

  • pixel_area (float) – arcsec^2 per pixel of the scene grid.

  • star_flux (float) – the star’s flux density in Jy (may be None when no conversion between families is needed).

Returns:

values in the internal unit, same shape.

Return type:

np.ndarray or float

toycoronagraph.units.star_flux_of(star, wavelength)[source]#

A star’s flux density in Jy.

Parameters:

  • star (float or Star or None) – a real number (Jy; a NumPy scalar too) or None, returned as it is; or a toycoronagraph.scene.Star, evaluated at the wavelength (Star.flux_at).

  • wavelength (float) –

Returns:

Jy (None when star is None).

Return type:

float

Raises:

UnitError – a Star with neither flux_jy nor temperature, radius and distance.

toycoronagraph.units.flux_per_pixel(unit, pixel_area)[source]#

What turns an image in the internal unit into each pixel’s flux (summing over pixels gives a total): the pixel area for “Jy/arcsec^2” (-> Jy), 1 for “contrast_pixel” (already a fraction of the star’s flux).

Parameters:

  • unit (str) – The internal unit, “Jy/arcsec^2” or “contrast_pixel”.

  • pixel_area (float) – arcsec^2 per pixel.

Returns:

the factor.

Return type:

float

toycoronagraph.units.convert_image(image, from_unit, to_unit, pixel_area, star_flux=None, peak_norm=None)[source]#

A scene image in another output unit.

Parameters:

  • image (np.ndarray) – (N, N) image in from_unit.

  • from_unit (str) – the scene’s internal unit, “Jy/arcsec^2” or “contrast_pixel”.

  • to_unit (str) – “Jy/arcsec^2”, “Jy/pixel”, “contrast_pixel”, or “contrast_peak” (surface brightness / the peak of the star’s unocculted PSF).

  • pixel_area (float) – arcsec^2 per pixel.

  • star_flux (float) – the star’s flux density in Jy; needed to go between the families.

  • peak_norm (float) – for “contrast_peak”: the peak of the star’s unocculted PSF as a fraction of the star’s flux per pixel.

Returns:

(N, N) image in to_unit (the input itself when the units are equal).

Return type:

np.ndarray

Raises:

UnitError – an unknown unit, a from_unit that is not an internal unit, or the star’s flux or peak_norm is needed but None.

toycoronagraph.units.header_unit(header)[source]#

The unit named by a FITS header’s BUNIT.

Parameters:

header (astropy.io.fits.Header or dict-like) – the image’s header.

Returns:

(unit, raw): unit is a NAMED unit, PHOTONS, the raw text when astropy reads it as a unit of either family, or None (no BUNIT, or not understood); raw is the BUNIT text (”” when absent).

Return type:

tuple