
.ec _
.ll 76
.ad b
.in 4

.ti -4
1 CURSOR          
.ti +4
[ORBIT_\]CURSOR

Call the graphic cursor for interactive data editing. This allows, among
other things, to ignore some data points, or to exchange the two stars
(to correct 180 degrees ambiguities).
For a summary of the supported actions, type ? when in cursor mode 

.ti -4
1 PERIODOGRAM     
.ti +4
[ORBIT_\]PERIODOGRAM Pmin Pmax Nperiods

Plot the Lomb-Scargle periodogram for the specified period range

.ti -4
1 SAVE 
.ti +4
[ORBIT_\]SAVE File__Name

Save the current data and orbit to a file (usable as input)

CAUTION: This command does not save whatever comments/notes the input file may
contain about the individual data points. If there are some and they are 
important to you (as is sually the case...), it's best to manually paste
the orbit part of a SAVE output with the data part of the original input.


.ti -4
1 READ
.ti +4
[ORBIT_\]READ Filename [/APPEND] [/OLD__FORMAT] 
 
Read one input file into memory. If /APPEND is
specified the new data are added to current ones.
Option /OLD__FORMAT provides backward compatibility with the old 
"fixed" format (still supported, but deprecated and no longer 
documented).  

The data files are free format ASCII text, and use a Keyword-Value syntax. Line
order is irrelevant, except that the latest occurence has precedence for 
keywords which should only occur once. Any item may be omitted and will 
then take a reasonable default value. The exclamation mark is the comment
character, and formatting details (spaces, number of digits...) should
not matter. 

The information naturally splits into 3 groups: initial orbital elements, 
data items, and auxiliary information (not directly relevant to the
orbit but useful: system name(s), position, spectral types...).



.ti -4
2 DATA
.ti +4
Presently supported data items are parallaxes, radial velocities,
and visual measurements (including interferometry). We plan to add
astrometric positions of the photocenter and interferometric uv data,
and would eventually like to support light-curves of eclipsing binaries.

Parallaxes are considered as data items, and used in the orbit 
adjustment as an additional link between physical (i.e. km or km/s) 
and angular (i.e. arcseconds) quantities. This unifies orbital
parallaxes from a fully constrained orbit (SB2+visual) with the
SB1+visual+parallax case, and this provide an optimal combination in
between. Syntax is 
.nf
PAR    Value Probable__Error
.fi


Radial velocities can be entered either as values (and probable error)
for one component, or as normalised (i.e. continuum=1) correlation
profiles. The component naming logic is summarised in the small diagram
below: component names can be 1 or 2 for the primary and secundary
of a binary system, 11 and 12 for the two inner components of the primary
in a triple (or symetric quadruple) system, or 21 and 22 for the two
inner components of the secundary. Higher multiplicities could easily be
supported upon request to the author, should that prove useful.
.nf
                       ----0----
                      |         |
                      1         2
                     ---       ---
                    |   |     |   |
                   11   12   21   22
.fi

The correlation profile approach provides better handling of 
profile blending near crossings, through use of a single profile width 
and depth for the full data set, and considerably reduces the number of
degrees of freedom in the adjustment. This often improves the precision
of the spectroscopic orbital elements by a factor of two. It also spares 
the user the trouble of identifying the components in nearly equal-lined 
SB2s, once an approximate orbit is available. It does on the other hand 
produce a less human-readable data file. Syntax is
.nf
V1       Date  Value Probable__Error  
V2       Date  Value Probable__Error  
V12      Date  Value Probable__Error  
V22      Date  Value Probable__Error  
VCORREL  Date  Npixels Refpix Refval Increment Sigma Val1 Val2 Val3...
....
.fi

"Visual" measurements can be specified as 2D separations in
rectangular (XY, see CAUTION note below on orientation conventions) or 
polar (rho-theta) coordinates, or as 1D
separations along an arbitrary direction (PROJ). The later description
is mostly used for 1D speckle data and lunar occultations. It could in 
principle also be used (twice) for 2D data too, but results in a less
readable graphic display. Rectangular 
coordinates are usually more apropriate at small separations (as Rho/Theta 
have strongly non-gaussian error statistics when Rho is less than 5 sigmas
or so). Polar 
coordinates are prefered when focal scale and orientation calibration 
dominate the error budget (i.e. at large separations, usually), because
focal scale and orientation typically are known with different uncertainties.

Syntax is:
.nf
rho-theta Date  Rho  Theta Stderr__Rho Stderr__Theta
XY        Date  X Y Stderr__X Stderr__Y
PROJ      Date  Posangle Separation Stderr__Sep 
.fi

Dates can be specified as Julian__Day-2400000, calendar date (for instance 
04-MAR-1996/12:34:11.6), as ISO-8601 dates (i.e. 1997-12-05T07:40:32), or 
as year and fraction of year (for instance Y1961.530).


CAUTION: X and Y are defined with the binary star observers' convention
that X is positive towards N and Y is positive towards E. This is
consistent with the astronomical definition of the position angle
(i.e. X= rho*cos(theta) and Y=rho*sin(theta)), but not with most
peoples's idea of what X and Y should be...

.ti -4
2 ORBITAL ELEMENTS
.ti +4
Given the non-linear character of the least square orbit adjustment,
initial values must be specified for the orbital elements. Also, one can
sometimes use external constrains (or an educated guess) to fix
an otherwise undetermined parameter (i.e. take the inclination from a
light curve analysis) and improve/permit a mass determination. All this can 
be done on the command line (using ADJUST or/and FIX) but it is usually 
more convenient to store these parameters in the data file.

The syntax for an orbital element line is
.nf
Element__Name   Value  Probable__Error  Status
.fi
Status is either "Fixed" or "Adjustable".

Supported orbital elements are listed (and briefly described) in the
help for ADJUST.

.ti -4
2 AUXILIARY INFORMATION
.ti +4
A number of things which are irrelevant to the orbit, but convenient
to have at hand.

.nf
Gl       Gliese__Name
HD       HD__Number         
NAMES    Other__Names
RA       HH:MM:SS.S
DEC      SDD:MM:SS.S
EQ       Year
TSA      Spectral__Type for primary
TSB      Spectral__Type for secundary                   
.fi

.ti -4
2 EXAMPLE
.ti +4

.nf
Gl       Gl 773.3            
RA       19:57:04            
DEC      -10:05.4            
EQ          1950.000
TSA        F8V              
TSB        G0V
!
P          1788.9988      9.3762
T0        47049.3359     24.2706
e              .5920       .0167
as             .1586       .0059
OM          327.1682      7.1612
om          318.7169     10.1511
i            22.0260     10.1786
K1            2.6006       .2676
V0           29.8432       .1026
! Data
PAR             .045        .001
!
VA       49138.60   30.68   .3   
VA       49183.45   30.52   .3   
rho-theta 49290.37  .1940  79.30  .0100 0.0 
rho-theta 44777.55  .2050 136.90  .0100 0.0 
XY       47700.19  -.0600 .2380   .0200 .0200 
PROJ      47702.29    0.   .2310 .0600   .0040
PROJ      48049.67    0.   .2300 .0100   .0080
PROJ      48050.67  -90.  -.1000 .0100   .0020
VCORREL 50080.12 10 90.5 0.0 3.0 0.01 1. 1. 1. .9 .8 .9 1. 1. 1. 1. 
.fi

A working example data file is part of the program distribution,
and can be found as gl886_profile.dat in the source directory.
It contains the data used by Delfosse et al. 1999 (A&A in press) 
to derive the orbit of the Gliese 866 very low mass system
triple system.


.ti -4
1 VISU
.ti +4
[ORBIT_\]VISU  [/ORBIT i] [/VELOCITY [Component]] [/CORRELATION n]
 
Produce a plot of the adjusted orbit and data values, for the
radial velocities, for the visual orbit, or for one coravel-like
velocity profile at a time.

.ti -4
1 FIT
.ti +4
[ORBIT_\]FIT
  
This command will perform a least square fit of the adjustable
orbital elements to the data.

.ti -4
1 FIX
.ti +4
[ORBIT_\]FIX Element [Value [Probable__error]]
 
Declare one orbital element as fixed, and optionally set its
value and probable error. If a value but no probable error is specified
a default zero probable error is used. See HELP ADJUST for a list of the
elements and a concise description of their meaning.

.ti -4
1 ADJUST
.ti +4
[ORBIT_\]ADJUST Element [Initial__guess] [/ALL] [/SB1] [/SB2] [/VISUAL]
 
Declare one orbital element as adjustable, and optionally set its
starting value for the (non-linear) least square fit. If option /ALL is
specified, all elements become adjustable at once (use FIX if you
then want to freeze some of them). Options /SB1, /SB2, and /VISUAL
make adjustable the elements which can be determined for,
respectively, a single line spectroscopic binary, a double line
spectroscopic binary, and a visual binary. Supported elements are:  

.nf
		 P    Period (Days)
		 T0   Epoch of periastron (Julian__days-2400000.0)
		 Ecc  Eccentricity (unitless)
	 	 as   Semi-major axis (arcseconds)
		 OM   Upper case omega (degrees)
                 w    Lower case omega (degrees)
                 i    Inclination (degrees)
                 K1   Radial velocity amplitude of component A (km/s)
                 K2   Radial velocity amplitude of component B (km/s)
                 V0   Barycenter radial velocity (km/s)
                 W1   Width of first correlation dip  (km/s)
                 W2   Width of second correlation dip (km/s)
                 EW1  Equivalent width of first correlation dip  (km/s)
                 EW2  Equivalent width of second correlation dip (km/s)

.fi
Of those, the last four are only necessary when the orbit is directly
adjusted to CORAVEL-like velocity correlation dips, rather than to
the resulting extracted velocities.

For triple and quadruple systems the above elements refer to the outer
orbit. They have the following additional elements to describe the inner 
orbit(s):
.nf
		 P_1    Period (Days)
		 T0_1   Epoch of periastron (Julian__days-2400000.0)
		 Ecc_1  Eccentricity (unitless)
	 	 as_1   Semi-major axis (arcseconds)
		 OM_1   Upper case omega (degrees)
                 w_1    Lower case omega (degrees)
                 i_1    Inclination (degrees)
                 K_11   Radial velocity amplitude of component A (km/s)
                 K_12   Radial velocity amplitude of component B (km/s)
.fi
and similarly for an orbit around the secundary of the outer orbit.

.ti -4
1 GLIESE
.ti +4
[ORBIT_\]GLIESE 
 
Read some information (parallax, position...) from the Gliese and Jahreiss
catalog (version 3.0). This of course can only work for Gliese stars, and if
you have the Gliese catalog on-line...

.ti -4
1 IGNORE
.ti +4
[ORBIT_\]IGNORE Data_Type 
 
Ignore some observational data during the orbit adjustment. Data_Type can
be PARALLAX, VELOCITY, CORRELATION, or VISUAL. USE has the reverse action.

.ti -4
1 USE
.ti +4
[ORBIT_\]USE Data_Type 
 
Use some (previously ignored) observational data during the orbit 
adjustment. Data_Type can
be PARALLAX, VELOCITY, CORRELATION, or VISUAL. IGNORE has the reverse action.

.ti -4
1 LIST
.ti +4
[ORBIT_\]LIST Information__Type [/MONTECARLO [Confidence_Level [Nsamples]]]
[/OUTPUT File_Name]
Print some information to the screen. Currently supported values are
DATA, STATISTICS, ELEMENTS, MASSES, and EPHEMERID. Probable errors are 
estimated in
the linear approximation (good when the relative errors are small), 
unless option /MONTECARLO is present. In this case confidence intervals
are listed for each parameter, at the requested confidence level (default
is 0.683, corresponding to 1 sigma for normally distributed errors). The
number of montecarlo samples can be selected, so that each user can make
his own tradeoff between computing time and statistical accuracy (the default
is to have 50 points outside the confidence interval: 90% confidence will
use 500 points, 99% will use 5000, and most likely will take a long time...).

/OUTPUT can be used to redirect the listing to an external file.
.ti -4
2 DATA
.ti +4
[ORBIT_\]LIST DATA

Print all data for current star.

.ti -4
2 STATISTICS
.ti +4
[ORBIT_\]LIST STATISTICS

Print a detailed summary of the residuals, number of data points and Chi2,
broken down by data types.

.ti -4
2 EPHEMERID
.ti +4
[ORBIT_\]LIST EPHEMERID [Ndates [Initial__date [Time__step] ] ] /SELECT Display_List

Predict radial velocities and relative stellar positions for arbitrary
dates from current orbital elements. Default parameters are 20 dates,
at 1/20th of a period spacing, and starting at current date.

Option /SELECT can be used to specify which ephemerid items will be 
displayed. The default is: Phase, V1, V2, Rho, Theta. It is usually 
adequate for double stars, so this option is most useful when analysing 
triple (or higher multiplicity) systems. Possible values then additionally
include V11, V12, V21 and V22.

.ti -4
2 ELEMENTS
.ti +4
[ORBIT_\]LIST ELEMENTS [ALL}

Print current determined orbital elements. If ALL is specified, even 
undetermined elements (for instance the systemic velocity for a purely
visual orbit) are displayed.

.ti -4
2 MASSES
.ti +4
[ORBIT_\]LIST MASSES

Print the astrophysical information which can be derived from the available
orbital elements: mass function(s), "projected masses", semi-major axis in 
AU, system mass, individual masses, parallax...



.ti -4
1 OPTIMISE
.ti +4
[ORBIT_\]OPTIMISE Parameter /TIME [/SB1] [/SB2] [/XY] 
         [/STORE] [/OUTPUT]

WORK ON THIS COMMAND IS STILL GOING ON...

Given an a priori orbit, optimise the dates of additional observations
(within a specified 
time interval) for best accuracy on one parameter. Existing
measurements are taken into account whenever any exist. Supported optimisable
parameters are MASS__A, MASS__B, MASS__TOT, and PARALLAX. Others (such as
any specific orbital element) could easily be added upon request. 
User input is the 
length of the interval (starting at current date by default), 
and the allowed number of measurements with their precision for each
data type (angular separations and radial velocities). 


The present version takes NO observing constraints (below the horizon, 
daytime...) into account. This command will thus mostly be useful
when the orbital period isn't close to either one year or one day
(or if the system is circumpolar).

Option /STORE can be used to append the simulated optimal observations
to the current measurement set (sometimes useful in complex optimisation).

Option /OUTPUT redirects command output to  the specified file.

.ti -4
2 /SB1
.ti +4
[ORBIT_\]OPTIMISE/SB1 Nvels StdErr

Specifies the number of single line radial velocity measurements and
their standard error (in km/s)

.ti -4
2 /SB2
.ti +4
[ORBIT_\]OPTIMISE/SB2 Nsb2 StdErr1 StdErr2

Specifies the number of double line radial velocity measurements and
the standard errors for the two components (in km/s)


.ti -4
2 /XY
.ti +4
[ORBIT_\]OPTIMISE/XY Nxy StdErr

Specifies the number of angular separation measurements and
their standard errors (in arcseconds)

.ti -4
2 /TIME
.ti +4
[ORBIT_\]OPTIMISE/TIME Ndays [Starting__MJD]

Specifies the duration (in days) and the starting date (in
julian days minus 240000, defaulting to current date) of the
interval within which observing dates should be optimised.




.ti -4
1 Language
.ti +20
ORBIT_\ Language Summary
.nf
ADJUST          : Change status of one parameter to adjustable
CURSOR          : Call the graphic cursor for interactive data editing
FIT             : Determine the orbital elements by least square fit
FIX             : Change status of one parameter to fixed
GLIESE          : Get some information from the Gliese and Jahreiss catalog
IGNORE          : Invalidate one type of observational data (see USE)
LIST            : Print information to terminal screen
OPTIMISE        : Optimise an observing schedule for a given a priori orbit
PERIODOGRAM     : Plot a Lomb-Scargle periodogram for the radial velocity data
READ            : Read a data file
SAVE            : Save the current data and orbit to a file (usable as input)
USE             : Validate one type of observational data (see IGNORE)
VISU            : Draw orbit and data points
.fi

.ti -4
1 END










