1. The Art of SUPERMONGO A Beginners Primer By Martin Altmann 17.11.2005

2. So, what is Supermongo for, what can it do, and what can't it do? ➔ make plots (2D), multiplots, allows quite sofisticated programming, very straightforward handling of data, easy to learn, fun ● is not a fitting program, 3D plots possible but difficult, is pay-ware! Advantages Disadvantages by Robert Lupton & Patricia Monger (Princeton)

3. Getting started....! ● computer with Supermongo installed! ● in the home directory a.sm file My.sm file: name Martin fonts /usr/astro/sm/lib/sm/fonts.bin help /usr/astro/sm/lib/sm/help/ history 80 history_file.smhist #+graphcap /usr/sm/lib/lib/sm/graphcap.local filecap /usr/astro/sm/lib/sm/filecap +graphcap /usr/astro/sm/lib/sm/graphcap.local graphcap /home/maltmann/SMres/graphcap macro /home/maltmann/SMres/macro/ #macro /usr/astro/sm/lib/sm/macro/ save_file smongo.sav temp_dir /tmp/ term xterm printer postscript prompt sado-maso> device X11 file_type fits TeX_strings 1 A more basic.sm file name Benedict XVI history 80 history file.smhist prompt super pope device X11 file_type fits Tex_strings 1

4. Getting started....! /vat/JP_II>sm Hello Benedict XVI, please give me a command super pope> So, in your xterm you type “sm”, and then this happens: SM... and this, the graphics plot device appears (for some reason it is unfortunately grey at Calan, making plots harder to see on the screen. BTW: quit exits sm, you get your normal xterm prompt and the black window vanishes into thin air!

5. A simple plot: We need: --- a data file, e.g. with two columns of data. # x y 0 0 0.1 0.01 0.2 0.04 0.3 0.09 0.4 0.16 0.5 0.25 0.7 0.49 0.9 0.81 1 1 1.5 2.25 2 4 2.5 6.25 3 9 4 16 5 25 super pope> data square.dat super pope> lines 0 0 # lines starting with # will be ignored! 0 0 means read all readable lines super pope> read x 1 super pope> read y 2 super pope> window 1 1 1 1 super pope> limits 0 5 0 25 #limits x y will do the same trick! super pope> box 1 2 0 0 super pope> points x y super pope> connect x y super pope> xlabel x [cm] super pope> ylabel y [m/s] #any text

6. A simple plot: VOILA, here it is! Not exactly stylish, but we're beginners. Lets first understand, what we did, okay???... and then we can see how to improve this result!!!!

7. A simple plot & the commands: ● data filename: names the file that contains the data ● lines n1 n2: gives the lines to read from ● 0 0: read all uncommented lines, comment sign is '#' ● read vec n: read command, reads the column chosen by the number ● i.e. 2 means the second column ● an.s attached to the number signals string type data ● read will stop reading as soon as something incompatible pops up ● empty line will get * as value (it might even stop afterwards) ● window x1 y1 x2 y2: specifies the partition of the window (1 st two numbers), and choses the window the following will be plotted in (2 nd set of two numbers) ● is one or both of the 1 st numbers negative the graphs will be joined together without space

8. A simple plot & the commands: ● limits x1 x2 y1 y2: states the limits of the graph, can be either given explicitely or by the names we have assigned to the columns (then it will pick the extremes) (Omitting “limits” does the same) ● box n1 n2 n3 n4: box draws a box, the numbers specify for each of the four sides how it should look like ● 0: ticks but no numbers ● 1: ticks and numbers parallel to line ● 2: ticks and numbers orthogonal to line ● 3: line w/o ticks or numbers ● 4: no line, no ticks, no numbers! ● default is 1 2 0 0

9. A simple plot & the commands: ● points x y: draws x vs. y as points (little crosses, points can be altered) ● connect x y connects x vs. y with straight lines (caveat: data should be in correct order, since sm connects from neighbour to neighbour as in the file!) ● x/ylabel text: labels the x/y axis with any given text (many of the LaTeX symbols can also be used here) So now we know how to make a simple plot and what all those different commands mean, but I think we can make a much nicer plot --- right now it is not that impressive is it, and I would like jucier symbols and what about some colour????

10. Beefing up the plot! ● expand r1: regulates the size of text and symbols (such as those the denote points in a plot), including the axis labels, btw. expand 1.001 (or any number other than 1 forces sm to use TeX fonts), line widths will NOT be affected! ● ptype n1 n2: allows to choose a point type ● the first number defines the number of sides ● the second whether the point symbol will be open (0), skeletal (1), starred (2) or filled (3) ● example ptype 6 3 means filled hexagons, ptype 1 1 (or 1 anything means dots) Some new commands:

11. Beefing up the plot! ● ctype expr.: Chooses the colour, expr. can either be a number or one of the following: default, black, white, red, green, blue, magenta, cyan, yellow (for advanced users, one can define & access more colours) ● lweight n1: changes the line width, also affects symbols and boxes and text! ● ltype n1: specifies a line type ● 0=solid, 1=dot, 2=short dash, 3=long dash, 4=dot – short dash, 5=dot – long dash, 6=short dash – long dash, 10=erase lines ● BTW: erase deletes everything! ● help command: invokes help function

12. Some more useful commands ● relocate x y: tells the “graphics cursor” to relocate to the position x y in the plot ● usually refers to user coordinates, it is also possible to relocate to fixed system coordinates (relocate (x) (y)) ● draw x y: draw a line from current position x0 y0 to x y, usually first use relocate! see also ltype, lweight ● label text: write text anywhere in the plot (position previously defined by relocate) ● angle value: all following labels, shades etc. are rotated by the value (in °) assigned to angle (remember to change angle back to 0 afterwards (all axis labels e.g. will else be rotated))

13. Some more useful commands ● errorbar x y expr. n1: works like points but draws errorbars (given by expr.) n1 (1-4) indicate the direction of the errorbar. error_x/y draw symmetrical errorbars in x/y, logerr for use in logarithmic plots ● ticksize nx1 nx2 ny1 ny2: defines the ticks/number spacing on the axes. nx1/ny1 give the space of the small ticks, and nx2/ny2 the large ticks/numbers. negative nx1/ny1 assume log plots, default: ticksize 0 0 0 0 ● notation n1 n2 n3 n4: define exponential range outside of which numerical labels are given in exp. form, default: notation -4 4 -4 4

14. Some more useful commands ● histogram x hx: draws a histogram (how to make the histogram (hx): later, just a little patience) ● shade histogram n1 x hx: shades a histogram with lines, spaced n1 apart (angle comes in handy here! Usually histogram and shade histogram are used together) ● and some other more specialised commands such as circle, spline, etc..... So now we know how to make plots of quite some sophistication - after all it is better to have a bad result presented in a nice form than a good one presented sloppily (see many commercials). But before I present a plot with bells and wistles......do we really need to hack in all that stuff over and over again to make a plot?

15. ...of course not! Macros ● A macro is a file (script) in which all commands to e.g. generate a plot are listed sequentially and are executed by sm in the order of appearance. ● more than one macro may be stored in one file, certain limits on file length apply? (haven't hit one lately) ● macros may be called from a macro (in same file or another file) ● after execution of the macro (as in most script based programming languages) the parameters are not defaulted (reinitialised), i.e. sm does not know where a command comes from, file or

16. Structure: ● 1st line: macroname (string which denotes this particular macro), starting at the beginning of the line) ● All other commands must start on the 6th (or later) character of the line ● comments with # on first position will be echoed to ● comments with # on later position will not be echoed Macros : the basic structure ● name of the file: irrelevant (but use.mac,.sm,.m or similar to keep macro files apart from others) – Do not use +*#'”$-/(){[]}><, etc., _. allowed macroname 1 st command 2 nd command 3 rd command 4 th command 5 th command etc. etc. nextmacro 1 st command 2 nd command # commented line

17. Macros : running them! ● Output (on, depending on verbosity level, can be adjusted): some commented lines (# on pos. 1), everything after echo (later), print (I said, later!!!), reading progress, warnings (log of negative numbers, different number of elements in vectors, errors (syntax, or otherwise, causing the macro to abort!) super pope> macro read st_peter.m #reading the file super pope> urbi_et_orbi #executing the macro super pope> macro read st_peter.m urbi_et_orbi # both commands in one line; better because only if # file containing the macro is reread after any # changes, sm will know about them! super pope> macro read st_peter.m padre_hurtado # reading another macro from the same file

18. And here we are, a plot with all kinds of Bells and Whistles!!! Nice plot, but how can I make a copy of it??? or even a PS file?... No problem! (well almost)

19. Making Hardcopies and EPS-files ● sm has a so called graphcap file. This file defines the output possibilities. It is possible to add an additional customised local graphcap file for more options including common bitmap formats ● Basic output devices: X11 (screen, usually w on b), postscript (directly to the printer, on Calan try to find out which one first), postencap (to an EPS file – recommended output) ● Commands: super pope> dev postencap test.ps super pope> macro read st_peter.m st_peter super pope> dev x11 super pope> dev postscript #w/o filename super pope>.... super pope> dev :SY@: :OF@: postencap... #CALAN

20. Looking deeper... and programming ● Supermongo is a powerful graphics package ● but it can do more.... ●... it is almost a full blown programming language with a readily available graphical output – no muddling with graphics libraries etc. ! So now we're able to make decent plots, lets look into these additional possibilities. To use it for programming we need to take a deeper look into how sm actually works. First we'll look at the two data types of sm, i.e. the concept of VARIABLES and VECTORS

21. Variables & Vectors ● Variables: are one-dimensional data used for interaction with the user, loops, etc. they can also be used for calculations, but vectors are better at that. defining variables: define varname (value) (parentheses necessary if value is more than a number) calling variables (contents): $varname, e.g. echo $varname will give value on calculating with/redefining variables: define i ($i+1) define a 2 define z (lg(z)+a**i) defining variables through : define a ? {prompt} define input_file ? {hey, gimme the freakin' file}

22. Variables & Vectors ● Vectors: are the prime data type for calculations. They are n-dimensional lists of numbers or strings. defining vectors: set vector = value (or expression) read vec 1 (yes, the old read command) set x=0,1000,1 (meaning: create a vector that goes from 0 to 1000 with increments of 1) set $a= x (assign a vector to the contents of a variable – extremely useful) calling vectors: in equations: vecname, without “$” output on screen/in a file: print {x} or print, the print command is formattable: print + $outfile '%7.3f\n' {x} (meaning:attach to an existing output file (+) the vector x in the format real 7 digits overall, and 3 behind the point, \n means newline)

23. Variables & Vectors ● Vectors: some useful commands dimen(x) gives the number of elements in the vector (its dimension) x[$i] refers to the (i+1) th element in the vector (note that the elements start counting at 0 to N-1, if N is the dimension) sum(x) gives the sum of all elements in the vector, vector needs to be of type real or integer. sort {x y z a} sorts the first vector (x) from small to large values and rearranges all subsequent vectors according to the first one. Up to 10 vectors can be sorted this way.

24. Variables & Vectors Vectors: calculating (4 basic types of arithmetic) x,y are vectors of dimension N, p has dimension 1, a is a variable Adding: x+y=(x0+y0, x1+y1,..., xn+yn), as in vector arithmetic but: x+p=(x0+p, x1+p,..., xn+p) unlike v.a. x+$a=(x0+$a,..., xn+$a) Vectors need to be either of the same dimension or one N and one 1, vectors of dimension N1 and N2 (both >1) do not mix! Subtracting: x-y=(x0-y0, x1-y1,..., xn-yn), as in vector arithmetic see Adding Multiplying: x*y=(x0*y0, x1*y1,..., xn*yn), unlike vector artihmetic but: x*p, x*$a are like v.a., see adding Division: x/y=(x0/y0, x1/y1,..., xn/yn) x/$a, x/p, see Multiplying/Adding

25. Variables & Vectors Vectors: calculating (advanced operations) All thinkable mathematical operations can be performed on vectors (many of them on variables too). There are also some operations for strings, such as string(x), index(x,'char') or substring, -expr Change sign ABS(expr) Absolute value ACOS(expr) Arccosine ASIN(expr) Arcsine ATAN(expr) Arctangent COS(expr) Cosine CTYPE() Return CTYPEs DIMEN(vector) Dimension of a vector EXP(expr) Exponential GAMMA(expr,expr) Incomplete gamma fn INT(expr) Integral part LG(expr) Log_10 LN(expr) Log_e RANDOM(s_expr) Random numbers SIN(expr) Sine SQRT(expr) Square root STRING(expr) Convert to a string SUM(expr) Sum_i expr_i TAN(expr) Tangent VECTOR[expr] Elements of an array ( expr ) Raise precedence Binary: expr + expr Add expr - expr Subtract expr CONCAT expr Concatenate expr * expr Multiply expr / expr Divide expr ** expr Exponentiate expr & expr Bitwise AND expr | expr Bitwise OR expr % expr Modulus ATAN2(expr_y,expr_x) Atan2

26. Variables & Vectors Vectors: calculating (special ops & comments) PI: is pi, i.e. 3,1416.... All arc functions assume arc measure (rad) not degrees (deg), degrees have to be transformed to rad first Constructing a histogram: y is a vector with values between -100 and 100. set x=-100,100,10 set hy=histogram(y:x) sorts the values of y into the bins defined by x histogram x hy etc. plotting the histogram

27. Branches & loops Branch: the if clause: if (condition==true){do this} (simple if statement) if (condition==true){ do this and that and also this } else { (i.e. if not true) do this other thing and this one as well } full if else statement The if clause is similar/identical to the if clause in most programming languages!

28. Branches & loops Loop: the while loop: while {condition==true}{do this stuff and also this and if you feel like it also this } typical usage: define N (dimen(x) define i 0 while {$i<$N}{commands define i ($i+1) !dont forget!!! } Again the while loop exists in most other languages

29. Branches & loops Loop: the do loop: do variable=start,end,[increment (default=1]{do this stuff and also this and if you feel like it also this } Again the do loop exists in most other languages the break command: exits a while loop prematurely – only works with while not with do testing conditions: >, =,==,!= (“=” alone will result in error message)

30. The finale I have given an overview of Supermongo that is far from complete, but it will give you enough input to be able to do plots and to start writing macros yourself. Now.... practise, practise, practise, soon you'll be able to write some very sophisticated stuff. For most commands I have shown there are more options, that you might want to explore in time. Now it was paramount to give a straightforward approuch focussing on the bare essentials. The most important command for some time will be help. S o have fun playing with and using Supermongo