# 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)