# 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 (none=assumes perfect transmission/reflection; uncoated=calculates as if uncoated)

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

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 two formats of input: 1) interference physics method and 2) the full numerical table format.

Full interference physics can be calculated for a variety of coatings. This may be more accurate than the table method 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 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.

Alternatively, 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 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)