The SpecMan Class

This application provides management functionality for the DESI spectrographs.

• It discovers the requested (in the .ini) file spectrograph processes and provides a fan-out for commands from the OCS or the Console/GUIs.
• It sets up the Spectrograph Interlock
• It synchronizes expose and illuminate calls and informs the OCS if readout and spectrograph level image building is complete.
• All calls to the spectrographs

exposure calls to spectrographs:

prepare_for_exposure expose digitize use multiops and when necessary separate execute and wait (passing a ctrl dictionary gives access to assignments)

exposure calls to IB

trigger IB

ToDo: clean up local IB stuff (build etc)

class SpecMan.SpecMan.SpecMan(device_mode=False, noSVE=None, **extra_args)

A class to manage DESI spectrograph applications.

commands = ['configure', 'get', 'set', 'spectrographs', 'stop', 'clear_image', 'prepare_for_exposure', 'expose', 'digitize', 'build', 'trigger_ib', 'register_callback', 'clear_callback', 'start_loop', 'stop_loop']

PML accessible commands

defaults = {'alarm_email': False, 'alarm_logbook': False, 'associated_ib': None, 'auto_build': True, 'auto_trigger': False, 'ccd_idle': True, 'ccd_prep': [], 'compress': False, 'constants_version': 'DEFAULT', 'device_mode': False, 'digitizer_timeout': 50.0, 'exclude': ['assignment', 'ib_processing', 'status', 'processing_times'], 'exposure_ready_mode': 'memory', 'extras': {}, 'file_purge': False, 'file_purge_threshold': 2, 'frame_purge_threshold': 4, 'image_dir': '${DOS_IMAGEDIR}', 'image_name': 'desi', 'instrument': 'DESI', 'local_copy': False, 'mem_purge': True, 'mem_purge_threshold': 4, 'plot_mark_center': False, 'plot_save': False, 'plot_save_ext': 'ALL', 'plot_save_mode': 'EXTENSIONS', 'plot_show': False, 'plot_show_ext': 'CCDS0Z', 'plot_show_mode': 'SPECTROGRAPH', 'plot_subtitle': False, 'plot_title': False, 'png_dir': '${DOS_IMAGEDIR}', 'primary': None, 'program': 'DESI', 'send_to': None, 'spectrograph_rolename': 'SP', 'spectrographs': 'auto', 'updater': None, 'use_built_callback': False, 'use_digitized_callback': False, 'use_exposed_callback': False, 'use_header': True, 'use_ib_callback': False, 'use_sv': False, 'wait_for_build': True, 'wait_for_digitize': True, 'wait_for_expose': True}

Default configuration paramters

init()

The init function for the SpecMan application. It waits until all requested spectrographs have been found or a timeout occurs.

Raises:Exception – Initialization failed. Returns str:SUCCESS

clear_image(expid=None, frame=None, extension=None)

Clear the exposures dictionary and thereby release the image memory buffers Arguments: expid: exposure number or all (careful!) if specific exposure is given: frame: frame number or all if also a specific frame is given: extension: extename or all

configure(constants='DEFAULT')

Restores the system to a known state. This includes the constants specified, and uses the default set if none are specified.

Keyword Arguments:  constants (str,optional) – The set of constants to use. Raises:RuntimeError – Failed to configure correctly. Returns str:SUCCESS/FAILED with error message.

register_callback(operation, interface=None, function=None, cb_args=None, enable=None)

register a PML interface (server) and function to be called at the end of accummulation or digitization. Only one callback can be registered per function (exposed, digitized, built, ib) meaning that earlier values will be overwritten by subsequent calls. The named arguments dictionary (kwargs) must include values for the interface and function to be called. When given, the value of cb_args is passed to the callback function. operation has to be either expose or digitize Supports both PML callbacks and Pyro URIs. If interface is None and function is callable, a local function call is executed (instead of a PML command)

clear_callback(callback)

clear the callback variables

set(**options)

Set key/value pairs to set parameters dynamically. Options include: local_copy, auto_build, updater, use_header, extras, send_to use_exposed_callback, use_digitized_callback, use_built_callback, use_ib_callback, use_exp_dir, use_obs_day exposure_ready_mode, primary, image_name, image_dir, png_dir, interlock

set interlock=<name> enable=True/False Enables/disables interlocks set interlock=<name> condition=<group>_<name> enable=True/False enables/disables a condition The condition is give as a string <group>_<name> (all uppercase)

mem_purge, file_purge, mem_purge_threshold, file_purge_threshold, frame_purge_threshold

stop(what, reason=None)

stop an ongoing operation (eg. expose) what has to be in expose, digitize, build reason, a string, is included in the log message(s)

prepare_for_exposure(expid, frame=None, spec_options={}, **options)

Prepare spectrograph for an exposure :keyword expid: exposure number :type expid: int Optional arguments (in options dictionary) :keyword spectrographs: selects which controllers to prepare (all, r[ed], b[lue], z[nir], spectcon or a list of these) :type spectrographs: list :keyword ccd_prep: action of list of actions to prepare the CCDs (clear, purge, erase) :type ccd_prep: list :keyword exposedCB: :type exposedCB: dict :keyword digitizedCB: the function provided in the structure will be called when the exposure is exposed or digitized. If exposedCB or digitizedCB are not given, the registered callbacks will be used. If nothing is registered no callback functions will be called at the end of the expose or digitize commands. :type digitizedCB: dict details Dictionary with extra info like tel_ra exptime Exposure time in seconds flavor Exposure type compress Save images compressed send_to Instructions to the image builder for image distribution extras Additional keywords to be added during build auto_trigger trigger associated IB if True spec_options can have the same keywords. It is forwared to the spectrographs. For example, auto_build in spec_options causes the spectrographs to built their (individual) images. Using auto_trigger in options sets the auto_trigger flag for SpecMan and the image builder is triggered to combine ALL spectrograph images.

expose(expid, frame=None, use_callback=None, callback_args=None, spec_options={}, **options)

expose spectrographs. See spectrograph roles for command syntax the spec_options keyword is passed to the spectrographs expose function wait controls if the routine waits for completion (default) Other options include (similar syntax is used for spec_options) frame is reserved for future extensions exptime is the exposure time in seconds (float) flavor will be converted to ‘dark’ (for zero, dark) or ‘normal’ (for object, test, winlight etc) if ccd_prep is not None, prepareCCDs() is called with ccd_prep providing the list of actions If updater is True or equal to the (spectrograph) role name, the spectro controller will be told to provide (exposure) updates If wait is True the command does not return until the exposure is complete If no callback is given or registered and wait is set to False, the command will also block until the exposure is done. If use_callback is True, the previously registered callback function (prepare_for_exposure or register_callback) is called at the spectrograph app level. [Note that a separate, internal callback is used between the spectrograph app and the spectrocontroller. use_callback does not affect this functionality.] Additional name arguments given via callback_args will be passed to the callback function (if used) Note that an exposure can also be triggered using the SPECTROGRAPHS_EXPOSE shared variable (if the spectrocontroller is armed (use auto_arm=True for simplified operation)

Currently the SV mode is not fully implemented. It requires an internal exposed callback function that’s called by each spectrograph plus the scoreboard logic and some code to wait for this to be done needs to be added to expose() if exposedCB is set and enabled, that internal exposed callback function can trigger that cb as well (similar to the architecture in spectrograph) Until this is done, we use multiops and expose waits for completion (or the caller has to poll completion status)

digitize(expid, frame=None, use_callback=None, callback_args=None, spec_options={}, **options)

digitize spectrographs. See spectrograph roles for command syntax the spec_options keyword is passed to the spectrographs digitize function wait controls if the routine waits for completion (default) Other options include (similar syntax is used for spec_options) frame is reserved for future extensions If updater is True or equal to the (spectrograph) role name, the spectro controller will be told to provide (exposure) updates If wait is True the command does not return until the exposure is complete If no callback is given or registered and wait is set to False, the command will also block until the exposure is done. If use_callback is True, the previously registered callback function (register_callback) is called. Additional name arguments given via callback_args will be passed to the callback function (if used)

Arguments for spec_options: ccd_idle

build(expid, frame=None, spec_options={}, **options)

build spectrograph images (in case auto_build wasn’t used) See spectrograph roles for command syntax if auto_trigger is set, the image builder is asked to combine all spectrographs (could be renamed to auto_build if not confusing)

Positional arguments:

expid exposure number (required)

Options forwarded to the Image Builder (when auto_trigger is set)

local_copy write a local copy in FITS format if True (spectcon table only) compress Save images rice-compressed extras Extra header keywords added to the primary header mem_purge delete old image data in memory file_purge delete old image data on disk if local_copy is true image_dir image_name send_to distribution information in image builder send_to notation use_header use preloaded header keywords and values for primary header (also forwarded to controllers)

Processed by SpecMan app:

use_callback built callback callback_args additional arguments to be returned with callback spectrographs List of participating spectrographs wait Wait for image built or saved (at spectrograph level) auto_trigger Trigger the image builder at the end of build

spec_options are sent to the spectrograph build command If use_callback is set to True, the callback for build will be used (via register_callback)

trigger_ib(expid, frame, **ib_args)

Trigger associated IB to collect image data ib_args is a dictionary with at least these keys: exp_info, local_copy, send_to, sources, extras

spectrographs(*args, control={}, participating_spectrographs=None, **kwargs)

Send a command to all monitored spectrographs abort (Event), check (function) and control (dictionary) provide control over the multiOps operation, e.g. to check progress or to stop waiting

Keyword Arguments:  

• *args – Passed to the spectrograhs
• **kwargs – Passed to the spectrographs

Raises:

RuntimeError – command execution failed

Returns:

Dictionary with individual responses or just the response if it’s the same from all spectrographs

get(params, *arguments, **kwargs)

Retrieve parameters dynamically. Options include: status, connected, Spectrographs, participating, local_copy, use_header, image_dir, png_dir, image_name, primary, version, use_exposed_callback, use_digitized_callback, use_built_callback, use_ib_callback, use_exp_dir, use_obs_day, required_spectrographs, program, instrument, processing_times, exposure_ready_mode, details, send_to, extras, exposure_status, exposure_processing, exposure Returns information about an exposure

Options: mode=all returns full exposure structure mode=list returns list of exposures mode=detail returns more details about the exposure extheader = extname returns extension header (expid, frame required) extdata = extname returns extension data (expid, frame required) expid=n returns information for exposure n expid=n, frame=m returns information for exposure n, frame m

exposedCB, digitizedCB, builtCB, ibCB interlock (parameter = (list, monitored, enabled, is_set, broken, name), cond = Name of condition (== SV name)), monitor (status, list, undiscovered, disconnected, monitored), device/role with option: key = field, spectrographs (<parameter for get>, spectrographs=<controller>, all),

about_to_connect_to_instance(*args, **kwargs)

To be overridden by the user so that any actions can be taken when the device application is about to connect to an instance

did_connect_to_instance(*args, **kwargs)

To be overridden by the user so that any actions can be taken when the device application connects to an instance

about_to_disconnect_from_instance(*args, **kwargs)

To be overridden by the user so that any actions can be taken when the device application is about to disconnect from an instance

did_disconnect_from_instance(*args, **kwargs)

To be overridden by the user so that any actions can be taken when the device application disconnects from an instance