ACU sun: docs and requirements

docs/agents/acu_agent.rst

@@ -88,6 +88,61 @@ example configuration block is below::
     }
 
 
+Sun Avoidance
+-------------
+
+The Sun's position, and the potential danger of the Sun to the
+equipment, is monitored and reported by the ``monitor_sun`` Process.
+If enabled to do so, this Process can trigger the ``escape_sun_now``
+Task, which will cause the platform to move to a Sun-safe position.
+
+The parameters used by an Agent instance for Sun Avoidance are
+determined like this:
+
+- Default parameters for each platform (LAT and SATP) are in the Agent
+  code.
+- On start-up the default parameters for platform are modified
+  according to any command-line parameters passed in by the user.
+- Some parameters can be altered using the command line.
+
+The avoidance policy is defined by a few key parameters and concepts.
+
+.. automodule:: socs.agents.acu.avoidance
+
+
+The ``exclusion_radius`` can be configured from the Agent command
+line, and also through the ``update_sun`` Task.
+
+When Sun Avoidance is active (``active_avoidance`` is ``True``), the
+following will be enforced:
+
+- When a user initiates the ``go_to`` Task, the target point of the
+  motion will be checked.  If it is not Sun-safe, the Task will exit
+  immediately with an error.  If the Task cannot find a set of moves
+  that are Sun-safe and that do not violate other requirements
+  (azimuth and elevation limits; the ``el_dodging`` policy), then the
+  Task will exit with error.  The move may be executed as a series of
+  separate legs (e.g. the Task may move first to an intermediate
+  elevation, then slew in azimuth, then continue to the final
+  elevation) rather than simulataneously commanding az and el motion.
+- When a user starts the ``generate_scan`` Process, the sweep of the
+  scan will be checked for Sun-safety, and the Process will exit with
+  error if it is not.  Furthermore, any movement required prior to
+  starting the scan will be checked in the same way as for the
+  ``go_to`` Task.
+- If the platform, at any time, enters a position that is not
+  Sun-safe, then an Escape will be Initiated.  During an Escape, any
+  running ``go_to`` or ``generate_scan`` operations will be cancelled,
+  and further motions are blocked.  The platform will be driven to a
+  position at due North or due South.  The current elevation of the
+  platform will be preserved, unless that is not Sun-safe (in which
+  case lower elevations will be attempted).  The Escape feature is
+  active, even when motions are not in progress, as long as the
+  ``monitor_sun`` Process is running.  However -- the Escape operation
+  requires that the platform be in Remote operation mode, with no
+  persistent faults.
+
+
 Exercisor Mode
 --------------
 
@@ -151,3 +206,6 @@ Supporting APIs
 
 .. automodule:: socs.agents.acu.drivers
     :members:
+
+.. automodule:: socs.agents.acu.avoidance
+    :members:

requirements.txt

@@ -16,6 +16,8 @@ pyyaml
 
 # acu agent
 soaculib @ git+https://github.com/simonsobs/soaculib.git@master
+so3g
+pixell
 
 # holography agent - python 3.8 only!
 # -r requirements/holography.txt

socs/agents/acu/agent.py

@@ -2443,11 +2443,11 @@ def add_agent_args(parser_in=None):
     pgroup.add_argument("--max-el", type=float,
                         help="Override the maximum el defined in platform config.")
     pgroup.add_argument("--avoid-sun", type=int,
-                        help="Pass 0 or 1 to enable or disable Sun avoidance. "
+                        help="Pass 0 or 1 to disable or enable Sun avoidance. "
                         "Overrides the platform default config.")
     pgroup.add_argument("--fov-radius", type=float,
-                        help="Override the default field of view (radius in "
-                        "degrees, for Sun avoidance purposes.")
+                        help="Override the default field-of-view (radius in "
+                        "degrees) for Sun avoidance purposes.")
     return parser_in
 
 

socs/agents/acu/avoidance.py

@@ -1,17 +1,72 @@
-"""Sun Avoidance
-
-This module provides code to support Sun Avoidance in the ACU Agent.
-The basic idea is to create a map in equatorial coordinates where the
-value of the map indicates when that region of the sky will next be
-within the Sun Exclusion Zone (likely defined as some radius around
-the Sun).
-
-Using that pre-computed map, any az-el pointings can be checked for
-Sun safety (i.e. whether they are safe positoins), at least for the
-following 24 hours.  The map can be used to identify safest routes
-between two az-el pointings.
+# Sun Avoidance
+#
+# The docstring below is intended for injection into the documentation
+# system.
+
+"""When considering Sun Safety of a boresight pointing, we consider an
+exclusion zone around the Sun with a user-specified radius. This is
+called the ``exclusion_radius`` or the field-of-view radius.
+
+The Safety of the instrument at any given moment is parametrized
+by two numbers:
+
+  ``sun_dist``
+    The separation between the Sun and the boresight (az, el), in
+    degrees.
+
+  ``sun_time``
+    The minimum time, in seconds, which must elapse before the current
+    (az, el) pointing of the boresight will lie within the exclusion
+    radius of the Sun.
+
+While the ``sun_dist`` is an important indicator of whether the
+instrument is currently in immediate danger, the ``sun_time`` is
+helpful with looking forward and avoiding positions that will soon be
+dangerous.
+
+The user-defined policy for Sun Safety is captured in the following
+settings:
+
+  ``exclusion_radius``
+    The radius, in degres, of a disk centered on the Sun that must be
+    avoided by the boresight.
+
+  ``min_sun_time``
+    An (az, el) position is considered unsafe (danger zone) if the
+    ``sun_time`` is less than the ``min_sun_time``. (Expressed in
+    seconds.)
+
+  ``response_time``
+    An (az, el) position is considered vulnerable (warning zone) if
+    the ``sun_time`` is less than the ``response_time``. This is
+    intended to represent the maximum amount of time it could take an
+    operator to reach the instrument and secure it, were motion to
+    stall unexpectedly. (Expressed in seconds.)
+
+  ``el_horizon``
+    The elevation (in degrees) below which the Sun may be considered
+    as invisible to the instrument.
+
+  ``el_dodging``
+    This setting affects how point-to-point motions are executed, with
+    respect to what elevations may be used in intermediate legs of the
+    trajectory. When this is False, the platform is restricted to
+    travel only at elevations that lie between the initial and the
+    target elevation. When True, the platform is permitted to travel
+    at other elevations, all the way up to the limits of the
+    platform. Using True is helpful to find Sun-safe trajectories in
+    some circumstances. But False is helpful if excess elevation
+    changes are potentially disturbing to the cryogenics.  This
+    setting only affects point-to-point motions; "escape" paths will
+    always consider all available elevations.
+
+
+A "Sun-safe" position is a pointing of the boresight that currently
+has a ``sun_time`` that meets or exceeds the ``min_sun_time``
+parameter.
 
 """
+
 import datetime
 import math
 import time