Instrument and Site Characteristics
A number of observatories are implemented in PhoSim through the use of the Instrument and Site Characteristics Files (ISC). These are directories located in phosim/data. If you want to put a new observatory into PhoSim you can create a new directory there, and then run PhoSim as usual with the "-i newDirectory" option to point to the ISC files.
The ISC files have a complex tiered format and this format does get modified as PhoSim is improved, so it may be necessary to email us when getting into the details. However, the details of the ISC are designed to be tiered, so that simple important characteristics can be implemented without worrying about the additional details.
Primary ISC files:
1) optics_?.txt files (required)
The first line of the optics file specifies the approximate properties of the whole system. These values are not used for simulating the system, but only for various approximations to decide what should be simulated. If you are inputting an untested optical design
optics X1 X2 X3 X4 X5 X6 X7 X8
X1 is name of configuration, X2 is the shortest wavelength of the system (not filter short wavelength) in microns, X3 is the longest wavelength of the system (not filter long wavelength) in microns, X4 is the approximate average wavelength of the configuration in microns, X5 is the approximate plate scale in microns per degree, X6 is -1 if the focal plane is flipped in x and 1 if it is not, X7 is if the focal plane is flipped in y and 1 if it is not, and X7 is 1 if x and y are swapped and 0 if it is not
The next lines specify the full details of the optical design. The columns are as follows:
Column 1: name of optic
Column 2: optic type (either mirror, filter, lens, det (detector plane), grating, or none (dummy surface))
Column 3: radius of curvature (mm)
Column 4: distance from last optic (mm)
Column 5: outer radius (mm)
Column 6: inner radius (mm)
Column 7: conic constant
Column 8-22: polynomial constants starting at 2nd degree
Column 23: coating properties file (none=assumes perfect transmission/reflection; uncoated=calculates as if uncoated)
Column 24: material optical properties file
Column 25: material mechanical properties file
For a grating (column 2) the column meanings change to:
Column 1: name of optic
Column 2: grating
Column 3: Must be 0.0; All gratings are assumed to be flat
Column 4: distance from last optic
Column 5: outer radius
Column 6: inner radius
Column 7: Not used
Column 8: transmission blaze angle in degrees
Column 9: Number of illuminated ruled grating lines
Column 10: Spacing of ruled lines (mm)
Column 11: Lower wavelength (nm) for table
Column 12: Upper wavelength (nm) for table
Column 13: Lower input angle (deg) for table
Column 14: Upper input angle (deg) for table
Column 15: Lower input angle (deg) for table
Column 16: Upper input angle (deg) for table
Additional notes on gratings: PhoSim will pre-calculate a table one time that takes minutes, and then this file will be used the next time PhoSim to be able to run quickly. The grating is nominally oriented in the y-direction. See data/gratingtest/optics_1.txt file for an example.
2) focalplanelayout.txt file (required)
The rows are the sensors in the focal plane. The columns are as follows:
Column 1: name of sensor (gets used with the -s option as well as the file naming convention)
Column 2 and 3: x position in focal plane in microns and y position in focal plane in microns
Column 4: pixel size in microns
Column 5 and 6: number of x pixels, number of y pixels
Column 7: sensor material (silicon or MCT)
Column 8: device type either CCD or CMOS (note CMOS also means Fast Frame CCD, and CCD with 0 readout time also means CMOS where you can set the exposure)
Column 9: readout integration mode (frame or sequence)
Column 10: readout time (CCD) or frame rate (CMOS) in seconds
Column 11: photosensitive layer thickness in microns
Column 12: group of sensors named group0, group1, etc. This is used for the camera configuration which is a bit mask for each type.
Column 13-15: 3 euler rotations in degrees
Column 16-18: 3 translations in mm
Column 19: name of sensor file
Column 20: additional defocus relative to focal plane in mm
3) site.txt file (optional)
A set of commands in any order. All commands are optional as each have their defaults. In particular, if you just specify the first three (latitude, longitude, and ground level), the global representations will predict all of the other distributions and parameters. Basic commands:
latitude X: latitude in degrees (N from equator)
longitude X: longitude in degrees (E from prime meridian is positive)
groundlevel X: ground level in meters
spacemode X: (X=0 ground, X=1 Low Earth Orbit, X=2 Lagrange 1, X=3 Lagrange 2, X=4 Lagrange 3, X=5 Lagrange 4, X=6 Lagrange 5)
Alternatively, there is a very large library of sites for most major cities in the World as well as many telescope sites. They can be found in data/standard/location. They can be used by either copying the chosen file to the instrument and site directory, or the existing site can be overridden with the --site=x command line option. Note: in the second case you should not use the .txt extension.
More advanced commands that are only necessary if want to override PhoSim distributions:
xtellocation X: offset from nominal location in x (useful for simulating telescopes on same site)
ytellocation X: offset from nominal location in y
outerscalemean X: mean outer scale of the turbulent free atmosphere
outerscalemedian X: median outer scale of the turbulent free atmosphere
domeseeingmean X: dome seeing mean in arc seconds
domeseeingmedian X: dome seeing median in arc seconds
turbulence X1 X2 X3 X4 X5 X6 X7 X8 X9 X10 X11: turbulence statistics for location in atmosphere
X1 is low range altitude, X2 is mean altitude, X3 is high range altitude, X4 is low range Cn2, X5 is median Cn2, X6 is high range Cn2, X7 is log variance of Cn2, X8 is low range Cn2 for ground layer, X9 is median Cn2 for ground layer, X10 is high range Cn2 for ground layer, X11 is log variance of Cn2
bortle X: the Bortle index of the site's artificial light contribution
artificial X: the artificial brightness in mag/sq. arcsecond (redundant with Bortle)
4) structure.txt file (optional)
windjitter X: variation in wind direction degrees
rotationjitter X: variation in rotation tracking (arcseconds)
elevationjitter X: variation in elevation tracking (arcseconds)
azimuthjitter X: variation in azimuth tracking (arcseconds)
windshake X: variation in wind shake (arcseconds)
rotationconstraint X: +/- angular in rotation of camera (degrees)
crossx X1 X2 X3 X4 X5 X6: X1=height of structure in x direction (mm), X2= width of structure (mm), X3=offset of structure from center (mm), X4=depth of structure (mm), X5=tilt of structure (degrees), X6=reference point where tilt occurs (mm)
crossy X1 X2 X3 X4 X5 X6: X1=height of structure in y direction (mm), X2= width of structure (mm), X3=offset of structure from center (mm), X4=depth of structure (mm), X5=tilt of structure (degrees), X6=reference point where tilt occurs (mm)
5) perturbation.txt file (optional)
The perturbation file described deviations from the ideal optic shape through a wide variety of mechanisms. It is also used to deal with complex geometries (non-cylindrically symmetric systems). Some perturbations can be static and some can be dynamic.
Column 1: name
Column 2: optic number (for more than one you can string together as 0|1|2)
Column 3: perturbation type (map, zernike, zlist, body, shape)
Column 4: perturbation value
Column 5: perturbation degree of freedom
Column 6: actuator number (for moving the degree of freedom with move command)
Column 7: actuator scaling
Column 8: actuator scaling constant
Column 9: actuator scaling angle
Column 10: actuator scaling cosine coefficient
Column 11: actuator scaling sine conefficient
Column 12: actuator scaling uniform random
Column 13: actuator component
Column 14: actuator component scaling
For the mechanical surface distortion, column 3 should be set to shape, and then the remaining columns follow
Column 4: tolerance
Column 5: control flag
Column 6: wavefront error
Column 7: actuator error
Column 8: angular tolerance
Column 9: initial step
Column 10: zernike start
Column 11: actuator start
6) segmentation.txt file (required)
The segmentation file describes the readout properties of the system.
For each chip an initial line describes the number of lines. The chip name should be consistent with the focal plane file.
chip_name number_of_amplifiers pixels_x pixels_y
chip_name: name describing chip (should match with focalplanelayout.txt file)
number_of_amplifiers: number of amplifiers for this chip
pixels_x: pixels in the x-direction
pixels_y: pixels in the y-direction
Then the next lines should be for each amplifier which defines which pixels are part of the amplifier as follows (all numbers are on a single line). The variation parameter are given in percentage. The cross-talk probability with other amplifiers end the line and there should be one element per amplifier.
amplifier_name x_min x_max y_min y_max serial_read_dir parallel_read_dir gain gain_variation bias bias_variation
read_noise read_noise_variation dark_current dark_current_variation parallel_prescan serial_overscan serial_prescan parallel_overscan hot_pixel_rate hot_column_rate
read_out_bits cross_talk_prob_1 cross_talk_prob_2 cross_talk_prob_3....cross_talk_prob_n ipc10 ipc11 ipc20 ipc21 ipc22 ppc
amplifier_name: amplifier name
x_min: starting pixel value in x
x_max: ending pixel value in x
y_min: starting pixel value in y
y_max: ending pixel value in y
serial_read_dir: direction of serial read (either +/- 1)
parallel_read_dir: direction of parallel read (either +/- 1)
gain: gain of amplifier
gain_variation: gain variation in percentage
bias: bias value of amplifier
bias_variation: bias variation in percentage
read_noise: read noise average value in electrons
read_noise_variation: read noise variation in percentage
dark_current: dark current in electrons per second
dark_current_variation: dark current variation in percentage
parallel_prescan: number of extra values in the prescan in the parallel direction
serial_prescan: number of extra values in the prescan in the serial direction
parallel_overscan: number of extra values in the overcan in the parallel direction
serial_overscan: number of extra values in the overscan in the serial direction
hot_pixel_rate: probability of having a hot pixel
hot_column_rate: probability of having a hot column
readout_bits: number of bits in the readout A/D conversion
cross_talk_prob_X: matrix value for cross-talk interaction with amplifier X
ipc10: relative inter-pixel capacitance in neighboring pixels
ipc11: relative inter-pixel capacitance in diagonals pixels
ipc20: relative inter-pixel capacitance in neighboring pixels 2 pixels away
ipc21: relative inter-pixel capacitance in pixels 2 pixels over and 1 pixel up/down
ipc22: relative inter-pixel capacitance in diagnoal pixels 2 pixels away
ppc: relative post-pixel coupling
Secondary ISC files:
7) coating files (optional)
This file contains the information to describe the interaction with coatings on the optics or detectors. There are three formats of input: 1) a set of standard coatings, 2) full specification by interference physics method and 3) full specification by the full numerical table format.
First, there are a set of standard coatings that are found in data/coating/standard. These include:
Detector Anti-Reflective: detector_ar
Lens Anti-Reflective: lens_ar
Johnson-Cousins Filters: jc_u, jc_b, jc_v, jc_r, and jc_i
SDSS Filters: sdss_u, sdss_g, sdss_r, sdss_i, and sdss_z
Mauna Kea Observatory Near-IR Filters: mko_y, mko_h, mko_j, mko_k, mko_kp, mko_ks, mko_lp, and mko_mp
All of these coatings can simply by used by putting the names above in the optics file. Then, no file is necessary in the instrument and site directory. These coating files can be very useful in implementing a new telescope quickly.
Second, full interference physics can be calculated for a variety of coatings when the details are known. This may be more accurate than the table method below depending on the information in the table.
For a single layer use:
monolayer material_name thickness
where the thickness is in microns. The material name is found in the data/material/optical directory. This would be most common for an A/R coating on a lens.
For a semi-infinite coating (typically on a mirror) use:
thicklayer material_name
For a semi-infinite coating (typically on a mirror) with a single layer coating use:
protectedlayer material_name substrate_name thickness
where the thickness is in microns, and the first material is for the single layer, and the second layer is for the semi-infinite coating.
For all coatings, the coatings can be deposited in an non-uniform manner by adding on the following command.
nonuniform NTERM TERM1 TERM2 ...
where NTERM is the number of terms (zernike polynomials for optics and chebyshev polynomials for sensors) and then the coefficient in microns for each term.
Third, the coating file can specify the transmission and reflection through a full table format.
For coatings on lenses (including filters) the format is
angle wavelength transmission_probability reflection_probability
The angle is given in degrees, and the wavelength is given in microns. The difference in the sum of transmission and reflection from 1 is the absorption probability.
For coatings on mirrors the format is:
angle wavelength reflection_probability transmission_probability
The angle is given in degrees, and the wavelength is given in microns. The difference in the sum of transmission and reflection from 1 is the absorption probability. Note the columns are flipped from the lens formats.
If only 1 angle is given, then PhoSim will approximate the angular dependence.
8) material optical properties files (optional)
This file has two columns to represent the index of refraction as a function of wavelength. The wavelength is in microns. The spacing of the wavelength grid can be variable.
wavelength index_of_refraction imaginary_part_of_index_of_refraction
9) material mechanical properties files (optional)
The material mechanical properties files describes the material properties and mounting properties of any optic. This file is optional and is used for the full mechanical simulation of a given optic. The commands can be given in any order.
mountPoint X: mounting points in one direction
mountVertical X: mounting points in vertical direction
mountRim X: mounting points around rim of surface
mountType X: X=0 mounted from bottom; X=1 mounted from top; X=2 mounted from side
mountHexagon X: mounting points across hexagonal object
mountSubHexagon X mounting points in each hexagon
segmentHexagon X: sets the number of hexagonal segments
heatCapacity X: X is the heat capacity
thickness X: X is the thickness of the optic in mm
density X: X is the density in kg per cubic meter
fillFactor X: X is the fill factor of the given material
thermalConductivity X: X is the thermal conductivity
youngsModulus X: X is the Young's modulus of the material
poissonRatio X: X is the Poisson ratio of the material
nominalTemperature X: X is the nominal temperature optic is created for in degrees Celcius
nominalGravity X: X is the nominal gravity factor (1=Earth, 0=no gravity) the optic is designed for
thermalExpansionCoefficient X: X is the thermal expansion coefficient
constraintSize X: size of actuator footprint (m)
constraintRim X: size of actuator footprint on rim mounts (m)
blankType X: X=0: flat surface; X=1: constant thickness
firstFocus X: effective focus scaling factor
secondFocus X: effective focus scaling factor for secondary optics
coolingPerformanceRate X: effective cooling rate, if additional (W)
10) sensor properties files (optional)
The sensor properties files shows the detailed properties of an individual sensor. This sensor propeties file is optional as well as all of the commands are optional. There are a set of standard sensor properties for three sensor types:
Silicon: p_type, n_type
Mercury Cadmium Telluride: mct
The three sensor file names can simply be added in the focalplane file to get a default set of properties. They are located in data/standard/sensor.
Alternatively, the details can be specified. By default, the values will default to an ideal perfect sensor. The commands below can be entered in any order.
edgeSurfaceCharge X: X is the effective charge density per sq. cm
treeRingPeriod X: X is the tree ring period in microns
treeRingAmplitude X: X is the tree ring amplitude
treeRingRatio X: X is the ratio of sensor to wafer size
treeRingVariation X: X is the variation of the period in microns
treeRingDecay X: X is the decay in microns of the tree ring patter
deadLayerDepth X: X is the depth in microns of the dead layer
deadLayerWidth X: X is the width of the laser annealing pattern in microns
deadLayerHeight X: X is the height of the laser annealing pattern in microns
deadLayerXoverlap X: X is the offset in microns of the annealing pattern
deadLayerYoverlap X: X is the offset in microns of the annealing pattern
deadLayerXinit X Y: X is the number of pattern and Y is the offset in microns
deadLayerYinit X Y: X is the number of pattern and Y is the offset in microns
deadLayerAngle X Y: X is the number of the pattern and Y is the angle in degrees
pixelVarX X: X is the lithographic pixel size variation fraction in the x direction
pixelVarY X: X is the lithographic pixel size variation fraction in the y direction
wellDepth X: X is the full well depth in microns
nbulk X: X is the doping charge density per cubic cm
nf X: X is the front side charge density
nb X: X is the back size charge density
sf X: X is the scaling length of the front side doping
sb X: X is the scaling length of the back side doping
spaceChargeShield X: X is the suppression factor of the accumulated charge field
spaceChargeSpreadX X: X is the effective full well charge spread in microns
spaceChargeSpreadY X: X is the effective full well charge spread in microns
chargeStopCharge X: X is the effective charge density of charge stops
siliconType X: X is the silicon type (-1 is electron/ 1 is holes)
sensorTempNominal X: X is the nominal temperature in Kelvin
shapeType X: X is the non-flatness method (either zern or cheb)
shapeValue X Y Z: X is the coefficient number, Y is the mean value in microns, Z is the variance in microns
inactiveX X: X is the number of shielded pixels in the x-direction (no photons)
inactiveY X: X is the number of shielded pixels in the y-direction (no photons)