SNMIN02 INSTRUCTIONS

Instructions and documentation for snmin02
for the simultaneous fitting of SNe Ia lightcurves
(Last updated 18 April 2003)
[This documentation is under development]

Original snminuit operator's manual by Don Groom, 1997 May 29 (editing repairs 1998 Nov 17, etc.)
Start of major update Feb02. New version snmin02 accomodates fits to more than two colors. Essentially finished 12/12/02.
Code and instructions revised 2002 aug by aconley, who made substantial improvements and other changes.
Revised 10 Oct 2002 and again 12 Dec 02 by DEGroom for similar reasons.

TABLE OF CONTENTS

Executive Summary
Other help files
Code organization
Running snmin02
[FOLLOWING UNDER DEVELOPMENT]
Format of template and K correction files
Data (lightcurve) file formats
TBA

1. EXECUTIVE SUMMARY

snmin02 makes a simultaneous fit to data obtained with ncolors different filters, using the CERN code MINUIT in order to obtain fit parameter correlations as well as nongaussian confidence limits in the parameters.

The single argument of snmin02 is a command file which specifies rest and observer's frame filters, photometry data path(s), and possibly K corrections and lightcurve templates. There are defaults on all of these, so the code will usually run with minimal instructions. The lightcurve data default is obsolete. The restricted set of K correction defaults is decent, as are the templates, but the expert will want to mess with them.

The basic IDL code spawns a FORTRAN process; the communication is by the files which each reads and writes.

The fits are displayed with nice screen graphics (see sn9781.jpg for an example). In addition, there are several output files: an ascii file generated by the FORTRAN code, a detailed postscript file of the results, a more publishable version of the postscript output, a short-form file to pass the results to cosmology fits, and an accumulating summary of the runs.

2. OTHER HELP FILES

This file contains instructions for using snmin02. The following additional files may be useful:

AAFREEDEMO: Try a couple of simple cases to see that the code works.

AACONTENTS: Tells you what the various subdirectories are and what code exists. The essential subdirectories are Control/ (where MINUIT looks for its control "cards"), Output/ (obvious) and /SN_hamuy and possibly other directories if you are using lightcurve files without covariance matrices.

AAGOTCHAS: If you have problems, read this file, or nobody will take the time to even listen to your questions. This file is a little out of date, but you still need to read it.

3. CODE ORGANIZATION

The main code (snmin02.pro) is about 1100 lines long. Nearly 500 are procedures devoted to command file readin and a number of safety checks -- seeing if the files really exist, etc. Another hundred lines before the spawn of the FORTRAN process are devoted to preparing the data, template, and K correction files for the FORTRAN code, as well as other setup tasks and error checking. The remaining half or so is mostly devoted to graphics and communicating with the user.

Half of the 430 lines of FORTRAN (many comments) consists of setup, ending with the MINUIT call. The rest is the routine called by MINUIT which calculates the function to be minimized, in this case CHISQ. followed by the subroutine that generates the parameter to be minimized, in this case chisq.

Eight (at last count) procedures are called for data preparation, graphics, etc.

There are many STOP's on errors, each of which describes the error and the module in which it was encountered. The one nonorderly stop, a return to snmin02 after a FORTRAN crash, is discussed below.

Details about these routines are given in AACONTENTS.

4. RUNNING snmin02

Calling snmin02

The sole argument of snmin02 is a string specifying the name of a command file which in turn specifies the LBNL name of the supernova, the filters, and the desired the options. Even in complicated cases it is usually well under 10 lines long. With the exception of the first line (the supernova name), the lines can be in any order, as nothing is decided until they are all read.
Command file overview

As an example, say you wanted to run lightcurves for a supernova called EarlScruggs. You might create a command file called EarlScruggs.command as follows:

EarlScruggs
v, rb, file= escruggsv.dat
u, b, kcorr= kcorr_scruggs_u_b.dat

Then from your "home" snmin02 directory,

IDL> snmin02,'EarlScruggs.command'

... and it all happens. In this case observer frame colors rb and b are fitted, using templates for restframe v and u colors. For v to rb the data file escruggsv.dat will override the default, but the default template and K corrections will be made. For u to b the K correction default is overridden but the default data file (a bad idea) and template will be used.

The simplest kind of command file is

sn9781.1.command:

sn9781
b,r

but all defaults (lightcurve data files, K corrections, lightcurve templates, default directories, etc.) can be overridden via keywords in the command file lines specifying filters or in special lines. In addition, default directories for these files can be defined. These options are discussed below.
SN data file SNe.dat or user-supplied equivalent

The code learns the name of the SN from the first line of the command file, but needs other information--redshift, IAU number, extinction, etc. This information is in a default file SNe.dat, which should be inspected for syntax. The first line (column headers) is ignored by the program. Some of the columns unused and historical. The first two (LBNL name, IAU name) are strings; z is in the 3rd column, etc. Format is not fixed.

You can either add your favorite SNe to the file in your space, or make a new one, whose name can be given in the command file.
Command files in detail

THIS SECTION NOT YET EDITED

If it's a high-z SN the default lightcurve directory is $DEEPHOME/roblight for ancient syntax reasons. Except for test purposes, users will ALWAYS override the default with other directions.

We usually have several observations at each of several observatories, so the input data are correlated. snmin02 expects a covariance matrix attached to the lightcurve file. If the SNe is not one of ours, a command file line will cause geration of a simple diagonal covariance matrix and rewrite the file in its standard form.

After all the setup, snmin02 spawns a call to the FORTRAN usercode for MINUIT, snmin02_FOR. It passes directions via a fixed-formatted input file you don't need to know about. What you DO need to know about is a control file, in /Control, which tells the code about the parameters to be fitted or held fixed. Normally the user will fool with the starting values and inital step sizes, but on the first call, when the file isn't there, a default file is written by snmin02.

In addition to defaults, there is lots of error checking and there are lots of STOP's when you screw up, All of them tell you the routine in which they are encountered. One mystery for the user: If the FORTRAN code crashes for some reason--bad input data or something--it returns to snmin02 without snmin02 knowing there was trouble. You usually learn about it when snmin02 can't read the file telling what happened. Look at /Output/snmin02_..results! ( is the number of lightcurves being fitted simultaneously.) But it's friendlier than Alex thinks.
Changing limits on the number of simultaneous lightcurves and the number of data points per lightcurve file

The maximum number of data points in a given lightcurve and the maximum number of colors is set by the file snmin02_FOR.size ("included" by snmin_FOR.for).

integer maxdat,maxcolors,maxpar,ndays parameter (maxdat=100,maxcolors=3,maxpar=2*maxcolors+2,ndays=331)

If you want to change maxdat or maxcolors, just change it/them in this one line and recompile snmin02_FOR.for using the g77 command from the comment early in the source code. IDL isn't so fussy, of course.

Don't screw with ndays, even though it's a parameter. In all of the code this number is more or less hardwired in, and a change would likely cause the end of civilization as we know it.

UNDEVELOPED FROM HERE ON

6. snmin02 command files - the details

This sections is split into several subsections III.a -- command file format : The file you pass as an argument to snmin02 III.b -- lightcurve format : Lightcurve data format III.c -- kcorrection format: Format for an optional user-supplied K correction III.d -- supernova file format : The format of an optional user-supplied snlist file (containing redshift, etc.) III.e -- template format : The format of an optional template file III.a : Command file format

This file controls how snmin02 is run. It determines which supernova lightcurve to fit, filters, etc etc.

III.a(1) Line 1 (mandatory): LBNL name of the supernova. This name will be looked up in a file with the format of SNe_hiz.dat, and must be found in some default or supplied file. Example: sn9821 III.a(2) Optional control lines: There are several different control options. They all take the form of TAG= VALUE. Order does not matter, except that those specifying directories must appear before a filters line expects them. You can set default subdirectories in which to find lightcurve data, templates, and/or kcorrections. For templates and kcorrections, the default is ./ , but for lcdir the fault is $DEEPHOME/roblight/ The directory name should be a complete path ending with a slash, e.g. /home/users/gerson/idl/ lcdir= lightcurvedirectory : Directory in which to look for lightcurves. kcdir= kcorrdirectory : Directory to look in for K correction file. tpldir = templatedirectory Other options are snlist= file : Used may specify the .dat file to read instead of SNe_hiz.dat or SNe_hamuy.dat. If not set, the SNe_hiz is searched followed by SNe_hamuy. ==> Format must be the same as that of SNe_hiz.dat nocov= YES (or NO) : Is covariance information missing from your (default is NO) lightcurves? If YES, then the program read_hamuy will generate a diagonal error matrix for use by snmin02. The following is probably unnecessary: gerson= YES : Set to use the Gerson conventions for filenames (default is NO) and input directories. This is intended to make it easy for Gerson to continue to work. gerson= YES overrides noconv. III.a(2) Filter specifications (at least one line required): Rest and observed filters, e.g. b,r, followed by optional keywords specifing user-supplied template, K corrections, lightcurve file, and stretch multiplier. snmin02 counts the filter specification lines to learn how many lightcurves are to be fit simultaneously. Entries are separated by commas. Case and spacing are ignored. Example 1: Default lightcurve file, template, K correction, and stretch multiplier: v,i Example 2: All possible keywords, which must be kept on one line: v, i, templ=my_v.template, kcorr= my_v_i.kcorr,s_mult=1.050,file=9728.dat (No space between keyword and "=", for the time being) Template, kcorr and lightcurve directories specified by control options, described above, will preface the kcorr and file names given in the filters line. The default directory is ./ Alternatively, the control option subdirectory specifications can be omitted and a complete path given. s_mult: The default s_mult = 1.000 means simply that the stretch is fitted relative to the template, which is a little subjective. There is no a priori reason this should be the same for templates for different colors. Nor, in the case of most high-z SNe, is there enough information for robust fits to stretches in more than one color. Hence the option exists to fit s_mult*stretch, where s_mult can be different for different colors. It's best to leave the best-determined lightcurve at the default 1.000. IV. Examples of command files for simultaneous fits to two lightcurves (generalization to one or three should be obvious!): (i) File One -- Simplest two lightcurve possibility (I find it convenient to call it sn9781.2.command) sn9781.2.command b,r v,i snmin02 will look for LBNL name 'sn9781' first in SNe_hiz.dat, and then in SNe_hamuy.dat, where it will be found. It will then expect to find sn92bk.out_b and sn92bk.out_v (for B and V bands, respectively) in the current directory. Since it is a Hamuy SN, it will generate a covariance matrix and otherwise "fix up" the lightcurve file. (ii) File Two -- Simple example with Gerson defaults sn92bk GERSON= yes b,b v,v This is the same as above except that the b band file will be named sn92bk.out, and the lightcurves will be expected in ~gerson/idl (iii) File Three -- Specifying files sn2001ay snlist=my.dat lcdir= /home/astro51/u/aconley/lightcurves/ b,b,file= sn2001ay.out_b_band v,v, file=sn2001ay.out_v Here the program will look for a b band lightcurve named /home/astro51/u/aconley/lightcurves/sn2001ay.out_b_band, and a v band file named /home/astro51/u/aconley/lightcurves/sn2001ay.out_v These MUST be roblight style files -- that is, they must have covariance matrix information. The .dat file that contains the redshift, etc. will be my.dat in the current directory. Note that specifying the full path for the b band file overrides the lcdir specification. (iv) File Four -- Specifying K correction and no covariance matrix sn2001ay datfile = /home/astro51/u/aconley/temp/my.dat NOCOV= YES kcdir= /home/astro51/u/aconley/kcorrs b,b,file=sn2001ay.out_b_band,kcorr=bcorr v,v Here the lightcurve files will be named sn2001ay.out_b_band in the b and sn2001ay.out_v in the v band. Both files must be in the current directory. The kcorrection file for the b band will be /home/astro51/u/aconley/kcorrs/bcorr, and the v band k correction will be generated by the program. The lightcurve files do not have covariance information. The .dat file is /home/astro51/u/aconley/temp/my.dat (v) File Five -- specifying your own template sn92bk b,b, templ= my_b_template.dat v,v This is just like example one in all resepects except that instead of using a default B template, my_b_template.dat is used. The default V template is used.