LatissAcquire

class lsst.ts.externalscripts.auxtel.LatissAcquire(index, add_remotes: bool = True)

Bases: BaseScript

Perform an acquisition of a target on LATISS with the AuxTel.

Parameters:
indexint

Index of Script SAL component.

Notes

An (optional) checkpoint is available to verify the calculated telescope offset after each iteration of the acquisition.

Details

This script is used to put the brightest target in a field on a specific pixel.

Attributes Summary

checkpoints

Get the checkpoints at which to pause and stop.

domain

group_id

Get the group ID (a str), or "" if not set.

state

Get the current state.

state_name

Get the name of the current state.state.

Methods Summary

amain(**kwargs)

Run the script from the command line.

arun([checkpoint])

assert_feasibility()

Verify that the telescope and camera are in a feasible state to execute the script.

assert_state(action, states)

Assert that the current state is in states and the script is not exiting.

checkpoint([name])

Await this at any "nice" point your script can be paused or stopped.

cleanup()

Perform final cleanup, if any.

close([exception, cancel_start])

Shut down, clean up resources and set done_task done.

close_tasks()

Shut down pending tasks.

configure(config)

Configure script.

do_configure(data)

Configure the currently loaded script.

do_resume(data)

Resume the currently paused script.

do_run(data)

Run the script and quit.

do_setAuthList(data)

Update the authorization list.

do_setCheckpoints(data)

Set or clear the checkpoints at which to pause and stop.

do_setGroupId(data)

Set or clear the group_id attribute.

do_setLogLevel(data)

Set logging level.

do_stop(data)

Stop the script.

execute_acquisition(target_position_x, ...)

Perform acquisition of target.

find_offset(data_id, target_position_x, ...)

Detects the brightest star in an image and returns the offsets (dx_arcsec and dy_arcsec) required to move the target to the target position.

get_best_effort_isr()

get_next_image_data_id()

Return dataID of image that appears from the ATOODS CSC.

get_schema()

Return a jsonschema to validate configuration, as a dict.

latiss_reacquire()

Initiates acquisition loop assuming telescope is already in position.

latiss_slew_and_acquire()

Performs slew to new target specified in configuration and initiates performs acquisition loop.

make_from_cmd_line(**kwargs)

Make a script from command-line arguments.

next_supplemented_group_id()

Return the group ID supplemented with a new subgroup.

put_log_level()

Output the logLevel event.

run()

set_metadata(metadata)

Set metadata fields in the provided struct, given the current configuration.

set_state([state, reason, keep_old_reason, ...])

Set the script state.

start()

Finish construction.

start_phase2()

Additional work after start before fully started.

Attributes Documentation

checkpoints

Get the checkpoints at which to pause and stop.

Returns self.evt_checkpoints.data which has these fields:

  • pause: checkpoints at which to pause, a regular expression

  • stop: checkpoints at which to stop, a regular expression

domain
group_id

Get the group ID (a str), or “” if not set.

state

Get the current state.

Returns self.evt_state.data, which has these fields:

  • state: lsst.ts.idl.enums.Script.ScriptState

    The current state.

  • lastCheckpoint: str

    Name of most recently seen checkpoint.

  • reason: str

    Reason for this state, if any.

  • numCheckpoints: int

    The number of checkpoints seen.

state_name

Get the name of the current state.state.

Methods Documentation

async classmethod amain(**kwargs: Any) None

Run the script from the command line.

Parameters:
kwargs

Keyword arguments for the script constructor. Must not include index. Ignored (other than testing for index) if the command specifies --schema.

Raises:
RuntimeError

If kwargs includes index.

Notes

The final return code will be:

  • 0 if final state is lsst.ts.idl.enums.Script.ScriptState.DONE or lsst.ts.idl.enums.Script.ScriptState.STOPPED.

  • 1 if final state is anything else, or if script.done_task is an exception (which would be raised by the script’s cleanup code).

Issues a RuntimeWarning if script.done_task is an exception and the final script state is anything other than Failed. This should never happen.

async arun(checkpoint=False)
async assert_feasibility() None

Verify that the telescope and camera are in a feasible state to execute the script.

assert_state(action: str, states: Sequence[ScriptState]) None

Assert that the current state is in states and the script is not exiting.

Parameters:
actionstr

Description of what you want to do.

stateslist [lsst.ts.idl.enums.Script.ScriptState]

Allowed states.

async checkpoint(name: str = '') None

Await this at any “nice” point your script can be paused or stopped.

Parameters:
namestr, optional

Name of checkpoint; “” if it has no name.

Raises:
RuntimeError

If the state is not ScriptState.RUNNING. This likely means you called checkpoint from somewhere other than run.

RuntimeError

If _run_task is None or done. This probably means your code incorrectly set the state.

async cleanup() None

Perform final cleanup, if any.

This method is called as the script state is exiting, unless the script had not yet started to run, or the script process is aborted by SIGTERM or SIGKILL.

async close(exception: Exception | None = None, cancel_start: bool = True) None

Shut down, clean up resources and set done_task done.

May be called multiple times. The first call closes the Controller; subsequent calls wait until the Controller is closed.

Subclasses should override close_tasks instead of close, unless you have a good reason to do otherwise.

Parameters:
exceptionException, optional

The exception that caused stopping, if any, in which case the self.done_task exception is set to this value. Specify None for a normal exit, in which case the self.done_task result is set to None.

cancel_startbool, optional

Cancel the start task? Leave this true unless calling this from the start task.

Notes

Removes the SAL log handler, calls close_tasks to stop all background tasks, pauses briefly to allow final SAL messages to be sent, then closes the dds domain.

async close_tasks() None

Shut down pending tasks. Called by close.

Perform all cleanup other than disabling logging to SAL and closing the dds domain.

async configure(config)

Configure script.

Parameters:
configtypes.SimpleNamespace

Script configuration, as defined by schema.

async do_configure(data: BaseMsgType) None

Configure the currently loaded script.

Parameters:
datacmd_configure.DataType

Configuration.

Raises:
base.ExpectedError

If self.state.state is not lsst.ts.idl.enums.Script.ScriptState.UNCONFIGURED.

Notes

This method does the following:

  • Parse the config field as yaml-encoded dict and validate it (including setting default values).

  • Call configure.

  • Set the pause and stop checkpoints.

  • Set the log level if data.logLevel != 0.

  • Call set_metadata.

  • Output the metadata event.

  • Change the script state to lsst.ts.idl.enums.Script.ScriptState.CONFIGURED.

async do_resume(data: BaseMsgType) None

Resume the currently paused script.

Parameters:
datacmd_resume.DataType

Ignored.

Raises:
base.ExpectedError

If self.state.state is not lsst.ts.idl.enums.Script.ScriptState.PAUSED.

async do_run(data: BaseMsgType) None

Run the script and quit.

The script must have been configured and the group ID set.

Parameters:
datacmd_run.DataType

Ignored.

Raises:
base.ExpectedError

If self.state.state is not lsst.ts.idl.enums.Script.ScriptState.CONFIGURED. If self.group_id is blank.

async do_setAuthList(data: BaseMsgType) None

Update the authorization list.

Parameters:
datacmd_setAuthList.DataType

Authorization lists.

Notes

Add items if the data string starts with “+”, ignoring duplicates (both with respect to the existing items and within the data string). Remove items if the data string starts with “-”, ignoring missing items (items specified for removal that do not exist). Ignore whitespace after each comma and after the +/- prefix.

async do_setCheckpoints(data: BaseMsgType) None

Set or clear the checkpoints at which to pause and stop.

This command is deprecated. Please set the checkpoints using the configure command.

Parameters:
datacmd_setCheckpoints.DataType

Names of checkpoints for pausing and stopping, each a single regular expression; “” for no checkpoints, “.*” for all.

Raises:
base.ExpectedError

If self.state.state is not one of:

  • lsst.ts.idl.enums.Script.ScriptState.UNCONFIGURED

  • lsst.ts.idl.enums.Script.ScriptState.CONFIGURED

  • lsst.ts.idl.enums.Script.ScriptState.RUNNING

  • lsst.ts.idl.enums.Script.ScriptState.PAUSED

async do_setGroupId(data: BaseMsgType) None

Set or clear the group_id attribute.

The script must be in the Configured state. This command may be called multiple times. It is typically called when the script reaches the top position on the script queue.

Parameters:
datacmd_setGroupId.DataType

Group ID, or “” to clear the group ID.

Raises:
base.ExpectedError

If state.state is not lsst.ts.idl.enums.Script.ScriptState.CONFIGURED.

async do_setLogLevel(data: BaseMsgType) None

Set logging level.

Parameters:
datacmd_setLogLevel.DataType

Logging level.

async do_stop(data: BaseMsgType) None

Stop the script.

Parameters:
datacmd_stop.DataType

Ignored.

Notes

This is a no-op if the script is already exiting. This does not wait for _exit to run.

async execute_acquisition(target_position_x, target_position_y)

Perform acquisition of target.

Will iteratively measure position of brightest object in image, calculate offsets required to translate to target_position, apply offsets, take a new image, measure position of brightest object in new image and check that it has arrived at target position within tolerance. Iterations will continue until either the brightest object has arrived at position within tolerance or configurable max acq iters parameter is met.

Parameters:
target_position_xfloat

desired final X position in detector coordinates.

target_position_yfloat

desired final X position in detector coordinates.

async find_offset(data_id, target_position_x, target_position_y)

Detects the brightest star in an image and returns the offsets (dx_arcsec and dy_arcsec) required to move the target to the target position.

Parameters:
data_iddict

data Id for initial exposure with target initial position.

target_position_xfloat

desired final X position in detector coordinates.

target_position_yfloat

desired final X position in detector coordinates.

Returns:
dx_arcsec, dy_arcsec: float, float

offsets (arcsec) required to translate target from detected position to desired final position

get_best_effort_isr()
async get_next_image_data_id()

Return dataID of image that appears from the ATOODS CSC.

This is meant to be called at the same time as a take image command. If this is called after take_image is completed, it may not receive the imageInOODS event.

classmethod get_schema()

Return a jsonschema to validate configuration, as a dict.

Please provide default values for all fields for which defaults make sense. This makes the script easier to use.

If your script has no configuration then return None, in which case the config field of the configure command must be an empty string.

async latiss_reacquire()

Initiates acquisition loop assuming telescope is already in position.

A final, verification image is taken if configured.

async latiss_slew_and_acquire()

Performs slew to new target specified in configuration and initiates performs acquisition loop.

A final, verification image is taken if configured.

classmethod make_from_cmd_line(**kwargs: Any) lsst.ts.salobj.base_script.BaseScript | None

Make a script from command-line arguments.

Return None if --schema specified.

Parameters:
kwargs

Keyword arguments for the script constructor. Must not include index.

Raises:
RuntimeError

If kwargs includes index.

next_supplemented_group_id() str

Return the group ID supplemented with a new subgroup.

The returned string has this format: f”{self.group_id}#{subgroup_id}”, where subgroup_id is an integer that starts at 1 and is incremented for every call to this method.

Raises:
RuntimeError

If there is no group ID.

async put_log_level() None

Output the logLevel event.

async run()
set_metadata(metadata)

Set metadata fields in the provided struct, given the current configuration.

Parameters:
metadataself.evt_metadata.DataType()

Metadata to update. Set those fields for which you have useful information.

Notes

This method is called after configure by do_configure. The script state will be ScriptState.UNCONFIGURED.

async set_state(state: lsst.ts.xml.enums.Script.ScriptState | int | None = None, reason: str | None = None, keep_old_reason: bool = False, force_output: bool = False) None

Set the script state.

Parameters:
stateScriptState or int, optional

New state, or None if no change

reasonstr, optional

Reason for state change. None for no new reason.

keep_old_reasonbool

If true, keep old reason; append the reason argument after “;” if it is is a non-empty string. If false replace with reason, or “” if reason is None.

force_outputbool, optional

If true the output even if not changed.

Notes

The lastCheckpoint field is set from self.last_checkpoint, and the numCheckpoints field is set from self.num_checkpoints.

async start() None

Finish construction.

async start_phase2() None

Additional work after start before fully started.

Used by BaseCsc to transition to handle the initial state.