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), X3 is the longest wavelength of the system (not filter long wavelength), X4 is the approximate average wavelength of the configuration, X5 is the approximate plate scale, 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
Column 4: distance from last optic
Column 5: outer radius
Column 6: inner radius
Column 7: conic constant
Column 8-22: polynomial constants starting at 2nd degree
Column 9: coating properties file
Column 10: material optical properties file
Column 11: 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 nominal 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
More advanced commands:
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
rotationjitter X
elevationjitter X
azimuthjitter X
windshake X
rotationconstraint X
crossx X1 X2 X3 X4 X5 X6
crossy X1 X2 X3 X4 X5 X6
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:
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 pixels_x pixels_y
Then the next lines should be the 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_1 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....
Secondary ISC files:
7) coating files (optional)
This file contains the information to describe the interaction with coatings on the optics or detectors.
For coatings on lenses 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.
Interference physics can also be calculated for some coatings (currently limited to HfO2) using the alternate format as:
coating_name
thickness_zernike_0
thickness_zernike_1
thickness_zernike_2
....
The thickness is described by a zernike pattern and the coefficients are in units of microns.
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
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
mountVertical X
mountRim X
mountType X
mountHexagon X
mountSubHexagon X
segmentHexagon X
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:
constraintRim X:
blankType X:
firstFocus X:
secondFocus X:
coolingPerformanceRate X:
10) sensor properties files (optional)
The sensor properties files shows the detailed properties of an individual sensor. This file is optional as well as all of the commands are optional. 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)