UTM A universal transit modeler H.J. Deeg, 29/10/2002 Version described: utm vers. 24/10/2002 1. General Description ---------------------- utm is a modeler for all kinds of configurations between any number and kind of objects, such as stars, planets, moons,.. It calculates the resulting brightness, and displays graphical representations of the transit-configurations. Depending on the settings of the tflag parameter (see 'Setup file' below), utm can be used to: -generate model lightcurves from scratch (tflag=0),with or without noise (parameter 'onoise') -generate model lightcurves for given time-points (tflag=1), with or without noise -add models of planetary transits to given lightcurves (tflag=2, only the noiseless case makes sense here) utm allows the definition of two general kinds of objects: -dark objects (planets, moons, rings) -luminous objects (currently only stars) For all objects, a geometric representation of the transparency of their shape is created. For luminous objects, a geometric representation of their surface luminosity is created as well, that may include details like limb-darkening. These are 2dimensional image-arrays in a plane vertical to the observer (the x-y plane, see 'coordinate systems' below). These 2D images are positioned in a 3D coordinate system, where eventual occultations are taken into account to calculate the brightness of the luminous objects. Displays of the luminosity of the system, state of the planetary system, and of the surface of the luminous objects can be shown. 1.1 System requirements ----------------------- utm was written with IDL version 5.1. The use of object oriented programming makes it impossible to rewrite utm for earlier versions of IDL. Source files needed to compile and run utm are: utm.pro setupfile.pro (at least 1 setup file is needed as well) The .pro files have to be in the current directory, or in the IDL-PATH. 2. Use of utm ------------- Start utm from the IDL command line with: IDL> utm,'setupfile',dflag example: utm,'set6bodies',3 where setupfile is the name of the setup file (this file is described below), and dflag takes one of the values 0-4. dflag controls the amount of information that is displayed: 0: none (only the resulting lightcurve may be written to a file) 1: printout of the lightcurve The time and brightness values of the modeled lightcurve are written to the terminal. The brightness may be displayed in three different ways, depending on 'oflag' (see description of setup files): System luminosity: the summed luminosity of all objects is plotted Relative loss: This is a number between 0 and 1. Its definition is: loss = (L0 - L)/L0 , where L0 is the total brightness of the system in the absence of transits, and L the actual brightness. Magnitude variations: This is the 'relative loss' converted to magnitudes. Off-transit, this magnitude is zero 2: plot of the lightcurve A log-plot of the system's lightcurve is shown. The plot shows only the last 100 time-points. The unit of the y axis corresponds to the way in which brightness is defined (see above) 3: additional, graphics of the planetary system, and of the luminous objects Two panels show the objects in the x-y plane (the view as seen from the observer), and in the x-z plane (the view from 'above' onto the system). In the x-z plane, the observer is indicated by a triangle at X=0 at the bottom. Also, for each luminous object, its current surface brightness distribution is shown. The object's size is always scaled to fill the panel (Hence two stars of different size appear equal). Transiting objects may be surrounded by a brighter or fainter square. This is due to small corrections that are employed to improve the precision of the brightness calculation. (The images shown are of the array which is used in the actual calculation of the brightness) 4: additional, positions of objects are printed. Uses single step mode After each time-step, the program stops and the current positions (in X,Y,Z coordinates) of the objects are printed, as well as a list of the objects which are transiting. All initial parameters of utm are red in from the setup file, except dflag 2.1 Setup files --------------- The setup file defines completely the initial state of utm. In it, all the objects and their parameters are defined. Examples of setup files are given in the appendix. There is also a number of setup files in the utm directory (files starting with set*). Each line in a setup file consists of two tokens: keyword value If a third token is present, it is ignored (may be used for comments) For the creation of a setup-file, the following rules apply: - the order of the parameters is unimportant - each keyword has to be unique (in case of duplication, the value of the first occurrence will be used). An exception are the 'fit' keywords, which -if present- are ignored by utm; they are described in the documentation to 'ufit'. - between the keyword and the value has to be at least one white space (thus, keywords cannot contain spaces) - alignments and numerical formats can be varied freely - everything behind a # sign is ignored - the third word in a line is ignored - very short lines (less then 3 characters) are ignored - keywords unused by utm are ignored - Parameters for the individual objects have to be prepended by the object's number N. (this way, parameter names are always unique.) - There has to be an object with number 0 (zero), and the object numbers have to be consecutive (there may be no 'holes' in the numbering). - The object-number of sub-bodies (moons, rings) needs to be higher then the object number of the associated main-object (planet) Below is a list of the parameters that have to be defined in a setup-file for utm. Given is the name of the parameter, and the variable-type of the associated value. {A,B,C} means that the parameter can have only values from the set in {}. 'opt=x' means that this parameter is optional and will take default value x if absent (if optional parameters are absent, utm generates a warning message) . In the comments, 'NOT USED' means that this parameter is not used in any meaningful way in the current version of utm. It should however be present in the setup file with some dummy value. #general parameters (need always to be defined) sunit string #units for size tunit string #unit for time lunit string #unit for luminosity, NOT USED (but see oflag) munit string #unit for mass, NOT USED tflag {0,1,2} #0: generate time-points from tinit,tinc,tfin #1: use time-points given in file 'infilename #2: add model to data given in file 'infilename'. tinit double #if tflag=0: time at start of utm (in units of 'tunit') tfin double #if tflag=0: time at end of utm tinc double #if tflag=0: step-size of time #tinit,tfin,tinc are only needed and used if tflag=0 infilename string #name of input file, #if tflag =0: infilename not needed #if tflag =1: file needs to contain # time-points in first row #if tflag =2: file is a lightcurve (time-points in # first, and brightness values in second row) oflag {0,1,2},opt=1 #0: output/input is given as system-luminosity #1: output/input is given as relative flux loss #2: output/input is given as magnitude variations onoise float,opt=0.0 #Gaussian noise to be added to output, defined like #oflag/lunit ooff float, opt=0.0 #adds an offset to output, in units of oflag wflag {0,1},opt=0 #1: write lightcurve to file, 0: don't do it lcfilename string,opt=lc.out #name of output lightcurve lchead {y,n},opt=y #write setupfile as header of output curve gsize integer size of 2D arrays that are used to represent objects. Minimum recommened size is 12. gsize cannot be changed without restarting IDL! #the following parameters have to be defined for ALL object classes (N is the object number): Ntype {star,planet,moon,ring} #type of object Nradi float #radius of object Nmass float #mass of obj (NOT USED) Nperiod double #period; if 0.0 then is fixed Nphase [0.0-1.0]double #phase (for defin. see 'coordinate system') Nepoch double #epoch (in unit 'tunit'). #EITHER phase or epoch needs to be given. #If both given, epoch overrides. Ninclin [0.0-90.0]double #inclination of orbit; 0=face-on, 90=edge-on #(for defin. see 'coordinate system') Nrdist double #distance from coord. ctr Npa [0.0-360.0]double #position angle: clockwise angle from +x axis. #if not given, defaults to pa=90 (+y axis) #for object type 'star' additionally: Nlum float #luminosity of object Nlimbd [0.0-1.0]float #limb-darkening coeficcient, for stars only # for object type 'moon' additionally: Nmainobj [0-Nmax]int #number of associated central object (a moon's positions,phase and periods are relative to the main-object) # for object type 'ring' additionally: Nmainobj [0-Nmax]int #number of associated central object Ntransp [0-1]float #FACE-ON transparency 0=opaque,1=transparent #!for object 'ring', the following parameters are DEFINED DIFFERENTLY then for #!the other objects: Nphase [0.01-1.0]float #phase around y axis (NOT USED) Nradi float #is the outer radius of the ring Nrdist float #is the inner radius of the ring Notes: - Again, for examples, see the appendix. - After changing the gsize parameter in the setupfile, IDL needs to be quitted completely, and restarted. The same applies, if using a setupfile with a different value of gsize then previously invoked. Otherwise, an error 'Conflicting data structures' will occur. This problem is due to IDL keeping structure definitions between program invocations. 2.2 Coordinate system ---------------------- The following coordinate system is used internally in utm: y ^ | | |_____>x / / z This is the standard for 3D image processing. The observer is at a positive z distance. Transits in front of the coordinate center occur at (0,0,z). 'rdist' is the distance of the object from the coordinate center. In the case of sub-objects (moon, ring), rdist is the distance from the main-object. 'Inclination' of an object is defined as the angle between the +y axis and a plane (with the object in it) rotated around the x axis, in direction +z ('Edge-on' is 90.0). 'Phase' of an object is defined as the angle between the object and the y-z plane, in direction +x. 3. Precision of utm ------------------- Below, results are shown from tests using setup file 'setcalib', where a star is transiting in front of a uniformly bright disk. The tests were performed for two sizes of 2D arrays (setup parameter gsize). gsize=12 Rplan/Rstar theor.loss loss in utm rel. error 0.001 1e-6 0.000001 <0.5 (limited by display) 0.01 1e-4 0.000101 <0.015 0.1 0.01 0.010050 0.005 0.2 0.04 0.040200 0.005 0.25 0.0625 0.062810 0.005 0.5 0.25 0.251258 0.005 0.9 0.81 0.824226 0.017 gsize=24 0.001 1e-6 0.000001 <0.5 (limited by display) 0.01 1e-4 0.000100 <0.005 0.1 0.01 0.010000 <0.00005 0.2 0.4 0.039998 0.00005 0.25 0.625 0.062496 0.00006 0.5 0.25 0.249989 0.00004 0.9 0.81 0.810408 0.0005 TIP: If modelled lightcurves display significant steps, the gsize parameter should be increased. Steps result from a time-increment that is so small that the rasterized representations of the objects remain in the same relative position to each other. 4. Scope of current version of utm and possible future extensions ----------------------------------------------------------------- utm is a modeling program only. For the fitting of transit-models to lightcurves, use the program 'ufit' The current version of utm has only circular orbits implemented, whose parameters are defined by the 'rdist','inclination','period', 'pa' and 'phase' or 'epoch' keywords. The 'mass' keyword is not used. Implementations of Kepler's laws, or of orbits derived from the 2 or n-body problem, could be included in future versions of utm. The current version calculates the lightcurve only in a single color (wavelength). If multi-color models need to be generated, one could run utm repeatedly with different values of limb-darkening (For multi-color models, one should define 1-N names of colors in the setup-file. Also, the luminosities and limb-darkenings would have to be given for all N colors, the 2D lform and lformoc arrays would get a 3rd dimension along color, evtl. tform (=transparency) as well. A further keyword would define which colors are plotted against each other) Reflection of stellar light on planets is not taken into account (this would best be done by creation of a new 'luminous' object-class 'reflecting_planet') Improvements to precision (Better precision of ingress/egress can be obtained, if the oversizing of the arrays by 0.1 is reduced, to a constant of 1 pixels. Precision for binary eclipsing lightcurves can be improved if loss-correction in case tscale ge lscale is implemented.) 5. Description of the code for future changes --------------------------------------------- Care has been taken to comment the code line-by-line, and here only a general overview is given. utm has been written in IDL, using the object-oriented extensions that are documented in the IDL manual 'Objects and Object Graphics'. This manual (as are all IDL manuals) is available in the on-line IDL help. The general layout of the source file (utm.pro) is: -sub-procedures and functions -object-methods (functions and procedures) -main program 5.1 Main program ---------------- The main program is relatively short, and at the end. It starts at the line: pro utm,setfname,dflag An overview about it is given here: -A few general parameters are read in (mostly related to size of the geometric arrays) -The different classes of object structures are defined. tform is a 2D array with image of the transparency (0=transp., 255=opaque) lform contains an image of the intrinsic luminosity (luminous objects only) lformoc is an image of the current luminosity (this one is displayed in the graphic panels when dflag >= 3 ) -The objects are initialized (=filled with data) -some more parameters are read in to be used in the time-increment loop (the main loop), and graphics is initialized -the main loop starts (for t=tinit,tfin...): -the objects are sorted in z-distance (most distant, at -z, is first) -starting from the most distant object, they are tested if they are a luminous object (star), with: if obj_isa(obj[izs],'star') then ... -if it is a star, a list is made o& objects that are transiting in front of it, with: frind= obj[izs] -> findinfront(i,zind,pos,rad) -if this list is empty, the star's brightness is added to the total brightness with: syslum=syslum+obj[izs] ->getlum() ;no transits -if this list contains any other object(s), the star's occulted brightness is added to the total brightness with: syslum=syslum+ obj[izs] ->gettranslum(obj[frind]) -the remainder of the loop is again concerned with graphical display The subroutines and methods called by the main program should be fairly self-explanatory, only the gettranslum() function is significantly more complicated. 5.2 gettranslum --------------- gettranslum returns the brightness of the calling object in the presence of one or more occulters. The idea is, that the overlapping zones of the occulter and of the luminous object are scaled to the same size. The luminosity behind the occulter is then multiplied by the occulters transparency. The operations are done on the self.lformoc array (which is a 'working copy' of the static self.lform array), and on the occulters tform array. The overlapping zones are calculated in the lines defining the variables lindmin,lindmax,tindmin,tindmax, which contain the indices of the overlapping subarry from the self.lformoc and the tform array. These corresponding subarrys are lformbh and tformoc Also calculated are the scales of both arrays (lscale, tscale) which are in units of 'sunit' per pixel (sunit is the arbitrary size unit defined in setup). The coarser of the two subarrys (lformbh and tformoc) is then regridded (calls using 'congrid') to the size of the finer one. The normal case is that the tformoc array of the occulter is finer then the lformbh array (since the occulter is normally much smaller). The program first considers the other case in line if tscale ge lscale... , (note: in utm version 28/1/99, that case is disabled) that should only occur for extreme size differences in eclipsing binary stars. Here, the tformoc array is enlarged to correspond to lformbh, giving the tformocproj array. lformbh is then scaled by the transparency, and glued back into self.lformoc. The normal case (lscale gt tscale) follows next in line endif else begin ;the lform array is scaled to tform... The basic structure is the same, but more care is involved to obtain a precise calculation. A simple reversal of the procedure above results in brightness losses that have errors of up to 20% due to the imperfect size-match between lformbh and tformoc. This match is not perfect, since these arrays can only increment their sizes by full pixels, and the scale of the projected array lformbhproj deviates from the occulters scale. The brightness-loss that is obtained in the lformbhproj and (after re-sizing) in the lformbh array is therefore scaled by a correction factor derived from the ratio between the scale of lformbhproj and tformoc. Errors in the loss calculation are now orders of magnitude smaller. The brighter or fainter squares around transiting objects are caused by this correction. ---------------------------------- Version history 28/1/1999 first version for utm 28/1/1999 5/5/1999 version for utm 30/4/1999. Updated use of dflag, incl. additional params tflag, oflag etc., some rewrite 3/10/2000 inserted gsize into description of setup file Appendix : Examples of setup files ---------------------------------- file setsimple: #setupfile for single star with 1 planet #general parameters sunit Rsol #units for size tunit day #unit for time lunit Lsol #unit for luminosity munit Msol #unti for mass wflag 1 #1: write lightcurve to file, 0: dont't do it lcfilename out.test #name of output lightcurve tinit 0 tfin 1 tinc 0.02 stepsize of time in units 'tunit' gsize 12 sidelength of 2D array representing bodies' geometric form. #below entries for the objects #entries for first object 0type star #type of object 0radi 1 #radius of object 0mass 0.1 #mass of obj 0period 0.0 #period; if 0.0 then is fixed 0phase 0.0 #posital phase [0-1] #0epoch 0.0 #epoch 0inclin 90 #inclination of orbit;0=face-on, 90=edge-on 0rdist 0 #distance from coord. ctr 0lum 1 #luminosity of object 0limbd 0.6 #limb-darkening coeficcient, for stars only #entries for 1st object 1type planet #type of object 1radi 0.2 #radius of object 1mass 0.1 #mass of obj 1period 10.0 #period; if 0.0 then is fixed #1phase -0.05 #posital phase [0-1] 1epoch 10.4 #epoch in tunit 1inclin 90 #inclination of orbit;0=face-on, 90=edge-on 1rdist 5 #distance from coord. ctr 1pa 75 #clockwise angle from +x axis --------------------------------------------------------------- file setmktestlc #setupfile to produce a test-lightcurve for single star with 1 planet #nearly same config as for 'setsimple' #general parameters sunit Rsol #units for size tunit day #unit for time lunit Lsol #unit for luminosity munit Msol #unti for mass gsize 12 #sidelength of 2D array representing bodies' geometric form. tflag 0 #0: generate time-points from tinit,tinc,tfin #1: use timepoints given in file 'infilename #2: add model to data given in file 'infilename'. tinit 0 tfin 1 tinc 0.02 #stepsize of time in units 'tunit' infilename junk #name of input file, not needed if tflag = 0 oflag 2 #0: output is system-luminosity #1: output is a relative flux loss #2: output are magnitude variations (set lunit to 'mag'!) onoise 0.0005 #noise to be added to output, in unit of oflag wflag 1 #1: write output lightcurve to file, 0: dont't do it lcfilename testtrans.lc #name of output lightcurve #below entries for the objects #entries for first object 0type star #type of object 0radi 1 #radius of object 0mass 0.1 #mass of obj 0period 0.0 #period; if 0.0 then is fixed 0phase 0.0 #posital phase [0-1] 0inclin 90 #inclination of orbit;0=face-on, 90=edge-on 0rdist 0 #distance from coord. ctr 0lum 1 #luminosity of object 0limbd 0.6 #limb-darkening coeficcient, for stars only #entries for 1st object 1type planet #type of object 1radi 0.1 #radius of object 1mass 0.1 #mass of obj 1period 10.0 #period; if 0.0 then is fixed 1phase -0.05 #posital phase [0-1] 1inclin 90 #inclination of orbit;0=face-on, 90=edge-on 1rdist 5 #distance from coord. ctr --------------------------------------------------------------- file set6bodies #demonstration setup for binary star, with 2 planets, of which one #has a moon and the other has a ring #general parameters sunit Rsol #units for size tunit day #unit for time lunit Lsol #unit for luminosity munit Msol #unti for mass wflag 1 #1: write lightcurve to file, 0: dont't do it lcfilename out.test #name of output lightcurve tinit 1234500.0 tfin 1234600.5 tinc 0.03 stepsize of time in units 'tunit' gsize 12 sidelength of 2D array representing bodies' geometric form. #below entries for the objects #entries for star object 0type star #type of object 0radi 0.5 #radius of object 0mass 0.1 #mass of obj 0period 2.0 #period; if 0.0 then is fixed 0phase 0.4 #posital phase [0-1] 0inclin 90 #inclination of orbit;0=face-on, 90=edge-on 0rdist 1 #distance from coord. ctr 0lum 1 #luminosity of object 0limbd 0.5 #limb-darkening coeficcient, for stars only #entries for star object 1type star #type of object 1radi 0.25 #radius of object 1mass 0.1 #mass of obj 1period 2.0 #period; if 0.0 then is fixed 1phase 0.9 #posital phase [0-1] 1inclin 90 #inclination of orbit;0=face-on, 90=edge-on 1rdist 1 #distance from coord. ctr 1lum 0.1 #luminosity of object 1limbd 0.5 #limb-darkening coeficcient, for stars only #define planet 2type planet 2radi 0.05 #radius of object 2mass 0.001 #mass of obj 2period 7.3 #period; if 0.0 then is fixed 2phase 0.95 #posital phase [0-1] 2inclin 90.0 #inclination of orbit; 0=face-on, 90=edge-on 2rdist 10.0 #distance from coord. ctr #define moon 3type moon 3radi 0.03 3mass 0.0005 #mass of obj 3period 1.1 3phase 0.25 3inclin 45.0 #inclination of orbit; 0=face-on, 90=edge-on 3rdist 0.15 #distance from coord. ctr 3mainobj 2 #number of associated central object #define planet 4type planet 4radi 0.02 #radius of object 4mass 0.001 #mass of obj 4period 4.1 #period; if 0.0 then is fixed 4phase 0.70 #posital phase [0-1] 4inclin 90.0 #inclination of orbit; 0=face-on, 90=edge-on 4rdist 4.0 #distance from coord. ctr #define ring 5type ring 5radi 0.2 #in ring: outer radius 5mass 0.0002 5period 0 5phase 0.0 5inclin 30 #inclination of ring; 0=face-on, 90=edge-on 5rdist 0.1 #in ring: inner radius 5mainobj 4 #associated central object 5transp 0.8 #transparency of ring FACE-ON (at inclin=0), 0=opaque,1=transp ---------------------------------------------------------------------------