MGL script language

Reference manual for v.1.10

Alexey Balakin, 2007-2009

Contents

  1. Introduction
  2. Graphics setup
  3. Scaling, moving and rotating
  4. Axis and Colorbar
  5. Primitive drawing functions
  6. 1d plotting commands
  7. 2d plotting commands
  8. 3d plotting commands
  9. Dual plotting commands
  10. Other plotting function
  11. Program flow commands
  12. Data creation and file I/O
  13. New data extraction (forming)
  14. Data handling
  15. Nonlinear fitting
  16. Color specification
  17. Line style specification
  18. Color scheme specification
  19. Text and font specification
  20. Formulas and functions
  21. Command options
  22. Suffixes for variable

1. Introduction

MathGL library supports (from version 1.3) the simplest scripts for data handling and plotting. These scripts can be used independently (with the help of mgl2png, mgl2eps, mgl2svg programs and others) or in the frame of the library using.

MGL script language is rather simple. Each string is a command. First word of string is the name of command. Other words are command arguments. Command may have up to 1000 arguments (at least for now). Words are separated from each other by space or tabulation symbol. The upper or lower case of words is suficient, i.e. variables a and A are different variables. Symbol # starts the comment (all characters after # will be ignored). The exception is situation when # is a part of some string. Also options can be specified at the end of string (after symbol ';', see Sec. Command options). Symbol ':' starts new command (like new line character) if it is not placed inside a string or inside brackets.

If string contain references to external parameters (substrings "$0", "$1" ... "$9") then before execution the values of parameter will be substituted instaed of reference. It allows to use the same MGL script for different parameters (filenames, paths, condition and so on).

Argument can be a string, a variable name or a number.

Before the first using all variables must bedefined with the help of commands new, var, list, copy or read.

All MGL commands can be divided on several groups. I will use the following notation for a command description: command names are bold, strings are denoted by commas, variable names are italic, numbers are typewriter. Optional arguments are placed in square brackets and default values for them are shown. Detailed description of color, line styles, color schemes, font types , TeX-like symbols and formulas can be found in corresponding section.

[contents]

2. Graphics setup

Commands in this group influences on overall graphics appearance. So all of them should placed before any actual plotting commands.

2.1. Transparency

There are several commands for setup transparency. The general command is alpha which switch on/off the transparency for overall plot. It influence only for graphics which created after alpha call. Command alphadef specify the default value of alpha-channel. You may switch off transparency of selected plot by command transparent. Finally, command transptype set the kind of transparency.

2.2. Lighting

There are several commands for setup lighting. The general command is light which switch on/off the lighting for overall plot. It influence only for graphics which created after light call. You can specify up to 10 independent light sources. By default only one light source is active. It is source number 0 with white color, located at top of the plot.

2.3. Fog

2.4. Default sizes

These commands control the default (initial) values for most graphics parameters including sizes of markers, arrows, linewidth and so on. As any other settings these ones will influence only on plots created after the settings change.

2.5. Zooming

These commands control the overall zooming of the picture or the sub-picture. Normally you can use these variables and commands for removing "white" spaces around a plot.

2.6. Cutting

These commands set the condition when the points are excluded (cutted) from the drawing.

2.7. Other settings

2.8. Axis settings

These large set of commands control how the axis and ticks will be drawn. Note that there is 3-step transformation of data coordinates are performed. Firstly, coordinates are projected and cutting is applied, after it transformation formulas are applied, and finally the data was normalized in bounding box. For drawing functions see axis and colorbar.
[contents]

3. Scaling, moving and rotating

These command define the position of plot on the picture and its properties. There is a curtain order of calling of these functions for the better plot view. The first one should be subplot or inplot for specifying of the place. After it a rotate and aspect. And finally any other plotting function may be called. Alternatevely you can use columnplot for position plots in the column one by another without gap between plot axis (bounding boxes).

[contents]

4. Axis functions

Axis functions control and draw the axes. There is the twofold axis representation in MGL. First one consists in normalizing of the data point coordinates in box specified in axis command. If cut is on then the outer point is omitted otherwise it is projected to bounding box. Also the points are omitted if they are inside the box specified in cut command. After it transformation formulas 'fx', 'fy', 'fz' are applied to the data point. Finally, the data point is plotted by one of functions.
[contents]

5. Primitive drawing functions

These functions draw some simple objects like line, point, sphere, drop, cone and so on. Also the text printing, plots by formula and legend drawing is included in this section.

5.1. Lines, curves and figures

These functions draw some simple objects like line, point, sphere, drop, cone and so on.

5.2. Text printing

These commands draw the text. There are commands for drawing text in arbitrary place, in arbitrary direction and along arbitrary curve. It is possible to use arbitrary font-faces and parse many TeX commands. The Unicode text is supported. The size argument control the size of text: if positive it give the value, if negative it give the value relative to defined by font command. For more details see Sec. Text and font specification.

5.2. Text printing

These commands draw legend to the graph (useful for 1D plotting (MGL)). Legend entry is a pair of strings: one for style of the line, another one with description text (with included LaTeX parsing). The array of string are accumulated first to the internal arrays (by command addlegend) and are plotted later. The position of the legend can be selected automatic or manually. Parameters 'fnt' and size specify the font style and size. Parameter llen set the relative width of the line sample and the text indent (default value is 0.1). If line style string for entry is empty then the corresponding text is printed without indent.

5.3. Plots by formula

These commands plots curves and surfaces defined by textual formulas. The actual number of points for curves is increased near singularities.
[contents]

6. 1d plotting commands

These functions perform plotting of 1D data. 1D means that the data depend on the only 1 parameter (index), like parametric curve {x(i),y(i),z(i)}, i=0...n-1. Most of commands have similar interface. There are version for drawing in 3d space or in plain. For the last one there is a possibility to use single data array.

If command allows to use parametric curve definition (depends on 2 or 3 data arrays) then its minor dimensions should be equal. If one of the arrays is 2d array (matrix) then the curves will be drawn for each of rows. At this the other arrays can be one-dimensional. If array xdat is not specified then its an automatic array is used with values equidistantly distributed along x. Also the zval (the default is at the bottom of the bounding box) is used instead zdat if last is not specified.

Optional string parameter 'stl' sets the style and color of line and marks for all 1d plotting commands. By default ('stl'='') solid line with next color from palette is used. See also color and line styles specification.

[contents]

2d plotting commands

These functions perform plotting of 2D data. 2D means that the data depend on 2 independent parameter (indexes). Most of commands have similar interface. There are 2 versions for drawing of the surface of single data array and for parametrically specified surface.

If command allows to use parametric surface definition (depends on 3 data arrays xdat, ydat, zdat) then its minor dimensions should be equal. At this arrays xdat, ydat can be one-dimensional. If arrays xdat, ydat are not specified then its an automatic arrays are used with values equidistantly distributed along x and y. If zdat is 3d array then the surfaces will be drawn for each of slices.

Optional string parameter 'stl' sets the color scheme. Previous color scheme is used by default. See also color and color schemes specification.

contents

8. 3d plotting commands

These functions perform plotting of 3D data. 3D means that the data depended on 3 independent parameter (indexes). Most of commands have similar interface. There are 2 versions for drawing single data array and for parametrically specified data.

If command allows to use parametric surface definition (depends on 4 data arrays xdat, ydat, zdat, adat) then its minor dimensions should be equal. At this arrays xdat, ydat, zdat can be one-dimensional. If arrays xdat, ydat, zdat are not specified then its an automatic arrays are used with values equidistantly distributed along x, y and z.

Optional string parameter 'stl' sets the color scheme. Previous color scheme is used by default. See also color and color schemes specification.

[contents]

9. Dual plotting commands

These plotting functions draw two (or three) data arrays simultaneously in different forms: as coloring or transparing, vector field, flow chart or mapping. There are 2 versions for drawing single data array and for parametrically specified data.

If the command allows to use parametric surface definition (depends on 4, 5 or 6 data arrays xdat, ydat, zdat, adat, bdat, cdat) then its minor dimensions should be equal. At this arrays xdat, ydat, zdat can be one-dimensional. The dimensions of other data arrays (adat, bdat, cdat and so on) must be equal. If arrays xdat, ydat, zdat are not specified then its an automatic arrays are used with values equidistantly distributed along x, y and z.

Optional string parameter 'stl' sets the color scheme. Previous color scheme is used by default. See also color and color schemes specification.

Commands for general dual arrays:

Commands for vector fields:
contents

10. Other plotting function

These plotting commands draw density plot or contour lines in x, y, or z plain. If dat is 3-dimensional data array then interpolation to a given sval is performed. These functions are useful for creating projections of the 3D data array to the bounding box. Optional string parameter 'stl' sets the color scheme. Optional parameter val sets the value of coordiante on the slice. Previous color scheme and axis origin are used by default. See also color and color schemes specification. These plotting commands draw rather rare plots like crust or dots which is arbitrary placed in space, or surface of triangles. If several data arrays for coordinates are specified then they should have the same size. These functions are useful for creating plots of unsorted or user-defined data arrays. Optional string parameter 'stl' sets the color scheme. Previous color scheme is used by default. See also color and color schemes specification.
contents

10. Program flow commands

These commands control program flow, like, conditions, cycles, define script arguments and so on.
contents

11. Data creation and file I/O

These commands create new variable with specified name. Note, that if a variable with the same name exists then it will be overwritten. The only exception is the command delete which deletes specified variable and makes its memory free.
[contents]

12. New data extraction (forming)

This data write resulting data array in some other variable. Note, that if a variable with the same name exists then it will be overwritten.
[contents]

13. Data handling

13.1. Information

13.2. Data filling

13.3. Rearrange data

13.4. Commands on direction

13.5. Operators

[contents]

14. Nonlinear fitting

These commands fit data to formula. Fitting goal is to find formula parameters for the best fit of the data points, i.e. to minimize the sum Σi (f(xi, yi, zi)-ai)2/si2. At this, the approximation function f can depend only on one argument x (1D case), on two arguments x, y (2D case) and on three arguments x, y, z (3D case). The function f also may depend on parameters. Normally the list of fitted parameters is specified by 'var' string (like, 'abcd'). Optional data ini set initial values for coefficients (by default zero values are used).
These commands fit and fits do not draw obtained data themselves. They just fill the data out by formula f with found coefficients. At this, the x, y, z coordinates in the formula are equidistantly distributed in bounding box. Number of points in out is selected as maximal value of out size or 100. Also you may print the last formula with found coefficients by putsfit command.
[contents]

15. Color specification

MGL script have the only way for color specification. It is a symbols (characters) wkrgbcymhRGBCYMHW each of them define unique color. Normally capital letter gives darker color than lowercase one. The full list of characters is: k – black, rred, Rdark red, ggreen, Gdark green, bblue, Bdark blue, ccyan, Cdark cyan, mmagenta, Mdark magenta, yyellow, Ydark yellow (gold), hgray, Hdark gray, w – white, Wbright gray, lgreen-blue, Ldark green-blue, egreen-yellow, Edark green-yellow, nsky-blue, Ndark sky-blue, ublue-violet, Udark blue-violet, ppurple, Pdark purple, qorange, Qdark orange (brown).

[contents]

16. Line style specification

MGL script use strings for specifying the parameters of lines and marks. The string may contain specification for color (wkrgbcymhRGBCYMHW), dashing style (-|;:ji or space), width (0123456789) and marks (#o+xsd.^v). If one of type of information is omitted then the previous values are used. If string is empty then solid line with next color from palette is used. By default palette contain following colors: dark gray 'H', blue 'b', green 'g', red 'r', cyan 'c', magenta 'm', yellow 'y', gray 'h', blue-green 'l', sky-blue 'n', orange 'q', yellow-green 'e', blue-violet 'u', purple 'p'.

The color types are defined by symbols as described in Sec. 14.

Dashing styles has the following meaning: space – no line (usable for plotting only marks), – solid line (■■■■■■■■■■■■■■■■), | – dashed line (■■■■■■■■□□□□□□□□), ; – small dashed line (■■■■□□□□■■■■□□□□), : – dotted line (■□□□■□□□■□□□■□□□), j – dash-dotted line (■■■■■■■□□□□■□□□□), i – small dash-dotted line (■■■□□■□□■■■□□■□□).

Marker types are: o – circle, + – cross, x – skew cross, s - square, d - rhomb (or diamond), . – point, ^ – triangle up, v – triangle down. If string contain # symbol then solid markers are used.

One may specify to draw special symbol (an arrow) at beginning and at the end of a line. It is possible if specification string contain one of following symbols: A – usual arrow, V – inner arrow, I – transverse hachures (or stop mark), K – arrow with hachures (or dimension mark), T – triangle, S – square, D – rhomb, O – circle, _ – nothing (it is default). At this there is a rule: first symbol specify the arrow at end of line, second symbol specify the arrow at beginning of line. For example, 'r-A' define red solid line with usual arrow at the end, 'b-AI' defien blue dash line with arrow at the end and with hachures at start, '-_O' define the line with current style and with circle at start. This styles are applicable also for any other plots (for example, plot).

contents

17. Color scheme specification

The color map scheme is used for coloring surfaces and other and is specified by the string. String may contain several characters which are color id (see Sec. 14) or character 'd' which denotes interpolation by 3d position instead of coloring by amplitude.

For coloring by amplitude (most common) the final color is linear interpolation of color array. The color array is constructed from string ids. The argument is the amplitude normalized between color range (see caxis, crange). For example, string containing 4 characters 'bcyr' corresponds to colorbar from blue (lowest value) through cyan (next value) through yellow (next value) to red (highest value). String 'kw' corresponds to colorbar from black (lowest value) to white (highest value). String 'm' corresponds to simple magenta color. If color scheme specification contain symbol '|' then the colors are used as is (without interpolation) else the intermediate colors are found as result of linear interpolation (this is default).

There are several useful combination. String 'kw' corresponds to simplest gray color scheme when higher values are brighter. String 'wk' presents inverse gray color scheme when higher value is darker. Strings "kRryw", 'kGgw', 'kBbcw' present the well-known "hot", "summer" and "winter" color schemes. Strings 'BbwrR' and 'bBkRr' allow to view bicolor figure on white or black background when negative values are blue and positive values are red. String 'BbcyrR' gives color scheme similar to well-known "jet" color scheme.

Examples of the most popular color schemes
kw kw.png wk wk.png kHCcw kHCcw.png
kRryw kRryw.png kGgew kGgew.png kBbcw kBbcw.png
BbwrR BbwrR.png BbwgG BbwgG.png GgwmM GgwmM.png
bcwyr bcwyr.png QqwcC QqwcC.png CcwyY CcwyY.png
BbcyrR BbcyrR.png BbcwyrRBbcwyrR.png bwr bwr.png
BbcyrR| sharp.png bcyr bcyr.png bgr bgr.png

For coloring by coordinate the final color is determined by position of point in 3d space and is calculated by formula c=x*c[1] + y*c[2] + z*c[3]. Herec[1], c[2], c[3] are the first three elements of color array; x, y, z are normalized coordinates of the point. This type of coloring is useful for isosurface plot when color may show the exact position of peace of surface. For example, try surf3 a 'bgrd' for some tensor data a.

[contents]

18. Text and font specification

Text style is specified by the string which may contain several characters of font (ribwou) and/or align (LRC) specifications. The string also may contatin the color id characters wkrgbcymhRGBCYMHW (see Sec. 14) after the symbol :. For example, 'biC:b' sets the bold italic font style with aligning at the center and with blue color.

The font types are: r – roman font, i – italic style, b – bold style. By default roman roman font is used. The align types are: L – align left (default), C – align center, R – align right. Additional font effects are: w – wired, o – overlined, u – underlined. Also a parsing of the LaTeX-like syntax is provided.

The font size can be defined explicitly (if size>0) or relatively the base font size as |size|*fontsize (if size<0). The value size=0 specifies that the string will not be printed. The base font size is measured in internal "MathGL" units.

Parsing of the string to special (TeX-like) commands is switched on by default. There are commands for the font style changing inside the string: \a or \overline – overlined, \b or \textbf – bold, \i or \textit – italic, \r or \textrm – roman (throw any other attributes), \u or \underline – underlined, \w or \wire – wired, \big – bigger size, @ – smaller size. The lower and upper indexes are specified by '_' and '^' symbols. At this the changed font style is applied only on next symbol or symbols in braces {}. The text in braces {} are treated as single symbol that allow one to print the index of index. For example, compare the strings 'sin (x^{2^3})' and 'sin (x^2^3)'. You may also change text color inside string by command #? or by \color? where '?' is symbolic id of the color. For example, words 'Blue' and 'red' will be colored in the string '#b{Blue} and \colorr{red} text' and this string will be printed as "Blue and red text".

TeX parser recognize most of commands for special TeX or AMSTeX symbols (see below), the commands for font style changing (\textrm, \textbf, \textit, \overline, \underline), accents (\hat, \tilde, \dot, \ddot, \acute, \check, \grave, \bar, \breve), roots (\sqrt, \sqrt3, \sqrt4), fractions (\frac) and "stacked" text (\overset, \underset, \stack, \stackr, \stackl). The full list contain approximately 2000 commands. Note that first space symbol after the command is ignored, but second one is printed as normal symbol (space). For example, the following strings produce the same result: '\tilde{a}'; '\tilde a'; '\tilde{}a'.

There are some differences from LaTeX standard parsing:

The Greek letters are recognizable special symbols: α – \alpha, β – \beta, γ – \gamma, δ – \delta, ε – \epsilon, η – \eta, ι – \iota, χ – \chi, κ – \kappa, λ – \lambda, μ – \mu, ν – \nu, o – \o, ω – \omega, ϕ – \phi, π – \pi, ψ – \psi, ρ – \rho, σ – \sigma, θ – \theta, τ – \tau, υ – \upsilon, ξ – \xi, ζ – \zeta, ς – \varsigma, ɛ – \varepsilon, ϑ – \vartheta, φ – \varphi, ϰ – \varkappa; A – \Alpha, B – \Beta, Γ – \Gamma, Δ – \Delta, E – \Epsilon, H – \Eta, I – \Iota, C – \Chi, K – \Kappa, Λ – \Lambda, M – \Mu, N – \Nu, O – \O, Ω – \Omega, Φ – \Phi, Π – \Pi, Ψ – \Psi, R – \Rho, Σ – \Sigma, Θ – \Theta, T – \Tau, Υ – \Upsilon, Ξ – \Xi, Z – \Zeta.

The small part of most common special TeX symbols are: ∠ – \angle,  aleph – \aleph, ⋅ – \cdot, ♣ – \clubsuit, ✓ – \checkmark, ∪ – \cup, ∩ – \cap, ♢ – \diamondsuit, ◇ – \diamond, ÷ – \div, ↓ – \downarrow, † – \dag, ‡ – \ddag, ≡ – \equiv, ∃ – \exists, ⌢ – \frown, ♭ – \flat, ≥ – \ge, ≥ – \geq, ≧ – \geqq, ← – \gets, ♡ – \heartsuit, ∞ – \infty, ∈ – \in, ∫ – \int, \Int, ℑ – \Im, ♢ – \lozenge, ⟨ – \langle, ≤ – \le, ≤ – \leq, ≦ – \leqq, ← – \leftarrow, ∓ – \mp, ∇ – \nabla, ≠ – \ne, ≠ – \neq, ♮ – \natural, ∮ – \oint, ⊙ – \odot, ⊕ – \oplus, ∂ – \partial, ∥ – \parallel, ⊥ –\perp, ± – \pm, ∝ – \propto, ∏ – \prod, ℜ – \Re, → – \rightarrow, ⟩ – \rangle, ♠ – \spadesuit, ~ – \sim, ⌣ – \smile, ⊂ – \subset, ⊃ – \supset, √ – \sqrt, § – \S, √ – \surd, ♯ – \sharp, ∑ – \sum, × – \times, → – \to, ∴ – \therefore, ↑ – \uparrow, ℘ – \wp.

[contents]

19. Formulas and functions

Formulas in MGL scripts is string with functions, operators, parentheses, variables, numbers and so on. There is no difference between lower or upper case in formulas. There are a lot of functions and operators available. The operators are: + – addition, – subtraction, * – multiplication, / – division, ^ – integer power. Also there are logical "operators": < – true if x<y, > – true if x>y, = – true if x=y, & – true if x and y both nonzero, | – true if x or y nonzero. These logical operators have lowest priority and return 1 if true or 0 if false.

The basic functions are: sqrt(x) – square root of x, pow(x,y) power x in y, ln(x) – natural logarithm of x, lg(x) – decimal logarithm of x, log(a,x) – logarithm base a of x, abs(x) – absolute value of x,sign(x) – sign of x, mod(x,y) – x modulo y, step(x) – step function, rnd – random number, pi – number π = 3.1415926…

Trigonometric functions are: sin(x), cos(x), tan(x) (or tg(x)). Inverse trigonometric functions are: asin(x), acos(x), atan(x). Hyperbolic functions are: sinh(x) (or sh(x)), cosh(x) (or ch(x)), tanh(x) (or th(x)). Inverse hyperbolic functions are: asinh(x), acosh(x), atanh(x).

There are a set of special functions: gamma(x) – Gamma function Γ(x) = ∫0 tx-1 exp(-t) dt, psi(x) – digamma function ψ(x) = Γ′(x)/Γ(x) for x≠0, ai(x) – Airy function Ai(x), bi(x) – Airy function Bi(x), cl(x) – Clausen function, li2(x) (or dilog(x)) – dilogarithm Li2(x) = -ℜ∫0xds log(1-s)/s, sinc(x) – compute sinc(x) = sin(πx)/(πx) for any value of x, zeta(x) – Riemann zeta function ζ(s) = ∑k=1k-s for arbitrary s≠1, eta(x) – eta function η(s) = (1 - 21-s)ζ(s) for arbitrary s, lp(l,x) – Legendre polynomial Pl(x), (|x|≤1, l≥0), w0(x) – principal branch of the Lambert W function, w1(x) – principal branch of the Lambert W function. Function W(x) is defined to be solution of the equation: W exp(W) = x.

The exponent integrals are: ci(x) – Cosine integral Ci(x) = ∫0xdt cos(t)/t, si(x) – Sine integral Si(x) = ∫0xdt sin(t)/t, erf(x) – error function erf(x) = (2/√π) ∫0xdt exp(-t2) , ei(x) – exponential integral Ei(x) = -PV(∫-xdt exp(-t)/t) (where PV denotes the principal value of the integral), e1(x) – exponential integral E1(x) = ℜ∫1dt exp(-xt)/t, e2(x) – exponential integral E2(x) = ℜ∫1∞dt exp(-xt)/t2, ei3(x) – exponential integral Ei3(x) = ∫0xdt exp(-t3) for x≥0.

Bessel functions are: j(nu,x) – regular cylindrical Bessel function of fractional order nu, y(nu,x) – irregular cylindrical Bessel function of fractional order nu, i(nu,x) – regular modified Bessel function of fractional order nu, k(nu,x) – irregular modified Bessel function of fractional order nu.

Elliptic integrals are: ee(k) – complete elliptic integral is denoted by E(k) = E(π/2,k), ek(k) – complete elliptic integral is denoted by K(k) = F(π/2,k), e(phi,k) – elliptic integral E(φ,k) = ∫0φdt √(1 - k2sin2(t)), f(phi,k) – elliptic integral F(φ,k) = ∫0φdt 1/√(1 - k2sin2(t))

Jacobi elliptic functions are: sn(u,m), cn(u,m), dn(u,m), sc(u,m), sd(u,m), ns(u,m), cs(u,m), cd(u,m), nc(u,m), ds(u,m), dc(u,m), nd(u,m).

[contents]

20. Command options

Command options allow the easy setup of the plot by changing of global settings only for this plot. Options are specified at the end of string. Each option is separated from the previous text by symbol ';'. Options work so that them remember the current settings, change settings as it being set in the option, execute command and return the original settings back. So, the options usage for data handling commands or for graphics setup commands is useless.

The most useful options are xrange, yrange, zrange. They sets the boundaries for data change. This boundaries are used for automatically filled variables. So, these options allow one to change the position of some plots. For example, in command plot y; xrange 0.1 0.9 the x coordinate will be equidistantly distributed in range 0.1 ... 0.9.

The full list of options are:

[contents]

21. Suffixes for variable

Suffixes can get some numerical value (like its size, maximal or minimal value, the sum of elements and so on) of the data array in variable and use it later as usual number in command arguments. The suffixes start from point '.' right after (without spaces) variable name or its subarray. For example, a.nx give the x-size of data a b(1).max give maximal value of second row of variable b c(:,0).sum give sum of element in first column of c and so on.

The full list of suffixes are:

[contents]