rtsi.com

home *** CD-ROM | disk | FTP | other *** search

/ rtsi.com / 2014.01.www.rtsi.com.tar / www.rtsi.com / OS9 / OSK / EFFO / pd8.lzh / DOC / ephem.doc

Wrap

Text File | 1990-04-13 | 60KB | 1,533 lines

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