ocd.run_shot – Run a HETDEX shot

Module to run a shot.

This module emits the following events:

Topic	Event
ocd.run_shot.run	exec_status (EXEC_STATUS): whether it is the start or the end of the run
	error (bool): if True and error occurred when running the shot
	exc_type (string): type of the exception
	exc_value (string): representation of the exception
	traceback (string): full error traceback
	the content of the shot_dict as passed to run()
ocd.run_shot.setup_telescope	exec_status (EXEC_STATUS): whether it is the start or the end of the telescope setup
	the content of the shot_dict as passed to run()
ocd.run_shot.exp_hetdex	exec_status (EXEC_STATUS): whether it is the start or the end of a HETDEX exposure
	exposure (int): exposure number
	seconds (float): exposure time
	observation (int): observation number, same as obs_number
	object, shotid (str): id of the shot
	recipe (str): script name and version
	x_binning, y_binning (int): binning of the output fits files
	type (str): type of observation
	recipe (str): script name and version
	the content of the shot_dict as passed to run()

ocd.run_shot.track_mapping = {0: 'EAST', 1: 'WEST'}

Map 0/1 to EAST/WEST

ocd.run_shot.track_mapping_initial = {0: 'E', 1: 'W'}

Map the keys of track_mapping to the first letter of the values

ocd.run_shot.inverse_track_mapping = {'EAST': 0, 'WEST': 1}

Invert key <-> value of track_mapping

ocd.run_shot.RUN_TOPIC = 'ocd.run_shot.run'

Topic of the events emitted by run()

ocd.run_shot.SETUP_TOPIC = 'ocd.run_shot.setup_telescope'

Topic of the events emitted by setup_telescope()

ocd.run_shot.EXP_TOPIC = 'ocd.run_shot.exp_hetdex'

Topic of the events emitted by do_exposure()

ocd.run_shot.ALL_TOPICS = ['ocd.run_shot.run', 'ocd.run_shot.setup_telescope', 'ocd.run_shot.exp_hetdex']

List of all the topics emitted in this module

ocd.run_shot.EXEC_STATUS = ExecStatus(START=0, FINISH=1)

Enumerator that tracks the execution status of each of the tasks that emit events

ocd.run_shot.shot_dict_keys = ['shotid', 'obs_number', 'ra', 'dec', 'azimuth', 'track', 'exp01', 'exp02', 'exp03']

List of the mandatory keys of the shot_dict used as input in run()

ocd.run_shot.run(conf, shot_dict)

Retrieve the information precomputed by shuffle, build the commands to setup the instrument and do the exposure.

Send out an event when starting and when finishing. Any error is captured and logged.

Some of the file and directory names can be build dynamically using format syntax. The following fields are used: {shotid}, {ra}, {dec}, {track_name}, {track_number}, {track_initial}.

Parameters:

conf : configparser.ConfigParser

configuration

shot_dict : dictionary

dictionary with the relevant information needed to run the next shot:

• shotid (string): id of the shot
• obs_number (int): observation number in the night (used for the name of the directory where the files are saved)
• ra, dec (float): ra and dec of the shot
• track (int): 0: East, 1: West
• azimuth (float): azimuth at which to execute the shot
• exp01, exp02, exp03 (floats): exposure times for the three exposures
• sleep_for (float), optional: sleep for sleep_for seconds between sending the starting event and beginning to setup the telescope
• metadata (dict), optional: set of metadata to send to TCS

ocd.run_shot._run(conf, shot_dict)

Actual implementation of run().

Parameters:

conf : configparser.ConfigParser

configuration

shot_dict : dictionary

dictionary with the relevant information needed to run the next shot

ocd.run_shot.retrieve_shuffle_info(fname)

Search and load the configuration file created by shuffle.

Parameters:

fname: string

name of the configuration file

Returns:

conf : configparser.ConfigParser

loaded configuration file from shuffle

Raises:

IOError

if the configuration file does not exist

configparser.ParsingError

Exception raised when errors occur attempting to parse a file

ocd.run_shot.validate_shuffle_conf(conf, shuffle_conf, shot_dict)

Make sure that the configuration is correct.

Compare the expected ra, dec, azimuth and track with the corresponding entries in the [trajectory] section.

Parameters:

conf : configparser.ConfigParser

application configuration file (for now not used, future proofed)

shuffle_conf : configparser.ConfigParser

configuration file from shuffle

shot_dict : dictionary

dictionary with the relevant information needed to run the next shot. Same as run()

Raises:

ocd.errors.ShuffleConfigError

if the ra, dec and track from shuffle do not agree with the ones from OCD

ocd.run_shot.copy_acam(conf, shuffle_conf, format_map)

Copy the acam image from the shuffle directory to to a target file.

Parameters:

conf : configparser.ConfigParser

application configuration file

shuffle_conf : configparser.ConfigParser

configuration file from shuffle

format_map : dict

dictionary used to format the file names from the configuration files

Returns:

acam_dest

destination file name

ocd.run_shot.setup_telescope(conf, shuffle_conf, shot_dict)

Set up the telescope and wait for the TO/RA to confirm that the setup is complete.

Parameters:

conf : pyhetdex.tools.configuration.ConfigParser

application configuration file

shuffle_conf : configparser.ConfigParser

configuration file from shuffle

shot_dict : dictionary

dictionary with the relevant information needed to run the next shot. Same as run()

ocd.run_shot._cancel_trajectory()

Try to cancel an existing trajectory. If the command fails because no active trajectory is found, send a warning log. Any other failure is re-raised.

ocd.run_shot._load_tracjectory(shuffle_conf, shot_dict)

Load the trajectory

Parameters:

shuffle_conf : configparser.ConfigParser

configuration file from shuffle

shot_dict : dictionary

dictionary with the relevant information needed to run the next shot. Same as run()

ocd.run_shot._set_probe_position(conf, shuffle_conf, shot_dict, probe_name, section_name)

Execute the commands necessary to setup the probes ra and dec

Parameters:

conf : pyhetdex.tools.configuration.ConfigParser

application configuration file

shuffle_conf : configparser.ConfigParser

configuration file from shuffle

shot_dict : dictionary

dictionary with the relevant information needed to run the next shot. Same as run()

probe_name, section_name : string

name of the probe and of the section of the shuffle_conf containing the information from the probe

ocd.run_shot._set_probe_object(conf, shuffle_conf, shot_dict, probe_name, section_name)

Execute the commands necessary to setup the probes object id and magnitudes

Parameters:

conf : pyhetdex.tools.configuration.ConfigParser

application configuration file

shuffle_conf : configparser.ConfigParser

configuration file from shuffle

shot_dict : dictionary

dictionary with the relevant information needed to run the next shot. Same as run()

probe_name, section_name : string

name of the probe and of the section of the shuffle_conf containing the information from the probe

ocd.run_shot._set_probes_fiductial(conf, shuffle_conf, shot_dict)

Setup the analysis region and the fiducial position and initialize the WFS exposure times.

Parameters:

conf : pyhetdex.tools.configuration.ConfigParser

application configuration file

shuffle_conf : configparser.ConfigParser

configuration file from shuffle

shot_dict : dictionary

dictionary with the relevant information needed to run the next shot. Same as run()

ocd.run_shot._set_metadata(conf, shot_dict)

Set the metadata stored in shot_dict['metadata']. If the key is not present, skip the step.

Parameters:

conf : pyhetdex.tools.configuration.ConfigParser

application configuration file

shot_dict : dictionary

dictionary with the relevant information needed to run the next shot. Same as run()

ocd.run_shot.message_expstart(conf, exptime, inst='VIRUS')

Trigger the exposure time clock

The name of the binary to execute and the options come from the message_board option of the [run_shot] configuration section.

Parameters:

conf : pyhetdex.tools.configuration.ConfigParser

application configuration file

exptime : float

Exposure time to display

inst : string (optional)

Instrument name to send to the message boad command

ocd.run_shot.play_sound(conf, file_option)

Play a sound.

The name of the binary to execute the sounds and the options come from the play_exe option of the [run_shot] configuration section.

Parameters:

conf : pyhetdex.tools.configuration.ConfigParser

application configuration file

file_option : string

name of the configuration option of the [run_shot] section containing the name of the file to play

ocd.run_shot._wait_for_setup(conf, shot_dict)

Wait for the confirmation that the setup is done. If the wait_for_setup_timeout option of the [run_shot] configuration section is positive, add a timeout to the waiting. If the continue_on_timeout option of the [run_shot] configuration section is false, abort the shot if the timeout is hit; if it is true run the shot even if the timeout is hit. Any other exception is re-raised.

Parameters:

conf : pyhetdex.tools.configuration.ConfigParser

application configuration file

shot_dict : dictionary

dictionary with the relevant information needed to run the next shot. Same as run()

ocd.run_shot.reset_probes(conf)

Before yielding stop the ACAM and set the storage of guider images. On return from yield, deactivate the probe images storage and deploy the ACAM mirror.

Parameters:

conf : configparser.ConfigParser

configuration

ocd.run_shot.run_hetdex(conf, shot_dict)

Run a hetdex shot

Parameters:

conf : configparser.ConfigParser

configuration

shot_dict : dictionary

dictionary with the relevant information needed to run the next shot. Same as run()

ocd.run_shot.retract_mirrors()

Retract the ACAM and CWFS mirrors

ocd.run_shot.ensure_first_dither()

Make sure that the dither position is set to 1 at the beginning and at the end, no matter what

ocd.run_shot.get_dithers(conf)

Get the dither positions and dither shifts

Parameters:

conf : configparser.ConfigParser

configuration. Uses the dither_with_probes option of the [general] section

Returns:

dither_pos : list

dither positions, either [1, 2, 3] or [1, 1, 1]

delta_shifts : ndarray

shifts to apply to the fiducial position of the guide probes. If the dither positions are different, a list of three None is returned, otherwise the following:

[[x_shift_1, y_shift_1],
 [x_shift_2, y_shift_2],
 [x_shift_3, y_shift_3]]

Examples

>>> import configparser
>>> conf = configparser.ConfigParser()
>>> conf.read_dict({'run_shot': {'dither_with_probes': 'false'}})
>>> get_dithers(conf)
([1, 2, 3], [None, None, None])
>>> conf['run_shot']['dither_with_probes'] = 'true'
>>> dithers, delta_shifts = get_dithers(conf)
>>> dithers
[1, 1, 1]
>>> delta_shifts
array([[ 1.27, -0.73],
       [ 0.  ,  1.46],
       [-1.27, -0.73]])

ocd.run_shot.do_exposure(conf, shot_dict, expose_kwargs, dither_pos, guider_shift, tot_exposures)

Run a single exposure

Parameters:

conf : configparser.ConfigParser

configuration

shot_dict : dictionary

dictionary with the relevant information needed to run the next shot. Same as run()

expose_kwargs : dictionary

keyword arguments for the virus.expose call

dither_pos : int

dither position

guider_shift : None or list of two elements

if not None, shift the fiducial position of the guide probes by dx = guider_shift[1] and dy = guider_shift[0]

tot_exposures : int

total number of exposures

ocd.run_shot.check_fiter_map(conf)

Make sure that the shuffle and the pas filters from the configuration file have the same number of names

Parameters:

conf : pyhetdex.tools.configuration.ConfigParser

configuration entries

Raises:

OCDValueError

if there is missmatch between the two lists

ocd.run_shot.run_shot_parser(subparsers)

Add a subcommand “run_shot” to run a hetdex shot.

Parameters:

subparsers : argparse subparsers object

subparser to use to generate new parsers

Returns:

parser : argparse.ArgumentParser

modified parser

ocd.run_shot._run_shot_cmd(args)

Entry point for running a shot from the command line

Parameters:

args : Namespace

parsed command line arguments

ocd.run_shot.setup_for_events(subcommand, config, wait_for_connection, timeout=10)

Initialise the zmq servers and, if necessary wait for the connection to be established.

Parameters:

subcommand : string

name of the subcommand

config : pyhetdex.tools.configuration.ConfigParser

configuration entries

wait_for_connection : bool

whether it has to wait for the connection to be established

timeout : int, option

if wait_for_connection is True wait at most timeout seconds before aborting

Raises:

ocd.errors.TimeOutError

if the timeout is hit

ocd.run_shot.run_shot_subprocess(conf, shot_dict)

Run the shot in a subprocess.

Parameters:

conf : configparser.ConfigParser

configuration. Passed to ocd.shots_db.create_shot_file(), run_autoschedule()

shot_dict : dictionary

dictionary of options; see run() for more info

Returns:

p : subprocess.Popen

process running the shot

cmd : string

command executed