ACU Sun Avoidance (#559)

* ACU: sun avoidance

* ACU sun: update .sun in the process

* ACU sun: working non-blocking state machine to seek safety

Can be triggered for testing.  Needs logging and a bit more
safetyizing.

* ACU sun: faster sun map computation

* ACU sun: capacity to time-shift the Sun's position, for testing

Also ability to temporarily disable the feature.

* ACU sun: generate_scan checks traj before starting

Also the safe position seek clears faults.

* ACU sun: create Task to handle seek_to_sunsafe

* ACU sun: consolidate SunTracker code and organize policy

* ACU sun: more clean up; catch edge cases

* ACU sun: args, more

* ACU sun: consistencyize, reterminologize.

* ACU sun: one more tweak to escape path computation

* ACU sun: monitor_sun session.data + docs

* ACU sun: fix direct path bug; remove "escape=True" switch

* ACU sun: generate_scan initial seek must be sun-safe too!

* ACU: fix bug where empty blocks were pushed to feed

This wasn't causing any trouble other than lots of log messages in
influxpublisher.

* ACU sun: docs and requirements

* ACU sun: add tests, cleanup

* ACU sunvoidance: more docs cleanup

* ACU sun: Add new dependencies to setup.py

* ACU sunvoidance: couple more docs fixes

---------

Co-authored-by: Brian Koopman <[email protected]>

docs/agents/acu_agent.rst

@@ -26,6 +26,12 @@ installed to use this Agent. This can be installed via:
 
     $ pip install 'soaculib @ git+https://github.com/simonsobs/soaculib.git@master'
 
+Additionally, ``socs`` should be installed with the ``acu`` group:
+
+.. code-block:: bash
+
+    $ pip install -U socs[acu]
+
 Configuration File Examples
 ---------------------------
 Below are configuration examples for the ocs config file and for soaculib.
@@ -88,6 +94,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;
+please see the descriptions of ``sun_dist``, ``sun_time``,
+``exclusion_radius``, and more in the :mod:`socs.agents.acu.avoidance`
+module documentation.
+
+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
 --------------
 
@@ -149,5 +210,14 @@ acquisition processes are running::
 Supporting APIs
 ---------------
 
+drivers (Scanning support)
+``````````````````````````
+
 .. automodule:: socs.agents.acu.drivers
     :members:
+
+avoidance (Sun Avoidance)
+`````````````````````````
+
+.. automodule:: socs.agents.acu.avoidance
+    :members:

docs/user/installation.rst

@@ -22,6 +22,8 @@ The different groups, and the agents they provide dependencies for are:
      - Supporting Agents
    * - ``all``
      - All Agents
+   * - ``acu``
+     - ACU Agent
    * - ``labjack``
      - Labjack Agent
    * - ``magpie``

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

setup.py

@@ -7,7 +7,11 @@
 
 # Optional Dependencies
 # ACU Agent
-# acu_deps = ['soaculib @ git+https://github.com/simonsobs/soaculib.git@master']
+acu_deps = [
+    # 'soaculib @ git+https://github.com/simonsobs/soaculib.git@master',
+    'pixell',
+    'so3g',
+]
 
 # Holography FPGA and Synthesizer Agents
 # holography_deps = [  # Note: supports python 3.8 only!
@@ -53,10 +57,9 @@
 #     'xy_stage_control @ git+https://github.com/kmharrington/xy_stage_control.git@main',
 # ]
 
-# Note: Not including the holograph deps, which are Python 3.8 only
-# all_deps = acu_deps + labjack_deps + magpie_deps + pfeiffer_deps + \
-#    pysmurf_deps + smurf_sim_deps + synacc_deps + xy_stage_deps
-all_deps = labjack_deps + magpie_deps + pfeiffer_deps + \
+# Note: Not including the holograph deps, which are Python 3.8 only. Also not
+# including any dependencies with only direct references.
+all_deps = acu_deps + labjack_deps + magpie_deps + pfeiffer_deps + \
     smurf_sim_deps + synacc_deps + timing_master_deps
 all_deps = list(set(all_deps))
 
@@ -111,7 +114,7 @@
     ],
     extras_require={
         'all': all_deps,
-        # 'acu': acu_deps,
+        'acu': acu_deps,
         # 'holography': holography_deps,
         'labjack': labjack_deps,
         'magpie': magpie_deps,