.. _apfteq:

apfteq - temperature equilibrium service
========================================

The apfteq KTL dispatcher maintains the interior temperature of the APF dome;
the manner in which it does so depends on the selected control mode.
The control mode is exposed as the ``MODE`` keyword in the apfteq service.

The apfteq dispatcher will actively control the temperature setpoint for
the fan cooling units (FCUs) on the second and third floor of the dome
in accordance with the current setting of the ``MODE`` keyword. The setpoint
for the FCU on the first floor will be set to match, within a restricted
range of values.

On transitions between modes, or if a system's permission keyword changes
state, other systems will be inspected and adjusted. This second tier of
semi-active control is implemented for the dome vent doors, and whether
the FCUs and recirculation fans are turned on. If any system under
semi-active control is modified by a human or another software tool, its
state will not be "corrected" by apfteq.

While other aspects of the APF will feed into the decisions made by
apfteq, these are the only subsystems that it will attempt to control.



.. _apfteq_progression:

Automatic progression of control modes
--------------------------------------

The ``PROGRESSION`` keyword indicates whether the control modes will
automatically progress to the next logical value at the appropriate time.
If ``PROGRESSION`` is set to Manual, no automatic progression will occur.
No automatic progression can occur out of the :ref:`Suppress <apfteq_suppress>`,
:ref:`Passive <apfteq_passive>`, or :ref:`Manual <apfteq_manual>` modes. The
chain of progression is as follows; each start time and end time is exposed
as a discrete keyword.

   ===============================      ============    ============
   Mode                                 Start time      End time
   ===============================      ============    ============
   :ref:`Morning <apfteq_morning>`      ``SUNRISE``     ``NOON``
   :ref:`Day <apfteq_day>`              ``NOON``        ``SUNSET``
   :ref:`Evening <apfteq_evening>`      ``SUNSET``      ``TWILIGHT``
   :ref:`Night <apfteq_night>`          ``TWILIGHT``    ``SUNRISE``
   ===============================      ============    ============

If at any time the control mode is manually set to another value, an
automatic transition to the "correct" control mode will occur on the
next time boundary. For example, if the control mode is set to :ref:`Night
<apfteq_night>` at 11AM, it will be reset to :ref:`Day <apfteq_day>` at noon.

If the dispatcher restarts while it is anywhere in the chain of progression,
when it first starts it will automatically select the appropriate mode based
on the current time. To use the above example, if the control mode is set to
:ref:`Night <apfteq_night>` at 11AM, upon restarting the dispatcher the control
mode will be reset to :ref:`Morning <apfteq_morning>`. Note that this excludes
the :ref:`Passive <apfteq_passive>`, :ref:`Suppress <apfteq_suppress>`, and
:ref:`Manual <apfteq_manual>` modes, which will persist across restarts of the
dispatcher.



.. _apfteq_reset:

Assisted reset of control mode
------------------------------

Setting the control mode keyword to Reset will immediately trigger a
calculation of the correct diurnal control mode, regardless of the previous
control mode. This is a convenient way to restore the apfteq dispatcher
to a nominal operating condition after manual manipulation of the control
mode.



.. _apfteq_passive:

Control mode: Passive
---------------------

The Passive prevents apfteq from taking any actions in response to changing
conditions. It will continue to check the forecast, but will not automatically
enter any of the other control modes, nor will it actively control any aspect
of the APF.

The Passive mode exists for the convenience of personnel working in the
dome during the day. Care should be taken to reset the control mode to an
appropriate value when restoring the dome to a ready-to-observe state; this
can most easily be done by setting the control mode to :ref:`Reset
<apfteq_reset>`.



.. _apfteq_suppress:

Control mode: Suppress
----------------------

The Suppress mode will turn off the FCUs and the recirculation fans.
apfteq will continue to check the forecast, but will not automatically
enter any of the other control modes. The Suppress mode does not concern
itself with the vent doors or the dome shutters.

The Suppress mode exists for the convenience of personnel working in the
dome during the day. Care should be taken to reset the control mode to an
appropriate value when restoring the dome to a ready-to-observe state; this
can most easily be done by setting the control mode to :ref:`Reset
<apfteq_reset>`.



.. _apfteq_manual:

Control mode: Manual
--------------------

The Manual mode will turn on the FCUs and the recirculation fans.
The Manual mode does not enforce a vent door state.

When, and only when, in the Manual mode, direct modification of the ``TARGET``
keyword is permitted. apfteq will ensure that the FCU setpoints are set to
the target value. The Manual mode is thus a convenient way to drive the dome
interior to a manually-selected target temperature for an extended duration
of time.



.. _apfteq_morning:

Control mode: Morning
---------------------

apfteq transitions automatically to the Morning mode at sunrise.
The Morning mode will turn on the FCUs and the recirculation fans.
The Morning mode does not enforce a vent door state.

When transitioning to the Morning mode, apfteq will query the keyword history
database for the ``eosti8k.TAVERAGE`` keyword (average telescope strut
temperature) and calculate an average temperature for all the intervals during
which science exposures were taken the previous night. The resulting value will
be reported in the ``TARGET`` keyword. If the keyword history lookup fails, or
contains no data, the last available ``TARGET`` value will be used; in normal
operation, this will be the last ``TARGET`` value from the :ref:`Night
<apfteq_night>` mode.

The Morning control mode is intended to benefit post-observing calibrations,
which typically want to run under the same conditions as the previous night's
observing. Once those calibrations are complete, it is beneficial to manually
set the control mode to :ref:`Day <apfteq_day>`, so that apfteq can begin
controlling the dome to the forecast temperature for the beginning of the next
night's observing.



.. _apfteq_day:

Control mode: Day
-----------------

apfteq transitions automatically to the Day mode at noon.
The Day mode will turn on the FCUs and the recirculation fans.
The Day mode does not enforce a vent door state.

On an hourly basis, regardless of the control mode, apfteq will query the
National Weather Service for the weather forecast for the beginning of the next
night, the precise time for which is exposed by the ``TWILIGHT`` keyword. The
forecast is not so precise: an hourly forecast is used, and the hour immediately
*after* the ``TWILIGHT`` value will be used as the forecast of interest. The
actual forecast is exposed as the ``FORECAST_RAW`` keyword; the forecast used
in the Day mode is exposed as the ``FORECAST`` keyword, which has an arbitrary
offset applied to correct for systematic errors in the raw forecast.



.. _apfteq_evening:

Control mode: Evening
---------------------

apfteq transitions automatically to the Evening mode at sunset.
The Evening mode will open the vent doors, and will turn on the
recirculation fans. If any of the vent doors are open, the FCUs
will be turned off; if they are all closed, the FCUs will be turned
on. The state of the recirculation fans and FCUs will be enforced
every time a vent door opens or closes.

The target temperature for the Evening mode will closely track the exterior
dome temperature, as reported by the ``eosmets.AIRTEMP`` keyword. As with
the other modes, the target temperature is reported in the ``TARGET`` keyword.



.. _apfteq_night:

Control mode: Night
-------------------

apfteq transitions automatically to the Night mode at twelve-degree twilight.
The Night mode will close the vent doors. If the dome shutter
is open, the Night mode will turn off both the FCUs and the recirculation fans;
if the dome shutters close, the FCUs and recirculation fans will be turned
back on. The state of the recirculation fans and FCUs will be enforced
every time the dome shutter opens or closes.

The target temperature for the Night mode will closely track the exterior
dome temperature, as reported by the ``eosmets.AIRTEMP`` keyword. As with
the other modes, the target temperature is reported in the ``TARGET`` keyword.



.. _apfteq_recommended:

Recommended usage
-----------------

The default behavior of apfteq is intended to be reasonable for most
observing situations, but it can be optimized by careful adjustment
from a master observing script. The basic idea is that a master script
best knows when it is done with a particular phase, and can manually
advance apfteq's diurnal progression sequence to suit its own needs.
The other thing to remember it takes a long time for the dome interior
to reach perfect equilibrium: there are significant thermal shorts
between the telescope structure, primary mirror, and the telescope
pier; though the thermal shorts between the Levy spectrometer and the
telescope structure have been significantly reduced, they do still
exist.

When beginning a night's observations, a master observing script should
correct the following conditions, or at least issue a stern warning::

        $apfteq.MODE != Night
        $apfteq.PROGRESSION != Automatic

Observations should not be conducted in any apfteq mode other than
:ref:`Night <apfteq_night>`, as it closes the vent doors, and ensures
the dome interior continues to track exterior condidtions even if the
dome is fully closed. While it may be reasonable to have the vent doors
open if there is no wind, as it could increase the likelihood that the
dome interior remains in equilibrium with the dome exterior, any
measurable amount of wind will degrade the overall tracking stability
of the APF telescope.

The :ref:`Morning <apfteq_morning>` mode exists for the benefit of
post-observing calibrations, and should be entered as soon as observations
are complete for a given night. Ideally, the master script would allow
a discrete amount of time for the average telescope strut temperature
to reach the target value before beginning calibrations. For example,
the following :class:`ktl.Expression` may be appropriate::

        $apfteq.TARGET - $eosti8k.TAVERAGE < 1 and $apfteq.TARGET - $eosti8k.TAVERAGE > -1

If the average telescope temperature is already above the target temperature
and continues to rise, calibrations should instead begin immediately. The
chiller that provides cooling to the APF dome has limited capacity, and there
are no shortage of conditions where it is unable to drive down the temperature
of the dome interior.

When morning calibrations are complete, the mode should be immediately set to
:ref:`Day <apfteq_day>`, to allow the maximum amount of time for the dome
interior to reach the target temperature for the subsequent night's observing.