Source Code 1994 March/Source_Code_CD-ROM_Walnut_Creek_March_1994.iso/compsrcs/x/volume16/xephem/part12

Text File | 1992-03-05 | 50.2 KB | 1,028 lines

Newsgroups: comp.sources.x
Path: uunet!think.com!mips!msi!dcmartin
From: [e-mail] (Elwood Downey)
Subject: v16i123: xephem - astronomical ephemeris program., Part12/24
Message-ID: <[e-mail]>
Originator: dcmartin@fascet
Sender: [e-mail] (David C. Martin - Moderator)
Organization: Molecular Simulations, Inc.
References: <[e-mail]>
Date: Fri, 6 Mar 1992 13:54:55 GMT
Approved: [e-mail]

Submitted-by: [e-mail] (Elwood Downey)
Posting-number: Volume 16, Issue 123
Archive-name: xephem/part12

# this is part.12 (part 12 of a multipart archive)
# do not concatenate these parts, unpack them in order with /bin/sh
# file patchlevel.h continued
#
if test ! -r _shar_seq_.tmp; then
    echo 'Please unpack part 1 first!'
    exit 1
fi
(read Scheck
 if test "$Scheck" != 12; then
    echo Please unpack part "$Scheck" next!
    exit 1
 else
    exit 0
 fi
) < _shar_seq_.tmp || exit 1
if test ! -f _shar_wnt_.tmp; then
    echo 'x - still skipping patchlevel.h'
else
echo 'x - continuing file patchlevel.h'
sed 's/^X//' << 'SHAR_EOF' >> 'patchlevel.h' &&
X * patch to xephem is created and distributed. it is only here because a given
X * patch may advance the version number an arbitrary amount. the version number
X * is maintained in version.c.
X */
#define    PATCHLEVEL 0
SHAR_EOF
echo 'File patchlevel.h is complete' &&
chmod 0644 patchlevel.h ||
echo 'restore of patchlevel.h failed'
Wc_c="`wc -c < 'patchlevel.h'`"
test 289 -eq "$Wc_c" ||
    echo 'patchlevel.h: original size 289, current size' "$Wc_c"
rm -f _shar_wnt_.tmp
fi
# ============= xephem.hlp ==============
if test -f 'xephem.hlp' -a X"$1" != X"-c"; then
    echo 'x - skipping xephem.hlp (File already exists)'
    rm -f _shar_wnt_.tmp
else
> _shar_wnt_.tmp
echo 'x - extracting xephem.hlp (Text)'
sed 's/^X//' << 'SHAR_EOF' > 'xephem.hlp' &&
@Intro
XXephem is a program that displays ephemerides for all the planets, some moons,
plus any two additional objects.  The additional objects may be fixed or
specified via heliocentric elliptical, hyperbolic or parabolic orbital
elements to accommodate solar system objects such as asteroids or comets.
X
Information displayed about each object includes RA and Dec precessed to any
epoch, local azimuth and altitude, heliocentric coordinates, distance from
sun and earth, solar elongation, angular size, visual magnitude, illumination
percentage, local rise, transit and set times, length of time up,
constellation, and angular separations between all combinations of objects.
A special detail of Earth's moon and and Jupiter's moons and central meridian
longitude is also available.
X
Observing circumstance information includes UTC and local date and time,
local sidereal time, times of astronomical twilight and length of night, local
temperature, pressure and height above sea level for the refraction model and a
monthly calendar.
X
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.
X
Plot and listing files of selected field values may be generated as the
program runs.  The plot files are full precision floating point values in
ASCII intended for export to other plotting programs.  The listing files are
tables formatted for more general human reading.  Xephem includes simple
quick-look facilities to view plot files.
X
One may also watch the sky or the solar system with simple dots displays.
X
XXephem may be asked to search for interesting conditions automatically, using
several algorithms. Most fields displayed on the screens may be used as terms
in an arbitrary arithmetic expression that can be solved for local zero or
extrema, or the time of state change of any boolean expression can be found.
X
XXephem uses three auxiliary files: an initial configuration, an object data
base and the help text. The default name of the configuration file is
ephem.cfg, in the current directory.  This name can also be set using the -c
command line argument or by defining the EPHEMCFG environment variable.
Details of the configuration file format may be found in the main on-line help
for "Initialization".
X
The default name of the database file is ephem.db, in the current directory.
This name can also be set using the -d command line argument or by defining
the EPHEMDB environment variable. Details of the database file may be found in
the on-line help from the "ObjX/Y" dialog.
X
The default name of the help file is xephem.hlp, in the current directory.
This name can also be set using the -h command line argument or by defining
the XEPHEMHELP environment variable.
X
Follows is a description of the fields visible on the Main menu. Note that
fields containing local and Universal times are not explicitly labeled, for
brevity.
X
X LTZ           the local timezone name.  The name field may be changed to
X           any three-character mnemonic.
X LT
X LD            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
X UD            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     the current Julian date, to about 1-second accuracy.
X LST           the current local sidereal time.  set to "n" to set from
X           computer clock.
X Dawn          local time when the sun center is 18 degrees below the
X           horizon before sunrise today.
X Dusk          local time when the sun center is 18 degrees below the
X           horizon after sunset today.
X NiteLn        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 will be updated (time
X           advanced by StpSz each step) automatically.
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" to the number or in terms of sidereal days by
X           appending an "s" to the number.
X Lat           location latitude, positive degrees north of equator.
X Long          location longitude, positive degrees west of Greenwich
X           meridian.
X Elev          local elevation of the ground above sea level, in feet. (see
X           implementation notes).
X Temp          local surface air temperature, in degrees F.
X AtmPr         local surface air pressure, in inches of mercury.
X TZ            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.
X Pause         number of seconds to pause between screen updates. This is
X           used mainly to set up for free-running unattended operation.
X           Pausing is not done when plotting or searching is on.
@Operation
When xephem starts it reads the configuration file and processes the command
line arguments to set the initial values of several fields, accessing the
database file if OBJX or OBJY is set. See the "Initialization" help for
details of the format of the file and the command line arguments. Xephem
then draws all fields on the main 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.
X
There are three fields that control this looping behavior.  NStep controls
the number of steps, StpSz the amount of time to add each step, and Pause
is the amount of real seconds to pause between steps.  Note that Xephem does
not pause between steps when plotting or searching is on.  When the number of
steps, NStep, goes to 0 or the "Stop" button is selected, the looping stops
and the button is relabeled "Update".
X
Most fields may be changed by selecting them. A prompt dialog with a brief
explanation of the field will be presented. A new value may be typed into
the text field provided. If "Ok" is selected the new value will be used;
if "Cancel" is selected the field will be left unchanged. In either case,
the prompt dialog goes away.
X
When you have changed a field that would invalidate any of the other
fields the message NEW CIRCUMSTANCES appears above the "Update/Stop" button.
This will remain until at least one screen update loop occurs.  If you change
any field that causes new circumstances, the StpSz value is not added to the
first loop. Note also that after a series of loops, NStep is automatically
reset to 1 from 0 so "Update" will do exactly one loop again.
@References
Many formulas and tables are based, with permission, on material found in:
"Astronomy with your Personal Computer" by Dr. Peter Duffett-Smith, Cambridge
University Press, (c) 1985.
X
Other references include:
X
Constellation algorithm from a paper by Nancy G. Roman, "Identification of a
constellation from a position", Publications of the Astronomical Society of
the Pacific, Vol.  99, p.  695-699, July 1987.
X
Precession routine from 1989 Astronomical Almanac.
X
Jupiter's moons based on information in "Astronomical Formulae for
Calculators" by Jean Meeus. Richmond, Va., U.S.A., Willmann-Bell, (c) 1982.
X
Moon bitmap is from xphoon, Copyright (C) 1988 by Jef Poskanzer and Craig Leres.
@Initialization
The ephem.cfg configuration file and command line options allows you to set
the initial values of many of the main menu fields. You can still change any
field while the program is running too; these just set the initial conditions.
Note that the order of these specifications 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 xephem.
X
The default name of the configuration file is ephem.cfg.  Ephem also looks
for one named by the EPHEMCFG environment variable (if defined) or you may
specify any name using the -c command line option.
X
The format of the file and the command line parameters uses the form
KEYWORD=VALUE, where the possible KEYWORDS and the types of VALUES for each
are described below. Any KEYWORDS not specified will take on some sort of
default. The separator need not be an actual equals sign; any char will do
because the VALUE is assumed to start one character after the KEYWORD,
regardless.
X
All lines in the configuration file that do not begin with an alpha character
(a through z, either case) are ignored and may be used for comments.
X
XXephem recognizes these same keyword=value pairs as command line parameters.
Command line parameters are processed after config file parameters.
X
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.
X
Follows is a list of the keywords that may be used in the configuration file
and/or command line:
X
UD     initial UTC date, such as 10/20/1988, or "NOW" to use the computer
X       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
X       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
X       not set this if you use "NOW" for UT or UD. This is purely a text
X       label; xephem makes no attempt to compute anything from this label,
X       such as a UTC offset.
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
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 or a time
X       in sidereal days by appending an s (or S) after the number.
PROPTS this selects what you want included initially in the tables. 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.
NSTEP  number of times program will loop automatically.
X       see the discussion under Program Operation.
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").
OBJX
OBJY   These fields specify the optional objects "x" and "y" by naming
X       any item in the database file. The form is OBJX=x, where x
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.
PAUSE  The number of seconds to pause between calculation steps. See
X       definition of the Pause field in the "Top Screen Fields"
X       section.
@Date/time
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.
X
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.
X
If you change the date, the time (ie, partial day) will not change.
X
Negative years indicate BC dates. For example, Jan 1, 1 BC is given as
1/1/-1.  There is no year 0.
X
Two other ways to set the date are supported for compatibility with some
published comet ephemerides.  You may enter the day portion as a floating
point number. When you set the day this way, the time will also change to
correspond to the fractional portion of the day.
X
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.
X
As a matter of typing convenience, the program accepts most any punctuation
character as the separator; you don't have to type a perfect ":" or "/".
@Notes
1) Remember that everything is for the current local time and day. 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.
X
2) The program uses a horizontal plane tangent to the earth Elev feet above
sea level as the horizon for all altitude calculations, rise/set events, etc.
Due to Earth's curvature, this is not the same as the angle up from the local
horizon unless the observer is directly on the ground. 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
The effect can be significant. For example, the effect is more than two arc
minutes at a height of 5 feet.
X
3) The accuracy of xephem 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 xephem
used TDT but I have not yet decided on a suitable algorithm.  Allowing for
this manually, comparisons with the Astronomical Almanac are often within a
very few arcseconds.
X
4) 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 far
more stable.
X
5) 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.
X
Ideas:
X + add tick marks (third axis?) to plots.
X + write a tool to find g/k from a set of predicted magnitudes.
X + display all or any selection of fixed objects in the database in sky views.
X + add star and deep sky objects to sky views.
X + search for occultations with all fixed objects.
X + add explicit searching for solar and lunar eclipses.
X + do more moons.
X + add sidereal and synodic step sizes of day week year etc.
X + add e/w flip option to jupiter moon display.
X + show a scrolled list of plot files, with filter, to choose from, or set.
X + use FileSelectionBox to choose plot, listing, and database files.
X + add a field to indicate search/sort criterion for database objects.
X + think of a way to display decimal years in plots as m/d/y somehow.
X + a "customize" menu to change to metric units, English dates.
X + incorporate Terrestrial Dynamical Time (known as Ephemeris Time prior to
X   1984).  TDT is about 57 seconds ahead of UT1 in 1990.
X + add option to put label for each dot right on sky views.
X + add horizon offset.
X + special shortcut buttons for RTC and Now.
X + add undo for plot and listing selections.
X + connect trails dots with line segments.
X + use a progress meter during database file loading, not just the watch cursor.
X
Bugs:
X - it's WAY too easy to turn on objx/y before it's defined and bomb out.
X - plotting or listing rise/set that doesn't happen just shows last entry.
X - %0*.* in f_sexad() doesn't work on some systems (needs 0 deleted)
X - should jup moon +y be S???
X - the built-in elements for pluto need to be updated. the elements for pluto
X   in the included ephem.db database sampler are more accurate.
X - planet magnitudes are not very accurate ...
X - allow for decimal seconds in format converters.
@Plot
This menu controls the plot generation and display functionality of xephem.
You may select most numeric information displayed by xephem, in pairs, to
form x/y coordinates of a plot. You may select up to ten such pairs. You then
select a file to contain the plot information. Xephem adds one line of
information to the file for each x/y pair each time iteration step. Xephem
can also plot any such file on the screen. The file format is compatible with
the character version of xephem, ephem.
X
Selecting data to plot:
X
Select the "Select fields" toggle button to make each field in the other
menus that eligible for plotting appear as a pushbutton. Select each such
button as desired to form the x or y component of a plot. As you make the
selections, they are listed in the menu. You may also associate a
one-character tag with each line. These tags will be included in the plot
display for identification later. Once all the field choices have been made
you may return all the menus to their normal operational appearance by
reselecting the same toggle button.
X
Specifying the plot file:
X
Type the name of the file to be used to contain the plot information in the
text field provided. When xephem first needs to write to the file, it will
first check for the existence of the file and ask whether you wish to append
to the file or overwrite it.
X
Specifying a plot file title:
X
All lines within a plot file that do not begin with a digit are considered
comments and are ignored. If the first line of a file is a comment, xephem
will use it as the title for the plot it draws.  When xephem first writes to
a plot file, it will place the contents of the title text area, if it is not
empty, into the file as a comment to ease use of this feature.
X
Generating the plot entires:
X
Once the fields have been specified and the plot file named and titled, you
may select the "Plot to file" toggle button when ready. Now each time xephem
goes through one iteration the values you have selected and their tags will be
written to the plot file. Note that when plotting is activated, xephem does
not update the screen until the NStep count goes to 1. This greatly speeds
the creation of plot files by avoiding screen updates. If you wish to watch
each iteration, set NStep to 1 and select the "Update" button manually for
each iteration. Once all the desired data has been entered into the plot
file, toggle the plot button back off to close the file and flush all data.
X
Be aware that the menus that contain each of the fields used in the plot
must be visible whenever the function is evaluated in order for the fields to
be accurate.
X
Viewing plot files:
X
Existing plot files may be viewed by typing their name into the text field
provided and selecting the "Show plot file" pushbutton. As many different
plot files may be viewed simultaneously as desired. Each plot has separate
controls for flipping the X and Y axes and for turning on and off a reference
coordinate grid.
@Listing
This menu controls the list generation functionality of xephem.  The fields
you select define columns of a table written to a file as xephem runs.  These
columns look exactly like their corresponding fields on the xephem menus and
so are far more readable than plot files. They are designed to be used in
further text processing operations or printed as-is. Two spaces are placed
between each column.
X
Selecting data to list:
X
Select the "Select fields" toggle button to make each field in the other
menus eligible for listing appear as a pushbutton. Select each such button as
desired to form each column of the listing. As you make the selections, they
are listed in the menu. Once all the column choices have been made you may
return all the menus to their normal operational appearance by reselecting the
same toggle button.
X
Specifying the listing file:
X
Type the name of the file to be used to contain the listing in the text field
provided. When xephem first needs to write to the file, it will first check
for the existence of the file and ask whether you wish to append to the file
or overwrite it.
X
Specifying a listing file title:
X
All lines within a listing file that do not begin with a digit are considered
comments and are ignored.  When xephem first writes to a listing file, it
will place the contents of the title text area, if it is not empty, into the
file as a comment for your convenience.
X
Generating the listing entires:
X
Once the fields have been specified and the listing file named and titled, if
desired, select the "List to file" toggle button. Now each time xephem goes
through one iteration the values you have selected will be written to the
file. Note that when listing is activated, xephem does not update the screen
until the NStep count goes to 1. This greatly speeds the creation of listing
files by avoiding screen updates. If you wish to watch each iteration, set
NStep to 1 and select the "Update" button manually for each iteration. Once
all the desired data has been entered into the listing file, toggle the
list button back off to close the file and finish writing data to it.
X
Be aware that the menus that contain each of the fields used in the listing
must be visible whenever the function is evaluated in order for the fields to
be accurate.
@Search
This menu controls the automatic searching facility. You define an arithmetic
or boolean function, using most of the fields xephem displays, then xephem
will automatically evaluate the function and adjust the time on each
iteration to search for the goal.
X
To perform a search:
X   enter a function,
X   compile it,
X   select a goal,
X   set the desired accuracy,
X   enable searching,
X   start the search process.
X
Each of these steps is described below.
X
Entering the function:
X
The function may be any arithmetic expression, in C-language syntax.  All of
C's comparison, logical and arithmetic operators are supported as well as
several common arithmetic functions. Here is the complete list:
X
X  + - * / && || > >= == != < <=
X  abs sin cos tan asin acos atan degrad raddeg pi log log10 exp sqrt pow atan2
X
The function is entered into the text line provided. It may utilize most of
the fields from the other xephem menus. Press the "Enable field buttons"
button to make each available field a button. Where ever a field is desired
in the function, position the text insertion cursor at the desired position
and select the field; its name will be inserted into the function text. When
you are finished defining the function, turn off the field button appearance
by selecting the "Enable..." button again.  Once you get to know the names of
the fields you may also enter them manually, if you prefer.
X
Compiling the function:
X
Once the function has been entered as desired, it must be compiled by
selecting the "Compile" button (or by pressing the Return or Enter key on
your keyboard).  If there are any errors, a diagnostic message will appear
just below the function.
X
Selecting a search goal:
X
You may choose from any of three evaluation algorithms, as selected by the
trio of radio buttons. "Find extreme" will search for a maxima or minima of
the function. "Find 0" will search for a time when the function evaluates to
zero.  "Binary" will keep incrementing time by StepSz (in the main menu)
until the state of the function changes, then do a binary search to find the
exact time when the function changes state. Binary search interprets a
function that evaluates to zero to be in one state and all other values to be
the opposite state. Generally, binary functions are comprised of logical
operators at their outermost expression levels.
X
Specifying the desired accuracy:
X
Searching will automatically stop when the time changes by less than the the
accuracy value. Note that this method of detecting convergence is not based
on the value of the search function itself. To change the desired accuracy
press the pushbutton showing the current accuracy next to the "Accuracy"
label and enter a new value in the dialog.
X
Performing the search:
X
Once the function is defined and compiles without errors, you may enable
searching by selecting the "On" button. Then, each time "Update" is selected
on the main menu the search proceeds until either "NStep" iterations have
occurred or until  "StepSz" becomes less than Accuracy. The initial search
time and step size are set from the main menu, and are adjusted automatically
as the search proceeds. Note that by setting NStep to 1 and repeatedly
selecting Update you can effectively single-step the search process. Search
control will automatically turn off when convergence is detected, the
function is edited or you may turn it off manually at any time by toggling
the "On" button back off.
X
Other issues:
X
When selecting fields for plotting or listing a button appears labeled "Use
for plotting". You may select this button to use the evaluated search
function as an item in the plot or listing feature. Note that the search
function may be used in plotting and listing whether or not searching is
enabled.
X
Be aware that the menus that contain each of the fields used in the search
function must be visible whenever the function is evaluated in order for the
fields to be accurate.
X
The "Close" button removes the search control menu from the screen; it does
not effect actual search operation in any way.
X
Searching periodic functions can lead to unexpected solutions. You will get
best results if you can start the search near the expected answer and with a
small step size that bounds the solution. You can use the plotting feature to
study a function and get an idea of the solution, then use the automatic
searching feature to zero in.
@Data Table
Column descriptions:
X
X Cns           name of the constellation in which the object appears.
X R.A.          apparent geocentric right ascension of object, precessed to
X           given epoch, in hours, minutes and decimal minutes.
X Dec           apparent geocentric declination of object, precessed to
X           given epoch, in degrees and minutes.
X Az            degrees eastward of true north for object.
X Alt           degrees up from a horizontal plane Elev feet above sea
X           level.
X H Long        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         true heliocentric latitude, in degrees.  For the moon this
X           is the geocentric latitude.
X Ea Dst        true distance from Earth center to object center, in AU,
X           except distance to the moon is in miles.
X Sn Dst        true distance from sun center to object center, in AU.
X Elong         spherical angular separation between sun and given object,
X           calculated from the their geocentric ecliptic coordinates.
X           Note this is not just the difference in ecliptic longitude.
X           The 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.  This field is not
X           generally useful in searching for conjunctions because of
X           the discontinuous sign change that occurs at conjunction.
X Size          angular size of object, in arc seconds.
X VMag          visual magnitude of object.
X Phs           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"?).
@Rise/Set Table
Column descriptions:
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 today.
X
Various odd ball conditions are accounted for and marked as follows:
X
X NvrRs        up some time but never rises, as such, today.
X NvrSt        up some time but never sets, as such, today.
X NoTrn        up some time but doesn't transit, as such, today.
X CPolr        object is circumpolar (never goes below horizon) today.
X NvrUp        object is never up today.
X XX:XX+        + appended to rise, transit or set times means the event occurs
X          twice today; the time given is the time of the first event.
X        + appended to "Hours Up" means it is still up at midnight.
X
Horizon displacement may be calculated in either of two ways: Adaptive or
Standard.  This selects the horizon displacement algorithm used. "Adaptive"
uses the local atmospheric and location conditions known to xephem and matches
the General Data 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.
@Separations Table
This view is a table of angular separations between each pair of objects, in
degrees.
X
The vantage point for the Separation values may be chosen. "Geocentric"
ignores local conditions and gives the separation as seen from Earth center.
"Topocentric" uses the local conditions known to xephem.  The choice is
particularly critical for lunar occultations, but the effect can be
significant for the planets. Geocentric separations between objects and the
sun will match the magnitude of the elongation given in the Data menu.
X
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.
X
@Solar System View
This is a graphical representation of the solar system. The Sun is always at
the center of the screen, marked as a plus (+). The three sliders at the
edges control the position of the observer. The vertical slider on the left
controls the distance from the sun - you are closer as the slider is slid
further up. The horizontal slider under the view controls the heliocentric
longitude. The vertical slider on the right controls the heliocentric
latitude - your angle above the ecliptic plane.
X
A simple 3d effect can be achieved by turning "trails" on and running xephem
for several months or years with a relatively small step size. This will yield
orbital paths that can be viewed in perspective. Consider doing this with a
comet selected as one of the user defined objects.
@Object
XXephem supports two user-defined objects, denoted X and Y. These may be fixed
objects or objects in elliptical, hyperbolic or parabolic heliocentric
orbits.
X
The ObjX/Y dialog allows you to define the objects. You may enter the
appropriate parameters manually or select from objects in the database. Be
sure the X/Y radio box is set to the object you wish to modify. Note that
computations are not performed as each parameter is entered since the
program can not determine if there yet more changes to be made. To force
a computation to occur, select the "Update" button on the main menu, or
toggle the object selection button in a tabular view menu.
X
To select from the database, select the Lookup button to read in the database
file, then select the desired object from the scrolled list. The selected
object will define the type and values for the current object (X or Y).
X
XXephem stores information separately for each type of object so it is possible
to have information for up to eight different objects loaded at once, if there
are two each of fixed, elliptical, hyperbolic and parabolic types. The current
type is shown in the type radio box.
X
The name of the database file is ephem.db by default or it may be set
explicitly using the -d option or as the value of the EPHEMDB environment
variable. The format of the file is such that each object occupies one line.
Fields are separated by commas. The first two fields are the name of the
object and its type. The type may be fixed, elliptical, hyperbolic, or
parabolic, or any abbreviation.  The remaining fields are in the same order as
the menu parameter entries and are described below for the current object
type. Lines beginning with anything other than a-z, A-Z or 0-9 are ignored.
X
Follows is a description of each parameter for the current object type.
X
@Fixed Object
+Object
Fixed objects are characterized by five parameters:
X
X    RA,
X    Dec,
X    magnitude,
X    the reference epoch for the coordinates and
X    angular size in arc seconds, optional
X
@Elliptical Object
+Object
Elliptical objects are characterized by 12 parameters: the parameters that
define a heliocentric elliptic orbit and the coefficients for either of two
magnitude models.  These elements are the same ones 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    s = angular size at 1 AU, arc seconds, optional
X
X
You might have other parameters available that can be converted into these.
The following relationships might be useful:
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    T = epoch of perihelion (add multiples of P for desired range)
X    q = perihelion distance, AU
X
Note that if you know T you can then set E = T and M = 0.
X
XXephem supports two different magnitude models for elliptical objects. One,
denoted here as g/k, is generally used for comets in elliptical objects. The
other, denoted H/G, is generally used for asteroids in the Astronomical Almanac.
X
+OBJXY_gkMAGNITUDE
When using this model for elliptical objects, the first of the two magnitude
fields must be preceded by a letter "g" in both the ephem.db database file
and the corresponding menu elliptical object definition prompt; otherwise the
default magnitude model for elliptical objects is the H/G model.
X
+OBJXY_HGMAGNITUDE
X
This is the default magnitude model for elliptical objects but it can also
be explicitly indicated when the first of the two magnitude fields is
preceded by a letter "H" in both the ephem.db database file and the
corresponding menu elliptical object definition prompt.
@Hyperbolic Object
+Object
Hyperbolic objects are characterized by 10 parameters: the parameters that
define a heliocentric hyperbolic orbit and the magnitude model coefficients.
These orbital parameters are, in order:
X
X    T = epoch of perihelion
X    i = inclination, degrees
X    O = longitude of ascending node, degrees
X    o = argument of perihelion, degrees
X    e = eccentricity,
X    q = perihelion distance, AU
X    D = the equinox year (ie, time of i/O/o).
X    g/k = magnitude model
X    s = angular size at 1 AU, arc seconds, optional
X
As with elliptical elements, other parameters might be available.  The
relationships are generally the same, except for:
X
X    q = a*(e-1)
X
+OBJXY_gkMAGNITUDE
@Parabolic Object
+Object
Parabolic objects are characterized by 9 parameters: the parameters that
define a heliocentric parabolic orbit and the magnitude model coefficients.
These orbital parameters are, in order:
X
X    T = epoch of perihelion
X    i = inclination, degrees
X    o = argument of perihelion, degrees
X    q = perihelion distance, AU
X    O = longitude of ascending node, degrees
X    D = the equinox year (ie, time of i/O/o).
X    g/k = magnitude model
X    s = angular size at 1 AU, arc seconds, optional
X
+OBJXY_gkMAGNITUDE
@OBJXY_gkMAGNITUDE
The g/k magnitude model requires two parameters to be specified. One, the
absolute magnitude, g, is the visual magnitude of the object if it were one
AU from both the sun and the earth.  The other, the luminosity index, k,
characterizes the brightness change of the object as a function of its
distance from the sun. This is generally zero, or very small, for inactive
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
Note that this model does not take into account the phase angle of
sunlight.
X
@OBJXY_HGMAGNITUDE
The H/G model also requires two parameters. The first, H, is the magnitude of
the object when one AU from the sun and the earth. The other, G, attempts to
model the reflection characteristics of a passive surface, such as an
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
Note that this model does not take into account the phase angle of
sunlight.
X
SHAR_EOF
chmod 0644 xephem.hlp ||
echo 'restore of xephem.hlp failed'
Wc_c="`wc -c < 'xephem.hlp'`"
test 40159 -eq "$Wc_c" ||
    echo 'xephem.hlp: original size 40159, current size' "$Wc_c"
rm -f _shar_wnt_.tmp
fi
# ============= ephem.db ==============
if test -f 'ephem.db' -a X"$1" != X"-c"; then
    echo 'x - skipping ephem.db (File already exists)'
    rm -f _shar_wnt_.tmp
else
> _shar_wnt_.tmp
echo 'x - extracting ephem.db (Text)'
sed 's/^X//' << 'SHAR_EOF' > 'ephem.db' &&
* ephem database.
*
* Objects are sorted by name for easy reading but they need not be in any
* order. Each object occupies one line. Fields are separated by commas. Lines
* beginning with anything other than a-z, A-Z or 0-9 are ignored.
*
* Format summaries:
*
* elliptical format (e < 1):
*    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).
*    g/k or H/G = magnitude model
*    s = angular size at 1 AU, arc seconds, optional
*
* hyperbolic format (e > 1):
*    T = epoch of perihelion
*    i = inclination, degrees
*    O = longitude of ascending node, degrees
*    o = argument of perihelion, degrees
*    e = eccentricity,
*    q = perihelion distance, AU
*    D = the equinox year (ie, time of i/O/o).
*    g/k = magnitude model
*    s = angular size at 1 AU, arc seconds, optional
*
* parabolic format (e == 1):
*    T = epoch of perihelion
*    i = inclination, degrees
*    o = argument of perihelion, degrees
*    q = perihelion distance, AU
*    O = longitude of ascending node, degrees
*    D = the equinox year (ie, time of i/O/o).
*    g/k = magnitude model
*    s = angular size at 1 AU, arc seconds, optional
*
* fixed format:
*    ra, hours
*    dec, degrees
*    magnitude
*    reference epoch
*    s = angular size, arc seconds, optional
X
Mueller,p,3/21.196/1992,95.524,307.011,0.19871,288.795,2000,0,0,0
* from IAU circular 4985
Austin,p,4/9.9715/1990,58.9574,61.5625,0.349854,75.2223,1950.0,4.5,4
* from IAU circular 4986
Cernis,p,3/17.2967/1990,48.138,100.588,1.06849,347.727,1950,0,0
* from IAU circular 4984
George,p,4/11.9396/1990,59.3652,137.8482,1.569001,279.3118,1950,0,0
*Comet Levy (1990c) elements from IAUC 5060 (25 Jul 1990);g & k by J. Fedock
Levy,h,10/24.6277/1990,131.5951,138.6561,242.6328,1.001267,.938779,1950,4.2,3.4
*Comet Tsuchiya-Kiuchi (1990i) from IAUC 5119; g & k by J. Fedock
TK,e,143.7938,330.0165,180.9616,159.539,.000489119,.993160,0,9/28.7785/1990,1950,g5.453,k4.087
X
*Comet Honda-Mrkos-Pajdusakova (1990f) elements from IAUC 5035 (19 June 1990)
*g & k via least squares fit by J. Fedock (10 Aug 90).
HMP,e,4.2224,88.7097,325.702,3.03891,0.186049,0.821936,0,9/12.6864/1990,1950,g14.018,7.946
X
* updated elements for Pluto
Pluto,e,17.1519,110.2183,113.5202,39.37210,.00398953,0.24678,0.1782,10/1/1989,2000.0,g6.3,0.0,8.1
X
* From Jost Jahn's asteroid database, version 4 (early 1990), as edited for
* ephem by Craig Counterman.
A'Hearn,e,2.87687,56.46890,90.08788,2.3774301,0.26887005,0.1693323,137.76469,11/5/1990,1950.0,13.80,0.25
A909TF,e,13.05804,14.82261,260.94419,2.6074201,0.23409253,0.1725529,162.39895,11/5/1990,1950.0,11.70,0.25
A917SG,e,10.92421,184.07399,174.69189,2.7617381,0.21474859,0.2727012,337.56689,11/5/1990,1950.0,12.10,0.25
A923RH,e,14.74876,1.24038,341.96457,2.5980838,0.23535550,0.1656514,17.63311,11/5/1990,1950.0,12.50,0.25
ASCII,e,19.47553,57.87728,281.02590,3.1328345,0.17774520,0.2478530,290.70384,11/5/1990,1950.0,12.30,0.25
ASP,e,0.91829,338.27607,54.31939,3.1893411,0.17304244,0.2033645,181.58305,11/5/1990,1950.0,11.50,0.15
Aaltje,e,8.48747,272.72810,271.98927,2.9569161,0.19384097,0.0458608,330.37626,11/5/1990,1950.0,9.74,0.15
Aarhus,e,4.55163,289.15969,45.24373,2.4046881,0.26431144,0.1252363,120.26961,11/5/1990,1950.0,12.70,0.25
Aaronson,e,8.57596,84.50475,296.66986,3.1365294,0.17743122,0.2735114,154.39503,11/5/1990,1950.0,11.27,0.15
Aaryn,e,1.08079,307.82490,110.45534,2.2409361,0.29380546,0.1272074,26.99953,11/5/1990,1950.0,13.95,0.25
Aase,e,5.44751,162.67062,193.30403,2.2081816,0.30036677,0.1899350,25.31938,11/5/1990,1950.0,12.98,0.25
Aavasaksa,e,3.44494,53.62796,45.44658,2.2599735,0.29010088,0.0860588,241.06139,11/5/1990,1950.0,12.60,0.25
Abalakin,e,1.67378,133.14284,112.36794,3.1907570,0.17292726,0.1575985,166.45446,11/5/1990,1950.0,12.27,0.15
Abanderada,e,2.53837,104.43486,94.62475,3.1611860,0.17535938,0.1184558,114.48803,11/5/1990,1950.0,10.88,0.25
Abante,e,3.76230,188.05876,20.26972,3.0394902,0.18599572,0.2848291,283.61482,11/5/1990,1950.0,13.20,0.25
Abastumani,e,19.97473,28.86510,2.55634,3.4351682,0.15480396,0.0256206,215.37544,11/5/1990,1950.0,9.21,0.15
Abell,e,2.04748,81.06151,335.60963,3.0753137,0.18275528,0.1630619,85.85842,11/5/1990,1950.0,12.70,0.25
Abetti,e,9.67257,352.12074,39.01209,3.0140253,0.18835785,0.0904920,6.29801,11/5/1990,1950.0,11.70,0.25
Abkhazia,e,1.46867,227.88836,155.68893,2.6085398,0.23394182,0.1182138,17.37355,11/5/1990,1950.0,13.70,0.25
Abnoba,e,14.40493,228.92151,5.33378,2.7878876,0.21173428,0.1787385,173.05782,11/5/1990,1950.0,9.90,0.15
Abundantia,e,6.45098,38.52356,135.34493,2.5918050,0.23621126,0.0341319,77.18226,11/5/1990,1950.0,9.34,0.25
Academia,e,8.30684,352.20228,40.20118,2.5806075,0.23775034,0.0987000,278.68118,11/5/1990,1950.0,11.07,0.15
Achaia,e,2.38809,206.14119,138.74688,2.1908746,0.30393296,0.2047396,311.26795,11/5/1990,1950.0,13.30,0.25
Achernar,f,1:37:42,-57:15,0.49,2000
Achilles,e,10.33072,315.87310,132.17731,5.1766909,0.08368078,0.1488952,91.77598,11/5/1990,1950.0,8.59,0.15
Aconcagua,e,2.10815,297.00600,349.59845,2.3777122,0.26882221,0.2032587,358.16995,11/5/1990,1950.0,13.70,0.25
Ada,e,4.32214,260.79429,188.04325,2.9653750,0.19301215,0.1826363,19.72227,11/5/1990,1950.0,9.62,0.15
Adalberta,e,6.76053,136.61970,259.48897,2.4686656,0.25410352,0.2504550,4.03763,11/5/1990,1950.0,12.70,0.25
Adams,e,15.11339,0.59263,353.48076,2.5582818,0.24086932,0.1381146,61.46515,11/5/1990,1950.0,12.10,0.25
Adara,f,6:58:38,-28:58,1.5,2000
Adelaide,e,5.99641,202.94821,263.67263,2.2447871,0.29304973,0.1026121,78.33286,11/5/1990,1950.0,12.55,0.25
Adele,e,13.29602,6.86795,352.38711,2.6616737,0.22697178,0.1652603,112.86986,11/5/1990,1950.0,11.30,0.25
Adelgunde,e,7.31217,254.41547,175.70732,2.4423937,0.25821446,0.1928141,226.15837,11/5/1990,1950.0,11.49,0.25
Adelheid,e,21.63329,210.84055,272.96873,3.1134014,0.17941196,0.0721676,311.16146,11/5/1990,1950.0,8.57,0.15
Adelinda,e,2.10874,27.90496,310.68216,3.4010913,0.15713634,0.1585745,51.03133,11/5/1990,1950.0,9.29,0.25
Adeona,e,12.62110,77.06580,44.98563,2.6714825,0.22572288,0.1463971,272.32221,11/5/1990,1950.0,8.05,0.01
Admete,e,9.54836,279.63834,158.97615,2.7354720,0.21784905,0.2270017,69.63125,11/5/1990,1950.0,10.46,0.15
Adolfine,e,9.38402,293.93860,68.03228,3.0252252,0.18731283,0.1179623,2.06061,11/5/1990,1950.0,10.69,0.25
Adonis,e,1.35998,350.57556,41.69158,1.8745105,0.38403628,0.7638749,148.64905,11/5/1990,1950.0,18.20,0.25
Adorea,e,2.43726,120.49032,68.85629,3.1032899,0.18028955,0.1230610,43.62559,11/5/1990,1950.0,8.40,0.15
Adrastea,e,6.17259,180.60316,207.93038,2.9676217,0.19279300,0.2342950,227.39218,11/5/1990,1950.0,10.62,0.15
Adria,e,11.45908,332.69123,252.96411,2.7613818,0.21479016,0.0712927,6.99169,11/5/1990,1950.0,9.24,0.15
Adriana,e,5.95087,118.34125,182.09269,3.1261897,0.17831221,0.0609284,61.75101,11/5/1990,1950.0,10.38,0.15
Adzhimushkaj,e,10.98839,134.99535,354.28304,2.9991220,0.18976358,0.0525055,294.44053,11/5/1990,1950.0,10.70,0.25
Aegina,e,2.11358,10.37779,72.97909,2.5911691,0.23629821,0.1039126,229.14306,11/5/1990,1950.0,8.79,0.15
Aegle,e,16.01987,321.63294,203.40264,3.0521491,0.18483979,0.1384225,349.56390,11/5/1990,1950.0,7.97,0.15
Aehlita,e,4.32804,50.66168,38.75787,2.7717812,0.21358250,0.0614195,28.96342,11/5/1990,1950.0,12.30,0.25
Aemilia,e,6.13070,133.79370,339.06297,3.1005743,0.18052645,0.1087480,311.61239,11/5/1990,1950.0,8.07,0.15
Aenna,e,6.59960,38.63516,193.57035,2.4645927,0.25473366,0.1618100,16.77040,11/5/1990,1950.0,11.81,0.25
Aeolia,e,2.54699,249.81765,19.67710,2.7447746,0.21674249,0.1576949,203.86085,11/5/1990,1950.0,9.77,0.15
Aeria,e,12.72909,93.95337,269.10164,2.6502946,0.22843510,0.0973862,124.56101,11/5/1990,1950.0,8.55,0.22
Aeschylus,e,14.86521,2.49213,97.15763,2.6009176,0.23497096,0.1197472,335.08387,11/5/1990,1950.0,12.68,0.15
Aesculapia,e,1.25398,28.96244,136.59314,3.1510486,0.17620629,0.1316161,225.72477,11/5/1990,1950.0,10.70,0.25
Aeternitas,e,10.61842,41.76994,279.51068,2.7859052,0.21196032,0.1271908,252.62679,11/5/1990,1950.0,8.82,0.25
SHAR_EOF
true || echo 'restore of ephem.db failed'
fi
echo 'End of  part 12'
echo 'File ephem.db is continued in part 13'
echo 13 > _shar_seq_.tmp
exit 0
--
--
Molecular Simulations, Inc.            mail: [e-mail]
796 N. Pastoria Avenue                uucp: uunet!dcmartin
Sunnyvale, California 94086            at&t: 408/522-9236