LIB MC
a library designed for celestial mechanics
version 20000402
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  (for Windows)

load bin/libmc.so  (for Linux)

in your current Tcl interpreter.

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.

1.3. Few examples

jlkhkjhkjh:
 
 

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 ?dec?: returns angle formatted as a list Dd Mm Ss.sss. If the second parameter is DEC, the result is written between -90 to +90 degrees (else between 0 and 360 degrees).
mc_angle2hms Angle : returns angle formatted as a list Hh Mm Ss.sss. The result is between 0 and 24 hours.
mc_angle2lx200dec Angle : returns angle formatted as a string for the function Sd of the LX200 protocol.
mc_angle2lx200ra Angle : returns angle formatted as a string for the function Sr of 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.

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).

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_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 :