#include <Telescope.h>

Inheritance diagram for Telescope:

Collaboration diagram for Telescope:

Public Member Functions
void	AddSource (Source aSource, TGraph aEffectiveArea, TH2F *aAcceptance)
	Adds a Source object to the telescope. More...

TGraph *	GetEffectiveArea (const UInt_t aSourceIndex)
	Returns the telescope on-axis effective area as a function of energy. More...

double	GetEffectiveArea (const UInt_t aSourceIndex, const double aEnergy)
	Returns the telescope on-axis effective area at a given energy. More...

double	GetEffectiveArea (const UInt_t aSourceIndex, const double aEnergyMin, const double aEnergyMax)
	Gets the telescope on-axis effective area in a energy band. More...

int	GetFocalLength (void)
	Returns the telescope focal length \([\mathrm{mm}]\). More...

string	GetName (void)
	Returns the telescope name. More...

TH2F *	GetPsf (const double aEnergy)
	Returns the point spread function at a given energy. More...

TH2F *	GetPsf (const UInt_t aEnergyBinIndex)
	Returns the point spread function in a given energy bin. More...

TH3F *	GetPsf (void)
	Returns the point spread function. More...

void	SetFocalLength (const int aFocalLength=1000)
	Sets the telescope focal length. More...

void	SetName (const string aName)
	Sets the telescope name. More...

bool	SetPsf (TH2F *aPsf, const double aEnergyMin=0.0, const double aEnergyMax=1000000)
	Sets the telescope PSF (energy independent). More...

bool	SetPsf (TH3F *aPsf)
	Sets the telescope PSF (full definition). More...

double	SetPsfAiry (const double aOpeningAngle, const int aYN, const int aZN, const int aEnergyN, const double aEnergyMin, const double aEnergyMax)
	Computes the telescope PSF as an Airy disk. More...

bool	SetPsfFile (const string aFileName)
	Sets the telescope PSF with a ROOT file. More...

void	StartObservation (TFile *aRootFile)
	Starts an observation sequence. More...

void	StopObservation (void)
	Stops an observation sequence. More...

void	TakePicture (const ULong64_t aTimeStart)
	Takes a picture. More...

Constructors and destructors
	Telescope (const int aNbits=14, const int aNy=256, const int aNz=256)
	Telescope class constuctor. More...

virtual	~Telescope (void)
	Telescope class destructor. More...

Public Member Functions inherited from Camera
void	AddCosmicRay (const double aEnergy, const double aY, const double aZ, const double aCosTheta, const double aSinTheta, const double aCosPhi, const double aSinPhi, const int aSourceIndex=0, const int aParticleIndex=0)
	Adds one cosmic ray to the current amplitude map. More...

void	AddPhoton (const double aEnergy, const double aY, const double aZ, const int aSourceIndex=0, const int aParticleIndex=0)
	Adds one photon to the current amplitude map. More...

void	AddPixelAmplitudeValue (const int aPixIndexY, const int aPixIndexZ, const int aValue)
	Increments the amplitude value of a given pixel. More...

void	GenAmplitudeNoiseMap (void)
	Fills the raw amplitude map with intrinsic pixel noise. More...

TH2S *	GetMap (const CAMERA_MAPTYPE aMapType)
	Returns a camera map. More...

int	GetMapNy (void)
	Returns the number of pixels in the Y direction. More...

int	GetMapNz (void)
	Returns the number of pixels in the Z direction. More...

string	GetName (void)
	Returns the camera name. More...

double	GetPixelError (const CAMERA_MAPTYPE aMapType, const int aPixIndexY, const int aPixIndexZ)
	Returns the error value of a given pixel. More...

int	GetPixelValue (const CAMERA_MAPTYPE aMapType, const int aPixIndexY, const int aPixIndexZ)
	Returns the value of a given pixel and a given map. More...

ULong64_t	GetTime (void)
	Returns the camera time [ms]. More...

UInt_t	GetTimeResolution (void)
	Returns the camera electronic integration time [ms]. More...

double	GetXsize (void)
	Returns the camera physical size in the X direction [mm]. More...

double	GetYsize (void)
	Returns the camera physical size in the Y direction [mm]. More...

double	GetZsize (void)
	Returns the camera physical size in the Z direction [mm]. More...

void	ResetMap (const CAMERA_MAPTYPE aMapType)
	Resets a given map. More...

void	SetCosmicRayEnergyLoss (const double aEnergyLoss=1.0)
	Sets the energy loss per pixel for cosmic rays. More...

void	SetFrozenBrightY (const int aPixIndexY)
	Sets an entire line of pixels (Y) at amplitude saturation. More...

void	SetFrozenBrightZ (const int aPixIndexZ)
	Sets an entire line of pixels (Z) at amplitude saturation. More...

void	SetGain (TH2F *aGainMap)
	Sets a gain map. More...

void	SetGainUniform (const double aGain)
	Sets a uniform gain map. More...

void	SetMap (const CAMERA_MAPTYPE aMapType, TH2S *aMap)
	Sets an external camera map. More...

void	SetName (const string aName)
	Sets the camera name. More...

void	SetPhotonResolution (const double aPixelResY=1.0, const double aPixelResZ=1.0)
	Sets the spatial resolution to inject photons in the camera frame. More...

void	SetPixelDistributions (const CAMERA_MAPTYPE aMapType, double aPar1=-1.0, double aPar2=-1.0, double aPar3=-1.0, double aPar4=-1.0)
	Sets a Gaussian distribution for a given pixel map. More...

void	SetPixelValue (const CAMERA_MAPTYPE aMapType, const int aPixIndexY, const int aPixIndexZ, const int aValue, const double aValueErr=0.0)
	Assigns a value to a given pixel of a given map. More...

void	SetRandomPixelBright (const int aN)
	Sets a given number of pixels, randomly chosen, at amplitude saturation (dark and read noise maps). More...

void	SetRandomPixelDead (const int aN)
	Sets a given number of pixels, randomly chosen, at 0 amplitude (dark and read noise maps). More...

void	SetSize (const double aXsize=1.0, const double aYsize=1.0, const double aZsize=1.0)
	Sets the physical size of the camera CCD. More...

void	SetTime (const ULong64_t aTime=0)
	Sets the camera time [ms]. More...

void	SetTimeResolution (const UInt_t aTimeResolution=100)
	Sets the camera electronic integration time [ms]. More...

void	TreeDelete (void)
	Deletes the TTree. More...

int	TreeFill (void)
	Fills all the TTree branches with current parameters. More...

void	TreeInit (void)
	Initializes a camera TTree. More...

void	TreeReset (void)
	Resets baskets, buffers and entries count in all branches and leaves. More...

int	TreeWrite (void)
	Writes the TTree to the current directory. More...

void	WriteMap (const string aOutFileName="./mymaps.root")
	Write the current camera maps in a ROOT file. More...

	Camera (const int aNbits=14, const int aNy=256, const int aNz=256)
	Camera class constuctor. More...

virtual	~Camera (void)
	Camera class destructor. More...

Public Member Functions inherited from Rotation
double	GetAlpha (void)
	Returns the current value of \(\alpha\) [rad]. More...

double	GetBeta (void)
	Returns the current value of \(\beta\) [rad]. More...

double	GetCosAlpha (void)
	Returns the current value of \(\cos(\alpha)\). More...

double	GetCosBeta (void)
	Returns the current value of \(\cos(\beta)\). More...

double	GetCosGamma (void)
	Returns the current value of \(\cos(\gamma)\). More...

double	GetGamma (void)
	Returns the current value of \(\gamma\) [rad]. More...

double	GetOmega (void)
	Returns the current value of \(\omega\). More...

double	GetPsi (void)
	Returns the current value of \(\Psi\). More...

double	GetRotationAngle (void)
	Returns the rotation angle from \(\cal{R}^{\prime}\) to \(\cal{R}\) [rad]. More...

double	GetRotationAxisXp (void)
	Returns the \(x^{\prime}\) component in \(\cal{R}^{\prime}\) of a vector defining the rotation axis from \(\cal{R}^{\prime}\) to \(\cal{R}\). More...

double	GetRotationAxisYp (void)
	Returns the \(y^{\prime}\) component in \(\cal{R}^{\prime}\) of a vector defining the rotation axis from \(\cal{R}^{\prime}\) to \(\cal{R}\). More...

double	GetRotationAxisZp (void)
	Returns the \(z^{\prime}\) component in \(\cal{R}^{\prime}\) of a vector defining the rotation axis from \(\cal{R}^{\prime}\) to \(\cal{R}\). More...

double	GetRxx ()
	Returns the rotation matrix element \(R_{xx}\). More...

double	GetRxy ()
	Returns the rotation matrix element \(R_{xy}\). More...

double	GetRxz ()
	Returns the rotation matrix element \(R_{xz}\). More...

double	GetRyx ()
	Returns the rotation matrix element \(R_{yx}\). More...

double	GetRyy ()
	Returns the rotation matrix element \(R_{yy}\). More...

double	GetRyz ()
	Returns the rotation matrix element \(R_{yz}\). More...

double	GetRzx ()
	Returns the rotation matrix element \(R_{zx}\). More...

double	GetRzy ()
	Returns the rotation matrix element \(R_{zy}\). More...

double	GetRzz ()
	Returns the rotation matrix element \(R_{zz}\). More...

double	GetSinAlpha (void)
	Returns the current value of \(\sin(\alpha)\). More...

double	GetSinBeta (void)
	Returns the current value of \(\sin(\beta)\). More...

double	GetSinGamma (void)
	Returns the current value of \(\sin(\gamma)\). More...

double	GetUpx (const double aThetaPrime, const double aPhiPrime)
	Returns the \(u^{\prime}_x\) coordinate in the \(\cal{R}^{\prime}\) reference frame. More...

double	GetUpy (const double aThetaPrime, const double aPhiPrime)
	Returns the \(u^{\prime}_y\) coordinate in the \(\cal{R}^{\prime}\) reference frame. More...

double	GetUpz (const double aThetaPrime)
	Returns the \(u^{\prime}_z\) coordinate in the \(\cal{R}^{\prime}\) reference frame. More...

double	GetUx (const double aTheta)
	Returns the \(u_x\) coordinate in the \(\cal{R}\) reference frame. More...

double	GetUy (const double aTheta, const double aPhi)
	Returns the \(u_y\) coordinate in the \(\cal{R}\) reference frame. More...

double	GetUz (const double aTheta, const double aPhi)
	Returns the \(u_z\) coordinate in the \(\cal{R}\) reference frame. More...

void	SetAlpha (const double aAlpha=0.0)
	Sets a new \(\alpha\) value. More...

void	SetAlphaBetaGamma (const double aAlpha, const double aBeta, const double aGamma)
	Sets Euler angles, \(\alpha, \beta, \gamma\), for the rotation. More...

void	SetBeta (const double aBeta=0.0)
	Sets a new \(\beta\) value. More...

void	SetGamma (const double aGamma=0.0)
	Sets a new \(\gamma\) value. More...

void	SetUnitQuaternion (const double aQ0, const double aQ1, const double aQ2, const double aQ3, const bool aRtoRprime=true)
	Sets Euler angles from a unit quaternion. More...

double	TransformGetCosPhi (const double aThetaPrime, const double aPhiPrime)
	Returns the \(\cos\varphi\) in the reference frame \(\cal{R}\). More...

double	TransformGetCosPhiPrime (const double aTheta, const double aPhi)
	Returns the \(\cos\varphi^{\prime}\) in the reference frame \(\cal{R}^{\prime}\). More...

double	TransformGetCosTheta (const double aThetaPrime, const double aPhiPrime)
	Returns the \(\cos\theta\) in the reference frame \(\cal{R}\). More...

double	TransformGetCosThetaPrime (const double aTheta, const double aPhi)
	Returns the \(\cos\theta^{\prime}\) in the reference frame \(\cal{R}^{\prime}\). More...

double	TransformGetSinPhi (const double aThetaPrime, const double aPhiPrime)
	Returns the \(\sin\varphi\) in the reference frame \(\cal{R}\). More...

double	TransformGetSinPhiPrime (const double aTheta, const double aPhi)
	Returns the \(\sin\varphi^{\prime}\) in the reference frame \(\cal{R}^{\prime}\). More...

double	TransformGetSinTheta (const double aThetaPrime, const double aPhiPrime)
	Returns the \(\sin\theta\) in the reference frame \(\cal{R}\). More...

double	TransformGetSinThetaPrime (const double aTheta, const double aPhi)
	Returns the \(\sin\theta^{\prime}\) in the reference frame \(\cal{R}^{\prime}\). More...

double	TransformGetTanPhi (const double aThetaPrime, const double aPhiPrime)
	Returns the \(\tan\varphi\) in the reference frame \(\cal{R}\). More...

double	TransformGetTanPhiPrime (const double aTheta, const double aPhi)
	Returns the \(\tan\varphi^{\prime}\) in the reference frame \(\cal{R}^{\prime}\). More...

double	TransformGetTanTheta (const double aThetaPrime, const double aPhiPrime)
	Returns the \(\tan\theta\) in the reference frame \(\cal{R}\). More...

double	TransformGetTanThetaCosPhi (const double aThetaPrime, const double aPhiPrime)
	Returns the \(\tan\theta\cos\varphi\) in the reference frame \(\cal{R}\). More...

double	TransformGetTanThetaPrime (const double aTheta, const double aPhi)
	Returns the \(\tan\theta^{\prime}\) in the reference frame \(\cal{R}^{\prime}\). More...

double	TransformGetTanThetaSinPhi (const double aThetaPrime, const double aPhiPrime)
	Returns the \(\tan\theta\sin\varphi\) in the reference frame \(\cal{R}\). More...

	Rotation (const double aAlpha, const double aBeta, const double aGamma)
	Rotation class constuctor. More...

virtual	~Rotation (void)
	Rotation class destructor. More...

Private Member Functions
void	ApplyPsf (double &aYf, double &aZf, const double aY0, const double aZ0, const double aEnergy)
	Applies the PSF and updates the coordinates in the telescope focal plane. More...

Private Attributes
vector< TH2F * >	tel_acc
	telescope acceptance to sources. More...

vector< TGraph * >	tel_effarea
	telescope on-axis effective area to sources. More...

TFile *	tel_file
	current TFile. More...

int	tel_foclen
	telescope focal length \([\mathrm{mm}]\). More...

string	tel_name
	telescope name. More...

TH3F *	tel_psf
	telescope optical point spread function (PSF). More...

TArrayD *	tel_psf_ebins
	energy bins for the PSF. More...

int	tel_psf_nebins
	number of energy bins for the PSF. More...

TH2F **	tel_psfe
	telescope optical point spread function at one energy. More...

vector< Source * >	tel_src
	vector of sources. More...

Additional Inherited Members
Protected Attributes inherited from Camera
TTree *	cam_tree
	camera tree. More...

TRandom3 *	randgen
	random generator. More...

Protected Attributes inherited from Rotation
double	rot_alpha
	Euler angle \(\alpha\). More...

double	rot_beta
	Euler angle \(\beta\). More...

double	rot_gamma
	Euler angle \(\gamma\). More...

Detailed Description

Telescope.

This class is used to describe a telescope. The telescope is made of 3 types of components:

A camera described by a Camera object (class inheritance).
A geometry and an optical design.
A list of associated astrophysical sources.

The telescope must be configured before taking pictures.

The telescope geometrical description

Telescope object.

The telescope position must be defined in space. The reference frame of the telescope is \(\cal{R}\), where the \(x\) axis is the pointing axis and the camera is located in the \(yOz\) plane, which coincide with the telescope focal plane. The Earth celestial reference frame is noted \(\cal{R}'\). The rotation between the telescope reference frame and the Earth reference frame is managed by the Rotation class from which the Telescope class inherits. Intrinsic Euler angles, \((\alpha, \beta, \gamma)\) are use to track the telescope reference frame in the Earth reference frame. These angles must be set with Rotation::SetAlphaBetaGamma() before taking pictures.

Telescope (blue) and Earth celestial (black) reference frame. The rotation to change the system of coordinates is given by the Euler angles and is represented in green.

Note: The telescope position is actually managed at the camera level, using the Rotation class.

The telescope optics

The telescope optics is assumed to be linear. It is entirely represented by the telescope point spread function (PSF) \({\cal{P}}\) which models the image pattern of a point-like source. In SatAndLight, source photons are simulated one by one. The PSF is used to compute the photon hit position in the camera plane.

For an incoming photon, represented by the red arrow in the diagram below, the hit position (red cross), \((y_0,z_0)\), is geometrically computed considering the ray of light crossing the optical center which is assumed to be aligned with the camera center:

\[ \begin{cases} y_0 = 0.5 + \frac{F}{L_y}\times \tan\theta\cos\varphi \\ z_0 = 0.5 + \frac{F}{L_z}\times \tan\theta\sin\varphi \end{cases} \]

where \(F\) is the telescope focal length and \(L_y\) and \(L_z\) are the camera dimensions in the Y and Z directions respectively.

Left: the photon hit position (red arrow) is first computed considering the ray of light crossing the optical center. Right: the PSF function is adjusted and used to compute the final photon hit position (green).

The PSF, represented in light blue, is then used to compute the final hit position (green cross). The PSF is a function of \(y\), \(z\) and \(E\): \({\cal{P}}={\cal{P}}(y,z,E)\), where \(y\) and \(z\) run from 0 to 2 and \(E\) is the photon energy. It must be placed such that its center matches the photon geometrical position (red cross). The final hit position, \((y_f,z_f)\), is randomly drawn using \({\cal{P}}(y-y_0+1,z-z_0+1,E)\) as a probability density function. The exact way the PSF is applied is described in Telescope::ApplyPSF().

Note: The size of the PSF is twice the size of the camera plane in both dimensions and the peak of the PSF is positioned at \((y=1,z=1)\).

See also: The convention for Point spread functions.

How to configure a Telescope object

A Telescope must be fully parameterized before using it for observations. Make sure all the functions have been used to properly configure your telescope.

Telescope geometry and optical design

Set the telescope name with SetName().
Set the focal length along the X axis, \(F\), with SetFocalLength().
Set the optical response with a point spread function (PSF) with SetPsf().
Set the pointing direction using the inherited Rotation class. This is achieved by using the Rotation::SetAlphaBetaGamma() function to set the Euler angles defining the rotation in the Earth reference frame.

Telescope CCD camera

The camera must be configured as detailed in the Camera class description. However:

The camera name is automatically set. Do not change it.
The camera pixel configuration is set in the constructor Telescope().

Astrophysical sources

Astrophysical sources can be added with AddSource(). The Source object must be configured first:

Set the source name with Source::SetName().
Set the source type with Source::SetType().
Set the source location with Source::SetPosition(), which can be time-dependent.

Note: The source position is dynamic. The entire sequence of positions must be programmed with Source::SetPosition() before running an observation sequence.

When adding a source, the corresponding on-axis effective area must also be specified. It is provided as a TGraph measuring the effective area \(S(E)\).

One must also specify the telescope acceptance for this source. The acceptance measures the probability for a particle with a given incoming direction to reach the camera. The acceptance must be provided as a TH2F object. The horizontal axis is binned in \(-1\le\cos\theta\le 1\), where \(\theta\) is measured from the telescope x-axis. The vertical axis is binned in \(0\le\varphi<2\pi\), where \(\varphi\) is measured from the telescope y-axis. Each bin is given the acceptance of the telescope (between 0 and 1).

Astro-particle detection

Astro-particles generated via the Source class, are given an energy \(E_p\), and a direction \(\theta'_p\), \(\varphi'_p\) measured in the Earth clestial coordinates. The Telescope object uses these parameters to compute the interaction with the camera (in TakePicture()).

First, the particle incoming direction is estimated in the telescope reference frame: \(\theta_p\), \(\varphi_p\). Then, the particle energy is determined by the SpecTime object as defined by the source.

The telescope acceptance for a given particle is tested. A binomial test, guided by the particle incoming direction, is used to decide if the particle is considered.

If the particle is a photon, the telescope PSF is applied with ApplyPsf(). Finally the particle interaction with the camera is managed with Camera::AddPhoton() or Camera::AddCosmicRay().

Taking a picture

Call TakePicture() to take a picture and Camera::WriteMap() to save the picture in a ROOT file.

Run an observation sequence

It is possible to run an observation sequence and save it in an organized structure in a ROOT file. Run the following steps:

StartObservation(): A TFile must be provided so that all the observation elements can be saved in a directory named after the telescope:
- A TTree with a single entry to describe the telescope properties.
- A TTree to save the camera object, see Camera::TreeInit().
- A TTree to save the source objects, see Source::TreeInit(). The source tree is filled with the source properties (single entry).
- A TTree for each source to save astro-particles, see Source::TreeInit().
Call TakePicture() multiple times to take a sequence of pictures which are saved in TTrees (camera and astro-particles).
StopObservation(): All TTrees are saved in the file. After this, the sequence TFile can be safely closed.

Between each picture, it is possible to change parameters:

Any camera parameters (like corrupted pixels), using the Camera Set functions.
The telescope pointing direction with Rotation::SetAlphaBetaGamma(). Note that it is not possible to change the telescope geometry or optics.

See also: The SatAndLight file structure for telescope objects.

Author: Florent Robinet

Constructor & Destructor Documentation

◆ Telescope()

Telescope::Telescope	(	const int	aNbits = `14`,
		const int	aNy = `256`,
		const int	aNz = `256`
	)

Telescope class constuctor.

The Telescope object is initialized as well as the Camera object. The telescope parameters are given default values:

name = "TEL"
focal length = 1000 mm
PSF = dirac at the center over all energies (0→1 GeV).
sky pointing direction: \(\alpha=0\,\mathrm{rad}\), \(\beta=0\,\mathrm{rad}\), and \(\gamma=0\,\mathrm{rad}\)

Warning: The telescope name must be unique if more than one telescope are used in the same time. Use SetName() to update the telescope name.

Parameters

[in]	aNbits	Number of bits to encode the pixel raw amplitude (must be less or equal to 16).
[in]	aNy	Number of pixels in the Y direction. Pixels are indexed from 0 to \(N_y-1\).
[in]	aNz	Number of pixels in the Z direction. Pixels are indexed from 0 to \(N_z-1\).

◆ ~Telescope()

Telescope::~Telescope ( void )

virtual

Telescope class destructor.

Member Function Documentation

◆ AddSource()

void Telescope::AddSource	(	Source *	aSource,
		TGraph *	aEffectiveArea,
		TH2F *	aAcceptance
	)

Adds a Source object to the telescope.

A new source is added to the telescope. The user must also provide the telescope on-axis effective area for this source. It must consist of a TGraph object the points of which measure the telescope effective area, in \([\mathrm{mm}^2]\) as a function of the particle energy in [keV].

Finally the user must provide the telescope acceptance for this source. The acceptance measures the probability for a particle with a given incoming direction to reach the camera. The acceptance must be provided as a TH2F object. The horizontal axis is binned in \(-1\le\cos\theta\le 1\), where \(\theta\) is measured from the telescope x-axis. The vertical axis is binned in \(0\le\varphi<2\pi\), where \(\varphi\) is measured from the telescope y-axis. Each bin is given the acceptance of the telescope (between 0 and 1).

Parameters

[in]	aSource	Pointer to a source object.
[in]	aEffectiveArea	On-axis effective area as a function of energy for this source.
[in]	aAcceptance	Telescope acceptance for this source.

Precondition: aSource must be a valid pointer to a source object and must be preserved while using this class. The TGraph and the TH2F, however, can be deleted after calling this function.

Warning: The input Source object is given a new name when calling this function. Do not change the name again as it is standardized to save the Source object in ROOT files.

◆ ApplyPsf()

void Telescope::ApplyPsf	(	double &	aYf,
		double &	aZf,
		const double	aY0,
		const double	aZ0,
		const double	aEnergy
	)

private

Applies the PSF and updates the coordinates in the telescope focal plane.

The coordinates (aY0,aZ0) in the telescope focal plane are modified using the PSF. To do this, a random generator draws a set of new coordinates following the PSF distribution centered on (aY0,aZ0,aEnergy). The original position is not changed if:

the photon energy is not covered by the PSF object.
the PSF is a single-bin object.

Note: The returned values, aYf and aZf, are always inside the camera plane, i.e with coordinates between 0 and 1.

Parameters

[out]	aYf	Final Y position after applying the PSF (intrinsic coordinates).
[out]	aZf	Final Z position after applying the PSF (intrinsic coordinates).
[in]	aY0	Original Y position in the telescope focal plane (intrinsic coordinates).
[in]	aZ0	Original Z position in the telescope focal plane (intrinsic coordinates).
[in]	aEnergy	Particle energy [keV].

◆ GetEffectiveArea() [1/3]

TGraph* Telescope::GetEffectiveArea ( const UInt_t aSourceIndex )

inline

Returns the telescope on-axis effective area as a function of energy.

This function is returned as a TGraph.

Parameters

[in] aSourceIndex Source index.

Returns: The telescope on-axis effective area in \([\mathrm{mm}^2]\) as a function of energy in \([\mathrm{keV}^2]\).

Precondition: aSourceIndex must a valid source index.

Warning: Do not delete or modify the returned TGraph as it is used internally by this class.

◆ GetEffectiveArea() [2/3]

double Telescope::GetEffectiveArea	(	const UInt_t	aSourceIndex,
		const double	aEnergy
	)

Returns the telescope on-axis effective area at a given energy.

If the input energy is out-of-range, 0.0 is returned. If the source index does not exist, -1 is returned.

Parameters

[in]	aSourceIndex	Source index.
[in]	aEnergy	Energy in [keV].

Returns: The telescope on-axis effective area in \([mm^2]\).

◆ GetEffectiveArea() [3/3]

double Telescope::GetEffectiveArea	(	const UInt_t	aSourceIndex,
		const double	aEnergyMin,
		const double	aEnergyMax
	)

Gets the telescope on-axis effective area in a energy band.

If the input energy band is out-of-range, 0.0 is returned. If the source index does not exist, -1 is returned. If the telescope energy range overlaps the input band, and mean effective area is computed over the overlapping band.

Parameters

[in]	aSourceIndex	Source index.
[in]	aEnergyMin	Minimum energy in [keV].
[in]	aEnergyMax	Maximum energy in [keV].

Returns: The telescope mean effective area in \([mm^2]\) over the input energy band.

◆ GetFocalLength()

int Telescope::GetFocalLength ( void )

inline

Returns the telescope focal length \([\mathrm{mm}]\).

◆ GetName()

string Telescope::GetName ( void )

inline

Returns the telescope name.

◆ GetPsf() [1/3]

TH2F * Telescope::GetPsf ( const double aEnergy )

Returns the point spread function at a given energy.

Warning: The user is in charge of deleting the returned histogram.

Parameters

[in] aEnergy Energy [keV].

◆ GetPsf() [2/3]

TH2F * Telescope::GetPsf ( const UInt_t aEnergyBinIndex )

Returns the point spread function in a given energy bin.

Warning: The user is in charge of deleting the returned histogram.

Parameters

[in] aEnergyBinIndex Energy bin index.

Returns: Pointer to NULL is the bin index is out of range.

◆ GetPsf() [3/3]

TH3F* Telescope::GetPsf ( void )

inline

Returns the point spread function.

Warning: Do not delete or modigy the returned object as it is a part of the class.

◆ SetFocalLength()

void Telescope::SetFocalLength ( const int aFocalLength = 1000 )

inline

Sets the telescope focal length.

Parameters

[in] aFocalLength Telescope focal length \([\mathrm{mm}]\).

◆ SetName()

void Telescope::SetName ( const string aName )

Sets the telescope name.

The telescope name must be unique if more than one telescope are used in the same time.The derived Camera object name is also updated with a new name: name of the telescope + "_CAM".

Parameters

[in] aName Telescope name.

◆ SetPsf() [1/2]

bool Telescope::SetPsf	(	TH2F *	aPsf,
		const double	aEnergyMin = `0.0`,
		const double	aEnergyMax = `1000000`
	)

Sets the telescope PSF (energy independent).

The input PSF must be a two-dimensional histogram, ranging from 0 to 2.0 for spatial axes. The PSF is energy independent, with one single energy bin.

Note: The input histogram can be deleted after calling this function.; A psf with a single bin is interpreted as a dirac function in the center for all energies.

See also: The convention for point spread functions for telescope objects.

Returns: false if the PSF object is not valid, true otherwise.

Parameters

[in]	aPsf	Pointer to the PSF histogram.
[in]	aEnergyMin	Minimum energy [keV].
[in]	aEnergyMax	Maximum energy [keV].

◆ SetPsf() [2/2]

bool Telescope::SetPsf ( TH3F * aPsf )

Sets the telescope PSF (full definition).

The input PSF must be a three-dimensional histogram, ranging from 0 to 2.0 for spatial coordinates.

Note: The input histogram can be deleted after calling this function.; A psf with a single bin is interpreted as a dirac function in the center for all energies.

See also: The convention for point spread functions for telescope objects.

Returns: false if the PSF object is not valid, true otherwise.

Parameters

[in] aPsf Pointer to the PSF histogram.

◆ SetPsfAiry()

double Telescope::SetPsfAiry	(	const double	aOpeningAngle,
		const int	aYN,
		const int	aZN,
		const int	aEnergyN,
		const double	aEnergyMin,
		const double	aEnergyMax
	)

Computes the telescope PSF as an Airy disk.

The PSF is given the Airy pattern produced by a circular aperture:

\[ {\cal{P}}(y,z,E)=\left[\frac{J_1\left(k(E)a\sin\theta(y,z)\right)}{k(E)a\sin\theta(y,z)}\right]^2, \]

where \(J_1\) is the Bessel function of the first kind of order one and \(a\) is the telescope radius of aperture given by the opening angle \(\theta_m\) of the telescope: \(a=F\sin\theta_m\). The wavenumber is given by \(k(E)=E/(\hbar c)\), where \(E\) is taken at the center of the energy bin. Finally, we use

\[ \sin\theta(y,z) = \frac{\tan\theta(y,z)}{\sqrt{1+\tan^2\theta(y,z)}}, \]

where \(\tan\theta(y,z) = \sqrt{(y-L_y)^2+(z-L_z)^2}/F\), such that the Airy peak is centered on \((L_y,L_z)\).

Parameters

[in]	aOpeningAngle	Telescope opening angle, \(\theta_m\), measured from central axis [rad].
[in]	aYN	Number of bins in the Y direction.
[in]	aZN	Number of bins in the Z direction.
[in]	aEnergyN	Number of energy bins.
[in]	aEnergyMin	Minimum energy [kev].
[in]	aEnergyMax	Maximum energy [kev].

Returns: The radius of the first dark fringe in the Y direction (intrinsic corrdinates) for the last (highest) computed energy.

◆ SetPsfFile()

bool Telescope::SetPsfFile ( const string aFileName )

Sets the telescope PSF with a ROOT file.

The input PSF must be a three-dimensional histogram, ranging from 0 to 2.0 for spatial coordinates. The PSF object is given as a ROOT file and extracted with SetPsf().

See also: The convention for point spread functions for telescope objects.

Returns: false if the PSF object is not valid, true otherwise.

Parameters

[in] aFileName ROOT file path.

◆ StartObservation()

void Telescope::StartObservation ( TFile * aRootFile )

Starts an observation sequence.

Call this function to start a sequence of observation. An open root file must be provided to create resident TTrees. A directory named after the telescope is created and the telescope TTree is saved (one single entry). The camera tree is created to save the sequence of camera maps. For each source object added with AddSource(), a TTree is created and filled with a single entry listing the source properties.

Parameters

[in] aRootFile Pointer to a TFile.

Precondition: aRootFile must be a valid pointer to an open TFile and must be kept open during the entire sequence, until StopObservation() is called.

◆ StopObservation()

void Telescope::StopObservation ( void )

Stops an observation sequence.

Call this function to end a sequence of observation. All TTrees are saved in the root file provided with StartObservation(). After calling this function the TFile can be safely closed.

◆ TakePicture()

void Telescope::TakePicture ( const ULong64_t aTimeStart )

Takes a picture.

A picture is taken with the following steps:

Update the camera time (Camera::SetTime()).
Generate a camera noise map (Camera::GenAmplitudeNoiseMap()).

Then for each astrophysical source, added with AddSource(), particles are generated:

The number of particles is randomly drawn with Source::GetParticleN() and reweighted by \(\cos\theta\), where \(\theta\) is the angle between the telescope pointing axis and the source direction.
Warning
This is an approximation for non-localized sources.
The particle parameters are drawn and saved with Source::GenerateAstroParticles().
For each particle:
- The incoming direction is computed in the telescope reference frame.
- The telescope acceptance is checked using a binomial test and the particle can possibly be ignored.
- If the particle is a photon, the telescope PSF is applied with ApplyPsf() and the camera hit coordinates are computed. The interaction with the camera is finally simulated with Camera::AddPhoton().
- If the particle is a cosmic ray, the camera entry point is randomly chosen in the camera plane. Then the interaction with the camera pixels is simulated with Camera::AddCosmicRay().
- If the particle is a background photon, the camera hit coordinates are computed, without applying the PSF. The interaction with the camera is simulated with Camera::AddPhoton()

Warning

During the camera integration time, the telescope orientation is assumed to be static and equal to the angles previously provided with Rotation::SetAlphaBetaGamma().

The picture can only be saved (see Camera::TreeWrite()) if all the following TTree have been activated:

Camera::TreeInit()
Source::TreeInit() for all sources.

Parameters

[in] aTimeStart Start time in [ms].

Member Data Documentation

◆ tel_acc

vector<TH2F*> Telescope::tel_acc

private

telescope acceptance to sources.

◆ tel_effarea

vector<TGraph*> Telescope::tel_effarea

private

telescope on-axis effective area to sources.

◆ tel_file

TFile* Telescope::tel_file

private

current TFile.

◆ tel_foclen

int Telescope::tel_foclen

private

telescope focal length \([\mathrm{mm}]\).

◆ tel_name

string Telescope::tel_name

private

telescope name.

◆ tel_psf

TH3F* Telescope::tel_psf

private

telescope optical point spread function (PSF).

◆ tel_psf_ebins

TArrayD* Telescope::tel_psf_ebins

private

energy bins for the PSF.

◆ tel_psf_nebins

int Telescope::tel_psf_nebins

private

number of energy bins for the PSF.

◆ tel_psfe

TH2F** Telescope::tel_psfe

private

telescope optical point spread function at one energy.

◆ tel_src

vector<Source*> Telescope::tel_src

private

vector of sources.

The documentation for this class was generated from the following files:

src/Telescope/Telescope.h
src/Telescope/Telescope.cc

Public Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

The telescope geometrical description

The telescope optics

How to configure a Telescope object

Telescope geometry and optical design

Telescope CCD camera

Astrophysical sources

Astro-particle detection

Taking a picture

Run an observation sequence

Constructor & Destructor Documentation

◆ Telescope()

◆ ~Telescope()

Member Function Documentation

◆ AddSource()

◆ ApplyPsf()

◆ GetEffectiveArea() [1/3]

◆ GetEffectiveArea() [2/3]

◆ GetEffectiveArea() [3/3]

◆ GetFocalLength()

◆ GetName()

◆ GetPsf() [1/3]

◆ GetPsf() [2/3]

◆ GetPsf() [3/3]

◆ SetFocalLength()

◆ SetName()

◆ SetPsf() [1/2]

◆ SetPsf() [2/2]

◆ SetPsfAiry()

◆ SetPsfFile()

◆ StartObservation()

◆ StopObservation()

◆ TakePicture()

Member Data Documentation

◆ tel_acc

◆ tel_effarea

◆ tel_file

◆ tel_foclen

◆ tel_name

◆ tel_psf

◆ tel_psf_ebins

◆ tel_psf_nebins

◆ tel_psfe

◆ tel_src