HAL Reference

Actor

class hal.actor.actor.ActorHelpers(actor)[source]

Bases: object

State helpers.

Parameters:

actor (HALActor)

class hal.actor.actor.HALActor(*args, **kwargs)[source]

Bases: LegacyActor

HAL actor.

static get_instance()[source]

Returns the current instance.

Note that this class is not a proper singleton; if called multiple times it will re-initialise and the instance will change. This is an easy way to get the instance when needed.

Macros

class hal.macros.macro.Macro[source]

Bases: object

A base macro class that offers concurrency and cancellation.

cancel(now=True)[source]

Cancels the execution ot the macro.

Parameters:

now (bool)

async fail_macro(error_or_message, stage=None)[source]

Fails the macros and informs the actor.

Parameters:
get_active_stages()[source]

Returns a list of running stages.

has_status(stages, status)[source]

Determines if any of the stages has that status.

Parameters:
is_stage_done(stage)[source]

Returns True if a stage is finished.

Parameters:

stage (str)

list_stages(command=None, level='i', only_all=False)[source]

Outputs stages to the actor.

Parameters:

  • command (Optional[HALCommandType])

  • level (str)

  • only_all (bool)

output_stage_status(command=None, level='d')[source]

Outputs the stage status to the actor.

Parameters:

  • command (Optional[HALCommandType])

  • level (str)

reset(command, reset_stages=None, force=False, **opts)[source]

Resets stage status.

reset_stages is a list of stages to be executed when calling run. If reset_stages is a list of string and force=False, the reset stages are rearranged according to the original __STAGES__ order, including concurrent stages. If the list of reset_stages includes tuples representing stages that must be run concurrently, or force=True, then the stages are run as input.

opts parameters will be used to override the macro configuration options only until the next reset.

Parameters:

  • command (HALCommandType)

  • reset_stages (Optional[list[StageType]])

  • force (bool)

async run()[source]

Executes the macro allowing for cancellation.

Return type:

bool

async send_command(target, command_string, raise_on_fail=True, **kwargs)[source]

Sends a command to an actor. Raises MacroError if it fails.

Parameters:

  • target (str) – Actor to command.

  • command_string (str) – Command string to pass to the actor.

  • raise_on_fail (bool) – If the command failed, raise an error.

  • kwargs – Additional parameters to pass to send_command().

set_stage_status(stages, status, output=True)[source]

Set the stage status and inform the actor.

Parameters:
async wait_until_complete()[source]

Asynchronously blocks until the macros is done, cancelled, or failed.

property actor

Returns the command actor.

property helpers

Returns the actor helpers.

property running

Is the macro running?

class hal.macros.apogee_dome_flat.APOGEEDomeFlatMacro[source]

Bases: Macro

Take an APOGEE dome flat after an exposure.

async cleanup()[source]

Closes the shutter and does cleanup.

async expose()[source]

Takes the dome flat. Turns on the FFS after the fourth read.

async ffs()[source]

Check the FFS status and closes it.

async gang_at_cart()[source]

Checks that the gang connected is at the cart.

async open_shutter()[source]

Opens the APOGEE cold shutter.

class hal.macros.expose.ExposeMacro[source]

Bases: Macro

Takes a science exposure with APOGEE and/or BOSS.

async cleanup()[source]

Cancel any running exposures.

async expose_apogee()[source]

Exposes APOGEE.

async expose_boss()[source]

Exposes BOSS.

async prepare()[source]

Prepare for exposures and run checks.

class hal.macros.goto_field.GotoFieldAPOMacro[source]

Bases: _GotoFieldBaseMacro

Goto field macro for APO.

async reslew()[source]

Re-slew to field.

async slew()[source]

Slew to field but keep the rotator at a fixed position.

Helpers

class hal.helpers.apogee.APOGEEHelper(actor)[source]

Bases: HALHelper

APOGEE instrument helper.

Parameters:

actor (HALActor)

async expose(command, exp_time, exp_type='dark', dither_position=None)[source]

Exposes APOGEE.

Parameters:

  • command (HALCommandType) – The command used to interact with the APOGEE actor.

  • exp_time (float) – The exposure time.

  • exp_type (str) – The exposure type. Valid values are object, dark, flat, and DomeFlat.

  • dither_position (str | None) – The dither position. If None, uses the current position.

async expose_dither_pair(command, exp_time, dither_sequence=None, exp_type='object')[source]

Takes an APOGEE dither set.

Parameters:

  • command (HALCommandType) – The command used to interact with the APOGEE actor.

  • exp_time (float) – The exposure time for each exposure in the dither sequence.

  • exp_type (str) – The exposure type. Valid values are object, dark, and flat.

  • dither_sequence (str | None) – The dither sequence. If None the first dither will be taken at the current position and the mechanism will be switched after it. Alternatively, a string "AB", "BA", etc.

get_dither_position()[source]

Returns the dither position or None if unknown.

Return type:

str | None

get_shutter_position(shutter='apogee')[source]

Returns the shutter status.

Parameters:

shutter (str) – The shutter to query. Can be apogee, calbox, or fpi.

Returns:

shutter_status – True if the shutter is open, False if closed, None if unknown.

Return type:

bool | None

is_exposing()[source]

Returns True if APOGEE is exposing or stopping.

async set_dither_position(command, position, force=False)[source]

Sets the dither mechanism to the commanded position.

Parameters:

  • command (HALCommandType)

  • position (str)

  • force (bool)

async shutter(command, open=True, shutter='apogee', force=False)[source]

Opens/closes the shutter.

Parameters:

  • command (HALCommandType) – The command instance to use to command the shutter.

  • open (bool) – If True, opens the shutter, otherwise closes it.

  • shutter (str) – The shutter to query. Can be apogee, calbox, or fpi.

  • force (bool) – If True, sends the command to the shutter even if it reports to already be in that position.

Returns:

shutter_command – The command sent to the shutter after been awaited for completion or None if the shutter is already at that position.

class hal.helpers.boss.BOSSHelper(actor)[source]

Bases: HALHelper

Control for BOSS spectrograph.

Parameters:

actor (HALActor)

clear_readout()[source]

Clears any pending readouts.

async expose(command, exp_time=0.0, exp_type='science', readout=True, read_async=False)[source]

Exposes BOSS. If readout=False, does not read the exposure.

Parameters:

  • command (HALCommandType)

  • exp_time (float)

  • exp_type (str)

  • readout (bool)

  • read_async (bool)

get_exposure_state()[source]

Returns the exposure state.

is_exposing()[source]

Returns True if the BOSS spectrograph is currently exposing.

is_reading()[source]

Returns True if the camera is reading.

async readout(command)[source]

Reads a pending readout.

Parameters:

command (HALCommandType)

property readout_pending

True if an exposure readout is pending.

class hal.helpers.ffs.FFSHelper(actor)[source]

Bases: HALHelper

Command and keeps track of the Flat-Field Screens status.

Parameters:

actor (HALActor)

all_closed()[source]

Returns True if all the petals are closed.

all_open()[source]

Returns True if all the petals are open.

async close(command)[source]

Close all the petals.

Parameters:

command (HALCommandType)

get_values()[source]

Returns the FFS status flags.

async open(command)[source]

Open all the petals.

Parameters:

command (HALCommandType)

class hal.helpers.ffs.FFSStatus(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

FFS status flags.

class hal.helpers.lamps.LampsHelperAPO(actor)[source]

Bases: HALHelper

Control for lamps.

Parameters:

actor (HALActor)

async all_off(command, force=False)[source]

Turn off all the lamps.

Parameters:

  • command (HALCommandType)

  • force (bool)

list_status()[source]

Returns a dictionary with the state of the lamps.

For each lamp the first value in the returned tuple is whether the lamp has been commanded on. The second value is whether the lamps is actually on. The third value is how long since it changed states. The final value indicates whether the lamp has warmed up.

Return type:

dict[str, tuple[bool, bool, float, bool]]

async turn_lamp(command, lamps, state, turn_off_others=False, delay=0.0, force=False)[source]

Turns a lamp on or off.

This routine always blocks until the lamps are on and warmed up. If you don’t want to block, call it as a task.

Parameters:

  • command (HALCommandType) – The command that issues the lamp switching.

  • lamps (str | list[str]) – Name of the lamp(s) to turn on or off.

  • state (bool) – Whether to turn lamp on or off.

  • turn_off_others (bool) – Turn off all other lamps.

  • delay (float) – Wait this amount of seconds before actually commanding the lamps.

  • force (bool) – If True, send the on/off command regardless of status.

class hal.helpers.lamps.LampsHelperLCO(actor)[source]

Bases: HALHelper

Control for lamps at LCO.

Parameters:

actor (HALActor)

async all_off(command)[source]

Turn off all the lamps.

Parameters:

command (HALCommandType)

list_status()[source]

Returns a dictionary with the state of the lamps.

For each lamp the first value in the returned tuple is whether the lamp has been commanded on with the second being whether the lamps has finished warming up.

Return type:

dict[str, tuple[bool, bool]]

async turn_lamp(command, lamps, state, turn_off_others=False, delay=0.0, is_retry=False)[source]

Turns a lamp on or off.

This routine always blocks until the lamps are on and warmed up. If you don’t want to block, call it as a task.

Parameters:

  • command (HALCommandType) – The command that issues the lamp switching.

  • lamps (str | list[str]) – Name of the lamp(s) to turn on or off.

  • state (bool) – Whether to turn lamp on or off.

  • turn_off_others (bool) – Turn off all other lamps.

  • delay (float) – Wait this amount of seconds before actually commanding the lamps.

  • is_retry (bool) – Flag to track whether the method is being called as a retry.

class hal.helpers.tcc.TCCHelper(actor)[source]

Bases: HALHelper

Helper for the TCC.

Parameters:

actor (HALActor)

axes_are_clear(axes=('az', 'alt', 'rot'))[source]

Checks that no bits are set in any axis status field.

Return type:

bool

async axis_init(command)[source]

Executes TCC axis init or fails.

Parameters:

command (HALCommandType)

Return type:

bool

async axis_stop(command, axis='')[source]

Issues an axis stop to the TCC.

Parameters:

  • command (HALCommandType)

  • axis (str)

Return type:

bool

below_alt_limit()[source]

Check if we are below the alt=18 limit that prevents init/motion in az.

Return type:

bool

check_axes_status(status)[source]

Returns True if all the axes are at status.

Parameters:

status (str)

Return type:

bool

check_stop_in(axes=('az', 'alt', 'rot'))[source]

Returns True if any stop bit is set in the <axis>Stat TCC keywords.

The [az,alt,rot]Stat[3] bits show the exact status: http://www.apo.nmsu.edu/Telescopes/HardwareControllers/AxisControllers.html#25mStatusBits

Return type:

bool

async do_slew(command, coords=None, track_command=None, keep_offsets=True, offset=False, rotwrap=None)[source]

Correctly handle a slew command, given what parse_args had received.

Parameters:

  • command – The actor command used to send child commands to the TCC.

  • coords (dict[str, float] | None) – The coordinates where to slew. It must be a dictionary with keys ra, dec, rot or alt, az, rot.

  • track_command (str | None) – A raw TCC track command (without the tcc target) to send. In this case other arguments like keep_offsets or rotwrap are ignored.

  • keep_offsets (bool) – Whether to keep the existing offsets.

  • rotwrap (str | None) – The type of /RotWrap to use.

  • offset (bool) – If defined, the coordinates will be treated as an offset and not absolute positions.

Return type:

bool

get_bad_axis_bits(axes=('az', 'alt', 'rot'), mask=None)[source]

Return the bad status bits for the requested axes.

async goto_position(command, where, **kwargs)[source]

Executes the goto command.

Parameters:

  • command (HALCommandType) – The actor command.

  • where (str | dict[str, float]) – The name of the goto entry in the configuration file, or a dictionary with the keys (alt, az, rot) in degrees.

  • kwargs – Arguments to pass to do_slew.

async mcp_semaphore_ok(command)[source]

Returns the semaphore if the semaphore is owned by the TCC or nobody.

Parameters:

command (HALCommandType)

class hal.helpers.scripts.Scripts(actor: 'HALActor', path: 'pathlib.Path')[source]

Bases: object

Parameters:
async cancel(name)[source]

Cancels a running script.

Parameters:

name (str)

get_steps(name)[source]

Returns the list of steps of the script.

Parameters:

name (str)

Return type:

list[tuple[str, str, float | None]]

list_scripts()[source]

Returns a list of script names.

async run(name, command=None)[source]

Runs a script.

This coroutine creates a task with all the steps to execute and adds it to the running dictionary. The execution can be cancelled by calling stop, at which point the task will be cancelled and run will handle the cancellation.

Parameters:
Return type:

bool