Instructions for EDITBINARY and BINARY for OpenVMS This file explains how to compile, link, and use the programs BINARY.EXE, EDITBINARY.EXE, ONE2TWO.EXE, and associated demo and plot routines on an OpenVMS 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, XYPLOT_PROGRAM.EXE, and XYPLOT2_PROGRAM.EXE which are used for directing a plot file to any supported plot device, for plotting data from an ASCII file on any supported plot device, and for plotting data from one ASCII file against another, respectively. A simple way to obtain the execute images as well as some sample data files and other files, is to download binary_vax_executables.zip from the download link at http://www.astro.gsu.edu/~gudehus/binary.html, and then extract the files. If you have access to the MIIPS package and are on an OpenVMS system you can alternately extract the execute images and other files from MIIPS$DISK:[MIIPS.FOR]BINARY_VAX_EXECUTABLES.ZIP. After obtaining the zipped file, first, uncompress the backup file with: UNZIP BINARY_VAX_EXECUTABLES.ZIP Then place the files into a desired location with a command such as: BACKUP BINARY_VAX_EXECUTABLES.BCK/SAVE/SELECT=[MIIPS.BINARY_EXE...]*.* [.MY_BINARY...] Note that all of the above two lines should be typed before pressing the carriage return. You should then carry out some assignments and logical definitions which are described further below. If you wish or need to recompile, you can download binary_vms_source.zip from the download link at http://www.astro.gsu.edu/~gudehus/binary.html, and then extract the source code and other files. If you have access to the MIIPS package and are on an OpenVMS system you can alternately extract the source code and other files from MIIPS$DISK:[MIIPS.FOR]BINARY_VMS_SOURCE.ZIP or create a new zipped backup file of the source code and other files with the command file [MIIPS.FOR]BINARY_VMS_SOURCE.COM. It is not recommended to copy the individual files from the MIIPS package. Once you have BINARY_VMS_SOURCE.ZIP available on your OpenVMS system, uncompress the file with the command: UNZIP BINARY_VMS_SOURCE.ZIP Place the files into a desired location with a command such as: BACKUP BINARY_VMS_SOURCE.BCK/SAVE/SELECT=[MIIPS.FOR.BINARY...]*.* [.MY_BINARY...] Note that all of the above two lines should be typed before pressing the carriage return. Set default to the directory [.MY_BINARY], say, and enter @MAKE_BINARY This will compile the files, put them into a library and link. A brief description of the source code files follows. In the directory [.MY_BINARY], say, one should have the files: Original Location Name on MIIPS$DISK Description ALPHA.FOR [MIIPS.FOR] User routine for character input BELL.FOR [MIIPS.FOR] Routine to ring the bell BESSYR_JULCENT.FOR [MIIPS.FOR] Routine to convert from Besselian years to Julian centuries BINARY.FOR [MIIPS.FOR] Main program for binary stars BINARY_EXCLUDE_BY_PHASE.FOR [MIIPS.FOR] Routine to exclude data by phase BINARY_INDEXES.FOR [MIIPS.FOR] Routine to establish offsets in parameter array BINARY_LTT_COR.FOR [MIIPS.FOR] Routine for light travel time correction BY_JD.FOR [MIIPS.FOR] Routine to compute Julian date from the Besselian year COFACTOR.FOR [MIIPS.FOR] Routine to compute a cofactor COFACTOR1.FOR [MIIPS.FOR] Helps of COFACTOR.FOR DATE_JD.FOR [MIIPS.FOR] Routine to compute Julain day number DAXPY.FOR [MIIPS.FOR] Required lower level routine DCD.FOR [MIIPS.FOR] Required lower level routine DCOPY.FOR [MIIPS.FOR] Required lower level routine DDOT.FOR [MIIPS.FOR] Required lower level routine DELAY.FOR [MIIPS.FOR] User routine to delay exection DETERMNT.FOR [MIIPS.FOR] Routine to compute a determinant DETERMNT1.FOR [MIIPS.FOR] Helps DETERMNT.FOR DHHMS.FOR [MIIPS.FOR] Routine to compute h, m, and s DISPLAY-PLOTTING_AVAILABILITY.DAT [MIIPS.PLOT] List of available plot devices DO.FOR [MIIPS.FOR] Required lower level routine DPAVERSIGWT.FOR [MIIPS.FOR] Routine to calculate weighted average and sigma DSPFA.FOR [MIIPS.FOR] Routine to factor a matrix DSPDI.FOR [MIIPS.FOR] Lower level routine to compute a determinant DYNAMIC.FOR [MIIPS.FOR] User routine to obtain dynamic memory EARTH.FOR [MIIPS.FOR] Routine to calculate Earth's parameters EDITBINARY.FOR [MIIPS.FOR] Main program to edit binary data EQHOR.FOR [MIIPS.FOR] Routine to compute azimuth, altitude, and zenith distance ERROR.FOR [MIIPS.FOR] Required lower level routine ETDATE_JC_BY.FOR [MIIPS.FOR] Routine to calculate Julian centuries and Besselian years FRINGE_ANGLE [MIIPS.FOR] Routine to compute baseline angle projected on sky GET_BINARY_HEADER.FOR [MIIPS.FOR] Routine to read data file header GET_ECLIPSE_EPOCHS.FOR [MIIPS.FOR] Routine to calculate epochs of possible eclipses for spectroscopic binaries HIBERNATE.FOR [MIIPS.FOR] Required lower level routine HMSDH.FOR [MIIPS.FOR] Routine to compute decimal hours HOREQ.FOR [MIIPS.FOR] Routine to calculate equatorial coordinates from horizon coordinates IDAMAX.FOR [MIIPS.FOR] Required lower level routine JD_BY.FOR [MIIPS.FOR] Routine to compute the Besselian year from the Julian date JD_DATE.FOR [MIIPS.FOR] Routine to compute the date from the Julian day number JD_SUN.FOR [MIIPS.FOR] Routine to compute the sun's position on the sky KEPLER.FOR [MIIPS.FOR] Routine to solve Kepler's equation KEYBOARD.FOR [MIIPS.FOR] Routine to obtain the key pressed MAKE_BINARY.COM [MIIPS.FOR] Command file to compile and link all the executables MAPSCRAT.FOR [MIIPS.FOR] Required lower level routine MATRIXINV.FOR [MIIPS.FOR] Routine to invert a matrix MATRIXINV1.FOR [MIIPS.FOR] Helps MATRIXINV.FOR MESSAGE.FOR [MIIPS.FOR] User routine to print messages on terminal and in log file NEL.FOR [MIIPS.FOR] Required lower level routine NELD.FOR [MIIPS.FOR] Required lower level routine NHINT.FOR [MIIPS.FOR] Required lower level routine NLDER_BINARY.FOR [MIIPS.FOR] Routine for nonlinear least squares adapted for BINARY.FOR NLDER3.FOR [MIIPS.FOR] Derivative for binary solution NLDER14.FOR [MIIPS.FOR] Derivative for ONE2TWO solution NLDER_DEMO_1.FOR [MIIPS.FOR] For nonlinear least squares demo NLDER_DEMO_2.FOR [MIIPS.FOR] For nonlinear least squares demo NLDER_DEMO_3.FOR [MIIPS.FOR] For nonlinear least squares demo NLDER_DEMO_4.FOR [MIIPS.FOR] For nonlinear least squares demo NLFUN_BINARY.FOR [MIIPS.FOR] Routine for nonlinear least squares adapted for BINARY.FOR and demos NLFUN3.FOR [MIIPS.FOR] Function for binary solution NLFUN14.FOR [MIIPS.FOR] Function for ONE2TWO solution NLFUN_DEMO_1.FOR [MIIPS.FOR] For nonlinear least squares demo NLFUN_DEMO_2.FOR [MIIPS.FOR] For nonlinear least squares demo NLFUN_DEMO_3.FOR [MIIPS.FOR] For nonlinear least squares demo NLFUN_DEMO_4.FOR [MIIPS.FOR] For nonlinear least squares demo NL_DEMO_1.FOR [MIIPS.FOR] Nonlinear least squares demo NL_DEMO_2.FOR [MIIPS.FOR] Nonlinear least squares demo NL_DEMO_3.FOR [MIIPS.FOR] Nonlinear least squares demo NL_DEMO_4.FOR [MIIPS.FOR] Nonlinear least squares demo NLIT.FOR [MIIPS.FOR] Routine for iterating in NONLINFIT.FOR NONLINFIT.FOR [MIIPS.FOR] Routine for generalized nonlinear least squares NONLINFIT1.FOR [MIIPS.FOR] Helps NONLINFIT.FOR NUMARGS.MAR [MIIPS.FOR] Required lower level routine ONE2TWO.FOR [MIIPS.FOR] Program to fit cosine curve to a set of 1-D interferometric data OPENCF.FOR [MIIPS.FOR] User routine to open a character file PARALLAXFACTORS.FOR [MIIPS.FOR] Routine to calculate parallax factors PLOT.OLB [MIIPS.LIB] Plot package library for OpenVMS VAX PLOTCOM.FOR [MIIPS.PLOT] Program to plot a file on any device PLOTDEVICES.FOR [MIIPS.PLOT] Routine for user to select plot devices PRECESSIO.FOR [MIIPS.FOR] Routine to compute precession PRINT_BINARY_HEADER.FOR [MIIPS.FOR] Routine to print binary star data file header on terminal PRTMSG.FOR [MIIPS.FOR] Required lower level routine SAVE.FOR [MIIPS.FOR] Required lower level routine STRKEY.FOR [MIIPS.FOR] Required lower level routine STRLUDEF.FOR [MIIPS.FOR] Required lower level routine SYMINV.FOR [MIIPS.FOR] Lower level routine to solve a system of linear equations TRANSPARENT_MODE.FOR [MIIPS.PLOT] Program to return a graphics terminal to transparent mode TRANSPARENT_MODE_X.FOR [MIIPS.PLOT] Program to erase the 4010 window of xterm and return control to the VT window TRANSPARENT_MODE_XN.FOR [MIIPS.PLOT] Program to retrun control to the VT window in xterm without erasing the 4010 window TV.OLB [MIIPS.LIB] Display package library for OpenVMS VAX USRINP.FOR [MIIPS.FOR] User routine for generalized character and numerical input UTGST.FOR [MIIPS.FOR] Routine to compute the mean Greenwich sidereal time VEL_AMP_ERROR.FOR [MIIPS.FOR] Routine to compute error of K WRITE_BINARY_HEADER.FOR [MIIPS.FOR] Routine to write binary star data file header XYPLOT.FOR [MIIPS.PLOT] Routine for generalized 2D plots XYPLOT_F.FOR [MIIPS.PLOT] Helper routine for XYPLOT.FOR XYPLOT_PROGRAM.FOR [MIIPS.PLOT] Program to plot from an ASCII file XYPLOT2_PROGRAM.FOR [MIIPS.PLOT] Program to plot from two ASCII files XYZECEQ.FOR [MIIPS.FOR] Routine to calculate equatorial rectangular coordinates ZFIOVI.C [MIIPS.C] Required lower level routine In the directory [.MY_BINARY.INCLUDE], one should have the files: Original Location Name on MIIPS$DISK Description BINARY_HEADER.FOR [MIIPS.INCLUDE] Include file for GET_BINARY_HEADER.FOR BINARY_PARAMETERS.FOR [MIIPS.INCLUDE] Binary parameters include file PLOTERRS.DAT [MIIPS.INCLUDE] List of plotting errors PLOTPAR.FOR [MIIPS.INCLUDE] List of plotting parameters SADERRS.DAT [MIIPS.INCLUDE] List of SAD errors SADPAR.FOR [MIIPS.INCLUDE] List of SAD parameters The samples files, included in both BINARY_VAX_EXECUTABLES.BCK and BINARY_VMS_SOURCE.BCK, are: Original Location Name on MIIPS$DISK Description MUCAS_L_PRI.DAT [MIIPS.SAMPLES] Astrometric data for Mu Cas from S. L. Lippincott, with parallax and proper motion removed MUCAS_L_PRI_PPM.DAT [MIIPS.SAMPLES] Astrometric data for Mu Cas from S. L. Lippincott, with parallax and proper motion included. MUCAS_SEC.DAT [MIIPS.SAMPLES] Position angle and separation data for the secondary of Mu Cas from various sources. MUCAS_VEL_PRI.DAT [MIIPS.SAMPLES] Radial velocity data for the primary of Mu Cas. HR6469_SEC.DAT [MIIPS.SAMPLES] Position angle and separation data for the secondary of HR6469. HR6469_VEL_PRI.DAT [MIIPS.SAMPLES] Radial velocity data for the primary of HR6469 combined from various sources. HR6469_VEL_SEC.DAT [MIIPS.SAMPLES] Radial velocity data for the secondary of HR6469 combined from various sources. 47_UMA.DAT [MIIPS.SAMPLES] Radial velocity data for two planets orbiting 47 UMa, from Fischer et al. SAMPLE_1D.DAT [MIIPS.SAMPLES] A sample file containing 1-D interferometric data which can be run with one2two.exe GALAXY_PROFILES.DAT [MIIPS.SAMPLES] 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 [MIIPS.SAMPLES] Save file for a simple solution of Mu CAS. The sample files are by default placed in the [.MY_BINARY] directory. The make command will create the object library BINARY.OLB. This together with the included object libraries PLOT.OLB and TV.OLB can be used to link with user written programs if desired. For whichever method you use to install the executable files, create the logical assignments: ASSIGN MY_DISK:[MY_DIR.MY_BINARY.INCLUDE] LBY: ASSIGN MY_DISK:[MY_DIR.MY_BINARY] MIIPS$PLOT: ASSIGN MY_DISK:[MY_DIR.MY_BINARY] XY$PLOT: where LBY references the location of some parameter files, MIIPS$PLOT references the location of DISPLAY-PLOTTING_AVAILABILITY.DAT, and XY$PLOT references the location of XYPLOT_SETUP.DAT. Then enter ASSIGN PLOT.PLT FOR079 ASSIGN VECT.RPL FOR053 ASSIGN MY_DISK:[MY_DIR.MY_BINARY] SAMPLES: where MY_DISK and MY_DIR.MY_BINARY refer to the location of the sample data files. Next, establish some symbols with A:==RUN MY_DISK:[MY_DIR.MY_BINARY]TRANSPARENT_MODE.EXE AX:==RUN MY_DISK:[MY_DIR.MY_BINARY]TRANSPARENT_MODE_X.EXE AXN:==RUN MY_DISK:[MY_DIR.MY_BINARY]TRANSPARENT_MODE_XN.EXE BINARY:==$MY_DISK:[MY_DIR.MY_BINARY]BINARY.EXE EDITBINARY:==$MY_DISK:[MY_DIR.MY_BINARY]EDITBINARY.EXE ONE2TWO:==$MY_DISK:[MY_DIR.MY_BINARY]ONE2TWO.EXE PLOT:==$MY_DISK:[MY_DIR.MY_BINARY]PLOTCOM.EXE XYPLOT:==$MY_DISK:[MY_DIR.MY_BINARY]XYPLOT_PROGRAM.EXE XYPLOT2:==$MY_DISK:[MY_DIR.MY_BINARY]XYPLOT2_PROGRAM.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 in an ASCII file. "XYPLOT2" will produce an XY plot of columnar data in one ASCII file against data in another ASCII file. 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. 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'. 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. 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 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. Running EDITBINARY The program EDITBINARY performs editing operations on binary star data written in standard format, allows manual input of data, and manually precesses position angle and separation. After launching the EDITBINARY program, you will be presented with the following menu: A = Adds one or more numbers to the data (default) CI = Creates a file of one-dimensional interferometric data from user supplied elements CS = Creates a file of artificial spectroscopic binary data from user supplied elements CV = Creates a file of artificial visual binary data from user supplied elements EI = Allows manual entry of one-dimensional interferometric data to a new or existing file ES = Allows manual entry of spectroscopic binary data to a new or existing file EV = Allows manual entry of visual binary data to a new or existing file M = Multiplies the data by one more more numbers P = Precesses the coordinates of the data. Should only be used where all data points have the same equator. PM = Precesses the position angle and separation of manually input data Q = Quits S = Smooths the data by averaging (blank line delimiters must be inserted in file) WS = Converts weights to sigmas The user input information should always be of the same case as what is shown in the menu, with the exception of logical answers for which TRUE, T, t, YES, y, J, and j are accepted in the affirmative and anything else is interpreted as false. Command "A" requires an existing file, and will add one or more independent numerical values to an equivalent number of columns of data. Since this is the default command, just press the Return to use it. Execution of the command will prompt the user for the name of the file to be edited, and then display the header information of the file. Next the user is prompted for the name of the output file. This is followed by a menu giving a number of choices equal to the number of data columns in the file of that type, excluding the Epoch column. For example, for a file with data representing position angle and separation (and the errors), the user is presented with the menu: P = Edits the position angle PE = Edits the position angle error S = Edits the separation SE = Edits the separation error If the position angle needs to be increased by 2.5 degrees and the separation error by 0.03 arc seconds, enter "P SE" (without the double quotes) and press the Return. Then when the program asks for the numbers, enter "2.5 0.03" and press the Return. The new file is written to disk and the program stops. Command "CI" will create a file of one-dimensional interferometric data from user supplied elements. When this command is chosen, the program will prompt the user for a file name, the name of the star, the star's coordinates, year of equinox, altitude, azimuth, longitude, and latitude of the interferometer, and the orbital elements and other information pertaining to the star. After entering the beginning and ending epochs in either Besellian years or Julian date, the program generates the data and asks if you wish to add noise to the data. Up to 10000 data points can be created. Command "CS" will create a file of artificial spectroscopic binary data from user supplied elements. When this command is chosen, the program will prompt the user for a file name, whether the star is the primary or secondary, the name and orbital elements of the star, and other information for the file header. There is also an opportunity to add reflex velocities for up to five subcomponents to the star system, and additionally save the subcomponent velocities in files as well. The program then generates the data and optionally adds user defined noise to the data. Up to 10000 data points can be created. Command "CV" will create a file of artificial visual binary data from user supplied elements. When this command is chosen, the program will prompt the user for a file name, the format of the data (X and Y coordinates, or position angle and separation), whether the star is the primary or secondary, the name and orbital elements of the star, and other information for the file header. The user is also asked whether the equator should be taken to be the epoch of the observation. In general for astrometric data (X and Y), the equator for the data is assumed to be that of equator given in the header. For visual and speckle data (position angle and separation), the equator for the data is assumed to be the epoch of the observation. The program then generates the data and optionally adds user defined noise to the data. Up to 10000 data points can be created. Command "EI" allows one to manually enter 1-dimensional interferometric data into a new or existing file. Upon choosing this command, the program first prompts for a file name, and if the file is a new one, it additionally prompts for the name and coordinates of the star, the equinox date, the scale, and whether the epoch is in Besselian years or Julian days. You can then enter the epoch, angle of the baseline projected on the sky, projected separation, and separation mean error. For an old file the existing header is displayed and the user enters data in the same format as what is present in the file and these data are appended to the file. Command "ES" allows one to manually enter spectroscopic binary data into a new or existing file. Upon choosing this command, the program first prompts for a file name, and if the file is a new one, it additionally prompts for the name and coordinates of the star, the equinox date, the scale, and whether the epoch is in Besselian years or Julian days. Then the user enters the epoch, velocity, and mean error of the velocity for each point. For an old file the existing header is displayed and the user enters data in the same format as what is present in the file and these data are appended to the file. Command "EV" allows one to manually enter visual binary data to a new or existing file. Upon choosing this command, the program first prompts for a file name, and if the file is a new one, it additionally prompts for the name and coordinates of the star, the equinox date, the scale, whether the type of orbit is absolute or relative, and whether the type of file is X and Y positions or position angle and separation. If the orbit is absolute, the user is further prompted for whether parallax and proper motion have been removed. For a relative orbit, parallax and proper motion are always assumed to have been removed. Then the user enters the epoch, the coordinates and their mean errors. For an old file the existing header is first displayed and the user then enters data in the same format as what is present in the file. Command "M" requires an existing file, and will multiply one or more independent numerical values to an equivalent number of columns of data. Since this is the default command, just press the Return to use it. Execution of the command will prompt the user for the name of the file to be edited, and then display the header information of the file. Next the user is prompted for the name of the output file. This is followed by a menu giving a number of choices equal to the number of data columns in the file of that type, excluding the Epoch column. For example, for a file with data representing position angle and separation (and the errors), the user is presented with the menu: P = Edits the position angle PE = Edits the position angle error S = Edits the separation SE = Edits the separation error If the separation needs to be increased by a factor of 1.5 and the separation error by a factor of 1.6, enter "S SE" (without the double quotes) and press the Return. Then when the program asks for the numbers, enter "1.5 1.6" and press the Return. The new file is written to disk and the program stops. Command "P" precesses the coordinates of both the position in the header and the data. If the file contains velocity data, then only the position in the header is precessed. It usually only makes sense to use this command on data where all the data points have the same equator, which is the expected situation for X and Y position data. The results will not be meaningful if the equator is equal to the epoch of each observation. Execution of the command will prompt the user for the name of the file to be edited, following which the header information of the file will be displayed. Next the user is prompted for the name of the output file. This is followed by a prompt for the initial equator (or equinox) where the default is the equator in the file. After the new equator is entered, the program converts the data. Command "PM" precesses the position angle and separation of maually input data. Execution of the command will prompt the user for the initial equinox, the right ascension and declination of the primary, the position angle and separation, and the final equinox. The program then precesses the coordinates and prints out the results on the terminal. Note that only the position angle will change in this operation. Command "Q" causes the program to stop. Command "S" smooths the data by averaging selected groups of data points. This command is useful if many points exist for a given range of epoch which is small compared to the system period, or for astrometric data containing parallax, small compared to a year. Each group to be averaged is defined by inserting a blank line delimiter in the file following the last line of data in that group. Note then that the first line of the data should not be a blank line, but the last line should. Each new datum represents a weighted average of the input points except for the epoch which is a simple average, and the mean errors where the new data are computed as the inverse square root of a simple average of the weights and further reduced by dividing by the square root of the number of points. Execution of the command simply prompts the user for the name of the input file and the output file. Command "WS" converts a data file containing weights to one containing mean errors (sigmas). This is useful if the original data was only available in the form of weights. The program first prompts for the name of the input file and the output file, and then asks for the sigmas that correspond to weights of zero for the various columns. For example, if the file contains X and Y coordinates, one should enter the sigmas for X and Y for a weight of 1; or if the file contains velocity coordinates, one should enter the sigma for velocity for a weight of 1. Running BINARY The program BINARY uses the nonlinear least squares subroutine NONLINFIT to solve for the orbital elements and other parameters such as parallax, proper motion, systemic radial velocity, mass ratio, and their errors, of a multiple star system by simultaneously considering weighted astrometric, relative positional, and radial velocity data. Both the primary and secondary are allowed to have spectroscopic subcomponents, present as included reflex velocities and files of subcomponent velocities. Up to 5 subcomponents in each can be simultaneously be solved for along with the astrometric and separation data. Therefore up to 12 stars could be considered in a restricted manner. The program can automatically take account of the light travel time across the orbit for spectroscopic binaries. Because the weights from the various input sources can be interactively scaled during program execution, it is possible to find a solution in which the reduced chi squared of each data variable is matched to unity, and which, in the absence of systematic errors, will thus yield an optimal solution. Systematic effects can be searched for by restricting the solution to various subsets of the data and checking for differences in the solution parameters inconsistent with their mean errors. The residuals of the visual solution can be written to a standard binary star file for further analysis, such as searching for a visual subcomponent. The program accepts files in the format described above for EDITBINARY, and writes the results to a log file with the name FOR007.DAT. For astrometric data, i.e., data of TYPE=Absolute, the equator for right ascension and declination is assumed to also be the equator for x and y positions. For visual and speckle data, i.e., data of TYPE=Relative, the equator is assumed to be the epoch of observation, though an exception can be made by setting the keyword TYPE equal to "Relative, Equator is constant". The data files can optionally include initial estimates of the elements, which the program can then use to start the solution. When the primary and secondary of a particular type (visual or spectroscopic) are solved together, "a" is that of the primary. For a single orbit of a particular type, "a" applies to that particular orbit. The program can also be used to solve for the elements describing a single or binary star with orbiting planets, when the planets impose reflex velocities on the parent star. For a single star with planets, there are four possibilities: 1) if there is just one planet, the planet could be treated as the secondary star; 2) if there is just one planet, the planet could be treated as a subcomponent of the primary; 3) if there are two or more planets, one planet could be treated as the secondary star and the others as subcomponents of the primary; 4) if there are two or more planets, the planets could all be treated as subcomponents of the primary. In cases 2) and 4) the program must work with a secondary star that doesn't actually exist. However if the period is forced to be very long, say 10^37 years, and all the elements of the main orbit are held constant in the solution, then the orbits of the planets can easily be solved for. In this case the velocity of the primary becomes insignificant compared to the reflex velocities of the planets. The initial estimates of the ficticious main binary pair could be included in the header of the data file, before holding them fixed in the solution, or more conveniently, only the period with a key value of 9999.99999 can be included in the header. When the program reads this key value, 1) the period is set to 10^37 years, 2) the other main pair elements are given appropriate values, 3) the main pair elements are automatically held constant in the solution, and inappropriate plots are suppressed. When considering solutions with planets, it is best to use a value of Scale so that the units of velocity in the columns in the data file are in m/s, i.e., Scale=0.001. For a binary star, as opposed to a single star, with planets, all the planets must be considered as subcomponents of the primary and/or secondary. On 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: SAMPLES:MUCAS_L_PRI.DAT Lippincott; Parallax and proper motion removed SAMPLES:MUCAS_L_PRI_PPM.DAT Lippincott; Parallax and proper motion not removed SAMPLES:MUCAS_SEC.DAT Various separations of pair SAMPLES: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: SAMPLES:MUCAS_VEL_PRI.DAT Radial velocities of primary SAMPLES:HR6469_VEL_PRI.DAT Scarfe et al; velocities of primary SAMPLES:HR6469_VEL_SEC.DAT Scarfe et al; velocities of secondary and one subcomponent SAMPLES: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 SAMPLES: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 than 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 mean error 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 SAMPLES: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, initial estimates for the orbital parameters are listed, based on the values in the header. If the above file was chosen, 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.42171925 +-0.5139801E-01 Time of periastron passage= 1975.752345 +-0.7410027E-01 Eccentricity= 0.6137377413 +-0.1635075E-01 Angle of line of nodes= 47.26983370 +-0.7312047 Inclination= -109.3814323 +-0.6914076 Angle from node to periastron= 335.4449922 +- 1.798943 Semimajor axis in "= 0.1888074436 +-0.2199082E-02 Parallax= 0.1322440279 +-0.1654172E-02 X center= 159.8349601 +-0.1514826E-01 X proper motion= 3.425092114 +-0.7987647E-03 X proper motion acceleration= 0.2532910792E-04 +-0.2052949E-04 Y center= -76.97343931 +-0.1569537E-01 Y proper motion= -1.587810484 +-0.8881817E-03 Y proper motion acceleration= -.6267391645E-04 +-0.2283482E-04 Additional Information The semimajor axis in " is assigned to the primary orbit The photocentric semimajor axis in " =0.1869193691 +-0.2177091E-02 The period in days is 7824.111324 +- 18.77271 The reduced chi squared is 0.99440011 for data dimension 1 0.99213061 for data dimension 2 The average reduced chi squared = 0.99326536 The mean error for a point of average weight is 0.15182121E-01 +- 0.744365E-03 for data dimension 1 0.16829353E-01 +- 0.825127E-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 -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 one or more letters corresponding to the plot devices you wish the plot to appear on, e.g. X F. If you are connected to an OpenVMS system via telnet or ssh from a Macintosh, then it is possible to use Versaterm. If you are connected to an OpenVMS system via telnet or ssh from a Unix system, then it is possible to use Xgterm. Versaterm and Xgterm do not run on OpenVMS. Note that SAOimage refers to "Enhanced SAOimage", available from http://www.astro.gsu.edu/~gudehus/enhanced_saoimage.html. After the plot appears, several interactive plot commands are available. Help can be obtained by typing (not entering) H or h. The full list of commands can be found in the section "Working with the Plot Programs". ***** If instead of positional data, 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 or C to reduce the amount of time spent 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_program.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. If the binary program was set up as a foreign command as mentioned above, then simply entering BINARY MY_FILE where MY_FILE.SVE is a save file, the binary program will automatically be rerun with the same parameter values. The extension "SVE" can be included on the command line if desired, but the file itself must always have this extension. This operation is made more useful by including keywords and new parameter 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 MY_FILE(NUMBERS_CONSTANT=1 SHOW_RESIDUALS=Y) In order to not hold any elements constant, NUMBERS_CONSTANT should be set to zero. There is one restriction on the use of parameter values entered on the command line: the OpenVMS operating system converts all characters to upper case. Therefore if a lower case string is entered, say as annotation on a plot, it will appear on the plot as upper case. To avoid this situation, simply edit the save file and enter the keyword and string there. Also bear in mind that the key presses used in the interactive plotting, and the mouse positions, are not recorded. Note that on the command line, the save file name may optionally include the extension, but may not include the version. 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. 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, NL_DEMO_2, NL_DEMO_3, and NL_DEMO_4 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" 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. Depending on the state of the this file, one might be presented with: Enter the plot devices: S = SAOimage -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 one or more letters corresponding to the plot devices you wish the plot to appear on, e.g. X F. If you are connected to an OpenVMS system via telnet or ssh from a Macintosh, then it is possible to use Versaterm. If you are connected to an OpenVMS system via telnet or ssh from a Unix system, then it is possible to use Xgterm. Versaterm and Xgterm do not run on OpenVMS. Note that SAOimage refers to "Enhanced SAOimage", available from http://www.astro.gsu.edu/~gudehus/enhanced_saoimage.html. After the plot appears, several interactive plot commands are available. Help can be obtained by typing (not entering) 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 toggles to the Greek alphabet and special symbols, and back to English ^H gives a backspace ^J 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 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, Versaterm, xterm, and xgterm, user prompts appear on the text terminal window, whereas on all other devices the prompts will appear on the Graphics (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. The version of SAOimage available from most sources will not work with plotting; the version that is required is "Enhanced SAOimage, v. 1.22", available at the MIIPS 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 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. To plot a plot file, first be sure that you have set up the PLOT command in a login file as: PLOT:==$MY_DISK:[MY_DIR.MY_BINARY]PLOTCOM.EXE Now enter: PLOT/DEVICE=P/XOFF=X/YOFF=Y/SCALE=S/ROTATE=R/NUMBER=N PLOT_FILE where 1) Each 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) 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 graphics terminal emulator for Unix SAOIMAGE = Enhanced SAOimage _SAOIMAGE = Enhanced SAOimage with not erasure of the previous image POSTSCRIPT = Postscript output file EPS = Encapsulated postscript output file (each device can be shortened to an unambiguous abbreviation, e.g. pos or POS for POSTSCRIPT)) XOFF is the desired horizontal offset, X, of the plot in inches YOFF is the desired vertical offset, Y, of the plot in inches SCALE is the desired magnification, S, of the plot in terms of a factor. ROTATE is the counterclockwise rotation, R, of the plot in degrees NUMBER is the desired 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 An ASCII file of data can be plotted with the XYPLOT_PROGRAM.EXE program. Simply enter XYPLOT_PROGRAM and the program will prompt for the number of header lines, the columns for the abscissas, and the columns for the ordinates. The number of columns given for the abscissa and ordinate must match. The maximum allowed number of characters in the ASCII file is 132. The plot styles, vector styles, colors, and labeling of the plots are given defaults by a setup file with the default name XYPLOT_SETUP.DAT. An example of the format of this file is: LINE VECTOR STYLE 0 1 2 3 4 5 PEN WIDTH 20 LINE TYPE -1 0 SYMBOL 0 1 2 3 4 5 6 7 8 9 10 INVERT X NO INVERT Y NO COLOR 16776960 Yellow 16711935 Magenta 65280 Green 16711680 Red 255 Blue 16766720 Gold1 65535 Cyan 7982541 DarkSlateGray4 16777200 Ivory1 10824234 Brown 16716947 Deep pink 5597999 Dark olive greem 15631086 Violet 16766720 Gold 8388564 Aquamarine 16770229 Moccasin X LABEL X Axis Y LABEL Y Axis TITLE Anonymous 1) Each keyword is followed by the values for a plot within the complete plot. If there are more plots than values, then rollover will occur. If there are fewer plots than values, then the extra ones will not be used. 2) The keywords may be in any order 2) Comments are allowed to the right of a value. 3) 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 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 4) 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 gives the style of the bar, i.e., 0 gives 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. e) the value in the third byte gives the symbol height in hundredths of an inch. If the value is not present a default of 0.14 inch is used. The program XYPLOT2_PROGRAM allows one to plot with two ASCII files, one for the abscissa and a different one for the ordinate. 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, and Wei-Chun Jao. Any questions should be directed to Donald Gudehus at gudehus@astro.gsu.edu.