The Spectrograph class

12/30/2015 v0.5 KH Initial framework 4/11/2018 v0.6 KH Image Builder integration

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

init(unit=None)

Initialize spectrograph application. Set up variables, import controller module, discovery

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 (expose, digitize, build) 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

build_callback(*args, **kwargs)

Callback when image is built (or saved)

digitize_callback(*args, **kwargs)

Callback when ccds are read out

expose_callback(*args, **kwargs)

Callback when exposure is complete

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

Configure the controller applications

Loads constants from DB when applicable Resets exposure id and the exposures management structure Repeats the initial configuration (_initial_configuration()) When successful, the application state is set to READY

get(params, *arguments, **kwargs)

Retrieve parameters dynamically. Options include: status, connected, vccd, ccdpower, auto_build, unit, ccd_info, remote_devices, local_copy, use_header, image_dir, image_name, version, exclude, use_exposed_callback, use_digitized_callback, use_built_callback, primary, program, instrument, processing_times, exposure_ready_mode, exposure_processing, exposure_status, send_to, extras, 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, device (all, <device name>), 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, ccdcon (<ccd controller parameter>, ccd=<controller>, all), spectcon_status, plot options (from ImageBuilder)

set(**options)

Set key/value pairs to set parameters dynamically. Options include: local_copy, use_header, use_exposed_callback, use_digitized_callback, use_built_callback, use_exp_dir, use_obs_day, exposure_ready_mode, primary, image_name, sub_dir, image_dir, vccd, ccdpower 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)

auto_build, mem_purge, file_purge, mem_purge_threshold, file_purge_threshold, frame_purge_threshold

ccdcontrol(ccd, command, *args, **kwargs)

Access to individual or all CCD controllers ccd selects the controller and can be either nir, red or blue command is the CCD controller function and args/kwargs are passed to that function The value returned from the CCD controller(s) is returned.

If ccd is set to all, the command is sent to all active CCD controllers. If all controllers return the same value, it’s returned to the called. If the values received from the controllers differ, a dictionary with the responses is returns

spectrocontrol(command, *args, **kwargs)

Access to the SpectroController command is the spectro controller function and args/kwargs are passed to that function The value returned from the spectro controller is returned.

prepare_for_illumination(*args, cb_name=None, cb_function=None, cb_args=None, auto_arm=True)

convenience function to prepare the illuminator for the next (FVC) exposure all arguments are passed on to the prepare_for_illumination function of the spectrograph controller If auto_arm is set, the illuminator is armed to wait for the SPECTROGRAPHS_ILLUMINATE SV. This is equivalent to calling spectrocontrol(‘prepare_for_illumination’,*args, **kwargs)

illuminate(*args, **kwargs)

Convenience function to control the fiber illuminator. The arguments are passed straight to the illuminator function of the spectrograph controller. This is equivalent to calling spectrocontrol(‘illuminator’,*args, **kwargs) Since the current spectro controller firmware uses fixed length pulses (50 ms each) we use multiple pulses to achieve the requested flash_time (if given, the default is just one pulse)

prepareCCDs(expid, frame=None, actions=None)

extra function separate from prepare_for_exposure to setup the CCDs at the last moment.

prepare_for_exposure(expid, frame=None, controller='all', use_sv=False, use_header=None, local_copy=None, compress=None, ccd_prep=None, auto_build=None, use_exposed_callback=None, use_digitized_callback=None, use_built_callback=None, send_to=None, extras=None, **options)

Prepare spectrograph for an exposure expid (int) exposure number controller (list) selects which controllers to prepare

(all, r[ed], b[lue], z[nir], spectcon or a list of these)

use_sv (bool) Use SPECTROGRAPHS_EXPOSE SV instead of loop over expose()

Will call spectro controller arm() function

ccd_prep (list) action of list of actions to prepare the CCDs (clear, purge, erase) local_copy, use_header, auto_build are flags to control the (image builder) behavior. If given they are stored in the exposures structure. use_exposed_callback (bool) use_digitized_callback (bool) use_built_callback (bool) Options: 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

expose(expid, frame=None, exptime=None, flavor=None, wait=None, use_callback=None, ccd_prep=None, updater=None, callback_args={}, **options)

Convenience function to start an exposure (open the shutter on the spectrograph) on the spectrograph controller. The function returns immediately unless wait is set. expid is the exposure number (integer) 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)

digitize(expid, frame=None, **options)

Digitize CCDs and generate spectcon table.

Optionally write spectcon table in FITS format to file Positional arguments

expid exposure number (required, int or ‘next’)

Named arguments):

controllers List of participating controllers auto_build Call the build function at the end of digitize (all IB related values will be forwarded) local_copy compress # forwarded to CCD controller ccd_idle set idle mode after readout is complete (passed on to ccd controllers ccd_local_copy write a local copy in FITS format if True ccd_compress instruct ccd controller to write compressed fits files report_progress update progress shared variable during readout # Digitized callback use_callback If True enables callback (if registered) callback_args additional name arguments will be passed to the callback function (if used) wait If True wait for digitization to complete

If auto_build is set, the complete options dictionary will be forwarded to the build function)

If use_callback is set to True, the callback for digitize will be used (via register_callback or prepare_for_exposure) The rest of the named arguments passed to the routine but not listed in digitize_headers will be added to the header. (expid will be renamed to EXPNUM) Returns a dictionary with status information on completion

build(expid, frame=None, **options)

Combine images from the 3 CCD controllers and builds the spectcon table extension into a single MEF “file”

*) using the get_image function of the controllers *) triggering the image builder

Supports arguments to write a local copy and to send the image to a pml interface Adds header information to the primary extensions, Callback support for the OCS (or others)

Positional arguments:

expid exposure number (required)

Named arguments:

local_copy write a local copy in FITS format if True (spectcon table only) compress Save images rice-compressed 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) use_callback built callback callback_args additional arguments to be returned with callback controllers List of participating controllers extras Extra header keywords added to the primary header wait Wait for image built or saved

If use_callback is set to True, the callback for build will be used (via register_callback) Returns a dictionary with status information on completion

finalize_exposure(expid)

Finalize an exposure by setting the status field in the exposures to ‘COMPLETE’

pause_exposure(expid, use_callback=False)

Pause an ongoing exposure. Call (pre registered) callback function if requested

resume_exposure(expid, use_callback=False, updater=None)

Resume a paused exposure. Call (pre registered) callback function if requested

stop_exposure(expid, use_callback=False)

Stop an ongoing exposure. Call (pre registered) callback function if requested

send_image(expid, frame=None, send_to=None, send_command=None, extra_headers=None, clobber=False, exclude=None, all_fields=False)

Send data for exposure = expid to an PML interface (name or proxy) Required arguments: expid (required) Optional arguments:

frame frame number (default is None which means send all frames) to (proxy or name of receiving PML interface (or list)) command (function of receiving PML interface to be called) extra_headers will be added to the FITS header clobber if true existing header keywords will be overwritten exclude list of frame keywords to omit from image data

get_image(expid, frame=None, extra_headers=None, clobber=False, exclude=None, all_fields=False)

Returns an image (single or all frames) Required arguments: expid (int) The requested image must be in the internal exposure status structure. If frame == None, all frames for this exposure will be returned key/value pairs given in extra_headers will be added to the header of each frame’s primary extension (if it exists). If clobber == True, existing header keys will be overwritten (if same name) exclude is used to omit <frame>/<extension> keywords

write_image(expid, frame=None, image_dir=None, image_name=None, extra_headers=None, clobber=False, overwrite=True, exclude=None, compress=False)

Save image to disk Required arguments: expid (int) Optional arguments: frame (int) frame to write (if None all frames are written to disk)

image_name Overwrites default image base name image_dir Overwrites default image directory overwrite If True, an existing file with the same name will be overwritten. extra_headers key/value pairs to be added to the header of each frame’s primary extension (if it exists). clobber If true, existing header keys will be overwritten (if same name) exclude list of frame keywords to omit from image data compress if True, image data will be saved rice-compressed (locally)

will_shutdown()

To be overridden by the user so that a shutdown can be handled internally.

main()

Main routine of the Spectrograph Application. Wait for shutdown flag while periodically updating telemetry and mechanism status.

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

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

init(unit=None)

Initialize spectrograph application. Set up variables, import controller module, discovery

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 (expose, digitize, build) 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

build_callback(*args, **kwargs)

Callback when image is built (or saved)

digitize_callback(*args, **kwargs)

Callback when ccds are read out

expose_callback(*args, **kwargs)

Callback when exposure is complete

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

Configure the controller applications

Loads constants from DB when applicable Resets exposure id and the exposures management structure Repeats the initial configuration (_initial_configuration()) When successful, the application state is set to READY

get(params, *arguments, **kwargs)

Retrieve parameters dynamically. Options include: status, connected, vccd, ccdpower, auto_build, unit, ccd_info, remote_devices, local_copy, use_header, image_dir, image_name, version, exclude, use_exposed_callback, use_digitized_callback, use_built_callback, primary, program, instrument, processing_times, exposure_ready_mode, exposure_processing, exposure_status, send_to, extras, 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, device (all, <device name>), 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, ccdcon (<ccd controller parameter>, ccd=<controller>, all), spectcon_status, plot options (from ImageBuilder)

set(**options)

Set key/value pairs to set parameters dynamically. Options include: local_copy, use_header, use_exposed_callback, use_digitized_callback, use_built_callback, use_exp_dir, use_obs_day, exposure_ready_mode, primary, image_name, sub_dir, image_dir, vccd, ccdpower 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)

auto_build, mem_purge, file_purge, mem_purge_threshold, file_purge_threshold, frame_purge_threshold

ccdcontrol(ccd, command, *args, **kwargs)

Access to individual or all CCD controllers ccd selects the controller and can be either nir, red or blue command is the CCD controller function and args/kwargs are passed to that function The value returned from the CCD controller(s) is returned.

If ccd is set to all, the command is sent to all active CCD controllers. If all controllers return the same value, it’s returned to the called. If the values received from the controllers differ, a dictionary with the responses is returns

spectrocontrol(command, *args, **kwargs)

Access to the SpectroController command is the spectro controller function and args/kwargs are passed to that function The value returned from the spectro controller is returned.

prepare_for_illumination(*args, cb_name=None, cb_function=None, cb_args=None, auto_arm=True)

convenience function to prepare the illuminator for the next (FVC) exposure all arguments are passed on to the prepare_for_illumination function of the spectrograph controller If auto_arm is set, the illuminator is armed to wait for the SPECTROGRAPHS_ILLUMINATE SV. This is equivalent to calling spectrocontrol(‘prepare_for_illumination’,*args, **kwargs)

illuminate(*args, **kwargs)

Convenience function to control the fiber illuminator. The arguments are passed straight to the illuminator function of the spectrograph controller. This is equivalent to calling spectrocontrol(‘illuminator’,*args, **kwargs) Since the current spectro controller firmware uses fixed length pulses (50 ms each) we use multiple pulses to achieve the requested flash_time (if given, the default is just one pulse)

prepareCCDs(expid, frame=None, actions=None)

extra function separate from prepare_for_exposure to setup the CCDs at the last moment.

prepare_for_exposure(expid, frame=None, controller='all', use_sv=False, use_header=None, local_copy=None, compress=None, ccd_prep=None, auto_build=None, use_exposed_callback=None, use_digitized_callback=None, use_built_callback=None, send_to=None, extras=None, **options)

Prepare spectrograph for an exposure expid (int) exposure number controller (list) selects which controllers to prepare

(all, r[ed], b[lue], z[nir], spectcon or a list of these)

use_sv (bool) Use SPECTROGRAPHS_EXPOSE SV instead of loop over expose()

Will call spectro controller arm() function

ccd_prep (list) action of list of actions to prepare the CCDs (clear, purge, erase) local_copy, use_header, auto_build are flags to control the (image builder) behavior. If given they are stored in the exposures structure. use_exposed_callback (bool) use_digitized_callback (bool) use_built_callback (bool) Options: 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

expose(expid, frame=None, exptime=None, flavor=None, wait=None, use_callback=None, ccd_prep=None, updater=None, callback_args={}, **options)

Convenience function to start an exposure (open the shutter on the spectrograph) on the spectrograph controller. The function returns immediately unless wait is set. expid is the exposure number (integer) 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)

digitize(expid, frame=None, **options)

Digitize CCDs and generate spectcon table.

Optionally write spectcon table in FITS format to file Positional arguments

expid exposure number (required, int or ‘next’)

Named arguments):

controllers List of participating controllers auto_build Call the build function at the end of digitize (all IB related values will be forwarded) local_copy compress # forwarded to CCD controller ccd_idle set idle mode after readout is complete (passed on to ccd controllers ccd_local_copy write a local copy in FITS format if True ccd_compress instruct ccd controller to write compressed fits files report_progress update progress shared variable during readout # Digitized callback use_callback If True enables callback (if registered) callback_args additional name arguments will be passed to the callback function (if used) wait If True wait for digitization to complete

If auto_build is set, the complete options dictionary will be forwarded to the build function)

If use_callback is set to True, the callback for digitize will be used (via register_callback or prepare_for_exposure) The rest of the named arguments passed to the routine but not listed in digitize_headers will be added to the header. (expid will be renamed to EXPNUM) Returns a dictionary with status information on completion

build(expid, frame=None, **options)

Combine images from the 3 CCD controllers and builds the spectcon table extension into a single MEF “file”

*) using the get_image function of the controllers *) triggering the image builder

Supports arguments to write a local copy and to send the image to a pml interface Adds header information to the primary extensions, Callback support for the OCS (or others)

Positional arguments:

expid exposure number (required)

Named arguments:

local_copy write a local copy in FITS format if True (spectcon table only) compress Save images rice-compressed 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) use_callback built callback callback_args additional arguments to be returned with callback controllers List of participating controllers extras Extra header keywords added to the primary header wait Wait for image built or saved

If use_callback is set to True, the callback for build will be used (via register_callback) Returns a dictionary with status information on completion

finalize_exposure(expid)

Finalize an exposure by setting the status field in the exposures to ‘COMPLETE’

pause_exposure(expid, use_callback=False)

Pause an ongoing exposure. Call (pre registered) callback function if requested

resume_exposure(expid, use_callback=False, updater=None)

Resume a paused exposure. Call (pre registered) callback function if requested

stop_exposure(expid, use_callback=False)

Stop an ongoing exposure. Call (pre registered) callback function if requested

send_image(expid, frame=None, send_to=None, send_command=None, extra_headers=None, clobber=False, exclude=None, all_fields=False)

Send data for exposure = expid to an PML interface (name or proxy) Required arguments: expid (required) Optional arguments:

frame frame number (default is None which means send all frames) to (proxy or name of receiving PML interface (or list)) command (function of receiving PML interface to be called) extra_headers will be added to the FITS header clobber if true existing header keywords will be overwritten exclude list of frame keywords to omit from image data

get_image(expid, frame=None, extra_headers=None, clobber=False, exclude=None, all_fields=False)

Returns an image (single or all frames) Required arguments: expid (int) The requested image must be in the internal exposure status structure. If frame == None, all frames for this exposure will be returned key/value pairs given in extra_headers will be added to the header of each frame’s primary extension (if it exists). If clobber == True, existing header keys will be overwritten (if same name) exclude is used to omit <frame>/<extension> keywords

write_image(expid, frame=None, image_dir=None, image_name=None, extra_headers=None, clobber=False, overwrite=True, exclude=None, compress=False)

Save image to disk Required arguments: expid (int) Optional arguments: frame (int) frame to write (if None all frames are written to disk)

image_name Overwrites default image base name image_dir Overwrites default image directory overwrite If True, an existing file with the same name will be overwritten. extra_headers key/value pairs to be added to the header of each frame’s primary extension (if it exists). clobber If true, existing header keys will be overwritten (if same name) exclude list of frame keywords to omit from image data compress if True, image data will be saved rice-compressed (locally)

will_shutdown()

To be overridden by the user so that a shutdown can be handled internally.

main()

Main routine of the Spectrograph Application. Wait for shutdown flag while periodically updating telemetry and mechanism status.

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