	Instructions for the BINARY package for Unix

     This file explains how to compile, link, and use the programs binary.exe,
editbinary.exe, one2two.exe, and associated demo and plot routines on a Unix
machine.  The program "binary" allows one to combine 2-D positional (XY and
Theta-Rho), and spectroscopic data in order to simultaneously solve for the
orbital elements and ratio of semimajor axes, system radial velocity, proper
motion, and parallax, if possible, of a binary or multiple star system.  Some
features of the program are:
1) Up to 10000 data points can be considered
2) Any data point can be ignored by setting its sigma in the file to
a key value
3) The weights for a file can be scaled at run time
4) Points can be excluded from the solution based upon their phase
5) Each spectroscopic component is allowed to have up to five spectroscopic
subcomponents, present in the parent's file and/or in separate files,
for a maximum of twelve objects
6) Apsidal motion for the main components and subcomponents can be solved for
7) Optional allowance for the light travel time across the orbit for the
spectroscopic data, including subcomponents, can be made
8) When possible, the mass(es) and mean error(s) are calculated
9) The reduced chi squared is calculated for each data dimension
10) The errors of each parameter are calculated
11) Any parameter or combination of parameters can be held constant in the
solution
12) The solution can be rerun with points which deviate beyond some factor
times the sigma, excluded
13) The data and the solution can be plotted over the entire time span
or over one cycle, with and without the subcomponents, and with the
subcomponents alone.
14) The residuals of the visual data can be written to a file in standard
format for further analysis
15) The program can be run with input parameters contained in a "save"
file and with some of them optionally specified on the command line.
16) The program can also solve for the orbits of planets around a single 
star.

The companion program "editbinary" allows one to edit values in the standard
data files.  Arithmetic operations are performed on one or more columns
simultaneously.  Some of the operations are:
1) Adds or multiplies the data values
2) Precesses the coordinates of the data
3) Smooths the data by averaging over specified intervals
4) Allows manual entry of visual, spectroscopic, and 1-D interferometric data
points
5) Converts weights to sigmas
6) Creates artificial visual, spectroscopic, and 1-D interferometric data from
user supplied elements.

The program "one2two" fits a cosine curve to 1-D interferometric data
consisting of projected baseline angle, and projected binary separation, and
derives the two-dimensional data point, position angle and separation which
can then be used in the above "binary" program.

Also included with the package are four demonstration programs, nl_demo_1.exe,
nl_demo_2.exe, nl_demo_3.exe, and nl_demo_4.exe which utilize the nonlinear 
least squares subroutine, nonlinfit, which is used by binary, and
the plot package programs plotcom.exe and xyplot_ascii.exe, which are used
for directing a plot file to any supported plot device, and for plotting
data from one or more ascii files on any supported plot device, respectively.
     To use the compiled versions on a Linux system with Intel processor, or
on Mac OS X, download binary_linux_executables.tar.gz or 
binary_macosppc_executables.tar.gz, respectively from the link at
http://www.chara.gsu.edu/~gudehus/binary.html, and then extract the execute
images and other files.  The compiled versions should work on any Linux/Intel
or Mac OS X system, but if the system libraries have been changed from their
default versions some programs might crash.  One known vulnerability is the
FORTRAN call to DTIME.

After the executables are on your system, you should define some aliases
which are described further below.

     If you wish or need to recompile, you can download the file
binary_unix_source.tar.gz from the download link at 
http://www.chara.gsu.edu/~gudehus/binary.html, and then extract the source
code and other files.
     Once you have binary_unix_source.tar.gz available on your Unix 
machine, just enter
  gzip -d binary_unix_source.tar.gz
  tar -xf binary_unix_source.tar
from a desired directory location.  Set default to the newly created binary 
directory and enter
  make linux
for Linux systems, or
  make macosintel
for MAc OS X Intel systems, or
  make macosppc
for Mac OS X PPC system, or
  make ultrix
for Ultrix systems, and
  make unix
for other Unix systems.  It is also possible to use the command
  make -f makefile-binary.pgf77
for Linux systems, for example.  Ignore any warning messages.

     The programs will compile and link on a DECstation with the
default compiler.  For Linux on Intel processors, and for Mac OS X
on Intel processors, you will need to have installed the Portland 
Group f77 compiler (http://www.pgroup.com).  A free 15-day trial 
version of their compiler is available from their website.  Their 
compiler also works for Solaris on Intel processors, but I have not
tested this.  Presumably, the linux makefile should work for their 
compiler on Solaris as well.  Other brand compilers may possibly
work with this code but I have not investigated them.  For Mac OS X 
PPC you will need to have installed the Absoft Pro Fortran compiler 
(http://www.absoft.com).  A free 30-day trial version of their 
compiler is available from their website.  The Absoft f77 compiler 
doesn't support variable FORMAT expressions which necessitated 
creating a special set of files just for that compiler.  Also, 
the Absoft compiler has a bug with handling %REF with character data.  
A special usrinp.for, i.e., usrinp_char.for, was created to handle 
this problem.  New subroutines for this and other limitations are 
located in the subdirectories mac_os_ppc.  The compiled PPC version 
will also run on Macintoshes which use the Intel processors and are 
able to run Rosetta.  The Portland Group's compiler for Mac OS X with
Intel will also work with the  make file included in this package.
     For other Unix flavors the default f77 compiler may or may not work.
A compatible compiler should support BYTE data type, ENCODE, DECODE, %REF,
%VAL, variable FORMAT expressions, CARRIAGECONTROL keyword, and PARAMETER
statement with or without parentheses.  For the C code files, the
built-in compiler will work.

A brief description of the source code files follows.

In the directory binary, one should have the files:

   Name         				Description
bessyr_julcent.for			Routine to convert from Besselian 
					years to Julian centuries
binary.for				Main program for binary stars
binary_exclude_by_phase.for		Routine to exclude data by phase
binary_indexes.for			Routine to establish offsets in	
					parameter array
binary_ltt_cor.for			Routine for light travel time 
					correction
binary_linux_executables.com		Command file to tar and compress
					the executables for Linux
binary_macosintel_executables.com	Command file to tar and compress
					the executables for Mac OS X Intel
binary_macosppc_executables.com		Command file to tar and compress
					the executables for Mac OS X PPC
binary_ultrix_executables.com		Command file to tar and compress
					the executables for Ultrix
binary_unix_executables.com		Command file to tar and compress
					the executables for Unix
binary_unix_source.com			Command file to tar and compress
					the source code files for Unix
by_jd.for				Routine to compute Julian date
					from the Besselian year
cofactor.for				Routine to compute a cofactor
cofactor1.for				Helps cofactor.for
date_jd.for				Routine to compute Julain day 
					number
daxpy.for				Required lower level routine
dcopy.for				Required lower level routine
ddot.for				Required lower level routine
determnt.for				Routine to compute a determinant
determnt1.for				Helps determnt.for
dhhms.for				Routine to compute h, m, and s
display-plotting_availability.dat	List of available plot devices
dpaversigwt.for				Routine to calculate weighted average
					and sigma
dspfa.for				Routine to factor a matrix	
dspdi.for				Lower level routine to compute a
					determinant
dswap.for				Required lower level routine 
earth.for				Routine to calculate Earth's 
					parameters
editbinary.for				Main program to edit binary data
eqhor.for				Routine to compute azimuth, altitude,
					and zenith distance
etdate_jc_by.for			Routine to calculate Julian 
					centuries and Besselian years
fringe_angle.for			Routine to compute baseline
					angle projected on sky
get_binary_header.for			Routine to read data file header
get_eclipse_epochs.for			Routine to calculate epochs of possible
					eclipses for spectroscopic binaries
hmsdh.for				Routine to compute decimal hours
horeq.for				Routine to calculate equatorial
					coordinates from horizon coordinates
idamax.for				Required lower level routine
jd_by.for				Routine to compute the Besselian 
					year from the Julian date
jd_date.for				Routine to compute the date from 
					the Julian day number
jd_sun.for				Routine to compute the sun's position
					on the sky 
kepler.for				Routine to solve Kepler's equation
makefile				General makefile to compile and 
					link all the executables
makefile-binary.macosppc		Makefile for Mac OS X PPC w/Absoft compiler
makefile-binary.pgf77			Makefile for Linux w/Portland Group compiler
makefile-binary.pgf77macos32		Makefile for Mac OS X Intel w/Portland Group
					compiler.  This compiles as 32 bits, but will
					also run under 64-bit systems.
makefile-binary.ultrix			Makefile for Ultrix
makefile-binary.unix			Makefile for other Unix
matrixinv.for				Routine to invert a matrix
matrixinv1.for				Helps matrixinv.for
nhint.for				Required lower level routine
nlder_binary.for			Routine for nonlinear least 
					squares adapted for binary.for
					amd demos
nlder3.for				Derivative for binary solution
nlder14.for				Derivative for one2two solution
nlder_demo_1.for			For nonlinear least squares demo
nlder_demo_2.for			For nonlinear least squares demo
nlder_demo_3.for			For nonlinear least squares demo
nlder_demo_4.for			For nonlinear least squares demo
nlfun_binary.for			Routine for nonlinear least 
					squares adapted for binary.for 
					and demos
nlfun3.for				Function for binary solution
nlfun14.for				Function for one2two solution
nlfun_demo_1.for			For nonlinear least squares demo
nlfun_demo_2.for			For nonlinear least squares demo
nlfun_demo_3.for			For nonlinear least squares demo
nlfun_demo_4.for        		For nonlinear least squares demo
nl_demo_1.for				Nonlinear least squares demo
nl_demo_2.for				Nonlinear least squares demo
nl_demo_3.for				Nonlinear least squares demo
nl_demo_4.for				Nonlinear least squares demo
nlit.for				Routine for iterating in 
					nonlinfit.for
nonlinfit.for				Routine for generalized nonlinear
					least squares
nonlinfit1.for				Helps nonlinfit.for
one2two.for				Program to fit cosine curve to a set
					of 1-D interferometric data
parallaxfactors.for			Routine to calculate parallax 
					factors
ploterrs.dat				Plot package error messages
precessio.for				Routine to compute precession
print_binary_header.for			Routine to print binary star data
					file header on terminal
strludef.for				Required lower level routine
syminv.for				Lower level routine to solve a 
					system of linear equations
utgst.for				Routine to compute the mean Greenwich
					sidereal time
vel_amp_error.for			Routine to compute error of K
write_binary_header.for			Routine to write binary star data
					file header
xyplot_setup.dat			Setup file for xyplot_ascii.exe
xyplot_setup1.dat			Setup file for xyplot_ascii.exe in demo
xyplot_setup2.dat			Setup file for xyplot_ascii.exe in demo
xyzeceq.for				Routine to calculate equatorial 
					Rectangular coordinates

In the directory binary/include one should have the files:

   Name						Description
binary_header.for			Include file for get_binary_header.for
binary_parameters.for			Binary parameters include file
plotpar.for				Plotting parameters include file
sao_default_vlt.for			Default lookup table for Enhanced
					SAOimage
saofacts.for                            Common block for Enhanced SAOimage



In the directory binary/mac_os_ppc one should have the files:

   Name                                         Description
binary.for				Mac OS X/Absoft version
editbinary.for				Mac OS X/Absoft version
nl_demo_1.for				Mac OS X/Absoft version
nl_demo_2.for				Mac OS X/Absoft version
nl_demo_3.for				Mac OS X/Absoft version
nl_demo_4.for				Mac OS X/Absoft version
nonlinfit1.for				Mac OS X/Absoft version
one2two.for				Mac OS X/Absoft version
print_binary_header.for			Mac OS X/Absoft version
write_binary_header.for			Mac OS X/Absoft version

In the directory binary/plot one should have the files:

   Name						Description
alogcode.for				Lower level plot routine
alogdeccode.for				Lower level plot routine
alogdecode.for				Lower level plot routine
alogaxis.for				Lower level plot routine
apple.for				Lower level routine for postscript
appleplot.for				Lower level routine for postscript
arrowhead.for				Lower level plot routine
axis.for				Lower level plot routine
bell.for				Routine to ring the bell
color_24_triplet.for			Lower level plot routine
color_input.for				Lower level plot routine
colormode.for				Lower level plot routine
colormode_background.for		Lower level plot routine
crosshair.for				Lower level plot routine
datalevel.for				Lower level plot routine
decode_intervals.for			Lower level plot routine
delay.for				Routine to produce a delay
errorbar.for				Lower level plot routine
fillmode.for				Lower level plot routine
findplot.for				Lower level plot routine
get_dp_availability.for			Lower level plot routine
histogram.for				Lower level plot routine
imtoolchecksum.for			Required lower level routine
issubsup.for				Lower level plot routine
keyboard.for				Lower level plot routine
limit.for				Lower level plot routine
line_symbl.for				Lower level plot routine
line.for				Lower level plot routine
makefile				Main makefile for plot files
makefile-binary_plot.linux		Makefile for Linux
makefile-binary_plot.macosppc		Makefile for Mac OS X
makefile-binary_plot.ultrix		Makefile for Ultrix
makefile-binary_plot.unix		Makefile for other Unix
nhint.for				Required lowel level routine
number.for				Lower level plot routine
penmode.for				Lower level plot routine
plot.for				Lower level plot routine
plotcom.for				Program to plot from plot file
plotdevices.for				Lower level plot routine
plotdevices2.for			Lower level plot routine
plotdevques.for				Lower level plot routine
pltdev.for				Lower level plot routine
pltread.for				Lower level plot routine
pltwrite.for				Lower level plot routine
prtmsg.for				Required lower level routine
resettek.for				Lower level plot routine
sao.for					Lower level plot routine
sao_curn.for				Lower level routine for SAOimage
sao_display_vect.for			Lower level routine for SAOimage
sao_draw.for				Lower level routine for SAOimage
sao_erase_cursor.for			User routine to erase cursors
sao_load_vlt.for			Lower level routine for SAOimage
sao_vect.for				Lower level routine for SAOimage
saocaption.for				Lower level routine for SAOimage
saoconvlt.for				Lower level routine for SAOimage
saoeras.for				Lower level routine for SAOimage
saofirst.for				Lower level routine for SAOimage
saoplot.for				Lower level plot routine
saostart.for				Lower level routine for SAOimage
scale_axis.for				Lower level plot routine
si_subs.c				Lower level routine for SAOimage
si_subs.h				Lower level routine for SAOimage
strludef.for				Required lowel level routine
symbol.for				Lower level plot routine
symgen.for				Lower level plot routine
symgengr.for				Lower level plot routine
sys_keyin.c				Lower level plot routine
tek.for					Lower level plot routine
tekcon.for				Lower level plot routine
tekpau.for				Lower level plot routine
tekplot.for				Lower level plot routine
textcnch.for				Lower level plot routine
transparent_mode.for			Program to go from Tek to terminal
transparent_mode_x.for			Program to go from Tek to terminal
					for xterm
transparent_mode_xn.for			Program to go from Tek to terminal
					for xterm without erasing plot
transparent_to_tek.for			Lower level plot routine
vectmode.for				Lower level plot routine
where.for				Lower level plot routine
xyplot.for				High level subroutine for
					XY plots
xyplot_ascii.for			Program to plot from one or more ASCII
					files
xyplot_f.for				Lower level plot routine
xyplot_setup.for			Lower level plot routine

In the directory binary/plot/mac_os_ppc one should have the files;

   Name                                         Description
apple.for				Mac OS X/Absoft version
crosshair.for				Mac OS X/Absoft version
errobar.for				Mac OS X/Absoft version
imtoolchecksum.for			Mac OS X/Absoft version
line.for				Mac OS X/Absoft version
line_symbl.for				Mac OS X/Absoft version
number.for				Mac OS X/Absoft version
plotcom.for				Mac OS X/Absoft version
plotdevices.for				Mac OS X/Absoft version
pltread.for				Mac OS X/Absoft version
pltwrite.for				Mac OS X/Absoft version
scale_axis.for				Mac OS X/Absoft version
si_subs.c				Mac OS X/Absoft version
si_subs.h				Mac OS X/Absoft version
xyplot.for				Mac OS X/Absoft version
xyplot_ascii.for			Mac OS X/Absoft version
xyplot_setup.for			Mac OS X/Absoft version

In the directory binary/utilities one should have the files:

   Name						Description
alpha.for				Character processing routine
bell.for				Routine to ring the bell
dcd.for					Routine to help usrinp.for
do.for					Routine to help usrinp.for
dynamic.for				Routine to obtain dynamic memory
dynamic_c.c				Routine to obtain dynamic memory
error.for				Required lower level routine
get_os_bytes.for			Routine to get OS number of bytes
get_os_bytes_c.c			Routine to get OS number of bytes
inel.for				Routine to help usrinp.for
makefile				Main makefile for utility files
makefile-utilities.linux		Makefile for Linux
makefile-utilities.macosppc		Makefile for Mac OS X
makefile-utilities.ultrix		Makefile for Ultrix
makefile-utilities.unix			Makefile for other Unix
message.for				Routine to display messages
nel.for					Routine to help usrinp.for
neld.for				Routine to help usrinp.for
opencf.for				User routine to open a character file
release_memory_c.c			Routine to release dynamic memory
save.for				Routine to help usrinp.for
strkey.for				Routine to help usrinp.for
usrinp.for				User input routine

In the directory binary/utilities/mac_os_ppc one should have the files:

   Name                                         Description
dcd.for					Mac OS X/Absoft version
nel.for					Mac OS X/Absoft version
neld.for				Mac OS X/Absoft version
opencf.for				Mac OS X/Absoft version
save.for				Mac OS X/Absoft version
usrinp.for				Mac OS X/Absoft version

     The samples files, included in both binary_*_executables.tar.gz
and binary_unix_source.tar.gz, are:

   Name						Description
mucas_l_pri.dat				Astrometric data for Mu Cas from
					S. L. Lippincott, with parallax and
					proper motion removed
mucas_l_pri_ppm.dat			Astrometric data for Mu Cas from
					S. L. Lippincott, with parallax and
					proper motion included.
mucas_sec.dat				Position angle and separation data 
					for the secondary of Mu Cas from
					various sources.
mucas_vel_pri.dat			Radial velocity data for the primary
					of Mu Cas.
hr6469_sec.dat				Position angle and separation data
					for the secondary of HR6469.	
hr6469_vel_pri.dat			Radial velocity data for the primary
					of HR6469 combined from various 
					sources.
hr6469_vel_sec.dat			Radial velocity data for the
					secondary of HR6469 combined from 
					various sources.
47_UMa.dat				Radial velocity data for two planets
					orbiting 47 UMa, from Fischer et al.
sample_1d.dat				A sample file containing 1-D 
					interferometric data which can be run
					with one2two.exe
galaxy_profiles.dat			Surface brightness profiles of galaxies
					in Abell 1689 from CCD data.  This 
					is used in the sample program
					nl_demo_4.
mucas_l_pri.sve				Save file for a simple solution of
					Mu Cas.
ascii1.dat				Sample file for xyplot_ascii.exe demo
ascii2.dat				Sample file for xyplot_ascii.exe demo
ascii3.dat				Sample file for xyplot_ascii.exe demo
ascii4.dat				Sample file for xyplot_ascii.exe demo
ascii5.dat				Sample file for xyplot_ascii.exe demo

The sample files are by default placed in the binary directory.

The makefile will also create the object libraries, binary_u.olb,
plot/plot_u.olb, and utilities/utilities_u.olb which can
be used to link with user written programs if desired.

For whichever method you use to install the executable files, create the
aliases:
  alias a 'transparent_mode.exe'
  alias ax 'transparent_mode_x.exe'
  alias axn 'transparent_mode_xn.exe'
  alias plot 'plotcom.exe'
  alias xyplot 'xyplot_ascii.exe'

"a" will change from the Tektronix window to the text window in a graphics
terminal.
"ax" will change from the Tektronix window to the text window in xterm, and
erase the screen.
"axn" will change from the Tektronix window to the text window in xterm,
without erasing the screen.
"plot" will operate the plot command on the standard plot files (see below)
"xyplot" will produce an XY plot of columnar data from one or more ASCII files.

These definitions can be placed in a login file if desired.

Finally, edit display-plotting_availability.dat to match the display and
plotting devices availabile on your system.

     The plot device xgterm is a color xterm-like graphics terminal emulator
which runs on Unix.  Copies compiled for Linux with Intel processors for
kernels 2.2 and 2.4, and Mac OS 10.4, Tiger, can be downloaded from the web
page for this package.  The version of xgterm for Mac OS from iraf.net will
not work correctly.  While a plot can be sent to it, the Tek window never
receives focus, so no cursor readback is possible.  The version on the package
web page was prepared by Chip Coldwell, and will work correctly.


			Format of Data Files

     Star positions may be in the form of X and Y coordinates, or position 
angle and separation.  Each such row of data consists of the epoch, 
first coordinate, sigma of first coordinate, second coordinate, and 
sigma of second coordinate.  For X and Y, all points are assumed to 
have the same equator (see below);  for position angle and separation, 
all points should have an equator equal to the epoch.  The FORTRAN 
format for these data is:

  FORMAT(' ',F12.6,4X,F14.5,2X,F14.5,2X,F14.5,2X,F14.5)

where it is assumed that the file has the attribute CARRIAGECONTROL='FORTRAN'.
Data can conveniently be entered with the correct format by using the 
editbinary program.  In addition to rows of data, each file should have at
its beginning, several lines of header information.  A sample header for
a visual binary (secondary of Mu Cassiopeiae) is:

  Name=Mu Cassiopeiae
  Right Ascension=01 07 56.51
  Declination=+54 56 33.4
  Equator=2000.0000
  Type=Relative orbit
  Parallax and proper motion=Removed
  Scale=   1.0000"/Unit
  Initial Estimates:
  Period=22.09
  Time of periastron passage=1975.78
  Eccentricity=0.58
  Angle of line of nodes=47.4
  Inclination=-109.0
  Angle from node to periastron=324.8
  Semimajor axis in "=1.0
  Ratio of semimajor axes (total to primary)=5.6

     The header item "Name" can have up to 75 characters;  "Type" (explained 
more fully in the section "Running Binary") can be "Relative orbit" (as 
for speckle data) or "Relative orbit, Equator is constant" (for nonstandard
cases in which the equator is constant rather than equal to the epoch
of the observation) or "Absolute orbit" (as for astrometric data);  
"Parallax and proper motion" can be "Removed" or "Included";  "Scale", which
gives the physical value of the positional or velocity data per unit value
given in the columns in the file, can be a number followed by " "/Unit"
(for position data) or " km/sec/Unit" (for spectroscopic data).  The
optional header items "Initial Estimates:" and the elements of the orbit
with their associated values follow on the lines below the above header
items.  The "Angle from the node to periastron" is always taken to be that
that of the primary, even when only data for the secondary exists.
The header for a primary is similar to that of a secondary except that
the last optional header item, "Ratio of semimajor axes (total to primary)"
is replaced by the optional header item "Semimajor axis in "".  If the
file contains X and Y coordinates where parallax and/or proper motion
have not been removed, the following additional optional header items
can be included:

  Parallax=0.13
  X center=160.0
  X proper motion=3.4364
  X proper motion acceleration=0.0
  Y center=-77.0
  Y proper motion=-1.5787
  Y proper motion acceleration=0.0

     Following the header items is a required single header line
for the columns of data.  For X and Y coordinates it should be:

   Epoch                 X             Sigma_X            Y            Sigma_Y

For position angle and separation it should be:

   Epoch               Theta         Sigma_Theta         Rho          Sigma_Rho


     One-dimensional interferometric data are in the form of baseline angle
projected on the sky and projected separation.  Each such row of data consists
of the epoch, projected baseline angle, projected separation, and projecged
separation sigma.  The FORTRAN format for these data is:

  FORMAT(' ',F15.6,4X,F14.5,2X,F14.6,2X,F14.6)

The header item for the period is optionally used in one2two.exe.
Following the header items is a required single line for the columns of
data.  For 1-D interferometric data with the epoch as Julian Date it should
be:

    Epoch(JD)       Theta(interfer.)  Rho(projected)    Sigma_Rho

For 1-D interferometric data with the epoch in Besselian years, it should be:

    Epoch(BY)       Theta(interfer.)  Rho(projected)    Sigma_Rho


     For spectroscopic binaries each row of data consists of the epoch, 
radial velocity, and sigma of radial velocity.  The format for these data is:

  FORMAT(' ',F15.6,4X,F14.5,2X,F14.5)

A sample header for a spectoscopic binary (primary of Mu Cassiopeiae) is:

  Name=Mu Cassiopeiae
  Right Ascension=01 05  0.00
  Declination=+54 00  0.0
  Equator=2000.0000
  Type=Absolute orbit
  Scale=   1.0000 km/sec/Unit
  Period=22.09
  Time of periastron passage=1975.78
  Eccentricity=0.58
  Angle from node to periastron=324.8
  System radial velocity=-98.0
  Sine of inclination times semimajor axis in AU=-1.2

Note here that the header items "Angle of line of nodes", "Inclination",
"Semimajor axis in "", and "Ratio of semimajor axes (total to primary)"
present in the visual binary header have been replaced by the optional 
header items "System radial velocity" and "Sine of inclination times 
semimajor axis in AU".  If a pair of spectroscopic binaries is being 
considered then one of the two files can contain the optional item
"Ratio of semimajor axes (total to primary)".  If the star contains
spectroscopic subcomponents, additional header items such as:

   Period of secondary subcomponent #1=0.0061045
   Time of periastron passage of sec. subcomp. #1=1984.3781
   Eccentricity of sec. subcomp. #1=0.01
   Periastron angle of sec. subcomp. #1=0.0
   Sine(incl.) times a(AU) of sec. subcomp. #1=0.0463

are used.
     Following the header items is a required single header line
for the columns of data.  For spectroscopic data with the epoch as
Julian Date, it should be:

    Epoch(JD)           v(radial)         Sigma_v

For spectroscopic data with the epoch in Besselian years, it should be:

    Epoch(BY)           v(radial)         Sigma_v


The following definitions are used:

Visual Binary:
1)  The measured position angle is always measured positive in the
counterclockwise direction from north.
2)  The angle of nodes is measured counterclockwise from north to the first
encountered node;  it is thus always =< 180 deg.  Depending on the initial
values, the program may yield an angle of nodes >180 deg.  In that case you
should try an initial value 180 deg smaller, and also estimate a new value for
the "angle from the node to periastron".
3)  The angle from the node to periastron, w, is measured in the direction of
motion of the star from the node to periastron.  In this program it is always
taken to be that of the primary, even when only data for the secondary exists.
4)  The sign of the inclination doesn't matter, so one could reverse the
sign in the example files and still produce the same solution, except for the
sign change.
5)  The time units are Besselian years.
6)  The "Scale" in the header affects only the data under the header
line, i.e., the Initial Estimates are not scaled.

These definitions, except for w being always that of the primary, are
consistent with those mentioned in Aitken's "The Binary Stars".  

Spectroscopic Binary:
1)  Velocity is taken to be positive for receding objects.
2)  The node angle is not used.
3)  The angle from node to periastron is defined as in the visual binary
for consistency in combined solutions.  However, the usual definition,
as in Aitken, is that it is measured from the ascending node to
periastron.  At the ascending node the star is moving away from the
observer, and has the largest positive velocity.  For the case of only
a spectroscopic binary (no visual included) the usual definition of the
elements will also work.  One would then, if the node was not the ascending
one, add 180 to w, and change the sign of a*sin(i), and have the same
solution as before except for those changes.  Also, as defined for the
visual case, in the program the value of w is always taken to be that
of the primary.
4)  The sign of i is determined by spectroscopic data.  When the star is
at the node (as defined in the visual case), if the node is ascending,
i is > 0, and if the node is descending, i is < 0.  Again as in 3) one
could switch nodes, resulting in w increasing by 180, and then
change the sign of i.
5)  The time units are Julian Date (JD) or Besselian years, depending
on the header line for the columns of data.  Note however that the units
for the optional initial estimates of the period and the time of periastron
passage are in years.
6)  The "Scale" in the header affects only the data under the header
line, i.e., the Initial Estimates are not scaled.

Some other things to note are:

1)  Primary and secondary data will always be 180 degrees apart.
2)  The required keywords are allowed to have the following values:
  Keyword                    Value            When Required
Right Ascension=            hh mm ss.ss    Precessing with editbinary;
                                           Visual binary data with equator
                                           equal to epoch of observation
                                           (usual case)
Declination=                +dd mm ss.s    Same as for Right Ascension
                            -dd mm ss.s
Equator=                    yyyy.yyyy      Same as for Right Ascension
Type=                    Absolute orbit    Combined solution
                         Relative orbit    Same as above
                  Relative orbit, Equator  Same as above     
                              is constant
Parallax and proper motion= Included       Astrometric and visual
                            Removed        Same as above
Scale=                 xx.xxxx"/unit       All astrometric and visual cases
                       xx.xxxx km/sec/Unit All spectroscopic cases

In general, there should be no blank spaces to the right of the equal sign
in the header keywords.  The "Scale" keyword is an exception;  any number
of blank spaces may precede the value.  For the initial estimate values of
all the elements, only the first eleven positions to the right of the equal
sign are used.  Extra characters are ignored.  It is recommended that the
optional initial estimate values be included in the data files because that
way one can simply press the carriage return to take them as default starting
values when running the binary program.  Otherwise the starting values would
have to be typed in manually.  The simplest way to create the header is to use
the editbinary program to enter some data, or use one of the sample data files
as a template.

3)  Notes may be placed in the header as long as their beginning characters
do not reproduce a standard keyword.  A list of some optional header
keywords (used for initial estimates of the elements and other parameters)
can be found in binary_header.for.  The one other optional header keyword
is "Name".  The note "Initial Estimates" can safely precede the initial
estimate keywords.
4)  For astrometric data (Type=Absolute orbit), the equator for right
ascension and declination is assumed to also be the equator for
X and Y positions.  For visual and speckle data (Type=Relative orbit),
the equator is assumed to be the epoch of observation, except if the
keyword Type equals "Relative orbit, Equator is constant", in which case
each observation has an equator equal to that of the epoch of right
ascension and declination given in the header.
5)  For astrometric data, the proper motion acceleration reported by the
program is two times the "coefficient of the quadratic time factor".
6)  When creating artificial data with the program editbinary, it is not
possible to create a file where the positions are relative and parallax
and proper motion are included.
7)  The interpretation of the semimajor axis depends on the particular case.
For primary and secondary of a particular type (e.g. visual or spectroscopic)
solved together, "a" is that of the primary.  For a single orbit of a
particular type, "a" applies to that particular orbit.
8)  When data exists for two stars in a system, the wrong choice for which
is the primary and secondary will affect the solution's ratio of semimajor
axes.
9)  Data with a sigma of 9999.99999 are ignored by the program.
10)  For astrometric data, it is possible to adjust the solution by the
ratio of the photocentric to true semimajor axis.  This almost
invariably applies to the situation where primary data alone is
available.  It is difficult to think of a situation where the secondary
alone would be so adjusted.
11)  Some known limitations of the programs are:
  a)  One-dimensional interferometric data cannot be analyzed as of yet.
  b)  The errors of the velocity amplitudes of the subcomponents are
      not calculated as of yet.
  c)  When the parallax is not solved for but an optional value is in
      the header, the program will not use the value as a default for
      calculating the mass.
  d)  If both primary and secondary astrometric (XY) data are used, they
      should currently have the same XY zero point.
  e)  The program editbinary does not yet preserve the optional note
      "Initial Estimates" or any other user supplied notes.
  f)  For a visual binary with the equator equal to the epoch, and right
      ascension equal to 0, position angles greater than 180 will create
      unpredictable results.


			Running EDITBINARY

     The program editbinary.exe performs editing operations on binary star
data written in standard format, allows manual input of data, and manually
precesses position angle and separation.
     After launching the editbinary program, you will be presented with
the following menu:

     A  = Adds one or more numbers to the data (default)
     CI = Creates a file of one-dimensional interferometric data from user
          supplied elements
     CS = Creates a file of artificial spectroscopic binary data from user
          supplied elements
     CV = Creates a file of artificial visual binary data from user
          supplied elements
     EI = Allows manual entry of one-dimensional interferometric data to
          a new or existing file
     ES = Allows manual entry of spectroscopic binary data to a new or
          existing file
     EV = Allows manual entry of visual binary data to a new or existing
          file
     M  = Multiplies the data by one more more numbers
     P  = Precesses the coordinates of the data.
          Should only be used where all data points have the same equator.
     PM = Precesses the position angle and separation of manually input data
     Q  = Quits
     S  = Smooths the data by averaging (blank line delimiters
          must be inserted in file)
     WS = Converts weights to sigmas

The user input information should always be of the same case as what is 
shown in the menu, with the exception of logical answers for which 
TRUE, T, t, YES, y, J, and j are accepted in the affirmative and anything 
else is interpreted as false.
     Command "A" requires an existing file, and will add one or more
independent numerical values to an equivalent number of columns of data.
Since this is the default command, just press the Return to use it.
Execution of the command will prompt the user for the name of the file to 
be edited, and then display the header information of the file.  Next the 
user is prompted for the name of the output file.  This is followed by a 
menu giving a number of choices equal to the number of data columns in the 
file of that type, excluding the Epoch column.  For example, for a file 
with data representing position angle and separation (and the errors), the 
user is presented with the menu:

     P  = Edits the position angle
     PE = Edits the position angle error
     S  = Edits the separation
     SE = Edits the separation error

If the position angle needs to be increased by 2.5 degrees and the separation
error by 0.03 arc seconds, enter "P SE" (without the double quotes) and 
press the Return.  Then when the program asks for the numbers, enter
"2.5 0.03" and press the Return.  The new file is written to disk and the
program stops.
     Command "CI" will create a file of one-dimensional interferometric data
from user supplied elements.  When this command is chosen, the program will
prompt the user for a file name, the name of the star, the star's coordinates,
year of equinox, altitude, azimuth, longitude, and latitude of the 
interferometer, and the orbital elements and other information pertaining
to the star.  After entering the beginning and ending epochs in either
Besellian years or Julian date, the program generates the data and asks
if you wish to add noise to the data.  Up to 10000 data points can be created.
     Command "CS" will create a file of artificial spectroscopic binary 
data from user supplied elements.  When this command is chosen, the program 
will prompt the user for a file name, whether the star is the primary
or secondary, the name and orbital elements of the star, and other 
information for the file header.  There is also an opportunity to
add reflex velocities for up to five subcomponents to the star system, and
additionally save the subcomponent velocities in files as well.  The program
then generates the data and optionally adds user defined noise to the data.
Up to 10000 data points can be created.
     Command "CV" will create a file of artificial visual binary data 
from user supplied elements.  When this command is chosen, the program 
will prompt the user for a file name, the format of the data (X and Y
coordinates, or position angle and separation), whether the 
star is the primary or secondary, the name and orbital elements of the 
star, and other information for the file header.  The user is also asked
whether the equator should be taken to be the epoch of the observation.  
In general for astrometric data (X and Y), the equator for the data is
assumed to be that of equator given in the header.  For visual and 
speckle data (position angle and separation), the equator for the data 
is assumed to be the epoch of the observation.  The program
then generates the data and optionally adds user defined noise to the data.
Up to 10000 data points can be created.
     Command "EI" allows one to manually enter 1-dimensional interferometric
data into a new or existing file.  Upon choosing this command, the program
first prompts for a file name, and if the file is a new one, it additionally
prompts for the name and coordinates of the star, the equinox date, the scale,
and whether the epoch is in Besselian years or Julian days.  You can then
enter the epoch, angle of the baseline projected on the sky, projected
separation, and separation mean error.  For an old file the existing header
is displayed and the user enters data in the same format as what is present
in the file and these data are appended to the file.
     Command "ES" allows one to manually enter spectroscopic binary data into
a new or existing file.  Upon choosing this command, the program first prompts
for a file name, and if the file is a new one, it additionally prompts for the 
name and coordinates of the star, the equinox date, the scale, and whether 
the epoch is in Besselian years or Julian days.  Then the user enters the 
epoch, velocity, and mean error of the velocity for each point.  For an old 
file the existing header is displayed and the user enters data in the same
format as what is present in the file and these data are appended to the 
file.
     Command "EV" allows one to manually enter visual binary data to a new 
or existing file.  Upon choosing this command, the program first prompts for
a file name, and if the file is a new one, it additionally prompts for the 
name and coordinates of the star, the equinox date, the scale, whether 
the type of orbit is absolute or relative, and whether the type of file
is X and Y positions or position angle and separation.  If the orbit is 
absolute, the user is further prompted for whether parallax and proper 
motion have been removed.  For a relative orbit, parallax and proper motion 
are always assumed to have been removed.  Then the user enters the epoch, 
the coordinates and their mean errors.  For an old file the existing 
header is first displayed and the user then enters data in the same format 
as what is present in the file.
     Command "M" requires an existing file, and will multiply one or more 
independent numerical values to an equivalent number of columns of data.  
Since this is the default command, just press the Return to use it.  
Execution of the command will prompt the user for the name of the file to 
be edited, and then display the header information of the file.  Next the 
user is prompted for the name of the output file.  This is followed by a 
menu giving a number of choices equal to the number of data columns in the
file of that type, excluding the Epoch column.  For example, for a file 
with data representing position angle and separation (and the errors), 
the user is presented with the menu:

     P  = Edits the position angle
     PE = Edits the position angle error
     S  = Edits the separation
     SE = Edits the separation error

If the separation needs to be increased by a factor of 1.5 and the 
separation error by a factor of 1.6, enter "S SE" (without the double 
quotes) and press the Return.  Then when the program asks for the numbers, 
enter "1.5 1.6" and press the Return.  The new file is written to disk and
the program stops.  
     Command "P" precesses the coordinates of both the position in the header
and the data.  If the file contains velocity data, then only the position
in the header is precessed.  It usually only makes sense to use this command
on data where all the data points have the same equator, which is the 
expected situation for X and Y position data.  The results will not be
meaningful if the equator is equal to the epoch of each observation.
Execution of the command will prompt the user for the name of the file to 
be edited, following which the header information of the file will be 
displayed.  Next the user is prompted for the name of the output file.  
This is followed by a prompt for the initial equator (or equinox) where 
the default is the equator in the file.  After the new equator is entered, 
the program converts the data.
     Command "PM" precesses the position angle and separation of maually
input data.  Execution of the command will prompt the user for the initial 
equinox, the right ascension and declination of the primary, the position
angle and separation, and the final equinox.  The program then precesses
the coordinates and prints out the results on the terminal.  Note that
only the position angle will change in this operation.
     Command "Q" causes the program to stop.
     Command "S" smooths the data by averaging selected groups of data
points.  This command is useful if many points exist for a given range of
epoch which is small compared to the system period, or for astrometric data
containing parallax, small compared to a year.  Each group to be averaged
is defined by inserting a blank line delimiter in the file following the
last line of data in that group. Note then that the first line of the data
should not be a blank line, but the last line should.  Each new datum 
represents a weighted average of the input points except for the epoch which
is a simple average, and the mean errors where the new data are computed 
as the inverse square root of a simple average of the weights and further
reduced by dividing by the square root of the number of points.  Execution
of the command simply prompts the user for the name of the input file and
the output file.
     Command "WS" converts a data file containing weights to one containing
mean errors (sigmas).  This is useful if the original data was only
available in the form of weights.  The program first prompts for the name
of the input file and the output file, and then asks for the sigmas that
correspond to weights of zero for the various columns.  For example, if the
file contains X and Y coordinates, one should enter the sigmas for X and 
Y for a weight of 1;  or if the file contains velocity coordinates, one
should enter the sigma for velocity for a weight of 1.


			Running BINARY

     The program BINARY uses the nonlinear least squares subroutine 
NONLINFIT to solve for the orbital elements and other parameters such as
parallax, proper motion, systemic radial velocity, mass ratio, and their
errors, of a multiple star system by simultaneously considering weighted 
astrometric, relative positional, and radial velocity data.  Both the 
primary and secondary are allowed to have spectroscopic subcomponents,
present as included reflex velocities and files of subcomponent velocities.
Up to 5 subcomponents in each can be simultaneously be solved for along
with the astrometric and separation data.  Therefore up to 12 stars could
be considered in a restricted manner.  The program can automatically take
account of the light travel time across the orbit for spectroscopic binaries.
Because the weights from the various input sources can be interactively
scaled during program execution, it is possible to find a solution in which
the reduced chi squared of each data variable is matched to unity, and
which, in the absence of systematic errors, will thus yield an optimal
solution.  Systematic effects can be searched for by restricting the
solution to various subsets of the data and checking for differences in
the solution parameters inconsistent with their mean errors.  The residuals
of the visual solution can be written to a standard binary star file for
further analysis, such as searching for a visual subcomponent.
     The program accepts files in the format described above for editbinary,
and writes the results to a log file with the name fort.7.
For astrometric data, i.e., data of TYPE=Absolute, the equator for right
ascension and declination is assumed to also be the equator for x and y
positions.  For visual and speckle data, i.e., data of TYPE=Relative, the
equator is assumed to be the epoch of observation, though an exception can
be made by setting the keyword TYPE equal to "Relative, Equator is constant".
The data files can optionally include initial estimates of the elements,
which the program can then use to start the solution.  When the primary and
secondary of a particular type (visual or spectroscopic) are solved together,
"a" is that of the primary.  For a single orbit of a particular type,
"a" applies to that particular orbit.
     The program can also be used to solve for the elements describing
a single or binary star with orbiting planets, when the planets impose
reflex velocities on the parent star.  For a single star with planets,
there are four possibilities:  1) if there is just one planet, the
planet could be treated as the secondary star;  2) if there is just one
planet, the planet could be treated as a subcomponent of the primary;
3) if there are two or more planets, one planet could be treated as the
secondary star and the others as subcomponents of the primary;  4) if 
there are two or more planets, the planets could all be treated as 
subcomponents of the primary.  In cases 2) and 4) the program must work
with a secondary star that doesn't actually exist.  However if the period
is forced to be very long, say 10^37 years, and all the elements of the
main orbit are held constant in the solution, then the orbits of the
planets can easily be solved for.  In this case the velocity of the
primary becomes insignificant compared to the reflex velocities of the
planets.  The initial estimates of the ficticious main binary pair could
be included in the header of the data file, before holding them fixed
in the solution, or more conveniently, only the period with a key value
of 9999.99999 can be included in the header.  When the program reads this
key value, 1) the period is set to 10^37 years, 2) the other main pair
elements are given appropriate values, 3) the main pair elements are
automatically held constant in the solution, and inappropriate plots
are suppressed.  When considering solutions with planets, it is best to
use a value of Scale so that the units of velocity in the columns in the
data file are in m/s, i.e., Scale=0.001.  For a binary star, as opposed
to a single star, with planets, all the planets must be considered as
subcomponents of the primary and/or secondary.
     Under Unix and OpenVMS VAX, it is possible to plot the results on 
any of the plot devices supported in the MIIPS plot package, e.g.,
VT100 with Retrographics, Versaterm, xterm, Apple LaserWriter, and
"Enhanced SAOimage, or write the plot to a file.  Under Unix, there is
one additional supported device, xgterm (a color xterm with enhancements
such as data level).
     After launching the binary program, you will be presented with the
following menu:

  Enter a choice for the positional information:
              P = Positional data exists for primary
              S = Positional data exists for secondary or for
                  relative orbit (default)
              B = Positional data exists for both stars
              N = No positional information available

After making a choice, the following menu is displayed:

  Enter a choice for the radial velocity information:
              P = Velocity data exists for primary (default)
              S = Velocity data exists for secondary
              B = Velocity data exists for both stars
              N = No velocity information available

Assuming that a choice involving a file containing positional data was
made, the following is displayed:

  Some files of positional data that are available are:
    mucas_l_pri.dat      Lippincott;  Parallax and proper
                         motion removed
    mucas_l_pri_ppm.dat  Lippincott;  Parallax and proper
                         motion not removed
    mucas_sec.dat        Various separations of pair
    hr6469_sec.dat       Scarfe et al;  separations of secondary

This is followed by:

  Open the primary star's file for positions
  Enter the file name:  (default = last entry)
  FILE_21=

and/or

  Open the secondary star's file for positions
  Enter the file name:  (default = last entry)
  FILE_22=

On the other hand, assuming that a choice involving a file containing 
spectroscopic data was made, the following is displayed:
       
  Some files of spectroscopic data that are available are:
    mucas_vel_pri.dat    Radial velocities of primary
    hr6469_vel_pri.dat   Scarfe et al;  velocities of primary
    hr6469_vel_sec.dat   Scarfe et al;  velocities of secondary and one
                         subcomponent
    47_UMa.dat           Fischer et al;  two planets orbiting a single star

This is followed by:

  Open the primary star's file for velocities
  Enter the file name:  (default = last entry)
  FILE_23=

and/or

  Open the secondary star's file for velocities
  Enter the file name:  (default = last entry)
  FILE_24=

The header information of each file will be displayed after it is opened.
If the header does not have an estimate for the rate of change of the
angle from node to periastron, then you are prompted to solve for apsidal
motion with:

  Do you wish to solve for apsidal motion?  (default = N)
  SOLVE_FOR_APSIDAL_MOTION=

If your answer is in the affirmative, then you are presented with:

  Enter an initial estimate for the apsidal motion in degrees per year:
  (default = 0.0)
  APSIDAL_MOTION=

If the file of positional data has not had parallax removed you will be
prompted with:

  Enter the ratio of the observed to true parallax:  (default = 1)
  OBSERVED_TO_TRUE_PARALLAX=

If the reference background stars are not infinitely far away, then this
ratio will be less than one.

                               *****

For the following steps, we will assume that we are only using a file of
astrometric positions of the primary of a bimary system where parallax and
proper motion have not been removed.  For the file mucas_l_pri_ppm.dat, use 
a value of 0.984 for the ratio of observed to true parallax.  Next you are
prompted with:

  Enter the ratio of the photocentric to true semimajor axis:  (default = 1)
  RATIO_PHOTOCENTRIC_TO_TRUE_SEMIMAJOR_AXIS=

Since the secondary of Mu Cas is about 100 times fainter that the primary,
use a ratio of 0.99 here.  Following this, you are prompted to optionally
scale the weights with:

  The average weight for the visual primary is  3687.3164
  and the average sigma is 0.16468149E-01
  Do you wish to scale the XY weights of the positions of the primary?
  (default = N)
  SCALE_WEIGHTS_PRIMARY_POSITION=

If your answer is in the affirmative, then you are presented with the
following prompt:

  Enter the factors to multiply the weights (in X and Y) by:
  (defaults = 1.0 1.0)
  WEIGHT_SCALE_PRIMARY_POSITION=

For the mucas_l_pri_ppm.dat data set, try scaling factors of 1.17 and 0.95.
For a file containing position angle and separation the prompt is similar,
but the prompt and operation refer to Theta and Rho instead.  Next, the
program lists the initial estimates for the orbital parameters, based on
the values in the data file header.  For mucas_l_pri_ppm.dat, you will see:

  Initial estimates are:
  Period=                                           22.09000000
  Time of periastron passage=                       1975.780000
  Eccentricity=                                    0.5800000000
  Angle of line of nodes=                           47.40000000
  Inclination=                                     -109.0000000
  Angle from node to periastron=                    324.8000000
  Semimajor axis in "=                             0.1900000000
  Parallax=                                        0.1300000000
  X center=                                         160.0000000
  X proper motion=                                  3.436400000
  X proper motion acceleration=                    0.0000000000E+00
  Y center=                                        -77.00000000
  Y proper motion=                                 -1.578700000
  Y proper motion acceleration=                    0.0000000000E+00
  Enter the initial estimates of the parameters:  (default = above)
  PARAMETERS=

This is followed by the prompt:

  Enter the indexes of the parameters which are to be held constant:
  (starting index = 1):  (default = none)  
  NUMBERS_CONSTANT=

The program will hold some parameters constant in the nonlinear least
squares solution, if desired.  The parameters are referenced by their
position in the list, starting at an index of one.  Try solving for
all the parameters.  Next, you should pick an iteration scheme according
to the following prompt:

  Select the iteration scheme:
       M = Manual
       A = Automatic selection of fractional increment with
           maximum searching (default)
       B = Automatic selection of fractional increment with
           minimum searching
       C = Automatic selection of fractional increment with
           no searching

The fractional increment is the fraction applied to the difference 
between the solution for the parameters at any given iteration and 
the starting parameters for that particular iteration.  The product
of the fractional increment and the above difference is added to the 
starting parameter values to yield the starting value for the next
iteration.  In the manual scheme, the user selects the increment, with
the default being 2/3 times the value of the previous fractional increment.
The user selects the values of the parameters for the next iteration with
the default being the values associated with the smallest average reduced
chi squared so far.  For iteration scheme A, the fractional increment is 
decreased by a factor of 2/3 if the average reduced chi squared for a 
particular iteration is greater than that of the previous iteration.  The
parameters for the next iteration are a weighted average of the parameters
associated with the smallest average reduced chi squared, and the vaules
for the most recent iteration, such that the most recent values are given
full weight if the fractional increment is one.  For iteration scheme B,
the fractional increment is decreased by a factor of 2/3 if the average 
reduced chi squared is greater than that of the previous iteration.  If 
this is the case, the parameters for the next iteration are set to the 
values associated with the best average reduced chi squared;  otherwise,
the most recently solved for values are used.  For iteration scheme C, 
the fractional increment is decreased by a factor of 2/3 if the 
average reduced chi squared is greater than the smallest value attained 
so far.  If this is the case, the parameters are set to the values 
associated with the best average reduced chi squared;  otherwise,
the most recent values are used.  Generally, scheme A can be used, but
noisy data or data covering only a small fraction of the orbit may require 
schemes B, C, or even M.
     Next, the program prompts for the tolerance to use in the iterations.

  Enter the tolerance for continuing the iteration:  (default = 0.0001)
  TOLERANCE=

The iterations are stoped when all the differences of the parameters
between the last two iterations are less than the tolerance times the
sum of a parameter and its sigma.
     The program then asks:

  Do you want to display the intermediate results?  (default = N)
  INTERMEDIATE=

It is useful to display intermediate results when first learning to use
the program, or if the solution is having difficulty converging.
     Next, the following is displayed:

  Enter the initial fractional increment:  (default = 1.0)
  FRACTIONAL_INCREMENT=

The initial fractional increment should be 1.0 unless the data are noisy.
A larger fractional increment allows the solution to reach a final answer
more quickly.
     The program now proceeds to solve for the parameters.  If intermediate
values are displayed, a great deal of data will scroll by.  Finally, you
may see a result such as:

      The Elements of the Orbit and Other Parameters
 The X and Y centers are for the epoch 2000.0000
 Period (years)=                                 21.42166196     +-0.5139849E-01
 Time of periastron passage=                     1975.752370     +-0.7409161E-01
 Eccentricity=                                  0.6137959281     +-0.1635130E-01
 Angle of line of nodes=                         47.26919817     +-0.7311127    
 Inclination=                                   -109.3820312     +-0.6913799    
 Angle from node to periastron=                  335.4451068     +- 1.798846    
 Semimajor axis in "=                           0.1888111610     +-0.2199145E-02
 Parallax=                                      0.1322431225     +-0.1654591E-02
 X center=                                       159.8349840     +-0.1515355E-01
 X proper motion=                                3.425092696     +-0.7990980E-03
 X proper motion acceleration=                  0.2534413026E-04 +-0.2053813E-04
 Y center=                                      -76.97342785     +-0.1568761E-01
 Y proper motion=                               -1.587810408     +-0.8877183E-03
 Y proper motion acceleration=                  -.6267044299E-04 +-0.2282285E-04
  
         Additional Information
 The semimajor axis in " is assigned to the primary orbit
 The photocentric semimajor axis in " =0.1869230494     +-0.2177153E-02
 The period in days is  7824.090097     +- 18.77288    
 The reduced chi squared is
      1.0029633     for data dimension  1
      1.0024898     for data dimension  2
 The average reduced chi squared =      1.0027265    
 The mean error for a point of average weight is
     0.15182605E-01 +-    0.744388E-03 for data dimension  1
     0.16828645E-01 +-    0.825092E-03 for data dimension  2
 The total number of points used in the solution =   215
  Press the <CR> to see the covariance:
  <CR>=

Next the program prompts with:

  Do you wish to redo the solution, eliminating points which deviate
  more than a given factor times the mean error?  (default = N)
  REDO_SOLUTION=

If both the primary and secondary are solved for, an additional parameter,
the ratio of semimajor axes (total to primary) will be present, and the 
reduced chi squared and mean error will occupy data dimensions 3 and 4,
as well as 1 and 2.

Next you will be prompted for whether to plot the data and the solution.
Plots with or without the parallax and proper motion included, and with
or without residual vectors can be made.

  Do you wish to plot the function and the data?  (default = Y)
  PLOT=

If the answer is in the affirmative, there appears:

  Do you wish to plot the residual vectors for the visual data?  (default =Y)
  PLOT=

Then one is prompted for the plot device.  Depending on the state of the
file display-plotting_availability.dat, one might be presented with

  Enter the plot devices:
       S   = SAOimage (Enhanced version)
      -S   = SAOimage, no erasure of screen
       G   = Graphics terminal (VT100/Retrographics and Visual 550)
       G4  = Graphics terminal emulator (Versaterm)
       X   = Xterm (default)
       XG  = Xgterm
       F   = File

The standard MIIPS plot package commands apply after the plot is
displayed (see list below).

                                *****

     If instead of positional data, only radial velocity data are used, one
might proceed as follows.  Enter N for the choice for 2-D positional data,
and enter B for the choice for spectroscopic information.  Let us assume that
the files hr6469_vel_pri.dat and hr6469_vel_sec.dat are used for the primary
and secondary, respectively.  After the primary file is opened, the program
will display the header information and then ask 

  Enter the number of primary subcomponents to solve for:  (default = 0)
  NUBER_OF_SUBCOMPONENTS=

Because the primary has no subcomponents (the file header also does not 
include any subcomponent elements), simply take the default by pressing
the <CR>.  After the secondary file is opened, the program will ask

  Enter the number of secondary subcomponents to solve for:  (default = 0)
  NUBER_OF_SUBCOMPONENTS=

In this case enter 1, whereupon the program will ask

  Enter the secondary subcomponents for which independent files exist;
  enter 0 for none:  (default = 0)
  SECONDARY_SUBCOMPONENT_SECONDARIES=

For this secondary, the subcomponent data are only contained in the same
file as the secondary itself, so take the default.  Since there are no
initial estimates for apsidal motion of the main components in the files,
the program will next ask

  Do you wish to solve for apsidal motion for the main components?
  (default = N)
  SOLVE_FOR_APSIDAL_MOTION=

Take the default.  Similarly, there is no estimate for apsidal motion
of the secondary subcomponent in the secondary file, so the program will
ask

  Do you wish to solve for apsidal motion for secondary subcomponent #1?
  (default = N)
  SOLVE_FOR_APSIDAL_MOTION_SUB=

Take the default.  The program next asks about excluding data points
based on phase.  This can be useful if line blending is suspected.  The
program asks

  Do you wish to exclude data points from the primary spectroscopic
  file based on phase?  This is not recommended if there are
  subcomponents.  The file's initial estimates will be used
  to calculate phase.  (default = N)
  EXCLUDE_BY_PHASE_PRI=

Although we will take the default here, if an affirmative answer
was given, the program would ask

  Enter pairs of lower and upper phase limits which will serve to exclude
  any data points which are so enclosed.  All limits must be greater
  than zero, but the upper limit of a pair may for convenience be
  greater than 1.  A maximum of three pairs can be specified.
  EXCLUDED_PHASES_PRI=

In which case one might enter "0.95 1.05".  The same question is
asked of the main secondary component, and after declining that
request also, the program will inquire about scaling the weights of
the primary and of the secondary.

  The average weight for the spectroscopic primary is  1.0000000
  and the average sigma is  1.0000000
  Do you wish to scale the weights of the velocities of the primary?
  (default = N)
  SCALE_WEIGHTS_PRIMARY_VELOCITY=

Answer no for this and a for similar question about the secondary.
Scaling the weights at run time is a useful feature for ensuring
that the reduced chi squared is close to unity.  For a single file
the reduced chi squared value can tell a researcher whether the
mean error from the solution is realistic vis a vis the sigmas
of the errors in the file.  If several files are being used, the
reduced chi squares of each data set should match so that no data
set is undully biased high or low.

Next you are prompted with

  Do you wish to correct for the light travel time across the orbit(s)?
  (default = Y)
  CORRECT_FOR_TRAVEL_TIME=

After taking the default, the following appears

  The inclination angle for the main pair cannot be solved for.
  Enter a working value for the calculation:  (default = 90 degrees)
  WORKING_INCLINATION=

If visual data were being solved for along with the spectroscopic data,
the inclination angle could be solved for, and there would be no need to
assume an angle.  Take the default.  A similar prompt then appears for the
secondary subcomponent

  The inclination angle(s) for the secondary subcomponents cannot be
  solved for.  Enter a working value:  (default = 90 degrees)
  WORKING_INCLINATION_SECONDARY_SUBCOMPONENT(S)=

Again, take the default.  Now the program is ready to start on the solution.
The initial estimates taken from the header data are displayed as follows:

  Initial estimates are:
  Period=                                           5.526500000
  Time of periastron passage=                       1986.361500
  Eccentricity=                                    0.6760000000
  Angle from node to periastron=                    220.4500000
  Ratio of semimajor axes (total to primary)=      0.0000000000E+00
  System radial velocity=                          -3.360000000
  Sine of inclination times semimajor axis in AU=   2.214500000
  Period of secondary subcomponent #1=             0.6104500000E-02
  Time of periastron passage of sec. subcomp. #1=   1984.378100
  Eccentricity of sec. subcomp. #1=                0.1000000000E-01
  Periastron angle of sec. subcomp. #1=            0.0000000000E+00
  Sine(incl.) times a(AU) of sec. subcomp. #1=     0.4630000000E-01
  Enter the initial estimates of the parameters:  (default = above)
  PARAMETERS=

You may notice a problem here;  the initial estimate for the "Ratio of
semimajor axes (total to primary)" is zero!  That is because no such
estimate was contained in either spectroscopic  file.  If we were attempting
a combined solution with both the positional data and spectroscopic data for
hr6469, i.e. files hr6469_sec.dat, hr6469_vel_pri.dat, and hr6469_vel_sec.dat,
then the initial estimate of that ratio would been obtained from the file of
positions.  We now have three choices:  1) start over and enter an initial
estimate of 2.0 in one of the two files, 2) enter all 12 estimates at the
terminal, 3) take the dafault and thereby take our chances with an 
inappropriate estimate.  Try taking the default for now.

After taking the default, the following appears:

  Enter the indexes of the parameters which are to be held constant:
  (starting index = 1):  (default = none)
  NUMBERS_CONSTANT=

Because the secondary subcomponent in this case is in an almost circular
orbit one cannot easily solve for its periastron angle.  Enter 11, the
periastron angle's index.  For the iteration scheme, enter B (minimum
searching for a solution).  Take the defaults for the tolerance and the
fractional increment, but don't display the intermediate values.  After
a while, the following appears:

     The Elements of the Orbit and Other Parameters
Period (years)=                                 5.522565784     +-0.2582205E-02
Time of periastron passage=                     1986.370545     +-0.3548141E-02
Eccentricity=                                  0.6830986973     +-0.3553659E-02
Angle from node to periastron=                  222.3247962     +-0.4256903
Ratio of semimajor axes (total to primary)=     1.710054721     +-0.7931953E-02
System radial velocity=                        -3.536043856     +-0.6238363E-01
Sine of inclination times semimajor axis in AU= 2.468962147     +-0.1693713E-01
Period of secondary subcomponent #1=           0.6104536485E-02 +-0.1879234E-08
Time of periastron passage of sec. subcomp. #1= 1984.379474     +-0.1288391E-05
Eccentricity of sec. subcomp. #1=              -.2907456313E-02 +-0.1286802E-02
Periastron angle of sec. subcomp. #1=          0.0000000000E+00 +-0.0000000E+00
Sine(incl.) times a(AU) of sec. subcomp. #1=   0.1915545621E-01 +-0.2208202E-04

        Additional Information
The projected semimajor axis in AU is assigned to the primary orbit
The period in days is  2017.074070     +-0.9431303
The time of periastron passage is    2446566.48119 +-       1.29593 JD
The projected vel. amp. of the primary is  18.229761     +-0.11173     km/sec
The projected vel. amp. of the secondary is  12.945328     +-0.11764     km/sec
The projected velocity amp. of sec. subcomp. #1 is  93.466448     km/sec
The reduced chi squared is
    0.00000000E+00 for data dimension  1
    0.00000000E+00 for data dimension  2
    0.00000000E+00 for data dimension  3
    0.00000000E+00 for data dimension  4
    0.73631956     for data dimension  5
     9.2246191     for data dimension  6
The average reduced chi squared =      4.5151713
The mean error for a point of average weight is
    0.00000000E+00 +-    0.000000E+00 for data dimension  1
    0.00000000E+00 +-    0.000000E+00 for data dimension  2
    0.00000000E+00 +-    0.000000E+00 for data dimension  3
    0.00000000E+00 +-    0.000000E+00 for data dimension  4
    0.85809065     +-    0.397503E-01 for data dimension  5
     3.0372058     +-    0.157472     for data dimension  6
The total number of points used in the solution =   429
Predicted times of eclipses assuming inclination = 90 degrees and no light
travel time correction
     Primary in front:       1986.481469 BY,      2446606.9956 JD
     Primary in back:       1985.606106 BY,      2446287.2759 JD
Press the <CR> to see the covariance:
<CR>=

Notice that the eccentricity of the secondary subcomponent came out 
negative.  Therefore a better approach would be to set this parameter
equal to 0 and hold its value constant in the solution (parameter number
10).  Also note that the reduced chi squared for the secondary data
is greater than 9.  Therefore the estimated sigma in the file is too
small.  One could either adjust this value with editbinary, or scale
the weights at the time of the solution in BINARY.  For the case of a
spectroscopic binary and no visual binary data, the program prints epochs
of possible eclipses assuming that the unknown inclination is 90 degrees,
and not including any correction for light travel time.
     If we had chosen iteration scheme C (no searching), the reduced chi
squared for the secondary data would have been much worse, over 500.  
That is because allowing the program to search over parameter space will
naturally give a better fit.  However if the data are noisy, one may need
to limit the searching in order to guarantee convergence.
     After the covariance is displayed, the program prompts with:

  Do you wish to redo the solution, eliminating points which deviate
  more than a given factor times the mean error?  (default = N)
  REDO_SOLUTION=

If the default is taken, one is asked:

  Do you wish to plot the function and the data?  (default = Y)
  PLOT=

     The program will plot the data as
1) the spectroscopic data over all time for both primary and secondary,
2) the spectroscopic data over all time without subcomponent reflex
velocities for both primary and secondary,
3) the spectroscopic data combined into one cycle without subcomponent
reflex velocities, for both primary and secondary, and
4) the spectroscopic reflex velocity data combined into one cycle for
secondary subcomponent #1
     Finaly, the residuals can be displayed, and the sum of the masses
will be calculated.  If visual data for the secondary (file hr6469_sec.dat)
is included with the spectroscopic data in a combined simultaneous
solution for this star, the program:
1) will not prompt for a working value for the inclination
2) will solve for the inclination
3) will solve for the parallax
4) will in addition plot the visual data
5) will in addition display the visual residuals and optionally write
them to a file
6) will prompt for the parallax, using the value from the solution as a
default
7) will calculate the masses and their errors.

     A combined solution for HR6469 can be obtained by using files
hr6469_sec.dat, hr6469_vel_pri.dat, and hr6469_vel_sec.dat.  This will give
somewhat reduced uncertainties for the elements.  
     A combined solution can also be obtained for Mu Cas, by opening the
files mucas_l_pri_ppm.dat, mucas_sec.dat, and mucas_vel_pri.dat, and
letting the program solve for the elements.  Because the first of these
files is positional data for the primary, and the third file is
spectroscopic data for the primary, the parallax of the system is
considered to be an unknown, and is solved for.  However the first file
by itself is astrometric data containing proper motion and parallax
information, thus the parallax could be obtained just from one file.
With the first and third files combined, the program automatically uses
all the information to solve for the parallax.  With the second file
(speckle data for the relative orbit) included, the program has enough
information to solve for the semimajor axes of both stars and hence both
their masses.

     The data file 47_UMa.dat contains reflex velocity data obtained by
Fischer et al for two planets orbiting the star 47 Ursa Majoris.  Because
the star is single rather than binary, a fictious main pair must be used
in the solution.  The file already has the period of this fictious pair
set equal to the key value of 9999.9999, which in the program has the 
effect of setting the main period equal to 10^37 years, setting the
other main elements to appropriate values, automatically holding the 
main elements constant in the solution, and suppressing inappropriate
plots.  The user is free to hold additional elements for the two
subcomponents constant.  For example, Fischer et al held the eccentricity
of the second planet constant in their analysis.  This is referenced as
the element with index 14 in the program.

     For binary data where there is little or no prior information on
the values of the orbital elements which could serve as starting values, 
one can proceed as follows:  First plot Y against X, Theta or Rho against
against Epoch, or Velocity against epoch with the plotting program 
xyplot_ascii.exe.  This will likely yield some hints as to the values
of P, T, a, or e.  Next use these values as starting values in the 
program.  At the beginning it is best to hold their values constant in 
the solution and solve for the remaining elements, while guessing at 
their starting values.  If the solution converges, the reduced chi
squared and the output plot will tell you whether your choices were
realistic.  The choice of iteration scheme and fractional increment are
imortant at this stage.  Initially, using scheme M with a fractional 
increment of about 0.1 will give more control of the process and assure
that the program doesn't go into an infinite loop.  Elements that give
small errors can be set constant and the program rerun with the iteration 
scheme advanced to C, and the fractional increment increased.  It may 
require some time to zero in on the best starting values, but eventually
with good data covering a large fraction of the orbit, iteraction scheme
A and a fractional increment of 1 can be used.  If the data cover only
a small portion of the orbit, it may be that some elements must always
be held constant to obtain convergence.
 

                    Running BINARY from a "Save" File

Every time BINARY is run, a file with the name binary.sve, containing
the keywords associated with the user prompts, and their corresponding
paramater values, is written to disk.  This file is different than the
log file, and is known as a save file.  By simply entering

  binary.exe my_file.sve

where my_file.sve is a save file, the binary program will automatically
be rerun with the same parameter values.  The save file can have any name
but if there is an extension, the full name must be used.  This operation 
is made more useful by including keywords and new parmeter values on the 
same line.  For example if you wanted to rerun the program but hold the 
period constant and show the residuals, you would enter

  binary.exe "my_file(NUMBERS_CONSTANT=1 SHOW_RESIDUALS=Y)"

In order to not hold any elements constant, NUMBERS_CONSTANT should be set
to zero.  Note that the keywords must always be upper case, and any character
data, such as those entered in the plotting software, should be of the same
case.  If keywords and parameter values are entered on the command line along
with the save file name as shown above, the entire string following the 
program name must be enclosed in double quotes (this is a Unix restriction).
Bear in mind that the key presses used in the interactive plotting,
and the mouse positions, are not recorded.  Only data preceded by an
upper case keyword is recorded.  
     For some combinations of data it is possible to calculate the mass of
the stars.  In that case the user is prompted for the parallax, with a default
equal to the value from the solution.  If the program is rerun with a save
file, the value of parallax in the save file will be used rather than the
value obtained from the new solution.  To avoid this, simply edit the save
file and delete the line with the old default value of parallax.  The program
will then stop at that point and prompt the user for a value, with a default
equal to the parallax from the new solution.
     An example save file, mucas_l_pri.sve, is included in the binary package.
This example will use only the file of positional data for the primary of
Muc Cas, with no proper motion included, solve for the elements, and do no
plotting.  


                            Running one2two

     one2two.exe will fit a cosine function to the projected separation of a
binary star as a function of baseline angle projected on the sky.  Such
one-dimensional information is obtained from a pair of telescopes operating
as an interferometer.  If the data cover a large enough span in projected
baseline angle, and the range in epoch is small compared to the binary's
period, the program will compute the true separation and position angle and
their errors.  This single two-dimensional data point can be used in the
program binary.exe along with other data to solve for the orbit of a binary
star.
    After launching the one2two program the user is asked to open a file
of one-dimensional interferometric data.  Such a file can be created from
editbinary with commands CI or EI.  The one-dimensional sample data file
sample_1d.dat is included in the package distribution for testing purposes.
After opening the file, the program displays the header information, the
ratio of the time span of the observations to the period from the header,
the weighted average of the epoch, and initial estimates of rho and theta.
The user is next prompted to enter initial estimates for the nonlinear
least squares solution.  The previously displayed initial estimates are used
as defaults.  Next one should answer prompts about which parameters to hold
constant, the iteration scheme, the tolerance for continuing the iteration,
whether to display intermediate results, and the initial fractional increment.
     The program will output the separation and position angle and their errors,
as well as the reduced chi squared, the mean error for an observation of average
weight, the total number of points used in the solution, and the covariance.
One can rerun the solution, eliminating points which deviate more than a given
factor times the mean error is desired.  The solution and the data are next
plotted, first as rho' against theta', and then as rho'/rho against theta' -
theta,  where the prime refers to the projected values.  Next, the residuals
can be displayed.  All input and results are written to the log file, 
one2two.log.


	    Running the Nonlinear Least Squares Demonstration
 Programs nl_demo_1.exe, nl_demo_2.exe, nl_demo_3.exe, and nl_demo_4.exe

     nl_demo_1.exe fits either a constant, a straight line, or two
intersecting lines to data which represents two intersecting  straight 
lines.  Although nonlinear least squares is not needed for fitting a
constant or a straight line to data, it is required if the fitting
function is two intersecting straight lines.  Two intersecting
straight lines are a good fit to data such as the logarithmic
integrated luminosity functions of rich clusters of galaxies, and the
run of log radius parameter with magntidue of cluster galaxy clusters.
The program begins by asking:

  Enter a choice:
                   K = Constant
                   L = Single straight line
                   T = Two intersecting straight lines (default)
  
For any choice the program asks if noise should be added to the data.
If choice K is made, the program asks for an estimate of the average;
if choice L is made, the program asks for an estimate of the constant
and slope;  and if choice T is made, the program asks for an estimate
of the intersection point and the slopes for the bright (left) and faint
(right) ends.  For choice T, the actual parameters used in the fit are
the constants and slopes for the bright and faint ends, but the parameters
that are asked for are more intuitive.  Defaults are provided in each case.
For each choice, the dimension of the data, and the dimension of the 
independent variable in nonlinfit.for are equal to one.
     nl_demo_2.exe fits an ellipse to x,y data given as a function of
the angle from the center of the ellipse.  An angle measured from the 
center would not be of use in fitting an ellipse to binary star data,
but is of use in certain image processing algorithms.   After prompting 
for whether noise should be added to the data, the program asks for
the initial inclination, eccentricty, amd semimajor axis.  The dimension
of the data is two and the dimension of the independent variable is one
in this application.
     nl_demo_3.exe fits a circle to x,y data.  There is no associated
angle connected to these data.  The setup for this situation is much
different than in the above example.  Instead of minimizing the
sum of the squares of differences in the x and y postions separately,
the program must minimize the sum of the squares of the differences in
the radii. 
     nl_demo_4.exe fits the de Vaucouleurs formula to a one-dimensional
file of surface brightness data.  When the program asks for a file
name, enter "galaxy_profiles.dat" or press the <CR> if this file is
in the same directory as the execute image.  Next the program asks for
the ID of the object;  Enter 70 or take the default.  Next the program
asks for the starting and ending radii for the fit;  enter the desired
radii or take the default if the entire range is desired.  The first
data point is at the center of the galaxy, but actually represents an
average surface brightness over the central pixel.  This average 
corresponds to the surface brightness at a radius of about 0.25 pixels.
The next prompt of the program gives the user to option of adjusting
the first data point to a radius of 0.25 pixels.  Next the initial 
estimates for the galaxian surface brightness at 1/2 the total light,
the corresponding radius, and the sky level are input.  The program
then asks for a weighting scheme;  the default is the most physically
plausible.  Next, the program asks for the readout noise and gain;
the defaults most accurately describe this data set.  The solution
will have a large chi squared because the effects of seeing have not
been taken into account and because the de Vaucouleurs formula does
not give a perfect fit to galaxian surface brightness data.  In the
full MIIPS package, option RG performs surface brightness fitting with
seeing taken into account.  In this final example, the dimensions of 
the data and the independent variable are one. 


		Working with the Plot Programs

     Plotting is built into the binary progam and some of the nonlinear
least squares demo programs.  A plot can be sent to one or more plot
devices and plot file simultaneously.  The plot devices that appear in
the list presented to the user are determined by settings in the file
display-plotting_availability.dat.  Simply uncomment or comment those
devices you wish to be or not be shown.  When the plot first appears on the
selected device(s), help can be obtained by typing (not entering) the
letter h or H.  The following will then appear (note that ^ denotes that
the control key is to be pressed as well):

A = Turns on the crosshairs and by pressing the <CR> at chosen X limits,
    the mean Y value will be calculated for each plot.
a = Allows the user to enter annotation at the location of the crosshairs
    with the color most recently selected.
    ^I (^L on Mac OS X) toggles to the Greek alphabet and special symbols,
    and back to English
    ^H (^B on Mac Os X) gives a backspace
    ^K toggles to subscript, superscript, and back to normal
^A = Prompts user for the height of the annotation.
B = Defines a box with the crosshairs placed at the lower left and upper right.
    Will replot with this scaling.
b = Allows the user to be prompted for the background color on Enhanced
    SAOimage.
C = Turns on the crosshairs and by pressing the <CR>, prints the values at
    that location and puts the values in a common block;  typing - deletes the
    last pair of values from the common block; and typing Q turns off the
    crosshairs.
c = Allows the user to be prompted for the color, e.g., on Enhanced SAOimage.
F = Allows the user to alter the scaling factor on the current plot device(s).
f = Allows the user to change the fill style for each plot.
H = Gives help.
h = Gives help.
I = Allows the user to be prompted for several of the plotting parameters
    before a replot is done.  This command is typically used when preparing
    a plot for publication.
    The following operations are available:
    1) Inverting the X axis and/or Y axis
    2) Labeling the X and Y axes in the following ways:  Linear automatic,
       Linear manual, Antilog automatic, Antilog manual (antilog refers to
       the fact that the labeling is the antilog of the plotted values which
       are logs)
       a) In the Linear manual mode one can specify for the X and Y axes, the
       lowest labeled physical value, the physical value/interval, and the
       number of intervals (coded as nn.llrr where nn is the integer part, .ll 
       represents the left (or bottom) fractional part, and .rr represents the
       right (or top) fractional part of an interval).
       b) In the Antilog manual mode one can specify for the X and Y axes, the
       lowest displayed tick mark (coded as log.antilog where log is the
       integer part of the plotted value (which is a log), and antilog
       represents the first displayed tick mark of that decade (which
       is an antilog)).  The antilog of the physical value at the first tick
       mark may or may not be printed byu the program.   One can also specify
       the number of displayed decades (coded as n.antilog where n is the
       integer part of the number of decades, and antilog represents the
       rightmost displayed tick mark of an additional decade.  For example, if
       one enters -1.5 for the lowest value and 3.2 for the number of decades,
       then the first tick mark will be at X=0.5 (log = -0.301 = -1 + 0.699)
       and the last tick mark will be at X=200 (log = 2.301).  Note that 
       fractional parts of .0 and .1 behave the same way.
       
       Note:  If the original plot was linear, then the log of the data should
       be taken first (with the L command) for the antilog labeling to make 
       sense.
    3) Specifying symbol heights
    4) Specifying labels for the X and Y axes
    5) Specifying a title
    6) Specifying one or more print devices
L = Allows the user to take log(X) and log(Y).
l = Allows the user to take ln(X) and ln(Y).
M = Allows the user to modify the X and Y values by adding increments and
    adjusting by scaling factors.
m = Allows the user to modify the X and Y values by adding increments and
    adjusting by scaling factors for a selected plot.
O = Redoes the original plot with any new axes, colors, and symbols.
o = Redoes the original plot without any new axes or symbols.
P = Allows the user to take powers.
p = Allows the user to specify the color of each plot.
Q = Returns.
q = Returns.
R = Turns on the crosshairs and by pressing the <CR> at chosen X limits,
    replotting with automatic scaling will be done.
S = Allows the user to specify the style of vector.
s = Allows the user to specify the symbol for a set of points.
V = Draws a vector of the color and vector style most recently selected.
v = Allows the user to be prompted for the starting and ending physical
    values of a vector.
X = Allows plotting an additional X axis in different linear units.
x = Allows plotting an additional X axis in different antilog units.
Y = Allows plotting an additional Y axis in different linear units.
y = Allows plotting an additional Y axis in different antilog units.

     On SAOimage and xgterm, user prompts appear on the text terminal 
whereas on all other devices the prompts will appear on the Tek window.
Note that a plot can be sent to more than one device at a time.
Xgterm, a color xterm, behaves mostly like xterm.  One difference
between the two is that xterm allows one to use the left mouse button to
interact with the plot whereas xgterm requires a <CR> press.  SAOimage
also requires a <CR> press for plot interaction.  SAOimage on Mac OS
also requires that it be given focus by clicking in the frame before
any interaction is attempted.  Following that, the cross cursor should
be positioned within the SAOimage desktop area before and commands are
given.  The version of SAOimage available from most sources will not work
with plotting;  the version that is required is "Enhanced SAOimage, v. 1.24",
available at the MIIPS website.
     The plot device xgterm is a color xterm-like graphics terminal
emulator which runs on Unix.  Copies for various operating systems can be
found on the website.
     Xgterm needs to have its colors defined in the user's .Xdefaults file.
The following entries will ensure that the correct colors are displayed:

Xgterm*gterm*color0:      black
Xgterm*gterm*color1:      ivory1
Xgterm*gterm*color2:      red
Xgterm*gterm*color3:      green
Xgterm*gterm*color4:      blue
Xgterm*gterm*color5:      cyan
Xgterm*gterm*color6:      yellow
Xgterm*gterm*color7:      magenta
Xgterm*gterm*color8:      gold1
Xgterm*gterm*color9:      DarkSlateGray3
Xgterm*gterm*height:      601
Xgterm*gterm*width:       801

     If a plot file is being created it is possible to add annotation
that will be written to the file.  For example, if one selects

  DEVICES=X F

the plot will appear on an xterm and be written to a file.  Pressing
"a" while the plot is displayed on an xterm will then bring up a cursor.
Position the cursor on the plot and then click the left mouse button 
(or press the <CR> for xgterm and SAOimage).  You are then prompted to 
enter some annotation.  You can enter either English text, Greek letters,
special symbols, or some combination of them.  Typing ^I (^L on Mac OS X)
at this time, toggles to the Greek alphabet and special symbols, and back
to English.  In the Greek mode, the numbers 0 to 9 produce the symbols 0
to 9.  One could for example use special symbol 1 (a circle) to denote the 
position of the primary in a plot of a relative orbit.  Note however,
that the cursor center currently corresponds to the lower left corner 
of the initial character.


                        The Plot Command

     After a plot file has been created, the plot can at any time be 
directed to any of the available plot devices by using the plotcom.exe 
program.  Since the plot file's default name is plot.plt, be sure to 
change this to some other name to avoid having it be overwritten by another
plot file.  To plot a plot file, first be sure that you have set up the 
alias 'plot' as described above.  Enter:
  
  plot device=P xoff=X yoff=Y scale=S rotate=R number=N input_plot_file

where 
1)  Each optional keyword, and in the case of "device", its value, can be
    shortened to an unambiguous abbreviation
2)  If no device is specified, the default is xterm
3)  If no plot_file is specified, the default is plot.plt
4)  An optional / delimiter can be used between keywords (but not before the
    first one)
5)  The keywords have the following meaning:
      device is the plot device, with values, P, equal to
         TEKTRONIX  = Graphics terminal (VT100/Retrographics and Visual 550)
         GRAPHON    = Graphon graphics terminal
         CODONICS   = Codonocs graphics terminal
         MICROTERM  = Microterm graphics terminal
         VERSATERM  = Versaterm graphics terminal emulator for Macintosh
         XTERM      = Xterm graphics terminal emulator for OpenVMS and Unix
         XGTERM     = Xgterm grpahics terminal emulator for Unix
         SAOIMAGE   = Enhanced SAOimage
         _SAOIMAGE  = Enhanced SAOimage with not erasure of the previous image
         POSTSCRIPT = Postscript output file (default name is plot.ps)
         EPS        = Encapsulated postscript output file (default name
                      is plot.eps)
         (each device can be shortened to an unambiguous abbreviation,
         e.g. pos or POS for POSTSCRIPT)
      xoff is the horizontal offset, X, of the plot in inches
      yoff is the vertical offset, Y, of the plot in inches
      scale is the magnification, S, of the plot in terms of a factor.
      rotate is the counterclockwise rotation, R, of the plot in degrees
      number is the number, N, of the complete plot within the plot file.
         Because the plot file is not closed until the binary program quits,
         all plots are written to the same file, and the "number" keyword
         must be used to select the plot.
6)  The keywords and their values can be upper- or lowercase
7)  When both rotation and offsets are given, the operation can be thought of
    as either 1) rotation about the lower left corner of the plot
    followed by translation in the rotated coordinate system, or 2) translation
    followed by rotation about the old location of the corner.  Thus a plot on
    xterm can be viewed rotated 90 counterclockwise with a command such as:
      plot yof=-6 rot=90 sca=0.75 myplot.plt
8)  Postscript files created by the plot command are by default matched to
    a printed sheet viewed in landscape orientation.  Thus when such a file
    is viewed with ghostview or another postscript viewer, they will appear
    to be rotated by 90 degrees counterclockwise.  To create a postscript
    file without the prerotation, use a command such as:
      plot dev=pos xof=-8.0 rot=-90 myplot.plt
9)  Encapsulated postscript files are by default not prerotated and will
    appear in the correct orientation in ghostview.  In addition, encapsulated
    postscript files are by default created with a bounding box size just
    slightly larger than the default XY plot size (X axis = 6 inches, Y axis
    = 5 inches).  If your plot size is larger or smaller than the default size
    just use an editor such as vi to change the dimensions in the *.eps file.
    The BoundingBox line is 5th from the top.  The encapsulated postscript
    files will not ordinarily produce output on a printer because because they
    do not contain the 'showpage' command.  If you wish to see a printed
    version of your eps file, just add 'showpage' after the last 'stroke'
    command on the third line from the end.
10) The keyword, number, selects the number of the plot within a multi-plot
    file.  If the number keyword is not given, by default the first plot is
    displayed on devices such as graphic terminals, xterm, xgterm, and
    SAOimage.  If a postscript file is created and no number keyword is given,
    all plots are written to the file.  For an eps file, only the first file
    is written.  If the value given for the number keywords is -1, then all
    plots are displayed overlapped on all devices, postscript files, and eps
    files.


               Plotting from an ASCII File

     One or more ASCII files of data can be plotted with the program
xyplot_ascii.exe, a general purpose interface for the xyplot.for.  Three
cases can be handled.  In the first case, the data for the abscissa and
ordinate are contained in one file having an arbitrary number of header lines,
an arbitrary number of columns, and an arbitrary number of rows of data.  All
columns must have the same number of rows however.  Multiple plots are possible
by selecting more than one column for the abscissa and ordinate.  The number
of columns chosen for the abscissa and ordinate must match.  In the second
case, the data for the abscissa are contained in a first file and the data for
the ordinate are contained in a second file.  The number of rows in both files,
other than header rows, must match.  Multiple plots are again possible.  In
the third case, the abscissa and ordinate data for the first plot are contained
in the first of several files, and the abscissa and ordinate data for
additional plots are contained in additional files up to a maximum of fifteen
plots.  This is the most general case because the numbers of rows do not have
to match between files.  In all three cases the data can be in the form of
decimal or integer values.
     A setup file needs to be opened which sets up the line dashing, pen
width, line style, symbols, and colors.  By editing this setup file, many
different graphs can be produced.  In the setup file, the name of the
control parameter is followed on successive lines by the values desired
for each plot.  The control parameters may be in any order.  The number of
values can be less than, equal to, or greater than the number of plots
desired.  The program will simply use the values up to the last one
available, and then roll the values over.
    The file xyplot_setup1.dat, shown below, is an example of this format:

LINE VECTOR STYLE
0
0
0
0
0
0
0
1
2
3
4
5
PEN WIDTH
20
LINE TYPE
-1
0
997
997
-1
997
997
SYMBOL
0
1
100
100
327681
100
100
5
6
7
8
9
10
INVERT X
NO
INVERT Y
NO
COLOR
16776960        Yellow
16711935        Magenta
65280           Green
65280           Green
16711680        Red
8388564         Aquamarine
8388564         Aquamarine
255             Blue
16766720        Gold1
65535           Cyan
7982541         DarkSlateGray3
16777200        Ivory1
10824234        Brown
16716947        Deep pink
5597999         Dark olive greem
15631086        Violet
16766720        Gold
16770229        Moccasin
X LABEL
X Axis
Y LABEL
Y Axis
TITLE
Anonymous

1) Each keyword is followed, on successive lines, by the values for a single
plot within the complete plot.  If there are more plots than values, rollover
will occur.  If there are fewer plots than values, the extra ones will not be
used.
2) The keywords may be in any order
3) Comments are allowed to the right of a value, however it is very important
that there be no tabs in the line.
4) The LINE TYPE (as explained in line.for) controls the plot lines and the
   type of plot, where:
   a) The magnitude of the value controls the frequency of plotted symbols,
      e.g. zero gives no symbols, and 4 gives a symbol every 4th data point
   b) Positive values give a straight line connecting every data point
   c) Negative values give no connecting straight lines
   d) If the value is 997 error bars are drawn (two plots are required)
   e) If the value is 998 a histogram is drawn with the bars stacked
      vertically if multiple plots are made
   f) If the valud is 999 a histogram is drawn with the bars placed next
      to each other is multiple plots are made
5) The SYMBOL controls the type of symbol where
   a) values from 0 to 13 in the first byte give the built-in symbols
   b) a character may be plotted if the ASCII code is placed in the second byte
   c) if a histogram is to be drawn, the value in the first byte give the
      filling style
   d) if error bars are to be drawn, the value in the first byte give the
      style of the bar, i.e., 0 give a short tick, 1 gives nothing, 2 gives
      an arrowhead.  If 100 is added to the first byte, the X or Y locations
      contain the central location and the deviation to the low and high
      directions, respectively, for the adjacent array locations.  Because
      errorbars require two plots, the values should be repeated.
   e) the value in the third byte give the symbol height in hundredths of
      an inch.  If the value is not present a default of 0.14 inch is used.

     In the above example setup file, the values under LINE TYPE and SYMBOL
indicate that the first plot will consist of points drawn with symbol number 0
with no connecting lines, and the second plot will have connecting lines
between the points with no symbols drawn.  The third plot will be error bars
drawn with the usual short ticks at the ends.  Because error bars require two
adjacent plot array locations, the values for each keword are repeated.  The
fourth plot will consists of points drawn with symbol number 1, but because
the symbol is to be drawn with a smaller size of 5/100 inches, 5 is added to
the 3rd byte, giving a final value of 1 + 5*256**2 = 327681.  A future version
of xyplot_ascii will attempt to make this operation more user friendly.
The next plot is again error bars, requiring repeated values.

     Five sample ASCII files are included in this package to demonstrate how
xyplot_ascii.exe works.  Launch the program, and you will be presented with
the following menu:

  Enter a choice for the input data:
       1 = Abscissa and ordinate data for one or more plots in one file
           (default)
       2 = Abscissa data in one file and ordinate data in another file for
           one or more plots
       3 = Abscissa and ordinate data for first plot in first file,
           additional data for additional plots in successive files, up
           to a maximum of ten files
  CHOICE=

Enter 1, and the program responds with:

  Open the file containing the abscissa and ordinate data for one or
  more plots.
  Enter the file name:
  FILE=

Enter ascii1.dat, and the program asks:

  How many lines are in the header?  (default = 1)
  LINES_HEADER_1=

Enter 1 or take the default, and the header line will be displayed, along
with the counts of the number of columns of data and the number of lines of
data.  The program then asks:

  Enter the column(s) to be plotted as abscissa values:
  COLUMNS_ABSCISSA=

Here we are going to plot the data in column 2 against time in column 1, plot
the curve in column 6 against time, and plot error bars for the data.  Because
all abscissa values originate from column 1, and because there are 4 plots
(data, curve, and error bars requiring 2 plots) we enter 1 1 1 1.  The program
then asks:

  Enter the column(s) to be plotted as ordinate values:
  COLUMNS_ORDINATE=

We enter 2 6 2 3 (column 2 for the data, column 6 for the curve, column 2 for
the central location of the error bar, and column 3 for the amplitdue of the
error bar).  Now the program asks for the name of the setup file:

  Open the setup file:  (default = xyplot_setup.dat)
  SETUP_FILE=

Enter xyplot_setup1.dat (do not take the default) and the program then asks

  Enter the plot devices:
       S   = SAOimage (Enhanced version)
      -S   = SAOimage, no erasure of screen
       G   = Graphics terminal (VT100/Retrographics and Visual 550)
       G4  = Graphics terminal emulator (Versaterm)
       X   = Xterm (default)
       XG  = Xgterm
       F   = File

Enter the appropriate device name, and you will see the plot.

     If you enter 1 1 1 1 1 1 1 for the abscissa columns, and 2 6 2 3 4 4 5
for the ordinate columns, you will see an additional set of data points
plotted with a different symbol, a different symbol size, a different error
bar length, and different colors (if you are using a color display).

                             *************
     Launch xyplot_ascii.exe again and this time enter 2 for the choice of
input data.  In this case, the abscissa data come from one file and the
ordinate data from a second file.  The program responds with:

  Open the file containing the abscissa data for one or more plots.
  Enter the file name:
  FILE=

Enter ascii2.dat, and the program asks:

  How many lines are in the header?  (default = 1)
  LINES_HEADER_1=

Enter 1 or take the default, and the header line will be displayed, along
with the counts of the number of columns of data and the number of lines of
data.  The program then asks:

  Enter the column(s) to be plotted as abscissa values:
  COLUMNS_ABSCISSA=

Enter 1 1 1 1.  The program then asks:

  Open the file for the ordinate
  Enter the file name:
  FILE=

Enter ascii1.dat, and the program asks:

  How many lines are in the header?  (default = 1)
  LINES_HEADER_2=

Enter 1 or take the default, and the header line will be displayed, along
with the counts of the number of columns of data and the number of lines of
data.  The program then asks:

  Enter the column(s) to be plotted as ordinate values:
  COLUMNS_ORDINATE=

Enter 2 6 2 3, as before, and the program asks:

  Open the setup file:  (default = xyplot_setup.dat)
  SETUP_FILE=

Enter xyplot_setup1.dat, as before, and the program then asks

  Enter the plot devices:
       S   = SAOimage (Enhanced version)
      -S   = SAOimage, no erasure of screen
       G   = Graphics terminal (VT100/Retrographics and Visual 550)
       G4  = Graphics terminal emulator (Versaterm)
       X   = Xterm (default)
       XG  = Xgterm
       F   = File

Enter the appropriate device name, and you will see a plot which differs from
the first one in that the abscissa values are larger by a factor of 100.

                             *************
     Launch xyplot_ascii.exe again and this time enter 3 for the choice of
input data.  In this case, the abscissa and ordinate data for the first plot
are contained in the first of several files, and the abscissa and ordinate
data for additional plots are contained in additional files up to a maximum
of fifteen plots.  The program responds with:

  Open the file containing the abscissa and ordinate data for the first plot.
  Enter the file name:
  FILE=

Enter ascii3.dat, and the program asks:

  How many lines are in the header?  (default = 1)
  LINES_HEADER=

Enter 13, and the program will report the number of columns of data and the
number of lines of data, and then ask:

  Enter the column(s) to be plotted as abscissa values:
  COLUMNS_ABSCISSA=

Enter 1 1 1, (the columns for the x data points and their error bars).  Then
the program asks:

  Enter the column(s) to be plotted as ordinate values:
  COLUMNS_ORDINATE=

Enter 2 2 3, (the columns for the y data points and their error bars), and
the program responds with:

  Enter the name of the input file for an additional plot;
  enter 0 to continue:
  FILE=

Enter ascii4.dat, and the program asks:

 How many lines are in the header?  (default = 1)
 LINES_HEADER=

Enter 13, and the program will report the number of columns of data and the
number of lines of data, and then ask:

  Enter the column(s) to be plotted as abscissa values:
  COLUMNS_ABSCISSA=

Enter 1, (the column for the x data of a single curve).  Then the program
asks:

  Enter the column(s) to be plotted as ordinate values:
  COLUMNS_ORDINATE=

Enter 2, (the column for the y data of that curve).  The program next asks:

   Enter the name of the input file for an additional plot;
  enter 0 to continue:
  FILE=

Enter ascii5.dat, and the program asks:

 How many lines are in the header?  (default = 1)
 LINES_HEADER=

Enter 13, and the program will report the number of columns of data and the
number of lines of data, and then ask:

  Enter the column(s) to be plotted as abscissa values:
  COLUMNS_ABSCISSA=

Enter 1 1 1, (the columns for the x data points and their error bars for
another set of data).  Then the program
asks:

  Enter the column(s) to be plotted as ordinate values:
  COLUMNS_ORDINATE=

Enter 2 2 3, (the columns for the y data points and their error bars).  The
program next asks:

  Enter the name of the input file for an additional plot;
  enter 0 to continue:
  FILE=

Enter 0, because we are done entering the ascii files of data.  Now the
program will ask:

  Open the setup file:  (default = xyplot_setup.dat)
  SETUP_FILE=

Enter xyplot_setup2.dat (don't take the default).  Then you are asked:

  Enter the plot devices:
        S   = SAOimage (Enhanced version)
       -S   = SAOimage, no erasure of screen
        G   = Graphics terminal (VT100/Retrographics and Visual 550)
        G4  = Graphics terminal emulator (Versaterm)
        X   = Xterm (default)
        XG  = Xgterm
        F   = File

  DEVICES=

Enter your current graphics device and a plot with two sets of data with error
bars, and a curve with a dashed line will be displayed.  You can then use the
built-in interacive commands of xyplot to rescale, arithmetically tranform
the data, add annotation, and send the plot to the same or a different device,
or a file.


                           Acknowlegements

The following people have made contributions to some of the supporting source
code (all before 1988):  Jack Dongarra, Ron Ekers, James Haywood, Greg Quinn,
Denis Warne, Jeff Youngen, and W. Zwitser.  Special thanks go to James Haywood
for his efforts in coding the visual binary derivatives for nonlinfit.  Useful
feedback and bug discoveries have come from Sid Parsons, Larry Wasserman,
Keivan Stassun, Wei-Chun Jao, and Dan Kiminki.


     Any questions should be directed to Donald Gudehus at
gudehus@chara.gsu.edu.
