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: clu.legacy.actor.LegacyActor

HAL actor.

Macros#

class hal.macros.macro.Macro(name=None)[source]#

Bases: object

A base macro class that offers concurrency and cancellation.

Parameters: name (str) –

cancel()[source]#: Cancels the execution ot the macro.

async fail_macro(error, stage=None)[source]#

Fails the macros and informs the actor.

Parameters

error (Exception) –
stage (Optional[Union[str, tuple[str, ...], list[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.

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

stages (Union[str, tuple[str, ...], list[str]]) –
status (hal.macros.macro.StageStatus) –
output (bool) –

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(name=None)[source]#

Bases: hal.macros.macro.Macro

Take an APOGEE dome flat after an exposure.

Parameters: name (Optional[str]) –

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(name=None)[source]#

Bases: hal.macros.macro.Macro

Takes a science exposure with APOGEE and/or BOSS.

Parameters: name (str) –

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.GotoFieldMacro(name=None)[source]#

Bases: hal.macros.macro.Macro

Go to field macro.

Parameters: name (Optional[str]) –

async acquire()[source]#: Acquires the field.

async boss_arcs()[source]#: Takes BOSS arcs.

async boss_flat()[source]#: Takes the BOSS flat.

async boss_hartmann()[source]#: Takes the hartmann sequence.

async cleanup()[source]#: Turns off all lamps.

async fvc()[source]#: Run the FVC loop.

async guide()[source]#: Starts the guide loop.

async prepare()[source]#: Check configuration and run pre-slew checks.

async reconfigure()[source]#: Reconfigures the FPS.

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: hal.helpers.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 (clu.command.Command) –
position (str) –
force (bool) –

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

Opens/closes the shutter.

Parameters

command (clu.command.Command) – 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: hal.helpers.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 (clu.command.Command) –
exp_time (float) –
exp_type (str) –
readout (bool) –
read_async (bool) –

is_exposing()[source]#: Returns True if the BOSS spectrograph is currently exposing.

async readout(command)[source]#

Reads a pending readout.

Parameters: command (clu.command.Command) –

property readout_pending#: True if an exposure readout is pending.

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

Bases: hal.helpers.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 (clu.command.Command) –

get_values()[source]#: Returns the FFS status flags.

async open(command)[source]#

Open all the petals.

Parameters: command (clu.command.Command) –

class hal.helpers.lamps.LampsHelper(actor)[source]#

Bases: hal.helpers.HALHelper

Control for lamps.

Parameters: actor (HALActor) –

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

Turn off all the lamps.

Parameters

command (clu.command.Command) –
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, 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.
lamp – Name of the lamp(s) to turn on or off.
turn_off_others (bool) – Turn off all other lamps.
force (bool) – If True, send the on/off command regardless of status.
lamps (str | list[str]) –
state (bool) –

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

Bases: hal.helpers.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 (clu.command.Command) –
Return type: bool

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

Issues an axis stop to the TCC.

Parameters

command (clu.command.Command) –
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=False, 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 (clu.command.Command) –

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

Bases: object

Parameters

actor (HALActor) –
path (pathlib.Path) –

Return type

None

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

name (str) –
command (Command[HALActor] | None) –

Return type

bool