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 Besselian 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 manually 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 fictitious 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 to see the covariance: = 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 . 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 to see the covariance: = 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 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 program 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 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 , 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 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 press. SAOimage also requires a 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 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.