Usenet 1994 October/usenetsourcesnewsgroupsinfomagicoctober1994disk2.iso/misc/volume11/ephem4.12/part06

Text File | 1990-03-10 | 36KB | 840 lines

Newsgroups: comp.sources.misc
subject: v11i007: ephem, 6 of 7 (part 1 of manual)
From: [e-mail]@ncs-med.UUCP (Elwood C. Downey)
Sender: [e-mail] (Brandon S. Allbery - comp.sources.misc)

Posting-number: Volume 11, Issue 7
Submitted-by: [e-mail]@ncs-med.UUCP (Elwood C. Downey)
Archive-name: ephem4.12/part06

# 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 of a two-part manual, Man.txt
if test -r Man.txt
then
    echo Man.txt has already been built.
    exit
fi

echo x Man.txt.1
sed -e 's/^X//' << 'EOFxEOF' > Man.txt.1
X
X
X
X
X
X
X                          Ephem V4.12 - February 20, 1990
X
X                    Copyright (c) 1990 by Elwood Charles Downey
X                               Chaska, Minnesota, USA
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 ............................................  5
X      3.2.  Data format columns ..........................................  6
X      3.3.  RiseSet format columns .......................................  7
X      3.4.  Separation format fields .....................................  7
X      4.  Date and Time Formats ..........................................  7
X      5.  Configuration File .............................................  8
X      5.1.  Configuration File fields ....................................  8
X      5.2.  Example ephem.cfg ............................................ 10
X      6.  Menu options ................................................... 10
X      6.1.  Adaptive vs. Standard hzn .................................... 11
X      6.2.  Geocentric vs. Topocentric ................................... 11
X      7.  Object X ....................................................... 11
X      7.1.  Controlling Object-X Operation ............................... 12
X      7.1.1.  Fixed coordinates .......................................... 12
X      7.1.2.  Elliptical elements ........................................ 12
X      7.1.3.  Parabolic elements ......................................... 12
X      7.1.4.  On or Off .................................................. 13
X      8.  Plotting ....................................................... 13
X      8.1.  Defining plot fields ......................................... 13
X      8.2.  Displaying a plot file ....................................... 14
X      8.3.  Cartesian or Polar coords .................................... 14
X      8.4.  Begin Plotting ............................................... 14
X      8.5.  Stopping Plotting ............................................ 14
X      9.  Watching ....................................................... 14
X      9.1.  Trails ....................................................... 15
X      9.2.  Night sky .................................................... 15
X      9.3.  Solar System ................................................. 15
X      10.  Searching ..................................................... 15
X      10.1.  Find extreme ................................................ 16
X      10.2.  Find 0 ...................................................... 16
X      10.3.  Binary ...................................................... 16
X      10.4.  Define a New function ....................................... 16
X      10.4.1.  Intrinsic functions ....................................... 17
X      10.4.2.  Field Specifiers .......................................... 17
X      10.4.3.  Constants ................................................. 17
X      10.4.4.  Operators ................................................. 18
X      10.5.  Specifying Search Accuracy .................................. 18
X      10.6.  Stop ........................................................ 18
X      10.7.  Example Searches ............................................ 18
X      10.8.  Another Example ............................................. 19
X      10.9.  Caution ..................................................... 19
X      11.  Implementation Notes .......................................... 20
X
X
X
X
X
X
X
X
X
X                                       - 2 -
X
X
X      11.1.  Program limits .............................................. 20
X      12.  DOS Installation Procedure .................................... 21
X      12.1.  Setting TZ .................................................. 21
X      13.  Wish List ..................................................... 21
X      14.  Sample Screens ................................................ 23
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
X
X
X
X
X
X
X
X
X                                       - 3 -
X
X
X     1.  Introduction
X
X     Ephem is a program that displays observing circumstances for all the
X     planets plus any one additional object. The additional object may be fixed
X     or specified via heliocentric elliptical or parabolic orbital elements to
X     accommodate 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 phase, local rise, transit and set times, length of time up,
X     and topocentric or geocentric angular separations between all combinations
X     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     A running plot file of selected field values may be generated as the
X     program runs.  Ephem includes a very crude quick-look facility to view
X     these plot files or they may be plotted by other programs.
X
X     One may watch the night sky or the solar system with a simple screen-
X     oriented 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 optionally specify an
X     alternate configuration file, and optionally specify values for several
X     screen fields.  The command line syntax can be summarized as follows:
X
X         ephem [-c <configfile>] [field=value  ...]
X
X
X
X
X
X
X
X
X
X                                       - 4 -
X
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 a configuration file to set the initial values of
X     several fields.  The default file name is ephem.cfg or .ephemrc in the
X     HOME environment variable directory if available.  The exact format of the
X     file is described below.  Then it processes any additional command line
X     arguments exactly as it would if they too came from the configuration
X     file.  (See the later section on this manual for a description of the
X     possible entries.) It then draws all fields on the screen with their
X     initial values.  The program then loops advancing time each step, by some
X     amount you may control, and updating all fields each loop.
X
X     There are two fields that control this looping behavior: NStep and StpSz.
X     These control the number of steps and the amount of time to add each step,
X     respectively. When the number of steps, NStep, goes to 0 or any key is
X     pressed, the looping stops and you 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     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.  You may also move the cursor immediately to a planet row by
X     typing one of the characters SMevmjsunpx.  (To avoid conflict with j,
X     jupiter's row must actually be typed as control-j.) "x" is for the user-
X     defined object X on the bottom row.  Also, the characters d, o and z move
X     you to the UT Date, Epoch and StpSz fields immediately, if appropriate.
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     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
X
X
X
X
X
X
X
X                                       - 5 -
X
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 one additional object 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     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     Watch         selects the sky or solar system displays; see complete
X                   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 is approximately 18 degrees below
X                   the horizon before sunrise.
X
X
X
X
X
X
X
X
X
X
X                                       - 6 -
X
X
X     Dusk(p)       local time when the sun is approximately 18 degrees below
X                   the horizon after sunset.
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                   to set to epoch of date.  The coordinates for the extra
X                   object are assumed to be in the epoch given by this field
X                   when they are entered.
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     Helio Long(p) true heliocentric longitude, in degrees.  Earth's is
X                   displayed on the sun's line.
X     Helio Lat(p)  true heliocentric latitude, in degrees.
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
X
X
X
X
X
X
X
X
X
X                                       - 7 -
X
X
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 X'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
X     3.3.  RiseSet format columns
X     Rise        The local time and azimuth when the upper limb of the object
X                 rises.
X     Transit     The local time and altitude when the object crosses the
X                 meridian, 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         The local time and azimuth when the upper limb of the object
X                 sets.
X     Hrs 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
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
X
X
X
X
X
X
X
X                                       - 8 -
X
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     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     You can have several different configuration files if you wish. By
X     default, ephem looks for one named ephem.cfg. You can tell it to use an
X     alternate file by using the -c switch as follows:
X
X         ephem -c <filespec>
X
X
X     If your system supports the HOME environment variable then ephem also
X     looks for a configuration file there with the name
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 (*), pound (#), or
X     whitespace (space 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
X
X
X
X
X
X
X
X
X
X                                       - 9 -
X
X
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     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
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      This field specifies the optional object "x".  The field
X               contains several items, each separated by a comma.  The first
X               field is the type of the object, that is, one of the strings
X               "fixed", "elliptical", or "parabolic"; only enough of the string
X               to be unique is required so you may use just the first character
X               if desired.  The remaining fields depend on the type of object.
X               They are exactly the same parameters, and in the same order, as
X               ephem asks for when defining the object from the menu.  These
X
X
X
X
X
X
X
X
X
X                                       - 10 -
X
X
X               are described in more detail in the section on "Object X".  You
X               may define one object of each type in the configuration file;
X               the last one defined will be the "current" one when ephem gets
X               going.
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     * time is the evening of comet austin's maximum solar separation angle.
X     UT=1:45:0
X     UD=4/5/1990
X     TZNAME=CST
X     TZONE=6:0;0
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=TSMevmjsunpx
X     EPOCH=Eod
X     NSTEP=1
X
X     * comet halley. elements from Duffett-Smith book; mag from 12/86 S&T pg 666
X     OBJX=e,1986.109,76.0081,170.011,0.9673,162.2384,58.1540,17.9435,3.66,7.05
X
X     * orion, roughly
X     OBJX=fixed,6:0:0,0:0:0,1950
X
X     * comet austin, 1989c1, as per IAU Circular 4941, and magnitude rumors.
X     OBJX=parabolic,4/9.847/1990,58.911,61.504,.34963,75.409,1950,3.8,13.7
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
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
X
X
X
X
X
X
X
X
X                                       - 11 -
X
X
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     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.  Object X
X
X     You may specify an extra object for ephem to use. This object may be
X     defined in three ways:  fixed celestial sphere coordinates, or
X     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     A simple magnitude model is used to estimate the brightness of comets.
X     This model requires two parameters to be specified.  One, the absolute
X     magnitude, is the visual magnitude of the comet if it were one AU from
X     both the sun and the earth.  The other, the luminosity index,
X     characterizes the brightness change of the comet as a function of its
X     distance from the sun.  The model may be expressed as:
X
X         m = A + 5*log10(Re) + S*log10(Rs)
X       where:
X         m  is the resulting visual magnitude;
X         A  is the absolute visual magnitude;
X         Re is the comet-earth distance, in AU;
X         S  is the luminosity index; and
X         Rs is the comet-sun distance.
X
X     Note that this model does not take into account the phase angle of
X     sunlight on the comet.
X
X
X
X
X
X
X
X
X
X
X                                       - 12 -
X
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 Operation
X
X     To control the type and the corresponding details for object X, select the
X     left column of the bottom row, that is, the X.  (Remember that typing the
X     character "x" is a shorthand way to move to the bottom row.) It will bring
X     up a quick-choice menu as follows:
X
X     Select: Fixed coordinates, Elliptical elements, Parabolic elements, 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.  You
X     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     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 coordinates
X
X     This selection will present a series of three prompts, one each for the
X     RA, Dec, and the reference epoch for the coordinates of a fixed object.
X
X     7.1.2.  Elliptical elements
X
X     This will begin a series of nine prompts asking for the parameters that
X     define a heliocentric elliptic orbit and the magnitude model coefficients.
X     These orbital parameters are, in order, the epoch of perihelion, orbital
X     period, longitude of perihelion, eccentricity, inclination, longitude of
X     the ascending node, and the semi-major axis of the ellipse.  Then follows
X     the absolute magnitude and luminosity index coefficients.
X
X     7.1.3.  Parabolic elements
X
X     This will begin a series of eight prompts asking for the parameters that
X     define a heliocentric elliptic orbit and the magnitude model coefficients.
X     These orbital parameters are, in order, the epoch of perihelion,
X     inclination, argument of perihelion (same as the longitude of perihelion
X
X
X
X
X
X
X
X
X
X                                       - 13 -
X
X
X     minus the longitude of the ascending node), perihelion distance, longitude
X     of the ascending node, and the reference epoch of the parameters.  Then
EOFxEOF
len=`wc -c < Man.txt.1`
if expr $len != 33834 > /dev/null
then echo Length of Man.txt.1 is $len but it should be 33834.
fi

# if Man.txt.2 exists, then the second half of the manual has already been
# created from its shar file so we stick it after this one to make Man.txt.
if test -w Man.txt.2
then
    echo catting Man.txt.2 to Man.txt.1 to form Man.txt
    cat Man.txt.2 >> Man.txt.1
    rm Man.txt.2
    mv Man.txt.1 Man.txt
fi