UFIT Universal fitting program for planetary and stellar transits H.J. Deeg, 30/09/2000 Version described: ufit vers. 30/9/20000 1. General description ---------------------- ufit is a fitting program to evaluate the parameters of transit configurations in lightcurves. It is written as an 'envelope' of the 'utm' transit modeller, and can fit ANY continously variable parameter that can be specified in an utm setup file. ufit can easily be modified to call any program that reads utm-style setupfiles, and that returns an array of values. 1.1 System requirements ----------------------- ufit was written with IDL version 5.1. The 'utm' program, which is called by ufit requires IDl version 5. Source files needed to compile and run ufit are: ufit.pro utm.pro setupfile.pro (at least 1 setup file is needed as well) The source files have to be in the current directory, or in the IDL-PATH. 2. Use of ufit ------------- Before attempting to use ufit, familiarity with the utm transit modeller and the use of its setup-files is needed (see the document utm.txt). The following description assumes such familiarity. utm is invoked from the IDL command line with: ufit,'setfile' or ufit,'setfile',df where 'setfile' is a setup-file as specified in section 2.1, and df is an optional parameter with values [0,1,2] regulating the amount of informationthat is displayed about the fitting process. Not specifiying df is similar to df=0, and displays the least information. After starting, ufit will read the file with the data that are to be fitted, and display them. After each fitting iteration, an intermediate fit is added as a dashed line, and residuals as dotted lines. After the final fit, the display is cleared for display of the final fit, toghether with the values of the fitted parameters. A setup-file that contains the fitted parameter values is saved with the name 'setfit'. (this setup-file can immediately be fed back into ufit with: ufit,'setfit', or into utm with utm,'setfit',dflag ) 2.1 Setup Files --------------- The setup-files of ufit are identical to those of utm (for documentation, see utm.txt), except for the addition of the 'fit' (and the optional 'pdrat' and 'chitol') parameters as follows: fit name-of-parameter-to-be-fitted For example, if the 1radi and the 1phase parameter (radius and phase of object Nr.1 in the setup file) should be fitted, the setup-file needs to contain lines with: fit 1radi fit 1phase There have to be at least 1 and at most 8 'fit' keywords in a setup file for ufit. Any continously variable parameter that can be defined for utm can be set as a parameter to be fitted. The initial values of the parameters to be fitted are taken from their value in the setup file; i.e. if the setup file states: 1radi 0.08 #radius of object this will be the first guess for 1radi. Two more parameters influence the behaviour of the fitting routine: The Levenberg-Marquard algorithm used by ufit needs to calcualate partial derivatives df/da_i where f is the fitted function and a_i are the fit-parameters to be derived. For the calculations of the derivatives ufit needs to employ a numerical approximation: df/da_i ~ [f(x,a_i+e) - f(x,a_i)]/e , where e is << a_i. Ufit calculates the value of e using: e=a_i * pdrat from the parmeter file: pdrat 1e-2 #if pdrat is not specified, a default of 1e-2 is used pdrat should therefore be adapted to the range of values over which the fit-parameters can be varied. For example, if an eclipse-epoch should be fitted, and the epoch is given with the last 4 digits of the Julian date (1749.332 for example), then pdrat = 1e-6 would be appropriate. Parameters which can be varied only by tiny fractions of their value should however be avoided due to numerical imprecisions that result. It is therefore recommended to remove leading numbers from epoch values, and from the input x-values (dates in the lightcurve). It should also be kept in mind that pdrat is used equally for all parameters in a multi-parmeter fit. The convergence criteria of the fit can be set with chitol 1e-7 #if chitol not specified, default of 1e-5 is used Ufit will then stop if the fractional variation of the chi-square value falls below the value of chitol. There is also a maximum of 10 repetitions of ufit starts osciallating around some parameters. Setup-files made for ufit can be used with utm as well, the additional parmeters for ufit are simply ignored by utm. An example of a ufit setupfile is given in Apendix 1. 2.2 Example for fitting a lightcurve with ufit --------------------------------------------- In this example, first a noisy lightcurve of a simulated transit is created. ufit is then used to recover the key-parameters of the transit. a) creation of the test-lightcurve run utm (the modeller) with utm,'setmktestlc',3 This will create a lightcurve named 'testtrans.lc'. In the file 'setmktestlc' note the settings of tflag=0 (creation of a model from scratch), wflag=1 (save model to file), oflag = 2 (make curve of relative magnitudes) and onoise=0.0005 (add Gaussian noise with an rms of 0.0005 mag) Also note the parameters of the planet that causes the transit: 1type planet #type of object 1radi 0.1 #radius of object 1period 10.0 #period; if 0.0 then is fixed 1phase -0.05 #posital phase [0-1] b) fitting of parameters to lightcurve run ufit (the fitter) with ufit,'setfitestlc' In 'setfitestlc', it is specified, that the 1radi, 1phase and 1period parameters should be fitted to 'testrans.lc', starting from initial values of 0.08, -0.055 and 8.0. After doing a few iteration, ufit will display: ufit: fitted parameters-------------- 1radi : 0.10423620 1phase : -0.049632733 1period : 10.037008 parameters are saved to `fitset` ---- running utm once more with final parameters to save fitted values to file: fitout.lc Note, that the fitted parameters you obtain will differ slightly, since the lightcurve does contain some random noise. (If you change the 'infilename' parameter in 'setfitestlc' to 'testtrans.lcdemo' you should get exacly the same fit results as shown here) Besides displaying the final parameters, utm has also saved them to a new setup file called 'fitset', which could be used in further runs of ufit or utm (The 'fitset' setup file has all comments stripped). Also, since the wflag=1 parameter has been set, the model-curve obtained with the fitted values is saved to a file 'fitout.lc' 3. Comments and future improvements: ----------------------------------- Due to time-constraints, the current version of ufit has been tested only with the simple cases given in the fitting example above. A more thorough testing is certainly needed. The number of invocations of utm PER ITERATION STEP given by: 1+3*np, where np is the number of fit-parameters. If wflag=1, then utm is invoked once more at the end. ufit is therefore quite processing intensive! A dflag parameter to control the display (like in utm) is desirable Setup parameters to control the fitting process (number of iterations, fitting tolerance, etc..) are desirable. Appendix 1 ---------- demonstration setup-file for ufit file: setfitestlc (this is also in the ufit/utm distribution) ------------------------ #demonstration setup file for ufit # #this fits demo-lightcurves created by a previous run of # utm,'setmktestlc',2 #params to be fitted fit 1radi fit 1phase fit 1period pdrat 1e-2 chitol 1e-5 #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 gsize 12 #sidelength of 2D array representing bodies' geometric form. tflag 1 #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 testtrans.lc #name of input file, not needed if tflag = 0 oflag 1 #0: output/input is system-luminosity #1: output/input is a relative flux loss #2: output/input are magnitude variations (set lunit to 'mag'!) onoise 0.00 #noise to be added to output, in unit of oflag/lunit wflag 0 #1: write output lightcurve to file, 0: dont't do it lcfilename fitout.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.08 #radius of object 1mass 0.1 #mass of obj 1period 8.0 #period; if 0.0 then is fixed 1phase -0.055 #posital phase [0-1] 1inclin 90 #inclination of orbit;0=face-on, 90=edge-on 1rdist 5 #distance from coord. ctr Appendix 2 ---------- demonstration setup-file for generation of test data with utm file: setmktestlc (this is also in the ufit/utm distribution) ------------------------ #setupfile to produce a test-lightcurve 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 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