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 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 take.
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:
rightascension 0
declination 0
azimuth 0
altitude 89
vistime 15.0
nsnap 1
moonalt -90.0
object 0 0.0 0.0 20 ../sky/sed_flat.txt 0 0 0 0 0 0 star none none
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.
backgroundmode 0
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:
phosim -h
phosim --help
More examples of these are in the later tutorials.
