v15i020: ephem v4.21 manual
dimed1!downey at cs.umn.edu
dimed1!downey at cs.umn.edu
Sat Oct 6 10:16:25 AEST 1990
Posting-number: Volume 15, Issue 20
Submitted-by: dimed1!downey at cs.umn.edu
Archive-name: ephem-4.21/part07
# This is the first line of a "shell archive" file.
# This means it contains several files that can be extracted into
# the current directory when run with the sh shell, as follows:
# sh < this_file_name
# This is file 1.
echo x Man.txt - 142834 characters
sed -e 's/^X//' << 'EOFxEOF' > Man.txt
X
X
X
X
X
X
X Ephem V4.20 - August 21, 1990
X
X Copyright (c) 1990 by Elwood Charles Downey
X Chaska, Minnesota, USA
X
X downey at dimed.com
X
X
X Table of Contents
X 1. Introduction ................................................... 3
X 2. Running Ephem .................................................. 3
X 2.1. Command Line Format .......................................... 3
X 2.2. Program Operation ............................................ 4
X 3. Screen Fields .................................................. 5
X 3.1. Top Screen Fields ............................................ 6
X 3.2. Data format columns .......................................... 7
X 3.3. RiseSet format columns ....................................... 8
X 3.4. Separation format fields ..................................... 8
X 4. Date and Time Formats .......................................... 8
X 5. Configuration File ............................................. 9
X 5.1. Configuration File fields .................................... 9
X 5.2. Example ephem.cfg ............................................ 11
X 6. Menu options ................................................... 11
X 6.1. Adaptive vs. Standard hzn .................................... 11
X 6.2. Geocentric vs. Topocentric ................................... 12
X 7. User Defined Objects: X and Y .................................. 12
X 7.1. Controlling Object-X or Y Operation .......................... 12
X 7.1.1. Fixed ...................................................... 13
X 7.1.2. Elliptical ................................................. 13
X 7.1.3. Parabolic .................................................. 13
X 7.1.4. Lookup ..................................................... 14
X 7.1.5. On or Off .................................................. 14
X 7.2. Magnitude models ............................................. 14
X 7.2.1. g/k model .................................................. 14
X 7.2.2. H/G model .................................................. 15
X 7.3. Database File ................................................ 15
X 8. Plotting ....................................................... 15
X 8.1. Defining plot fields ......................................... 16
X 8.2. Displaying a plot file ....................................... 16
X 8.3. Cartesian or Polar coords .................................... 16
X 8.4. Begin Plotting ............................................... 17
X 8.5. Stopping Plotting ............................................ 17
X 9. Listing ........................................................ 17
X 10. Watching ...................................................... 17
X 10.1. Trails ...................................................... 17
X 10.2. Sky dome .................................................... 18
X 10.3. Alt/az sky .................................................. 18
X 10.4. Solar System ................................................ 18
X 11. Searching ..................................................... 18
X 11.1. Find extreme ................................................ 19
X 11.2. Find 0 ...................................................... 19
X 11.3. Binary ...................................................... 19
X 11.4. Define a New function ....................................... 19
X 11.4.1. Intrinsic functions ....................................... 20
X
X
X
X
X
X
X
X
X
X - 2 -
X
X
X 11.4.2. Field Specifiers .......................................... 20
X 11.4.3. Constants ................................................. 21
X 11.4.4. Operators ................................................. 21
X 11.5. Specifying Search Accuracy .................................. 21
X 11.6. Stop ........................................................ 21
X 11.7. Example Searches ............................................ 22
X 11.8. Another Example ............................................. 22
X 11.9. Caution ..................................................... 22
X 12. Implementation Notes .......................................... 23
X 12.1. Program limits .............................................. 24
X 13. DOS Installation Procedure .................................... 24
X 13.1. Setting TZ .................................................. 24
X 14. Known Bugs and Wish List ...................................... 25
X 15. Sample Screens ................................................ 26
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X - 3 -
X
X
X 1. Introduction
X
X Ephem is a program that displays ephemerides for all the planets plus any
X two additional objects. The additional objects may be fixed or specified
X via heliocentric elliptical or parabolic orbital elements to accommodate
X solar system objects such as comets or asteroids.
X
X Information displayed about each object includes RA and Dec precessed to
X any epoch, heliocentric coordinates, local azimuth and altitude, distance
X from sun and earth, solar elongation, angular size, visual magnitude,
X illumination percentage, local rise, transit and set times, length of time
X up, and topocentric or geocentric angular separations between all
X combinations of objects.
X
X Observing circumstance information includes UTC and local date and time,
X local sidereal time, times of astronomical twilight, length of day and
X night, local temperature, pressure and height above sea level for the
X refraction model and a monthly calendar.
X
X RA/Dec calculations are geocentric and include the effects of light travel
X time, nutation, aberration and precession. Alt/az and rise/set/transit
X and, optionally, angular separation calculations are topocentric and
X include the additional effects of parallax and refraction.
X
X Plot and listing files of selected field values may be generated as the
X program runs. The plot files are full precision floating point values in
X ASCII intended for input to other plotting programs. The listing files
X are tables formatted for general reading. Ephem includes simple quick-
X look facilities to view these files.
X
X One may watch the sky or the solar system with a simple screen-oriented
X display.
X
X Ephem may be asked to search for interesting conditions automatically,
X using several algorithms. Most fields displayed on the screen may be used
X as terms in an arbitrary arithmetic expression that can be solved for zero
X or minimized or maximized, or the time of state change of any boolean
X expression can be found.
X
X The program is written in C for unix or DOS. It uses only a very simple
X set of io routines and should be easily ported to any ASCII display.
X
X The planetary data and correction algorithms are taken, with permission,
X from "Astronomy With Your Personal Computer", by Peter Duffett-Smith,
X Cambridge University Press, 1985.
X
X 2. Running Ephem
X
X
X 2.1. Command Line Format
X
X To run ephem, just type "ephem". You may also specify an alternate
X configuration file, an alternate database file, and specify initial values
X for several screen fields. The command line syntax can be summarized as
X
X
X
X
X
X
X
X
X
X - 4 -
X
X
X follows:
X
X ephem [-c <config_file>] [-d <database_file>] [field=value ...]
X
X
X The default configuration file is named ephem.cfg in the current
X directory. Ephem also looks for one named by the EPHEMCFG environment
X variable, if it is set. You may specify an arbitrary name with the -c
X option.
X
X The default database file is named ephem.db in the current directory.
X Ephem also looks for one named by the EPHEMDB environment variable, if it
X is set. You may specify an arbitrary name with the -d option.
X
X The exact format of these files is described below.
X
X Any additional command line arguments are treated exactly as if they too
X came from the configuration file.
X
X 2.2. Program Operation
X
X When ephem starts, it first displays a disclaimer banner. Then, after any
X key is pressed, it reads the configuration file and processes the command
X line arguments to set the initial values of several fields, accessing the
X database file if OBJX or OBJY is set, It then draws all fields on the
X screen with their initial values. The program then loops advancing time
X each step, by some amount you may control, and updating all fields each
X loop.
X
X There are three fields that control this looping behavior. NStep controls
X the number of steps, StpSz the amount of time to add each step, and Pause
X is the amount of real seconds to pause between steps. Ephem does not
X pause between steps when plotting or searching is on. When the number of
X steps, NStep, goes to 0 or any key is pressed, the looping stops and you
X enter a command mode.
X
X Command mode allows you to modify most of the fields. The idea is that
X you move to each field on the screen you wish to change and change it.
X When you have changed everything you want to, type "q" to resume screen
X updates.
X
X To change a field:
X
X 1) move the cursor to the field (see below);
X 2) type RETURN;
X 3) type in the new value along the command line at the top according
X to the format indicated in the prompt. To accept the new value
X type RETURN, or to leave it unchanged after all type "q".
X
X
X A few fields don't require you to type anything; just typing RETURN does
X all the work. If you can't move to it, you can't change it.
X
X The arrow keys on most systems move the cursor around. If these do not
X
X
X
X
X
X
X
X
X
X - 5 -
X
X
X function or function incorrectly, the h/j/k/l keys also move the cursor
X left/down/up/right, respectively. Motions off any edge of the screen will
X wrap around.
X
X Several "hot-keys" move the cursor immediately to frequently used fields.
X You may move the cursor immediately to a planet row by typing one of the
X characters SMevmjsunpxy. To avoid conflict with j, jupiter's row must
X actually be typed as control-j. "x" and "y" are for the user-defined
X objects X and y on the bottom rows. Also, the characters c, d, o, w, L
X and z move you to the Menu, UT Date, Epoch, Watch, Listing and StpSz
X fields immediately.
X
X When you have changed a field that would invalidate any of the other
X fields the message NEW CIRCUMSTANCES appears in the top center of the
X screen. This will remain until you type "q" to allow at least one screen
X update loop to occur. If you change any field that causes new
X circumstances, the StpSz value is not added to the first loop. Note also
X that after a series of loops, NStep is automatically reset to 1 so "q"
X will do exactly one loop and return you to command mode.
X
X On some systems, you may temporarily escape from ephem while in command
X mode to run your operating system's command interpretor. This is done by
X typing an exclamation point (!) followed by your command. When the
X command completes, you will return back to ephem where you left off.
X
X To quit the program, type control-d from command mode. For a little more
X help, type ?. The entire screen may be erased and redrawn with control-l.
X
X 3. Screen Fields
X
X The screen is divided into two halves, top and bottom. The top fields are
X always present. They define the general observing circumstances and
X control features.
X
X The planets and two additional objects are displayed in a table in the
X bottom portion of the screen. There is one object per row, and several
X columns. There are three forms of this portion selected by picking the
X Menu selection.
X
X Some things may be turned off to reduce compute times. Calculations for
X each planet may be turned on and off by selecting the planet name field.
X Calculations for Dawn/Dusk/NiteLn may be turned off by selecting any of
X these fields. Planet positions are only updated as often as necessary to
X match the display precision of the screen unless plotting or searching is
X on. In these cases full precision is desired at all times and so
X positions are always fully recalculated at each iteration.
X
X Follows is a list and description of each of the fields in each section.
X Following each name a parenthetical "p" indicates the field may be
X selected for plotting (see later). All fields may be selected for
X changing.
X
X
X
X
X
X
X
X
X
X
X
X
X - 6 -
X
X
X 3.1. Top Screen Fields
X
X LTZ the local timezone name. The name field may be changed to
X any three-character mnemonic.
X LT(p)
X LD(p) The local time and date are not labeled as such but are to
X the right of the local timezone name. They are individually
X selectable. Time and date fields may be changed as
X described in a later section. Set to "n" to set to "now"
X from computer clock.
X UT(p)
X UD(p) The universally coordinated time and date are not labeled as
X such but are to the right of the UTC label. They are
X individually selectable. Time and date fields may be
X changed as described in a later section. Set to "n" to set
X to "now" from computer clock.
X JulianDat(p) the current Julian date, to about 1-second accuracy.
X Listing controls listing; see complete discussion below.
X Watch selects the sky dome, altitude/azimuth sky or solar system
X displays; see complete discussion below.
X Search controls the automatic search feature of ephem. See the
X complete discussion below.
X Plot controls plotting; see complete discussion below.
X Menu controls which menu is in the bottom half of the screen.
X See their complete discussion below.
X LST(p) the current local sidereal time. set to "n" to set from
X computer clock.
X Dawn(p) local time when the sun center is 18 degrees below the
X horizon before sunrise today.
X Dusk(p) local time when the sun center is 18 degrees below the
X horizon after sunset today.
X NiteLn(p) length of astronomical night, ie, Dawn - Dusk. If this line
X is shown as "-----", it means the sun is either always below
X or always above approximately -18 degrees altitude on this
X particular day. This and the Dawn and Dusk lines are blank
X when their computation has been turned off.
X NStep The number of times the display with be updated (time
X advanced by StpSz each step) before entering command mode.
X StpSz the amount of time UTC (and its derivatives) is incremented
X each loop. set this to "r" to use real-time based on the
X computer clock. you may also set it in terms of days by
X appending a "d" after the number when you set it.
X Lat(p) location latitude, positive degrees north of equator.
X Long(p) location longitude, positive degrees west of Greenwich
X meridian. set to "N" to set from computer clock.
X Elev(p) local elevation of the ground above sea level, in feet. (see
X implementation notes).
X Temp(p) local surface air temperature, in degrees F.
X AtmPr(p) local surface air pressure, in inches of mercury.
X TZ(p) hours local time is behind utc, ie, positive west or
X negative east of Greenwich.
X Epoch the epoch, to the nearest 0.1 years, to which the ra/dec
X fields are precessed. This says (OfDate) when coordinates
X are not precessed, ie, are in the epoch of date. Set to "e"
X
X
X
X
X
X
X
X
X
X - 7 -
X
X
X to set to epoch of date.
X Pause number of seconds to pause between screen updates. This is
X used mainly to set up for free-running unattended operation.
X This pause also applies to free-running "watch" screen
X updates. Pausing is not done when plotting or searching is
X on. If pausing is used with StpSz set to RT CLOCK and the
X time was set with Now then ephem attempts to synchronize the
X time to an integral multiple of pause seconds after the
X minute, for aesthetic reasons.
X Also in the upper right of the screen is a calendar for the current local
X month. Dates of new and full moons are marked NM and FM, respectively.
X
X 3.2. Data format columns
X Ob name of object. Select this to toggle the display and
X calculations on and off.
X R.A.(p) apparent geocentric right ascension of object, precessed to
X given epoch, in hours, minutes and decimal minutes.
X Dec(p) apparent geocentric declination of object, precessed to
X given epoch, in degrees and minutes.
X Az(p) degrees eastward of true north for object.
X Alt(p) degrees up from a horizontal plane Elev feet above sea
X level.
X H Long(p) true heliocentric longitude, in degrees. Earth's is
X displayed on the sun's line. For the moon this is the
X geocentric longitude.
X H Lat(p) true heliocentric latitude, in degrees. For the moon this
X is the geocentric latitude.
X Ea Dst(p) true distance from Earth center to object center, in AU,
X except distance to the moon is in miles.
X Sn Dst(p) true distance from sun center to object center, in AU.
X Elong(p) spherical angular separation between sun and given object,
X calculated from the their geocentric ecliptic coordinates.
X Note this is not just difference in ecliptic longitude. The
X sign, however, is simply sign(obj's longitude - sun's
X longitude), ie, degrees east. thus, a positive elongation
X means the object rises after the sun.
X Size(p) angular size of object, in arc seconds.
X VMag(p) visual magnitude of object.
X Phs(p) percent of visible surface in sunlight. Note the moon phase
X is calculated simplistically as just abs(elongation)/180*100
X which can be a few degrees off... this means that because of
X how elongation is defined it doesn't say 0 during new moon
X (or 100 during full) except during close eclipses (maybe
X that's a "feature"?).
X Also, some terminals scroll when a character is written to the lower right
X character position. To avoid this, Object Y's phase is left shifted by one
X column. This can look particularly ugly when the phase is 100% because the
X "100" is right next to visual magnitude number.
X If desired, the angle between Earth and Sun from the object, p, can be
X computed from the illumination percentage, i, with the following relation:
X
X cos (p) = i/50 - 1
X
X
X
X
X
X
X
X
X
X
X
X - 8 -
X
X
X 3.3. RiseSet format columns
X Rise Time
X Rise Az The local time and azimuth when the upper limb of the object
X rises today.
X Transit Time
X Transit Alt The local time and altitude when the object crosses the
X meridian today, ie, when its azimuth is true south or, if no
X precession, when the local sidereal time equals the object's
X right ascension.
X Set Time
X Set Az The local time and azimuth when the upper limb of the object
X sets today.
X Hours Up The number of hours the object is up on the local date.
X
X Horizon displacement may be calculated in either of two ways; see the
X horizon discussion in the Menu selection section.
X
X Various oddball conditions are accounted for, including an object that is
X up sometime during the day but that doesn't rise, transit or set as such
X on that day, an object that is circumpolar or that is never up or one that
X rises twice on the same day. These are marked as "Never rises", "Never
X transits", "Never sets", "Circumpolar", "Never up" or appended with a plus
X "+" sign, respectively.
X
X 3.4. Separation format fields
X This format is a table of angular separations between each pair of
X objects. These angles are based on the local altitude/azimuth, and so in
X general differ somewhat from the elongations reported for the sun in the
X Data menu.
X Unfortunately, with the format "ddd:mm", there is not enough room for a
X space between columns when the angle is at least 100 degrees. To avoid
X this, I drop the minutes portion if the (rounded) angle is at least 100
X degrees.
X
X 4. Date and Time Formats
X Times are displayed and entered in h:m:s format. If you pick a time field
X to change it any of the h, m, and s components that are not specified are
X left unchanged from their current value. For example, 0:5:0 set hours to
X 0, minutes to 5, seconds to 0, whereas :5 sets minutes to 5 but leaves
X hours and seconds unchanged. A negative time is indicated by a minus sign
X (-) anywhere before the first digit.
X
X Dates are displayed and entered in American month:day:year format. As
X with time, components omitted when entering a new value retain the current
X value. For example, if the current date is 10/20/1988 and you type 20/20
X the new date will become 20/20/1988. Note you must type the full year
X since the program is accurate over several centuries either side of 1900.
X If you change the date, the time (ie, partial day) will not change.
X
X Two other ways to set the date are supported for compatibility with some
X published comet ephemerides. You may enter the day portion as a real
X number. When you set the day this way, the time will also change to
X correspond to the fractional portion of the day.
X
X
X
X
X
X
X
X
X
X
X - 9 -
X
X
X You may also enter a date as a decimal year, as in 1990.12345. This is
X also useful in interpreting plot files that include a date field, since
X date fields are stored in plot files as decimal years. If no decimal
X point is included, the number is assumed to be a year unless it is in the
X range 1-12, in which case it will be taken to mean that you are just
X changing the month of the current date. To actually specify the years 1 -
X 12, you must append a decimal point to distinguish them from months.
X
X As a matter of typing convenience, the program accepts most any character
X as the separator; you don't have to type a perfect ":" or "/".
X
X 5. Configuration File
X The ephem.cfg configuration file allows you to set the initial values of
X many of the screen fields. You can still change any field while the
X program is running too; this file just sets the initial conditions. Note
X that the order of entries in this file is important because they each take
X effect immediately. You should put them in the same order you wish them
X to be processed, just as though you were changing the fields interactively
X within ephem.
X
X The default name of the file is ephem.cfg. Ephem also looks for one named
X by the EPHEMCFG environment variable (if defined) or you may specify any
X name using the -c command line option.
X
X The format of the file uses the form KEYWORD=VALUE, where the possible
X KEYWORDS and the types of VALUES for each are described below. Any
X KEYWORDS not in the file will take on some sort of default. The separator
X need not be an actual equals sign; any char will do because the VALUE is
X assumed to start one character after the KEYWORD, regardless.
X
X Blank lines and lines that begin with an asterisk (*) or whitespace (space
X or tab) are ignored and may be used for comments.
X
X Note: because of the way unspecified time and date components are left
X unchanged (see section on Date and Time Formats) always specify the
X complete time and date for all entries in the configuration file. For
X example, to initialize the longitude to zero degrees, say 0:0:0, not just
X 0.
X
X 5.1. Configuration File fields
X UD initial UTC date, such as 10/20/1988, or "NOW" to use the
X computer clock.
X UT initial UTC time, such as 12:0:0, or "NOW" to use the computer
X clock.
X TZONE hours the local time is behind utc, such as 5:0:0. you need not
X set this if you use "NOW" for UT or UD.
X TZNAME name of the local time zone, such as CDT. 3 chars max. you need
X not set this if you use "NOW" for UT or UD.
X LONG longitude, in degrees west of Greenwich, in the form d:m:s.
X LAT latitude, in degrees north of the equator, in the form d:m:s.
X HEIGHT height above sea level, in feet, such as 800
X TEMP air temperature, in degrees F, such as 50
X
X
X
X
X
X
X
X
X
X
X
X - 10 -
X
X
X PRES air pressure, in inches of Mercury, such as 29
X STPSZ the time increment between screen updates, such as "1" to give
X one hour updates. this can be a specific amount or RTC to use
X the system clock as a real-time source. You may also specify a
X time in days, by appending a D (or d) after the number.
X PROPTS this selects what you want included initially in the display.
X since IBM-PC math is not very fast, you can reduce the time to
X update the screen by only printing those fields of interest. the
X VALUE is a collection of letters to turn on each item from the
X following set:
X
X T twilight (dawn-dusk)
X S circumstances for the sun
X M circumstances for the moon
X e circumstances for mercury
X v circumstances for venus
X m circumstances for mars
X j circumstances for jupiter
X s circumstances for saturn
X u circumstances for uranus
X n circumstances for neptune
X p circumstances for pluto
X x circumstances for object X
X y circumstances for object Y
X
X For example, to just track the sun and saturn, say PROPTS=Ss
X
X If the delimiter between PROPTS and the selection is a plus (+)
X sign then the given planets are included IN ADDITION TO ones
X already specified. Any other delimiter sets the selection to
X exactly the set specified. This feature was added so that the
X command line version of using PROPTS could add to the set of
X planets giving in the configuration file.
X NSTEP number of times program will loop before entering command mode.
X see the discussion under Program Operation.
X EPOCH this sets the desired ra/dec precession epoch. you can put any
X date here or EOD to use the current instant ("Epoch of Date").
X OBJX
X OBJY These fields specify the optional objects "x" and "y" by naming
X any item in the database file. The form is OBJX=xyz, where xyz
X must be in the database file, case sensitive. You may define
X one object of each type for each of OBJX and OBJY; the last one
X defined will be the "current" one when ephem gets going.
X PAUSE The number of seconds to pause between calculation steps. See
X definition of the Pause field in the "Top Screen Fields"
X section.
X MENU establishes the initial bottom screen menu type. This should be
X one of the keywords DATA, RISET or SEP. There is no way to set
X horizon or center suboptions at this time.
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X - 11 -
X
X
X 5.2. Example ephem.cfg
X
X This is the ephem.cfg file that was in effect when the sample screens (in
X another section) were generated. You might run ephem with this
X configuration file and compare with the samples as a check.
X
X UT=0;0;0
X UD=5/1/1990
X TZNAME=CDT
X TZONE=5
X LONG=93:42:8
X LAT=44:50:37
X HEIGHT=800
X TEMP=40
X PRES=29.5
X STPSZ=RTC
X PROPTS=TSMevmjsunpxy
X EPOCH=2000
X NSTEP=1
X
X OBJX=Austin
X OBJY=Juno
X
X As another common example, this ephem.cfg creates an essentially free-
X running real-time screen based on the computer clock:
X
X UT=Now
X LONG=90:10:8
X LAT=40:50:20
X HEIGHT=800
X TEMP=50
X PRES=29
X STPSZ=RTC
X PROPTS=TSMevmjsunp
X NSTEP=9999999
X EPOCH=Eod
X PAUSE=30
X
X
X 6. Menu options
X
X When you select "Menu" you can change among the three styles of bottom
X screens. There are also two options that can be set from the Menu quick-
X choice menu. These options toggle when picked and retain their values so
X they need only be changed when desired.
X
X 6.1. Adaptive vs. Standard hzn
X
X This selects the horizon refraction displacement algorithm used by the
X Rise/Set menu. "Adaptive" uses the local atmospheric conditions known to
X ephem and matches the Planet Info times nicely. "Standard" uses the
X "accepted nominal" horizon refraction value of 32 arc minutes and usually
X agrees, to a minute or so, with published tables.
X
X
X
X
X
X
X
X
X
X
X - 12 -
X
X
X 6.2. Geocentric vs. Topocentric
X
X This selects the vantage point for the Separation menu. "Geocentric"
X ignores local conditions and gives the separation as seen from Earth
X center. "Topocentric" uses the local conditions known to ephem. They are
X particularly critical for lunar occultations, but the effect can be
X significant for the planets.
X
X Note that searching over a period that will include the rise or set times
X of either object is generally better performed from the geocentric
X viewpoint. The refraction effect of the topocentric viewpoint causes many
X arcminutes of rapid whiplash displacement as the objects rise and set that
X overlays the smooth celestial motion of the objects. This rapid position
X variation can confuse the solver algorithms that expect fairly smooth
X functions.
X
X 7. User Defined Objects: X and Y
X
X You may specify one or two extra objects for ephem to use. The objects may
X be defined in three different ways: fixed celestial sphere coordinates,
X or heliocentric elliptical or parabolic orbital elements. Elliptical
X elements are typically useful for periodic comets or asteroids, and
X parabolic elements are for nonrecurring solar system interlopers such as
X aperiodic comets.
X
X The parameters for each type of object are stored separately, so you may
X switch between types of objects without losing parameters.
X
X 7.1. Controlling Object-X or Y Operation
X
X To control the type and the corresponding details for object X or Y,
X select the corresponding row near the bottom. (Remember that typing the
X character "x" or "y" is a shorthand way to move to the bottom rows.) It
X will bring up a quick-choice menu as follows:
X
X Select: Fixed, Elliptical, Parabolic, Lookup, On
X
X
X When you first enter the quick-choice menu the cursor will start out
X positioned at the field for the current type of object. The first three
X selections allow you to enter or review the various parameters required to
X define an object's position of such type, one parameter at a time.
X
X You set the current object type and begin to view its parameters by
X positioning the cursor over the type and pressing RETURN. The prompt for
X each item includes a short description, the units to use, and its current
X setting is shown in parentheses. To leave the item unchanged and go to the
X next item, type RETURN. If you do not wish to change or see any more
X items about the object then type "q" and you will return immediately to
X the object-X quick-choice menu.
X
X You exit the quick-choice menu by typing "q" while over any field or
X RETURN while over On or Off, as described in a later section.
X
X
X
X
X
X
X
X
X
X
X - 13 -
X
X
X As with all dates throughout ephem, the dates for the epochs of perihelion
X and reference epochs may be entered in month/day/year or decimal year
X formats, and the day may be entered as a real number (see the section on
X Date and Time Formats). All dates given for comet parameters are always
X in UT.
X
X 7.1.1. Fixed
X
X This selection will present a series of five prompts, the name and one
X each for the RA, Dec, magnitude and the reference epoch for the
X coordinates of a fixed object.
X
X 7.1.2. Elliptical
X
X This will begin a series of twelve prompts asking for a name and the
X parameters that define a heliocentric elliptic orbit and the coefficients
X for either of two magnitude models. These elements are the same ones
X often listed in the Astronomical Almanac. The elements are, in order:
X
X i = inclination, degrees
X O = longitude of ascending node, degrees
X o = argument of perihelion, degrees
X a = mean distance (aka semi-major axis), AU
X n = daily motion, degrees per day
X e = eccentricity
X M = mean anomaly (ie, degrees from perihelion)
X E = epoch date (ie, time of M)
X D = the equinox year (ie, time of i/O/o)
X g/k or H/G = either of two magnitude models; see below
X
X
X You might have other parameters available that can be converted into
X these. For example, we have the following relationships:
X
X P = sqrt(a*a*a)
X p = O + o
X n = 360/days_per_year/P ~ 0.98563/P
X T = E - M/n
X q = a*(1-e)
X where
X P = the orbital period, years;
X p = longitude of perihelion, degrees
X n = daily motion, degrees per day;
X T = epoch of perihelion (add multiples of P for desired range)
X q = perihelion distance, AU
X
X Note that if you know T you can then set E = T and M = 0.
X
X 7.1.3. Parabolic
X
X This will begin a series of nine prompts asking for a name and the
X parameters that define a heliocentric elliptic orbit and the magnitude
X model coefficients. These orbital parameters are, in order:
X
X
X
X
X
X
X
X
X
X
X - 14 -
X
X
X epoch of perihelion,
X inclination,
X argument of perihelion,
X perihelion distance,
X longitude of the ascending node,
X and the reference epoch of the parameters.
X absolute magnitude, g
X luminosity index coefficients, k
X
X
X 7.1.4. Lookup
X
X This option lets you define an object from any of those listed in the
X database file, described in a subsequent section.
X
X If successful, the cursor will move to the type of the new object and it
X becomes the current type.
X
X 7.1.5. On or Off
X
X The last selection on the right toggles the calculations for the object On
X and Off. It toggles when selected with RETURN and then immediately exits
X the quick-choice menu back to the main menu. If calculations become On,
X then they will be performed for the current type of object; if they become
X Off the object-X or Y row of information will be erased.
X
X 7.2. Magnitude models
X
X Ephem supports two different magnitude models. One, denoted here as g/k,
X is generally used for comets and may be used for parabolic and elliptical
X objects. The other, denoted H/G, is generally used for asteroids and is
X the one used in the Astronomical Almanac.
X
X 7.2.1. g/k model
X
X This model requires two parameters to be specified. One, the absolute
X magnitude, g, is the visual magnitude of the object if it were one AU from
X both the sun and the earth. The other, the luminosity index, k,
X characterizes the brightness change of the object as a function of its
X distance from the sun. This is generally zero, or very small, for inactive
X objects like asteroids. The model may be expressed as:
X
X m = g + 5*log10(D) + 2.5*k*log10(r)
X where:
X m = resulting visual magnitude;
X g = absolute visual magnitude;
X D = comet-earth distance, in AU;
X k = luminosity index; and
X r = comet-sun distance.
X
X Note that this model does not take into account the phase angle of
X sunlight.
X
X When using this model for elliptical objects, the first of the two
X
X
X
X
X
X
X
X
X
X - 15 -
X
X
X magnitude fields must be preceded by a letter "g" in both the ephem.db
X database file and the corresponding quick-choice elliptical object
X definition prompt; otherwise the default is the H/G model.
X
X 7.2.2. H/G model
X
X This model also requires two parameters. The first, H, is the magnitude of
X the object when one AU from the sun and the earth. The other, G, attempts
X to model the reflection characteristics of a passive surface, such as an
X asteroid. The model may be expressed with the following code fragment:
X
X beta = acos((rp*rp + rho*rho - rsn*rsn)/ (2*rp*rho));
X psi_t = exp(log(tan(beta/2.0))*0.63);
X Psi_1 = exp(-3.33*psi_t);
X psi_t = exp(log(tan(beta/2.0))*1.22);
X Psi_2 = exp(-1.87*psi_t);
X m = H + 5.0*log10(rp*rho) - 2.5*log10((1-G)*Psi_1 + G*Psi_2);
X where:
X m = resulting visual magnitude
X rp = distance from sun to object
X rho = distance from earth to object
X rsn = distance from sun to earth
X
X Note that this model does not take into account the phase angle of
X sunlight.
X
X 7.3. Database File
X
X You may save a list of objects in a file to be used for setting OBJX and
X OBJY. The default name of this file is ephem.db. You may also set it from
X the command line with the -d option, or set it with the EPHEMDB
X environment variable.
X
X The file consists of one object per line. Lines that begin with an
X asterisk (*) are ignored. Each line contains several fields, each
X separated by a comma. The first field is the name of the object. The
X second field is the type of the object, that is, one of the strings
X "fixed", "elliptical", or "parabolic"; actually, "f", "e" and "p" are
X sufficient. The remaining fields depend on the type of object. They are
X exactly the same parameters, and in the same order, as ephem asks for when
X defining the object from the menu.
X
X 8. Plotting
X
X Each time a field is drawn on the screen during a full screen update cycle
X (that as, during automatic looping or a manual "q" command character from
X the main menu but not from a screen redraw from control-l or when an
X individual planet is turned on or a single time field is changed) its
X full-precision value may be written to a file. This implies you may not
X plot a field from other than the current menu at the time plotting is on.
X You can append several plot runs together, however, if necessary.
X
X Each line in the file consists of a tag character followed by two or three
X floating point variables, all separated by commas. If there are two
X
X
X
X
X
X
X
X
X
X - 16 -
X
X
X values, they should be interpreted to be x and y (or perhaps r and theta).
X If there is a third, it is a z or trace value.
X
X For efficiency on systems that can compute a screen full faster than they
X can display it, screen updates are suppressed while plotting is on and
X NStep is greater than 1. This can greatly reduce the time to generate a
X long plot file. Fields are still logged for plotting; they just are not
X drawn on the screen.
X
X The Plot field controls plotting. Whether plotting is currently active is
X indicated by "on" or "off" immediately to its right.
X
X Picking "Plot" brings up a quick-choice menu, as follows:
X
X Select: Select fields, Display a plot file, Cartesian coords, Begin plotting
X
X
X 8.1. Defining plot fields
X
X Select the "Select fields" option. You will be asked to move the cursor
X to the field you want to use as the x coordinate (abscissa), then asked to
X choose the y coordinate (ordinate), then asked to choose an optional z
X trace variable and finally a tag character. (Of course, you may have in
X mind fields that are more appropriately displayed in other than Cartesian
X coordinates, in which case think of x, y and z as dimensions.) If you type
X q for either x or y then no more fields will be defined. If you type q
X for the z field there will be no z field. You can not label a plot line
X with the letter "q" at this time.
X
X This then repeats so you may choose up to ten of these sets for any given
X plot run. Each set defines what will become a line on the final plot.
X Note that you may select the "Search" field to indicate use of the current
X search function; that function must be defined by the time plotting is
X turned on.
X
X If you turn plotting off and back on the fields selected for plotting are
X reactivated the same as they were last time. You may change them if
X desired, of course, but there is no need to redefine them if you do not
X wish to change them.
X
X 8.2. Displaying a plot file
X
X Select the "Display a plot file" option to generate a crude plot on the
X screen of an existing plot file previously created by ephem. The entries
X in the file will be drawn on the screen using their tag characters; the
X plot remains on the screen until you type any character.
X
X The plot may be made in polar or Cartesian coordinates, depending on the
X setting of the plotting mode in the quick-choice (see next section).
X
X 8.3. Cartesian or Polar coords
X
X This toggles the plotting mode coordinate system. The mode remains until
X changed. Polar coordinates assume the first numeric field in the plot
X
X
X
X
X
X
X
X
X
X - 17 -
X
X
X file is the radius, and the second is the angle counterclockwise from
X right, in degrees.
X
X 8.4. Begin Plotting
X
X If plot field lines are defined then the third option, "Begin plotting"
X will be available. You will be asked for the name of the file to use. If
X it already exists you will be asked whether to overwrite it or append to
X it. You will also be asked for a title line that will become the next
X line of the file, automatically prefixed with a "*" to make it a valid
X comment line. Once you have chosen a file, plotting is on and the top
X menu plotting status field changes to "on". The default plot file name is
X ephem.plt. The values are written to the plot file each time they are
X updated on the screen until you select "Plot" again and select the "Stop"
X option to turn plotting back off.
X
X 8.5. Stopping Plotting
X
X If plotting is on, then selecting the Plot field in the top section will
X turn plotting off. You may pick Plot again and resume with the same fields
X by selecting "Begin plotting" again.
X
X Note that due to internal buffering the plot file will not be completely
X written to disk until plotting is turned off.
X
X 9. Listing
X
X This feature works very much like Plotting. However, the fields you select
X define columns of a table generated as ephem runs. These columns are look
X exactly like their corresponding fields on the ephem screen and so are far
X more readable than plot files.
X
X See the section on Plotting for an explanation of the quick-choice menu.
X The general operation is very much the same.
X
X 10. Watching
X
X You may generate a simple drawing on the screen of the local sky in two
X forms or the solar system by selecting "Watch". It will bring up a
X quick-choice menu as follows:
X
X Select: Sky dome, Alt/az sky, Solar system, No trails
X
X
X 10.1. Trails
X
X You may either erase after each iteration or leave the tags up, referred
X to as "trails". Picking the right-most choice will toggle between "No
X trails" and "Leave trails"; you should set it as desired before you select
X the style of sky plot you wish. Ephem will remember your selection.
X
X
X
X
X
X
X
X
X
X
X
X
X
X - 18 -
X
X
X 10.2. Sky dome
X
X This draws the currently active planets within a circle that represents
X the locally visible hemisphere. This is similar to the formats commonly
X used in the popular astronomy magazines. East is left, south is down,
X west is right and north is up.
X
X 10.3. Alt/az sky
X
X This is a cylindrical projection showing the currently active planets as
X they would appear in the sky looking southwards at the current time and
X date. The coordinate system is such that 0 degrees azimuth (north)
X through 360 degrees (north, once around) is mapped to the horizontal
X screen dimension, and 0 degrees altitude (level) through 90 degrees (the
X zenith) is mapped to the vertical dimension. Thus, the bottom row is the
X horizon and all across the top is the zenith.
X
X 10.4. Solar System
X
X This selection draws the currently active planets as they would appear
X looking "down from the top" of the ecliptic, with the sun at the center
X and zero hours right ascension towards the right. The scale is adjusted
X to roughly fill the screen according to the outer-most active planet.
X Note that the scaling does not take into account the distances of the user
X defined objects so, if they don't appear, select a planet that is at least
X as far out as they are. The screen transformation assumes a screen aspect
X width/height ratio of 4/3. Down the left column of the screen is the
X heliocentric altitude of the planet above or below the ecliptic, drawn to
X the same scale as the circular display. Values so close as to land on the
X same line are sorted left to right; the S and E symbols always denote
X heliocentric altitude 0.
X
X In each style of display, pressing RETURN advances the time by whatever
X amount StpSz is set to. Pressing "h" advances the time by one hour, "d"
X advances by one day, and "w" advances by one week (seven days). Pressing
X "q" returns to the watch quick-choice menu from which you may select
X another display style or return to the main tabular display by typing
X another "q". Pressing any other key starts an automatic loop with each
X step advancing by StpSz; pressing any key stops the looping.
X
X As symbols are placed, collisions (overstrikes) are avoided by moving
X characters in such a way as to maintain increasing sorted order towards
X the right.
X
X When you return to the main menu, the last watched time will be maintained
X as the current time. The StpSz is not changed.
X
X 11. Searching
X
X Ephem can search for arbitrary conditions to exist among most displayed
X fields. You first enter a function, then select from among three forms of
X equation solvers to iteratively solve for the next time when the function
X meets the requirements of the solver. The solver selects the next time for
X which it wants the function evaluated and sets StpSz so that the next
X
X
X
X
X
X
X
X
X
X - 19 -
X
X
X iteration will occur at that time. The solvers continue to iterate until
X either they achieve their goal or NStep reaches 0.
X
X You may set NStep to be quite large and let ephem search unattended or set
X it to 1 and watch it converge one step at a time. You may also plot at the
X same time as search to record the exact steps ephem took to converge.
X (But recall that screen updates are suppressed if plotting is also on).
X
X The "Search" selection in the top half of the screen controls all
X searching. Picking it brings up a quick-choice menu as follows:
X
X Select: Find extreme, Find 0, Binary, New function, Accuracy
X
X
X 11.1. Find extreme
X
X This search algorithm searches for a local maximum or a minimum in the
X search function, whichever it finds first. It begins by evaluating the
X search function at the current time then for two more times each separated
X by StpSz. It then fits these three points to a parabola and solves it for
X the time of its maximum (or minimum). StpSz is set so that the next
X iteration will evaluate at this point. This parabolic fit solution keeps
X repeating until StpSz changes by less than the desired accuracy or until
X the curve becomes so flat that an extrema appears too broad to find.
X
X 11.2. Find 0
X
X This search algorithm uses the secant method to solve for the time at
X which the search function is zero. The function is evaluated at the
X current time and then again StpSz later to establish a slope for which the
X x-intercept is found as the next zero guess. This is used to set StpSz for
X the next desired time value and the slope hunting process repeats until
X StpSz changes by less than the desired accuracy.
X
X 11.3. Binary
X
X This search algorithm must be used with a search function that yields a
X boolean result, ie, a true or false value. The idea is that the function
X is assumed to be one truth value when evaluated at the present time, and
X the opposite truth value when it is evaluated StpSz later. The algorithm
X will then do a binary search for the time when the truth value changes.
X
X The binary algorithm does not begin until the state change is bounded in
X time. Initially, as long as the truth value at StpSz is the same as the
X previous value the algorithm will just keep moving in time by StpSz
X looking for when the state changes. That is, a linear search is initiated
X to bound the state change, then the binary search proceeds.
X
X 11.4. Define a New function
X
X Select "New function" to display the current search function. If you type
X "q" it will be left unchanged. If you type RETURN it will be erased. If
X you type anything else it will be compiled and, if there are no errors, it
X will become the new search function. Once a valid function has been
X
X
X
X
X
X
X
X
X
X - 20 -
X
X
X stored, it will remain unless changed. If a search function is selected
X and there is as yet no valid search function defined, you will
X automatically be asked to enter one as though you had selected "New
X function."
X
X A search function consists of intrinsic functions, field-specifiers,
X constants and operators, and precedence may be overridden with
X parentheses.
X
X
X 11.4.1. Intrinsic functions
X
X In this release, the only intrinsic function available is abs(), which
X returns the absolute value of its argument.
X
X 11.4.2. Field Specifiers
X
X A field in the bottom half of the menu is specified in the form of
X "object_name.column_name". The object_name is enough of the planet name to
X be unique; use "x" or "y" for the user-specified object X or Y. The
X column_name is from the following table, depending on which menu is up. In
X all cases additional characters may be entered but are ignored.
X
X Planet Data Menu Rise/Set Menu Separation Menu
X ------------------ -------------------- ---------------
X al Alt hr Hrs Up, or j Jup
X az Az hu Hrs Up ma Mars
X d Dec raz Rise Az me Merc
X ed Ea Dst rt Rise Time mo Moon
X el Elong saz Set Az n Nep
X hla Helio Lat st Set Time pl Pluto
X hlo Helio Long ta Transit Alt sa Saturn
X ph Phs tt Transit Time su Sun
X ra R.A. u Uranus
X sd Sn Dst ve Venus
X si Size
X vm VMag
X
X
X In addition, the following top-half fields may be used:
X
X da Dawn
X du Dusk
X n NiteLn
X
X
X
X Remember, searching may only involve fields being calculated for display
X at the time the solver is active. While you can syntactically include any
X field in a search function it is useless to define a search that uses
X fields from other than the menu that is selected at the time the search is
X running.
X
X
X
X
X
X
X
X
X
X
X
X - 21 -
X
X
X 11.4.3. Constants
X
X Constants may be integers or floating point numbers. The latter may be
X expressed in scientific notation if desired. Examples include 100, .9,
X 1.234, 1e10 and 1.2e-4. Any number may be preceded by - to make it
X negative.
X
X 11.4.4. Operators
X
X The collection of arithmetic, relational and boolean operators provided
X mimics those of C language as listed in the following table, in decreasing
X order of precedence. Operators grouped together have the same precedence
X and all have left-to-right associativity. Parentheses may be used as
X desired.
X
X Symbol Meaning Resulting type
X ------ -------------------- --------------
X * multiply arithmetic
X / divide arithmetic
X
X + add arithmetic
X - subtract arithmetic
X
X > greater than boolean
X >= greater than or equal boolean
X < less than boolean
X <= less than or equal boolean
X
X == equality boolean
X != inequality boolean
X
X && logical and boolean
X
X || logical or boolean
X
X
X 11.5. Specifying Search Accuracy
X
X Selecting "Accuracy" allows you to specify when the search will stop. The
X search algorithms will stop when StpSz becomes equal to or less than this
X value. The default is one minute. If ephem has not yet converged to the
X specified accuracy but NStep has decremented to 1, the searching will stop
X but the search status field will still indicate which search procedure is
X in effect. To try more iterations you may increase NStep and resume
X searching. If the accuracy was achieved, the search status field will
X switch to "off" with the number of "unused" steps remaining in NStep and
X the last step size in the StpSz fields.
X
X 11.6. Stop
X
X If searching is on, this option will also appear on the quick-choice menu
X and may be selected to turn off the search.
X
X
X
X
X
X
X
X
X
X
X
X - 22 -
X
X
X 11.7. Example Searches
X
X As an example, let's find when Pluto again becomes the furthest planet
X from Sol. You may find when the difference in their sun distance is zero,
X or you might use a binary search on the condition that Pluto's sun
X distance is larger then Neptune's.
X
X To try the former approach select Search, select "Find 0", specify the
X search function to be:
X
X pl.sd - nep.sd
X
X set StpSz to something large like 10d, NStep to allow several iterations
X like 20, and then type "q" to start the search and watch ephem do the
X hunt. Ephem will settle on about 21:02 1/10/1999 UT.
X
X To try a binary search, you first need to have some idea of when the event
X will occur so you can eliminate the initial linear search for the state
X change. We can start at, say, 1/1/1999, set StpSz to 30d, select Binary
X search, specify the search function to be:
X
X pl.sd > nep.sd
X
X and go. Once it brackets the state change note how StpSz keeps being cut
X in half but can go in either direction (sign) as it divides each interval
X in half. Ephem will converge on the same answer.
X
X 11.8. Another Example
X
X To find the time of last quarter moon during December, 1989, use the "Find
X 0" search algorithm to solve "moon.el + 90". (At last quarter, the moon
X is 90 degrees west of the sun, or -90 east in ephem's elongation display.)
X Set the initial time to mid-month, 12/15/1989, StpSz to 1 day and NStep to
X 10. Ephem takes only a few iterations to settle on 23:57 12/19 UT.
X
X 11.9. Caution
X
X Beware that most celestial phenomena are generally pseudo-periodic in
X nature. In early search steps ephem can easily skip over a local maxima
X and find a later one, which, while correct, may not be what was desired.
X In general, the closer you can be when you start the search the better
X ephem can refine it; it is not as good with very broad searches that can
X go "wild". Set StpSz large enough to offer significant change in the
X function value, but small enough not to skip too far.
X
X For example, Saturn and Neptune had three close approaches during 1989.
X If you did not know this then just asking ephem to find a minimum would
X have produced different results depending on the starting conditions.
X When starting a search for a certain class of event it is a good idea to
X first use the plotting or watching facility of ephem to get a broad
X picture of the general circumstances then use ephem's search facility to
X refine a given region (or create and inspect a plot file and do your own
X interpolation directly from it separately).
X
X
X
X
X
X
X
X
X
X
X - 23 -
X
X
X Similarly, ephem's searching techniques are not good for eclipses because
X the moon and sun are close every month; the trick is sorting through the
X frequent conjunctions for ones that are particularly close. One needs a
X way of establishing an envelope fit to the local extrema of a cyclic
X function in order to find a more global extreme.
X
X 12. Implementation Notes
X
X Remember that everything is for the current local time and day. So, for
X example, the calendar marks moon events in local time; commercial
X calendars usually mark the UT date. Similarly, the rise/set times are for
X the current local day.
X
X The program uses a horizontal plane tangent to the earth as the horizon
X for all altitude calculations, rise/set events, etc. This is not the same
X as the angle up from the local horizon unless the observer is directly on
X the ground due to earth's curvature. The effect can be found from:
X
X sin(a)**2 = (h**2 + 2Rh) / (R+h)**2
X where:
X R = radius of earth
X h = height above ground (same units as R)
X a = increase in altitude
X
X For example, the effect is more than two arc minutes at a height of 5
X feet.
X
X Visual magnitudes are not very accurate ... I haven't bothered to fix.
X
X The accuracy of ephem can not be specifically stated since the Duffett-
X Smith book does not warrant its planet position polynomials to any given
X degree. I know for sure that better accuracy could be achieved if ephem
X used TDT but I have not yet decided on a suitable algorithm. Allowing for
X this manually, (see the Wish List section) comparisons with the
X Astronomical Almanac are often within a few arcseconds.
X
X The program uses double precision throughout. While this precision might
X seem a little ridiculous, it is actually more efficient for most
X traditional K&R C compilers and the search functions seem to be are far
X more stable.
X
X Searching and plotting always use full precision but if neither of these
X are turned on pure display and watching only recompute a given planets new
X location if the time has changed enough to effect the required display
X precision, based on the planets mean apparent orbital motion.
X
X The sun-moon distance is the solution for the third side of a planar
X triangle whose two other sides are the earth-moon distance and earth-sun
X distance separated by the angle of elongation.
X
X Beware of specifying a year of 0, or of computing with the user-defined
X objects before they are properly defined. These conditions can cause ephem
X to blow.
X
X
X
X
X
X
X
X
X
X
X - 24 -
X
X
X 12.1. Program limits
X
X The search function is limited to a maximum of 32 instructions (each
X constant, field spec, and operation is one instruction), with no more than
X a total of 16 constants and field specs. At run time, the function can not
X require more than 16 stacked values (due to operator precedence or
X explicit parenthetical expressions) to evaluate.
X
X No more than 32 different fields can be tracked simultaneously for
X plotting and/or searching.
X
X No more than 10 lines may be plotted at once.
X
X The maximum file name length is 14 characters.
X
X 13. DOS Installation Procedure
X
X You must be running DOS V2.0 or later, though somewhere between V2.0 and
X V3.21 the behavior of control-c to terminate the program was fixed. An
X 8087 floating point chip will be used if present.
X
X The distribution floppy contains five files:
X README describes last minute items and details of this release.
X MAN.TXT is this manual, hopefully formatted and printable on most any
X printer.
X EPHEM.EXE is the executable program.
X EPHEM.CFG is a sample configuration file.
X EPHEM.DB is a sample database.
X To run the program, make working copies of these files in a directory and
X run "ephem" from that directory.
X
X 13.1. Setting TZ
X
X Before running ephem, you should set a DOS environment variable, TZ. It
X is is used to establish the timezone name and hours offset whenever the
X "Now" shorthand is used from ephem, either from the configuration startup
X file or whenever any time field is changed manually. Set it in the
X following form:
X
X set TZ=SSSnDDD
X
X where
X
X SSS is the 3-letter abbreviation for the local standard timezone;
X
X n is a number between -23 to 24 indicating the number of hours that are
X subtracted from GMT to obtain local standard time;
X
X DDD is an optional 3-letter abbreviation for the local daylight savings
X time zone name. Leave it off if you do not have savings time in your
X area or it is not currently in effect. If the changeover dates differ
X from the internal algorithm, just use SSS and n directly.
X
X For example, in the midwestern United States with savings times set
X
X
X
X
X
X
X
X
X
X - 25 -
X
X
X TZ=CST6CDT
X
X If for some reason your system does not change to savings time at the
X right time, then omit the DDD parameter and just set the SSS and n to
X exactly what you want.
X
X You can put this in your AUTOEXEC.BAT file so it gets set each time you
X boot DOS.
X
X 14. Known Bugs and Wish List
X
X incorporate Terrestrial Dynamical Time (known as Ephemeris Time prior to
X 1984). TDT is about 57 seconds ahead of UT1 in 1990.
X
X it's too easy to turn on objx/y before it's defined and bomb out.
X
X add explicit searching for eclipses and occultations.
X
X in watch mode, RTC reverts back to being based off the time when watch was
X first entered.
X
X add a facility (or tool) to find g/k from a set of observed magnitudes.
X
X find a better precession algorithm; current one exhibits some hysteresis
X and isn't all that accurate in general.
X
X add search criteria for database objects.
X
X add plot options to reverse x and/or y direction.
X
X handle year 0 properly.
X
X add moons.
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X - 26 -
X
X
X 15. Sample Screens
X
X Here are sample ephem screens. They are generated using the first sample
X ephem.cfg file (listed in the section describing the configuration file).
X There is one for each of the three possible screen formats. The rise/set
X screen was done using the Adaptive option. The separations screen was
X done using the Topocentric option.
X
XMove to another field, RETURN to change this field, ? for help, or q to run
X
XCDT 19:00:00 4/30/1990 | LST 8:19:50 | Lat 44:50:37 | April 1990
XUTC 0:00:00 5/01/1990 | | Long 93:42:08 | Su Mo Tu We Th Fr Sa
XJulianDat 2448012.50000 | Dawn 4:10 | Elev 800 ft | 1 2 3 4 5 6 7
XWatch | Dusk 22:15 | Temp 40 F | 8 FM 10 11 12 13 14
XListing off | NiteLn 5:55 | AtmPr 29.50 in | 15 16 17 18 19 20 21
XSearch off | | TZ 5:00:00 | 22 23 NM 25 26 27 28
XPlot off | NStep 1 | Epoch 2000.0 | 29 30
XMenu Planet Data | StpSz RT CLOCK | Pause 0 |
X--------------------------------------------------------------------------------
XOb R.A. Dec Az Alt H Long H Lat Ea Dst Sn Dst Elong Size VMag Phs
XSu 2:32.3 14:58 278:40 12:38 220:22 1.0075 1905 -27
XMo 8:09.9 21:11 186:06 65:53 119:55 1:04 234821 1.0071 79.5 1897 -12 44
XMe 2:49.4 17:39 277:48 17:26 214:08 1:43 0.5764 0.4360 4.9 11.7 1.6 1
XVe 23:49.4 -2:25 296:53 -27:39 282:39 -1:30 0.9288 0.7276 -43.9 18.2 -4.8 64
XMa 22:39.8 -10:09 308:17 -44:14 297:56 -1:43 1.5438 1.4067 -62.9 6.1 0.3 89
XJu 6:30.9 23:23 235:13 59:04 106:16 0:08 5.6806 5.1941 56.6 34.6 -2.0 99
XSa 19:49.6 -20:53 17:24 -65:14 289:45 0:10 9.7077 10.017 -105.0 17.1 1.1 100
XUr 18:41.9 -23:24 51:18 -60:39 276:55 -0:18 18.864 19.401 -120.9 3.5 5.6 100
XNe 19:03.2 -21:46 40:51 -62:01 282:48 0:51 29.754 30.207 -115.8 2.1 7.9 100
XPl 15:14.8 -1:26 81:18 -10:37 226:18 15:28 28.693 29.658 -162.9 0.3 13.6 100
XX 0:08.3 36:01 316:59 5:58 238:20 26:29 0.5622 0.6657 -38.4 1.5 33
XY 15:22.9 -2:40 80:43 -12:54 226:17 10:49 2.3635 3.3381 -162.5 10.1100
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X - 27 -
X
X
XMove to another field, RETURN to change this field, ? for help, or q to run
X
XCDT 19:00:00 4/30/1990 | LST 8:19:50 | Lat 44:50:37 | April 1990
XUTC 0:00:00 5/01/1990 | | Long 93:42:08 | Su Mo Tu We Th Fr Sa
XJulianDat 2448012.50000 | Dawn 4:10 | Elev 800 ft | 1 2 3 4 5 6 7
XWatch | Dusk 22:15 | Temp 40 F | 8 FM 10 11 12 13 14
XListing off | NiteLn 5:55 | AtmPr 29.50 in | 15 16 17 18 19 20 21
XSearch off | | TZ 5:00:00 | 22 23 NM 25 26 27 28
XPlot off | NStep 1 | Epoch 2000.0 | 29 30
XMenu Rise/Set Info | StpSz RT CLOCK | Pause 0 |
X--------------------------------------------------------------------------------
XOb Rise Time Rise Az Trans Time Trans Alt Set Time Set Az Hours Up
XSu 6:05 67:48 13:12 60:01 20:20 292:28 14:15
XMo 10:54 57:14 18:49 66:01 1:56 304:46 15:02
XMe 6:13 63:34 13:30 62:51 20:47 296:04 14:34
XVe 4:35 93:02 10:29 42:33 16:23 267:14 11:48
XMa 3:57 103:53 9:20 34:52 14:43 256:17 10:45
XJu 9:24 54:59 17:11 68:33 1:00 305:01 15:36
XSa 1:56 119:18 6:31 24:17 11:06 240:42 9:10
XUr 1:01 123:08 5:24 21:47 9:46 236:52 8:45
XNe 1:14 120:39 5:45 23:24 10:16 239:21 9:02
XPl 19:55 91:11 1:57 43:46 7:55 268:48 12:00
XX 1:41 32:26 10:51 81:10 20:00 327:20 18:19
XY 20:08 92:55 2:06 42:28 7:59 267:01 11:50
X
X
XMove to another field, RETURN to change this field, ? for help, or q to run
X
XCDT 19:00:00 4/30/1990 | LST 8:19:50 | Lat 44:50:37 | April 1990
XUTC 0:00:00 5/01/1990 | | Long 93:42:08 | Su Mo Tu We Th Fr Sa
XJulianDat 2448012.50000 | Dawn 4:10 | Elev 800 ft | 1 2 3 4 5 6 7
XWatch | Dusk 22:15 | Temp 40 F | 8 FM 10 11 12 13 14
XListing off | NiteLn 5:55 | AtmPr 29.50 in | 15 16 17 18 19 20 21
XSearch off | | TZ 5:00:00 | 22 23 NM 25 26 27 28
XPlot off | NStep 1 | Epoch 2000.0 | 29 30
XMenu Separations | StpSz RT CLOCK | Pause 0 |
X--------------------------------------------------------------------------------
XOb Sun Moon Merc Venus Mars Jup Sat Uranus Nep Pluto X Y
XSu 79:32 4:52 43:59 62:55 56:31 105: 121: 116: 163: 38:21 162:
XMo 79:32 74:49 124: 142: 23:01 175: 160: 164: 106: 99:52 108:
XMe 4:52 74:49 48:43 67:39 51:50 110: 126: 121: 163: 39:57 163:
XVe 43:59 124: 48:43 18:56 100: 61:09 77:00 71:58 129: 38:49 126:
XMa 62:55 142: 67:39 18:56 119: 42:14 58:04 53:04 111: 50:48 108:
XJu 56:31 23:01 51:50 100: 119: 162: 177: 172: 128: 80:40 130:
XSa 105: 175: 110: 61:09 42:14 162: 15:52 10:50 69:37 83:36 67:17
XUr 121: 160: 126: 77:00 58:04 177: 15:52 5:11 54:43 97:18 52:21
XNe 116: 164: 121: 71:58 53:04 172: 10:50 5:11 59:06 92:24 56:46
XPl 163: 106: 163: 129: 111: 128: 69:37 54:43 59:06 125: 2:22
XX 38:21 99:52 39:57 38:49 50:48 80:40 83:36 97:18 92:24 125: 124:
XY 162: 108: 163: 126: 108: 130: 67:17 52:21 56:46 2:22 124:
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X Ephem V4.20 - August 21, 1990
X
X Copyright (c) 1990 by Elwood Charles Downey
X Chaska, Minnesota, USA
X
X downey at dimed.com
X
X
X Table of Contents
X 1. Introduction ................................................... 3
X 2. Running Ephem .................................................. 3
X 2.1. Command Line Format .......................................... 3
X 2.2. Program Operation ............................................ 4
X 3. Screen Fields .................................................. 5
X 3.1. Top Screen Fields ............................................ 6
X 3.2. Data format columns .......................................... 7
X 3.3. RiseSet format columns ....................................... 8
X 3.4. Separation format fields ..................................... 8
X 4. Date and Time Formats .......................................... 8
X 5. Configuration File ............................................. 9
X 5.1. Configuration File fields .................................... 9
X 5.2. Example ephem.cfg ............................................ 11
X 6. Menu options ................................................... 11
X 6.1. Adaptive vs. Standard hzn .................................... 11
X 6.2. Geocentric vs. Topocentric ................................... 12
X 7. User Defined Objects: X and Y .................................. 12
X 7.1. Controlling Object-X or Y Operation .......................... 12
X 7.1.1. Fixed ...................................................... 13
X 7.1.2. Elliptical ................................................. 13
X 7.1.3. Parabolic .................................................. 13
X 7.1.4. Lookup ..................................................... 14
X 7.1.5. On or Off .................................................. 14
X 7.2. Magnitude models ............................................. 14
X 7.2.1. g/k model .................................................. 14
X 7.2.2. H/G model .................................................. 15
X 7.3. Database File ................................................ 15
X 8. Plotting ....................................................... 15
X 8.1. Defining plot fields ......................................... 16
X 8.2. Displaying a plot file ....................................... 16
X 8.3. Cartesian or Polar coords .................................... 16
X 8.4. Begin Plotting ............................................... 17
X 8.5. Stopping Plotting ............................................ 17
X 9. Listing ........................................................ 17
X 10. Watching ...................................................... 17
X 10.1. Trails ...................................................... 17
X 10.2. Sky dome .................................................... 18
X 10.3. Alt/az sky .................................................. 18
X 10.4. Solar System ................................................ 18
X 11. Searching ..................................................... 18
X 11.1. Find extreme ................................................ 19
X 11.2. Find 0 ...................................................... 19
X 11.3. Binary ...................................................... 19
X 11.4. Define a New function ....................................... 19
X 11.4.1. Intrinsic functions ....................................... 20
X
X
X
X
X
X
X
X
X
X - 2 -
X
X
X 11.4.2. Field Specifiers .......................................... 20
X 11.4.3. Constants ................................................. 21
X 11.4.4. Operators ................................................. 21
X 11.5. Specifying Search Accuracy .................................. 21
X 11.6. Stop ........................................................ 21
X 11.7. Example Searches ............................................ 22
X 11.8. Another Example ............................................. 22
X 11.9. Caution ..................................................... 22
X 12. Implementation Notes .......................................... 23
X 12.1. Program limits .............................................. 24
X 13. DOS Installation Procedure .................................... 24
X 13.1. Setting TZ .................................................. 24
X 14. Known Bugs and Wish List ...................................... 25
X 15. Sample Screens ................................................ 26
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X - 3 -
X
X
X 1. Introduction
X
X Ephem is a program that displays ephemerides for all the planets plus any
X two additional objects. The additional objects may be fixed or specified
X via heliocentric elliptical or parabolic orbital elements to accommodate
X solar system objects such as comets or asteroids.
X
X Information displayed about each object includes RA and Dec precessed to
X any epoch, heliocentric coordinates, local azimuth and altitude, distance
X from sun and earth, solar elongation, angular size, visual magnitude,
X illumination percentage, local rise, transit and set times, length of time
X up, and topocentric or geocentric angular separations between all
X combinations of objects.
X
X Observing circumstance information includes UTC and local date and time,
X local sidereal time, times of astronomical twilight, length of day and
X night, local temperature, pressure and height above sea level for the
X refraction model and a monthly calendar.
X
X RA/Dec calculations are geocentric and include the effects of light travel
X time, nutation, aberration and precession. Alt/az and rise/set/transit
X and, optionally, angular separation calculations are topocentric and
X include the additional effects of parallax and refraction.
X
X Plot and listing files of selected field values may be generated as the
X program runs. The plot files are full precision floating point values in
X ASCII intended for input to other plotting programs. The listing files
X are tables formatted for general reading. Ephem includes simple quick-
X look facilities to view these files.
X
X One may watch the sky or the solar system with a simple screen-oriented
X display.
X
X Ephem may be asked to search for interesting conditions automatically,
X using several algorithms. Most fields displayed on the screen may be used
X as terms in an arbitrary arithmetic expression that can be solved for zero
X or minimized or maximized, or the time of state change of any boolean
X expression can be found.
X
X The program is written in C for unix or DOS. It uses only a very simple
X set of io routines and should be easily ported to any ASCII display.
X
X The planetary data and correction algorithms are taken, with permission,
X from "Astronomy With Your Personal Computer", by Peter Duffett-Smith,
X Cambridge University Press, 1985.
X
X 2. Running Ephem
X
X
X 2.1. Command Line Format
X
X To run ephem, just type "ephem". You may also specify an alternate
X configuration file, an alternate database file, and specify initial values
X for several screen fields. The command line syntax can be summarized as
X
X
X
X
X
X
X
X
X
X - 4 -
X
X
X follows:
X
X ephem [-c <config_file>] [-d <database_file>] [field=value ...]
X
X
X The default configuration file is named ephem.cfg in the current
X directory. Ephem also looks for one named by the EPHEMCFG environment
X variable, if it is set. You may specify an arbitrary name with the -c
X option.
X
X The default database file is named ephem.db in the current directory.
X Ephem also looks for one named by the EPHEMDB environment variable, if it
X is set. You may specify an arbitrary name with the -d option.
X
X The exact format of these files is described below.
X
X Any additional command line arguments are treated exactly as if they too
X came from the configuration file.
X
X 2.2. Program Operation
X
X When ephem starts, it first displays a disclaimer banner. Then, after any
X key is pressed, it reads the configuration file and processes the command
X line arguments to set the initial values of several fields, accessing the
X database file if OBJX or OBJY is set, It then draws all fields on the
X screen with their initial values. The program then loops advancing time
X each step, by some amount you may control, and updating all fields each
X loop.
X
X There are three fields that control this looping behavior. NStep controls
X the number of steps, StpSz the amount of time to add each step, and Pause
X is the amount of real seconds to pause between steps. Ephem does not
X pause between steps when plotting or searching is on. When the number of
X steps, NStep, goes to 0 or any key is pressed, the looping stops and you
X enter a command mode.
X
X Command mode allows you to modify most of the fields. The idea is that
X you move to each field on the screen you wish to change and change it.
X When you have changed everything you want to, type "q" to resume screen
X updates.
X
X To change a field:
X
X 1) move the cursor to the field (see below);
X 2) type RETURN;
X 3) type in the new value along the command line at the top according
X to the format indicated in the prompt. To accept the new value
X type RETURN, or to leave it unchanged after all type "q".
X
X
X A few fields don't require you to type anything; just typing RETURN does
X all the work. If you can't move to it, you can't change it.
X
X The arrow keys on most systems move the cursor around. If these do not
X
X
X
X
X
X
X
X
X
X - 5 -
X
X
X function or function incorrectly, the h/j/k/l keys also move the cursor
X left/down/up/right, respectively. Motions off any edge of the screen will
X wrap around.
X
X Several "hot-keys" move the cursor immediately to frequently used fields.
X You may move the cursor immediately to a planet row by typing one of the
X characters SMevmjsunpxy. To avoid conflict with j, jupiter's row must
X actually be typed as control-j. "x" and "y" are for the user-defined
X objects X and y on the bottom rows. Also, the characters c, d, o, w, L
X and z move you to the Menu, UT Date, Epoch, Watch, Listing and StpSz
X fields immediately.
X
X When you have changed a field that would invalidate any of the other
X fields the message NEW CIRCUMSTANCES appears in the top center of the
X screen. This will remain until you type "q" to allow at least one screen
X update loop to occur. If you change any field that causes new
X circumstances, the StpSz value is not added to the first loop. Note also
X that after a series of loops, NStep is automatically reset to 1 so "q"
X will do exactly one loop and return you to command mode.
X
X On some systems, you may temporarily escape from ephem while in command
X mode to run your operating system's command interpretor. This is done by
X typing an exclamation point (!) followed by your command. When the
X command completes, you will return back to ephem where you left off.
X
X To quit the program, type control-d from command mode. For a little more
X help, type ?. The entire screen may be erased and redrawn with control-l.
X
X 3. Screen Fields
X
X The screen is divided into two halves, top and bottom. The top fields are
X always present. They define the general observing circumstances and
X control features.
X
X The planets and two additional objects are displayed in a table in the
X bottom portion of the screen. There is one object per row, and several
X columns. There are three forms of this portion selected by picking the
X Menu selection.
X
X Some things may be turned off to reduce compute times. Calculations for
X each planet may be turned on and off by selecting the planet name field.
X Calculations for Dawn/Dusk/NiteLn may be turned off by selecting any of
X these fields. Planet positions are only updated as often as necessary to
X match the display precision of the screen unless plotting or searching is
X on. In these cases full precision is desired at all times and so
X positions are always fully recalculated at each iteration.
X
X Follows is a list and description of each of the fields in each section.
X Following each name a parenthetical "p" indicates the field may be
X selected for plotting (see later). All fields may be selected for
X changing.
X
X
X
X
X
X
X
X
X
X
X
X
X - 6 -
X
X
X 3.1. Top Screen Fields
X
X LTZ the local timezone name. The name field may be changed to
X any three-character mnemonic.
X LT(p)
X LD(p) The local time and date are not labeled as such but are to
X the right of the local timezone name. They are individually
X selectable. Time and date fields may be changed as
X described in a later section. Set to "n" to set to "now"
X from computer clock.
X UT(p)
X UD(p) The universally coordinated time and date are not labeled as
X such but are to the right of the UTC label. They are
X individually selectable. Time and date fields may be
X changed as described in a later section. Set to "n" to set
X to "now" from computer clock.
X JulianDat(p) the current Julian date, to about 1-second accuracy.
X Listing controls listing; see complete discussion below.
X Watch selects the sky dome, altitude/azimuth sky or solar system
X displays; see complete discussion below.
X Search controls the automatic search feature of ephem. See the
X complete discussion below.
X Plot controls plotting; see complete discussion below.
X Menu controls which menu is in the bottom half of the screen.
X See their complete discussion below.
X LST(p) the current local sidereal time. set to "n" to set from
X computer clock.
X Dawn(p) local time when the sun center is 18 degrees below the
X horizon before sunrise today.
X Dusk(p) local time when the sun center is 18 degrees below the
X horizon after sunset today.
X NiteLn(p) length of astronomical night, ie, Dawn - Dusk. If this line
X is shown as "-----", it means the sun is either always below
X or always above approximately -18 degrees altitude on this
X particular day. This and the Dawn and Dusk lines are blank
X when their computation has been turned off.
X NStep The number of times the display with be updated (time
X advanced by StpSz each step) before entering command mode.
X StpSz the amount of time UTC (and its derivatives) is incremented
X each loop. set this to "r" to use real-time based on the
X computer clock. you may also set it in terms of days by
X appending a "d" after the number when you set it.
X Lat(p) location latitude, positive degrees north of equator.
X Long(p) location longitude, positive degrees west of Greenwich
X meridian. set to "N" to set from computer clock.
X Elev(p) local elevation of the ground above sea level, in feet. (see
X implementation notes).
X Temp(p) local surface air temperature, in degrees F.
X AtmPr(p) local surface air pressure, in inches of mercury.
X TZ(p) hours local time is behind utc, ie, positive west or
X negative east of Greenwich.
X Epoch the epoch, to the nearest 0.1 years, to which the ra/dec
X fields are precessed. This says (OfDate) when coordinates
X are not precessed, ie, are in the epoch of date. Set to "e"
X
X
X
X
X
X
X
X
X
X - 7 -
X
X
X to set to epoch of date.
X Pause number of seconds to pause between screen updates. This is
X used mainly to set up for free-running unattended operation.
X This pause also applies to free-running "watch" screen
X updates. Pausing is not done when plotting or searching is
X on. If pausing is used with StpSz set to RT CLOCK and the
X time was set with Now then ephem attempts to synchronize the
X time to an integral multiple of pause seconds after the
X minute, for aesthetic reasons.
X Also in the upper right of the screen is a calendar for the current local
X month. Dates of new and full moons are marked NM and FM, respectively.
X
X 3.2. Data format columns
X Ob name of object. Select this to toggle the display and
X calculations on and off.
X R.A.(p) apparent geocentric right ascension of object, precessed to
X given epoch, in hours, minutes and decimal minutes.
X Dec(p) apparent geocentric declination of object, precessed to
X given epoch, in degrees and minutes.
X Az(p) degrees eastward of true north for object.
X Alt(p) degrees up from a horizontal plane Elev feet above sea
X level.
X H Long(p) true heliocentric longitude, in degrees. Earth's is
X displayed on the sun's line. For the moon this is the
X geocentric longitude.
X H Lat(p) true heliocentric latitude, in degrees. For the moon this
X is the geocentric latitude.
X Ea Dst(p) true distance from Earth center to object center, in AU,
X except distance to the moon is in miles.
X Sn Dst(p) true distance from sun center to object center, in AU.
X Elong(p) spherical angular separation between sun and given object,
X calculated from the their geocentric ecliptic coordinates.
X Note this is not just difference in ecliptic longitude. The
X sign, however, is simply sign(obj's longitude - sun's
X longitude), ie, degrees east. thus, a positive elongation
X means the object rises after the sun.
X Size(p) angular size of object, in arc seconds.
X VMag(p) visual magnitude of object.
X Phs(p) percent of visible surface in sunlight. Note the moon phase
X is calculated simplistically as just abs(elongation)/180*100
X which can be a few degrees off... this means that because of
X how elongation is defined it doesn't say 0 during new moon
X (or 100 during full) except during close eclipses (maybe
X that's a "feature"?).
X Also, some terminals scroll when a character is written to the lower right
X character position. To avoid this, Object Y's phase is left shifted by one
X column. This can look particularly ugly when the phase is 100% because the
X "100" is right next to visual magnitude number.
X If desired, the angle between Earth and Sun from the object, p, can be
X computed from the illumination percentage, i, with the following relation:
X
X cos (p) = i/50 - 1
X
X
X
X
X
X
X
X
X
X
X
X - 8 -
X
X
X 3.3. RiseSet format columns
X Rise Time
X Rise Az The local time and azimuth when the upper limb of the object
X rises today.
X Transit Time
X Transit Alt The local time and altitude when the object crosses the
X meridian today, ie, when its azimuth is true south or, if no
X precession, when the local sidereal time equals the object's
X right ascension.
X Set Time
X Set Az The local time and azimuth when the upper limb of the object
X sets today.
X Hours Up The number of hours the object is up on the local date.
X
X Horizon displacement may be calculated in either of two ways; see the
X horizon discussion in the Menu selection section.
X
X Various oddball conditions are accounted for, including an object that is
X up sometime during the day but that doesn't rise, transit or set as such
X on that day, an object that is circumpolar or that is never up or one that
X rises twice on the same day. These are marked as "Never rises", "Never
X transits", "Never sets", "Circumpolar", "Never up" or appended with a plus
X "+" sign, respectively.
X
X 3.4. Separation format fields
X This format is a table of angular separations between each pair of
X objects. These angles are based on the local altitude/azimuth, and so in
X general differ somewhat from the elongations reported for the sun in the
X Data menu.
X Unfortunately, with the format "ddd:mm", there is not enough room for a
X space between columns when the angle is at least 100 degrees. To avoid
X this, I drop the minutes portion if the (rounded) angle is at least 100
X degrees.
X
X 4. Date and Time Formats
X Times are displayed and entered in h:m:s format. If you pick a time field
X to change it any of the h, m, and s components that are not specified are
X left unchanged from their current value. For example, 0:5:0 set hours to
X 0, minutes to 5, seconds to 0, whereas :5 sets minutes to 5 but leaves
X hours and seconds unchanged. A negative time is indicated by a minus sign
X (-) anywhere before the first digit.
X
X Dates are displayed and entered in American month:day:year format. As
X with time, components omitted when entering a new value retain the current
X value. For example, if the current date is 10/20/1988 and you type 20/20
X the new date will become 20/20/1988. Note you must type the full year
X since the program is accurate over several centuries either side of 1900.
X If you change the date, the time (ie, partial day) will not change.
X
X Two other ways to set the date are supported for compatibility with some
X published comet ephemerides. You may enter the day portion as a real
X number. When you set the day this way, the time will also change to
X correspond to the fractional portion of the day.
X
X
X
X
X
X
X
X
X
X
X - 9 -
X
X
X You may also enter a date as a decimal year, as in 1990.12345. This is
X also useful in interpreting plot files that include a date field, since
X date fields are stored in plot files as decimal years. If no decimal
X point is included, the number is assumed to be a year unless it is in the
X range 1-12, in which case it will be taken to mean that you are just
X changing the month of the current date. To actually specify the years 1 -
X 12, you must append a decimal point to distinguish them from months.
X
X As a matter of typing convenience, the program accepts most any character
X as the separator; you don't have to type a perfect ":" or "/".
X
X 5. Configuration File
X The ephem.cfg configuration file allows you to set the initial values of
X many of the screen fields. You can still change any field while the
X program is running too; this file just sets the initial conditions. Note
X that the order of entries in this file is important because they each take
X effect immediately. You should put them in the same order you wish them
X to be processed, just as though you were changing the fields interactively
X within ephem.
X
X The default name of the file is ephem.cfg. Ephem also looks for one named
X by the EPHEMCFG environment variable (if defined) or you may specify any
X name using the -c command line option.
X
X The format of the file uses the form KEYWORD=VALUE, where the possible
X KEYWORDS and the types of VALUES for each are described below. Any
X KEYWORDS not in the file will take on some sort of default. The separator
X need not be an actual equals sign; any char will do because the VALUE is
X assumed to start one character after the KEYWORD, regardless.
X
X Blank lines and lines that begin with an asterisk (*) or whitespace (space
X or tab) are ignored and may be used for comments.
X
X Note: because of the way unspecified time and date components are left
X unchanged (see section on Date and Time Formats) always specify the
X complete time and date for all entries in the configuration file. For
X example, to initialize the longitude to zero degrees, say 0:0:0, not just
X 0.
X
X 5.1. Configuration File fields
X UD initial UTC date, such as 10/20/1988, or "NOW" to use the
X computer clock.
X UT initial UTC time, such as 12:0:0, or "NOW" to use the computer
X clock.
X TZONE hours the local time is behind utc, such as 5:0:0. you need not
X set this if you use "NOW" for UT or UD.
X TZNAME name of the local time zone, such as CDT. 3 chars max. you need
X not set this if you use "NOW" for UT or UD.
X LONG longitude, in degrees west of Greenwich, in the form d:m:s.
X LAT latitude, in degrees north of the equator, in the form d:m:s.
X HEIGHT height above sea level, in feet, such as 800
X TEMP air temperature, in degrees F, such as 50
X
X
X
X
X
X
X
X
X
X
X
X - 10 -
X
X
X PRES air pressure, in inches of Mercury, such as 29
X STPSZ the time increment between screen updates, such as "1" to give
X one hour updates. this can be a specific amount or RTC to use
X the system clock as a real-time source. You may also specify a
X time in days, by appending a D (or d) after the number.
X PROPTS this selects what you want included initially in the display.
X since IBM-PC math is not very fast, you can reduce the time to
X update the screen by only printing those fields of interest. the
X VALUE is a collection of letters to turn on each item from the
X following set:
X
X T twilight (dawn-dusk)
X S circumstances for the sun
X M circumstances for the moon
X e circumstances for mercury
X v circumstances for venus
X m circumstances for mars
X j circumstances for jupiter
X s circumstances for saturn
X u circumstances for uranus
X n circumstances for neptune
X p circumstances for pluto
X x circumstances for object X
X y circumstances for object Y
X
X For example, to just track the sun and saturn, say PROPTS=Ss
X
X If the delimiter between PROPTS and the selection is a plus (+)
X sign then the given planets are included IN ADDITION TO ones
X already specified. Any other delimiter sets the selection to
X exactly the set specified. This feature was added so that the
X command line version of using PROPTS could add to the set of
X planets giving in the configuration file.
X NSTEP number of times program will loop before entering command mode.
X see the discussion under Program Operation.
X EPOCH this sets the desired ra/dec precession epoch. you can put any
X date here or EOD to use the current instant ("Epoch of Date").
X OBJX
X OBJY These fields specify the optional objects "x" and "y" by naming
X any item in the database file. The form is OBJX=xyz, where xyz
X must be in the database file, case sensitive. You may define
X one object of each type for each of OBJX and OBJY; the last one
X defined will be the "current" one when ephem gets going.
X PAUSE The number of seconds to pause between calculation steps. See
X definition of the Pause field in the "Top Screen Fields"
X section.
X MENU establishes the initial bottom screen menu type. This should be
X one of the keywords DATA, RISET or SEP. There is no way to set
X horizon or center suboptions at this time.
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X - 11 -
X
X
X 5.2. Example ephem.cfg
X
X This is the ephem.cfg file that was in effect when the sample screens (in
X another section) were generated. You might run ephem with this
X configuration file and compare with the samples as a check.
X
X UT=0;0;0
X UD=5/1/1990
X TZNAME=CDT
X TZONE=5
X LONG=93:42:8
X LAT=44:50:37
X HEIGHT=800
X TEMP=40
X PRES=29.5
X STPSZ=RTC
X PROPTS=TSMevmjsunpxy
X EPOCH=2000
X NSTEP=1
X
X OBJX=Austin
X OBJY=Juno
X
X As another common example, this ephem.cfg creates an essentially free-
X running real-time screen based on the computer clock:
X
X UT=Now
X LONG=90:10:8
X LAT=40:50:20
X HEIGHT=800
X TEMP=50
X PRES=29
X STPSZ=RTC
X PROPTS=TSMevmjsunp
X NSTEP=9999999
X EPOCH=Eod
X PAUSE=30
X
X
X 6. Menu options
X
X When you select "Menu" you can change among the three styles of bottom
X screens. There are also two options that can be set from the Menu quick-
X choice menu. These options toggle when picked and retain their values so
X they need only be changed when desired.
X
X 6.1. Adaptive vs. Standard hzn
X
X This selects the horizon refraction displacement algorithm used by the
X Rise/Set menu. "Adaptive" uses the local atmospheric conditions known to
X ephem and matches the Planet Info times nicely. "Standard" uses the
X "accepted nominal" horizon refraction value of 32 arc minutes and usually
X agrees, to a minute or so, with published tables.
X
X
X
X
X
X
X
X
X
X
X - 12 -
X
X
X 6.2. Geocentric vs. Topocentric
X
X This selects the vantage point for the Separation menu. "Geocentric"
X ignores local conditions and gives the separation as seen from Earth
X center. "Topocentric" uses the local conditions known to ephem. They are
X particularly critical for lunar occultations, but the effect can be
X significant for the planets.
X
X Note that searching over a period that will include the rise or set times
X of either object is generally better performed from the geocentric
X viewpoint. The refraction effect of the topocentric viewpoint causes many
X arcminutes of rapid whiplash displacement as the objects rise and set that
X overlays the smooth celestial motion of the objects. This rapid position
X variation can confuse the solver algorithms that expect fairly smooth
X functions.
X
X 7. User Defined Objects: X and Y
X
X You may specify one or two extra objects for ephem to use. The objects may
X be defined in three different ways: fixed celestial sphere coordinates,
X or heliocentric elliptical or parabolic orbital elements. Elliptical
X elements are typically useful for periodic comets or asteroids, and
X parabolic elements are for nonrecurring solar system interlopers such as
X aperiodic comets.
X
X The parameters for each type of object are stored separately, so you may
X switch between types of objects without losing parameters.
X
X 7.1. Controlling Object-X or Y Operation
X
X To control the type and the corresponding details for object X or Y,
X select the corresponding row near the bottom. (Remember that typing the
X character "x" or "y" is a shorthand way to move to the bottom rows.) It
X will bring up a quick-choice menu as follows:
X
X Select: Fixed, Elliptical, Parabolic, Lookup, On
X
X
X When you first enter the quick-choice menu the cursor will start out
X positioned at the field for the current type of object. The first three
X selections allow you to enter or review the various parameters required to
X define an object's position of such type, one parameter at a time.
X
X You set the current object type and begin to view its parameters by
X positioning the cursor over the type and pressing RETURN. The prompt for
X each item includes a short description, the units to use, and its current
X setting is shown in parentheses. To leave the item unchanged and go to the
X next item, type RETURN. If you do not wish to change or see any more
X items about the object then type "q" and you will return immediately to
X the object-X quick-choice menu.
X
X You exit the quick-choice menu by typing "q" while over any field or
X RETURN while over On or Off, as described in a later section.
X
X
X
X
X
X
X
X
X
X
X - 13 -
X
X
X As with all dates throughout ephem, the dates for the epochs of perihelion
X and reference epochs may be entered in month/day/year or decimal year
X formats, and the day may be entered as a real number (see the section on
X Date and Time Formats). All dates given for comet parameters are always
X in UT.
X
X 7.1.1. Fixed
X
X This selection will present a series of five prompts, the name and one
X each for the RA, Dec, magnitude and the reference epoch for the
X coordinates of a fixed object.
X
X 7.1.2. Elliptical
X
X This will begin a series of twelve prompts asking for a name and the
X parameters that define a heliocentric elliptic orbit and the coefficients
X for either of two magnitude models. These elements are the same ones
X often listed in the Astronomical Almanac. The elements are, in order:
X
X i = inclination, degrees
X O = longitude of ascending node, degrees
X o = argument of perihelion, degrees
X a = mean distance (aka semi-major axis), AU
X n = daily motion, degrees per day
X e = eccentricity
X M = mean anomaly (ie, degrees from perihelion)
X E = epoch date (ie, time of M)
X D = the equinox year (ie, time of i/O/o)
X g/k or H/G = either of two magnitude models; see below
X
X
X You might have other parameters available that can be converted into
X these. For example, we have the following relationships:
X
X P = sqrt(a*a*a)
X p = O + o
X n = 360/days_per_year/P ~ 0.98563/P
X T = E - M/n
X q = a*(1-e)
X where
X P = the orbital period, years;
X p = longitude of perihelion, degrees
X n = daily motion, degrees per day;
X T = epoch of perihelion (add multiples of P for desired range)
X q = perihelion distance, AU
X
X Note that if you know T you can then set E = T and M = 0.
X
X 7.1.3. Parabolic
X
X This will begin a series of nine prompts asking for a name and the
X parameters that define a heliocentric elliptic orbit and the magnitude
X model coefficients. These orbital parameters are, in order:
X
X
X
X
X
X
X
X
X
X
X - 14 -
X
X
X epoch of perihelion,
X inclination,
X argument of perihelion,
X perihelion distance,
X longitude of the ascending node,
X and the reference epoch of the parameters.
X absolute magnitude, g
X luminosity index coefficients, k
X
X
X 7.1.4. Lookup
X
X This option lets you define an object from any of those listed in the
X database file, described in a subsequent section.
X
X If successful, the cursor will move to the type of the new object and it
X becomes the current type.
X
X 7.1.5. On or Off
X
X The last selection on the right toggles the calculations for the object On
X and Off. It toggles when selected with RETURN and then immediately exits
X the quick-choice menu back to the main menu. If calculations become On,
X then they will be performed for the current type of object; if they become
X Off the object-X or Y row of information will be erased.
X
X 7.2. Magnitude models
X
X Ephem supports two different magnitude models. One, denoted here as g/k,
X is generally used for comets and may be used for parabolic and elliptical
X objects. The other, denoted H/G, is generally used for asteroids and is
X the one used in the Astronomical Almanac.
X
X 7.2.1. g/k model
X
X This model requires two parameters to be specified. One, the absolute
X magnitude, g, is the visual magnitude of the object if it were one AU from
X both the sun and the earth. The other, the luminosity index, k,
X characterizes the brightness change of the object as a function of its
X distance from the sun. This is generally zero, or very small, for inactive
X objects like asteroids. The model may be expressed as:
X
X m = g + 5*log10(D) + 2.5*k*log10(r)
X where:
X m = resulting visual magnitude;
X g = absolute visual magnitude;
X D = comet-earth distance, in AU;
X k = luminosity index; and
X r = comet-sun distance.
X
X Note that this model does not take into account the phase angle of
X sunlight.
X
X When using this model for elliptical objects, the first of the two
X
X
X
X
X
X
X
X
X
X - 15 -
X
X
X magnitude fields must be preceded by a letter "g" in both the ephem.db
X database file and the corresponding quick-choice elliptical object
X definition prompt; otherwise the default is the H/G model.
X
X 7.2.2. H/G model
X
X This model also requires two parameters. The first, H, is the magnitude of
X the object when one AU from the sun and the earth. The other, G, attempts
X to model the reflection characteristics of a passive surface, such as an
X asteroid. The model may be expressed with the following code fragment:
X
X beta = acos((rp*rp + rho*rho - rsn*rsn)/ (2*rp*rho));
X psi_t = exp(log(tan(beta/2.0))*0.63);
X Psi_1 = exp(-3.33*psi_t);
X psi_t = exp(log(tan(beta/2.0))*1.22);
X Psi_2 = exp(-1.87*psi_t);
X m = H + 5.0*log10(rp*rho) - 2.5*log10((1-G)*Psi_1 + G*Psi_2);
X where:
X m = resulting visual magnitude
X rp = distance from sun to object
X rho = distance from earth to object
X rsn = distance from sun to earth
X
X Note that this model does not take into account the phase angle of
X sunlight.
X
X 7.3. Database File
X
X You may save a list of objects in a file to be used for setting OBJX and
X OBJY. The default name of this file is ephem.db. You may also set it from
X the command line with the -d option, or set it with the EPHEMDB
X environment variable.
X
X The file consists of one object per line. Lines that begin with an
X asterisk (*) are ignored. Each line contains several fields, each
X separated by a comma. The first field is the name of the object. The
X second field is the type of the object, that is, one of the strings
X "fixed", "elliptical", or "parabolic"; actually, "f", "e" and "p" are
X sufficient. The remaining fields depend on the type of object. They are
X exactly the same parameters, and in the same order, as ephem asks for when
X defining the object from the menu.
X
X 8. Plotting
X
X Each time a field is drawn on the screen during a full screen update cycle
X (that as, during automatic looping or a manual "q" command character from
X the main menu but not from a screen redraw from control-l or when an
X individual planet is turned on or a single time field is changed) its
X full-precision value may be written to a file. This implies you may not
X plot a field from other than the current menu at the time plotting is on.
X You can append several plot runs together, however, if necessary.
X
X Each line in the file consists of a tag character followed by two or three
X floating point variables, all separated by commas. If there are two
X
X
X
X
X
X
X
X
X
X - 16 -
X
X
X values, they should be interpreted to be x and y (or perhaps r and theta).
X If there is a third, it is a z or trace value.
X
X For efficiency on systems that can compute a screen full faster than they
X can display it, screen updates are suppressed while plotting is on and
X NStep is greater than 1. This can greatly reduce the time to generate a
X long plot file. Fields are still logged for plotting; they just are not
X drawn on the screen.
X
X The Plot field controls plotting. Whether plotting is currently active is
X indicated by "on" or "off" immediately to its right.
X
X Picking "Plot" brings up a quick-choice menu, as follows:
X
X Select: Select fields, Display a plot file, Cartesian coords, Begin plotting
X
X
X 8.1. Defining plot fields
X
X Select the "Select fields" option. You will be asked to move the cursor
X to the field you want to use as the x coordinate (abscissa), then asked to
X choose the y coordinate (ordinate), then asked to choose an optional z
X trace variable and finally a tag character. (Of course, you may have in
X mind fields that are more appropriately displayed in other than Cartesian
X coordinates, in which case think of x, y and z as dimensions.) If you type
X q for either x or y then no more fields will be defined. If you type q
X for the z field there will be no z field. You can not label a plot line
X with the letter "q" at this time.
X
X This then repeats so you may choose up to ten of these sets for any given
X plot run. Each set defines what will become a line on the final plot.
X Note that you may select the "Search" field to indicate use of the current
X search function; that function must be defined by the time plotting is
X turned on.
X
X If you turn plotting off and back on the fields selected for plotting are
X reactivated the same as they were last time. You may change them if
X desired, of course, but there is no need to redefine them if you do not
X wish to change them.
X
X 8.2. Displaying a plot file
X
X Select the "Display a plot file" option to generate a crude plot on the
X screen of an existing plot file previously created by ephem. The entries
X in the file will be drawn on the screen using their tag characters; the
X plot remains on the screen until you type any character.
X
X The plot may be made in polar or Cartesian coordinates, depending on the
X setting of the plotting mode in the quick-choice (see next section).
X
X 8.3. Cartesian or Polar coords
X
X This toggles the plotting mode coordinate system. The mode remains until
X changed. Polar coordinates assume the first numeric field in the plot
X
X
X
X
X
X
X
X
X
X - 17 -
X
X
X file is the radius, and the second is the angle counterclockwise from
X right, in degrees.
X
X 8.4. Begin Plotting
X
X If plot field lines are defined then the third option, "Begin plotting"
X will be available. You will be asked for the name of the file to use. If
X it already exists you will be asked whether to overwrite it or append to
X it. You will also be asked for a title line that will become the next
X line of the file, automatically prefixed with a "*" to make it a valid
X comment line. Once you have chosen a file, plotting is on and the top
X menu plotting status field changes to "on". The default plot file name is
X ephem.plt. The values are written to the plot file each time they are
X updated on the screen until you select "Plot" again and select the "Stop"
X option to turn plotting back off.
X
X 8.5. Stopping Plotting
X
X If plotting is on, then selecting the Plot field in the top section will
X turn plotting off. You may pick Plot again and resume with the same fields
X by selecting "Begin plotting" again.
X
X Note that due to internal buffering the plot file will not be completely
X written to disk until plotting is turned off.
X
X 9. Listing
X
X This feature works very much like Plotting. However, the fields you select
X define columns of a table generated as ephem runs. These columns are look
X exactly like their corresponding fields on the ephem screen and so are far
X more readable than plot files.
X
X See the section on Plotting for an explanation of the quick-choice menu.
X The general operation is very much the same.
X
X 10. Watching
X
X You may generate a simple drawing on the screen of the local sky in two
X forms or the solar system by selecting "Watch". It will bring up a
X quick-choice menu as follows:
X
X Select: Sky dome, Alt/az sky, Solar system, No trails
X
X
X 10.1. Trails
X
X You may either erase after each iteration or leave the tags up, referred
X to as "trails". Picking the right-most choice will toggle between "No
X trails" and "Leave trails"; you should set it as desired before you select
X the style of sky plot you wish. Ephem will remember your selection.
X
X
X
X
X
X
X
X
X
X
X
X
X
X - 18 -
X
X
X 10.2. Sky dome
X
X This draws the currently active planets within a circle that represents
X the locally visible hemisphere. This is similar to the formats commonly
X used in the popular astronomy magazines. East is left, south is down,
X west is right and north is up.
X
X 10.3. Alt/az sky
X
X This is a cylindrical projection showing the currently active planets as
X they would appear in the sky looking southwards at the current time and
X date. The coordinate system is such that 0 degrees azimuth (north)
X through 360 degrees (north, once around) is mapped to the horizontal
X screen dimension, and 0 degrees altitude (level) through 90 degrees (the
X zenith) is mapped to the vertical dimension. Thus, the bottom row is the
X horizon and all across the top is the zenith.
X
X 10.4. Solar System
X
X This selection draws the currently active planets as they would appear
X looking "down from the top" of the ecliptic, with the sun at the center
X and zero hours right ascension towards the right. The scale is adjusted
X to roughly fill the screen according to the outer-most active planet.
X Note that the scaling does not take into account the distances of the user
X defined objects so, if they don't appear, select a planet that is at least
X as far out as they are. The screen transformation assumes a screen aspect
X width/height ratio of 4/3. Down the left column of the screen is the
X heliocentric altitude of the planet above or below the ecliptic, drawn to
X the same scale as the circular display. Values so close as to land on the
X same line are sorted left to right; the S and E symbols always denote
X heliocentric altitude 0.
X
X In each style of display, pressing RETURN advances the time by whatever
X amount StpSz is set to. Pressing "h" advances the time by one hour, "d"
X advances by one day, and "w" advances by one week (seven days). Pressing
X "q" returns to the watch quick-choice menu from which you may select
X another display style or return to the main tabular display by typing
X another "q". Pressing any other key starts an automatic loop with each
X step advancing by StpSz; pressing any key stops the looping.
X
X As symbols are placed, collisions (overstrikes) are avoided by moving
X characters in such a way as to maintain increasing sorted order towards
X the right.
X
X When you return to the main menu, the last watched time will be maintained
X as the current time. The StpSz is not changed.
X
X 11. Searching
X
X Ephem can search for arbitrary conditions to exist among most displayed
X fields. You first enter a function, then select from among three forms of
X equation solvers to iteratively solve for the next time when the function
X meets the requirements of the solver. The solver selects the next time for
X which it wants the function evaluated and sets StpSz so that the next
X
X
X
X
X
X
X
X
X
X - 19 -
X
X
X iteration will occur at that time. The solvers continue to iterate until
X either they achieve their goal or NStep reaches 0.
X
X You may set NStep to be quite large and let ephem search unattended or set
X it to 1 and watch it converge one step at a time. You may also plot at the
X same time as search to record the exact steps ephem took to converge.
X (But recall that screen updates are suppressed if plotting is also on).
X
X The "Search" selection in the top half of the screen controls all
X searching. Picking it brings up a quick-choice menu as follows:
X
X Select: Find extreme, Find 0, Binary, New function, Accuracy
X
X
X 11.1. Find extreme
X
X This search algorithm searches for a local maximum or a minimum in the
X search function, whichever it finds first. It begins by evaluating the
X search function at the current time then for two more times each separated
X by StpSz. It then fits these three points to a parabola and solves it for
X the time of its maximum (or minimum). StpSz is set so that the next
X iteration will evaluate at this point. This parabolic fit solution keeps
X repeating until StpSz changes by less than the desired accuracy or until
X the curve becomes so flat that an extrema appears too broad to find.
X
X 11.2. Find 0
X
X This search algorithm uses the secant method to solve for the time at
X which the search function is zero. The function is evaluated at the
X current time and then again StpSz later to establish a slope for which the
X x-intercept is found as the next zero guess. This is used to set StpSz for
X the next desired time value and the slope hunting process repeats until
X StpSz changes by less than the desired accuracy.
X
X 11.3. Binary
X
X This search algorithm must be used with a search function that yields a
X boolean result, ie, a true or false value. The idea is that the function
X is assumed to be one truth value when evaluated at the present time, and
X the opposite truth value when it is evaluated StpSz later. The algorithm
X will then do a binary search for the time when the truth value changes.
X
X The binary algorithm does not begin until the state change is bounded in
X time. Initially, as long as the truth value at StpSz is the same as the
X previous value the algorithm will just keep moving in time by StpSz
X looking for when the state changes. That is, a linear search is initiated
X to bound the state change, then the binary search proceeds.
X
X 11.4. Define a New function
X
X Select "New function" to display the current search function. If you type
X "q" it will be left unchanged. If you type RETURN it will be erased. If
X you type anything else it will be compiled and, if there are no errors, it
X will become the new search function. Once a valid function has been
X
X
X
X
X
X
X
X
X
X - 20 -
X
X
X stored, it will remain unless changed. If a search function is selected
X and there is as yet no valid search function defined, you will
X automatically be asked to enter one as though you had selected "New
X function."
X
X A search function consists of intrinsic functions, field-specifiers,
X constants and operators, and precedence may be overridden with
X parentheses.
X
X
X 11.4.1. Intrinsic functions
X
X In this release, the only intrinsic function available is abs(), which
X returns the absolute value of its argument.
X
X 11.4.2. Field Specifiers
X
X A field in the bottom half of the menu is specified in the form of
X "object_name.column_name". The object_name is enough of the planet name to
X be unique; use "x" or "y" for the user-specified object X or Y. The
X column_name is from the following table, depending on which menu is up. In
X all cases additional characters may be entered but are ignored.
X
X Planet Data Menu Rise/Set Menu Separation Menu
X ------------------ -------------------- ---------------
X al Alt hr Hrs Up, or j Jup
X az Az hu Hrs Up ma Mars
X d Dec raz Rise Az me Merc
X ed Ea Dst rt Rise Time mo Moon
X el Elong saz Set Az n Nep
X hla Helio Lat st Set Time pl Pluto
X hlo Helio Long ta Transit Alt sa Saturn
X ph Phs tt Transit Time su Sun
X ra R.A. u Uranus
X sd Sn Dst ve Venus
X si Size
X vm VMag
X
X
X In addition, the following top-half fields may be used:
X
X da Dawn
X du Dusk
X n NiteLn
X
X
X
X Remember, searching may only involve fields being calculated for display
X at the time the solver is active. While you can syntactically include any
X field in a search function it is useless to define a search that uses
X fields from other than the menu that is selected at the time the search is
X running.
X
X
X
X
X
X
X
X
X
X
X
X - 21 -
X
X
X 11.4.3. Constants
X
X Constants may be integers or floating point numbers. The latter may be
X expressed in scientific notation if desired. Examples include 100, .9,
X 1.234, 1e10 and 1.2e-4. Any number may be preceded by - to make it
X negative.
X
X 11.4.4. Operators
X
X The collection of arithmetic, relational and boolean operators provided
X mimics those of C language as listed in the following table, in decreasing
X order of precedence. Operators grouped together have the same precedence
X and all have left-to-right associativity. Parentheses may be used as
X desired.
X
X Symbol Meaning Resulting type
X ------ -------------------- --------------
X * multiply arithmetic
X / divide arithmetic
X
X + add arithmetic
X - subtract arithmetic
X
X > greater than boolean
X >= greater than or equal boolean
X < less than boolean
X <= less than or equal boolean
X
X == equality boolean
X != inequality boolean
X
X && logical and boolean
X
X || logical or boolean
X
X
X 11.5. Specifying Search Accuracy
X
X Selecting "Accuracy" allows you to specify when the search will stop. The
X search algorithms will stop when StpSz becomes equal to or less than this
X value. The default is one minute. If ephem has not yet converged to the
X specified accuracy but NStep has decremented to 1, the searching will stop
X but the search status field will still indicate which search procedure is
X in effect. To try more iterations you may increase NStep and resume
X searching. If the accuracy was achieved, the search status field will
X switch to "off" with the number of "unused" steps remaining in NStep and
X the last step size in the StpSz fields.
X
X 11.6. Stop
X
X If searching is on, this option will also appear on the quick-choice menu
X and may be selected to turn off the search.
X
X
X
X
X
X
X
X
X
X
X
X - 22 -
X
X
X 11.7. Example Searches
X
X As an example, let's find when Pluto again becomes the furthest planet
X from Sol. You may find when the difference in their sun distance is zero,
X or you might use a binary search on the condition that Pluto's sun
X distance is larger then Neptune's.
X
X To try the former approach select Search, select "Find 0", specify the
X search function to be:
X
X pl.sd - nep.sd
X
X set StpSz to something large like 10d, NStep to allow several iterations
X like 20, and then type "q" to start the search and watch ephem do the
X hunt. Ephem will settle on about 21:02 1/10/1999 UT.
X
X To try a binary search, you first need to have some idea of when the event
X will occur so you can eliminate the initial linear search for the state
X change. We can start at, say, 1/1/1999, set StpSz to 30d, select Binary
X search, specify the search function to be:
X
X pl.sd > nep.sd
X
X and go. Once it brackets the state change note how StpSz keeps being cut
X in half but can go in either direction (sign) as it divides each interval
X in half. Ephem will converge on the same answer.
X
X 11.8. Another Example
X
X To find the time of last quarter moon during December, 1989, use the "Find
X 0" search algorithm to solve "moon.el + 90". (At last quarter, the moon
X is 90 degrees west of the sun, or -90 east in ephem's elongation display.)
X Set the initial time to mid-month, 12/15/1989, StpSz to 1 day and NStep to
X 10. Ephem takes only a few iterations to settle on 23:57 12/19 UT.
X
X 11.9. Caution
X
X Beware that most celestial phenomena are generally pseudo-periodic in
X nature. In early search steps ephem can easily skip over a local maxima
X and find a later one, which, while correct, may not be what was desired.
X In general, the closer you can be when you start the search the better
X ephem can refine it; it is not as good with very broad searches that can
X go "wild". Set StpSz large enough to offer significant change in the
X function value, but small enough not to skip too far.
X
X For example, Saturn and Neptune had three close approaches during 1989.
X If you did not know this then just asking ephem to find a minimum would
X have produced different results depending on the starting conditions.
X When starting a search for a certain class of event it is a good idea to
X first use the plotting or watching facility of ephem to get a broad
X picture of the general circumstances then use ephem's search facility to
X refine a given region (or create and inspect a plot file and do your own
X interpolation directly from it separately).
X
X
X
X
X
X
X
X
X
X
X - 23 -
X
X
X Similarly, ephem's searching techniques are not good for eclipses because
X the moon and sun are close every month; the trick is sorting through the
X frequent conjunctions for ones that are particularly close. One needs a
X way of establishing an envelope fit to the local extrema of a cyclic
X function in order to find a more global extreme.
X
X 12. Implementation Notes
X
X Remember that everything is for the current local time and day. So, for
X example, the calendar marks moon events in local time; commercial
X calendars usually mark the UT date. Similarly, the rise/set times are for
X the current local day.
X
X The program uses a horizontal plane tangent to the earth as the horizon
X for all altitude calculations, rise/set events, etc. This is not the same
X as the angle up from the local horizon unless the observer is directly on
X the ground due to earth's curvature. The effect can be found from:
X
X sin(a)**2 = (h**2 + 2Rh) / (R+h)**2
X where:
X R = radius of earth
X h = height above ground (same units as R)
X a = increase in altitude
X
X For example, the effect is more than two arc minutes at a height of 5
X feet.
X
X Visual magnitudes are not very accurate ... I haven't bothered to fix.
X
X The accuracy of ephem can not be specifically stated since the Duffett-
X Smith book does not warrant its planet position polynomials to any given
X degree. I know for sure that better accuracy could be achieved if ephem
X used TDT but I have not yet decided on a suitable algorithm. Allowing for
X this manually, (see the Wish List section) comparisons with the
X Astronomical Almanac are often within a few arcseconds.
X
X The program uses double precision throughout. While this precision might
X seem a little ridiculous, it is actually more efficient for most
X traditional K&R C compilers and the search functions seem to be are far
X more stable.
X
X Searching and plotting always use full precision but if neither of these
X are turned on pure display and watching only recompute a given planets new
X location if the time has changed enough to effect the required display
X precision, based on the planets mean apparent orbital motion.
X
X The sun-moon distance is the solution for the third side of a planar
X triangle whose two other sides are the earth-moon distance and earth-sun
X distance separated by the angle of elongation.
X
X Beware of specifying a year of 0, or of computing with the user-defined
X objects before they are properly defined. These conditions can cause ephem
X to blow.
X
X
X
X
X
X
X
X
X
X
X - 24 -
X
X
X 12.1. Program limits
X
X The search function is limited to a maximum of 32 instructions (each
X constant, field spec, and operation is one instruction), with no more than
X a total of 16 constants and field specs. At run time, the function can not
X require more than 16 stacked values (due to operator precedence or
X explicit parenthetical expressions) to evaluate.
X
X No more than 32 different fields can be tracked simultaneously for
X plotting and/or searching.
X
X No more than 10 lines may be plotted at once.
X
X The maximum file name length is 14 characters.
X
X 13. DOS Installation Procedure
X
X You must be running DOS V2.0 or later, though somewhere between V2.0 and
X V3.21 the behavior of control-c to terminate the program was fixed. An
X 8087 floating point chip will be used if present.
X
X The distribution floppy contains five files:
X README describes last minute items and details of this release.
X MAN.TXT is this manual, hopefully formatted and printable on most any
X printer.
X EPHEM.EXE is the executable program.
X EPHEM.CFG is a sample configuration file.
X EPHEM.DB is a sample database.
X To run the program, make working copies of these files in a directory and
X run "ephem" from that directory.
X
X 13.1. Setting TZ
X
X Before running ephem, you should set a DOS environment variable, TZ. It
X is is used to establish the timezone name and hours offset whenever the
X "Now" shorthand is used from ephem, either from the configuration startup
X file or whenever any time field is changed manually. Set it in the
X following form:
X
X set TZ=SSSnDDD
X
X where
X
X SSS is the 3-letter abbreviation for the local standard timezone;
X
X n is a number between -23 to 24 indicating the number of hours that are
X subtracted from GMT to obtain local standard time;
X
X DDD is an optional 3-letter abbreviation for the local daylight savings
X time zone name. Leave it off if you do not have savings time in your
X area or it is not currently in effect. If the changeover dates differ
X from the internal algorithm, just use SSS and n directly.
X
X For example, in the midwestern United States with savings times set
X
X
X
X
X
X
X
X
X
X - 25 -
X
X
X TZ=CST6CDT
X
X If for some reason your system does not change to savings time at the
X right time, then omit the DDD parameter and just set the SSS and n to
X exactly what you want.
X
X You can put this in your AUTOEXEC.BAT file so it gets set each time you
X boot DOS.
X
X 14. Known Bugs and Wish List
X
X incorporate Terrestrial Dynamical Time (known as Ephemeris Time prior to
X 1984). TDT is about 57 seconds ahead of UT1 in 1990.
X
X it's too easy to turn on objx/y before it's defined and bomb out.
X
X add explicit searching for eclipses and occultations.
X
X in watch mode, RTC reverts back to being based off the time when watch was
X first entered.
X
X add a facility (or tool) to find g/k from a set of observed magnitudes.
X
X find a better precession algorithm; current one exhibits some hysteresis
X and isn't all that accurate in general.
X
X add search criteria for database objects.
X
X add plot options to reverse x and/or y direction.
X
X handle year 0 properly.
X
X add moons.
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X - 26 -
X
X
X 15. Sample Screens
X
X Here are sample ephem screens. They are generated using the first sample
X ephem.cfg file (listed in the section describing the configuration file).
X There is one for each of the three possible screen formats. The rise/set
X screen was done using the Adaptive option. The separations screen was
X done using the Topocentric option.
X
XMove to another field, RETURN to change this field, ? for help, or q to run
X
XCDT 19:00:00 4/30/1990 | LST 8:19:50 | Lat 44:50:37 | April 1990
XUTC 0:00:00 5/01/1990 | | Long 93:42:08 | Su Mo Tu We Th Fr Sa
XJulianDat 2448012.50000 | Dawn 4:10 | Elev 800 ft | 1 2 3 4 5 6 7
XWatch | Dusk 22:15 | Temp 40 F | 8 FM 10 11 12 13 14
XListing off | NiteLn 5:55 | AtmPr 29.50 in | 15 16 17 18 19 20 21
XSearch off | | TZ 5:00:00 | 22 23 NM 25 26 27 28
XPlot off | NStep 1 | Epoch 2000.0 | 29 30
XMenu Planet Data | StpSz RT CLOCK | Pause 0 |
X--------------------------------------------------------------------------------
XOb R.A. Dec Az Alt H Long H Lat Ea Dst Sn Dst Elong Size VMag Phs
XSu 2:32.3 14:58 278:40 12:38 220:22 1.0075 1905 -27
XMo 8:09.9 21:11 186:06 65:53 119:55 1:04 234821 1.0071 79.5 1897 -12 44
XMe 2:49.4 17:39 277:48 17:26 214:08 1:43 0.5764 0.4360 4.9 11.7 1.6 1
XVe 23:49.4 -2:25 296:53 -27:39 282:39 -1:30 0.9288 0.7276 -43.9 18.2 -4.8 64
XMa 22:39.8 -10:09 308:17 -44:14 297:56 -1:43 1.5438 1.4067 -62.9 6.1 0.3 89
XJu 6:30.9 23:23 235:13 59:04 106:16 0:08 5.6806 5.1941 56.6 34.6 -2.0 99
XSa 19:49.6 -20:53 17:24 -65:14 289:45 0:10 9.7077 10.017 -105.0 17.1 1.1 100
XUr 18:41.9 -23:24 51:18 -60:39 276:55 -0:18 18.864 19.401 -120.9 3.5 5.6 100
XNe 19:03.2 -21:46 40:51 -62:01 282:48 0:51 29.754 30.207 -115.8 2.1 7.9 100
XPl 15:14.8 -1:26 81:18 -10:37 226:18 15:28 28.693 29.658 -162.9 0.3 13.6 100
XX 0:08.3 36:01 316:59 5:58 238:20 26:29 0.5622 0.6657 -38.4 1.5 33
XY 15:22.9 -2:40 80:43 -12:54 226:17 10:49 2.3635 3.3381 -162.5 10.1100
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X - 27 -
X
X
XMove to another field, RETURN to change this field, ? for help, or q to run
X
XCDT 19:00:00 4/30/1990 | LST 8:19:50 | Lat 44:50:37 | April 1990
XUTC 0:00:00 5/01/1990 | | Long 93:42:08 | Su Mo Tu We Th Fr Sa
XJulianDat 2448012.50000 | Dawn 4:10 | Elev 800 ft | 1 2 3 4 5 6 7
XWatch | Dusk 22:15 | Temp 40 F | 8 FM 10 11 12 13 14
XListing off | NiteLn 5:55 | AtmPr 29.50 in | 15 16 17 18 19 20 21
XSearch off | | TZ 5:00:00 | 22 23 NM 25 26 27 28
XPlot off | NStep 1 | Epoch 2000.0 | 29 30
XMenu Rise/Set Info | StpSz RT CLOCK | Pause 0 |
X--------------------------------------------------------------------------------
XOb Rise Time Rise Az Trans Time Trans Alt Set Time Set Az Hours Up
XSu 6:05 67:48 13:12 60:01 20:20 292:28 14:15
XMo 10:54 57:14 18:49 66:01 1:56 304:46 15:02
XMe 6:13 63:34 13:30 62:51 20:47 296:04 14:34
XVe 4:35 93:02 10:29 42:33 16:23 267:14 11:48
XMa 3:57 103:53 9:20 34:52 14:43 256:17 10:45
XJu 9:24 54:59 17:11 68:33 1:00 305:01 15:36
XSa 1:56 119:18 6:31 24:17 11:06 240:42 9:10
XUr 1:01 123:08 5:24 21:47 9:46 236:52 8:45
XNe 1:14 120:39 5:45 23:24 10:16 239:21 9:02
XPl 19:55 91:11 1:57 43:46 7:55 268:48 12:00
XX 1:41 32:26 10:51 81:10 20:00 327:20 18:19
XY 20:08 92:55 2:06 42:28 7:59 267:01 11:50
X
X
XMove to another field, RETURN to change this field, ? for help, or q to run
X
XCDT 19:00:00 4/30/1990 | LST 8:19:50 | Lat 44:50:37 | April 1990
XUTC 0:00:00 5/01/1990 | | Long 93:42:08 | Su Mo Tu We Th Fr Sa
XJulianDat 2448012.50000 | Dawn 4:10 | Elev 800 ft | 1 2 3 4 5 6 7
XWatch | Dusk 22:15 | Temp 40 F | 8 FM 10 11 12 13 14
XListing off | NiteLn 5:55 | AtmPr 29.50 in | 15 16 17 18 19 20 21
XSearch off | | TZ 5:00:00 | 22 23 NM 25 26 27 28
XPlot off | NStep 1 | Epoch 2000.0 | 29 30
XMenu Separations | StpSz RT CLOCK | Pause 0 |
X--------------------------------------------------------------------------------
XOb Sun Moon Merc Venus Mars Jup Sat Uranus Nep Pluto X Y
XSu 79:32 4:52 43:59 62:55 56:31 105: 121: 116: 163: 38:21 162:
XMo 79:32 74:49 124: 142: 23:01 175: 160: 164: 106: 99:52 108:
XMe 4:52 74:49 48:43 67:39 51:50 110: 126: 121: 163: 39:57 163:
XVe 43:59 124: 48:43 18:56 100: 61:09 77:00 71:58 129: 38:49 126:
XMa 62:55 142: 67:39 18:56 119: 42:14 58:04 53:04 111: 50:48 108:
XJu 56:31 23:01 51:50 100: 119: 162: 177: 172: 128: 80:40 130:
XSa 105: 175: 110: 61:09 42:14 162: 15:52 10:50 69:37 83:36 67:17
XUr 121: 160: 126: 77:00 58:04 177: 15:52 5:11 54:43 97:18 52:21
XNe 116: 164: 121: 71:58 53:04 172: 10:50 5:11 59:06 92:24 56:46
XPl 163: 106: 163: 129: 111: 128: 69:37 54:43 59:06 125: 2:22
XX 38:21 99:52 39:57 38:49 50:48 80:40 83:36 97:18 92:24 125: 124:
XY 162: 108: 163: 126: 108: 130: 67:17 52:21 56:46 2:22 124:
X
X
X
X
X
X
X
X
X
X
EOFxEOF
len=`wc -c < Man.txt`
if expr $len != 142834 > /dev/null
then echo Length of Man.txt is $len but it should be 142834.
fi
More information about the Comp.sources.misc
mailing list