From 14a8c9e4d9eb95c071cdee294f610becf0515866 Mon Sep 17 00:00:00 2001 From: Will Barnes Date: Wed, 13 Nov 2024 16:48:21 -0500 Subject: [PATCH] Add a topic guide for response function vocabulary (#111) Co-authored-by: Joy <74623359+joyvelasquez@users.noreply.github.com> Co-authored-by: Nick Murphy Co-authored-by: Nabil Freij Co-authored-by: Laura Hayes Co-authored-by: Stuart Mumford Co-authored-by: Joy <74623359+joyvelasquez@users.noreply.github.com> --- changelog/111.doc.rst | 1 + docs/index.rst | 1 + docs/topic_guide/channel_response.rst | 162 ++++++++++++++++++++++++++ docs/topic_guide/index.rst | 15 +++ 4 files changed, 179 insertions(+) create mode 100644 changelog/111.doc.rst create mode 100644 docs/topic_guide/channel_response.rst create mode 100644 docs/topic_guide/index.rst diff --git a/changelog/111.doc.rst b/changelog/111.doc.rst new file mode 100644 index 00000000..de306245 --- /dev/null +++ b/changelog/111.doc.rst @@ -0,0 +1 @@ +Add a topic guide on a vocabulary for instrument response functions. diff --git a/docs/index.rst b/docs/index.rst index 0e8089f5..5a5a20e7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -42,6 +42,7 @@ Once you have that virtual environment, you will want to fork the repo and then code_ref/index generated/gallery/index + topic_guide/index whatsnew/index diff --git a/docs/topic_guide/channel_response.rst b/docs/topic_guide/channel_response.rst new file mode 100644 index 00000000..2bcb7b51 --- /dev/null +++ b/docs/topic_guide/channel_response.rst @@ -0,0 +1,162 @@ +.. _sunkit-instruments-topic-guide-channel-response: + +************************************ +A Vocabulary for Instrument Response +************************************ + +This topic guide provides a vocabulary for response functions for imaging instruments. +The reason to provide a single vocabulary for instrument response calculations is to define a specification for a common interface that can be used by multiple instruments. +This reduces the amount of effort needed to develop analysis software for new instruments and enables cross-instrument comparisons as upstream packages and users can program against a single interface for these response calculations. +An abstract implementation of this vocabulary is provided in this package. + +Temperature Response +-------------------- + +The temperature response describes the instrument sensitivity as a function of temperature. +It is a useful quantity when performing thermal analysis of imaging data, such as a differential emission measure or filter ratio analysis. +The temperature response is defined as, + +.. math:: + + K(T) = \int\mathrm{d}\lambda\,R(\lambda)S(\lambda,T)\quad[\mathrm{DN}\,\mathrm{pixel}^{-1}\,\mathrm{s}^{-1} \,\mathrm{cm}^5] + +It has a physical type of data number (DN) per pixel per unit time per unit emission measure. +Note that the temperature response is a function of *both* the instrument properties as well as the atomic physics of the emitting source. +The temperature response is related to the observed intensity in a given pixel by, + +.. math:: + + I = \int\mathrm{d}T\,K(T)\mathrm{DEM}(T)\quad[\mathrm{DN}\,\mathrm{pixel}^{-1}\,\mathrm{s}^{-1}], + +where, + +.. math:: + + \mathrm{DEM}(T)=n^2\frac{dh}{dT} + +is the line-of-sight *differential* emission measure distribution in a given pixel. +It is typically expressed in units of :math:`\mathrm{cm}^{-5}\,\mathrm{K}^{-1}`. + +Source Spectra +-------------- + +The source spectra describes how a source is emitting as a function of wavelength and temperature. +It is denoted by :math:`S(\lambda, T)`. +The source spectra has a physical type of photon per unit time per unit wavelength per solid angle per unit density. +The units are commonly expressed as +:math:`\mathrm{photon}\,\mathrm{s}^{-1}\,\mathring{\mathrm{A}}^{-1}\,\mathrm{sr}^{-1}\,\mathrm{cm}^3`. +As such, it may also be referred to as the *spectral radiance per unit emission measure*. +The source spectra is specified by the user and can be computed from atomic databases (e.g. CHIANTI). +This quantity is independent of any instrument properties. + + +Wavelength Response +------------------- + +The wavelength response describes the instrument sensitivity as a function of wavelength and time. +The wavelength response is defined as, + +.. math:: + + R(\lambda,t) = A_{\mathrm{eff}}(\lambda,t)f(\lambda)\frac{pg}{s}\quad[\mathrm{cm}^2\,\mathrm{DN}\,\mathrm{photon}^{-1}\,\mathrm{sr}\,\mathrm{pixel}^{-1}] + +It has a physical type of area DN per photon solid angle per pixel. + +Camera Gain +----------- + +The camera gain, :math:`g`, describes the conversion between electrons and data number (DN). +This is a property of the detector. +The units of the camera gain are :math:`\mathrm{DN}\,\mathrm{electron}^{-1}`. + +Photon-to-Energy Conversion +--------------------------- + +The photon-to-energy conversion is given by the amount of energy carried by a photon of wavelength :math:`\lambda`, + +.. math:: + + f(\lambda) = \frac{hc}{\lambda}\quad[\mathrm{eV}\,\mathrm{photon}^{-1}] + +where :math:`h` is Planck's constant and :math:`c` is the speed of light. +It has a physical type of energy per photon. + +.. note:: + + Use the `~astropy.units.spectral` unit equivalency to provide a list of appropriate `astropy.units` equivalencies for this conversion. + +Energy-to-Electron Conversion +----------------------------- + +The energy-to-electron conversion, :math:`s`, describes the conversion between electrons released in the detector and the energy of an incoming photon. +This is commonly referred to as the *electron-hole-pair-creation energy*. +It has a physical type of energy per electron. +For silicon detectors, a value of :math:`s=3.65\,\mathrm{eV}\,\mathrm{electron}^{-1}` is typically used as this is approximately the energy required to free an electron in silicon. + +Pixel Solid Angle +----------------- + +The pixel area, :math:`p`, is the angular area in the plane of the sky subtended by a single detector pixel. +It has a physical type of solid angle per pixel. +The units of the pixel area are typically expressed as :math:`\mathrm{sr}\,\mathrm{pixel}^{-1}`. +Typically, this quantity can be determined as the product of the spatial plate scale in each direction. +In the FITS standard, these keys are denoted by "CDELTi", with "i" typically taking on values of 1 or 2. +Note that the pixel area is sometimes confusingly referred to as the plate scale. +However, here we explicitly define the plate scale to be the angular *distance* subtended by one side of a pixel. + +Effective Area +-------------- + +The effective area describes the instrument sensitivity as a function of wavelength and time. +It is given by, + +.. math:: + + A_{\mathrm{eff}}(\lambda,t) = A_{\mathrm{geo}}M(\lambda)F(\lambda)Q(\lambda)D(\lambda,t)\quad[\mathrm{cm}^2] + +The effective area has a physical type of area. +:math:`A_\mathrm{eff}(\lambda,t=0)` is defined as the effective area at the start of the mission. +Each component of the effective area is described in detail below. + +Geometrical Area +**************** + +The geometrical collecting area, :math:`A_\mathrm{geo}`, is the cross-sectional area of the telescope aperture. +It has a physical type of area. +The units of the geometrical collecting area are commonly expressed as :math:`\mathrm{cm}^2`. +For example, for a telescope with a circular aperture of diameter :math:`d`, the geometrical collecting area is :math:`A_\mathrm{geo}=\pi d^2/4`. + +Mirror Reflectance +****************** + +The mirror reflectance, :math:`M(\lambda)`, is a dimensionless quantity describing the efficiency of the mirror(s) in the instrument as a function of wavelength. +If the instrument contains multiple mirrors (e.g. a primary and secondary mirror), this quantity is the product of the reflectance of each mirror. +:math:`M(\lambda)` should always be between 0 and 1. + +Filter Transmittance +******************** + +The filter transmittance, :math:`F(\lambda)`, is a dimensionless quantity describing the efficiency of the filter(s) as a function of wavelength. +This is typically calculated by computing the transmittance through a given compound of a specified thickness. +In the case of a multilayer coating, the transmittance is the product of the transmittance of each layer of the coating. +Similarly, if an instrument contains multiple filters (e.g. an entrance and focal-plane filter), this quantity is the product of the transmittance of each mirror. +:math:`F(\lambda)` should always be between 0 and 1. + +Effective Quantum Efficiency +**************************** + +The effective quantum efficiency, :math:`Q(\lambda)`, is a dimensionless quantity describing the efficiency of the detector. +:math:`Q(\lambda)` should always be between 0 and 1. +This quantity may also be referred to as the `external quantum efficiency `__. +Note that the *quantum efficiency* is usually defined as the number of electron-hole pairs measured per photon. + +Degradation +*********** + +The degradation, :math:`D(\lambda,t)`, is a dimensionless quantity describing how the effective area degrades as a function of time and also how that degradation varies with wavelength. +The time dimension, :math:`t`, corresponds to the lifetime of the mission. +:math:`D(\lambda,t)` should always be between 0 and 1. +The degradation need not be equal to 1 at :math:`t=0`. +For example, there could be some known degradation due to contamination in the telescope known at the time of launch. +This quantity should include all sources of degradation in the instrument. +For example, if there is a known degradation model for the filter and the CCD, :math:`D(\lambda,t)` will be the product of these two degradation factors. diff --git a/docs/topic_guide/index.rst b/docs/topic_guide/index.rst new file mode 100644 index 00000000..75931298 --- /dev/null +++ b/docs/topic_guide/index.rst @@ -0,0 +1,15 @@ +.. _sunkit-instruments-topic-guide-index: + +************ +Topic Guides +************ + + +These topic guides provide a set of in-depth explanations for various parts of the ``sunkit-instruments`` package. +They are designed to be read in a standalone manner, without running code at the same time. +Although there are code snippets in various parts of each topic guide, these are present to help explanation, and are not structured in a way that they can be run as you are reading a topic guide. + +.. toctree:: + :maxdepth: 1 + + channel_response