LIB MC
a library designed for celestial mechanics
version 20010717
Alain KLOTZ

User manual

Libmc is a Tcl extension library which adds functions concerning celestial mechanics. This user guide is adressed to users of Tcl scripts who want to use the libmc functions. Functions of libmc which require AudeLA "buffer" can be used only with the AudeLA platform.
 

1. Introduction

1.1. Loading the library in a Tcl interpreter

To load the libmc library in a Tcl interpreter, use the following function :

load libmc[info sharedlibextension]

in your current Tcl interpreter. The command [info sharedlibextension] allow, to the Tcl interpreter, to append letters for the suffix .dll or .so corresponding to the operating system Windows or Linux.

If the interpreter returns the error message : couldn't load file "libmc": invalid argument, it means that the file of the libmc library (libmc.dll with Windows and libmc.so with Linux) is not placed in the current folder of the interpreter (cf. pwd and cd function of Tcl).

1.2. General principles of Mc functions

Every libmc function, added to Tcl, begins with the prefix mc_ in order to be easily reconizable. For instance, function mc_date2jd converts a date in a julian day. The parameter of the function mc_date2jd is a Tcl variable which defines the date under differents formats. For exemple, in order to compute the julian day of the present time, the parameter is now. The syntax should be :

mc_date2jd now

If the interpreter returns the error message : invalid command name "mc_date2jd", it means that  the libmc library was not loaded correctly.

2. Reference guide for MC functions

The Tcl functions, added by MC, give many possibilities. According to the Tcl syntax, every function is followed by mandatory parameters and ended by optional parameters. These parameters must respect some constraints. MC used specific "types" of parameters. They are listed below : For exemple, the syntax of the function mc_date2jd is : date2jd Date
 

2.1. Definition of parameter types for MC :

2.1.1. Types Date and ListDates

the definition of a date can be writed by differents forms : N.B. Words NOW, NOW0 et NOW1 can be written uppercase or lowercase without incidence.

The type ListDates of MC defines a Tcl list of elements of type Date. For exemple :

{2000 1 1} {2000 1 2} 2451056.4563 {2000-01-03T00:00:00} now

2.1.2. Types Angle and ListAngles

An angle can be written by many ways. Some following exemples show these possibilities : The type ListAngles of MC defines a Tcl list of elements of type Angle. For exemple :

{45d34} {-45 38 6.4} {1h30m} {2 r}

2.1.3. Types Object and ListObjects

A planet or a star can be defined by a list of elements defined (by order) : N.B. Words that defines Format and Data can be written uppercase or lowercase without incidence.

For exemple, Jupiter planet is define by the following list

{jupiter internal}

or only by the word Jupiter since Internal is the default value. On the other hand, for the asteroïd 1997DQ :

{1997DQ Bowellfile astorb.dat}

The type ListObjectss is a list of Objects or * for every objects defined in the Data element. For exemple,

{ { {1} {6809} {10222} {1997DQ} } Mpcfile mpcorb.txt }

One another exemple, to define the nine planets of the solar system plus the moon and the sun :

{ * Internal}

which can be written by only * because Internal is the default value of Format.

2.1.4. Type Home

Type Home is used to locate a point on the Earth surface. By this way, one can compute an topocentric ephemeris for that location (taking account parallax effects). Type Home is defined by a list of the following elements : The other elements depend on the value of Format : N.B. Word that defines Format can be written uppercase or lowercase without incidence.

For example, for the Paris observatory, located at 2.3375 degrees eastern from Greenwich, rho*sin(phi') = 0.74918 and rho*cos(phi') = 0.65950, one writes :

{ MPC 2.3375 0.65950 0.74918 }

Another example is given for an observatory located at 3 degrees western from Greenwich, a latitude of 46 degrees and an altitude of 456 meters :

{ GPS 3 W 46 456 }

2.1.5. Type Field

Type Home is used to define a field of view seen by an optic system which produce a gnomonic projection (a CCD image for example). Type Field is defined by a list of the following elements : According to the value of format, the other elements are : N.B. Word that defines Format (NAXIS1, etc.) can be written uppercase or lowercase without incidence.

For example, to define a field centered on 12h00m and 15d with a 2.5 meters focal length telescope, a 768x512 pixels of 9 microns size camera, one writes :

{ OPTIC NAXIS1 768 NAXIS2 512 FOCLEN 2.5 PIXSIZE1 9e-6 PIXSIZE2 9e-6 CROTA2 0 RA 180 DEC 15 }
 

2.1.6. Types Format and ListFormat

Output format is a word which indicate the data to print. Values are : N.B. Words that defines Format can be written uppercase or lowercase without incidence.

Type ListFormat allows to write a list of parameters of type Format. For example, to output the name, date and magnitude of an object, one writes :

{ OBJENAME YEAR MONTH DAY MAG }

2.1.7. Type option -constraint

Type -constraint is dedicaced to options. It allows to exclude objects out acceptable limits. Two syntaxes can be employed : The following words can be used as constraints : N.B. Words that defines Options and their arguments can be written uppercase or lowercase without incidence.

Note : concerning options azimuth et ha, the meaning of > et < differs slightly. -ha< 15 means to keep every object which have a hour angle value lower than 15 degrees from the meridian. Same thing for azimuth.

For example, one wichs to keep only objects brighter than mag 12 but fainter than mag 10, having declinations upper to -15 degres, an altutide upper than 30 degrees. One writes :

-mag< 12 -mag> 10 -dec> -15 -altitude> 30

2.2. Tcl extension functions of MC

Here we explain how to use the MC functions in the Tcl interpreter.

2.2.1. Ephemeris

Le function which generates ephemeris is called mc_ephem.

mc_ephem ListObjects ?ListDates? ?ListFormat? -constraint Value -topo Home

By default, ListDate=NOW and ListFormat={ OBJENAME RA DEC}

It returns a list. Each element contains data defined by ListFormat. The last element of the list is different. It contains some informations about the computation. Star catalogs are not taken into account. Options -contrainst, magr and magb are not taken into account.

In the peculiar cases of objects of type asteroïds from the Bowell ou MPC database, their are two extra options :

Examples : In order to compute the ephemeris of an object for many dates, it is usefull to generate the ListDates from the function mc_date2listdates.

2.2.2. Objects in a field

mc_readcat returns a list of objects in the field of a CCD image. Its syntax is :

mc_readcat Field ListObjects Output -constraint Value -objmax Value -date Date -topo Home

The mandatory parameter Output indicates how to print the output datas : a Tcl list or a file :

The option -objmax allow to limit the number of objects in the output datas. By defualt, its value is 1000.

The only options -contrainst, magb are magv can be used.

Option -date allows to define a date for the case of computation of planetary positions (NOW by default).

Option -topo allows to define an Earth location for the case of computation of planetary positions (geocentric by default).

The output format is : {RA DEC MAGB MAGR X Y OBJENAME}. Le field OBJENAME is written only for planets. The last element of the list differ from the others. It contains some informations about the computation.

Examples :

2.2.3. Angle convertions

mc_angle2deg Angle : returns angle formatted floating point degrees.
mc_angle2rad Angle : returns angle formatted floating point radians.
mc_angle2dms Angle ?limit? ?nozero|zero? ?subsecdigits? ?auto|+? ?list|string? : return the angle as arc degrees,minute and second. The result is returned between 0 and 360 degrees. Option limit (=360 by default) allow to limit  the range of the angle. If the angle is upper than the limit then it is returned negative. For a declination, one must use limit as 90. Option nozero|zero format the output with leading zeroes before digits (=nozero by default). Option subsecdigits allow to return a number of digits after seconds. Option auto|+ allow to display the signe before the result (=auto by default hence no sign appear if the result is positive). Option list|string allow to format the output as a list (three elements {12 56 34.234} ex.) or as simple string (12d56m34s234 for exemple).
mc_angle2hms Angle ?limit? ?nozero|zero? ?subsecdigits? ?auto|+? ?list|string? : return the angle as hours,minute and second of time. The result is returned between 0 and 24 hours. Option limit (=360 by default) allow to limit  the range of the angle (limit must expressed in degrees). If the angle is upper than the limit then it is returned negative. Option nozero|zero format the output with leading zeroes before digits (=nozero by default). Option subsecdigits allow to return a number of digits after seconds. Option auto|+ allow to display the signe before the result (=auto by default hence no sign appear if the result is positive). Option list|string allow to format the output as a list (three elements {12 56 34.234} ex.) or as simple string (12h56m34s234 for exemple).
mc_angle2lx200dec Angle ?-format long|short? : returns angle formatted as a string for the function Sd of the LX200 protocol. Option "-format" allows to choose the output result as the long or short writting as it is described in the LX200 protocol.
mc_angle2lx200ra Angle ?-format long|short? : returns angle formatted as a string for the function Sr of the LX200 protocol. Option "-format" allows to choose the output result as the long or short writting as it is described in the LX200 protocol.
mc_anglesep ListAngles ?Units?: Returns angle distance and the position angle. ListAngles is composed by 4 angles on the following order : Ra1 Dec1 Ra2 Dec2. The result is expressed in degrees by default. It can be expressed in redian if Unit=Radian.
mc_angles2ultima2000 Angle Angle : returns a string formatted for the functions of the Ultima2000 protocol.
mc_ultima20002angles Ultima2000_string : returns a list RA DEC (in degrees) from a string formatted by the Ultima2000 protocol.

mc_radec2altaz Angle_ra Angle_dec Home Date : returns a list that contains four usefull anglesused in the altaz coordinate system : Azimut, Altitude, Hour angle and Parallactic angle.

mc_anglescomp Angle1 operand Angle2 : performs a mathematical operation (+,-,*,/,modulo) for the two angles.

Following function are obsolecents but can be used :

mc_deg2dms Degrees : Returns a list Dd Mm Ss.sss
mc_deg2hms Degrees : Returns a list Hh Mm Ss.sss
mc_dms2deg Dd Mm Ss.sss : Returns a list Degrees
mc_hms2deg Hh Mm Ss.sss : Returns a list Degrees

mc_sepangle Ra1 Dec1 Ra2 Dec2 ?Units? : returns angle distance and the position angle. Ra1 Dec1 Ra2 Dec2 are expressed in floating point degrees only. The result is expressed in degrees by default. It can be expressed in redian if Unit=Radian.

2.2.4. Date conversions

mc_date2jd Date : returns the julian day from a type Date.
mc_date2ymdhms Date : returns the gregorian calendar date (Yyyy Mm Dd Hh Mm Ss.sss) from a type Date
mc_date2lst Date Home : returns the local sideral time formatted Hh Mm Ss.sss from paraeter type Date and Home.
mc_date2listdates Date DateStep NbSteps : returns a list of ListDates from an initial Date increased NbSteps times the step DateStep (in days).
mc_date2iso8601 Date: returns a date as a FITS header argument of DATE-OBS.
mc_datescomp Date Operand days : performs a mathematical operation from a type Date.

Examples :

2.2.5. Astrometry

mc_buf2field Numbuffer : returns a ListField of optical parameters from the header FITSQ of the image staraged in the buffer Numbuffer.
mc_xy2radec x y Field : returns a list formatted {RA DEC}from the cartesian coordinates x et y.
mc_radec2xy ra dec Field : returns a list formatted {X Y}from the coordinates ra and dec.
mc_precessradec ListAngles Date_eq1Date_eq2 ?Listangles_proper? : returns an angle list in degrees (Ra and Dec) corrected by precession from coordinates Listangle formated {ra dec} with the equinox Date_eq1 towards equinox Date_eq2. One may add annual proper motions with Listangles_proper.

mc_listradec Field Mosaic ComPix : generate a list of {X Y RA DEC} from a field of type Field, making a mosaïc defined by the parameter Mosaic with an overlap of ComPix pixels between each field. The mosaïc can be generated by different ways :

9 2 3
8 1 4
7 6 5
If Parity=0 then every fields will be computed (default value).
If Parity=1 then only the odd fields will be computed
If Parity=2 then only the even fields will be computed
Examples :