robotic module
**************

The robotic module provides a client for robotic operation of the APO SONG telescope.
It uses the routine and Alpyca devices of the aposong module to execute observatory,
telescope and camera control.

The robotic module can draw targets and observing sequences from a local database
or from a database populated by the SONG conductor at Aarhus.

The basic robotic operation is independent of where requests are drawn from.
The main function is observe(). This will wait until a specified time relative
to sunset to open the dome, and then wait until a specified time relative to nautical
twilight to start observing. Observing continues in a loop until a specified time
relative to morning twilight. Safety status is checked in between each object to
determine whether to suspend operations until it becomes safe again; note that
the dome closes independently immediately on unsafe conditions through the
Dome server.

Local requests are drawn from a Postgres robotic schema that includes a 
database table (requests) that gives a target (defined in target table), observing schedule
constraints (defined in schedule table), and observing sequence
(defined in sequence table). The getbest() routine selects the best
object to observed given the constraints and length of observing
sequence based on either a criterion to observe objects before they
set (default), or to observe objects that will be available for the
longest amount of time.

For SONG targets, robotic targets are conducted through Postgres
database syncs from Aarhus to the song1m_db machine. Requested
observations are loaded into the obs_request_4 table in db_song with
information about the target and the observing sequence. As the request
is started, completed, or aborted, the status is communicated back
through the obs_reqeust_status_4 table in db_apo. Other tables in db_apo
communicate the state of the APO system so that the conductor can choose
appropriate targets.

Once an object is selected, it is acquired, guiding started, and then the
exposure sequence executed. Completed sequences are logged back into the Postgres
database in the observed table.

Calibration sequences can also be obtained automatically.

At the end of the night, web pages, focus curves, and guider movies for the
night are constructed.

The contents of the database tables for local requests is shown below:

.. image:: robotic_schema.png
  :width: 600
  :alt: robotic schema

To add a local observation request, use the loadrequest() function. This
requires specifying a target, sequence, schedule, from the respective
database tables, as well as a integer priority (larger number is higher
priority). You can retrieve existing entries in the tables using the
query() function, and can add new entries using loadtarg(), loadsched(),
and loadseq() functions. See docstrings (using help or ?) for details.

Module functions
++++++++++++++++
.. automodule:: robotic
   :members:
   :member-order: bysource