The dome shadow program - Implementation
Introduction
The dome shadow program is a utility program to calculate whether
the sun shines on any part of the dish/telescope structure at the
current telescope position at the present time, whether the sun
would shine on the dish if you slewed the telescope to a certain
new position to be input by the user, or whether the sun would
shine on the dish if you slewed to an observer specified position
at an observer specified time.
It facilitates carrying out daytime observing without getting the
sun on any part of the telescope (usually the back of the secondary
mirror assembly).
However, there is no control of either the dome shutters or the antenna.
The only communication with the antenna computer is in reading
the time and telescope position out of it.
The shadow program can of course also be used to determine how far the
shutters can be opened at any particular azimuth/zenith angle the
telescope is pointed during the day. Using the AZ coordinate system
it allows to determine whether the sun would shine on the telescope
if you open the dome to a certain percentage. It can be assumed that
the numbers output here are conservative. Both in real life and in the
program the shutter opening percentages are dependent on not only the
position of the Sun but also (which is not obvious to most people)
quite critically on the zenith angle position of the telescope.
This document is intended for users who want to know ``how it actually
works'' and for the programmer who has to maintain it.
Constraints
The dome shadow program will not work
when the antenna computer is not running.
It will throw you out when the sun sets (or when it thinks the sun sets).
To ensure some level of accuracy it is necessary that the time in the
VAX is fairly accurate (close to the time in the antenna computer).
It is known that the percentage dome open is on the conservative
side (but it is also known that the percentages read out by the gauge
are not always all too meaningful - this is why the opening angle is also
given in the output: negative angles are to the back side of vertical,
positive angles are to the front).
Also, it has not been implemented to check whether the dome could be open
further than is necessary for the telescope to be fully illuminated by the
source to be observed. The percentage dome open is determined from the source
position only.
Implementation
The dome shadow program is written in FORTRAN. It uses some ephemeris routines
from Perry McGehee that are written in C and some routines to communicate with
the antenna computer from the UIP that are of course in PASCAL. The subroutine
object code is kept in an object library (including the ephemeris routines, but
not the main program). The DCL command procedure SHADOW_LINK.COM is provided for
relinking with other necessary object libraries (like the UIP.OLB) as well. (I
hate having to figure out how to relink somebody else's programs and I don't
blame anybody else who does too ...).
The dome shadow program itself consists of a main program that is
fairly messy (but there are reasons for that), and subroutines
- SHADOW_AST and SHADOW_CONTROL_C -
are for interrupting the tracking
loop without interrupting the program.
- SHADOW_CHECK_POS - obsolete?
- SHADOW_COMMAND -
lists the available commands to the screen and prompts for command entry. This
part has been taken out of the main program for readability.
- SHADOW_COORD - changes the coordinate system you're
working in. Otherwise undocumented feature mainly implemented for test
purposes: SHADOW_COORD will accept 'Q' as valid input and quit the program,
just like typing 'Q' at the command prompt.
- SHADOW_DAY_OF_YEAR - calculates the day of year
from the date
- SHADOW_DOMEAZ -
to check the separation on the sky between the sun and the source in azimuth
(only used for slewing)
- SHADOW_DOMEZA - obsolete?
- SHADOW_GET_LST - reads the local siderial time out of
the antenna computer
- SHADOW_GET_TEL - reads the current telescope position out
of the antenna computer
- SHADOW_SHUTTER_MAX - uses the outputs of
SHADOW_SHUTTER_BACK,
SHADOW_SHUTTER_FRONT,
SHADOW_SHUTTER_SEC and
SHADOW_SHUTTER_TEEPEE
to determine which of these is the smallest and most constraining of the
numbers.
- SHADOW_SHUTTER_BACK - determines how far the shutters
have to be closed for the sun not to shine on the back/top of the dish
- SHADOW_SHUTTER_FRONT - determines how far the shutters
have to be closed for the sun not to shine on the front/bottom of the dish
- SHADOW_SHUTTER_SEC - determines how far the shutters
have to be closed for the sun not to shine on any part of the secondary
mirror assembly
- SHADOW_SHUTTER_TEEPEE - determines how far the shutters
have to be closed for the sun not to shine on the teepee
- SHADOW_SHUTTER_MIN - determines how far the shutter
has to be open for the telescope to not be vignetted for the current
(or specified other) position
- SHADOW_SHUTTER_TEXAS_MIN - determines how far the shutter
has to be open for the telescope to not be vignetted for the current
(or specified other) position when using the Texas focal plane reducer.
- SHADOW_SOURCE - for inputting source coordinates
- SHADOW_TIME -0 for specifying a time for which to
calculate these items
There is a bug in EPHEM.C with the following effect: to get the right
LST one has to add 2 to the modified Julian date, but one has to add
1 to get the right line out of the ephemeris.
Another bug in EPHEM.C dealing with -0 degrees (in declination) was fixed
in 1992.
The projected zenith angle
The first implementation of SHADOW dealt with the problem of having a
rectangular opening (with dimensions in linear units) in polar
coordinates in a somewhat cryptic way that can still be found in the now
obsolete SHADOW_CHECK_POS and SHADOW_DOMEZA routines (which I have left
for this reason).
Thinking through the geometry of the problem some more lead to the
introduction of the projected zenith angle (of the Sun).
It seems like the concept of the 'projected zenith angle' is a much
simpler way of dealing with this problem - in spite of the fact that
it in itself is somewhat hard to explain.
The 'projected zenith angle' is defined as the component of the Sun's
zenith angle that is parallel with the telescope's line of sight (at
this point in time), i.e. if telescope and Sun are opposite directions,
it is the negative zenith angle, at right angles it is zero and if the
telescope points closer towards the Sun than 90 degrees it is above
zero, getting to the full value if both are at the same azimuth.
Using the projected zenith angle of the Sun allows calculating the
(projected) zenith angle difference between the telescope and the
Sun (or angular distance of the Sun from the telescope axis) by a
simple subtraction.
Cartesian components of the 'position' of the Sun and the telescope
structure component in question are then calculated, followed by
the intercepts of the line connecting them and the shutter rail's
circle. Depending on whether the Sun is on the front or the back side
of the dome, the front or back intercept is used for the rest of the
calculation, of which the only part left now is to determine which
part of the telescope structure the Sun would shine on first, a simple
minimum taking of the 4 positions calculated.
Main program
The main program, SHADOW, is mainly a large subroutine calling
IF-THEN-ELSE block. Most of the functionality, including user
input and screen output has been put in the subroutines.
Things that one might implement some day
Coordinates have to be typed in, they cannot be input from source
catalogs.
Coordinate systems are limited to altaz and RA/DEC.
Not all input is trapped for input errors.
The program will not warn the user if the antenna computer doesn't
provide ``reasonable'' output, e.g. if it isn't running.
There is no control of the dome shutters or of the telescope to prevent
the observer from pointing close to or into the sun.
back to CSO reference page
------------------------------------------------------------
Maren Purves, Caltech Submm Observatory / maren@poliahu.submm.caltech.edu
Nov. 1, 1996