Difference between revisions of "SHOC"

Revision as of 22:46, 27 March 2015

SHOC User Manual

NOTE: THIS PAGE REFERS TO THE LINUX- and WEB-BASED SOFTWARE (AS OF MARCH, 2015). For the original, manufacturer-based software and instrument commissioning details, please refer to the manual at http://shoc.saao.ac.za/Documents/ShocnHelpful.pdf.

Introduction

The SHOC systems consist of a filterwheel unit (with one or two filterwheels), a GPS unit for providing accurate timing triggers, an Andor iXon camera, and a control PC. Currently there are 2 full SHOC systems (shocnawe & shocndisbelief), and 1 development system running a different camera (shocnhorror). As of March 2015, the control software is web-based. Users point their browser to the instrument location, and separate tabs appear to allow control of the camera, GPS, and filter wheel. SHOC can be mounted on the 1.9- and 1-m telescopes, so please confirm which SHOC system is mounted on your telescope so that you know where to point the browser! Details on instrument operation are below.

The SHOC website may well have more extensive detail about this instrument.

Dr. Marissa Kotze has written some pipeline software which may help with reduction of SHOC data.

Quick Start

• (1) Connect to the web browser. Go to http://shoc40in.suth.saao.ac.za:5000 or http://shoc74in.suth.saao.ac.za:5000 depending on which telescope you are using.
• (2) Initialize the filter wheel and select your filter. You must initialize both filter wheels whenever the webservice is started.
• (3) Click on camera tab: turn on the camera and confirm that it is cooling.
• (4) If using the GPS to trigger data frames, click on GPS tab: check that the GPS has valid time and can be set.
• (5) Click on camera tab: set parameters on the camera and start previewing and taking data.
• (6) Transfer data from the instrument to your local machine or the SAN.
• (7) Turn OFF the camera before you leave!!

Filter wheel

• (1) Point your browser at shoc40in.suth.saao.ac.za:5000 or shoc74in.suth.saao.ac.za:5000

NOTE: ON DNS ALIASES: These telescope web addresses are aliases to the SHOC instruments. The real addresses for the instruments are shocnawe.suth.saao.ac.za:5000 or shocndisbelief.suth.saao.ac.za:5000. In order to avoid confusion, or the requirement that the user know which instrument is mounted on their telescope, we have created the aliases.

• (2)Select the filterwheel tab
• Initialize the filterwheel(s) (3), then select the filter required (4), click "Move" (5). The "Centered" indicator should be green when the wheel is finished moving (6).

GPS

• If using external triggering, select the GPS tab (1)
• Ensure timing is valid (2).
• Set the Programmed Output Pulse (POP) parameters (mode (3), pulse width (4), start date (5), start time (6), trigger interval (7)) and click apply (8). The status should change to pending (9).

Camera

• Select the camera tab (1).
• Turn the camera on (2)

• Set the desired Readout Rate (1), Preamp (2) and Electron Multiplying (3) parameters (NB: EM MODE MAY ONLY BE SET IF YOU HAVE WRITTEN PERMISSION TO DO SO).
• Set the sub image (4) and binning (5) parameters.
• Set the trigger type (6), exposure (7) and kinetic series (8) parameters.
• Start the acquisition (9).

Acquiring data

• Stop to abort (1), or wait until completion. The image display area (based on DS9) (2) shows snapshots of the images throughout the acquisition.
• When the series is complete, the FITS data cube is copied to /data/<telescope>/<INSTR>/<YYYY>/<MMDD>/<filename>.fits, where:
  

<telescope> is 40in or 74in,

<INSTR> could be SHD for shocndisbelief, SHA for shocnawe or SHH for shocnhorror,

<YYYY> is the year,

<MMDD> is the month and day, (Note that YYYY/MMDD is that of the start of the night and is increased at NOON the following day.)

<filename> is the instrument abbreviation (SHA or SHD) followed by the date in YYYYMMDD format and the number of the acquisition.

• An example is /data/74in/SHA/2015/0325/SHA_20150325.0001.fits
• Make sure to turn off the camera when you are done for the night.

Data Transfer

• To transfer data directly to your computer from the SHOC instrument, use the command line. Copy the data using the following command, depending on the telescope:

  rsync -avzP shoc74in@shoc74in.suth.saao.ac.za:/data/74in/SH?/<YYYY>/<MMDD>/*.fits /LocalFilePath  
  rsync -avzP shoc40in@shoc40in.suth.saao.ac.za:/data/40in/SH?/<YYYY>/<MMDD>/*.fits /LocalFilePath

NOTE: Data are moved to the SAN on the plateau every morning at 9:30am. However, if you're wanting to get your data to the SAN (and from there to the servers in Cape Town sooner than 9:30am) you MUST have run the shocdatacopy.sh script in order to get the data to the SAN. You can then obtain the data from astro.suth.saao.ac.za (or astro.cape.saao.ac.za if you're back in Cape Town). See Data Transfer information under the advanced guide below for details on how to transfer to the SAN.

Advanced users guide

Web interface

• The primary means of controlling SHOC is via a web interface. The Firefox or Chrome browsers are preferred.
• Point your browser at http://shoc74in.suth.saao.ac.za:5000 or http://shoc40in.suth.saao.ac.za:5000
• The interface should appear, showing three tabs: Filterwheel, GPS and Camera.

Filter wheel

• Select the filterwheel tab. There may be one or two wheels physically present; the interfaces to these are displayed side-by-side. The interface values for a wheel will be empty if the wheel is absent.
• Initialize the wheel by clicking the "Initialize" button (usually only at the start of the night, but may also be done if you suspect that the controller has lost its way). The wheel will move around to the reference position; this may take several seconds. While still moving, the "Moving" indicator above the controls will be red. Once there, the "Initialized" and "At Ref" indicators should turn green. The value in the "Current Position" field should be 1 after initialization. YOU MUST INITIALIZE BOTH FILTER WHEELS AT THE START OF THE NIGHT, AND MOVE ONE TO AN "EMPTY" POSITION TO ENSURE THAT THE CORRECT FILTER IS IN THE BEAM.
• Select the filter required, by using the up and down arrows on the right of the "Required Position" field. The filter name will indicate the filter in the selected position. Click the "Move" button. The indicators above the wheel controls should change; once the wheel has reached the required position, the "Moving" indicator should turn grey, while the "Centred" indicator should be green. The "Current Position" field will indicate the slot number and name of the filter now in the light path.

GPS (optional: to be used for accurately-timed images)

• The GPS tab allows the user to view the time, GPS state, and to change the Programmed Output Pulse (POP) settings.
• Check that the time is valid, and that there are no alarm conditions indicated.
• To set the Programmed Output Pulse, choose whether you want a single or repeating pulse, then choose a pulse width, the start date and time (in local time, 24 hour format), and for repeating pulses, the repeat interval. Then push the "Apply" button. Note: the POP may only be set to occur in the future; if an error occurs, check that you haven't chosen a time in the past.
• To stop the pulses from being sent, click the "Stop" button.

Camera

• The camera tab allows control and setting of the SHOC imaging camera.
• Before using the camera, you need to switch it on: click the "Turn Camera On" button.
• Once the camera has been initialized, the camera setting and view interface is displayed.
• On the left is the image display area; more on that later.
• On the right is the settings area, with three tabs for camera control, analysis and advanced settings.
• When switched on, the camera starts cooling to its target temperature. The temperature display button is orange while the camera is not yet at the target temperature, and green once it is. If using a non-standard temperature, this may be set using the "Advanced" tab.
• The camera may be used in internal, external or external start modes, selectable using the "Triggering" drop-down.
• While in internal or external start trigger modes, the exposure time may be set, and the kinetic cycle time is automatically calculated and displayed. The latter is the period between the start of successive frames in a kinetic series. Arbitrarily short exposre and kinetic cycle times are not possible, due to the time required to read out the image. If you choose an exposure time less than the minimum allowed, the minimum exposure and kinetic cycle times are calculated and automatically displayed.
• In external trigger mode, the kinetic cycle time is determined by the frequency of the GPS POP signals. However, this frequency should not be higher than than the minimum readout time. The minimum allowed kinetic cycle time is calculated and displayed; this may be useful when deciding on the GPS POP frequency to use.
• For all trigger modes, the number of frames in the data cube is determined by the Kinetic Series value.
• The next row down allows the sub-image area and binning to be chosen. For both of these, standard or custom values may be used. Smaller sub-images and higher binning allow faster image readouts, at the expense of image size and resolution. The minimum values discussed above are automatically re-calculated and displayed when the sub-image or binning is changed. NOTE: BINNING DIMENSIONS SHOULD BE EQUALLY DIVISIBLE INTO THE AREA OF THE SUB-IMAGE WHEN USING CUSTOM VALUES. An error message will appear, and will need to be cleared, when the values are not evenly divisible.
  • You can visually draw a custom sub-image in the display area by clicking the white square to the right of the sub-image options. This will display a red region which can be manipulated to select the desired sub-image. Click the square again to hide the region in the display area. NOTE: YOU WILL NEED TO CAPTURE A FRAME BEFORE YOU CAN SELECT A SUB-FRAME USING THIS METHOD.
• Below this, the readout speed and preamp gain may be set. Higher readout speeds allow for shorter exposure times, but at the expense of noisier data.
• The last setting is the Electron Multiplying (EM) gain. NOTE: DO NOT USE ELECTRON MULTIPLYING MODE UNLESS YOU HAVE SPECIFICALLY OBTAINED PERMISSION FROM DR AMANDA GULBIS TO DO SO, AND YOU UNDERSTAND HOW AND WHEN TO USE IT. PERMANENT DAMAGE TO THE SENSOR CAN RESULT FROM INCORRECT USAGE. If you are using EM mode, choose the EM output amplifier, and then select a gain. BEGIN WITH LOW GAIN VALUES, BECAUSE IF THERE IS TOO MUCH SIGNAL YOU CAN DAMAGE THE CAMERA.
• To get a quick view of the images that will result, press the "Preview" button. Images will be displayed in the left-hand display panel. Press "Stop" when you're done.
• To begin collecting data, press the "Start" button. The kinetic series will start, either immediately or at the designated time if using the GPS, and the data will be spooled to disk. At the same time, temporary images will be displayed in the image display area.
• Once the acquisition is finished (or earlier, if you push the "Stop" button), the header information in the FITS cube will be updated to include various GPS, filter and environmental parameters, an the cube written to disk. The filename for the current or past kinetic series is displayed above the "Start" button. The filename consists of the instrument name, the date and an index. The index is updated every acquisition. and the new filename is calculated and displayed immediately after the "Start" button is pressed.
• The index appended to file names begins at 1, and increments by 1 after each acquisition. It may be edited by clicking on the "Advanced" tab, and changing its value. Note that if you change it to a value already used, it will cause files with that value to be overwritten.

* Once you're finished with the camera, remember to turn it off! It should not be left with the cooler on once the night's observations are finished.

Real-time image display

• As an acquisition proceeds, snapshot images are displayed in the display area of the camera tab, basically as fast as the browser can render them.
• The interface is based on JS9, a Javascript version of the DS9 FITS processing and display engine (so users familiar with DS9 should be able to adapt to the JS9 interface relatively easily).
• Menu items above the image allow users to change the image zoom level, scaling and colour. It is also possible to select regions of the graph for further analysis.

Data Transfer

There are two ways to transfer data: (1) directly to your computer or (2) onto the SAAO storage area network (SAN). The data are automatically copied to the server every morning (at 9:30am).

• (1) To transfer data directly to your computer, use the command line.
  • Open a shell on your local PC (Putty if you're using Windows or a bash/tcsh/sh if on Mac or Linux)
  • Copy the data using the following command, depending on the telescope:

       rsync -avzP shoc74in@shoc74in.suth.saao.ac.za:/data/74in/SH?/<YYYY>/<MMDD>/*.fits /LocalFilePath
       rsync -avzP shoc40in@shoc40in.suth.saao.ac.za:/data/40in/SH?/<YYYY>/<MMDD>/*.fits  /LocalFilePath
         ---- where SH? is a wildcard that will point to the correct instrument mounted on the telescope for that night and "/LocalFilePath" is the location on your local machine
         ---- the password is that for the shoc74in or shoc40in accounts

• (2) To move data to the SAN on the Sutherland plateau (from which you can access it by connecting to the SAAO server), there is a data copy script on the SHOC computer.
  • From a command line, connect to the instrument computer. As appropriate for your telescope, use either of the following commands:

       ssh shoc74in@shoc74in.suth.saao.ac.za  
       ssh shoc40in@shoc74in.suth.saao.ac.za
            ---- When prompted for the password, use the password for the 74in or 40in user.

• • Run the shocdatacopy.sh script. Options can be:

       shocdatacopy.sh -d yesterday # to transfer yesterday's data
       shocdatacopy.sh -d YYYYMMDD # to transfer data from some specified date
             ---- Without parameters, it will try to transfer today's data.

• • To collect your data from the SAN, you'll have to secure copy it from astro.suth.saao.ac.za. The usernames for this are ccd40 and ccd74 depending on your telescope. Ask for the password. Data are in the path /data/telescopedata/<TELESCOPE>/SH?/<YYYY>/<MMDD>

       rsync -avzP ccd74@ astro.suth.saao.ac.za:/data/telescopedata/74in/SH?/<YYYY>/<MMDD>/*.fits /LocalFilePath
       rsync -avzP ccd40@ astro.suth.saao.ac.za:/data/telescopedata/40in/SH?/<YYYY>/<MMDD>/*.fits /LocalFilePath
         ---- where SH? is a wildcard that will point to the correct instrument mounted on the telescope for that night; YYYY is the year; MMDD is the month and day;  and "/LocalFilePath" is the location on your local machine

• Useful:
  • On the SHOC computers, the 'tree' command will assist you in trying to look at what folders and files are under that directory.
  • For information on the script, a logfile is produced that will be in /var/log/<TELESCOPE>DataCopyLog<MMDD>-<NUM> where <TELESCOPE> is 40in or 74in <MMDD> MonthDay <NUM> the Nth time this script has been run

Recuing Data

Under normal operation, the system automatically updates the FITS cube header with supplementary information (filter, external trigger parameters, telescope pointing information etc.) and the moves the cube to the permanent (for the night) storage area. From time to time, it may be neccessary to do this manually, using the rescue_data tool. In particular, if the system has frozen at the end of an acquisition, but before fixing the header and moving the datra file, it will be neccessary to perform this procedure.

• Open a terminal. Find your data in the spool directory. It's stored in a directory named /data/spool/<CCYYMMDD><index>.<HHMMSS> (where index is the index, CCYYMMDD is the date and HHMMSS is the time the acquisition started). For example, /data/spool/201503250002.141026/ . Go to this directory:

       ssh shoc74in@shoc74in.suth.saao.ac.za
            ---- or  
       ssh shoc40in@shoc74in.suth.saao.ac.za
            ---- When prompted for the password, use the password for the 74in or 40in user.ssh shoc74in@shoc74in.suth.saao.ac.za
       cd /data/spool
       ls -l
       cd <CCYYMMDD><index>.<HHMMSS>
       ls -l

• There should be files named data.fits and info.txt
• The info.txt file contains the supplementary information.
• Change to this directory.
• Run the rescue utility: type rescue_data.py and then answer the questions as prompted.
• The telescope is the name of the telescope being used; either 40in or 74in.
• The instrument will be one of shocnawe (SHA) or shocndisbelief (SHD). These are used to create the directory and filename in the /data directory. The directory will be of the form /data/<telescope>/<instrument>/<YYYY>/<MMDD>, and the file of the form <instrument>_<YYYYMMDD>.<index>.fits. From this, the instrument name can be determined.
• You will be prompted for an index to use. NB: make sure there is no existing file with the same index that will be overwritten (one option is to use an index like 3a , if index 3 exists).

In-depth Information

Characteristics and Properties

The specification sheets for the cameras, other manuals and documentation, can be found at http://shoc.saao.ac.za/Documentation.html .

Choosing an Observing Method

• BINNING: The plate scale is 0.076 and 0.163 "/pixel for the 1.9m without and with the focal reducer. It is 0.167"/pixel for the 1.0m without the focal reducer. The optimal binning is ~ 3 pixels per full width half maximum. The seeing conditions in Sutherland are typically > 1"; therefore, SHOC should usually be binned at least 2x2.

For example, if the seeing is 2" and SHOC is mounted on the 1.9m telescope without the focal reducer, sources would be well sampled at a binning of 6x6.

• SUBFRAMING: The SHOC field of view is not large (1.3' and 2.8' on each side on the 1.9m without and with a focal reducer; 2.9' on each side on the 1.0m with a focal reducer). Subframing is typically only used if the cadence needs to be increased.
• MODE: For most observations, the mode should be selected that allows the desired cadence with the lowest read noise. Start by setting 1 MHz Conventional mode in the optimal binning, and type 0 in the exposure time -- the time will default to the minimum allowable (and the cadence will be displayed). If the cadence is too slow, either subframe or select 3 MHz Conventional mode. The EM mode should only be used in cases of experienced observers who understand both the risks and the noise vs. signal payoffs.
• GAIN: The three gain settings correspond to different electron/ADU conversion values and effect dynamic range. They are slightly different from camera to camera. The standard options for conventional modes are as follows:

Mode...................... Approx. Gain setting................... Approx. Electrons/ADU

1 MHz Conv....................1, 2.5, 5....................................... 4, 1.5, 0.7

3 MHz Conv...................1, 2.5, 5....................................... 10, 4, 1.8

User's troubleshooting guide

• Acquisition doesn't start: Check on the GPS tab that the trigger signal has been activated. If it has, but the camera is still not taking images, try stopping, resetting the GPS trigger to a time in the near future, and try again. Sometimes, it appears that the GPS trigger signal is not being sent (despite the software reporting that it is). The current acquisition should be stopped and restarted (because when the acquisition is started, the time the POP signal will start is recorded and will apear in the fits headers - so stopping and starting the acquisition will ensure that the correct POP time is used). Note that the index willl be incremented when doing this. To avoid this, you can rewind the increment by 1, in the advanced tab. Make sure you have no data that will be overwritten.
• Acquisition doesn't finish: Sometimes it appears that the camera does not ever leave the acquiring state (despite all images in the kinetic series having been obtained). It may in this case be neccessary to restart the server, manually edit the FITS files to include the filter and timing informations, and to then copy them to their final destination. The server may be restarted running the command "restart_services" from a terminal. The data is spooled to a directory under /data/spool/, based on the date, the sequence number and the time the acquisition started. In this directory is the data file, data.fits, and file containing other acquisition parameters, info.txt. The latter may be used to update the FITS header. The procedure is as follows:
  • Open a terminal and ssh to the instrument, running the command ssh shoc74in@shoc74in.suth.saao.ac.za. When prompted for the password, use the password for the 74in user.
  • Rescue your data using the data rescue utility, as described in the section Rescuing Data.
  • Run the command to restart the webserver: restart_services . This will take a few seconds to complete. The web server should be accessible again.
  • Return to the web browser, refresh the page, turn the camera back on, and continue with your observing. If the camera is non-responsive, run the restart_services command again.
  • IMPORTANT:
    • Check that the file number is correct --- look at the Advanced Tab, and the Start Index should be that for the next file. Currently, for the Phase 1 software, this number seems to be the same as the file you just saved from spool and you will likely need to increase it by one to avoid overwriting.
    • The filter wheel needs to be reinitialized. Go to the filter wheel tab, click the initialize button under the active wheel(s).

Technician's guide

Mounting SHOC

• The SHOC box should be mounted at the base of the telescope, and the camera should be mounted below the filter wheel box.

• With the power OFF, connect the following cables:
  • computer to camera operation (thick, white cable)
  • computer to camera trigger (thin back with gold SMB)
  • camera power (black)
  • GPS antenna (BNC from telescope into the GPS in the SHOC box)
  • network cable (ethernet from back of SHOC box)
  • SHOC box power (standard three-prong cable from back of the box)
  • the filter wheel to the computer

The power must be off when disconnecting and reconnecting cables.

• To power up:
  • (1) Turn on power to the outlet where the SHOC box cable is plugged
  • (2) Turn on power switch at the back of the SHOC box.
  • (3) Press the computer power button on the front of the computer.

Testing the components

• Once the machine has booted, fire up a browser and point it at http://shocnawe.suth.saao.ac.za:5000/ or http://shocndisbelief.suth.saao.ac.za:5000/.
• In the filterwheel tab:
  • Check that the filterwheel(s) can be initialized and moved by selecting the initialize button, then selecting a different filter(s) and moving the wheel(s).
• In the GPS tab:
  • Check that the time is valid (it will read "valid" in green). (Note: the time will NOT be valid if the GPS antenna cannot see the sky. The dome must be open for the GPS to see satellites.)
  • Check that POP settings can be made:
    • Set mode to repeat.
    • Pulse width should 10 microseconds (default)
    • Start date should be set or selected to be today's date.
    • Start time should be set to some seconds or a min in the future, localtime.
    • Repeat interval can be your choice: this is just a test value, something like a few hundred millisec is appropriate.
    • Click the apply button .
    • The status should change to pending, and at the chosen time, should change to activated. Make sure to switch off the POP signal again by clicking stop.
    • Make sure to close the dome before trying the camera tests, or else the images could be saturated.
• In the camera tab:
  • Check that the camera can be switched on (press "turn camera on")
  • Check that the cooler is working (the temperature should drop)
  • Check that the camera is reading out: confirm the setting is full frame, conventional mode (the default) and press "preview". Images should appear every ~ 1.2 sec. Once confirmed that images are coming through, press "stop".
  • Switch the camera off again (press "turn camera off").

Configuring the SHOC computer (not the web interface!)

To access the SHOC computer, ssh into it from a terminal on your local machine or tablet (e.g. ssh ccd@shocnawe.suth.saao.ac.za or ssh ccd@shocndisbelief.suth.saao.ac.za).

• Ensure GPS location settings are correct in /home/ccd/programming/shoc/shoc/instruments/gps/gps.py:
  • after sshing, move into the directory: cd /home/ccd/programming/shoc/shoc/instruments/gps/
  • open the file using a viewer: vi gps.py
  • Use the up and down arrows to view each line of the file. Check that the location settings for Sutherland are active (not commented with a '#') and that the settings for Cape Town are commented (i.e. are preceded by a '#'). To remove a character type x . To add a character type a followed by the character to add, then hit esc to stop inserting. To exit, type :wq .
• Edit service settings using the file /etc/init/shoc-camera.conf (the filepaths need to have the correct telescope and instrument names):
  • after sshing, move into the directory: cd /etc/init/
  • open the file using a viewer: vi shoc-camera.conf
    • Use the up and down arrows to view each line of the file. Change the telescope name to the name of the currently used telescope: 74in or 40in. The instrument name should already be set to SHA or SHD (for shocnawe or shocndisbelief) and the log level should be info (not debug). In the editor, to remove a character type x . To add a character type a followed by the character to add, then hit esc to stop inserting. To exit, type :wq .
• To enact any changes made during configuration, restart all services:
  • Under /home/ccd/programming/shoc, type the following: ./restart_services

Technician's Troubleshooting guide

• SHOC computers have two disks, a solid state drive to which data are spooled and a hard drive which runs the system. If there are concerns about the disks, you can verify mount points:

At the command line, type the command 'mount'. The solid state disk should be mounted on /data/spool, while the spinning hard disk should be mounted on /data.

• Time is not valid:
  • Check that the antenna cable has been connected to the SHOC GPS on the box.
  • Check that the antenna has access to the sky (i.e. the dome is open)
  • Check that the location settings are correct. Click on 'receiver status' in the GPS tab and look at the latitude and longitude. The Sutherland Latitude is ~32 22 S while Cape Town is 33 56S. If the location is not corrrect, then the GPS will not find satellites and the correct location needs to be updated as described in the Configuring SHOC section.
• Camera is in an inoperable state:
  • Restart the services by sshing into the SHOC computer (see Configuring SHOC section):
    • change into directory /home/ccd/programming/shoc and type the following: ./restart_services. It may be neccessary to do this a few times.
    • If that does not work, under /home/ccd/programming/shoc type the following to stop and start in separate steps:

./stop_services

./start_services

• • If prompted for the password, it is the same as that for the ccd user.
• Worst case scenario, when restarting the entire computer seems like an appropriate option:
  • ssh into the SHOC computer (see Configuring SHOC section)
  • type the following: sudo shutdown -h now
  • The computer will shutdown. To power back on, someone must MANUALLY go press the button on the front of the SHOC computer.

* If, for whatever reason, you decide to open the SHOC computer case, you MUST USE ELECTROSTATIC PROTECTION. The computer components, especially the PCI card, are electrostatically sensitive. The computer should be placed on a grounding mat and a grounding wriststrap should be used before anything is touched.