From bacchus.pa.dec.com!shlump.nac.dec.com!decuac!haven!udel!rochester!cornell!uw-beaver!mit-eddie!bu.edu!rpi!julius.cs.uiuc.edu!apple!sun-barr!decwrl!lll-winken!uunet!allbery Sat Oct 6 14:14:44 PDT 1990 Article: 1834 of comp.sources.misc Path: bacchus.pa.dec.com!shlump.nac.dec.com!decuac!haven!udel!rochester!cornell!uw-beaver!mit-eddie!bu.edu!rpi!julius.cs.uiuc.edu!apple!sun-barr!decwrl!lll-winken!uunet!allbery From: dimed1!downey@cs.umn.edu Newsgroups: comp.sources.misc Subject: v15i020: ephem v4.21 manual Message-ID: <107420@uunet.UU.NET> Date: 6 Oct 90 00:16:25 GMT Sender: allbery@uunet.UU.NET Lines: 3580 Approved: allbery@uunet.UU.NET (Brandon S. Allbery - comp.sources.misc) X-UNIX-From: dimed1!downey@cs.umn.edu Posting-number: Volume 15, Issue 20 Submitted-by: dimed1!downey@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@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 ] [-d ] [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@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 ] [-d ] [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