 |
SatAndLight
2.2.2-hubble
Simulation toolkit for space telescopes
|
|
SatAndLight
2.2.2-hubble
Simulation toolkit for space telescopes
|
Classes of SatAndLight are designed to save the result of a simulation in a ROOT file. These data are usually saved in a ROOT TTree in which the simulation output is distributed in branches. Specific classes are meant to read these data. For example, the Camera class offers functions to save pictures in a TTree in a ROOT file. Then the class CameraRead is used to read this TTree on disk to access the camera pictures in a ROOT file.
Sections below explain the file structure for the main classes of SatAndLight.
When a Camera object is created, it is usually meant to take pictures. These pictures can be saved in a TTree in a ROOT file. Each entry of the TTree is associated to a picture. Each picture comes with additional data characterizing the conditions in which the picture was taken: the camera pixel intrinsic noise, the camera size, the time of the picture and so on. Here is the typical functions you should call using your MyCamera Camera object:
// open a TFile
TFile *MyOutputFile = new TFile("./myfile.root","recreate");
MyOutputFile->cd();
// initialize the TTree
MyCamera->TreeInit();
// simulate your image...
// save your image (fill the TTree)
MyCamera->TreeFill();
// simulate more images and save them with TreeFill()
// save your TTree in the open TFile
MyCamera->TreeWrite();
// close the file
MyOutputFile->Close();
You can simulate as many camera images as you need and you can save them by calling Camera::TreeFill() for each of them.
The camera images saved in one or several ROOT files can be loaded using the CameraRead class.
The TTree generated by the Camera class is structured with the following branches:
cam_map_amplitude (TH2S): this is the camera picture represented by a 2-dimensional histogram.cam_map_darknoise (TH2S): this is the camera pixel dark noise map represented by a 2-dimensional histogram.cam_map_readnoise (TH2S): this is the camera pixel read noise map represented by a 2-dimensional histogram.cam_map_gain (TH2F): this is the camera pixel gain map represented by a 2-dimensional histogram. The gain is used to convert the pixel raw amplitude to a calibrated energy.cam_nbits (int): number of bits to encode the pixel raw amplitude.cam_xsize (double): camera size in the X direction (or thickness) in [mm].cam_ysize (double): camera size in the Y direction in [mm].cam_zsize (double): camera size in the Z direction in [mm].cam_time (unsigned long int): picture time in [ms].cam_dt (unsigned int): camera integration time in [ms].cam_hitn (int): number of particle hits in the picture.cam_hitsrc (int[cam_hitn]): list of source indices associated to the particle hits.cam_hitastro (int[cam_hitn]): list of particle indices associated to the particle hits.cam_hity (double[cam_hitn]): list of Y positions associated to the particle hits.cam_hitz (double[cam_hitn]): list of Z positions associated to the particle hits.Astrophysical sources are simulated using the Source class. The result of a simulation is saved in 2 TTree structures. The first TTree contains a single entry and summarizes the source properties (type, position, flux, size...). The second one constains all the astro-particles generated for this source.
The methods offered by the Source class to manage the TTree structures is very much similar to the Camera class. After opening a TFile, you need to call Source::TreeInit() which creates the trees. This is where the source properties are saved and they can no longer be modified after that (unless you open a new file). So, you must make sure that your source is entirely configured before calling Source::TreeInit(). The astro-particle TTree is created. Then it is filled with particles when you call Source::GenerateAstroParticles(). Finally the trees are saved to disk when calling Source::TreeWrite(), after what the file can be closed.
The source properties, as well as the simulated astro-particles, saved in one or several ROOT files can be loaded using the SourceRead class.
Two TTree structures are generated by the Source class:
[SOURCE_NAME], one single entry:src_type (int): this is the source type: photons of cosmic rays (see also Source::sourcetype).src_flux (TH2D): this is the source particle flux as function of time and energy (see also the convention for the source flux).src_rate (TH2D): this is the source particle rate as function of time and energy (see also the convention for the source rate).src_thetap (TGraph): this is the source \(\theta'_S\) position angle as a function of time (see also the convention for the source position).src_phip (TGraph): this is the source \(\varphi'_S\) position angle as a function of time (see also the convention for the source position).src_cosconeangle (TGraph): this is the source \(\cos\theta\) parameter as a function of time to measure the source extension in the sky.[SOURCE_NAME]_astro, one particle = one entry:astro_time (unsigned long int): this is the particle time [ms].astro_thetap (double): this is the particle \(\theta'_p\) position angle [rad].astro_phip (double): this is the particle \(\varphi'_p\) position angle [rad].astro_energy (double): this is the particle energy [keV].A telescope structure is quite complex. On top of specific parameters, it includes one camera object as well as multiple astrophysical sources. The Telescope class internally organizes all the derived TTree structures inside a TDirectory named after the telescope. The camera TTree, described in the camera section, is named: [TELESCOPE_NAME]_cam. Several source structures are saved in the telescope directory. The source trees, described in the source section, are saved as is, since sources have a unique name. Finally the Telescope class generates its own TTree, named after the telescope and with a single entry, to save the telescope-specific parameters (point spread function, focal length...).
The user should not deal with all the individual components (camera, sources...) to save the simulation in TTree structures. Instead, these steps should be followed:
The entire telescope simulation, saved in one or several ROOT files can be loaded using the TelescopeRead class.
A TDirectory is created and named after the telescope. Hence, multiple telescopes can be simulated simultaneously and saved in the same file. The image below shows a typical example of a Telescope file structure. There are two telescopes named "TEL1" and "TEL2".
The directory of "TEL1" contains six TTree structures:
TEL1 is the Telescope parameter TTree:tel_psf (TH3F): this is the telescope point spread function.tel_foclen (int): this is the telescope focal length in \([\mathrm{mm}]\).tel_effarea_src_[SRCNAME] (TGraph): this is the telescope effective area for source with name [SRCNAME].tel_acc_src_[SRCNAME] (TH2F): this is the telescope acceptance for source with name [SRCNAME].TEL1_cam is the telescope camera TTree. The stucture of this element is described in the camera section. When associated to a telescope, the camera TTree includes three additional branches to capture the telescope orientation in space:rot_alpha (double): this is the Euler angle \(\alpha\) (see the rotation description conventions).rot_beta (double): this is the Euler angle \(\beta\) (see the rotation description conventions).rot_gamma (double): this is the Euler angle \(\gamma\) (see the rotation description conventions).TEL1_MONOSRC is the Source ("MONOSRC") parameter TTree, as described in the astrophysical sources section.TEL1_MONOSRC_astro is the astro-particle associated to the "MONOSRC" source TTree, as described in the astrophysical sources section.TEL1_COSMIC is the Source ("COSMIC") parameter TTree, as described in the astrophysical sources section.TEL1_COSMIC_astro is the astro-particle associated to the "COSMIC" source TTree, as described in the astrophysical sources section.A Satellite object is the master object to drive a SatAndLight simulation. It should be seen as a collection of telescopes associated to a clock and a flight sequence (position). When working with a Satellite object, the user does not have to worry about the file organization. Only the output directory and the file duration have to be specified. When a running a sequence (Satellite::RunSequence()), the class object manages all the telescopes and takes pictures as specified in the configuration.
The entire simulation, saved in one or several ROOT files can be loaded using the SatelliteRead class.
The file structure is described in the file structure section for telescopes.
2.2.2-hubble