Clone wiki

phosim_release / Walkthrough

(Back to Home)


The main Photon Simulator (PhoSim) page has a number of links to technical PhoSim content. Following is a brief walkthrough about installing and running the code and some basic techniques in cookbook form.

Getting the Code

There are two ways of obtaining the phosim package:

tar xzf  v-5.0.tar.gz
  • or download the entire git tree and use git commands as normal (only recommended if you are familiar with git). The master branch is configured to be the most recent stable version (git checkout master).

Installing PhoSim

Once the directory hierarchy is in place, the package is installed via:


The configure script provides an option of installing cfitsio and fftw, if they are not yet installed on the local system. Note that the python module, multiprocessing, is needed, which requires python >= 2.6.

PhoSim GUI

The easiest way to learn about the most basic uses of PhoSim is by using the GUI. The GUI has most of the features but not all. It is a good way to get started without reading pages of documentation and can be useful in most studies. To launch the GUI, simply type:


The PhoSim GUI then should look something like (it may be different depending on your OS):


One simple test is to simply hit the run button without changing any options. It will make a simple simulation of a single star similar to the example below.

Simple Command Line Examples

If the installation is successful (i.e., with no errors), you may test phosim by simulating a single star:

phosim examples/star -c examples/nobackground

Two types of output images are produced: 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 images may be examined with ds9 or other FITS tools.

ds9 output/lsst_e_99999999_f2_R22_S11_E0000.fits.gz

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


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

phosim examples/star -c examples/nobackground --ds9

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

Phosim is a python script that requires an instance catalog as a command-line argument. The format of the instance catalog can be found at the Instance Catalog page. In this example, we have deliberately turned of sky background. This is a very common use, because note that there are overwhelmingly more photons from background than there are astrophysical sources. There are approximations for background photons to make them simulate a couple of orders of magnitude faster, but there are still billions of photons in a single image. There are also options to make the background simulate several orders of magnitude faster, by averaging over sensor details using examples/quickbackground. The following would generate an image with background quickly:

phosim examples/small_catalog -c examples/quickbackground

For detailed science applications requiring background, it is best though to use no special commands in order to not approximate any of the sensor physics and therefore no options in the command file should be used.

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:

phosim -h
phosim --help

More complex uses of PhoSim

To simulate a field of astronomical objects you can use a full catalog following the PhoSim Instance Catalog format. An example of this covering part of one chip is :

phosim examples/small_catalog -c examples/nobackground

It should look like this (log scale and zoomed in):


PhoSim has many options to modify or override the default settings. The nominal settings are based on the most realistic physics. There are many cases where it is useful to study parts of the simulation to determine what aspect of the simulation may affect a particular measurement or property of the images. A series of commands can be placed in an physics override file for many different kinds of simulations. One example of this would be to place these commands in a file (called commandfile):

opticsonlymode 0
backgroundmode 0
pixelsize 0.1

This would then ignore aspects of the sensor and atmosphere simulation and simulate objects with very small pixel sizes (0.1 microns). Then a simulation with the following command

phosim examples/brightstar -c commandfile

would produce an image like this:


which demonstrates the large amount of detail in the optical raytracing in PhoSim. This is just one example of the many uses of the command file.

Another complex use of PhoSim is to simulate other telescopes. There are a set of files called the instrument and site characteristics (ISC). By default, PhoSim points to the files in data/lsst. However, new directories can be created or other implemented designs can be simulated using the -i option.

Generating Calibration Data

Calibration data can be generated in a similar manner as with a real telescope.

A bias frame can be generated with the catalog:

nsnap 1
vistime 0.0
minsource 0
obshistid 9999

The electron image will be empty, and the amplifier images will have the appropriate bias level and read noise.

A dark can be generated with the catalog:

nsnap 1
vistime 150.0
minsource 0
telconfig 1
obshistid 9999

The electron image will contain many cosmic rays since the exposure time is 150 seconds, and the appropriate dark current will be in the amplifier images.

A flat can be generated with the following catalog:

obshistid 9999
nsnap 1
vistime 15.0
telconfig 2
filter 2
minsource 0
domeint 28.0
domewav 0

This catalog will close the dome and put on the dome light (telconfig 2). The dome light will have an intensity of 28.0 magnitudes per sq. arcsecond and a flat spectrum (domewav 0). This flat will have very few photons due to the intensity, but a more realistic flat can be generated with a domeint of 18.0.