v09i038: ephem, v4.8, 1 of 5

Brandon S. Allbery - comp.sources.misc allbery at uunet.UU.NET
Tue Nov 28 11:32:19 AEST 1989


Posting-number: Volume 9, Issue 38
Submitted-by: ecd at umn-cs.cs.umn.edu@ncs-med.UUCP (Elwood C. Downey)
Archive-name: ephem2/part01

[Lousy shar.  Sigh.  ++bsa]

Please accept a new release of my interactive astronomical ephemeris, v4.8,
for posting in comp.sources.misc. I am mailing it to you as five shar files,
each under 64k bytes. thank you very much.

Elwood Downey
umn-cs!ncs-med!ecd

-----------------------------------------------------------------------------
# This is a "shell archive" file; run it with sh.
# This is file 1.
echo x Readme
cat > Readme << 'xXx'
1) There is a generic-printer-ready manual in Man.

2) for dos, here is a typical autoexec.bat
set TZ=CDT5
date
time

3) Note the change from ESC to 'q' from V4.6 of ephem.

If you have source:

1) Change the define in io.c depending on whether you wish to compile under
unix or dos turbo/lattice.

2) Try changing the define in time.c if you get link undefines related to time
functions.

3) The following files are pretty much just pure transliterations from BASIC
into C from machine-readable copies of the programs in Duffett-Smith's book.
They have nothing to do with the rest of ephem so they may be used for
completely different applications if so desired.
    aa_hadec.c anomaly.c astro.h cal_mjd.c eq_ecl.c moon.c moonnf.c nutation.c
    obliq.c parallax.c pelement.c plans.c precess.c refract.c riset.c
    sex_dec.c sun.c utc_gst.c

4) I didn't make a Makefile because to make ephem just compile everthing
and link with -ltermcap and -lm, such as
    cc -O -o ephem *.c -ltermcap -lm
xXx
echo x Man
cat > Man << 'xXx'






                                     Ephem V4.8
                                         by
                                   Elwood Downey
                                     Chaska, MN

                                 Table of Contents
      1.  Introduction ...................................................  2
      2.  Sample Screens .................................................  2
      2.1.  Planet Data Screen ...........................................  2
      2.2.  Rise/Set Info Screen .........................................  3
      2.3.  Separation Screen ............................................  4
      3.  Program Operation ..............................................  4
      3.1.  Command Line Format ..........................................  4
      4.  Screen Fields ..................................................  5
      4.1.  Top Screen Fields ............................................  6
      4.2.  Data format columns ..........................................  7
      4.3.  RiseSet format columns .......................................  7
      4.4.  Separation format fields .....................................  8
      5.  Date and Time Formats ..........................................  8
      6.  Configuration File .............................................  8
      6.1.  Configuration file fields ....................................  9
      6.2.  Example ephem.cfg ............................................  9
      7.  Menu options ................................................... 10
      7.1.  Adaptive vs. Standard hzn .................................... 10
      7.2.  Geocentric vs. Topocentric ................................... 10
      8.  Plotting ....................................................... 11
      8.1.  Defining plot fields ......................................... 11
      8.2.  Displaying a plot file ....................................... 12
      8.3.  Cartesian or Polar coords .................................... 12
      8.4.  Begin Plotting ............................................... 12
      8.5.  Stopping Plotting ............................................ 12
      9.  Watching ....................................................... 12
      9.1.  Trails ....................................................... 12
      9.2.  Night sky .................................................... 13
      9.3.  Solar System ................................................. 13
      10.  Searching ..................................................... 13
      10.1.  Find extreme ................................................ 13
      10.2.  Find 0 ...................................................... 14
      10.3.  Binary ...................................................... 14
      10.4.  Define a New function ....................................... 14
      10.4.1.  Intrinsic functions ....................................... 14
      10.4.2.  Field Specifiers .......................................... 14
      10.4.3.  Constants ................................................. 15
      10.4.4.  Operators ................................................. 15
      10.5.  Specifying Search Accuracy .................................. 16
      10.6.  Stop ........................................................ 16
      10.7.  Example Searches ............................................ 16
      10.8.  Another Example ............................................. 17
      10.9.  Caution ..................................................... 17
      11.  Implementation Notes .......................................... 17
      11.1.  Program limits .............................................. 18
      12.  DOS Installation Procedure .................................... 18
      12.1.  Details ..................................................... 19
      13.  Wish List ..................................................... 20









                                       - 2 -


     1.  Introduction

     Ephem is a program that displays observing circumstances for all the
     planets plus any one additional fixed object.

     Information displayed about each object includes RA and Dec precessed to
     any epoch, heliocentric coordinates, local azimuth and altitude, distance
     from sun and earth, solar elongation, angular size, visual magnitude,
     phase, local rise, transit and set times, length of time up, and
     topocentric or geocentric angular separations between all combinations of
     objects.

     Observing circumstance information includes UTC and local date and time,
     local sidereal time, times of astronomical twilight, length of day and
     night, local temperature, pressure and height above sea level and a
     monthly calendar.

     RA/Dec calculations are geocentric and include the effects of precession,
     nutation and aberration.  Alt/az and rise/set/transit and, optionally,
     angular separation calculations are topocentric and include effects of
     refraction and parallax.

     A running plot file of selected field values may be generated as the
     program runs.  Ephem includes a very crude quick-look capability to view
     these plot files or they may be plotted by other programs.  One may also
     watch the night sky or the solar system with a simple screen-oriented
     display.

     Ephem may be asked to search for interesting conditions automatically,
     using several algorithms. Most fields displayed on the screen may be used
     as terms in an arbitrary arithmetic expression that can be solved for zero
     or minimized or maximized, or the time of state change of any boolean
     expression can be found.

     The program is written in C for unix or DOS. It uses only a very simple
     set of io routines and should be easily ported to any ASCII display.  The
     DOS version requires the ANSI.SYS screen driver.

     The planetary data and correction algorithms are taken, with permission,
     from "Astronomy With Your Personal Computer", by Peter Duffett-Smith,
     Cambridge University Press, 1985.

     2.  Sample Screens

     Here are typical ephem screens. They are generated using the sample
     ephem.cfg file (listed in a later section).

     2.1.  Planet Data Screen















                                       - 3 -


     Move to another field, RETURN to change this field, ? for help, or q to run

     CDT  8:10:20 10/31/1989 | LST    9:34:47 | Lat   44:50:37 |     October 1989
     UTC 13:10:20 10/31/1989 |                | Long  93:42:08 | Su Mo Tu We Th Fr Sa
     JulianDat 2447831.04884 | Dawn      6:13 | Elev    800 ft |  1  2  3  4  5  6  7
                             | Dusk     19:43 | Temp      40 F |  8  9 10 11 12 13 FM
     Watch                   | NiteLn   10:31 | AtmPr 29.50 in | 15 16 17 18 19 20 21
     Search              off |                | TZ     5:00:00 | 22 23 24 25 26 27 28
     Plot                off | NStep        1 | Epoch (OfDate) | NM 30 31
     Menu        Planet Data | StpSz RT CLOCK |                |
     --------------------------------------------------------------------------------
     Ob R.A.    Dec    Az     Alt    Helio  Helio  Ea Dst Sn Dst Elong  Size VMag Phs
        Hr:Mn.d Deg:Mn Deg E  Deg Up Long   Lat    AU(mi) AU     Deg E  ArcS      %
     Su 14:22.9 -14:13 112:39   2:31  38:06   0:00 0.9927 0.0000    0.0 1933  -27
     Mo 15:41.8 -24:46 106:59 -19:13               251296 0.9901   21.3 1773   -8  12
     Me 13:59.4 -10:59 114:48   8:33 195:48   3:46 1.3809 0.4108   -6.6  4.9 -1.6  98
     Ve 17:37.4 -26:43  89:49 -39:47  -8:53  -3:23 0.7287 0.7271   46.9 23.2 -5.1  53
     Ma 13:43.1 -10:05 117:19  11:49 201:05   0:53 2.5823 1.6168  -10.6  3.6  1.6 100
     Ju  6:47.2  22:46 251:12  49:26  90:57  -0:13 4.5980 5.1287 -117.2 42.8 -2.5  99
     Sa 18:40.3 -22:44  72:49 -48:14 284:16   0:24 10.471 10.030   61.2 15.8  1.2 100
     Ur 18:10.6 -23:41  80:20 -43:45 274:49  -0:17 19.931 19.369   54.3  3.3  5.7 100
     Ne 18:43.5 -22:12  71:28 -48:24 281:43   0:53 30.666 30.212   62.0  2.0  8.0 100
     Pl 15:06.9  -1:47  96:11   3:53 225:01  15:38 30.607 29.656   16.5  0.3 13.8 100
     Or  6:00.0   0:00 242:37  24:51                             -124.5


     2.2.  Rise/Set Info Screen

     This was done using the Adaptive option.

     Move to another field, RETURN to change this field, ? for help, or q to run

     CDT  8:10:20 10/31/1989 | LST    9:34:47 | Lat   44:50:37 |     October 1989
     UTC 13:10:20 10/31/1989 |                | Long  93:42:08 | Su Mo Tu We Th Fr Sa
     JulianDat 2447831.04884 | Dawn      6:13 | Elev    800 ft |  1  2  3  4  5  6  7
                             | Dusk     19:43 | Temp      40 F |  8  9 10 11 12 13 FM
     Watch                   | NiteLn   10:31 | AtmPr 29.50 in | 15 16 17 18 19 20 21
     Search              off |                | TZ     5:00:00 | 22 23 24 25 26 27 28
     Plot                off | NStep        1 | Epoch (OfDate) | NM 30 31
     Menu      Rise/Set Info | StpSz RT CLOCK |                |
     --------------------------------------------------------------------------------
     Ob            Rise               Transit                Set            Hrs Up
               Time     Az          Time     Alt         Time     Az
     Su        7:51   109:07       12:58    30:55       18:06   250:41      10:15
     Mo       10:09   126:04       14:30    18:57       18:46   232:37       8:37
     Me        7:15   104:44       12:35    34:04       17:55   254:50      10:40
     Ve       12:08   128:21       16:13    18:28       20:19   231:37       8:11
     Ma        6:55   103:28       12:18    35:03       17:41   256:23      10:47
     Ju       21:37    55:59        5:23    67:55       13:06   304:01      15:29
     Sa       12:48   122:05       17:14    22:28       21:40   237:55       8:52
     Ur       12:24   123:34       16:45    21:31       21:06   236:27       8:42
     Ne       12:49   121:16       17:18    23:00       21:46   238:44       8:57
     Pl        7:45    91:43       13:42    43:24       19:38   268:16      11:53
     Or       22:29    89:13        4:36    45:10       10:40   270:47      12:11









                                       - 4 -


     2.3.  Separation Screen

     This was done using the Geocentric option.

     Move to another field, RETURN to change this field, ? for help, or q to run

     CDT  8:10:20 10/31/1989 | LST    9:34:47 | Lat   44:50:37 |     October 1989
     UTC 13:10:20 10/31/1989 |                | Long  93:42:08 | Su Mo Tu We Th Fr Sa
     JulianDat 2447831.04884 | Dawn      6:13 | Elev    800 ft |  1  2  3  4  5  6  7
                             | Dusk     19:43 | Temp      40 F |  8  9 10 11 12 13 FM
     Watch                   | NiteLn   10:31 | AtmPr 29.50 in | 15 16 17 18 19 20 21
     Search              off |                | TZ     5:00:00 | 22 23 24 25 26 27 28
     Plot                off | NStep        1 | Epoch (OfDate) | NM 30 31
     Menu        Separations | StpSz RT CLOCK |                |
     --------------------------------------------------------------------------------
     Ob   Sun   Moon   Merc   Venus  Mars    Jup  Saturn Uranus   Nep   Pluto

     Su         21:21   6:34  46:57  10:34 117:14  61:11  54:20  61:58  16:31
     Mo  21:21         27:54  26:03  31:47 137:45  40:43  33:50  41:32  24:29
     Me   6:34  27:54         53:30   4:07 110:45  67:40  60:50  68:25  19:07
     Ve  46:57  26:03  53:30         57:31 163:41  14:49   8:06  15:41  43:52
     Ma  10:34  31:47   4:07  57:31        106:40  71:45  64:54  72:31  22:25
     Ju 117:14 137:45 110:45 163:41 106:40        178:25 171:33 178:58 122:40
     Sa  61:11  40:43  67:40  14:49  71:45 178:25          6:53   0:55  55:47
     Ur  54:20  33:50  60:50   8:06  64:54 171:33   6:53          7:42  49:32
     Ne  61:58  41:32  68:25  15:41  72:31 178:58   0:55   7:42         56:22
     Pl  16:31  24:29  19:07  43:52  22:25 122:40  55:47  49:32  56:22
     Or 124:29 138:25 119:15 152:44 115:20  25:30 155:15 156:10 155:25 136:42


     3.  Program Operation


     3.1.  Command Line Format

     To run ephem, just type "ephem".  You may also optionally specify an
     alternate configuration file, and optionally specify values for several
     screen fields.  The command line syntax can be summarized as follows:

         ephem [-c <configfile>] [field=value] ...

     When ephem starts, it first displays a disclaimer banner.  Then, after any
     key is pressed, it reads a configuration file to set the initial values of
     several fields.  The default filename is ephem.cfg or .ephemrc in the HOME
     environment variable directory if available.  The exact format of the file
     is described below.  Then it processes any additional command line
     arguments exactly as it would if they too came from the configuration
     file.  It then draws all fields on the screen with their initial values.
     The program then loops advancing time each step, by some amount you may
     control, and updating all fields each loop.

     There are two fields that control this looping behavior: NStep and StpSz.
     These control the number of steps and the amount of time to add each step,
     respectively. When the number of steps, NStep, goes to 0 or any key is









                                       - 5 -


     pressed, the looping stops and you enter a command mode.

     Command mode allows you to modify most of the fields.  The idea is that
     you move to each field on the screen you wish to change and change it.
     When you have changed everything you want to, type "q" to resume screen
     updates.

     To change a field:

         1) move the cursor to the field (see below);
         2) type RETURN;
         3) type in the new value along the command line at the top according
            to the format indicated in the prompt. To accept the new value
            type RETURN, or to leave it unchanged after all type "q".


     A few fields don't require you to type anything; just typing RETURN does
     all the work.  If you can't move to it, you can't change it.

     The arrow keys on most systems move the cursor around.  If these do not
     function or function incorrectly, the h/j/k/l keys also move the cursor
     left/down/up/right, respectively.  You may also move the cursor
     immediately to one of the planet rows by typing one of SMevmjsunp (to
     avoid conflict with j, jupiter's row must actually be typed as control-j).

     When you have changed a field that would invalidate any of the other
     fields the message NEW CIRCUMSTANCES appears in the top center of the
     screen.  This will remain until you type "q" to allow at least one screen
     update loop to occur.  If you change any field that causes new
     circumstances, the StpSz value is not added to the first loop.  Note also
     that after a series of loops, NStep is automatically reset to 1 so "q"
     will do exactly one loop and return you to command mode.

     To quit the program, type control-d from command mode.  For a little more
     help, type ?.  The entire screen may be erased and redrawn with control-l.

     4.  Screen Fields

     The screen is divided into two halves, top and bottom.  The top fields are
     always present. They define the general observing circumstances and
     control features.

     The planets and one additional object are displayed in a table in the
     bottom portion of the screen.  There is one object per row, and several
     columns.  There are three forms of this portion selected by picking the
     Menu selection.

     Some things may be turned off to reduce compute times.  Calculations for
     each planet may be turned on and off by selecting the planet name field.
     Calculations for Dawn/Dusk/NiteLn may be turned off by selecting any of
     these fields.  Planet positions are only updated as often as necessary to
     match the display precision of the screen unless plotting or searching is
     on, in which case full precision is required at all times and so positions
     are always fully recalculated at each iteration.









                                       - 6 -


     Follows is a list and description of each of the fields in each section.
     Following each name, in parentheses, might be a "c" to mean the field may
     be picked to be changed or a "p" to mean the field may be picked to be
     included in a plot (see below).


     4.1.  Top Screen Fields

     LT(c)         the local timezone name, time and date.  The name field may
                   be changed to any three-character mnemonic.  Local time and
                   date may be changed as described in a later section.  set to
                   "N" to set from computer clock.
     UTC(cp)       universally coordinated time and date. set to "N" to set
                   from computer clock.
     JulianDat(cp) the current Julian date, to about 1-second accuracy.
     LST(cp)       the current local sidereal time.  set to "N" to set from
                   computer clock.
     TZ(cp)        hours local time is behind utc, ie, >0 west, <0 east of
                   Greenwich.  set to "N" to set from computer clock.
     Lat(cp)       location latitude, positive degrees north of equator.
     Long(cp)      location longitude, positive degrees west of Greenwich
                   meridian.
     Temp(cp)      local surface air temperature, in degrees F.
     AtmPr(cp)     local surface air pressure, in inches of mercury.
     Epoch(c)      the precession epoch, to nearest 0.1 years.  This says
                   (OfDate) when coordinates are not precessed, ie, are in the
                   epoch of date.
     NStep(c)      The number of times the display with be updated (time
                   advanced by StpSz each step) before entering command mode.
     StpSz(c)      the amount of time UTC (and its derivatives) is incremented
                   each loop.  set this to RTC to use real-time based on the
                   computer clock.  you may also set it in terms of days by
                   appending a D (or d) after the number when you set it.
     Elev(cp)      local elevation of the ground above sea level, in feet.
     Dawn(cp)      local time when the sun is about 18 degrees below the
                   horizon before sunrise
     Dusk(cp)      local time when the sun is about 18 degrees below the
                   horizon after sunset
     NiteLn(cp)    length of astronomical night, ie, Dawn - Dusk.
     Plot(c)       controls plotting; see complete discussion below.
     Watch         selects the sky or solar system displays; see complete
                   discussion below.
     Menu          The three picks after this field select the format of the
                   lower half of the screen.  See their complete discussion
                   below.
     Search        controls the automatic search feature of ephem. See the
                   complete discussion below.
     Also in the upper right of the screen is a calendar for the current local
     month.  Dates of new and full moons are marked NM and FM, respectively.
     One object may also be added to the display by putting its name and
     location in the bottom row of the screen. This is done by moving the
     cursor to the bottom row (the row beneath Pluto) and selecting the field
     under the Ob, R.A., and Dec columns.










                                       - 7 -


     4.2.  Data format columns
     Ob            name of object.
     R.A.(p)       right ascension of object, precessed to given epoch, in
                   Hours, minutes and decimal minutes.
     Dec(p)        declination of object, precessed to given epoch, in degrees
                   and minutes.
     Az(p)         degrees eastward of true north for object.
     Alt(p)        degrees up from a horizontal plane Elev feet above sea
                   level.
     Helio         heliocentric longitude. the earth's is displayed on the
                   Sun's line.
     Helio         heliocentric latitude.
     Ea Dst(p)     distance from earth center to object center, in AU, except
                   distance to moon is in miles.
     Sn Dst(p)     distance from sun center to object center, in AU.
     Elong(p)      spherical angular separation between sun and given object,
                   calculated from the their geocentric ecliptic coordinates.
                   Note this is not just difference in ecliptic longitude. The
                   sign, however, is simply sign(obj's longitude - sun's
                   longitude), ie, degrees east.  thus, a positive elongation
                   means the object rises after the sun.
     Size(p)       angular size of object, in arc seconds.
     VMag(p)       visual magnitude of object.
     Phs(p)        percent of visible surface in sunlight, ie, the phase. Note
                   the moon phase is calculated simplistically as just
                   abs(elongation)/180*100 which can be a few degrees off...
                   this means that because of how elongation is defined it
                   doesn't say 0 during new moon (or 100 during full) except
                   during close eclipses (maybe that's a "feature"?).

     4.3.  RiseSet format columns
     Rise        The local time and azimuth when the upper limb of the object
                 rises.
     Transit     The local time and altitude when the object crosses the
                 meridian, ie, when its azimuth is true south or, if no
                 precession, when the local sidereal time equals the object's
                 right ascension.
     Set         The local time and azimuth when the upper limb of the object
                 sets.
     Hrs Up      The number of hours the object is up on the local date.

     Horizon displacement may be calculated in either of two ways; see the
     horizon discussion in the Menu selection section.

     Various oddball conditions are accounted for, such as an object that is up
     sometime during the day but that doesn't rise, transit or set as such on
     that day, an object that is circumpolar or that is never up or one that
     rises twice on the same day.  These are marked as "Never rises", "Never
     transits", "Never sets", "Circumpolar", "Never up" or appended with a plus
     "+" sign, respectively.













                                       - 8 -


     4.4.  Separation format fields
     This format is a table of angular separations between each pair of
     objects.  These angles are based on the local altitude/azimuth, and so in
     general differ somewhat from the elongations reported for the sun in the
     Data menu.

     5.  Date and Time Formats
     Times are displayed and entered in h:m:s format.  If you pick a time field
     to change it any of the h, m, and s components that are not specified are
     left unchanged from their current value.  For example, 0:5:0 set hours to
     0, minutes to 5, seconds to 0, whereas :5 sets minutes to 5 but leaves
     hours and seconds unchanged.  A negative time is indicated by a minus sign
     (-) anywhere before the first digit.

     Dates are displayed and entered in American m:d:y format.  As with time,
     components omitted when entering a new value remain the current value.
     For example, if the current date is 10/20/1988 and you type 20/20 the new
     date will become 20/20/1988. Note you must type the full year since the
     program is accurate over several centuries either side of 1900.

     As a matter of typing convenience, the program accepts any character other
     than a digit or minus as the separator; you don't have to type a perfect
     ":" or "/".

     6.  Configuration File
     The ephem.cfg configuration file allows you to set the initial values of
     many of the screen fields. You can still change any field while the
     program is running too; this file just sets the initial conditions.  Note
     that the order of entries in this file is important.  They each take
     effect immediately and so you should put them in the same order you wish
     them to be processed, just as though you were changing the fields
     interactively within ephem.

     You can have several different configuration files if you wish. By
     default, ephem looks for one named ephem.cfg. You can tell it to use an
     alternate file by using the -c switch as follows:

         ephem -c <filespec>


     If your system supports the HOME environment variable then ephem also
     looks for a configuration file there with the name

     The format of the file uses the form KEYWORD=VALUE, where the possible
     KEYWORDS and the types of VALUES for each are described below. Any
     KEYWORDS not in the file will take on some sort of default. The separator
     need not be an actual equals sign; any char will do because the VALUE is
     assumed to start one character after the KEYWORD, regardless.

     Note:  because of the way unspecified time and date components are left
     unchanged (see section on Date and Time Formats) always specify the
     complete time and date for all entries in the configuration file. For
     example, to initialize the longitude to zero degrees, say 0:0:0, not just
     0.









                                       - 9 -


     6.1.  Configuration file fields
     UD        initial UTC date, such as 10/20/1988, or "NOW" to use the
               computer clock.
     TZONE     hours the local time is behind utc, such as 5:0:0.  you need not
               set this if you use "NOW" for UT or UD.
     TZNAME    name of the local time zone, such as CDT. 3 chars max.  you need
               not set this if you use "NOW" for UT or UD.
     LONG      longitude, in degrees west of greenwich, in the form d:m:s.
     LAT       latitude, in degrees north of the equator, in the form d:m:s.
     HEIGHT    height above sea level, in feet, such as 800
     TEMP      air temperature, in degrees F, such as 50
     PRES      air pressure, in inches of Mercury, such as 29
     STPSZ     the time increment between screen updates, such as "1" to give
               one hour updates. this can be a specific amount or RTC to use
               the system clock as a real-time source. You may also specify a
               time in days, by appending a D (or d) after the number.
     PROPTS    this selects what you want included initially in the display.
               since IBM-PC math is not very fast, you can reduce the time to
               update the screen by only printing those fields of interest. the
               VALUE is a collection of letters to turn on each item from the
               following set:

                       T       twilight (dawn-dusk)
                       S       circumstances for the sun
                       M       circumstances for the moon
                       e       circumstances for mercury
                       v       circumstances for venus
                       m       circumstances for mars
                       j       circumstances for jupiter
                       s       circumstances for saturn
                       u       circumstances for uranus
                       n       circumstances for neptune
                       p       circumstances for pluto

               For example, to just track the sun and saturn, say PROPTS Ss
     NSTEP     number of times program will loop before entering command mode.
               see the discussion under Program Operation.
     EPOCH     this sets the desired ra/dec precession epoch. you can put any
               date here or EOD to use the current instant ("Epoch of Date").
     OBJN      name of the extra object to track.
     OBJRA     right ascension of the extra object to track.
     OBJDEC    declination of the extra object to track.

     6.2.  Example ephem.cfg

     This is the ephem.cfg file that was in effect when the sample screens (in
     an earlier section) were generated. You might run ephem with this
     configuration file and compare with the samples as a check.















                                       - 10 -


     TZONE 5
     TZNAME CDT
     UT 13:10:20
     UD 10/31/1989
     LONG 93:42:8
     LAT 44:50:37
     HEIGHT 800
     TEMP 40
     PRES 29.5
     STPSZ RTC
     PROPTS TSMevmjsunp
     EPOCH EOD
     NSTEP 1
     OBJN Or
     OBJRA 6:0:0
     OBJDEC 0:0:0

     As another common example, this ephem.cfg creates an essentially free-
     running real-time screen based on the computer clock:


     UT NOW
     LONG 90:10:8
     LAT 40:50:20
     HEIGHT 800
     TEMP 50
     PRES 29
     STPSZ RTC
     PROPTS TSMevmjsunp
     NSTEP 9999999
     EPOCH EOD


     7.  Menu options

     When you select "Menu" you can change among the three styles of bottom
     screens. There are also two options that can be set from the Menu quick-
     choice menu. These options toggle when picked and retain their values so
     they need only be changed when desired.

     7.1.  Adaptive vs. Standard hzn

     This selects the horizon refraction displacement algorithm used by the
     Rise/Set menu.  "Adaptive" uses the local conditions known to ephem and
     matches the Planet Info times very nicely. "Standard" uses the "accepted
     nominal" refraction value of 32 arc minutes, and agrees to a minute or two
     with published tables.

     7.2.  Geocentric vs. Topocentric

     This selects the vantage point for the Separation menu. "Geocentric"
     ignores local conditions and gives the separation as seen from Earth
     center. "Topocentric" uses the local conditions known to ephem.  They are
     particularly critical for lunar occultations, but the effect can be









                                       - 11 -


     significant for the planets.

     Note that searching over a period that will include the rise or set times
     of either object is generally better performed from the geocentric
     viewpoint.  The refraction effect of the topocentric viewpoint causes many
     arcminutes of rapid whiplash displacement as the objects rise and set that
     overlays the smooth celestial motion of the objects.  This rapid position
     variation can confuse the solver algorithms that expect fairly smooth
     functions.

     8.  Plotting

     Each time a field is drawn on the screen its full-precision value may be
     written to a file.  This implies you may not plot a field from other than
     the current menu at the time plotting is on.

     Each line in the file consists of a tag character followed by two or three
     floating point variables, all separated by commas. If there are two
     values, they should be interpreted to be x and y (or perhaps r and theta).
     If there is a third, it is a z or trace value.

     For efficiency on systems that can compute a screenfull faster than they
     can display it, screen updates are suppressed while plotting is on and
     NStep is greater than 1. This can greatly reduce the time to generate a
     long plot file. Fields are still logged for plotting; they just are not
     drawn on the screen.

     The Plot field controls plotting.  Whether plotting is currently active is
     indicated by "on" or "off" immediately to its right.

     Picking "Plot" brings up a quick-choice menu, as follows:

     Select: Select fields, Display a plot file, Cartesian coords, Begin plotting


     8.1.  Defining plot fields

     Select the "Select fields" option.  You will be asked to move the cursor
     to the field you want to use as the x coordinate (abscissa), then asked to
     choose the y coordinate (ordinate), then asked to choose an optional z
     trace variable and finally a tag character.  (X and Y may be for other
     coordinate systems too but ephem's quicky plotter can only plot in
     Cartesian coordinates.) If you type q for either x or y then no more
     fields will be defined.  If you type q for the z field there will be no z
     field.  You can not label a plot line with the letter "q" at this time.

     This then repeats so you may choose up to ten of these sets for any given
     plot run.  Each set defines what will become a line on the final plot.
     Note that you may select the "Search" field to indicate use of the current
     search function; that function must be defined by the time plotting is
     turned on.

     If you turn plotting off and back on the fields selected for plotting are
     reactivated the same as they were last time. You may change them if









                                       - 12 -


     desired, of course, but there is no need to redefine them if you do not
     wish to change them.

     8.2.  Displaying a plot file

     Select the "Display a plot file" option to make a crude plot of an
     existing plot file previously created by ephem.  The entries in the file
     will be drawn on the screen using their tag characters; the plot remains
     on the screen until you type any character.

     The plot may be made in polar or Cartesian coordinates, depending on the
     setting of the plotting mode in the quick-choice (see next section).

     8.3.  Cartesian or Polar coords

     This toggles the plotting mode coordinate system.  The mode remains until
     changed.  Polar coordinates assume the first numeric field in the plot
     file is the radius, and the second is the angle counterclockwise from
     right, in degrees.

     8.4.  Begin Plotting

     If there are defined plot field lines then the third option, "Begin
     plotting" will be available.  You will be asked for the name of the file
     to use and, if it already exists, whether to overwrite it or append to it.
     Once you have chosen a file, plotting is on and the top menu plotting
     status field changes to "on".  The default plot filename is ephem.plt.
     The values are written to the plot file each time they are updated on the
     screen until you select "Plot" again and select the "Stop" option to turn
     plotting back off.

     8.5.  Stopping Plotting

     If plotting is on, then selecting the Plot field in the top section will
     turn plotting off. You may pick Plot again and resume with the same fields
     by selecting "Begin plotting" again.

     Note that due to internal buffering the plot file will not be completely
     written to disk until plotting is turned off.

     9.  Watching

     You may make a simple drawing on the screen of the night sky or the solar
     system by selecting "Watch".  It will bring up a quick-choice menu as
     follows:

     Select: Night sky, Solar system, No trails


     9.1.  Trails

     You may either erase after each iteration or leave the tags up, referred
     to as "trails". Picking the right-most choice will toggle between "No
     trails" and "Leave trails"; set it accordingly before you select the style









                                       - 13 -


     of sky plot you wish. Ephem will remember your selection.

     9.2.  Night sky

     This selection draws the currently active planets as they would appear in
     the sky at the current time and date.  The coordinate system is such that
     0 degrees azimuth (north) through 360 degrees (north, once around) is
     mapped to the horizontal screen dimension, and 0 degrees altitude (level)
     through 90 degrees (the zenith) is mapped to the vertical dimension. Thus,
     the bottom row is the horizon and all across the top is the zenith.

     9.3.  Solar System

     This selection draws the currently active planets as they would appear
     looking "down from the top" of the sun.

     In either style of display, pressing RETURN advances the time by whatever
     amount StpSz is set to.  Pressing h advances it by one hour and d advances
     it by one day.  Pressing "q" returns to the tabular main screen. Pressing
     any other key starts an automatic loop with each step advancing by StpSz;
     pressing any key stops the looping.

     10.  Searching

     Ephem can search for arbitrary conditions to exist among most displayed
     fields.  You first enter a function, then select from among three forms of
     equation solvers to iteratively solve for the next time when the function
     meets the requirements of the solver. The solver selects the next time for
     which it wants the function evaluated and sets StpSz so that the next
     iteration will occur at that time. The solvers continue to iterate until
     either they achieve their goal or NStep reaches 0.

     You may set NStep quite large and let ephem search unattended or set it to
     1 and watch it converge one step at a time. You may also plot at the same
     time as search to record the exact steps ephem took to converge.  (But
     recall that screen updates are suppressed if plotting is also on).

     The "Search" selection in the top half of the screen controls all
     searching.  Picking it brings up a quick-choice menu as follows:

     Select: Find extreme, Find 0, Binary, New function, Accuracy


     10.1.  Find extreme

     This search algorithm searches for a local maximum or a minimum in the
     search function, whichever it finds first. It begins by evaluating the
     search function at the current time then for two more times each separated
     by StpSz. It then fits these three points to a parabola and solves it for
     the time of its maximum (or minimum). StpSz is set so that the next
     iteration will evaluate at this point.  This parabolic fit solution keeps
     repeating until StpSz changes by less than the desired accuracy or until
     the curve becomes so flat that an extrema appears too broad to find.










                                       - 14 -


     10.2.  Find 0

     This search algorithm uses the secant method to solve for the time at
     which the search function is zero. The function is evaluated at the
     current time and then again StpSz later to establish a slope for which the
     x-intercept is found as the next zero guess. This is used to set StpSz for
     the next desired time value and the slope hunting process repeats until
     StpSz changes by less than the desired accuracy.

     10.3.  Binary

     This search algorithm must be used with a search function that yields a
     boolean result, ie, a true or false value. The idea is that the function
     is assumed to be one truth value when evaluated at the present time, and
     the opposite truth value when it is evaluated StpSz later. The algorithm
     will then do a binary search for the time at which the truth value
     changes.

     The binary algorithm does not begin until the state change is bounded in
     time.  Initially, as long as the truth value at StpSz is the same as the
     previous value the algorithm will just keep moving in time by StpSz
     looking for when the state changes.  That is, a linear search is initiated
     to bound the state change, then the binary search proceeds.

     10.4.  Define a New function

     Select "New function" to display the current search function.  If you type
     "q" it will be left unchanged.  If you type RETURN it will be erased.  If
     you type anything else it will be compiled and, if there are no errors, it
     will become the new search function.  Once a valid function has been
     stored, it will remain unless changed.  If a search function is selected
     and there is as yet no valid search function defined, you will
     automatically be asked to enter one as though you had selected "New
     function."

     A search function consists of intrinsic functions, field-specifiers,
     constants and operators, and precedence may be overridden with
     parentheses.


     10.4.1.  Intrinsic functions

     In this release, the only intrinsic function available is abs(), which
     returns the absolute value of its argument.

     10.4.2.  Field Specifiers

     A field in the bottom half of the menu is specified in the form of
     "object_name.column_name". The object_name is enough of the planet name to
     be unique, or the exact name of the optional object. The column_name is
     from the following table, depending on which menu is up. In all cases
     additional characters may be entered but are ignored.











                                       - 15 -


     Planet Data Menu        Rise/Set Menu               Separation Menu
     ------------------      --------------------        ---------------
     al      Alt             hr      Hrs Up, or          j       Jup
     az      Az              hu      Hrs Up              ma      Mars
     d       Dec             raz     Rise Az             me      Merc
     ed      Ea Dst          rt      Rise Time           mo      Moon
     el      Elong           saz     Set Az              n       Nep
     hla     Helio Lat       st      Set Time            pl      Pluto
     hlo     Helio Long      ta      Transit Alt         sa      Saturn
     ph      Phs             tt      Transit Time        su      Sun
     ra      R.A.                                        u       Uranus
     sd      Sn Dst                                      ve      Venus
     si      Size
     vm      VMag


     In addition, the following top-half fields may be used:

     da      Dawn
     du      Dusk
     n       NiteLn


     Note that while you may include any field in a search function, it will
     only be calculated if it is actually being displayed.  This implies it is
     useless to define a search that uses fields from other than the one menu,
     namely, the current menu at the time the search is running.

     10.4.3.  Constants

     Constants may be integers or floating point numbers. The latter may be
     expressed in scientific notation if desired. Examples include 100, .9,
     1.234, 1e10 and 1.2e-4.  Any number may be preceded by - to make it
     negative.

     10.4.4.  Operators

     The collection of arithmetic, relational and boolean operators provided
     mimics those of C language as listed in the following table, in decreasing
     order of precedence.  Operators grouped together have the same precedence
     and all have left-to-right associativity. Parentheses may be used as
     desired.





















                                       - 16 -


     Symbol  Meaning                 Resulting type
     ------  --------------------    --------------
     *       multiply                arithmetic
     /       divide                  arithmetic

     +       add                     arithmetic
     -       subtract                arithmetic

     >       greater than            boolean
     >=      greater than or equal   boolean
     <       less than               boolean
     <=      less than or equal      boolean

     ==      equality                boolean
     !=      inequality              boolean

     &&      logical and             boolean

     ||      logical or              boolean


     10.5.  Specifying Search Accuracy

     Selecting "Accuracy" allows you to specify when the search will stop.  The
     search algorithms will stop when StpSz becomes equal to or less than this
     value. The default is one minute.  If ephem has not yet converged to the
     specified accuracy but NStep has decremented to 1, the searching will stop
     but the search status field will still indicate which search procedure is
     in effect. To try more iterations you may increase NStep and resume
     searching. If the accuracy was achieved, the search status field will
     switch to "off" with the number of "unused" steps remaining in NStep and
     the last step size in the StpSz fields.

     10.6.  Stop

     If searching is on, this option will also appear on the quick-choice menu
     and may be selected to turn off the search.

     10.7.  Example Searches

     As an example, let's find when Pluto again becomes the furthest planet
     from Sol.  You may find when the difference in their sun distance is zero,
     or you might use a binary search on the condition that Pluto's sun
     distance is larger then Neptune's.

     To try the former approach select Search, select "Find 0", specify the
     search function to be:

     pl.sd - nep.sd

     set StpSz to something large like 10d, NStep to allow several iterations
     like 20, and then type "q" to start the search and watch ephem do the
     hunt.  Ephem will settle on about 21:02 1/10/1999 UT.










                                       - 17 -


     To try a binary search, you first need to have some idea of when the event
     will occur so you can eliminate the initial linear search for the state
     change. We can start at, say, 1/1/1999, set StpSz to 30d, select Binary
     search, specify the search function to be:

     pl.sd > nep.sd

     and go. Once it brackets the state change note how StpSz keeps being cut
     in half but can go in either direction (sign) as it divides each interval
     in half.  Ephem will converge on the same answer.

     10.8.  Another Example

     To find the time of last quarter moon during December, 1989, use the "Find
     0" search algorithm to solve "moon.el + 90".  (At last quarter, the moon
     is 90 degrees west of the sun, or -90 east in ephem's elongation display.)
     Set the initial time to mid-month, 12/15/1989, StpSz to 1 day and NSteps
     to 10. Ephem takes only a few iterations to settle on 23:57 12/19 UT.

     10.9.  Caution

     Beware that most celestial phenomena are generally pseudo-periodic in
     nature.  In early search steps ephem can easily skip over a local maxima
     and find a later one, which, while correct, may not be what was desired.
     In general, the closer you can be when you start the search the better
     ephem can refine it; it is not as good with very broad searches that can
     go "wild". Set StpSz large enough to offer significant change in the
     function value, but small enough not to skip too far.

     For example, Saturn and Neptune had three close approaches during 1989.
     If you did not know this then just asking ephem to find a minimum would
     have produced different results depending on the starting conditions.
     When starting a search for a certain class of event it is a good idea to
     first use the plotting or watching facility of ephem to get a broad
     picture of the general circumstances then use ephem's search facility to
     refine a given region (or create and inspect a plot file and do your own
     interpolation directly from it separately).

     Similarly, ephem's searching techniques are not good for eclipses because
     the moon and sun are close every month; the trick is sorting through the
     frequent conjunctions for ones that are particularly close. One needs a
     way of establishing an envelope fit to the local extrema of a cyclic
     function in order to find a more global extreme.

     11.  Implementation Notes

     Remember that everything is for the current local time. So, for example,
     the calendar marks moon events in local time; commercial calendars usually
     mark the UT date.  Similarly, the rise/set times are for the current local
     day.

     The program uses a horizontal plane tangent to the earth as the horizon
     for all altitude calculations, rise/set events, etc.  This is not the same
     as the angle up from the local horizon unless the observer is directly on









                                       - 18 -


     the ground due to earth's curvature.  The effect can be found from:

             sin(a)**2 = (h**2 + 2Rh) / (R+h)**2
         where:
             R = radius of earth
             h = height above ground (same units as R)
             a = increase in altitude

     For example, the effect is more than two arc minutes at a height of 5
     feet.

     Visual magnitudes are not very accurate at all... I haven't bother to fix.

     The accuracy of ephem can not be specifically stated since the Duffett-
     Smith book does not warrant its planet position polynomials to any given
     degree. I know for sure that better accuracy could be achieved if ephem
     used ET but I have not yet decided on a suitable UT-ET algorithm.

     The program uses double precision throughout. While this precision might
     seem a little ridiculous, it is actually more efficient for most
     traditional K&R C compilers, the search functions are far more stable, it
     improves small angles (conjunctions) calculated using acos(), etc.

     Searching and plotting always use full precision but if neither of these
     are turned on pure display and watching only recompute a given planets new
     location if the time has changed enough to effect the required display
     precision, based on the planets mean apparent orbital motion.

     A "negative 0" is displayed when a value is negative but less than half
     the display precision.

     The sun-moon distance is the solution for the third side of a planar
     triangle whose two other sides are the earth-moon distance and earth-sun
     distance separated by the angle of elongation.

     11.1.  Program limits

     The search function is limited to a maximum of 32 instructions (each
     constant, field spec, and operation is one instruction), with no more than
     a total of 16 constants and fields specs. At run time, the function can
     not require more than 16 stacked values (due to operator precedence or
     explicit parenthetical expressions) to evaluate.

     No more than 32 fields can be tracked simultaneously for plotting and/or
     searching.

     No more than 10 lines may be plotted at once.

     The maximum file name length is 14 characters.

     12.  DOS Installation Procedure

     Summary:










                                       - 19 -


     You must be running DOS V2.0 or later, though somewhere between V2.0 and
     V3.21 the behavior of control-c to terminate the program was fixed.  A
     8087 floating point chip will be used if present.

     The distribution floppy contains two files, ephem.exe and ephem.cfg.
     Ephem.exe is the executable program; ephem.cfg is a sample configuration
     file. To run the program, make working copies of these two files in a
     directory and run "ephem" from that directory. The program uses the
     ANSI.SYS terminal driver for screen control. It also uses an environment
     variable, TZ, to establish the local timezone.

     12.1.  Details


     1) The ANSI.SYS screen driver is required for this program. Edit the
        CONFIG.SYS file, if necessary, so it contains the following line:
              device=ANSI.SYS

        If it wasn't already there and you had to add it, note it will not
        take effect until you reboot DOS.



     2) Set a DOS environment variable, TZ, in the following form:
              set TZ=SSSnDDD

        "SSS" is the 3-letter abbreviation for the local standard timezone;
        "n"   is a number between -23 to 24 indicating the number of hours
              that are subtracted from GMT to obtain local standard time;
        "DDD" is an optional 3-letter abbreviation for the local daylight
              savings time zone name. Leave it off if you do not have savings
              time in your area or it is not currently in effect. If the
              changeover dates differ from the internal algorithm, just use
              SSS and n directly.


         For example, in the midwestern United States with savings times:
              set TZ=CST6CDT

         If for some reason your system does not change to savings time at the
         right time, then omit the DDD parameter and just set the SSS and n
         to exactly what you want.

         You can put this in your AUTOEXEC.BAT file so it gets set each time
         you boot DOS.

         This environment variable is used to establish the timezone name and
         hours offset whenever the "NOW" shorthand is used from ephem, either
         from the configuration startup file or whenever any time field is
         changed manually.













                                       - 20 -


     3) place the distribution floppy into drive a:.

     4) copy the ephem.* files to a working diskette:
             copy ephem.* b:*.*/v
     or hard disk:
             copy ephem.* c:*.*/v

     5) run using the sample configuration file by just running
             ephem

     To run with a different configuration file, use the -c switch:
             ephem -c <filespec>


     13.  Wish List

     allow specifying the extra object with orbital elements so it could be
     used for earth satellites, comets, etc.

     incorporate ephemeris time, not just UT.








































xXx
echo x astro.h
cat > astro.h << 'xXx'
#ifndef PI
#define	PI		3.141592653589793
#endif

/* conversions among hours (of ra), degrees and radians. */
#define	degrad(x)	((x)*PI/180.)
#define	raddeg(x)	((x)*180./PI)
#define	hrdeg(x)	((x)*15.)
#define	deghr(x)	((x)/15.)
#define	hrrad(x)	degrad(hrdeg(x))
#define	radhr(x)	deghr(raddeg(x))

/* ratio of from synodic (solar) to sidereal (stellar) rate */
#define	SIDRATE		.9972695677

/* manifest names for planets.
 * N.B. must cooincide with usage in pelement.c and plans.c.
 */
#define	MERCURY	0
#define	VENUS	1
#define	MARS	2
#define	JUPITER	3
#define	SATURN	4
#define	URANUS	5
#define	NEPTUNE	6
#define	PLUTO	7
xXx
echo x circum.h
cat > circum.h << 'xXx'
#define	SPD	(24.0*3600.0)	/* seconds per day */

#define	EOD	(-9876)		/* special epoch flag: use epoch of date */
#define	RTC	(-1234)		/* special tminc flag: use rt clock */

#define	STDHZN		0	/* rise/set times based on nominal conditions */
#define	ADPHZN		1	/* rise/set times based on exact current " */
#define	TWILIGHT	2	/* rise/set times for sun 18 degs below hor */

/* info about our local observing circumstances */
typedef struct {
	double n_mjd;	/* modified Julian date, ie, days since
			 * Jan 0.5 1900 (== 12 noon, Dec 30, 1899), utc.
			 * enough precision to get well better than 1 second.
			 */
	double n_lat;	/* latitude, >0 north, rads */
	double n_lng;	/* longitude, >0 east, rads */
	double n_tz;	/* time zone, hrs behind UTC */
	double n_temp;	/* atmospheric temp, degrees C */
	double n_pressure; /* atmospheric pressure, mBar */
	double n_height;	/* height above sea level, earth radii */
	double n_epoch;	/* desired precession display epoch as an mjd, or EOD */
	char n_tznm[4];	/* time zone name; 3 chars or less, always 0 at end */
} Now;
extern double	mjd_day(), mjd_hr();

/* info about where and how we see something in the sky */
typedef struct {
	double s_ra;	/* ra, rads (precessed to n_epoch) */
	double s_dec;	/* dec, rads (precessed to n_epoch) */
	double s_az;	/* azimuth, >0 e of n, rads */
	double s_alt;	/* altitude above topocentric horizon, rads */
	double s_sdist;	/* dist from object to sun, au */
	double s_edist;	/* dist from object to earth, au */
	double s_elong;	/* angular sep between object and sun, >0 if east */
	double s_hlong;	/* heliocentric longitude, rads */
	double s_hlat;	/* heliocentric latitude, rads */
	double s_size;	/* angular size, arc secs */
	double s_phase;	/* phase, % */
	double s_mag;	/* visual magnitude */
} Sky;

/* flags for riset_cir() status */
#define	RS_NORISE	0x001	/* object does not rise as such today */
#define	RS_2RISES	0x002	/* object rises more than once today */
#define	RS_NOSET	0x004	/* object does not set as such today */
#define	RS_2SETS	0x008	/* object sets more than once today */
#define	RS_CIRCUMPOLAR	0x010	/* object stays up all day today */
#define	RS_2TRANS	0x020	/* transits twice in one day */
#define	RS_NEVERUP	0x040	/* object never rises today */
#define	RS_NOTRANS	0x080	/* doesn't transit today */
#define	RS_ERROR	0x100	/* can't figure out times... */

/* shorthands for fields a Now pointer, np */
#define mjd	np->n_mjd
#define lat	np->n_lat
#define lng	np->n_lng
#define tz	np->n_tz
#define temp	np->n_temp
#define pressure np->n_pressure
#define height	np->n_height
#define epoch	np->n_epoch
#define tznm	np->n_tznm
xXx



More information about the Comp.sources.misc mailing list