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 (trm@phastr.soton.ac.uk). 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 "@<FILE> 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 <command>" 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 MOL_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 generate
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 related 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 pointer to the MOL_HLP file to show it
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.
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 and information .