From 11e3f587ab5e2c6cadd2d1cdf1d9193d31eb7a11 Mon Sep 17 00:00:00 2001 From: Matthew Hasselfield Date: Wed, 1 Nov 2023 19:39:48 +0000 Subject: [PATCH] ACU sun: docs and requirements --- docs/agents/acu_agent.rst | 58 ++++++++++++++++++++++++++ requirements.txt | 2 + socs/agents/acu/agent.py | 6 +-- socs/agents/acu/avoidance.py | 79 ++++++++++++++++++++++++++++++------ 4 files changed, 130 insertions(+), 15 deletions(-) diff --git a/docs/agents/acu_agent.rst b/docs/agents/acu_agent.rst index c08f3cbeb..dcde6f975 100644 --- a/docs/agents/acu_agent.rst +++ b/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: diff --git a/requirements.txt b/requirements.txt index 6c02ae1dd..1f74fe79b 100644 --- a/requirements.txt +++ b/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 diff --git a/socs/agents/acu/agent.py b/socs/agents/acu/agent.py index 4979d40ee..1a2e9581e 100644 --- a/socs/agents/acu/agent.py +++ b/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 diff --git a/socs/agents/acu/avoidance.py b/socs/agents/acu/avoidance.py index e1371672e..55144decb 100644 --- a/socs/agents/acu/avoidance.py +++ b/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