Transcript
LASER INTERFEROMETER GRAVITATIONAL WAVE OBSERVATORY
LIGO Laboratory / LIGO Scientific Collaboration
LIGO-T1000155-v15
Advanced LIGO
Date: May 20, 2015
Hartmann sensor software architecture Authors: Aidan Brooks, Peter Veitch, Won Kim, Mindy Jacobson, Phil Willems. Distribution of this document: LIGO Scientific Collaboration This is an internal working note of the LIGO Laboratory. California Institute of Technology LIGO Project – MS 18-34 1200 E. California Blvd. Pasadena, CA 91125 Phone (626) 395-2129 Fax (626) 304-9834 E-mail:
[email protected]
Massachusetts Institute of Technology LIGO Project – NW22-295 185 Albany St Cambridge, MA 02139 Phone (617) 253-4824 Fax (617) 253-7014 E-mail:
[email protected]
LIGO Hanford Observatory P.O. Box 159 Richland WA 99352 Phone 509-372-8106 Fax 509-372-8137
LIGO Livingston Observatory P.O. Box 940 Livingston, LA 70754 Phone 225-686-3100 Fax 225-686-7189
http://www.ligo.caltech.edu/
LIGO
LIGO-T1000155-v15
Table of Contents 1 Purpose .................................................................................................................................................. 3 2 Scope ....................................................................................................................................................... 3 3 Reference Documents ....................................................................................................................... 3 4 Overview ............................................................................................................................................... 4 5 Nomenclature & Definitions ........................................................................................................ 10 6 Components ...................................................................................................................................... 11 6.1 Hartmann sensor PC ............................................................................................................................. 11 6.1.1 .bashrc environment variables .................................................................................................................... 11 6.2 PCIe Camera-‐Link Frame-‐Grabber ................................................................................................... 11 6.3 Dalsa 1M60 Camera .............................................................................................................................. 12 7 Communication ................................................................................................................................ 13 7.1 Camera Link connection ...................................................................................................................... 13 7.1.1 Low-‐bandwidth: Dalsa 1M60 Camera Control ..................................................................................... 13 7.1.2 High-‐bandwidth: Image transfer ................................................................................................................ 13 7.2 Hartmann sensor PC ............................................................................................................................. 13 7.3 EPICS .......................................................................................................................................................... 13 7.3.1 EPICS channel names ....................................................................................................................................... 13 8 States of Operation ......................................................................................................................... 17 8.0 State 0: Code ready to run ................................................................................................................... 17 8.1 State 1: Preparation .............................................................................................................................. 17 8.2 State 2: Initialization ............................................................................................................................ 17 8.2.1 State 2A: Check serial communication ..................................................................................................... 17 8.2.2 State 2B: Verify image frame acquisition ................................................................................................ 18 8.2.3 State 2C: Determine optimum exposure time ....................................................................................... 18 8.2.4 State 2D: load background level .................................................................................................................. 18 8.2.5 State 2E: Acquire template centroids ....................................................................................................... 19 8.2.6 State 2F: Load default magnifications (not shown in Figures). ..................................................... 19 8.3 State 3: Acquisition ............................................................................................................................... 19 8.3.1 State 3A: Acquire REFerence centroids ................................................................................................... 20 8.3.2 State 3B: Acquire LIVE centroids ................................................................................................................ 20 8.3.3 State 3C: Calculate gradient field ................................................................................................................ 21 8.3.4 State 3D: Calculate wavefront aberration ............................................................................................... 21 8.3.5 State 3G: Export data to frames ................................................................................................................... 21 8.4 State 4: Operator Intervention .......................................................................................................... 22 8.5 State 5: Interrupts or Alarms ............................................................................................................. 23 9 Description of HWS Classes ......................................................................................................... 25 10 Appendix: Least-‐squares fitting to the gradient field ....................................................... 27 11 Appendix: Writing gradient fields and phase maps to frames ...................................... 32 12 Appendix: Defunct States ........................................................................................................... 33 12.1.1 State 2D: Acquire dark image – earlier version ................................................................................. 33 12.1.2 State 2F: Check Probe-‐Beam-‐Centering – not implemented currently ................................... 33 12.1.3 State 2G: Check Hartmann Plate and ITM are conjugate – not currently implemented .. 34 2
LIGO
LIGO-T1000155-v15
12.1.4 State 2H: Re-‐determine optimum exposure time and dark image ............................................ 34 12.1.5 State 3E: Parameterize aberration .......................................................................................................... 34 12.1.6 State 3F: Update camera parameters ..................................................................................................... 34
13 Summary of units and exported variables ........................................................................... 36 13.1 centroids ................................................................................................................................................ 36 13.2 magnification ........................................................................................................................................ 36 13.3 gradients ................................................................................................................................................ 36 13.4 wf_numerical ........................................................................................................................................ 36 13.5 Polynomial coefficients of distortion (as per equation (1) in Section 10) ....................... 36 13.6 Seidel coefficients of distortion (as per equation (2) in Section 10) ................................. 36 13.7 Zernike-‐like coefficients of distortion (as per equation (3) in Section 10) ..................... 37
1 Purpose The goal of this document is to describe the software architecture of the Hartman Sensor Control System. The intent is that this document provides (a) an overview of the software in enough detail that the reader is able to understand the operation of the Hartmann sensor software within the context of the whole Hartmann sensor system, (b) an indication of robustness by virtue of a mapping of states to possible fault modes and (c) the code can interface with the rest of the LIGO CDS system including exporting data to LIGO approved frames and reading/writing control signals from and to EPICS.
2 Scope This document references the hardware, but is focused on the software. It is not a full software reference for the HWS, which can be found in the HWS Software Reference Manual.
3 Reference Documents T1000092: Section 4 – Software T1000484-v1, Hartmann sensor data storage and distribution requirements, A Brooks, P Willems, S O’Connor, R Bork, S Anderson, E Maros. P0900080-v1 Hartmann Wavefront Sensors for Advanced Gravitational Wave Interferometers, Brooks Thesis (2007) T1000703, Hartmann Wavefront Sensor Software Beta Version. T0900304-v2, Advanced LIGO Thermal Compensation System Preliminary Design T1000702, Hartmann Wavefront Sensor (HWS) Signal Processing Computer specifications E1300023, MIME type definition image/x-lhd, LIGO HARTMANN DATA
3
LIGO
LIGO-T1000155-v15
4 Overview An overview of the measurement subsystem of the Hartmann sensor is illustrated schematically in Figure 1. A Hartman probe beam (HWS SLED) is injected into the interferometer and overlays the IFO beam as it passes through the compensation plate (CP) and the ITM. The beam is retroreflected by the high reflectivity coating on the ITM. The wavefront reflected at the ITM is imaged onto the Hartmann plate, which creates a Hartmann spot pattern at the CCD. REFerence Hartmann spot centroids are recorded before the 1064 nm beam is injected into the IFO. As the power stored in the IFO is increased, absorption by the substrate and coating of the ITM, and by the CP, distort the LIVE probe wavefront, resulting in a transverse aberration of the Hartmann spot pattern relative to the REFerence spot pattern. The LIVE probe beam also measures wavefront changes introduced by heating of the CP by the thermal compensation system actuators. Ideally the compensation wavefront change should null the absorption-induced wavefront change. Changes in the ambient temperature of the laboratory will also result in distortion of the LIVE wavefront but that effect is considered negligible [T1200465 ].
HWS SLED Light Source
ITM + CP
probe beam
HWS Detection
EPICS control & extra input signals (from IFO and other sensors)
To Commissioner: characteristics of wavefront distortion. Display of Wavefront map
Figure 1: Inputs and outputs of the Measurement Part of the Hartmann sensor system
4
LIGO
LIGO-T1000155-v15
A more detailed diagram of the HWS Detection system is shown in Figure 2. This block includes all components involved in measuring a wavefront and calculating the absorption-induced wavefront distortion. The operation of this part of the HWS is 1. The wavefront incident on the Hartmann plate is conjugate to that at the ITM. 2. The Hartmann plate samples the incident wavefront, producing a set of rays that propagate normal to the wavefront. 3. A Dalsa 1M60 CCD camera records the spots formed when these rays intercept the CCD. This camera can record frames containing about 1 Mpixels, each of which is digitized with 11 bits (66 dB) of dynamic range at a maximum frame rate of 60 Hz. 4. The operation of the CCD camera is controlled using an EDT PCIe4 DVa C-Link frame grabber, which is housed in a Linux PC running the Ubuntu 10.10 OS. 5. The frame grabber is connected to the CCD camera using EDT RCX C-Link optical fiber converters and a duplex fiber of length about 100 m. This system allows frames from the camera to be transferred to the computer at data rates of up to 120 MB per second. 6. The software that controls the frame-grabber and, by extension, the CCD camera, resides and runs on the Linux computer. It is comprised of compiled MATLAB v.2009b and compiled C++ executables. It extracts individual frames from the camera. Frames are summed pixel-by-pixel to increase the photoelectron number for each pixel (referred to as the pixel value (PV)) and thus reduce the effect of shot noise. The position of the centroid of each spot in the summed-frame is calculated. 7. The transverse displacement of the centroid position of each spot (LIVE-REF) is divided by the “lever arm” distance between the Hartmann plate and the CCD to yield the change in the local gradient of the wavefront at the CCD, g xCCD , yCCD , due to the distortion.
(
)
8. The coordinates of the spots and the change in local gradient at those spots are then referenced to the TM HR surface using the magnification, M : xTM = xCCD × M , yTM = yCCD × M and gTM = gCCD M , creating the “gradient field”. Note that M > 1 . 9. The distortion represented by the gradient field is parameterized by least-squares fitting to a set of polynomials. 10. Amplitudes of common wavefront descriptors, such as prism, spherical and cylindrical power, and Zernike-like polynomials up to degree 2 are calculated from the amplitudes of the polynomials. 11. The gradient field is also numerically integrated to yield a map of the wavefront distortion. In principle, the wavefront distortion could also be characterized by Zernike decomposition, in which overlap integrals are used to calculate the amplitudes of Zernike functions that are orthonormal over the central circular region of the wavefront. However, numerical testing of this process indicated that the numerical integration of the gradient field introduced significant errors.
5
LIGO
LIGO-T1000155-v15 Probe beam from ITM
HWS plate assembly Hartmann rays Dalsa 1M60 Camera fiber-optic CameraLink connection
low bandwidth (settings)
high bandwidth (images)
serial port
EDT frame grabber
Linux PC
HWS Detection
image buffer
HWS software (MATLAB & C++)
commands & extra input signals
- gradient field to frames - characteristics of wavefront distortion
Figure 2: An expanded view of the HWS System [Measurement Part] from Figure 1. This block contains the Hartmann plate, the Dalsa 1M60 CCD camera, the CameraLink/fiberoptic cable and a Linux PC containing an EDT frame-grabber and running the HWS software described here. An overview of the HWS software block is shown in Figure 3. The software has three main states.1 •
State 1: Preparation. Software is preparing to run the HWS data acquisition. EPICS channel connections are established.
•
State 2: Initialization. Software determines if all necessary conditions to run the Hartmann sensor are TRUE, and determines the template used to seed calculation of the centroid locations.
1
The states 0-6 described in T1000092 have been condensed into the three main states described here and additional substates.
6
LIGO
•
LIGO-T1000155-v15
State 3: Acquisition. CCD fames are recorded, summed and analyzed as required to yield the wavefront gradient field. The gradient field is numerically integrated to yield wavefront aberration, and the aberration is parameterized using least-squares fitting of derivatives of Seidel functions to the gradient field.
State 1: PREPARATION command > start HWS State 2: INITIALIZATION
serial port image buffer HWS software (MATLAB & C++)
State 3: ACQUISITION (runs continuously)
extra input signals
serial port image buffer
- Seidel parametes to EPICS - integrated wavefront
Figure 3: An overview of the States of the HWS Software in Figure 2. The sub-states within the Initialization and Acquisition States are illustrated in Figure 4 and Figure 5 respectively. The States are described in more detail in Section 8.
7
LIGO
LIGO-T1000155-v15
State 0: Ready to run (code not running)
run_initialize_State1_initial_EPICS_parameters.m State 1: Preparation & EPICS
State 2: INITIALIZATION (prepare to run as HWS)
State2A
run_initialize_State2A.m - check serial communication with camera
IF FAIL
State2B
run_initialize_State2B.m - check image acquisition is normal
IF FAIL
State2C
run_acquire_State2C_check_camera_exposure.m - check camera exposure level & adjust if necessary
IF FAIL
State2D
run_acquire_State2D_get_background_value.m - get the average background level (default = 50 counts)
IF FAIL
State2E
run_acquire_State2E_get_template_centroids.m - get the template centroids for the current image
IF FAIL
State 3: ACQUIRE (run continuously as HWS)
EPICS message & END HWS
State 5: INTERRUPT/ALARM (code either running due to interrupt, or running with ALARMs activated)
Figure 4: Flow chart for the State 2: INITIALIZATION. Also shown is lead-in from State 0, 1 and the transition to State 3: ACQUIRE or State 5: INTERRUPT.
8
LIGO
LIGO-T1000155-v15
State 3: ACQUISITION (run continuously)
run_acquire_pull_EPICS_variables.m - update EPICS variables
State 3: REFerence or LIVE
run_acquire_top_of_loop_pause_checking.m - peek EPICS values to see if anything has changed
IF
State 4: OPERATOR INTERVENTION
run_acquire_State3A_get_reference_centroids_check.m - checks if REF centroids are requested via EPICS or during 1st loop
State3A
run_acquire_State3B_get_current_centroids.m - retrieves and centroids image from HWS
State3B
run_acquire_State3C_get_current_gradients.m - calculates current gradient field
State3C
State3D run_acquire_State3D_calculate_wavefronts.m - calculate wavefront from GRAD FIELD - exports data to EPICS channels
data to EPICS
run_acquire_get_parameters_check.m - check camera parameters every hour
State3G run_acquire_State3G_export_to_file.m - export gradient and wavefront data to file
data to frames
(States 3E and 3F are not currently used)
Figure 5: Flow chart for State 3: ACQUISITION and State 4: OPERATOR INTERVENTION.
9
LIGO
LIGO-T1000155-v15
5 Nomenclature & Definitions Definitions closed-loop – a generic control-systems term meaning the output signal being controlled is fed back in to the system and used as an input. probe beam – the Hartmann beam that propagates through the CP and the ITM. REFerence centroids – the initial position of the centroids measured by the HWS. LIVE centroids – the current position of the centroids measured by the HWS. Conventions Unless otherwise specified in the text of the document: • Items in black are the current plan-of-record. • Items in red are To-Be-Determined, alternative plans, or otherwise uncertain. • Items in blue are background information which is necessary to know in order to understand the context of the surrounding information. • Items in green are numbers, which are now set and expected to not change. • Items in darkblue are hyperlinks. • Text that is struck out has recently been changed/removed, but is left documented for reference. It will likely (but not necessarily) be removed entirely in the next revision of the document. Note: Occasionally pdflatex fails to preserve the color of a paragraph across a page boundary.
10
LIGO
LIGO-T1000155-v15
6 Components 6.1 Hartmann sensor PC This is shown in Figure 2. Full details about this PC can be found in T1000702. • • • • 6.1.1
Runs compiled Matlab executables. Controls frame-grabber and camera. Analyzes images. Exports data. .bashrc environment variables
Each HWS PC contains a list of environment variables in the .bashrc file that define names and directory locations that are unique to that PC. A full list of environment variables is presented in the following table. Table 1: List of environment variables on the HWS PC Variable name
Description
$HWS_EPICS
The top directory of the HWS_EPICS IOC
$HWS_DB
The directory containing the HWS EPICS database file
$HWS_DBARCHIVE
A directory to archive the old HWS EPICS database files
$HWS_IOC
The startup directory of the HWS EPICS IOC (usually $HWS_EPICS/iocBoot/iocHWS_epics).
$SOFTIOC_DIR
Location of the softIoc binary
$IFO
The name of the current IFO (e.g. H1, L1, I1)
$OPTIC0
The name of the 1st optic used in the code (e.g. ITMX)
$OPTIC1
The name of the 2nd optic used in the code (e.g. ITMY)
$HWS_CMD
The command to launch the HWS EPICS process
$PREFIX0
“$IFO:TCS-$OPTIC0”
$PREFIX1
“$IFO:TCS-$OPTIC1”
$HWS_FRAME_FOLDER
The location of the folder to save LHD_STRUCT frames containing gradient fields and wavefront maps.
$FRAME_ARCHIVE_DIR
The location of the archive for the HWS GWF frame files
6.2 PCIe Camera-Link Frame-Grabber Shown in Figure 2. Comes with SDK. Also described in T1000702.
11
LIGO
LIGO-T1000155-v15
6.3 Dalsa 1M60 Camera Shown in Figure 2. • •
Camera settings are controlled via serial communication access. The HWS software uses the serial_cmd command provided by frame-grabber SDK. Data frames are transferred from the camera to the computer using the take command provided by the frame-grabber SD.
12
LIGO
LIGO-T1000155-v15
7 Communication 7.1 Camera Link connection 7.1.1
Low-bandwidth: Dalsa 1M60 Camera Control
Serial 38400 baud, 8 data bits, no parity, 1 stop bit. 7.1.2
High-bandwidth: Image transfer
120 MB per second
7.2 Hartmann sensor PC Standard ethernet connection to LIGO network: See T1000702.
7.3 EPICS The HWS code uses EPICS channels to import instruction parameters and export data and processed results. The names of the EPICS channels are listed in Section 7.4. EPICS channel access is provided in MATLAB via the MCA (Matlab Channel Access) EPICS extension: http://ics-web.sns.ornl.gov/kasemir/mca/ Communication with the EPICS channels is assigned solely to the class HS_EPICS. An instance of HS_EPICS corresponds to an EPICS channel, and uses its instance methods (e.g., mca_open, mca_put, mca_get) to access/modify its channel value. HS_EPICS specifies which EPICS command file (of .cmd extension) should be used, launches EPICS only when the system does not have an existing EPICS process, and ensures that a HS_EPICS instance is correctly associated to its corresponding EPICS channel. Once an EPICS process is running, one can change the value of any EPICS channel using caput (Unix terminal command), mcaput (MCA command) or mca_put (an instance method of HS_EPICS). However, since the type checking of EPICS and MCA is not adequate to prevent the input of inappropriate values, we have introduced some protection against such changes. If a channel value retrieved by a HS_EPICS instance is invalid, it will be replaced by either the current value (HS_EPICS##current_value) or the default value (HS_EPICS##default_value) if the current value is not defined (e.g., in the beginning of HWS execution). The default values are contained within the Run_EPICS.m script. 7.3.1
EPICS channel names
EPICS channels are named
_EPICS_Base_Name, where •
•
is aa:TCS-b o aa is set by the environment variable IFO defined in .bashrc. It specifies the interferometer: H1, H2 or L1 o b is set by the environment variables OPTIC0 and OPTIC1 defined in .bashrc. It specifies the optic: ETMX, ITMY, etc EPICS_Base_Name is specified in the Table below.
13
LIGO
LIGO-T1000155-v15
EPICS Base Name
Type Description
DEVICE_NUMBER
stringin
The device channel number of the camera
STATUS_MESSAGE
stringin
The state HWS is executing currently
EVENT_MESSAGE
stringin
Display error messages, pause/resume status, instructions to a user etc.
TERMINATE
bi
Terminate HWS when 1
RESTART
bi
Restart HWS when 1
PAUSE
bi
PAUSE HWS when 1
NO_REF_IMAGES_TO_AVERAGE
ai
The number of images to average for REFerence centroids
REFRESH_PROBE_REFERENCE
bi
Refresh probe reference centroids when 1. Default value is 0.
NO_LIVE_IMAGES_TO_AVERAGE
ai
The number of images to average for LIVE centroids.
NO_IMAGES_FOR_LSQ_WEIGHTS
ai
The number of images to use for calculation of weights to be used in the least-squares fit. Default value is 10.
USE_LSQ_WEIGHTS
bi
Use calculated weight factors in least-squares fit when 1. Default value is 1.
RESET_AVERAGING
bi
Reset (initialize) live centroids array when 1. Default value is 0.
LEVER_ARM
ai
The lever arm length of the Hartmann sensor [meters]
MAGNIFICATION
ai
Measured magnification of optical system. Ratio of test mass conjugate plane size to HWS image plane size. Default value is 17.5
SPOT_RADIUS
ai
Radius of each spot in pixel units to be used when centroiding. Actually this is half the width of a square, not the radius of a circle.
CENTROID_WEIGHT_FACTOR
ai
The factor used to weight pixel counts of an image before centroiding
BACKGROUND_PV
ai
Background PV to be subtracted from all frames prior to centroiding. Default value is 50.
DEFOCUS_TEMPERATURE_COEFFICIENT
ai
GET_TEMPLATE_CENTROIDS
bi
Run get_template_centroids when 1
CHECK_BEAM_CENTERING
bi
Run check_beam_centering when 1
CHECK_CONJUGATE
bi
Run check_conjugate when 1
MODULATION_NO_OF_CYCLES
ai
Number of modulation cycles used to estimate modulation amplitudes and period when checking probe beam alignment.
CAMERA_ACCESSIBLE
bi
1 means camera accessible; 0 means camera is inaccessible. Triggers a major alarm if equal to 0.
14
LIGO
TOP100_PV
LIGO-T1000155-v15
ai
CAMERA_MODEL_NUMBER
stringin
CAMERA_SERIAL_NUMBER
stringin
SENSOR_SERIAL_NUMBER
stringin
TAP_1_GAIN
stringin
TAP_2_GAIN
stringin
FIRMWARE_DESIGN_REV
stringin
DSP_DESIGN_REV
stringin
PRETRIGGER
stringin
VIDEO_MODE
stringin
DATA_MODE
stringin
BINNING_MODE
stringin
GAIN_MODE
stringin
OUTPUT_CONFIG
stringin
EXPOSURE_CONTROL
stringin
EXPOSURE_MODE
stringin
SYNC_FREQUENCY
stringin
EXPOSURE_TIME
stringin
The mean value of the brightest 100 pixels [counts]. Triggers a minor alarm if value is too small or large.
SENSOR_TEMPERATURE
ai
DIGITIZER_TEMPERATURE
ai
ITMM_CENTER_X_PERIOD
ai
Estimated period of ITM modulation in x direction
ITMM_CENTER_Y_PERIOD
ai
Estimated period of ITM modulation in y direction
ITMM_CENTER_X_AMPLITUDE
ai
Estimated amplitude of ITM modulation in x direction (in pixel units)
ITMM_CENTER_Y_AMPLITUDE
ai
Estimated amplitude of ITM modulation in y direction (in pixel units)
ITMM_PRISM_X_PERIOD
ai
Estimated period of ITM modulation for prism x
ITMM_PRISM_Y_PERIOD
ai
Estimated period of ITM modulation for prism y
ITMM_PRISM_X_AMPLITUDE
ai
Estimated amplitude of ITM modulation for prism x
ITMM_PRISM_Y_AMPLITUDE
ai
Estimated amplitude of ITM modulation for prism y
ITMM_CENTER_X
ai
Estimated X coordinate of the beam center (in pixel units)
ITMM_CENTER_Y
ai
Estimated Y coordinate of the beam center (in pixel units)
ITMM_WIDTH_X
ai
Estimated X width of the beam (in pixel units)
ITMM_WIDTH_Y
ai
Estimated Y width of the beam (in pixel units)
ITMM_BACKGROUND
ai
wk: What should this be?
15
LIGO
LIGO-T1000155-v15
LIVE_ACQUISITION_GPSTIME
ai
REFERENCE_ACQUISITION_GPSTIME
ai
FRAME_RATE
WITM
stringin
POLY_FIT_ORDER
ai
Maximum order of polynomials to use for least-squares fit. Can be 2 , 3, 4, 5 or 6; Default value is 6.
UNITIZATION_LENGTH
ai
Length
u used to make polynomials in least-squares-fit
dimensionless. Default value is 0.05m. PROBE_POLY_Ai_COEFF (i=01,…,27)
ai
Coefficients of polynomials in Eqn (1) in Section 10. Dimensions of the coefficients are varied.
PROBE_PRISM
ai
[radians – referenced to Test Mass (TM) conj. plane]
PROBE_ALPHA
ai
orientation of prism
PROBE_PRISM_X
ai
[radians – referenced to TM conj. plane]
PROBE_PRISM_Y
ai
[radians – referenced to TM conj. plane]
PROBE_PHI
ai
orientation of cylinder
PROBE_CYLINDRICAL_POWER
ai
[m-1 – referenced to TM conj. plane]
PROBE_SPHERICAL_POWER
ai
[m-1 – referenced to TM conj. plane]
PROBE_ZERNIKE_Zi_COEFF (1=1,…,5)
ai
Coefficients of Zernike-like functions in Eqn (3) in Section 10. Dimensions of the coefficients are varied.
PROBE_GRADIENTS_SSR
ai
Sum of squared residuals of gradients compared to polynomial fit.
PROBE_TOTAL_PIXEL_VALUE
ai
PROBE_NO_OF_CENTROIDS
ai
The number of centroids in an image
Data types: • • •
ai: analogue bi: binary (Boolean) stringin: ASCII character string
16
LIGO
LIGO-T1000155-v15
8 States of Operation Nomenclature The symbol # is used to refer to an instance method; e.g., Foo#bar is the instance method bar of an instance of the class Foo. The symbol ## is similarly used to refer to an instance property. [units] indicates the units of a particular variable
8.0 State 0: Code ready to run The computer is ready for the HWS code to run at this point. There is no EPICS process running.
8.1 State 1: Preparation Script: run_initialize_State1_initial_EPICS_parameters.m The Run_EPICS script is used to set-up the EPICS channels using the environment variables defined in .bashrc If EPICS process is not running then it launches EPICS process and loads default values. If EPICS process is already running then it uses the values already present in the channels.
8.2 State 2: Initialization This State is illustrated in Figure 4. The sub-states are: 8.2.1
State 2A: Check serial communication Script: run_initialize_State2A.m Verifies that serial communication with the camera can be achieved. Classes used explicitly by HWS: HS_Camera, HS_EPICS Operation 1. Create an instance of HS_Camera. 2. Call HS_Camera#on_or_off. 3. If the connection is made, export camera parameters to EPICs channels. 4. If no response is received with a certain time, try another 3 times. Condition for Success: Receipt of a designated response from the camera to the gcp (SDK) command. On Failure: Set value of EPICS channel CAMERA_ACCESSIBLE to false (0), which will trigger an alarm and force HWS to exit.
17
LIGO
8.2.2
LIGO-T1000155-v15
State 2B: Verify image frame acquisition Script: run_initialize_State2B.m Verifies that image frames can be acquired from the camera via the frame grabber. Classes used explicitly by HWS: HS_Camera, HS_EPICS Operation 1. Call HS_Camera#read_images. This method acquires an image frame via the frame grabber and saves it as a .raw file in a designated folder. 2. Call HS_Camera#check_image_size to check that the image has the right dimension (1024 by 1024). Condition for Success: Successful acquisition of an image frame from the camera. On Failure: Set value of EPICS channel CAMERA_ACCESSIBLE to false (0), which will trigger an alarm and force HWS to exit.
8.2.3
State 2C: Determine optimum exposure time Script: run_initialize_State2C_check_camera_exposure.m Determine the exposure time that ensures the brightest pixels are within the range defined by HS_Camera##upper_th and HS_Camera##lower_th. Classes used explicitly by HWS: HS_EPICS, HS_Camera Operation 1. Set initial exposure time = 100 ms. 2. Record 10 image frames and average. Calculate mean of 100 brightest pixels in average frame. 3. Compare this mean pixel value with specified limits. If too large, reduce exposure time and go to step 1. If too small then increase exposure time and go to step 1. 4. Write optimum exposure time to EPICS. Condition for Success: Optimum exposure time > 16 ms and < 1 s. On Failure: Broadcast message: “Adjust exposure failed. Exiting HWS”, via EVENT_MESSAGE channel and exit.
8.2.4
State 2D: load background level Script: run_initialize_State2D_get_background_value.m
18
LIGO
LIGO-T1000155-v15
Loads a default value of 50 counts to the background value Classes used explicitly by HWS: HS_EPICS, HS_Camera On Failure: Not applicable.
8.2.5
State 2E: Acquire template centroids Script: run_initialize_State2E_get_template_centroids.m Determine the locations that will be used to seed the calculation of the reference centroids [pixels]. This process can also run during State 3. Classes used explicitly by HWS: HS_EPICS, HS_Camera, HS_Image, HS_Centroids Operation 1. Call get_template_centroids script. This script will record and average a number of images, and find centroids from the averaged image. 2. Display template centroids overlaid on spot pattern. 3. PAUSE HWS Condition for Success: User approves template centroids. On Failure: User selects EXIT or RESUME after resolving issue.
8.2.6
State 2F: Load default magnifications (not shown in Figures). Script: run_initialize_State2F_set_default_magnification.m Checks the optic name. Sets the default magnification in the EPICS channel to 17.5x for an ITM and 20.5x for an ETM. Classes used explicitly by HWS: HS_EPICS Operation 1. Try to search the optic name from the environment variable for the substrings ‘ITM’ or ‘ETM’. If found, change the magnification appropriately. On Failure: If no string name is found, or the EPICS call fails, the try loop prevents the code from crashing and the magnification is unchanged.
8.3 State 3: Acquisition This State is illustrated in Figure 5. During this state the HWS continuously acquires and analyses Hartmann images.
19
LIGO
8.3.1
LIGO-T1000155-v15
State 3A: Acquire REFerence centroids Script: run_initialize_State3A_get_reference_centroids_check.m Determine the coordinates of the reference centroids [pixels]. It will be bypassed if reference centroids have been generated already and an update is not requested. Classes used explicitly by HWS: HS_EPICS, HS_Centroids, HS_Image, HS_Camera Operation 1.
Call HS_EPICS method to determine value of record_ref_centroids flag.
2.
Acquire and average images, as specified by no_ref_images_to_average .
3.
Export mean of 100 brightest pixels in average frame pixel to EPICS channel TOP100_PV.
4.
Determine the coordinates of the average REFerence centroids [pixels].
5.
Acquire CCD sensor temperature at which REFerence centroids were recorded, and export the value to its EPICS channel.
On Failure: If camera communication fails then set value of EPICS channel CAMERA_ACCESSIBLE to false (0), which will trigger an alarm and force HWS to exit. If TOP100_PV is too large or too small, as determined by parameters within EPICS definition, then an alarm will be triggered, but HWS will continue to run.
8.3.2
State 3B: Acquire LIVE centroids Script: run_initialize_State3B_get_current_centroids.m Determine the coordinates of the LIVE centroids [pixels]. Classes used explicitly by HWS: HS_EPICS, HS_Centroids, HS_Image, HS_Camera Operation 1.
Record an image, calculate centroids.
2.
Record UTC immediately after last image. Convert to GPS time and broadcast via EPICS.
3.
Calculate running average and standard deviation (LSQ weight factors) of centroids.
On Failure: If camera communication fails then set value of EPICS channel CAMERA_ACCESSIBLE to false (0), which will trigger an alarm and force HWS to exit. If TOP100_PV is too large or too small, as determined by parameters within EPICS definition, then an alarm will be triggered, but HWS will continue to run. 20
LIGO
8.3.3
LIGO-T1000155-v15
State 3C: Calculate gradient field Script: run_initialize_State3C_get_current_gradients.m Calculate gradients using the REFerence and the LIVE centroids (the running average from State 3B). Magnification Note: the gradient field is referenced to the TM surface by the measured magnification. The magnification (for this purpose) is the scale of the TM conjugate plane divided by the scale of the HWS plane (it should be ~17.5×) Classes used explicitly by HWS: HS_EPICS, HS_Centroids, HS_Gradients Operation 1.
Calculate gradient field (dW/dxi [radians], dW/dyi [radians], xi [meters], yi [meters]) using LIVE-REFerence
2.
Export gradient field to PROBE_GRADIENTS_xx waveform channels in EPICS.
On Failure: If spot displacement > 0.5 pixel then warning is displayed on terminal.
8.3.4
State 3D: Calculate wavefront aberration Script: run_initialize_State3D_calculate_wavefronts.m Characterize wavefront aberration using least-squares fit to gradient field using gradient field from State 3C and LSQ weight factors from State 3B (if requested), and by numerical integration of gradient field to produce wavefront aberration map. Classes used explicitly by HWS: HS_EPICS, HS_Gradients, HS_WF, HS_WFP Operation 1.
Perform least-squares-fit of polynomials to gradient field. User can select maximum polynomial order (2, 3, 4, 5, 6) and whether to use LSQ weight factors or not.
2.
Calculate coefficients of Seidel functions and of Zernike-like functions, as per Section 10.
3.
Numerically integrate gradient field to produce wavefront aberration (variable name: wf_numerical). The wavefront map is Wij [meters].
On Failure: No failure modes yet.
8.3.5
State 3G: Export data to frames Script: run_initialize_State3G_export_to_file.m
21
LIGO
LIGO-T1000155-v15
Writes the gradient and wavefront data to frame files, per Section 11. Classes used explicitly by HWS: none Operation -
Collect the gradient and wavefront data into a MATLAB LHD structure (defined explicitly in E1300023. Export the data to a frame file using the precompiled MEX function LHD_WRITE_STRUCT_TO_FRAME
On Failure: No failure modes yet.
8.4 State 4: Operator Intervention This describes the state of the HWS when it is paused by an operator. The relevant EPICS channel suffixes are listed below: TERMINATE
bi
Terminate HWS when 1
RESTART
bi
Restart HWS when 1
PAUSE
bi
PAUSE HWS when 1
22
LIGO
LIGO-T1000155-v15
8.5 State 5: Interrupts or Alarms This state is entered when the code fails in either a controlled or uncontrolled fashion or when EPICS alarms are triggered but the code does not fail. The list of controlled processes that enter this stage is below. Table 2: Description of the controlled interrupt/alarm mechanisms Interrupt code
Script
v1.0.2
101
Run_EPICS.m, Line 556
211
run_initialize_State2A.m, Line 11
212
run_initialize_State2A.m, Line 13
221
run_initialize_State2B.m, Line 20
231
run_initialize_State2C_ check_camera_exposure.m, Line 31
251
run_initialize_State2E_ get_template_centroids.m, Line 15
252
run_initialize_State2E_ get_template_centroids.m, Line 57
301
run_acquire_pull_EPICS_variables.m, Line 36.
302
run_acquire_pull_EPICS_variables.m, Line 93.
303
Run_acquire.m, Line 11
1001
TOP100_PV EPICS channel
Description Failure to save EPICS db to file. Result: error message generated. Code terminates with command line error message. No EPICS signal. Check the camera connection 3 times. Result: error message generated. Code terminates with command line error message. No EPICS signal. Get camera parameters. Result on failure to communicate: error message generated. Code terminates with command lines error message. No EPICS signal. Checks the image size. Result on failure: generates a MATLAB‘error’. Code terminates with command line error message. No EPICS signal Adjusts the exposure. Result on failure: - EPICS channel updated with message ‘Adjust exposure failed. Exiting HWS ….’ - HWS code exits Template centroid file requested and doesn’t exist or isn’t valid. Result on failure: generates a MATLAB‘error’. Code terminates with command line error message. No EPICS signal If user has requested HWS to terminate after template centroids generated Result: - ‘Exiting HWS …’ message added to EPICS channel - exits HWS code Load a camera instance from disk. Result on no file: Prompts user in EPICS channel to Resume initialization or Terminate Load a centroid template from disk. Result on no file: Prompts user in EPICS channel to Resume initialization or Terminate Each time the loop reaches the top, the EPICS terminate channel is checked for any requests to terminate the HWS code. Result on TERMINATE: - ‘HWS terminated’ output to EPICS channel - HWS code ends - EPICS ALARM triggers if this falls below 30% of saturation = 1230 counts
23
LIGO
LIGO-T1000155-v15
1002
CAMERA_ACCESSIBLE channel
EPICS
- HWS keeps running if this ALARM is triggered - EPICS ALARM triggers if the camera is not accessible. - Exits HWS code if the camera is not accessible.
24
LIGO
LIGO-T1000155-v15
9 Description of HWS Classes Class Name
Description
HS_Base
HS_Base is a parent class, which other classes should inherit to be able to use HS_Messenger to send messages to an instance of HS_Report.
HS_CamConfig
HS_CamConfig is a placeholder for camera parameter values that can be accessed by "gcp" camera serial command. For each of the entry in the gcp output there is a property.
HS_Camera
HS_Camera should be a single communication point between the Hartmann Sensor equipment (camera and frame grabber) and the rest of the code. It holds properties and methods relevant to the system initialization and diagnostics, as well as image acquisition from the frame grabber. Need to consider whether one of its properties should be an instance of HS_Image. If so, HS_Image and HS_Camera should be revised.
HS_Image
HS_Image is a class used to store and interact with images from Hartmann Sensor camera.
HS_Centroids
HS_Centroids is a class used to generate and interact with centroids of Hartmann Sensor images.
HS_Gradients
Calculates 2D array of displacement of one set of centroids from another, then converts it into gradient array referenced to the ITM.
HS_WFP
A class used for least-squares-fitting of polynomials to the gradient field. User can choose maximum power of the polynomials used for the fit; default is 6th power. This class also calculates the amplitudes of the lowest order Seidel and Zernike functions, derived from the amplitudes of the polynomials.
HS_WF
A class used for least-squares fitting of 3rd order Seidel functions to gradient field. It produces 8 parameters: prism, the angle of the prism, spherical power, cylindrical power and the angle of the cylindrical power, coma, angle of coma, and spherical aberration. Note that this is not equivalent to fitting up to 3rd power polynomials. This class also does numerical integration of the wavefront.
HS_WF3
3-parameter version of its parent class HS_WF. When used to construct Seidel wavefront aberration, it only deals with prism, the angle of the prism, and spherical power. HS_WF3 has the same set of properties as HS_WF.
25
LIGO
HS_WF5
LIGO-T1000155-v15
5-parameter version of its parent class HS_WF. When used to construct Seidel wavefront aberration, it only deals with prism, the angle of the prism, spherical power, cylindrical power and the angle of the cylindrical power. HS_WF5 has the same set of properties as HS_WF.
HS_EPICS
HS_EPICS is a class used to open and interact with EPICS channels. An instance of HS_EPICS is to be associated to one channel
HS_EventData
When sending notifying messages to an instance of HS_Report class, any extra parameters (e.g., an message to be exported, a class of the instance that is reporting a message) should be packaged as an instance of HS_EventData class.
HS_Messenger
HS_Messenger is a class solely responsible for notifying listener instances of any events that trigger during an execution of Hartmann Sensor Matlab application.
HS_Report
Not fully implemented yet. HS_Report class is responsible for sending messages to an EPICS channel. An instance of HS_Report accepts a message from an instance of HS_Messenger by the event-listener system, then calls its callback method to send the received messaged to an EPICS channel.
Additional Code Run_EPICS.m
Code that oversees running of State 1. It sets up EPICS channels and either launches a new EPICS process or connects to an existing EPICS process.
Run_initialize.m
Code that oversees running of State 2
Run_acquire.m
Code that oversees running of State 3
Run_hws.m
The script that sequentially runs the State 1, 2 and 3 scripts.
26
LIGO
LIGO-T1000155-v15
10 Appendix: Least-squares fitting to the gradient field A wavefront distortion W can be described by a sum of dimensionless linearly-independent functions Ψ i ( x, y ) : m
WTM = ∑ ξi Ψ i ( x, y ) . i=0
where x =
xTM y and y = TM , u u
u is a scale length that best conditions the least-squares matrix, and ξ i have units of length. HS_WFP uses the polynomial functions: Ψ0 = 1 Ψ1 = x Ψ 2 = y
Ψ 3 = x2
Ψ 4 = xy Ψ 5 = y 2
Ψ 6 = x 3 Ψ 7 = x 2 y Ψ 8 = xy 2
Ψ9 = y3
Ψ10 = x 4
Ψ11 = x 3 y Ψ12 = x 2 y 2
Ψ13 = xy 3 Ψ14 = y 4
Ψ15 = x 5
Ψ16 = x 4 y Ψ17 = x 3 y 2
Ψ18 = x 2 y 3 Ψ19 = xy 4
Ψ 21 = x 6
Ψ 22 = x 5 y Ψ 23 = x 4 y 2
Ψ 24 = x 3 y 3 Ψ 25 = x 2 y 4
Ψ 20 = y 5 Ψ 26 = xy 5
Ψ 27 = y 6 .
The x and y components of the local gradient of the wavefront are given by
gx =
∂WTM ∂Ψ i ξ ∂Ψ i = ∑ ξi =∑ i = ∑ α i Xi and ∂xTM ∂x ∂x TM i i u i
gy =
∂WTM ∂Ψ i ξ ∂Ψ i = ∑ ξi =∑ i = ∑ α iYi , ∂yTM ∂yTM ∂y i i u i
where α i =
∂Ψ i ∂Ψ i ξi , Xi = and Yi = . ∂y ∂x u
27
LIGO
LIGO-T1000155-v15
The coefficients α i are determined using a modified chi-square (least-square) fitting, where χ 2 is defined:
(
⎧⎡ g − α X xj, yj n ⎪ xj ∑ i i ⎪⎢ 2 i χ = ∑ ⎨⎢ σxj j=1 ⎪ ⎢ ⎪⎩ ⎣
) ⎤⎥
where n is the number of Hartmann spots, and g x measured x
(
2
⎡ gy − ∑ α iYi x j , y j ⎢ j i + ⎥ ⎢ σ yj ⎥ ⎢ ⎦ ⎣
j
) ⎤⎥
2⎫
⎪⎪ ⎥ ⎬ ⎥ ⎪ ⎦ ⎪⎭
( g ) and σ (σ ) are the average yj
xj
yj
( y ) component of the local gradient and its standard deviation at spot
j.
Solving ∂χ 2 ∂α i = 0 yields equations that can be written conveniently as a matrix equation: Mα = b T T where M = X X + Y Y
(
)
⎡ X x ,y 0 1 1 ⎢ σx ⎢ 1 ⎢ X =⎢ ... ⎢ X x ,y ⎢ 0 n n ⎢ σx n ⎣
(
(
)
⎡ Y x ,y ⎢ 0 1 1 σy ⎢ 1 ⎢ Y=⎢ ... ⎢ Y x ,y ⎢ 0 n n ⎢ σy n ⎣
(
⎡ α0 ⎢ α = ⎢ ... ⎢ αm ⎣
...
(
X m x1, y1 σx
1
)
... ...
...
Xm
... xn , yn
(
σx
(
Ym x1, y1 σy
... ...
Ym
(
)
... xn , yn
σy
n
)
n
1
)
)
)
⎤ ⎥ ⎥ ⎥ ⎥ ⎥ ⎥ ⎥ ⎦
⎤ ⎥ ⎥ ⎥ ⎥ ⎥ ⎥ ⎥ ⎦
⎤ ⎥ ⎥ ⎥ ⎦
b = X T bx + Y T by
28
LIGO
LIGO-T1000155-v15
⎡ ⎢ ⎢ ⎢ bx = ⎢ ⎢ ⎢ ⎢ ⎢⎣
⎤ ⎡ g ⎥ ⎢ y1 σx ⎥ ⎢ σy 1 1 ⎥ ⎢ ... ⎥ and by = ⎢ ... ⎢ g gx ⎥ ⎥ n ⎢ yn ⎢ σ σx ⎥ n ⎥⎦ ⎢⎣ yn gx
1
⎤ ⎥ ⎥ ⎥ ⎥. ⎥ ⎥ ⎥ ⎥⎦
The wavefront distortion can also be written in terms of coordinates at the TM: 27
27
(
WTM = ∑ uα i Ψ i ( x, y ) = ∑ ai Ψ i xTM , yTM i=1
i=1
)
(1)
where
ai = α i for i = 1,2 ai = α i u for i = 3, 4,5 ai = α i 2u for i = 6,…,9 ai = α i 3u for i = 10,…,14 ai = α i 4u
ai = α i 5u
for i = 15,…,20
.
for i = 21,…,27
Example 2 3 + 3xTM Assume WTM = xTM + 2xTM . Thus, g x =
∂WTM 2 . Assuming u = 2 , = 1+ 4xTM + 9xTM ∂xTM
xTM
WTM
gx
x = xTM u
0
0
1
0
2
34
45
1
4
228
161
2
Fitting g x = α1 + α 3 2x + α 6 3x 2 → α1 = 1 α 3 = 4 α 6 = 12 and hence a1 = 1 a3 = 2 a6 = 3 . Thus, WTM =
∑
i=1,3,6
(
)
2 3 as required. ai Ψ i xTM , yTM = xTM + 2xTM + 3xTM
29
LIGO
LIGO-T1000155-v15
Coefficients of Seidel functions The wavefront distortion is also described in terms of (leading order) Seidel functions:
(
)
2 2 WTM = P ( xTM cosα + yTM sinα ) + 0.5S xTM + yTM + 0.5C ( xTM sinφ − yTM cosφ )
(
)
2 2 = Px xTM + Py yTM + 0.5S xTM + yTM + 0.5C ( xTM sinφ − yTM cosφ )
⎛ −a4 ⎞ where Px = a1 , Py = a2 , φ = 0.5 × arctan ⎜ ⎟, C=2 ⎝ a5 − a3 ⎠
2
(2)
2
(a5 − a3 )2 + a42 , S = a3 + a5 − 0.5C .
The magnitude of the prism is given by P = a12 + a22 . Coefficients of Zernike-like functions The wavefront distortion is also described in terms of Zernike-like functions: 5
WTM = ∑ zi Zi ( xTM , yTM )
(3)
i=1
where Z1 = rTM cosθTM = xTM , Z2 = rTM sinθTM = yTM
(
)
2 2 2 2 2 2 Z3 = −1+ 2rTM = −1+ 2 xTM + yTM , Z4 = rTM cos 2θ = xTM − yTM 2 Z5 = rTM sin 2θ = 2xTM yTM .
and
z1 = a1 , z2 = a2 , z3 =
( a3 + a5 ) 4
, z4 =
( a3 − a5 ) , z 2
5
=
a4 . 2
Note that these functions are not “Zernike circle polynomials” as they are not functions of a dimensionless position parameter. Aside (note that the least-squares fit described below is not implemented) One could describe the wavefront distortion in terms of Zernike circle polynomials, as shown below, but it would not provide any information additional to that provided by the polynomial parameterization. For example, to use Zernike polynomials up to degree 3, define 9
WTM = ∑ ζi Zi ( x, y )
(4)
i=0
where Z0 = 1 Z1 = ρcosθ = x Z2 = ρsinθ = y ,
(
Z 3 = −1+ 2ρ2 = −1+ 2 x 2 + y 2
)
Z 4 = ρ2 cos 2θ = x 2 − y 2
Z 5 = ρ2 sin 2θ = 2xy ,
30
LIGO
LIGO-T1000155-v15
(
)
(
Z 6 = ρ −2 + 3ρ2 cosθ = −2x + 3x x 2 + y 2 Z 8 = ρ3 cos 3θ = x 3 − 3xy 2
x=
)
(
)
(
)
Z 7 = ρ −2 + 3ρ2 sinθ = −2y + 3y x 2 + y 2 ,
Z 9 = ρ3 sin 3θ = 3x 2 y − y 3 ,
xTM y and y = TM u u ,
u is a scale length, and ζi have units of length. Expanding (4) and collecting terms gives
WTM = ξ 0 + ξ1x + ξ 2 y + ξ 3x 2 + ξ 4 xy + ξ5 y 2 + ξ 6 x 3 + ξ 7 x 2 y + ξ8 xy 2 + ξ 9 y 3 where ξ 0 = ζ0 − ζ3 ξ1 = ζ1 − 2ζ6
ξ 2 = ζ2 − 2ζ7
ξ 3 = 2ζ3 + ζ4
ξ 4 = 2ζ5 ξ5 = 2ζ3 − ζ4
ξ 6 = 3ζ6 + ζ8
ξ 7 = 3ζ7 + 3ζ9
Thus, gx =
gy =
ξ8 = 3ζ6 − 3ζ8
ξ 9 = 3ζ7 − ζ9 .
∂WTM ∂Ψ i ξ ∂Ψ i = ∑ ξi =∑ i = ∑ α i Xi and ∂xTM ∂xTM ∂x i i u i ∂WTM ∂Ψ i ξ ∂Ψ i = ∑ ξi =∑ i = ∑ α iYi . ∂yTM ∂y ∂y TM u i i i
where Ψ i are as defined above. Proceeding as above yields values for α i , from which ⎡ ( 3α 6 + α 8 ) ⎤ , ζ = ⎡α + (α 7 + 3α 9 ) ⎤ , ζ1 = u ⎢α1 + ⎥ 2 ⎥ u⎢ 2 6 6 ⎣ ⎦ ⎣ ⎦
ζ3 = u
(α 3 + α 5 ) , ζ
ζ6 = u
( 3α 6 + α 8 ) , ζ
4
12
4
= u 7
(α 3 − α 5 ) , ζ
= u
2
5
= u
(α 7 + 3α 9 ) , ζ 12
8
α4 , 2
= u
(α 6 − α 8 ) , ζ 4
9
= u
(α 7 − α 9 ) 4
,
For Zernike polynomials up to degree 4, a different set of equations would be required, as Zernike polynomials incorporate mixed powers to provide orthogonality over the unit circle.
31
LIGO
LIGO-T1000155-v15
11 Appendix: Writing gradient fields and phase maps to frames The image/x-lhd MIME type definition (E1300023) defines the LHD_STRUCT data structure, consisting of Hartmann gradient field and phase map data, which is saved to LIGO frames. Additionally, the gps time that Hartmann sensor images are captured is recorded in this data structure as well. Frames are saved to a remote disk mounted on the HWS machine. It’s location is specified in the Linux environment variable $HWS_FRAME_FOLDER. The definition calls out a series of MATLAB interface functions that allow the user to import or export x-lhd data structure. The addition or extract of data from that structure within MATLAB is accomplished using the standard MATLAB structure access syntax. The table below lists the functions (created from a compiled MEX binary) that can be accessed from MATLAB to control input and output of LHD_STRUCT data structures from LIGO frames. Table 3: A list of x-lhd MATLAB functions Function name
Purpose
LHD_WRITE_STRUCT
Write an LHD structure to a ‘.lhd’ file
LHD_WRITE_STRUCT_TO_FRAME
Write an LHD structure to a ‘.gwf’ LIGO frame file
LHD_READ_STRUCT
Read an LHD structure from a ‘.lhd’ file
LHD_READ_STRUCT_FROM_FRAME
Read an LHD structure from a ‘.gwf’ LIGO frame file
32
LIGO
LIGO-T1000155-v15
12 Appendix: Defunct States 12.1.1 State 2D: Acquire dark image – earlier version Records ‘dark’ images, and calculates the average dark image and average dark pixel value. Classes used explicitly by HWS: HS_EPICS, HS_Camera Operation 1. Call HS_EPICS method to request blocking of probe beam by flipper mirror. The script pauses and waits until EPICS channel indicates flipper has been activated. 2. Read 100 image frames, average them, and assign the averaged image to HS_Camera##dark_image. 3. Call HS_Camera#calculate_background to calculate mean dark pixel value. Condition for Success: Recording and averaging 100 images. On Failure: Not applicable.
12.1.2 State 2F: Check Probe-Beam-Centering – not implemented currently Determine the location of the center and width of the probe beam as determined by the envelope of the centroids. User must adjust beam-steering mirrors to achieve centration. Classes used explicitly by HWS: HS_EPICS, HS_Camera, HS_Image, HS_Centroids Operation 1. Call HS_EPICS method to determine value of check_beam_centering. 2. If check_beam_centering is FALSE then go to State 2G; otherwise continue. 3. Call check_beam_centering script, which runs continuously while check_beam_centering flag is TRUE. i. Record and sum 20 frames. ii. Determine positions and amplitudes of centroids. iii. Calculate location of probe beam center. iv. Write location and width of beam center to EPICS channel. v. If beam center is within 50 pixels of CCD-center then broadcast message via EPICS: “beam is centered”. Otherwise broadcast: “beam not centered”. Condition for Success: Probe beam centered on CCD within 50 pixels. On Failure: Warning broadcast via EPICS
33
LIGO
LIGO-T1000155-v15
12.1.3 State 2G: Check Hartmann Plate and ITM are conjugate – not currently implemented
12.1.4 State 2H: Re-determine optimum exposure time and dark image This sub-state occurs only if sub-states 2F and 2G have been executed. Classes used explicitly by HWS: HS_EPICS, HS_Camera Operation 1. Run substate 2C 2. Run substate 2D Condition for Success: as per state 2C and 2D On failure: as per state 2C and 2D 12.1.5 State 3E: Parameterize aberration Parameterize aberration using least-squares fit of derivatives of Seidel functions to the gradient field. Classes used explicitly by HWS: HS_EPICS, HS_Gradients, HS_WF Operation 1.
Determine the amplitudes of Seidel functions that describe the wavefront aberration by doing least-square fit of derivatives of Seidel functions to the measured gradient field. User can choose a 3, 5 or 8-parameter fit.
2.
Export Seidel amplitudes to EPICS waveform channels
On Failure: No failure modes yet.
12.1.6 State 3F: Update camera parameters Update camera parameters and export to EPICS if more than 60 minutes since last update. Pause if requested. Classes used explicitly by HWS: HS_EPICS, HS_Camera Operation 1. Retrieve camera parameters. 2. Broadcast parameters to EPICS channels. On Failure: If camera communication fails then set value of EPICS channel CAMERA_ACCESSIBLE to false (0), which will trigger an alarm and force HWS to exit.
34
LIGO
LIGO-T1000155-v15
35
LIGO
LIGO-T1000155-v15
13 Summary of units and exported variables The following section summarizes all variables that and explain the units used for them (variables and flags that are used for maintenance or flow control in the code are not included).
13.1 centroids -
centroids: these are measured in pixel indices [pixels]. o The centroids property of HS_Centroids is a 2 column array of length N that is a list of the x- and y- centroids of each of the HWS spots.
13.2 magnification -
magnification: this is the scale of the TM conjugate plane divided by the scale of the HWS plane (it should be ~17.5×)
13.3 gradients -
gradients: this is a property of HS_Gradients. o It is a 4 column array of length N where each row is the x-gradient of the wavefront [radians], the y-gradient of the wavefront [radians], the x-coordinate of the gradient measurement [meters], the y-coordinate of the wavefront measurement [meters]. These four physical quantities are referenced to the TM surface.
13.4 wf_numerical -
wf_numerical: this is a 100×100 array of values of the wavefront aberration (in meters) constructed from the numerically integrated gradient field. o The arrays xf and yf contain the x- and y-coordinates of each point (in meters referenced to the TM) in wf_numerical.
13.5 Polynomial coefficients of distortion (as per equation (1) in Section 10) -
PROBE_POLY_Ai_COEFF PROBE_POLY_Ai_COEFF PROBE_POLY_Ai_COEFF PROBE_POLY_Ai_COEFF PROBE_POLY_Ai_COEFF PROBE_POLY_Ai_COEFF PROBE_POLY_Ai_COEFF
where i = 01 : x-component of prism (YAW) [radians] where i = 02 : y-component of prism (PITCH) [radians] where i = 03, 04, 05 : [m-1] where i = 06, 07, 08, 09 : [m-2] where i = 10, 11, 12, 13, 14 : [m-3] where i = 15, 26, 17, 18, 19, 20 : [m-4] where i = 21, 22, 23, 24, 25, 26, 27 : [m-5]
13.6 Seidel coefficients of distortion (as per equation (2) in Section 10) -
PROBE_PRISM_X: x-component of prism referenced to the TM [radians] PROBE_PRISM_Y: y-component of prism referenced to the TM [radians] PROBE_CYLINDRICAL_POWER: astigmatic component of wavefront referenced to the TM [m-1] PROBE_SPHERICAL_POWER: spherical power component of wavefront referenced to the TM [m-1]
36
LIGO
LIGO-T1000155-v15
13.7 Zernike-like coefficients of distortion (as per equation (3) in Section 10) -
PROBE_ZERNIKE_Zi_COEFF where i = 01 : x-component of prism [radians] PROBE_ZERNIKE_Zi_COEFF where i = 02 : y-component of prism [radians] PROBE_ZERNIKE_Zi_COEFF where i = 03, 04, 05 : [m-1]
37
