@Intro
Xephem is a program that computes ephemerides for all the planets, some of
their moons, plus any two user-defined objects.

In addition to information in numeric form, xephem displays simple schematic
views of Saturn, Jupiter, Mars, Luna and Earth as well as maps of the night
sky and the solar system. The sky and solar system maps support labeling and
trailing, and the solar system can be shown as a stereo pair.

Xephem can compute information on demand or time can be set to increment
automatically. In this way a series of computations and movies can be
generated unattended.

Quantitative information available 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.

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 elevation above sea level for the refraction
model and a monthly calendar.

RA/Dec calculations are geocentric and may 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.

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. Xephem includes simple
quick-look facilities to view plot files. The listing files are tables
formatted for more general human reading.

Xephem can read databases of objects. The objects may be fixed or specified
via heliocentric elliptical, hyperbolic or parabolic orbital elements to
accommodate solar system objects such as asteroids or comets.  These are
then available as candidate values for the user defined objects and all of
them can be displayed in the sky map subject to type and magnitude filters.
The format of the database file is described in the Help for the DB menu.

@MainMenu
Across the top of the Main menu is a menu bar to allow selecting the
principle display menus of xephem. These may be turned on in any desired
combination.  Each menu will have its own Close button or it may be closed
by reselecting it from the main menu bar.

    The "File" pulldown is a few miscellaneous controls. The "Reset" entry will
    return xephem to its initial state. The "Messages" entry toggles whether
    the general messages menu is displayed. Note that all messages that go
    to this menu also appear on stdout regardless of whether the menu is
    up.  In order to be sure it is seen, the "messages" menu is always moved
    to the top of the window stack and placed under the pointer whenever it
    is up and new messages are added to it. The "Quit" entry exits xephem.

    The "View" pulldown toggles any of the several xephem displays.

    The "Control" pulldown toggles the plotting, listing and searching control
    menus.

    The "ObjX/Y..." pushbutton toggles the menu that allows you to define
    the user defined objects, ObjX and ObjY. Said menu also allows you to
    inspect each item currently in the xephem database.

    The "DB..." pushbutton toggles the menu that allows to add or replace
    entries in the xephem database from files of database objects.

    The "Preferences" pulldown lists the available preferences that may be
    changed at runtime. The options currently available include whether the
    algorithms are chosen for accuracy or speed; dates are shown and entered
    in month/day/year, year/month/day or day/month/year format; and whether
    local topocentric circumstances are given in English or Metric units of
    measure. Each of these may be initialized via the XEphem resources; see
    the sample XEphem.ad resource file for details.  When the Algorithm
    setting is for Fast, a simpler precession algorithm is used and there
    is no correction for light travel time or nutation.  Whenever the
    preferences are changed at run time, all effected fields are immediately
    recalculated.

    Finally, the "Help" pulldown provides access to several general areas of
    information.

The next row is a status line that contains a short description of what
xephem is doing at the moment with regards to its looping behavior.

Below that is room for the NEW CIRCUMSTANCES message. When you change a
field that would invalidate any of the other fields the message NEW
CIRCUMSTANCES appears near the top of the menu. This will remain until at
least one screen update loop occurs.

See the Help for "Operation" for more information on changing the fields in
the Main menu and controlling xephem's runtime behavior. See the Help for
"Triad formats" for more information on these formats.

Follows is a description of each of the display fields in the Main menu.

 UTC Date      The UTC date.
 UTC Time      The UTC time.
 Julian        The current Julian date, to about 1-second accuracy.
 Sidereal      The sidereal time for the current time and location..
 TZ Name       The local timezone name.  The name field may be changed to any
               three-character mnemonic.
 TZ Offset     Hours local time is behind UTC, ie, positive west or negative
               east of Greenwich.
 Local Date    The local date. This is UTC minus the value of TZ Offset.
 Local Time    The local time. This is UTC minus the value of TZ Offset.

 Twilight Dip  The number of degrees the sun is below the horizon we wish to
               call twilight. This sets the value for the following fields.
 Dawn          Local time when the sun center is "Twilight dip" degrees below
               the horizon before sunrise today.
 Dusk          Local time when the sun center is "Twilight dip" degrees below
               the horizon after sunset today.
 Night Length  Length of astronomical night, ie, Dawn - Dusk.  If this and the
	       display for Dawn and Dusk are shown as "-----", it means the sun
	       is either always below or always above "Twilight dip" degrees
	       below the horizon on this particular day.

 N Steps       The number of times the display will be updated (time advanced
               by Step Size each step) automatically.
 Step Size     The amount of time UTC (and its derivatives) is incremented
	       each loop. 
 Pause         Number of seconds to pause between screen updates. This is
	       used mainly to set up for free-running unattended operation.
	       Pausing is not done when plotting or searching is on.

 Latitude      Location latitude, positive degrees north of equator.
 Longitude     Location longitude, positive degrees west of Greenwich meridian.
 Elevation     Local elevation of the ground above sea level, in feet. (see
	       implementation notes). Used in refraction correction.
 Temperature   Local surface air temperature, in degrees F. Used in refraction
	       correction.
 Atm Pressure  Local surface air pressure, in inches of mercury. Used in
	       refraction correction.
 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.

The calendar on the right of the Main menu is based on UTC. Selecting a date
button will set the date. Unlabeled buttons before the first of the month
and after the last of the month work as expected to also imply a change in
month or year as necessary. The month and year buttons pop up selections
that allow these to be changed as well. In no case does using the calendar
change the current time (just the date).

@Operation
When xephem starts it sets the initial values of several fields from several
X resource values. See the Help for "Initialization" for details of the
format of these resources. 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.

There are three fields that control this looping behavior. "N Steps"
controls the number of steps, "Step Size" the amount of time to add each
step, and "Pause" is the amount of real seconds to pause between steps. When
looping is in effect, the bottom button on the Main menu says "Stop". (Note
that Xephem does not pause between steps when plotting or searching is on.)
When the number of steps goes to 0 or the "Stop" button is selected, the
looping stops and the button is relabeled "Update".

Note that when looping with Pause set to 0, most numeric field data are not
drawn in order to speed up the display. These values are always updated
internally, however. and may safely be used for plotting, searching or
listing. This is true even if the menu that displays the information is
closed.

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. Some of the dialogs have an extra button as a handy
way to enter frequently used values for the field.

When you have changed a field that would invalidate any of the other fields
the message NEW CIRCUMSTANCES appears near the top of the Main menu.  This
will remain until at least one screen update loop occurs.  If you change any
field that causes new circumstances, the "Step Size" value is not added to
the current time after the first loop. Note also that after a series of
loops, "N Steps" is automatically reset to 1 from 0 so "Update" will do
exactly one loop again.
@Credits
First and foremost, I want to thank my lovely and loving wife, Kathy, for
freely accepting me as I am and for encouraging and supporting my passion for
astronomy in general and writing xephem in particular.

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.

Constellation algorithm is 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.

The high-precision precession routine is from 1989 Astronomical Almanac, as
interpreted by Craig Counterman. Mr. Counterman also deserves the credit for
providing the initial encouragement to write an astronomical tool
specifically for X Windows.

The Earth map is derived from one of the demos that comes with gnuplot,
Copyright (C) 1986, 1987, 1990, 1991   Thomas Williams, Colin Kelley.

The moon bitmap is derived from xphoon, Copyright (C) 1988 by Jef Poskanzer
and Craig Leres.

Jupiter's moons based on information in "Astronomical Formulae for
Calculators" by Jean Meeus. Richmond, Va., U.S.A., Willmann-Bell, (c) 1982.

Saturn's moons based on code supplied by Doug McDonald.

Many test cases were gleaned from the pages of Sky and Telescope, (C) Sky
Publishing Corp.

I thank all the organizations behind the incredible Internet for its
maintenance and free and easy access.

National Space Science Data Center and the Institute for Theoretical
Astronomy of the Russian Academy of Sciences for the asteroid database and
the NSSDC and the Smithsonian Astrophysical Observatory for the SAO
database.

The members of the Saguaro Astronomy Club for the preparation and free
distribution of their deep-sky database.

Bright stars are from the Yale Bright Star catalog, as edited by Robert Tidd
(inp@violet.berkeley.edu) and Alan Paeth (awpaeth@watcgl.waterloo.edu). Any
errors in conversion to the ephem.db format are strictly mine.

Special thanks to all the folks over the years who have provided innumerable
ideas, suggestions and bug reports, both for xephem and its ancestor,
ephem.  A major benefit to writing and distributing these programs has been
the chance to make friends from around the world.

@Initialization
Most of the fields in the Main xephem menu can be initialized from the X
resources for class "XEphem".  Of course, you may still change any field
while the program is running too; these just set the initial conditions.

Because of the way unspecified triad components are left unchanged (see
help on Triad Formats) always specify all three for all such entries. For
example, to initialize the longitude to zero degrees, say 0:0:0, not just 0.

 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.
 JD        time specified as a Julian Date.
 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. This is purely a text
           label; xephem makes no attempt to compute anything from this label,
           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.
 Elevation height above sea level, in feet or meters, such as 800. Used to
	   compute parallax of solar system objects.
 Temp      air temperature, in degrees F or C, such as 60.
 Pressure  air pressure, in inches of Mercury or mBar, such as 29.50.
	   Temp and Pressure are used to compute refraction when the AdpHzrn
	   option is active; see the Help for the Data setup table.
 StepSize  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 or a time
           in sidereal days by appending an s (or S) after the number.
 NSteps    number of times program will loop automatically.
           see the discussion under Program Operation.
 Epoch     this sets the desired ra/dec precession epoch. you can put any
           date here (use decimal form, such as 1992.5) or "EOD" to use the
	   current instant ("Epoch of Date").
 Pause     The number of seconds to pause between calculation steps.
 TwilightDip Number of degrees the sun is below the horizon that you want to
	   define as being the end of "twilight"; must be at least 0.
@Date/time
Xephem uses many values that get are entered in some variation of X/Y/Z form.
We call this a "triad" input format.

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 any one of month/day/year, year/month/day
or day/month/year form. A preference selection on the main menu, and controlled
by the XEphem resource DateFormat, selects which form is currently being used.

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/30
the new date will become 20/30/1988. If you then type //2000 the new date will
become 20/30/2000. 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.

Negative years indicate BC dates. For example, Jan 1, 1 BC is given as
1/1/-1.  There is no year 0.

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.

You may also enter a date as a decimal year, as in 1990.12345. Also, when
the date format preference is set to M/D/Y or D/M/Y the decimal point may be
omitted if the value is not a reasonable month or date value, respectively.
Decimal years are useful in interpreting plot files that include a date field,
since date fields are stored in plot files as decimal years. Any input that
includes exactly one decimal point is assumed to be a decimal year.

Other parameters such as longitude, latitude and "Step Size" also fall into
the general triad format. The same rules apply to these with respect to
only having to set the portions that are being changed.

As a matter of typing convenience, the program accepts most any punctuation
character as the separator in a triad; you don't have to type a perfect ":" or
"/".
@Notes
1) 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:

     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

The effect can be significant. For example, the effect is more than two arc
minutes at a height of 5 feet.

2) 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.

3) 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.

4) The calendar shows UTC, including dates of new and full moon.

5) The visual magnitudes for the planets take into account the phase of the
illumination; the magnitudes for other solar system objects do not.

6) Ideas:
 + add tick marks (third axis?) to plots.
 + write a tool to find g/k from a set of predicted magnitudes.
 + search for occultations with all fixed objects.
 + add explicit searching for solar and lunar eclipses.
 + do more moons.
 + add a shorthand for synodic step sizes.
 + add e/w flip option to all displays.
 + use FileSelectionBox to choose plot, listing, and database files.
 + think of a way to display decimal years in plots as m/d/y.
 + incorporate Terrestrial Dynamical Time (known as Ephemeris Time prior to
   1984).  TDT is about 57 seconds ahead of UT1 in 1990.
 + account for lunar augmentation.
 + add undo for plot and listing selections.
 + use a progress meter during long operations, not just the watch cursor.
 + let xephem put things in the root window.
 + add lots more stuff to the Earth display, including interactive selection
   and tracking of lat/long and allow different viewpoints.
 + compute and display libration info in moon view.

Bugs:
 - %0*.* in f_sexad() doesn't work on some systems (needs 0 deleted)
 - should jup moon +y be S???
 - the built-in elements for pluto need to be updated. the elements for pluto
   in the included ephem.db database sampler are more accurate.
 - 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.

Selecting data to plot:

Select the "Select fields" toggle button to make each field in the other
menus that are 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.

Specifying the plot file name:

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, if it already exists, ask
whether you wish to append to the file or overwrite it.

The default plot file name may be specified as the value of the resource
named "XEphem*Plot*Filename.value". If this resource is not specified then
the file name will be "ephem.plt".

Specifying a plot file title:

Enter a short title for the plot information in the text are provided.  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. All lines within
a plot file that do not begin with an alphanumeric character 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 when it displays the plot.

Generating the plot entires:

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 "N Steps" count goes to 1. This greatly
speeds the creation of plot files by avoiding screen updates. If you wish to
watch each iteration, set "N Steps" 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 flush all data and close
the file.

The menus that contain each of the fields used in the plot need not be
visible while the plot is being generated.

Viewing plot files:

Existing plot files may be viewed by entering 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.

The xephem distribution kit includes a sample plot file of the analemma.
@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 more familiar and readable than the entries in plot files.
They are designed to be used in further text processing operations or
printed as-is. Two spaces are placed between each column.

Selecting data to list:

Select the "Select fields" toggle button to make each field in the other
menus that are 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.

Specifying the listing file:

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, if it exists, ask whether you wish
to append to the file or overwrite it.

The default listing file name may be specified as the value of the resource
named "XEphem*List*Filename.value". If this resource is not specified then
the file name will be "ephem.lst".

Specifying a listing file title:

All lines within a listing file that do not begin with an alphanumeric
character 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.

Generating the listing entires:

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 "N Steps" count goes to 1. This greatly speeds the creation
of listing files by avoiding screen updates. If you wish to watch each
iteration, set "N Steps" to 1 and select the "Update" button manually for
each iteration. Once all the desired data have been entered into the listing
file, toggle the list button back off to flush all data and close the file.

Menus that contain each of the fields used in the listing need not be
visible for the fields to be listable.
@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.

To perform a search:
   enter a function,
   compile it,
   select a goal,
   set the desired accuracy,
   enable searching,
   start the search process.

Each of these steps is described below.

Entering the function:

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:

  + - * / && || > >= == != < <=
  abs sin cos tan asin acos atan degrad raddeg pi log log10 exp sqrt pow atan2

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.

Compiling the function:

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. Whenever a search function has been successfully
compiled, the message will read <no compile errors>. Each time a function
is successfully compiled, xephem updates all fields and evaluates the
function. As explained below, this can be used as a sort of "astronomical
calculator" even when not actually searching.

Selecting a search goal:

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 "Step Size" (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.

Specifying the desired accuracy:

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.

Performing the search:

Once the function is defined and it compiles without errors, you may enable
searching by selecting the button at the top labeled "Searching is Active".
Then, each time "Update" is selected on the main menu the search proceeds until
either "N Steps" iterations have occurred or until "Step Size" 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 "N Steps" 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 button labeled "Search is Active" back off.

Additional notes on searching:

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.

The menus that contain each of the fields used in the search function need
not be visible for the fields to used for searching.

The "Close" button removes the search control menu from the screen; it does
not effect actual search operation in any way.

A successfully compiled search function is evaluated each time xephem updates.
Whenever a search function is compiled it is also evaluated using freshly
updated values. In this way, the Search menu can actually be used as an
arbitrary "astronomical calculator" at any time. In each of these cases you
need not be actually `searching' to use these feature.

Hint:

Searching periodic functions can lead to solutions far from the intended
range. 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
This is a table of information about each planet, Sol, Luna, and any two
user defined objects, ObjX and ObjY. Each data item occupies one column in
the table and each object occupies one row.

Select the "Setup" button to configure the table rows and columns as
desired.  The initial configuration can be set from the X resources
DataSelRows and DataSelMiscCols. See the sample XEphem.ad resource file for
examples.

When any columns related to rising or setting are active boxes at the bottom
will indicate whether the Standard or Adaptive refraction model is in
effect and whether the times refer to the center or the upper limb of the
object. Similarly, when any of the separation columns are active a box will
be present to indicate whether the separation is from a geocentric or
topocentric point of view. See the help for the "Setup" menu for more
information about these modes.

Various odd ball rising, transit and setting conditions are accounted for
and marked as follows when they occur:

 NoRise	  up some time but never rises, as such, today.
 NoSet	  up some time but never sets, as such, today.
 NoTran	  up some time but doesn't transit, as such, today.
 CirPol	  object is circumpolar (never goes below horizon) today.
 NvrUp	  object is never up today.
 XX:XX+	  "+" appended to rise, transit or set times means the event occurs
              twice today; the time given is the time of the first event.
	  "+" appended to "Hours Up" means it is still up at midnight.

Any of the information in this table may be plotted, listed or used in a
search algorithm. See the help for these control functions for more details.

See the help for the "Setup" menu for a description of each field.
@DataSelection Table
This menu lets you configure which rows and columns will be in the Data
Table.  When this menu first comes up it will be set to indicate the state
of the Data Table. You may then manipulate the toggle buttons as desired. To
actually change the Data Table to a new configuration select the "Apply"
button.  "Ok" does the same thing but also closes this menu. "Close" just
closes this menu without making any permanent changes. In addition to
manipulating each item individually, each columns includes handy shortcut
controls at the top to make changes to column as a whole.

The first column of this menu selects which rows will be present in the Data
Table. The planets and the sun and moon are always in this column. If user
defined objects ObjX or ObjY are defined then they will also be present and
controllable from this column. See the help for the "ObjX/Y" menu for more
information about user defined objects.

Entries in the remaining three columns in this menu control which columns
will be present in the Data Table. They are grouped into three categories
for convenience.

Column two controls miscellaneous basic information. The descriptions of
each entry are as follows:

 Cns           name of the constellation in which the object appears.
 R_A           apparent geocentric right ascension of object, precessed to
	       given epoch, in hours, minutes and decimal minutes.
 Dec           apparent geocentric declination of object, precessed to
	       given epoch, in degrees and minutes.
 Az            degrees eastward of true north for object.
 Alt           degrees up from a horizontal plane that is Elevation feet above
               sea level.
 HeLong        true heliocentric longitude, in degrees.  Earth's is displayed
               on the sun's line.  For the moon this is the geocentric
	       longitude.
 HeLat         true heliocentric latitude, in degrees.  For the moon this is
               the geocentric latitude.
 EaDst         true distance from Earth center to object center, in AU, except
               distance to the moon is in miles or km depending on the Units
	       preference.
 SnDst         true distance from sun center to object center, in AU.
 Elong         spherical angular separation between sun and given object,
	       calculated from the their geocentric ecliptic coordinates.
	       Note this is not just the 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.  This field is not
	       generally useful in searching for conjunctions because of
	       the discontinuous sign change that occurs at conjunction.
 Size          angular size of object, in arc seconds.
 VMag          visual magnitude of object.
 Phase         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"?).

Column three controls information related to rising, transiting, and
setting.  These may be computed according to two options.

"StdRefr", which stands for "standard refraction", computes rising and setting
based on the standard horizon refraction of 32 arc minutes. This agrees well
will standard publications. "AdpRefr", which stands for "adaptive refraction",
computes rising and setting based on a refraction model that used the actual
atmospheric and topocentric circumstances displayed on the Main menu. This
generally leads to accuracies well within one minute if all conditions are
carefully entered.

"Limb" means that the rise and set circumstances are based on the location
of the upper limb of the object. "Center" means that the circumstances are
based on the location of the center of the object. (In fact, these allowances
are only taken into account for the Sun and moon.)

Follows is a description of the Data Table columns controlled by the third
Data Selection column:

 RiseTm
 RiseAz   The local time and azimuth when the upper limb (or center) of the
          object rises today.
 TrnTm
 TrnAlt   The local time and altitude when the object crosses the meridian
          today, ie, when its azimuth is true south or, if no precession, when
	  the local sidereal time equals the object's right ascension.
 SetTm
 SetAz    The local time and azimuth when the upper limb (or center) of the
          object sets today.
 HrsUp    The number of hours the object is up today, that is, the difference
	  between the set and rise times.

Note that these times are for the current local day. See the description of
"odd ball" circumstances that this definition can produce and how xephem
reports them.

The last column in the Data Table setup menu controls for which objects
angular separation is computed.  Each entry in the Data Table will be the
angular separations between each pair of objects, in degrees.

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.

When ObjX or ObjY are defined, these will appear in the last column and
separations between them and the other objects (in column 1) may be selected
for display.

Note:

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.
@Mars
This menu displays the central meridian longitude of Mars, that is, the
Martian meridian currently facing towards Earth.  This value may be selected
for plotting, listing and searching as described in the help for these
functions.

Also included in this menu is a simple schematic display of the Martian
surface at the current time. I would like to find a map with a bit more
detail.

@Earth
This menu displays a simple map of the Earth oriented so that the subsolar
point is centered. The subsolar point is the location on the Earth from which
the sun appears to be directly overhead. Another way to interpret the display
is to think of it as displaying exactly that portion of the Earth currently in
sunlight. The subsolar point is marked with a cross.

The latitude and longitude of the current subsolar point are displayed and may
be selected for plotting, listing or searching as described in the help for
those functions.

It is interesting to set the step size to a few integral number of days and
watch the change in latitude. Plotting latitude vs. longitude over the
course of a year is equivalent to plotting the analemma.

Remember that the numeric information is not updated while looping with Pause
set to 0.
@Sky View
This menu displays each object currently loaded in the xephem database with
several display options, subject to filtering by type and magnitude range.  The
central display is intended to be similar to a telescopic view.  Descriptions
of each function are keyed to the schematic depiction below:

		    _____________________________________________
		    |Alt-Az  |   | [Alt]               [Az] |   |
		    |RA-Dec  | F |                          | A |
		    |--------| O |                          | l |
		    |Grid    | V |                          | t |
		    |--------|   |                          |   |
		    |F Mag   |   |                          | / |
		    |B Mag   |   |           Sky            |   |
		    |--------|   |                          | D |
		    |Dots    |   |                          | e |
		    |Ecliptic|   |                          | c |
		    |Labels  |   |                          |   |
		    |--------|   |                          |   |
		    |Locate  |   |                          |   |
		    |--------|   | [RA]               [Dec] |   |
		    |        |___|__________________________|___|
		    |        |             Az / RA              |
		    |        |__________________________________|
		    |        |         Date/Time stamp          |
		    |________|__________________________________|
		    |   Filter          Close            Help   |
		    |___________________________________________|

Alt-Az / RA-Dec
    The radio box in the upper left corner selects whether the display
    coordinate system is Altitude-Azimuth or Right Ascension-Declination.
    Whenever the Alt-Az system is used, nothing is displayed that would lie
    below the current horizon (except trails; see note under Sky).

    The orientation of the display circle is always without reflections. In
    Alt-Az mode, left, right, up and down as are they would appear to the
    otherwise unaided eye. In RA-Dec mode, up is always celestial north, left
    is always celestial East. The meridian named by the horizontal slider is
    always the line between the center of the field-of-view and the nearest
    pole.

Grid
    The toggle button labeled "Grid" controls whether a calibration grid will
    overlay the display. When the grid is displayed, its graduation is displayed
    below the toggle button.

F Mag / B Mag
    The two sliders on the left set the brightness range being displayed. Only
    objects that are currently within the selected range will be shown on the
    display. Note that sliding either scale beyond its opposite is not permitted
    but it is permitted to do this by selecting in the slider trough should you
    really want to do this (to turn off all objects).

    Note this does not effect trails.

Dots
    The toggle on the left labeled "Just Dots" selects how objects are drawn.

    When the toggle is pushed in, objects of all types are displayed simply as
    dots.  The diameter of the dots equals the difference between its magnitude
    and the faintest magnitude. In this way the size of the dots can be changed
    as desired.

    When the toggle is released, each type of object is displayed with a unique
    schematic symbol. These symbols may be viewed from the Filter menu. In this
    case too the size is proportional to magnitude above the faintest limit.

    In either form, the color of the object is displayed according to the value
    established for each basic type in the X resource database.  See the sample
    XEphem.ad resource file for examples of setting object colors.

Ecliptic
    The toggle on the left labeled "Ecliptic" selects whether a dotted line is
    drawn along the ecliptic. The ecliptic is the plane of the Earth's orbit
    or, as seen from Earth, the path of the Sun and the approximate path
    of the planets across the sky.

Labels
    The toggle on the left labeled "All labels" controls whether the labels
    for all objects are forced on. This does not effect which objects have
    their individual "Persistent label" options on.

Locate
    The button labeled "Locate..." will pop up a list of the basic objects and
    the defined user defined objects, if any. Selecting any of these entries
    will place a cross-hair over the object. If the object is not within the
    field of view the object will first be centered, unless Alt-Az mode is 
    currently active and the object is below the horizon. To locate other
    objects use the ObjX/Y menu.

FOV
    The left vertically-oriented slider controls the field-of-view of the
    display circle. This can be varied from 1 to 180 degrees.

[Alt] [Az] [RA] [Dec]
   The coordinates of the cursor are tracked and displayed across the bottom
   and top of the circular display area as long as it is within the circle and
   the left mouse button is depressed.

   NOTE: The values displayed during tracking for the coordinate system
   opposite to the one currently in effect may not agree exactly with
   the values displayed elsewhere by xephem, particularly for close solar
   system objects. To understand why recall that in all these other displays
   xephem computes geocentric RA/Dec and topocentric Alt/Az. Recall further
   that parallax contributes significantly to the difference between these
   points of view and parallax depends on the distance to each particular
   object. Thus, there is no single transformation between these coordinate
   systems that is correct for all objects. During tracking, the transformation
   to the coordinate system opposite to the one in current use by the Sky View
   display is computed without regard to parallax; this is strictly correct
   only for objects very far away. This has the useful result that while in
   RA/Dec coordinate mode the tracking values for Alt/Az may be thought of as
   being geocentric; and while in Alt/Az mode, RA/Dec will be topocentric.
   
Sky
    The center circular area is the sky display of objects. Follows is a
    description of the operations that may be performed in this area using the
    pointer.

    If the pointer is placed near a visible object and the third button is
    pushed, a popup will appear. This will present several basic data for the
    object. This data is exactly the same as that which is available in the
    Data Table menu; see it's Help for more information. If a trailed object is
    selected, the data will be as it was at the time the position was created.
    In addition, the popup offers several control operations, as follows:

	Selecting "Point" from the popup will center the object in the field of
	view (as well as can be done with the accuracy of the pointing scales
	anyway).

	Selecting "Make ObjX/Y" will assign the given object to become ObjX
	or ObjY, depending on which one is currently being displayed in the
	ObjX/Y menu. See the help for the ObjX/Y menu for more information on
	that menu.

	Selecting "Leave Trail" will start to accumulate all positions of the
	given object as time is advanced. Each new location will be connected
	with a line to its previous location. The trails remain correct if the
	display coordinate system is changed. Trails may be turned on or off
	without loss of trail information. However, trailing information is
	discarded if trailing is turned off when a new time step is performed.
	If any point in a trail is selected the information displayed is as per
	the object at that time. The fastest way to accumulate trailing
	information is to turn trailing on and pop the menu down while running.

	Note that in Alt-Az mode, if an object goes below the horizon the line
	segments of the trail are displayed but not the actual points.

	Selecting "Persistent Label" will place the name of the object near it
	on the display. This will remain until the label is turned off. Note
	this option is maintained separately for trailed objects and for
	the untrailed objects; that is, you have independent control over
	labeling for a trailed object and its currently displayed object
	since the latter also always appears in the trailed list.

    The coordinates of the cursor are displayed in the corners of the circular
    sky area as long as the cursor is within the central circle and the left
    mouse button is depressed.

Alt / Dec
    The right vertically-oriented slider controls one of two axes that
    defines the direction in which the display points. In Alt-Az mode this
    controls altitude and can be varied from 0 to 90 degrees. In RA-Dec mode
    this controls Declination and can be varied from -90 to +90.

Az / RA
    The bottom horizontally-oriented slider controls one of two axes that 
    defines the direction in which the display points. In Alt-Az mode this
    controls azimuth and can be varied from 0 to 359 degrees.  Azimuth 0 is
    north and increases eastward. In RA-Dec mode this controls Right Ascension
    and can be varied from 0 to 23.9 hours.

Date/Time Stamp
    This displays the date and time for which the display is valid.

Filter
    The Filter button along the bottom brings up a menu that controls
    whether classes of objects are displayed. Using the Filter menu, one may
    select which classes of objects are desired. Selecting "Apply" updates
    the sky display according to the desired selection. Selecting "Ok" does
    the same thing but also closes the filter menu.

    For reference, the Filter menu also contains the schematic symbol for each
    type of object, and its code when used in a database file.
@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 -- think of it as a rotation about
the central axis. The vertical slider on the right controls the heliocentric
latitude -- your angle above the ecliptic plane.

Any feature may be identified by pointing near it and clicking the right
mouse button. This will bring down a temporary popup menu with additional
information until the button is released. The RA/Dec given for the Earth is
that of the sun.  All RA/Dec info displayed is for the epoch as it was set
on the Main menu when the dot was computed.

The "Leave trails" option can be used to retain old dots. By turning on the
"Connect dots" option, these dots are connected by line segments. The
fastest way to accumulate lengthy trail operation is to turn on trailing
and run with the menu popped down.

The planets may be individually turned on and off, without loss of any
display data associated with them, by using the toggle panel near the
bottom. If ObjX or ObjY are defined and are solar system objects then they
will appear on the display and in the list.

The bottom button marked "Stereo" is used to bring up another image of the
solar system from a slightly displaced vantage point. Adjusting your gaze to
fuse the two images together will reveal a 3D image. This effect is most
pronounced if trails have been turned for a significant portion of the
orbits of the objects of interest. This effect was designed primarily to
help visual the orbits of comets.

At the bottom of the stereo display is a slider to control the location of
the second vantage point. When the slider is in the center both views are
identical.  Moving the slider to the left will display the scene as though
the viewer has moved such as to move the objects to the left. Objects closer
to the viewer move more. Moving the slider to the right does the same but in
the opposite direction. In this way, you may adjust the stereo effect to be
most comfortable to you, and with or without requiring crossed eyes.

Closing the main Solar System menu will close both it and the Stereo menu,
If the Solar System menu is closed while the Stereo menu is on, it will
reappear when the Solar System menu is reactivated.  if it is up.
@DataBase menu
This menu allows you to inspect and modify the collection of objects that
are currently in memory. These objects form what is referred to as the
xephem database.

The top portion of the menu displays a count of each major type of object in
the database.

Xephem supports files that contain descriptions of objects. These files may
be read into memory either adding to the current database or replacing it.
Enter the name of the desired xephem database file in the text area provided
then select either "Append" or "Replace", respectively.

The default database filename may be specified by setting the X resource
named "XEphem*DBPromptD.textString". The internal default name is
"ephem.db".  The xephem distribution kit includes a sample ephem.db that
contains more than 15,000 objects of all types.

Also available from the author is the entire Smithsonian Astrophysical
Observatory star list. These have been sorted into ten sky regions. There is
one file per region. The entire set is some 11MB.

Follows is a description of the format of these database files. This format
remains compatible with the "ephem" dumb-terminal version of xephem for
those interested.

Note that the "Filter" menu accessible from the "Sky View" menu also includes
a list of the type codes for each object, for easy reference.

 Each object occupies one line. Fields are separated with commas. Some fields
 are further subdivided into subfields with vertical bars (|). Lines
 beginning with anything other than a-z, A-Z or 0-9 are ignored and may be
 used for comets. Objects may be in any order.

 Where they appear, all date fields may be in either of two forms:

   1) month/day/year, where day may contain a trailing decimal portion.
     examples: 1/1/1993 and 1/1.234/1993
     NOTE: this is always the format of dates in database files, regardless of
     the current xephem run-time Data format preference setting.

   2) a real-number, such as 1993.123.

 The first two fields are always Name and Type. Remaining fields depend on the
 form of the object's motion.

 The Name field is the object's name.

 The Type field always starts with a single letter designating the form of
 the object's motion:
   f: fixed (no proper motion)
   e: heliocentric elliptical orbit
   h: heliocentric hyperbolic orbit
   p: heliocentric parabolic orbit

   if "Type" is fixed, an object class code may follow in the next subfield:
       C: Cluster, globular
       U: Cluster, with nebulosity
       O: Cluster, open
       G: Galaxy, spiral
       H: Galaxy, spherical
       A: Cluster of galaxies
       N: Nebula, bright
       F: Nebula, diffuse
       K: Nebula, dark
       P: Nebula, planetary
       Q: Quasar
       T: stellar object
       B: Star, binary
       D: Star, double
       M: Star, multiple
       S: Star
       V: Star, variable

   if class is one of T, B, D, S or V, the spectral class and possibly the
   numerical subclass designation may follow in the next subfield:
       O, B, A, F, G, K, M, N, C, S

 For other object types, the remaining fields are defined as follows:

 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 = mean daily motion, degrees per day (computed from a**3/2 if omitted)
	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; select which by preceding the first field
	    with either a "g" or an "H"; H/G is the default if neither is given.
	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
	Declination, degrees
	magnitude
	reference epoch
	s = angular size, arc minutes, optional
@Object
Xephem supports two user-defined objects, denoted ObjX and ObjY. These may
be fixed objects or objects in elliptical, hyperbolic or parabolic
heliocentric orbits. The ObjX/Y dialog allows you to define these objects.

Xephem maintains a working copy of these objects for use with the ObjX/Y
menu that is separate from the real ObjX and ObjY. The ObjX/Y menu always
works on these working copies. The working copies and the real ObjX/Y only
interact when using the Ok, Apply and Reset control, as described shortly.

The ObjX/Y menu is always displaying information from one or the other of
these working copies as indicated by the small radio box in the center of
the menu at the top. This box may also be used to changed whether ObjX or
ObjY is being displayed and manipulated. We will refer to the one selected
as the "current working object."

The radio box in the upper left displays the basic type of the current
working object. This can be changed by selecting another of the collection
of toggle buttons.

In the left and center of the menu is an area that lists each field for the
current working object and its present value. The list is adjusted to
correspond to the fields that are associated with the type of the current
working object. These fields may be changed by selecting the button that
contains their value. This will bring up a small text entry dialog. A new
entry may be typed into the dialog box and applied by hitting RETURN or
selecting the "Ok" button. The value may be left unchanged by selecting
"Cancel".

Along the right edge of the ObjX/Y menu is a list of each object currently
loaded into the xephem database. (See the Help for the "Data Base" menu for
more information on manipulating this data base.) If there are more than 20
items then a scroll bar may be used to browse through the list. The entries
are sorted in numeric and alphabetic order for easy selection.  If one of
these objects is selected, then it is copied to the current working object.
You may then further edit the values for this working object as desired.

When the current working object is as you want it, select "Apply" to copy it
the real ObjX (or ObjY) used throughout the other functions of xephem. "Ok"
will do the same thing and also close the ObjX/Y menu.

Selecting "Reset" will load the current working object with a copy of the
real ObjX (or ObjY).

Selecting "Sky Point" will move the center of the field of view on the "Sky
View" menu so that the current working object is centered and a cross-hair
is drawn over the object. This change in pointing direction and marking will
take place even if the object is not in the Sky View type filter or within
the magnitude range. Note that the Sky View display will _not_ be changed if
it is set to Alt-Az mode and the current working object is below the
horizon.

Selecting "Sky Mark" will draw a cross-hair on the Sky View menu at the
location of the current working object if it is within the Sky View field of
view. The Sky View menu is never reaimed with this command.

Follows is a description of each field for the type of the current working
object. To get a description of the fields for other types of objects,
change the type of the current working object and reselect Help.

@Fixed Object
+Object
Fixed objects are characterized by five parameters:

    RA,
    Dec,
    magnitude,
    the reference epoch for the coordinates and
    angular size in arc seconds, optional

Note:

In order to conserve memory usage, xephem stores the RA and Dec for a fixed
object only once with each object. These values are always precessed _in
place_ to the current display epoch. Thus, you will find that the RA and Dec
displayed for a given object may change if the epoch is changed on the main
menu and the object information is redisplayed here on the ObjX/Y menu.
@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:

    i = inclination, degrees
    O = longitude of ascending node, degrees
    o = argument of perihelion, degrees
    a = mean distance (aka semi-major axis), AU
    n = mean 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  = either of two magnitude models; see below
    s = angular size at 1 AU, arc seconds, optional


You might have other parameters available that can be converted into these. 
The following relationships might be useful:

    P = sqrt(a*a*a)
    p = O + o
    n = 0.9856076686/P
    T = E - M/n
    q = a*(1-e)
    AU = 149,597,870 km = 92,955,621 U.S. statute miles
 where
    P = the orbital period, years;
    p = longitude of perihelion, degrees
    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.

Xephem 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.

+OBJXY_gkMAGNITUDE
When using this model for elliptical objects, the first of the two magnitude
fields must be preceded by a letter "g". This applies 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.

+OBJXY_HGMAGNITUDE

The H/G model 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". This works 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:

    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

As with elliptical elements, other parameters might be available.  The
relationships are generally the same, except for:

    q = a*(e-1)

+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:

    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

+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:

    m = g + 5*log10(D) + 2.5*k*log10(r)
 where:
    m = resulting visual magnitude;
    g = absolute visual magnitude;
    D = comet-earth distance, in AU;
    k = luminosity index; and
    r = comet-sun distance.

Note that this model does not take into account the phase angle of sunlight.

@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:

    beta = acos((rp*rp + rho*rho - rsn*rsn)/ (2*rp*rho));
    psi_t = exp(log(tan(beta/2.0))*0.63);
    Psi_1 = exp(-3.33*psi_t);
    psi_t = exp(log(tan(beta/2.0))*1.22);
    Psi_2 = exp(-1.87*psi_t);
    m = H + 5.0*log10(rp*rho) - 2.5*log10((1-G)*Psi_1 + G*Psi_2);
 where:
    m   = resulting visual magnitude
    rp  = distance from sun to object
    rho = distance from earth to object
    rsn = distance from sun to earth

Note that this model does not take into account the phase angle of sunlight.
