molly


 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 'commannd_defs' defines a command which does not actually
 exist. Finally you need to add a line in the Makefile where it generates
 the help_pointers file to show molly where to look for help on your command 
 (typically the start of the subroutine itself since this increases the 
 chances of the help files being up to date by about 1000 times). molly help 
 prints out lines delimited at the start and end by records of the form 
 "*Command" where Command is the name of a command. molly help will then 
 print out all lines in between such markers with the first character removed 
 to allow the help file to be part of a FORTRAN program. In this way you can 
 put the help inside your subroutine. As usual, see the many examples of how
 to do this.

 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


Tom Marsh, Warwick