At the moment this help is the 'user guide' to molly and is quite long. Note that if you are accessing this help through html then some of the text may not be relevant, e.g. If you want a hard copy of it then type "help molly junk ; !lpr junk" molly is a monolithic program for handling 1D spectroscopic data written by Tom Marsh. Its prime purpose is for handling large numbers of similar spectra (e.g. time series spectroscopy), but it contains many of the standard operations used for normal spectrum analysis as well. It was written as a replacement for Keith Horne's RUBY, and has many similar functions, but it differs from RUBY in the way commands are called and is meant to be simpler for batch processing. Spectra in molly are stored in "slots" ranging from 1 to some number dependent upon the maximum size of spectrum the user wants. This number is normally quite large, 1500 say, but it depends upon the capacity of your machine. Command calling: (If this is your first time with molly it is worth reading this section in full.) Prompted input A command can be carried out by just typing its name. You will then be prompted for the various parameters. A '?' when responding to numerical parameters will type the allowable range for a parameter. The prompts are only one line long at most and so may be opaque on occasion. If so, look at the help on the command in question. Entering something outside the allowed range should get you out of the command (-1 for a slot is always a good one). This is the simplest way to start with molly and is the way to get a feel for it. Command line input Fairly soon you will get irritated at responding to prompts especially if you are only changing one or two of several. Once you have got to a point in a command where you are not going to change any more parameters, type a backslash "\" (a la FIGARO) and default values will be taken for the rest. Even better, once you start to remember the parameters for a command, you can put them all on the same line as the command, so that e.g. "plot 1 10" will plot spectra in slots 1 through 10. Again a backslash on the command line means take the default value of a parameter and for all following unspecified parameters. Therefore if "plot \ 8" followed "plot 2 10", it would use 2 as the first argument, while "plot \" after this will take 2 and 8. If you are unsure about one of many parameters, you can put a question mark "?" to force prompting. Therefore "plot \ ?" will prompt for the second parameter even though the default flag is set. Finally, a crude level of arithematic is supported for integer, real or double precision arguments, so that you can write e.g. 10++11 meaning 21 (--,**,// also possible). This is most useful for user defined commands and command files (see below). The doubling is to guard against confusion in an expression like 1.E-4++1.E-3 Shortening commands Command names can be shortened to their shortest non-ambiguous version. Thus "pl \" is the same as "plot \" if there are no other commands beginning with "pl". Commands are not case-sensitive. Specifying the spectra that you want Normally operations on blocks of slots are carried out. e.g. 1 through 10 as above. Suppose you want to plot slots 1,2,5, and 6 though. You can do this by specifying "plot 0 0", and you will then be prompted to specify the spectra you want. "plot \" will remember the same spectra as will most commands, but a few commands use the same subroutine (e.g. spline and polynomial fitting) in which case the spectra used by one will equally affect the other. If in doubt, specify the spectra fully for each command. This is most likely to be of importance in batch jobs. Concatenation Commands can be concatenated on one line using semicolons. e.g. "plot 1 10; write file 1 10 n" will plot slots 1 to 10 and then write them to a disc file (the "n" means a new file). Execution of concatenated commands stops if any individual command fails. User defined commands Concatenation is probably most useful when it comes to commands which you can define yourself with one-line definitions. e.g. psum == add $01 $01 $02 $02 1000; plot 1000 1000 \ Defines a command with one argument called "psum" which adds two spectra stores the result in slot 1000 (assuming it exists) and then plots it. When you type "psum 10 21" the string 10 will be substituted for $01 and 21 will be substituted for $02. The substitute strings run from $01 to $99. If you don't put the arguments on the line you will be prompted for them. However, you will be prompted for each one which negates the advantage of multiple substitutions. User defined commands can save alot of typing and time. For example say you have to load, say, the 11th and 12th spectra from a series of files called long_name_A_More, long_name_B_More, etc. Writing it out in full each time is a bore. However defining the command: ld == load long_name_$01_More A 2 11 you now need only type "ld A", "ld B" etc. (Note the use of A in the load command to add spectra after the highest numbered slot.) The arithematic facility allows you to do things like plot 2 spectra from a given start e.g. p2 == plot $01 $01++1. Command files Files of commands can be run by typing "@Par1 Par2 etc". The parameters are substituted for strings of the form $01 to $99 as for user defined commands. e.g. a file called 'hard' consists of: dev postscript_l plot $01 $02 \ close !lpr pgplot.ps dev last This changes the device to a postscript printer, plots a range of spectra $01 to $02, closes the plot, submits a shell command (see below) to print it to the default plot device (should be a postscript printer of course) and then switches back to the device being used before the postscript printer. This would be invoked as e.g. "@hard 10 12" to plot spectra 10 to 12. A '#' as the first character is a comment flag inside a command file. Shell commands (UNIX only) Commands can be issued to the shell by entering "! command" e.g. "!ls" to list the working directory. The routine forks a child process which dies once the command is completed. Therefore a command like "cd" will not effect a permanent change of directory (but may be useful as part of a more complex command). If you are an expert, shell commands can do useful things such as rearrange an ascii file dumped by molly with awk. Restrictions on command calling The options above are varied, but they are subject to some restrictions on what can be called from what. Here is a summary of what options can call what. ---> means "can call or invoke"; File1 and 2 refer to top level and second level command files. Similarly with concatenated(1) etc. Terminal input ---> File1, user definition, concatenated(1), shell, molly and user defined commands. File1 ---> File2, user definition, concatenated(1), shell, molly and user defined commands. File2 ---> user definition, concatenated(1), shell, molly and user defined commands Concatenated(1) command ---> shell, user defined and molly commands User defined command ---> concatenated(2) commands, shell and molly commands Concatenated(2) command ---> shell and molly commands Note restrictions which this implies such as : (a) user defined commands cannot call other user defined commands or command files (b) concatenated commands cannot call command files. (c) Only 2 levels of command file are allowed. Selection A powerful feature of molly is that spectra can be selected by header attributes. Thus it is possible to read from a file only those spectra with phases between 0 and 0.1 for instance, or with name e.g. "SS Cyg" etc. The header editor in molly allows for the inclusion of an arbitrary set of header items. Thus, one could measure the strength of a spectrum line, dump it out, edit the file to suit the header editor and set a new header parameter representing the strength of the line. One could then average only those spectra with the line having a certain strength or whatever. It should be noted that not all molly commands apply selection, since for some commands (e.g. adding a series of spectra) it could lead to incompatible numbers of spectra. Help on molly and its commands: Type "HELP " to get fuller information the operation and meaning of parameters for a given command. If you don't know the precise name of your command but know that it contains "pt" for example, then limited wildcard support is available. "HELP "*pt*" would list all such commands. If you are starting with molly then probably the best way to find your way around is to type "Help class" which lists classes into which molly commands have been loosely classified. This can make searching for a command much easier. For example if you want to input FIGARO spectra, then look in the "Input" class where all commands to do with input are listed. If you know the class, you can type "help class input" to go straight to a list of commands to do with input. Startup files or customising molly You may find yourself always starting molly with the same set of commands e.g. you redefine the plot device, the maximum spectrum length and change the plot axes every time. If so, then you may want to edit a startup file which is an ordinary command file (but with no parameters) containing those commands. e.g. startup.dat mxpix 2100 dev xwindows ax a m \ Then put SETENV MOLLY_START to point to this file in your .login. and "source .login" to get it going. Once set, this file will be run as part of the entry to molly. Concatenated commands or calls to other files are not possible in the startup file which is just a file of commands like any other. molly will also look for a local startup file called 'molly.com' in whichever directory you are working in. This allows you to define a set of commands/settings suited to a particular dataset. Internal storage of data: molly works with milliJansky internal flux units = 10**(-26) W m**-2 Hz**-1 but can accept a variety of units as input and for plotting. It retains three arrays for each spectrum which are raw counts and their errors and fluxes. If no flux cal has been applied, the flux array equals the counts array. The wavelength scale is stored as polynomial coefficients in order to save space. Headers: The molly headers are flexible, and almost any name and amount of header information can be stored, but for convenience some routines do assume standard names and data types for some header parameters. There are several others which are stored since they are useful. Many of these are set by the "HFIX" command, which should routinely be run as the first step in molly analysis. NB. One condition must be satisfied by header parameter names (you won't be allowed to set ones which violate this restriction in fact): for a given type (C,D,I,R) no header item's name can equal the first part of any other name, otherwise they cannot be reliably distinguished from one another. This could be altered, but at the cost of not being able to specify shortened forms (e.g. "UT" when you mean "UTC"). Standard names and types are as follows: (C=CHARACTER,D=DOUBLE PRECISION,I=INTEGER,R=REAL) R Dwell -- Exposure time in seconds. I Night -- Night number of observing run I Record -- Record or run number of exposure I Day -- Day of month I Month -- Month I Year -- Year D UTC -- UT at centre of exposure D HJD -- Heliocentric Julian date at centre of exposure D RJD -- Julian date at centre of exposure D Delay -- RJD-HJD (heliocentric correction) in days D Sidereal time -- Sidereal time of observation in hours. D Hour angle -- Hour angle of observation in hours D Airmass -- Airmass at centre of observation. D RA -- Right ascension of object (decimal hours) D Dec -- declination of object (decimal degrees) D Equinox -- Equinox of coordinates D Gal longitude -- Galactic longitude D Gal latitude -- Galactic latitude D Airmass -- Airmass at mid-point of observation. C Object -- Object name D Longitude -- Longitude of observing site (degrees) D Latitude -- Latitude of observing site (degrees) D Height -- height of site in metres C Site -- Name of site D Vearth -- Vtrue = Vobs - Vearth (km/s) The above are set by HFIX. In addition several phases can be specified. The orbital phase may be set by HFIX if an ephemeris is avaialble, otherwise use the command PHASE. All of the phases are treated in the same manner, but for convenience there are several specific names (spin, beat and hump) which can be associated with phases required for CV studies. You can invent your own name for a phase but it will not necessarily be averaged correctly when combining spectra. Three non-specific names (phase1, phase2 and phase3) are treated correctly. The command 'PHASE' will also store the ephemeris used to define the phase as Zero?, Period?, Pdot? where ? = O,S,B,H,1,2, or 3. D Orbital phase -- Orbital phase of a binary D Spin phase -- Spin phase (e.g. for intermediate polars) D Beat phase -- Beat phase again for intermediate polars D Hump phase -- Superhump phase for SU UMa stars D Phase1 -- User defined phases which are correctly D Phase2 -- treated by routines such as the average D Phase3 -- and phase bin commands. Associated routines: PCA runs a principal components analysis on molly spectra. It is not a molly command because of the large amount of storage it requires. TRANSLATE reads foreign molly files (i.e. written under different operating system) and dumps out to a normal molly file. Memory requirements Another level of customisation depends on the machine that you wish to run molly on. The number of spectra that can be stored depends upon parameter declarations contained in the file 'molly.pars'. The most important of these are: MXBUFF which sets the size of the data buffers (3 arrays each MXBUFF real numbers. Thus requires 12*MXBUFF bytes storage. e.g. My machine has a memory of 80 Mbytes, and I use MXBUFF=5000000 (it could probably be larger). MXSPEC sets the maximum number of spectra set by the space available for headers etc. MXWORK sets the maximum size of work buffers which should be more than the largest likely spectrum you will ever use. MXCHAR, MXDOUB, MXINTR, MXREAL sets maximum number of header items/spectrum Total space required by main arrays = 12*MXBUFF + MXWORK*(8*MXWD+4*MXWI+4*MXWL+4*MXWR) + MXSPEC*(24+8*MXARC+32*MXCHAR+24*MXDOUB+20*MXINTR+20*MXREAL)+ MXSLOT*(4*MXSI+4*MXSR) e.g. MXBUFF=3000000, MXSPEC=2000, MXWORK=4000, MXSLOT=2000, MXCHAR=10, MXDOUB=40, MXINTR=10, MXREAL=50, MXWD=6, MXWR=9, MXWI=1, MXWL=1, MXARC=20, MXSI=3, MXSR=1 Memory used = 36000000 + 368000 + 5328000 + 32000 = 41728000 This is a lower limit of course because there are many other small arrays and variables and there is the code itself. molly quirks Yes it certainly does have them. Most quirks are to do with the way it has been built which is largely determined by what I needed. This is most apparent in the tweaks that can be applied to get a fancy spectrum plot. e.g. you can change the aspect ratio of the spectum plots, and it would be nice for consistency if you could do that for every plot (e.g. arc drift with time) but not ever likely to be of any great use and so it is not implemented. There are also some routines that have sub-menus but they do not follow the same command style as the main level of molly. They should of course.. ****************************************************************************** Adding your own commands to molly Writing a subroutine: All molly commands with arguments are called as subroutines from the main program. The arguments are passed as a character string array generated from input from the user with a subroutine called 'control' (the latter fixes the way command files, concatenated commands etc are handled and you should look at it first if you want to alter the way molly operates). The easiest way to add your own routine is to copy an existing routine with a similar argument structure. Here is an example of a typical and fairly complete first part of a call (in this case to a command to make plots of header items) CALL HEDPLT(SPLIT, NSPLIT, MXSPLIT, COUNTS, & ERRORS, FLUX, MXBUFF, MXSPEC, MAXPX, NPIX, ARC, NARC, & MXARC, NMCHAR, NMDOUB, NMINTR, NMREAL, HDCHAR, HDDOUB, & HDINTR, HDREAL, NCHAR, NDOUB, NINTR, NREAL, MXCHAR, & MXDOUB, MXINTR, MXREAL, NMSCHAR, VSCHAR, NMSDOUB, VSDOUB, & NMSINTR, VSINTR, NMSREAL, VSREAL, NSCHAR, NSDOUB, NSINTR, & NSREAL, MXSCHAR, MXSDOUB, MXSINTR, MXSREAL, ..... etc) Fairly horrific yes, because part of philosphy of molly is to avoid COMMON blocks as far as possible (although some routines do use common blocks for simplicity -- look at mgasfit.f for example). However it is not so bad looked at bit by bit. SPLIT, NSPLIT, MXSPLIT These specify a CHARACTER array passed from the molly command interpreter. All commands with arguments should have this. In the array SPLIT(MXSPLIT) there are NSPLIT arguments from the command line (may=0). COUNTS, ERRORS, FLUX (REAL arrays MXBUFF long) The data arrays. 1D in molly to allow a variable size. They can be declared 2D inside programs e.g. COUNTS(MAXPIX,MXBUFF/MAXPX) MXBUFF, MXSPEC, MAXPX The size of the data arrays, the maximum number of spectra determined by header arrays and the maximum number of pixels/spec. Note that the maximum number of spectra possible is MIN(MXBUFF/MAXPX, MXSPEC) NPIX -- INTEGER array containing number of pixels/spectrum ARC, NARC, MXARC REAL*8 array ARC(MXARC,MXSPEC) contains arc scales for each spectrum INTEGER array NARC(MXSPEC) contains number of coefficients for each spectrum NMCHAR, NMDOUB, NMINTR, NMREAL C*16 arrays of names of header items for each spectrum (for C*32, R*8, I*4, R*4 types) HDCHAR, HDDOUB, HDINTR, HDREAL Arrays of values of header items for each spectrum (for C*32, R*8, I*4, R*4 types) NCHAR, NDOUB, NINTR, NREAL Arrays of numbers of header items for each spectrum MXCHAR, MXDOUB, MXINTR, MXREAL Maximum number of header items of each type for each spectrum NMSCHAR, VSCHAR, NMSDOUB, VSDOUB, NMSINTR, VSINTR, NMSREAL, VSREAL Names and limits of search parameters for selecting header values NSCHAR, NSDOUB, NSINTR, NSREAL Numbers of search parameters of each type MXSCHAR, MXSDOUB, MXSINTR, MXSREAL Maximum number of search parameters of each type. The search parameters are not always needed. Any other parameters can be added to the call. The most common are work arrays and list arrays, please use the standard ones defined in molly.dims. The best policy is always to borrow from the many examples available. The inputs inside the subroutine should be handled with INTR_IN, CHAR_IN, REAL_IN and DOUB_IN. Here is an example: MAXSPEC = MIN(MXBUFF/MAXPX, MXSPEC) ! Set maximum number of slots DEFAULT = .FALSE. ! Initialise for command input IFAIL = 0 ! If IFAIL.NE.0, INTR_IN etc return immediately NCOM = 0 ! Counter for command arguments. * * Get range/list of slots to plot. Each of the numeric input routines * includes an upper and lower limit for the parameter. * CALL INTR_IN('First slot for header plot', SPLIT, NSPLIT, &MXSPLIT, NCOM, DEFAULT, SLOT1, 0, MAXSPEC, IFAIL) IF(IFAIL.NE.0) GOTO 999 SLOT2 = MAX(SLOT1, SLOT2) CALL INTR_IN('Last slot for header plot', SPLIT, NSPLIT, &MXSPLIT, NCOM, DEFAULT, SLOT2, SLOT1, MAXSPEC, IFAIL) IF(IFAIL.NE.0) GOTO 999 IF(SLOT1.EQ.0 .AND. SLOT2.NE.0) THEN WRITE(*,*) 'Only 0,0 to get list option' GOTO 999 ELSE IF(SLOT1.EQ.0 .AND. SLOT2.EQ.0) THEN IF(DEFAULT .AND. NLIST.GT.0) THEN CALL SETSLOT(LIST, NLIST, MXLIST, SLOTS, NSLOTS, MXSLOTS) ELSE WRITE(*,*) 'Enter list of spectra for header plot' CALL GETLIS(LIST, NLIST, MXLIST, MAXSPEC, SLOTS, & NSLOTS, MXSLOTS) END IF IF(NSLOTS.EQ.0) GOTO 999 ELSE CALL SETLIS(SLOT1, SLOT2, LIST, NLIST, MXLIST, SLOTS, & NSLOTS, MXSLOTS) END IF * * Get name of header item for X axis. Character input does not have * any range of possible inputs. * CALL CHAR_IN('X axis header item', SPLIT, NSPLIT, &MXSPLIT, NCOM, DEFAULT, XNAME, IFAIL) Once you have the inputs, the rest of the subroutine is pretty much up to you, although it would be nice to keep number of extra subroutines to a minimum and there may always be a subroutine that does what you want. You should be aware of data access routines like GET_FLX and ANGST. You should also know how molly stores the data. For each pixel it keeps the number of counts, the uncertainty on the counts and the flux. Linearity is assumed in calculating the error on the flux given the counts error. The counts/flux ratio is an important number that must remain defined even if counts=flux=0. To do this, if COUNTS=0, then FLUX is set equal to the COUNTS/FLUX ratio. This is acounted for if you use the routines GET_FLX and GET_ERF to get the mJy flux and uncertainty on a mJy flux, and SET_FLX and SET_ERF to set the FLUX and ERRORS arrays given an mJy flux and its uncertainty. When a new command is added, you may have to increase the parameter MXCOM by 1 to allow space for it in the command buffers (it is probably best to compile and see if it encounters a problem on startup). Assuming that this is not a problem, you need to add an entry to the file 'command_defs' giving the command name, the one-line info line and the help classes the command falls into. If you find that none of the current help classes are suitable then you can add another to the start of 'command_defs' and you may have to increase MXCLASS by 1 inside molly to accomodate it. Next you need to insert your command in the large IF block which has one entry per command. Always add your command before the final ELSE which is needed in case 'command_defs' defines a command which does not actually exist. Finally, if you have created a new file, you will need to add its name to the Makefile to the list of MOLLY_OBJ object files. Other things: Do not use units 79 and 80 for I/O as they are used when reading command files. There are buffers of integer, real, and double precision types which can be passed to any routine if you need them. They have names like IWORK, RWORK and DWORK. Please use these rather than declaring your own work arrays inside subroutines as this keeps the storage requirements under control. Look inside molly.dims for a list of these. The dimensions are set by parameter statements at the start of molly.f.
This command belongs to the classes: miscellaneous , information