.. _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 `, :ref:`Passive `, or :ref:`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 ` ``SUNRISE`` ``NOON`` :ref:`Day ` ``NOON`` ``SUNSET`` :ref:`Evening ` ``SUNSET`` ``TWILIGHT`` :ref:`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 ` at 11AM, it will be reset to :ref:`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 ` at 11AM, upon restarting the dispatcher the control mode will be reset to :ref:`Morning `. Note that this excludes the :ref:`Passive `, :ref:`Suppress `, and :ref:`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_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_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 ` 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 `, 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 `, 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 ` 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 `, to allow the maximum amount of time for the dome interior to reach the target temperature for the subsequent night's observing.