PhoSim Tutorial 3: How to simulate a single star

To simulate a single star with PhoSim via the command line, simply do:

The process should complete in less than a minute and then a series of output files will be produced There are two types of output images: raw amplifier images (output/....a.fits.gz) and electron images (output/....e.fits.gz) which are the image of the electrons prior to readout (not possible in real life). The amplifier images are similar to what would be obtained at an actual telescope. However, the electron images will have many of the more basic readout effects removed (gain/offsets) that are often the first step of a calibration pipeline. Therefore, most users have found the electron images more useful to just getting started.

The images may be examined with ds9 or other FITS tools or with various packages common in astronomical research. With DS9 you can look at the output image by using this command:

Here is what the chip image from the example should look like (zoomed in X4 and in log scale): 

If you do have ds9 installed, you can repeat the process above in a single step with:

Then DS9 will pop up when the simulation is complete, which is particularly useful for longer simulations.

PhoSim is a Python script that runs a series of C++ codes. The only required input of PhoSim is called an Instance Catalog as the primary command line argument. PhoSim uses this term to describe what is in the sky at a particular time. If the objects are not time variable, then it simply contain information about what is in the sky. PhoSim is capable of trimming the catalog down to remove the objects that are not in the field of view, so its not necessary for the user to worry about the complexity of chip orientations and field rotations. However, for ambitious simulations, catalogs with essentially all objects in the Universe could be quite large, so a smaller fraction of the objects that might be in the field of view should sometimes be given to PhoSim. The instance catalog also contains a set of telescope operator commands that specify parameters of the observation. These commands are basically either things that an operator would control (e.g., pointing position) or things that an observer could require (e.g. for the moon to be below the horizon) before the observation is taken.

A complete set of documentation of instance catalog can be found at the Instance Catalog page. However, following the tutorials will go through some uses of this, including some novel uses.

The instance catalog for the above single star example looks like:

The first four lines specify the pointing, the vistime specifies the visit time of 15 seconds, the nsnap specifies there is a single exposure, and moonalt at -90.0 puts the moon below the horizon. Finally, the object line specifies a single 20th AB magnitude star at a position of 0,0 with a flat spectral energy distribution (SED). This is a somewhat artificial example. The object's position is exactly placed at the foresight of the telescope. 

It is also artificial because we have specified the pointing position and the alt/az of the telescope. With a real telescope, one could only specify the alt/az and then the ra/dec would depend on the observing time as well as the latitude/longitude of the telescope. PhoSim can calculate this as well, but PhoSim lets you specify inconsistent parameters if that is desired. In this case, it is useful to do this, because we simply want to have a star in the center of the field and we do not want to do an inverse visibility calculation. Another interesting aspect of this example is that there are very few commands to generate this example. PhoSim's interface philosophy is to always do the most realistic self-consistent physics unlessthe user overrides it. 

We also used another aspect of PhoSim's interface by including a command-line option with the command file -c examples/nobackground. The command file with the -c option includes commands to override the realistic self-consistent default physics. In this case, we wanted to turn off the background (which would be realistic) so the examples/nobackground includes this command.

The full documentation for the command file is found at the physics command page. The phosim script also accepts many other command-line options, such as a command file that contains optics, detector, or atmospheric parameters that may be manipulated. A list of command-line options may be found as follows: