MGL script language

This file documents the MGL script language. It corresponds to release 2.0.2 of the MathGL library. Please report any errors in this manual to mathgl.abalakin@gmail.org. More information about MGL and MathGL can be found at the project homepage, http://mathgl.sourceforge.net/.

Copyright © 2008 Alexey A. Balakin.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover Texts being “A GNU Manual,” and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled “GNU Free Documentation License.”

(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and modify this GNU manual. Buying copies from the FSF supports it in developing GNU and promoting software freedom.”

1. MGL scripts

MathGL library supports the simplest scripts for data handling and plotting. These scripts can be used independently (with the help of UDAV, mglconv, mglview programs and others

1.1 MGL definition

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 important, 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 after symbol ‘;’ (see section 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’) or definitions (substrings ‘$a’, ‘$b’ ... ‘$z’) then before execution the values of parameter/definition will be substituted instead 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 (data arrays) or a number (scalars).

• The string is any symbols between ordinary marks ‘'’. Long strings can be concatenated from several lines by ‘\’ symbol. I.e. the string ‘'a +'\<br>' b'’ will give string ‘'a + b'’ (here ‘<br>’ is newline).
• Usually variable have a name which is arbitrary combination of symbols (except spaces and ‘'’) started from a letter and with length less than 64. A temporary array can be used as variable:
  • sub-arrays (like in subdata command) as command argument. For example, a(1) or a(1,:) or a(1,:,:) is second row, a(:,2) or a(:,2,:) is third column, a(:,:,0) is first slice and so on. Also you can extract a part of array from m-th to n-th element by code a(m:n,:,:) or just a(m:n).
  • any column combinations defined by formulas, like a('n*w^2/exp(t)') if names for data columns was specified (by idset command or in the file at string started with ##).
  • any expression (without spaces) of existed variables produce temporary variable. For example, ‘sqrt(dat(:,5)+1)’ will produce temporary variable with data values equal to tmp[i,j] = sqrt(dat[i,5,j]+1).
  • temporary variable of higher dimensions by help of []. For example, ‘[1,2,3]’ will produce a temporary vector of 3 elements {1, 2, 3}; ‘[[11,12],[21,22]]’ will produce matrix 2*2 and so on. Here you can join even an arrays of the same dimensions by construction like ‘[v1,v2,...,vn]’.
  • result of code for making new data (see section Make another data) inside {}. For example, ‘{sum dat 'x'}’ produce temporary variable which contain result of summation of dat along direction ’x’. This is the same array tmp as produced by command ‘sum tmp dat 'x'’. You can use nested constructions, like ‘{sum {max dat 'z'} 'x'}’.

  Temporary variables can not be used as 1st argument for commands which create (return) the data (like ‘new’, ‘read’, ‘hist’ and so on).

• Special names nan=#QNAN, pi=3.1415926..., on=1, off=0, :=-1 are treated as number if they were not redefined by user. Variables with suffixes are treated as numbers (see section Data information). Names defined by define command are treated as number. Also results of formulas with sizes 1x1x1 are treated as number (for example, ‘pi/dat.nx’).

Before the first using all variables must be defined with the help of commands, like, new, var, list, copy, read, hist, sum and so on (see sections Data constructor, Data filling and Make another data).

Command may have several set of possible arguments (for example, plot ydat and plot xdat ydat). All command arguments for a selected set must be specified. However, some arguments can have default values. These argument are printed in [], like text ydat ['stl'=''] or text x y 'txt' ['fnt'='' size=-1]. At this, the record [arg1 arg2 arg3 ...] means [arg1 [arg2 [arg3 ...]]], i.e. you can omit only tailing arguments if you agree with its default values. For example, text x y 'txt' '' 1 or text x y 'txt' '' is correct, but text x y 'txt' 1 is incorrect (argument 'fnt' is missed).

1.2 Program flow commands

Below I show commands to control program flow, like, conditions, loops, define script arguments and so on. Other commands can be found in chapters MathGL core and Data processing.

MGL command: chdir 'path'

Changes the current directory to path.

MGL command: ask $N 'question'

Sets N-th script argument to answer which give the user on the question. Usually this show dialog with question where user can enter some text as answer. Here N is digit (0...9) or alpha (a...z).

MGL command: define $N smth

Sets N-th script argument to smth. Note, that smth is used as is (with ‘'’ symbols if present). Here N is digit (0...9) or alpha (a...z).

MGL command: define name smth

Create scalar variable name which have the numeric value of smth. Later you can use this variable as usual number. Here N is digit (0...9) or alpha (a...z).

MGL command: defchr $N smth

Sets N-th script argument to character with value evaluated from smth. Here N is digit (0...9) or alpha (a...z).

MGL command: defnum $N smth

Sets N-th script argument to number with value evaluated from smth. Here N is digit (0...9) or alpha (a...z).

MGL command: defpal $N smth

Sets N-th script argument to palette character at position evaluated from smth. Here N is digit (0...9) or alpha (a...z).

MGL command: call 'fname' [ARG1 ARG2 ... ARG9]

Executes function fname (or script if function is not found). Optional arguments will be passed to functions. See also func.

MGL command: func 'fname' [narg=0]

Define the function fname and number of required arguments. The arguments will be placed in script parameters $1, $2, ... $9. Note, you should stop script execution before function definition(s) by command stop. See also return.

MGL command: return

Return from the function. See also func.

MGL command: if dat 'cond'

Starts block which will be executed if dat satisfy to cond.

MGL command: if val

Starts block which will be executed if val is nonzero.

MGL command: elseif dat 'cond'

Starts block which will be executed if previous if or elseif is false and dat satisfy to cond.

MGL command: elseif val

Starts block which will be executed if previous if or elseif is false and val is nonzero.

MGL command: else

Starts block which will be executed if previous if or elseif is false.

MGL command: endif

Finishes if/elseif/else block.

MGL command: for $N v1 v2 [dv=1]

Starts cycle with $N-th argument changing from v1 to v2 with the step dv. Here N is digit (0...9) or alpha (a...z).

MGL command: for $N dat

Starts cycle with $N-th argument changing for dat values. Here N is digit (0...9) or alpha (a...z).

MGL command: next

Finishes for cycle.

MGL command: once val

The code between once on and once off will be executed only once. Useful for large data manipulation in programs like UDAV.

MGL command: stop

Terminate execution.

2. General concepts

The set of MathGL features is rather rich – just the number of basic graphics types is larger than 50. Also there are functions for data handling, plot setup and so on. In spite of it I tried to keep a similar style in function names and in the order of arguments. Mostly it is used for different drawing functions.

There are six most general (base) concepts:

1. Any picture is created in memory first. The internal (memory) representation can be different: bitmap picture (for SetQuality(MGL_DRAW_LMEM)) or the list of vector primitives (default). After that the user may decide what he/she want: save to file, display on the screen, run animation, do additional editing and so on. This approach assures a high portability of the program – the source code will produce exactly the same picture in any OS. Another big positive consequence is the ability to create the picture in the console program (using command line, without creating a window)!
2. Every plot settings (style of lines, font, color scheme) are specified by a string. It provides convenience for user/programmer – short string with parameters is more comprehensible than a large set of parameters. Also it provides portability – the strings are the same in any OS so that it is not necessary to think about argument types.
3. All functions have “simplified” and “advanced” forms. It is done for user’s convenience. One needs to specify only one data array in the “simplified” form in order to see the result. But one may set parametric dependence of coordinates and produce rather complex curves and surfaces in the “advanced” form. In both cases the order of function arguments is the same: first data arrays, second the string with style, and later string with options for additional plot tuning.
4. All data arrays for plotting are encapsulated in mglData(A) class. This reduces the number of errors while working with memory and provides a uniform interface for data of different types (float, double and so on) or for formula plotting.
5. All plots are vector plots. The MathGL library is intended for handling scientific data which have vector nature (lines, faces, matrices and so on). As a result, vector representation is used in all cases! In addition, the vector representation allows one to scale the plot easily – change the canvas size by a factor of 2, and the picture will be proportionally scaled.
6. New drawing never clears things drawn already. This, in some sense, unexpected, idea allows to create a lot of “combined” graphics. For example, to make a surface with contour lines one needs to call the function for surface plotting and the function for contour lines plotting (in any order). Thus the special functions for making this “combined” plots (as it is done in Matlab and some other plotting systems) are superfluous.

In addition to the general concepts I want to comment on some non-trivial or less commonly used general ideas – plot positioning, axis specification and curvilinear coordinates, styles for lines, text and color scheme.

2.1 Coordinate axes

Two axis representations are used in MathGL. The first one consists of normalizing coordinates of data points in a box Min x Max (see Axis settings). If SetCut() is true then the outlier points are omitted, otherwise they are projected to the bounding box (see Cutting). Also, the point will be omitted if it lies inside the box defined by SetCutBox() or if the value of formula CutOff() is nonzero for its coordinates. After that, transformation formulas defined by SetFunc() or SetCoor() are applied to the data point (see Curved coordinates). Finally, the data point is plotted by one of the functions.

The range of x, y, z-axis can be specified by SetRange() or SetRanges() functions. Its origin is specified by SetOrigin() function. At this you can you can use NAN values for selecting axis origin automatically.

There is 4-th axis c (color axis or colorbar) in addition to the usual axes x, y, z. It sets the range of values for the surface coloring. Its borders are automatically set to values of Min.z, Max.z during the call of SetRanges() function. Also, one can directly set it by call SetRange('c', ...). Use Colorbar() function for drawing the colorbar.

The form (appearence) of tick labels is controlled by SetTicks() function (see section Ticks). Function SetTuneTicks switches on/off tick enhancing by factoring out acommon multiplier (for small coordinate values, like 0.001 to 0.002, or large, like from 1000 to 2000) or common component (for narrow range, like from 0.999 to 1.000). Finally, you may use functions SetTickTempl() for setting templates for tick labels (it supports TeX symbols). Also, there is a possibility to print arbitrary text as tick labels the by help of SetTicksVal() function.

2.2 Color styles

Base colors are defined by one of symbol ‘wkrgbcymhRGBCYMHWlenupqLENUPQ’. The color types are: ‘k’ -- black, ‘r’ -- red, ‘R’ -- dark red, ‘g’ -- green, ‘G’ -- dark green, ‘b’ -- blue, ‘B’ -- dark blue, ‘c’ -- cyan, ‘C’ -- dark cyan, ‘m’ -- magenta, ‘M’ -- dark magenta, ‘y’ -- yellow, ‘Y’ -- dark yellow (gold), ‘h’ -- gray, ‘H’ -- dark gray, ‘w’ -- white, ‘W’ -- bright gray, ‘l’ -- green-blue, ‘L’ -- dark green-blue, ‘e’ -- green-yellow, ‘E’ -- dark green-yellow, ‘n’ -- sky-blue, ‘N’ -- dark sky-blue, ‘u’ -- blue-violet, ‘U’ -- dark blue-violet, ‘p’ -- purple, ‘P’ -- dark purple, ‘q’ -- orange, ‘Q’ -- dark orange (brown).

You can also use “bright” colors. The “bright” color contain 2 symbols in brackets ‘{cN}’: first one is the usual symbol for color id, the second one is a digit for its brightness. The digit can be in range ‘1’...‘9’. Number ‘5’ corresponds to a normal color, ‘1’ is a very dark version of the color (practically black), and ‘9’ is a very bright version of the color (practically white). For example, the colors can be ‘{b2}’ ‘{b7}’ ‘{r7}’ and so on.

2.3 Line styles

The line style is defined by the string which may contain specifications for color (‘wkrgbcymhRGBCYMHWlenupqLENUPQ’), dashing style (‘-|;:ji=’ or space), width (‘123456789’) and marks (‘*o+xsd.^v<>’ and ‘#’ modifier). If one of the type of information is omitted then default values used with next color from palette (see Palette and colors). Note, that internal color counter will be nullified by any change of palette. This includes even hidden change (for example, by Box() or Axis() functions). By default palette contain following colors: dark gray ‘H’, blue ‘b’, green ‘g’, red ‘r’, cyan ‘c’, magenta ‘m’, yellow ‘y’, gray ‘h’, green-blue ‘l’, sky-blue ‘n’, orange ‘q’, green-yellow ‘e’, blue-violet ‘u’, purple ‘p’.

Dashing style has the following meaning: space -- no line (usable for plotting only marks), ‘-’ -- solid line (■■■■■■■■■■■■■■■■), ‘|’ -- long dashed 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), ‘.’ – dot (point), ‘^’ – triangle up, ‘v’ – triangle down, ‘<’ – triangle left, ‘>’ – triangle right, ‘#*’ – Y sign, ‘#+’ – squared cross, ‘#x’ – squared skew cross, ‘#.’ – circled dot. If string contain symbol ‘#’ then the solid versions of markers are used.

One may specify to draw a special symbol (an arrow) at the beginning and at the end of line. This is done if the specification string contains one of the following symbols: ‘A’ – outer arrow, ‘V’ – inner arrow, ‘I’ – transverse hatches, ‘K’ – arrow with hatches, ‘T’ – triangle, ‘S’ – square, ‘D’ – rhombus, ‘O’ – circle, ‘_’ – nothing (the default). The following rule applies: the first symbol specifies the arrow at the end of line, the second specifies the arrow at the beginning of the line. For example, ‘r-A’ defines a red solid line with usual arrow at the end, ‘b|AI’ defines a blue dash line with an arrow at the end and with hatches at the beginning, ‘_O’ defines a line with the current style and with a circle at the beginning. These styles are applicable during the graphics plotting as well (for example, 1D plotting).

2.4 Color scheme

The color scheme is used for determining the color of surfaces, isolines, isosurfaces and so on. The color scheme is defined by the string, which may contain several characters that are color id (see section Line styles) or characters ‘#:|’. Symbol ‘#’ switches to mesh drawing or to a wire plot. Symbol ‘|’ disables color interpolation in color scheme, which can be useful, for example, for sharp colors during matrix plotting. Symbol ‘:’ terminate the color scheme parsing. Following it, the user may put styles for the text, rotation axis for curves/isocontours, and so on. Color scheme may contain up to 32 color values.

The final color is a linear interpolation of color array. The color array is constructed from the string ids (including “bright” colors, see Color styles). The argument is the amplitude normalized between Cmin – Cmax (see Axis settings). For example, string containing 4 characters ‘bcyr’ corresponds to a colorbar from blue (lowest value) through cyan (next value) through yellow (next value) to the red (highest value). String ‘kw’ corresponds to a colorbar from black (lowest value) to white (highest value). String ‘m’ corresponds to a simple magenta color.

There are several useful combinations. String ‘kw’ corresponds to the simplest gray color scheme where higher values are brighter. String ‘wk’ presents the inverse gray color scheme where 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 bi-color figure on white or black background, where negative values are blue and positive values are red. String ‘BbcyrR’ gives a color scheme similar to the well-known jet color scheme.

When coloring by coordinate (used in map), the final color is determined by the position of the point in 3d space and is calculated from formula c=x*c[1] + y*c[2]. Here, c[1], c[2] are the first two elements of color array; x, y are normalized to axis range coordinates of the point.

2.5 Font styles

Text style is specified by the string which may contain: color id characters ‘wkrgbcymhRGBCYMHW’ (see Color styles), and font style (‘ribwou’) and/or alignment (‘LRC’) specifications. At this, font style and alignment begin after the separator ‘:’. For example, ‘r:iCb’ sets the bold (‘b’) italic (‘i’) font text aligned at the center (‘C’) and with red color (‘r’).

The font styles are: ‘r’ – roman (or regular) 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’ – over-lined, ‘u’ – underlined.

Also a parsing of the LaTeX-like syntax is provided. There are commands for the font style changing inside the string (for example, use \b for bold font): \a or \overline – over-lined, \b or \textbf – bold, \i or \textit – italic, \r or \textrm – roman (disable bold and italic 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 (see section Color styles). For example, words ‘blue’ and ‘red’ will be colored in the string ‘#b{blue} and \colorr{red} text’. The most of functions understand the newline symbol ‘\n’ and allows to print multi-line text. Finally, you can use arbitrary (if it was defined in font-face) UTF codes by command \utf0x????. For example, \utf0x3b1 will produce α symbol.

The most of commands for special TeX or AMSTeX symbols, the commands for font style changing (\textrm, \textbf, \textit, \textsc, \overline, \underline), accents (\hat, \tilde, \dot, \ddot, \acute, \check, \grave, \bar, \breve) and roots (\sqrt, \sqrt3, \sqrt4) are recognized. 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’; ‘\tilde{}a’.

The small part of most common special TeX symbols are: ∠ – \angle, ⋅ – \cdot, ♣ – \clubsuit, ✓ – \checkmark, ∪ – \cup, ∩ – \cap, ♢ – \diamondsuit, ◇ – \diamond, ÷ – \div, ↓ – \downarrow, † – \dag, ‡ – \ddag, ≡ – \equiv, ∃ – \exists, ⌢ – \frown, ♭ – \flat, ≥ – \ge, ≥ – \geq, ≧ – \geqq, ← – \gets, ♡ – \heartsuit, ∞ – \infty, ∫ – \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 or \surd, § – \S, ♯ – \sharp, ∑ – \sum, × – \times, → – \to, ∴ – \therefore, ↑ – \uparrow, ℘ – \wp.

The font size can be defined explicitly (if size>0) or relatively to a 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. Special functions SetFontSizePT(), SetFontSizeCM(), SetFontSizeIN() (see Font settings) allow one to set it in more “common” variables for a given dpi value of the picture.

2.6 Textual formulas

MathGL have the fast variant of textual formula evaluation . 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, ‘int(x)’ – integer part of x, ‘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) = ∫₀^∞ t^x-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 Li₂(x) = -ℜ∫₀^xds log(1-s)/s, ‘sinc(x)’ – compute sinc(x) = sin(πx)/(πx) for any value of x, ‘zeta(x)’ – Riemann zeta function ζ(s) = ∑_k=1^∞k^-s for arbitrary s≠1, ‘eta(x)’ – eta function η(s) = (1 - 2^1-s)ζ(s) for arbitrary s, ‘lp(l,x)’ – Legendre polynomial P_l(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) = ∫₀^xdt cos(t)/t, ‘si(x)’ – Sine integral Si(x) = ∫₀^xdt sin(t)/t, ‘erf(x)’ – error function erf(x) = (2/√π) ∫₀^xdt exp(-t²) , ‘ei(x)’ – exponential integral Ei(x) = -PV(∫_-x^∞dt exp(-t)/t) (where PV denotes the principal value of the integral), ‘e1(x)’ – exponential integral E₁(x) = ℜ∫₁^∞dt exp(-xt)/t, ‘e2(x)’ – exponential integral E₂(x) = ℜ∫₁∞dt exp(-xt)/t², ‘ei3(x)’ – exponential integral Ei₃(x) = ∫₀^xdt exp(-t³) 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) = ∫₀^φdt √(1 - k²sin²(t)), ‘f(phi,k)’ – elliptic integral F(φ,k) = ∫₀^φdt 1/√(1 - k²sin²(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)’.

Note, some of these functions are unavailable if MathGL was compiled without GSL support.

There is no difference between lower or upper case in formulas. If argument value lie outside the range of function definition then function returns NaN.

2.7 Command options

Command options allow the easy setup of the selected plot by changing global settings only for this plot. Each option start from symbol ‘;’. Options work so that MathGL remember the current settings, change settings as it being set in the option, execute function and return the original settings back. So, the options are most usable for plotting functions.

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"); or 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:

MGL option: alpha val

Sets alpha value (transparency) of the plot. The value should be in range [0, 1]. See also alphadef.

MGL option: ambient val

Sets brightness of ambient light for the plot. The value should be in range [0, 1]. See also ambient.

MGL option: diffuse val

Sets brightness of diffuse light for the plot. The value should be in range [0, 1]. See also diffuse.

MGL option: xrange val1 val2

Sets boundaries of x coordinate change for the plot. See also xrange.

MGL option: yrange val1 val2

Sets boundaries of y coordinate change for the plot. See also yrange.

MGL option: zrange val1 val2

Sets boundaries of z coordinate change for the plot. See also zrange.

MGL option: cut val

Sets whether to cut or to project the plot points lying outside the bounding box. See also cut.

MGL option: size val

Sets the size of text, marks and arrows. See also font, marksize, arrowsize.

MGL option: meshnum val

Work like meshnum command.

MGL option: legend 'txt'

Adds string ’txt’ to internal legend accumulator. The style of described line and mark is taken from arguments of the last 1D plotting command. See also legend.

MGL option: value val

Set the value to be used as additional numeric parameter in plotting command.

2.8 Interfaces

You can use mglParse class for executing MGL scripts from different languages.

3. MathGL core

This chapter contains a lot of plotting commands for 1D, 2D and 3D data. It also encapsulates parameters for axes drawing. Moreover an arbitrary coordinate transformation can be used for each axis. Additional information about colors, fonts, formula parsing can be found in General concepts.

3.1 Create and delete objects

You don’t need to create canvas object in MGL.

3.2 Graphics setup

Functions and variables in this group influences on overall graphics appearance. So all of them should be placed before any actual plotting function calls.

3.2.1 Transparency

There are several functions and variables for setup transparency. The general function is alpha which switch on/off the transparency for overall plot. It influence only for graphics which created after alpha call (with one exception, OpenGL). Function alphadef specify the default value of alpha-channel. Finally, function transptype set the kind of transparency.

MGL command: alpha [val=on]

Sets the transparency on/off and returns previous value of transparency. It is recommended to call this function before any plotting command. Default value is transparency off.

MGL command: alphadef val

Sets default value of alpha channel (transparency) for all plotting functions. Initial value is 0.5.

MGL command: transptype val

Set the type of transparency. Possible values are:

• Normal transparency (‘0’) – below things is less visible than upper ones. It does not look well in OpenGL mode (mglGraphGL) for several surfaces.
• Glass-like transparency (‘1’) – below and upper things are commutable and just decrease intensity of light by RGB channel.
• Lamp-like transparency (‘2’) – below and upper things are commutable and are the source of some additional light. I recommend to set SetAlphaDef(0.3) or less for lamp-like transparency.

.

3.2.2 Lighting

There are several functions for setup lighting. The general function is Light(bool) which switch on/off the lighting for overall plot. It influence only for graphics which created after light call (with one exception, OpenGL). Generally MathGL support up to 10 independent light sources. But in OpenGL mode only 8 of light sources is used due to OpenGL limitations. The position, color, brightness of each light source can be set separately. By default only one light source is active. It is source number 0 with white color, located at top of the plot.

MGL command: light [val=on]

Sets the using of light on/off for overall plot. Function returns previous value of lighting. Default value is lightning off.

MGL command: light num val

Switch on/off n-th light source separately.

MGL command: light num xdir ydir zdir ['col'='w' br=0.5]

MGL command: light num xdir ydir zdir xpos ypos zpos ['col'='w' br=0.5]

The function adds a light source with identification n in direction d with color c and with brightness bright (which must be in range [0,1]). If position r is specified and isn’t NAN then light source is supposed to be local otherwise light source is supposed to be placed at infinity.

MGL command: ambient val

Sets the brightness of ambient light. The value should be in range [0,1].

3.2.3 Fog

MGL command: fog val [dz=0.25]

Function imitate a fog in the plot. Fog start from relative distance dz from view point and its density growths exponentially in depth. So that the fog influence is determined by law ~ 1-exp(-d*z). Here z is normalized to 1 depth of the plot. If value d=0 then the fog is absent. Note, that fog was applied at stage of image creation, not at stage of drawing.

3.2.4 Default sizes

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

MGL command: barwidth val

Sets relative width of rectangles in bars, barh, boxplot, candle. Default value is 0.7.

MGL command: marksize val

Sets size of marks for 1D plotting. Default value is 0.02.

MGL command: arrowsize val

Sets size of arrows for 1D plotting, lines and curves (see Primitives). Default value is 0.03.

MGL command: meshnum val

Sets approximate number of lines in mesh, fall, grid and also the number of hachures in vect, dew and the number of cells in cloud. By default (=0) it draws all lines/hachures/cells.

3.2.5 Cutting

These variables and functions set the condition when the points are excluded (cutted) from the drawing. Note, that a point with NAN value(s) of coordinate or amplitude will be automatically excluded from the drawing.

MGL command: cut val

Flag which determines how points outside bounding box are drawn. If it is true then points are excluded from plot (it is default) otherwise the points are projected to edges of bounding box.

MGL command: cut x1 y1 z1 x2 y2 z2

Lower and upper edge of the box in which never points are drawn. If both edges are the same (the variables are equal) then the cutting box is empty.

MGL command: cut 'cond'

Sets the cutting off condition by formula cond. This condition determine will point be plotted or not. If value of formula is nonzero then point is omitted, otherwise it plotted. Set argument as "" to disable cutting off condition.

3.2.6 Font settings

MGL command: font 'fnt' [val=6]

Font style for text and labels (see text). Initial style is ’fnt’=’:rC’ give Roman font with centering. Parameter val sets the size of font for tick and axis labels. Default font size of axis labels is 1.4 times large than for tick labels. For more detail, see Font styles.

MGL command: rotatetext val

Method on mglGraph: void SetRotatedText (bool val)

C function: void mgl_set_rotated_text (HMGL gr, int val)

Sets to use or not text rotation.

3.2.7 Palette and colors

MGL command: palette 'colors'

Sets the palette as selected colors. Default value is "Hbgrcmyhlnqeup" that corresponds to 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 palette is used mostly in 1D plots (see 1D plotting) for curves which styles are not specified. Internal color counter will be nullified by any change of palette. This includes even hidden change (for example, by Box() or Axis() functions).

3.2.8 Error handling

3.3 Axis settings

These large set of variables and functions 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 if Cut=true (see Cutting), after it transformation formulas are applied, and finally the data was normalized in bounding box.

3.3.1 Ranges (bounding box)

MGL command: xrange v1 v2

MGL command: yrange v1 v2

MGL command: zrange v1 v2

MGL command: crange v1 v2

Sets the range for ‘x’-,‘y’-,‘z’- coordinate or coloring (‘c’). See also ranges.

MGL command: xrange dat [add=off]

MGL command: yrange dat [add=off]

MGL command: zrange dat [add=off]

MGL command: crange dat [add=off]

Sets the range for ‘x’-,‘y’-,‘z’- coordinate or coloring (‘c’) as minimal and maximal values of data dat. Parameter add=on shows that the new range will be joined to existed one (not replace it).

MGL command: ranges x1 x2 y1 y2 [z1=0 z2=0]

Sets the ranges of coordinates. If minimal and maximal values of the coordinate are the same then they are ignored. Also it sets the range for coloring (analogous to crange z1 z2). This is default color range for 2d plots. Initial ranges are [-1, 1].

MGL command: origin x0 y0 [z0=nan]

Sets center of axis cross section. If one of values is NAN then MathGL try to select optimal axis position.

3.3.2 Curved coordinates

MGL command: axis 'fx' 'fy' ['fz'='' 'fa'='']

Sets transformation formulas for curvilinear coordinate. Each string should contain mathematical expression for real coordinate depending on internal coordinates ‘x’, ‘y’, ‘z’ and ‘a’ or ‘c’ for colorbar. For example, the cylindrical coordinates are introduced as SetFunc("x*cos(y)", "x*sin(y)", "z");. For removing of formulas the corresponding parameter should be empty or NULL. Using transformation formulas will slightly slowing the program. Parameter EqA set the similar transformation formula for color scheme. See section Textual formulas.

MGL command: axis how

Sets one of the predefined transformation formulas for curvilinear coordinate. Paramater how define the coordinates: mglCartesian=0 – Cartesian coordinates (no transformation); mglPolar=1 – Polar coordinates x_n=x*cos(y),y_n=x*sin(y), z_n=z; mglSpherical=2 – Sperical coordinates x_n=x*sin(y)*cos(z), y_n=x*sin(y)*sin(z), z_n=x*cos(y); mglParabolic=3 – Parabolic coordinates x_n=x*y, y_n=(x*x-y*y)/2, z_n=z; mglParaboloidal=4 – Paraboloidal coordinates x_n=(x*x-y*y)*cos(z)/2, y_n=(x*x-y*y)*sin(z)/2, z_n=x*y; mglOblate=5 – Oblate coordinates x_n=cosh(x)*cos(y)*cos(z), y_n=cosh(x)*cos(y)*sin(z), z_n=sinh(x)*sin(y); mglProlate=6 – Prolate coordinates x_n=sinh(x)*sin(y)*cos(z), y_n=sinh(x)*sin(y)*sin(z), z_n=cosh(x)*cos(y); mglElliptic=7 – Elliptic coordinates x_n=cosh(x)*cos(y), y_n=sinh(x)*sin(y), z_n=z; mglToroidal=8 – Toroidal coordinates x_n=sinh(x)*cos(z)/(cosh(x)-cos(y)), y_n=sinh(x)*sin(z)/(cosh(x)-cos(y)), z_n=sin(y)/(cosh(x)-cos(y)); mglBispherical=9 – Bispherical coordinates x_n=sin(y)*cos(z)/(cosh(x)-cos(y)), y_n=sin(y)*sin(z)/(cosh(x)-cos(y)), z_n=sinh(x)/(cosh(x)-cos(y)); mglBipolar=10 – Bipolar coordinates x_n=sinh(x)/(cosh(x)-cos(y)), y_n=sin(y)/(cosh(x)-cos(y)), z_n=z; mglLogLog=11 – log-log coordinates x_n=lg(x), y_n=lg(y), z_n=lg(z); mglLogX=12 – log-x coordinates x_n=lg(x), y_n=y, z_n=z; mglLogY=13 – log-y coordinates x_n=x, y_n=lg(y), z_n=z.

MGL command: ternary val

The function sets to draws Ternary or Quaternary plot. Ternary plot is special plot for 3 dependent coordinates (components) a, b, c so that a+b+c=1. MathGL uses only 2 independent coordinates a=x and b=y since it is enough to plot everything. At this third coordinate z act as another parameter to produce contour lines, surfaces and so on. Correspondingly Quaternary plot is plot for 4 dependent coordinates a, b, c and d so that a+b+c+d=1. Use Ternary(0) for returning to usual axis.

3.3.3 Ticks

MGL command: adjust ['dir'='xyzc']

Set the ticks step, number of sub-ticks and initial ticks position to be the most human readable for the axis along direction(s) dir. Also set SetTuneTicks(true). Usually you don’t need to call this function except the case of returning to default settings.

MGL command: xtick val [sub=0 org=nan]

MGL command: ytick val [sub=0 org=nan]

MGL command: ztick val [sub=0 org=nan]

MGL command: ctick val [sub=0 org=nan]

Set the ticks step d, number of sub-ticks ns and initial ticks position org for the axis along direction dir (use ’c’ for colorbar ticks). Variable d set step for axis ticks (if positive) or it’s number on the axis range (if negative). Zero value set automatic ticks. If org value is NAN then axis origin is used.

MGL command: xtick val1 'lbl1' [val2 'lbl2' ...]

MGL command: ytick val1 'lbl1' [val2 'lbl2' ...]

MGL command: ztick val1 'lbl1' [val2 'lbl2' ...]

Set the manual positions val and its labels lbl for ticks along axis dir. If array val is absent then values equidistantly distributed in interval [Min.x, Max.x] are used. Labels are separated by ‘\n’ symbol. Use SetTicks() to restore automatic ticks.

MGL command: xtick 'templ'

MGL command: ytick 'templ'

MGL command: ztick 'templ'

MGL command: ctick 'templ'

Set template templ for x-,y-,z-axis ticks or colorbar ticks. It may contain TeX symbols also. If templ="" then default template is used (in simplest case it is ‘%.2g’). Setting on template switch off automatic ticks tuning.

MGL command: ticktime 'dir' [dv 'tmpl']

Set time labels with step val and template templ for x-,y-,z-axis ticks or colorbar ticks. It may contain TeX symbols also. The format of template templ is the same as described in http://www.manpagez.com/man/3/strftime/. Most common variants are ‘%X’ for national representation of time, ‘%x’ for national representation of date, ‘%Y’ for year with century. If val=0 and/or templ="" then automatic tick step and/or template will be selected.

MGL command: tuneticks val [pos=1.15]

Switch on/off ticks enhancing by factoring common multiplier (for small, like from 0.001 to 0.002, or large, like from 1000 to 2000, coordinate values – enabled if tune&1 is nonzero) or common component (for narrow range, like from 0.999 to 1.000 – enabled if tune&2 is nonzero). Also set the position pos of common multiplier/component on the axis: =0 at minimal axis value, =1 at maximal axis value. Default value is 1.15.

MGL command: ticklen val [stt=1]

The relative length of axis ticks. Default value is 0.1. Parameter stt>0 set relative length of subticks which is in sqrt(1+stt) times smaller.

MGL command: axisstl 'stl' ['tck'='' 'sub'='']

The line style of axis, (stl) ticks (tck) and subticks (sub). If stl is empty then default style is used (‘k’ or ‘w’ depending on transparency type). If sub or sub is empty then axis style is used (i.e. stl).

3.4 Subplots and rotation

These functions control how and where further plotting will be placed. There is a certain calling order of these functions for the better plot appearance. First one should be subplot, multiplot or inplot for specifying the place. Second one can be title for adding title for the subplot. After it a rotate and aspect. And finally any other plotting functions may be called. Alternatively you can use columnplot, gridplot, stickplot or relative inplot for positioning plots in the column (or grid, or stick) one by another without gap between plot axis (bounding boxes).

MGL command: subplot nx ny m ['stl'='<>_^' dx=0 dy=0]

Puts further plotting in a m-th cell of nx*ny grid of the whole frame area. This function set off any aspects or rotations. So it should be used first for creating the subplot. Extra space will be reserved for axis/colorbar if stl contain:

• ‘L’ or ‘<’ – at left side,
• ‘R’ or ‘>’ – at right side,
• ‘A’ or ‘^’ – at top side,
• ‘U’ or ‘_’ – at bottom side.

From the aesthetical point of view it is not recommended to use this function with different matrices in the same frame. The position of the cell can be shifted from its default position by relative size dx, dy.

MGL command: multiplot nx ny m dx dy ['style'='<>_^']

Puts further plotting in a rectangle of dx*dy cells starting from m-th cell of nx*ny grid of the whole frame area. This function set off any aspects or rotations. So it should be used first for creating subplot. Extra space will be reserved for axis/colorbar if stl contain:

• ‘L’ or ‘<’ – at left side,
• ‘R’ or ‘>’ – at right side,
• ‘A’ or ‘^’ – at top side,
• ‘U’ or ‘_’ – at bottom side.

MGL command: inplot x1 x2 y1 y2 [rel=off]

Puts further plotting in some region of the whole frame surface. This function allows one to create a plot in arbitrary place of the screen. The position is defined by rectangular coordinates [x1, x2]*[y1, y2]. The coordinates x1, x2, y1, y2 are normalized to interval [0, 1]. If parameter rel=true then the relative position to current subplot (or inplot with rel=false) is used. This function set off any aspects or rotations. So it should be used first for creating subplot.

MGL command: columnplot num ind [d=0]

Puts further plotting in ind-th cell of column with num cells. The position is relative to previous subplot (or inplot with rel=false). Parameter d set extra gap between cells.

MGL command: gridplot nx ny ind [d=0]

Puts further plotting in ind-th cell of nx*ny grid. The position is relative to previous subplot (or inplot with rel=false). Parameter d set extra gap between cells.

MGL command: stickplot num ind tet phi

Puts further plotting in ind-th cell of stick with num cells. At this, stick is rotated on angles tet, phi. The position is relative to previous subplot (or inplot with rel=false).

MGL command: title 'title' ['stl'='' size=-2]

Add text title for current subplot/inplot. Paramater stl can contain:

• font style (see, Font styles);
• ‘#’ for box around the title.

Parameter size set font size. This function set off any aspects or rotations. So it should be used just after creating subplot.

MGL command: rotate tetz tetx [tety=0]

Rotates a further plotting relative to each axis {x, z, y} consecutively on angles TetX, TetZ, TetY.

MGL command: rotate tet x y z

Rotates a further plotting around vector {x, y, z} on angle Tet.

MGL command: aspect ax ay [az=1]

Defines aspect ratio for the plot. The viewable axes will be related one to another as the ratio Ax:Ay:Az. For the best effect it should be used after rotate function.

MGL command: perspective val

Add (switch on) the perspective to plot. The parameter a ~ 1/z_eff \in [0,1). By default (a=0) the perspective is off.

3.5 Export picture

Functions in this group save or give access to produced picture. So, usually they should be called after plotting is done.

MGL command: setsize w h

Sets size of picture in pixels. This function must be called before any other plotting because it completely remove picture contents.

MGL command: quality val

Sets quality of the plot depending on value val: MGL_DRAW_WIRE=0 – no face drawing (fastest), MGL_DRAW_FAST=1 – no color interpolation (fast), MGL_DRAW_NORM=2 – high quality (normal). If MGL_DRAW_LMEM=0x4 is set then direct bitmap drawing is used (low memory usage).

3.5.1 Export to file

These functions export current view to a graphic file. The filename fname should have appropriate extension. Parameter descr gives the short description of the picture. Just now the transparency is supported in PNG, SVG, OBJ and IDTF files.

MGL command: write ['fname'='']

Exports current frame to a file fname which type is determined by the extension. Parameter descr adds description to file (can be ""). If fname="" then the file ‘frame####.jpg’ is used, where ‘####’ is current frame id and name ‘frame’ is defined by PlotId class property.

3.5.2 Frames/Animation

There are no commands for making animation in MGL. However you can use features of mglconv and mglview utilities. For example, by busing special comments ‘##a ’ or ‘##c ’.

3.5.3 Bitmap in memory

3.5.4 Parallelization

3.6 Primitives

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

MGL command: clf

Clear the picture and fill it by color specified color.

MGL command: ball x y ['col'='r.']

MGL command: ball x y z ['col'='r.']

Draws a mark (point ‘.’ by default) at position p={x, y, z} with color col.

MGL command: line x1 y1 x2 y2 ['stl'='']

MGL command: line x1 y1 z1 x2 y2 z2 ['stl'='']

Draws a geodesic line (straight line in Cartesian coordinates) from point p1 to p2 using line style stl. Parameter num define the “quality” of the line. If num=2 then the stright line will be drawn in all coordinate system (independently on transformation formulas (see Curved coordinates). Contrary, for large values (for example, =100) the geodesic line will be drawn in corresponding coordinate system (straight line in Cartesian coordinates, circle in polar coordinates and so on). Line will be drawn even if it lies out of bounding box.

MGL command: curve x1 y1 dx1 dy1 x2 y2 dx2 dy2 ['stl'='']

MGL command: curve x1 y1 z1 dx1 dy1 dz1 x2 y2 z2 dx2 dy2 dz2 ['stl'='']

Draws Bezier-like curve from point p1 to p2 using line style stl. At this tangent is codirected with d1, d2 and proportional to its amplitude. Parameter num define the “quality” of the curve. If num=2 then the straight line will be drawn in all coordinate system (independently on transformation formulas, see Curved coordinates). Contrary, for large values (for example, =100) the spline like Bezier curve will be drawn in corresponding coordinate system. Curve will be drawn even if it lies out of bounding box.

MGL command: facex x0 y0 z0 wy wz ['stl'='' d1=0 d2=0]

MGL command: facey x0 y0 z0 wx wz ['stl'='' d1=0 d2=0]

MGL command: facez x0 y0 z0 wx wy ['stl'='' d1=0 d2=0]

Method on mglGraph: void FaceX (float x0, float y0, float z0, float wy, float wz, const char *stl="w", float d1=0, float d2=0)

Method on mglGraph: void FaceY (float x0, float y0, float z0, float wx, float wz, const char *stl="w", float d1=0, float d2=0)

Method on mglGraph: void FaceZ (float x0, float y0, float z0, float wx, float wy, const char *stl="w", float d1=0, float d2=0)

C function: void mgl_facex (HMGL gr, float x0, float y0, float z0, float wy, float wz, const char *stl, float d1, float d2)

C function: void mgl_facey (HMGL gr, float x0, float y0, float z0, float wx, float wz, const char *stl, float d1, float d2)

C function: void mgl_facez (HMGL gr, float x0, float y0, float z0, float wx, float wy, const char *stl, float d1, float d2)

Draws the solid rectangle (face) perpendicular to [x,y,z]-axis correspondingly at position {x0, y0, z0} with color stl and with widths wx, wy, wz along corresponding directions. At this colors can be the same for all vertexes or separately if all 4 colors are specified for each vertex. Parameters d1!=0, d2!=0 set additional shift of the last vertex (i.e. to draw quadrangle).

MGL command: sphere x0 y0 r ['col'='r']

MGL command: sphere x0 y0 z0 r ['col'='r']

Draw the sphere with radius r and center at point p={x0, y0, z0} and color stl.

MGL command: drop x0 y0 dx dy r ['col'='r' sh=1 asp=1]

MGL command: drop x0 y0 z0 dx dy dz r ['col'='r' sh=1 asp=1]

Draw the drop with radius r at point p elongated in direction d and with color col. Parameter shift set the degree of drop oblongness: ‘0’ is sphere, ‘1’ is maximally oblongness drop. Parameter ap set relative width of the drop (this is analogue of “ellipticity” for the sphere).

MGL command: cone x1 y1 z1 x2 y2 z2 r1 [r2=-1 'stl'='' edge=off]

Draw tube (or truncated cone if edge=false) between points p1, p2 with radius at the edges r1, r2. If r2<0 then it is supposed that r2=r1. The cone color is defined by string stl.

MGL command: circle x0 y0 r ['col'='r']

MGL command: circle x0 y0 z0 r ['col'='r']

Draw the circle with radius r and center at point p={x0, y0, z0}. Parameter col may contain

• colors for filling and boundary (second one if style ‘@’ is used, black color is used by default);
• ‘#’ for wire figure (boundary only);
• ‘@’ for filling and boundary.

MGL command: ellipse x1 y1 x2 y2 r ['col'='r' sh=1 asp=1]

MGL command: ellipse x1 y1 z1 x2 y2 z2 r ['col'='r' sh=1 asp=1]

Draw the ellipse with radius r and focal points p1, p2. Parameter col may contain

• colors for filling and boundary (second one if style ‘@’ is used, black color is used by default);
• ‘#’ for wire figure (boundary only);
• ‘@’ for filling and boundary.

MGL command: rhomb x1 y1 x2 y2 r ['col'='r' sh=1 asp=1]

MGL command: rhomb x1 y1 z1 x2 y2 z2 r ['col'='r' sh=1 asp=1]

Draw the rhombus with width r and edge points p1, p2. Parameter col may contain

• colors for filling and boundary (second one if style ‘@’ is used, black color is used by default);
• ‘#’ for wire figure (boundary only);
• ‘@’ for filling and boundary.

3.7 Text printing

These functions draw the text. There are functions for drawing text in arbitrary place, in arbitrary direction and along arbitrary curve. MathGL can use arbitrary font-faces and parse many TeX commands (for more details see Font styles). All these functions have 2 variant: for printing 8-bit text (char *) and for printing Unicode text (wchar_t *). In first case the conversion into the current locale is used. So sometimes you need to specify it by setlocale() function. The size argument control the size of text: if positive it give the value, if negative it give the value relative to SetFontSize(). The font type (STIX, arial, courier, times and so on) can be selected by function LoadFont(). See section Font settings.

The font parameters are described by string. This string may set the text color ‘wkrgbcymhRGBCYMHW’ (see Color styles). Also, after delimiter symbol ‘:’, it can contain characters of font type (‘rbiwou’) and/or align (‘LRC’) specification. The font types are: ‘r’ – roman (or regular) font, ‘i’ – italic style, ‘b’ – bold style, ‘w’ – wired style, ‘o’ – over-lined text, ‘u’ – underlined text. By default roman font is used. The align types are: ‘L’ – align left (default), ‘C’ – align center, ‘R’ – align right. For example, string ‘b:iC’ correspond to italic font style for centered text which printed by blue color.

If string contains symbols ‘aA’ then text is printed at absolute position {x, y} (supposed to be in range [0,1]) of subplot (for ‘a’) or picture (for ‘A’). If string contains symbol ‘@’ then box around text is drawn.

MGL command: text x y 'text' ['fnt'='' size=-1]

MGL command: text x y z 'text' ['fnt'='' size=-1]

The function plots the string text at position p with fonts specifying by the criteria fnt. The size of font is set by size parameter (default is FontSize).

MGL command: text x y dx dy 'text' ['fnt'=':L' size=-1]

MGL command: text x y z dx dy dz 'text' ['fnt'=':L' size=-1]

The function plots the string text at position p along direction d with specified size. Parameter fnt set text style and text position: above (‘T’) or under (‘t’) the line.

MGL command: fgets x y 'fname' [n=0 'fnt'='' size=-1.4]

MGL command: fgets x y z 'fname' [n=0 'fnt'='' size=-1.4]

Draws unrotated n-th line of file fname at position {x,y,z} with specified size. By default parameters from font command are used.

MGL command: text ydat 'text' ['fnt'='']

MGL command: text xdat ydat 'text' ['fnt'='']

MGL command: text xdat ydat zdat 'text' ['fnt'='']

The function draws text along the curve between points {x[i], y[i], z[i]} by font style fnt. The string fnt may contain symbols ‘t’ for printing the text under the curve (default), or ‘T’ for printing the text above the curve. The sizes of 1st dimension must be equal for all arrays x.nx=y.nx=z.nx. If array x is not specified then its an automatic array is used with values equidistantly distributed in interval [Min.x, Max.x] (see Ranges (bounding box)). If array z is not specified then z[i] = Min.z is used. String opt contain command options (see Command options).

3.8 Axis and Colorbar

These functions draw the “things for measuring”, like axis with ticks, colorbar with ticks, grid along axis, bounding box and labels for axis. For more information see Axis settings.

MGL command: axis ['dir'='xyz' 'stl'='']

Draws axes with ticks (see Axis settings). Parameter dir may contain:

• ‘xyz’ for drawing axis in corresponding direction;
• ‘_’ for disabling tick labels;
• ‘U’ for disabling rotation of tick labels;
• ‘AKDTVISO’ for drawing arrow at the end of axis;
• ‘a’ for forced adjusting of axis ticks.

Styles of ticks and axis can be overrided by using stl string.

MGL command: colorbar ['sch'='']

Draws colorbar. Parameter sch may contain:

• color scheme (see Color scheme);
• ‘<>^_’ for positioning at left, at right, at top or at bottom correspondingly;
• ‘I’ for positioning near bounding (by default, is positioned at edges of subplot);
• ‘A’ for using absolute coordinates.

MGL command: colorbar vdat ['sch'='']

The same as previous but with sharp colors sch (current palette if sch="") for values v.

MGL command: colorbar 'sch' x y [w=1 h=1]

The same as first one but at arbitrary position of subplot {x, y} (supposed to be in range [0,1]). Parameters w, h set the relative width and height of the colorbar.

MGL command: colorbar vdat 'sch' x y [w=1 h=1]

The same as previous but with sharp colors sch (current palette if sch="") for values v.

MGL command: grid ['dir'='xyz' 'pen'='B']

Draws grid lines perpendicular to direction determined by string parameter dir. The step of grid lines is the same as tick step for axis. The style of lines is determined by pen parameter (default value is dark blue solid line ‘B-’).

MGL command: box ['stl'='k' ticks=on]

Draws bounding box outside the plotting volume with color col. If col contain ‘@’ then filled faces are drawn. At this first color is used for faces (default is light yellow), last one for edges.

MGL command: xlabel 'text' [pos=1 shift=0]

MGL command: ylabel 'text' [pos=1 shift=0]

MGL command: zlabel 'text' [pos=1 shift=0]

MGL command: tlabel 'text' [pos=1 shift=0]

Prints the label text for axis dir=‘x’,‘y’,‘z’,‘t’ (here ‘t’ is “ternary” axis t=1-x-y). The position of label is determined by pos parameter. If pos=0 then label is printed at the center of axis. If pos>0 then label is printed at the maximum of axis. If pos<0 then label is printed at the minimum of axis. See section Text printing.

3.9 Legend

These functions draw legend to the graph (useful for 1D plotting). Legend entry is a pair of strings: one for style of the line, another one with description text (with included TeX parsing). The arrays of strings may be used directly or by accumulating first to the internal arrays (by function addlegend) and further plotting it. The position of the legend can be selected automatic or manually (even out of bounding box). Parameters fnt and size specify the font style and size (see Font settings). Parameter llen set the relative width of the line sample and the text indent. If line style string for entry is empty then the corresponding text is printed without indent. Parameter fnt may contain:

• font style for legend text;
• ‘A’ for positioning in absolute coordinates;
• ‘#’ for drawing box around legend;
• colors for background (first one) and border (second one) of legend. Note, that last color is always used as color for legend text.

MGL command: legend [pos=3 'fnt'='#' size=-0.8 llen=0.1]

Draws legend of accumulated legend entries by font fnt with size. Parameter pos sets the position of the legend: ‘0’ is bottom left corner, ‘1’ is bottom right corner, ‘2’ is top left corner, ‘3’ is top right corner (is default). Parameter fnt can contain colors for face (1st one), for border (2nd one) and for text (last one). If less than 3 colors are specified then the color for border is black (for 2 and less colors), and the color for face is white (for 1 or none colors). If string fnt contain ‘#’ then border around the legend is drawn.

MGL command: legend x y ['fnt'='#' size=-1 llen=0.1]

Draws legend of accumulated legend entries by font fnt with size. Position of legend is determined by parameter x, y which supposed to be normalized to interval [0,1].

MGL command: addlegend 'text' 'stl'

Adds string text to internal legend accumulator. The style of described line and mark is specified in string style (see Line styles).

MGL command: clearlegend

Clears saved legend strings.

MGL command: legendmarks val

Set the number of marks in the legend. By default 1 mark is used.

3.10 1D plotting

These functions perform plotting of 1D data. 1D means that data depended from only 1 parameter like parametric curve {x[i],y[i],z[i]}, i=1...n. By default (if absent) values of x[i] are equidistantly distributed in axis range, and z[i]=Min.z. The plots are drawn for each row if one of the data is the matrix. By any case the sizes of 1st dimension must be equal for all arrays x.nx=y.nx=z.nx.

String pen specifies the color and style of line and marks (see Line styles). By default (pen="") solid line with color from palette is used (see Palette and colors). Symbol ‘!’ set to use new color from palette for each point (not for each curve, as default). String opt contain command options (see Command options).

MGL command: plot ydat ['stl'='']

MGL command: plot xdat ydat ['stl'='']

MGL command: plot xdat ydat zdat ['stl'='']

These functions draw continuous lines between points {x[i], y[i], z[i]}. See also area, step, stem, tube, mark, error, belt, tens, tape.

MGL command: radar adat ['stl'='']

This functions draws radar chart which is continuous lines between points located on an radial lines (like plot in Polar coordinates). Parameter value in options opt set the additional shift of data (i.e. the data a+value is used instead of a). If value<0 then r=max(0, -min(value). If pen containt ‘#’ symbol then "grid" (radial lines and circle for r) is drawn. See also plot.

MGL command: step ydat ['stl'='']

MGL command: step xdat ydat ['stl'='']

MGL command: step xdat ydat zdat ['stl'='']

These functions draw continuous stairs for points to axis plane. See also plot, stem, tile, boxs.

MGL command: tens ydat cdat ['stl'='']

MGL command: tens xdat ydat cdat ['stl'='']

MGL command: tens xdat ydat zdat cdat ['stl'='']

These functions draw continuous lines between points {x[i], y[i], z[i]} with color defined by the special array c[i] (look like tension plot). String pen specifies the color scheme (see Color scheme) and style and/or width of line (see Line styles). See also plot, mesh, fall.

MGL command: tape ydat ['stl'='']

MGL command: tape xdat ydat ['stl'='']

MGL command: tape xdat ydat zdat ['stl'='']

These functions draw tapes of normals for curve between points {x[i], y[i], z[i]}. Initial tape(s) was selected in x-y plane (for ‘x’ in pen) and/or y-z plane (for ‘x’ in pen). The width of tape is proportional to SetBarWidth(). See also plot, flow, barwidth.

MGL command: area ydat ['stl'='']

MGL command: area xdat ydat ['stl'='']

MGL command: area xdat ydat zdat ['stl'='']

These functions draw continuous lines between points and fills it to axis plane. Also you can use gradient filling if number of specified colors is equal to 2*number of curves. See also plot, bars, stem, region.

MGL command: region ydat1 ydat2 ['stl'='']

MGL command: region xdat ydat1 ydat2 ['stl'='']

These functions fill area between 2 curves. Dimensions of arrays y1 and y2 must be equal. Also you can use gradient filling if number of specified colors is equal to 2*number of curves. If pen contain symbol ‘i’ then only area with y1<y<y2 will be filled else the area with y2<y<y1 will be filled too. See also area, bars, stem.

MGL command: stem ydat ['stl'='']

MGL command: stem xdat ydat ['stl'='']

MGL command: stem xdat ydat zdat ['stl'='']

These functions draw vertical lines from points to axis plane. See also area, bars, plot, mark.

MGL command: bars ydat ['stl'='']

MGL command: bars xdat ydat ['stl'='']

MGL command: bars xdat ydat zdat ['stl'='']

These functions draw vertical bars from points to axis plane. If string pen contain symbol ‘a’ then lines are drawn one above another (like summation). If string contain symbol ‘f’ then waterfall chart is drawn for determining the cumulative effect of sequentially introduced positive or negative values. You can give different colors for positive and negative values if number of specified colors is equal to 2*number of curves. See also barh, cones, area, stem, chart, barwidth.

MGL command: barh vdat ['stl'='']

MGL command: barh ydat vdat ['stl'='']

These functions draw horizontal bars from points to axis plane. If string contain symbol ‘a’ then lines are drawn one above another (like summation). If string contain symbol ‘f’ then waterfall chart is drawn for determining the cumulative effect of sequentially introduced positive or negative values. You can give different colors for positive and negative values if number of specified colors is equal to 2*number of curves. See also bars, barwidth.

MGL command: cones ydat ['stl'='']

MGL command: cones xdat ydat ['stl'='']

MGL command: cones xdat ydat zdat ['stl'='']

These functions draw cones from points to axis plane. If string contain symbol ‘a’ then cones are drawn one above another (like summation). You can give different colors for positive and negative values if number of specified colors is equal to 2*number of curves. See also bars, barwidth.

MGL command: chart adat ['col'='']

The function draws colored stripes (boxes) for data in array a. The number of stripes is equal to the number of rows in a (equal to a.ny). The color of each next stripe is cyclically changed from colors specified in string col or in palette Pal (see Palette and colors). Spaces in colors denote transparent “color” (i.e. corresponding stripe(s) are not drawn). The stripe width is proportional to value of element in a. Chart is plotted only for data with non-negative elements. If string col have symbol ‘#’ then black border lines are drawn. The most nice form the chart have in 3d (after rotation of coordinates) or in cylindrical coordinates (becomes so called Pie chart).

MGL command: boxplot adat ['stl'='']

MGL command: boxplot xdat adat ['stl'='']

These functions draw boxplot (also known as a box-and-whisker diagram) at points x[i]. This is five-number summaries of data a[i,j] (minimum, lower quartile (Q1), median (Q2), upper quartile (Q3) and maximum) along second (j-th) direction. See also plot, error, bars, barwidth.

MGL command: candle vdat1 ['stl'='']

MGL command: candle vdat1 vdat2 ['stl'='']

MGL command: candle vdat1 ydat1 ydat2 ['stl'='']

MGL command: candle vdat1 vdat2 ydat1 ydat2 ['stl'='']

MGL command: candle xdat vdat1 vdat2 ydat1 ydat2 ['stl'='']

These functions draw candlestick chart at points x[i]. This is a combination of a line-chart and a bar-chart, in that each bar represents the range of price movement over a given time interval. Wire (or white) candle correspond to price growth v1[i]<v2[i], opposite case – solid (or dark) candle. "Shadows" show the minimal y1 and maximal y2 prices. If v2 is absent then it is determined as v2[i]=v1[i+1]. See also plot, bars, barwidth.

MGL command: error ydat yerr ['stl'='']

MGL command: error xdat ydat yerr ['stl'='']

MGL command: error xdat ydat xerr yerr ['stl'='']

These functions draw error boxes {ex[i], ey[i]} at points {x[i], y[i]}. This can be useful, for example, in experimental points, or to show numeric error or some estimations and so on. If string pen contain symbol ‘@’ than large semitransparent mark is used instead of error box. See also plot, mark.

MGL command: mark ydat rdat ['stl'='']

MGL command: mark xdat ydat rdat ['stl'='']

MGL command: mark xdat ydat zdat rdat ['stl'='']

These functions draw marks with size r[i]*marksize at points {x[i], y[i], z[i]}. If you need to draw markers of the same size then you can use plot function with empty line style ‘ ’. For markers with size in axis range use error with style ‘@’. See also plot, textmark, error, stem.

MGL command: textmark ydat 'txt' ['stl'='']

MGL command: textmark ydat rdat 'txt' ['stl'='']

MGL command: textmark xdat ydat rdat 'txt' ['stl'='']

MGL command: textmark xdat ydat zdat rdat 'txt' ['stl'='']

These functions draw string txt as marks with size proportional to r[i]*marksize at points {x[i], y[i], z[i]}. By default (if omitted) r[i]=1. See also plot, mark, stem.

MGL command: label ydat 'txt' ['stl'='']

MGL command: label xdat ydat 'txt' ['stl'='']

MGL command: label xdat ydat zdat 'txt' ['stl'='']

These functions draw string txt at points {x[i], y[i], z[i]}. If string txt contain ‘%x’, ‘%y’, ‘%z’ or ‘%n’ then it will be replaced by the value of x-,y-,z-coordinate of the point or its index. See also plot, mark, textmark.

MGL command: tube ydat rdat ['stl'='']

MGL command: tube ydat rval ['stl'='']

MGL command: tube xdat ydat rdat ['stl'='']

MGL command: tube xdat ydat rval ['stl'='']

MGL command: tube xdat ydat zdat rdat ['stl'='']

MGL command: tube xdat ydat zdat rval ['stl'='']

These functions draw the tube with variable radius r[i] along the curve between points {x[i], y[i], z[i]}. See also plot.

MGL command: torus rdat zdat ['stl'='']

These functions draw surface which is result of curve {r, z} rotation around axis. If string pen contain symbols ‘x’ or ‘z’ then rotation axis will be set to specified direction (default is ‘y’). See also plot, axial.

3.11 2D plotting

These functions perform plotting of 2D data. 2D means that data depend from 2 independent parameters like matrix f(x_i,y_j), i=1...n, j=1...m. By default (if absent) values of x, y are equidistantly distributed in axis range. The plots are drawn for each z slice of the data. The minor dimensions of arrays x, y, z should be equal x.nx=z.nx && y.nx=z.ny or x.nx=y.nx=z.nx && x.ny=y.ny=z.ny. Arrays x and y can be vectors (not matrices as z). String sch sets the color scheme (see Color scheme) for plot. String opt contain command options (see Command options).

MGL command: surf zdat ['sch'='']

MGL command: surf xdat ydat zdat ['sch'='']

The function draws surface specified parametrically {x[i,j], y[i,j], z[i,j]}. If string sch have symbol ‘#’ then grid lines are drawn. See also mesh, dens, belt, tile, boxs, surfc, surfa.

MGL command: mesh zdat ['sch'='']

MGL command: mesh xdat ydat zdat ['sch'='']

The function draws mesh lines for surface specified parametrically {x[i,j], y[i,j], z[i,j]}. See also surf, fall, meshnum, cont, tens.

MGL command: fall zdat ['sch'='']

MGL command: fall xdat ydat zdat ['sch'='']

The function draws fall lines for surface specified parametrically {x[i,j], y[i,j], z[i,j]}. This plot can be used for plotting several curves shifted in depth one from another. If sch contain ‘x’ then lines are drawn along x-direction else (by default) lines are drawn along y-direction. See also belt, mesh, tens, meshnum.

MGL command: belt zdat ['sch'='']

MGL command: belt xdat ydat zdat ['sch'='']

The function draws belts for surface specified parametrically {x[i,j], y[i,j], z[i,j]}. This plot can be used as 3d generalization of plot). If sch contain ‘x’ then belts are drawn along x-direction else (by default) belts are drawn along y-direction. See also fall, surf, plot, meshnum.

MGL command: boxs zdat ['sch'='']

MGL command: boxs xdat ydat zdat ['sch'='']

The function draws vertical boxes for surface specified parametrically {x[i,j], y[i,j], z[i,j]}. See also surf, dens, tile, step.

MGL command: tile zdat ['sch'='']

MGL command: tile xdat ydat zdat ['sch'='']

The function draws horizontal tiles for surface specified parametrically {x[i,j], y[i,j], z[i,j]}. Such plot can be used as 3d generalization of step. See also surf, boxs, step, tiles.

MGL command: dens zdat ['sch'='']

MGL command: dens xdat ydat zdat ['sch'='']

The function draws density plot for surface specified parametrically {x[i,j], y[i,j], z[i,j]} at z = Min.z. If string sch have symbol ‘#’ then grid lines are drawn. See also surf, cont, contf, boxs, tile, dens[xyz].

MGL command: cont vdat zdat ['sch'='']

MGL command: cont vdat xdat ydat zdat ['sch'='']

The function draws contour lines for surface specified parametrically {x[i,j], y[i,j], z[i,j]} at z=v[k] or at z = Min.z if sch contain symbol ‘_’. Contours are plotted for z[i,j]=v[k] where v[k] are values of data array v. If string sch have symbol ‘t’ or ‘T’ then contour labels v[k] will be drawn below (or above) the contours. See also dens, contf, contd, axial, cont[xyz].

MGL command: cont zdat ['sch'='']

MGL command: cont xdat ydat zdat ['sch'='']

The same as previous with vector v of num-th elements equidistantly distributed in color range. Here num is equal to parameter value in options opt (default is 7).

MGL command: contf vdat zdat ['sch'='']

MGL command: contf vdat xdat ydat zdat ['sch'='']

The function draws solid (or filled) contour lines for surface specified parametrically {x[i,j], y[i,j], z[i,j]} at z=v[k] or at z = Min.z if sch contain symbol ‘_’. Contours are plotted for z[i,j]=v[k] where v[k] are values of data array v (must be v.nx>2). See also dens, cont, contd, contf[xyz].

MGL command: contf zdat ['sch'='']

MGL command: contf xdat ydat zdat ['sch'='']

The same as previous with vector v of num-th elements equidistantly distributed in color range. Here num is equal to parameter value in options opt (default is 7).

MGL command: contd vdat zdat ['sch'='']

MGL command: contd vdat xdat ydat zdat ['sch'='']

The function draws solid (or filled) contour lines for surface specified parametrically {x[i,j], y[i,j], z[i,j]} at z=v[k] (or at z = Min.z if sch contain symbol ‘_’) with manual colors. Contours are plotted for z[i,j]=v[k] where v[k] are values of data array v (must be v.nx>2). String sch sets the contour colors: the color of k-th contour is determined by character sch[k%strlen(sch)]. See also dens, cont, contf.

MGL command: contd zdat ['sch'='']

MGL command: contd xdat ydat zdat ['sch'='']

The same as previous with vector v of num-th elements equidistantly distributed in color range. Here num is equal to parameter value in options opt (default is 7).

MGL command: contv vdat zdat ['sch'='']

MGL command: contv vdat xdat ydat zdat ['sch'='']

The function draws vertical cylinder at contour lines for surface specified parametrically {x[i,j], y[i,j], z[i,j]} at z=v[k] or at z = Min.z if sch contain symbol ‘_’. Contours are plotted for z[i,j]=v[k] where v[k] are values of data array v. See also cont, contf.

MGL command: contv zdat ['sch'='']

MGL command: contv xdat ydat zdat ['sch'='']

The same as previous with vector v of num-th elements equidistantly distributed in color range. Here num is equal to parameter value in options opt (default is 7).

MGL command: axial vdat zdat ['sch'='']

MGL command: axial vdat xdat ydat zdat ['sch'='']

The function draws surface which is result of contour plot rotation for surface specified parametrically {x[i,j], y[i,j], z[i,j]}. Contours are plotted for z[i,j]=v[k] where v[k] are values of data array v. If string sch have symbol ‘#’ then wire plot is produced. If string contain symbols ‘x’ or ‘z’ then rotation axis will be set to specified direction (default is ‘y’). See also cont, contf, torus, surf3.

MGL command: axial zdat ['sch'='']

MGL command: axial xdat ydat zdat ['sch'='']

The same as previous with vector v of num-th elements equidistantly distributed in color range. Here num is equal to parameter value in options opt (default is 3).

MGL command: grid2 zdat ['sch'='']

MGL command: grid2 xdat ydat zdat ['sch'='']

The function draws grid lines for density plot of surface specified parametrically {x[i,j], y[i,j], z[i,j]} at z = Min.z. See also dens, cont, contf, meshnum.

3.12 3D plotting

These functions perform plotting of 3D data. 3D means that data depend from 3 independent parameters like matrix f(x_i,y_j,z_k), i=1...n, j=1...m, k=1...l. By default (if absent) values of x, y, z are equidistantly distributed in axis range. The minor dimensions of arrays x, y, z, a should be equal x.nx=a.nx && y.nx=a.ny && z.nz=a.nz or x.nx=y.nx=z.nx=a.nx && x.ny=y.ny=z.ny=a.ny && x.nz=y.nz=z.nz=a.nz. Arrays x, y and z can be vectors (not matrices as a). String sch sets the color scheme (see Color scheme) for plot. String opt contain command options (see Command options).

MGL command: surf3 adat val ['sch'='']

MGL command: surf3 xdat ydat zdat adat val ['sch'='']

The function draws isosurface plot for 3d array specified parametrically a[i,j,k](x[i,j,k], y[i,j,k], z[i,j,k]) at a(x,y,z)=val. If string contain ‘#’ then wire plot is produced. Note, that there is possibility of incorrect plotting due to uncertainty of cross-section defining if there are two or more isosurface intersections inside one cell. See also cloud, dens3, surf3c, surf3a, axial.

MGL command: surf3 adat ['sch'='']

MGL command: surf3 xdat ydat zdat adat ['sch'='']

Draws num-th uniformly distributed in color range isosurfaces for 3d data. Here num is equal to parameter value in options opt (default is 3).

MGL command: cloud adat ['sch'='']

MGL command: cloud xdat ydat zdat adat ['sch'='']

The function draws cloud plot for 3d data specified parametrically a[i,j,k](x[i,j,k], y[i,j,k], z[i,j,k]). This plot is a set of cubes with color and transparency proportional to value of a. The resulting plot is like cloud – low value is transparent but higher ones are not. The number of plotting cells depend on MeshNum. If string sch contain symbol ‘.’ then lower quality plot will produced with much low memory usage. If string sch contain symbol ‘!’ then transparency will be inversed, i.e. higher become transparent and lower become not transparent. See also surf3, meshnum.

MGL command: dens3 adat ['sch'='' sval=-1]

MGL command: dens3 xdat ydat zdat adat ['sch'='' sval=-1]

The function draws density plot for 3d data specified parametrically a[i,j,k](x[i,j,k], y[i,j,k], z[i,j,k]). Density is plotted at slice sVal in direction {‘x’, ‘y’, ‘z’} if sch contain corresponding symbol (by default, ‘y’ direction is used). If string stl have symbol ‘#’ then grid lines are drawn. See also cont3, contf3, dens, grid3.

MGL command: cont3 vdat adat ['sch'='' sval=-1]

MGL command: cont3 vdat xdat ydat zdat adat ['sch'='' sval=-1]

The function draws contour plot for 3d data specified parametrically a[i,j,k](x[i,j,k], y[i,j,k], z[i,j,k]). Contours are plotted for values specified in array v at slice sVal in direction {‘x’, ‘y’, ‘z’} if sch contain corresponding symbol (by default, ‘y’ direction is used). If string stl have symbol ‘#’ then grid lines are drawn. If string stl have symbol ‘t’ or ‘T’ then contour labels will be drawn below (or above) the contours. See also dens3, contf3, cont, grid3.

MGL command: cont3 adat ['sch'='' sval=-1]

MGL command: cont3 xdat ydat zdat adat ['sch'='' sval=-1]

The same as previous with vector v of num-th elements equidistantly distributed in color range. Here num is equal to parameter value in options opt (default is 7).

MGL command: contf3 vdat adat ['sch'='' sval=-1]

MGL command: contf3 vdat xdat ydat zdat adat ['sch'='' sval=-1]

The function draws solid (or filled) contour plot for 3d data specified parametrically a[i,j,k](x[i,j,k], y[i,j,k], z[i,j,k]). Contours are plotted for values specified in array v at slice sVal in direction {‘x’, ‘y’, ‘z’} if sch contain corresponding symbol (by default, ‘y’ direction is used). If string stl have symbol ‘#’ then grid lines are drawn. If string stl have symbol ‘t’ or ‘T’ then contour labels will be drawn below (or above) the contours. See also dens3, cont3, contf, grid3.

MGL command: contf3 adat ['sch'='' sval=-1]

MGL command: contf3 xdat ydat zdat adat ['sch'='' sval=-1]

The same as previous with vector v of num-th elements equidistantly distributed in color range. Here num is equal to parameter value in options opt (default is 7).

MGL command: grid3 adat ['sch'='' sval=-1]

MGL command: grid3 xdat ydat zdat adat ['sch'='' sval=-1]

The function draws grid for 3d data specified parametrically a[i,j,k](x[i,j,k], y[i,j,k], z[i,j,k]). Grid is plotted at slice sVal in direction {‘x’, ‘y’, ‘z’} if sch contain corresponding symbol (by default, ‘y’ direction is used). See also cont3, contf3, dens3, grid2, meshnum.

MGL command: beam tr g1 g2 adat rval ['sch'='' flag=0 num=3]

Draws the isosurface for 3d array a at constant values of a=val. This is special kind of plot for a specified in accompanied coordinates along curve tr with orts g1, g2 and with transverse scale r. Variable flag is bitwise: ‘0x1’ - draw in accompanied (not laboratory) coordinates; ‘0x2’ - draw projection to \rho-z plane; ‘0x4’ - draw normalized in each slice field. The x-size of data arrays tr, g1, g2 must be nx>2. The y-size of data arrays tr, g1, g2 and z-size of the data array a must be equal. See also surf3.

3.13 Dual plotting

These plotting functions draw two matrix simultaneously. There are 5 generally different types of data representations: surface or isosurface colored by other data (SurfC, Surf3C), surface or isosurface transpared by other data (SurfA, Surf3A), tiles with variable size (TileS), mapping diagram (Map), STFA diagram (STFA). By default (if absent) values of x, y, z are equidistantly distributed in axis range. The minor dimensions of arrays x, y, z, c should be equal. Arrays x, y (and z for Surf3C, Surf3A) can be vectors (not matrices as c). String sch sets the color scheme (see Color scheme) for plot. String opt contain command options (see Command options).

MGL command: surfc zdat cdat ['sch'='']

MGL command: surfc xdat ydat zdat cdat ['sch'='']

The function draws surface specified parametrically {x[i,j], y[i,j], z[i,j]} and color it by matrix c[i,j]. If string sch have symbol ‘#’ then grid lines are drawn. All dimensions of arrays z and c must be equal. Surface is plotted for each z slice of the data. See also surf, surfa, surf3c.

MGL command: surf3c adat cdat val ['sch'='']

MGL command: surf3c xdat ydat zdat adat cdat val ['sch'='']

The function draws isosurface plot for 3d array specified parametrically a[i,j,k](x[i,j,k], y[i,j,k], z[i,j,k]) at a(x,y,z)=val. It is mostly the same as surf3 function but the color of isosurface depends on values of array c. If string contain ‘#’ then wire plot is produced. See also surf3, surfc, surf3a.

MGL command: surf3c adat cdat ['sch'='']

MGL command: surf3c xdat ydat zdat adat cdat ['sch'='']

Draws num-th uniformly distributed in color range isosurfaces for 3d data. Here num is equal to parameter value in options opt (default is 3).

MGL command: surfa zdat cdat ['sch'='']

MGL command: surfa xdat ydat zdat cdat ['sch'='']

The function draws surface specified parametrically {x[i,j], y[i,j], z[i,j]} and transparent it by matrix c[i,j]. If string sch have symbol ‘#’ then grid lines are drawn. All dimensions of arrays z and c must be equal. Surface is plotted for each z slice of the data. See also surf, surfc, surf3a.

MGL command: surf3a adat cdat val ['sch'='']

MGL command: surf3a xdat ydat zdat adat cdat val ['sch'='']

The function draws isosurface plot for 3d array specified parametrically a[i,j,k](x[i,j,k], y[i,j,k], z[i,j,k]) at a(x,y,z)=val. It is mostly the same as surf3 function but the color of isosurface depends on values of array c. If string contain ‘#’ then wire plot is produced. See also surf3, surfc, surf3a.

MGL command: surf3a adat cdat ['sch'='']

MGL command: surf3a xdat ydat zdat adat cdat ['sch'='']

Draws num-th uniformly distributed in color range isosurfaces for 3d data. At this array c can be vector with values of transparency and num=c.nx. In opposite case num is equal to parameter value in options opt (default is 3).

MGL command: tiles zdat rdat ['sch'='']

MGL command: tiles xdat ydat zdat rdat ['sch'='']

The function draws horizontal tiles for surface specified parametrically {x[i,j], y[i,j], z[i,j]}. It is mostly the same as tile but the size of tiles is determined by r array. This is some kind of “transparency” useful for exporting to EPS files. Tiles is plotted for each z slice of the data. See also surfa, tile.

MGL command: map udat vdat ['sch'='']

MGL command: map xdat ydat udat vdat ['sch'='']

The function draws mapping plot for matrices {ax, ay } which parametrically depend on coordinates x, y. The initial position of the cell (point) is marked by color. Height is proportional to Jacobian(ax,ay). This plot is like Arnold diagram ???. If string sch contain symbol ‘.’ then the color ball at matrix knots are drawn otherwise face is drawn.

MGL command: stfa re im dn ['sch'='']

MGL command: stfa xdat ydat re im dn ['sch'='']

Draws spectrogram of complex array re+i*im for Fourier size of dn points at plane z=Min.z. For example in 1D case, result is density plot of data res[i,j]=|\sum_d^dn exp(I*j*d)*(re[i*dn+d]+I*im[i*dn+d])|/dn with size {int(nx/dn), dn, ny}. At this array re, im parametrically depend on coordinates x, y. The size of re and im must be the same. The minor dimensions of arrays x, y, re should be equal. Arrays x, y can be vectors (not matrix as re).

3.14 Vector fields

These functions perform plotting of 2D and 3D vector fields. There are 5 generally different types of vector fields representations: simple vector field (Vect), vectors along the curve (Traj), vector field by dew-drops (Dew), flow threads (Flow, FlowP), flow pipes (Pipe). By default (if absent) values of x, y, z are equidistantly distributed in axis range. The minor dimensions of arrays x, y, z, ax should be equal. The size of ax, ay and az must be equal. Arrays x, y, z can be vectors (not matrices as ax). String sch sets the color scheme (see Color scheme) for plot. String opt contain command options (see Command options).

MGL command: traj xdat ydat udat vdat ['sch'='']

MGL command: traj xdat ydat zdat udat vdat wdat ['sch'='']

The function draws vectors {ax, ay, az} along a curve {x, y, z}. The length of arrows are proportional to \sqrtax^2+ay^2+az^2. String pen specifies the color (see Line styles). By default (pen="") color from palette is used (see Palette and colors). Option value set the vector length factor (if non-zero) or vector length to be proportional the distance between curve points (if value=0). The minor sizes of all arrays must be equal and large 2. The plots are drawn for each row if one of the data is the matrix. See also vect.

MGL command: vect udat vdat ['sch'='']

MGL command: vect xdat ydat udat vdat ['sch'='']

The function draws plane vector field plot for the field {ax, ay} depending parametrically on coordinates x, y at level z=Min.z. The length and color of arrows are proportional to \sqrtax^2+ay^2. The number of arrows depend on meshnum. The apperance of the hachures (arrows) can be changed by symbols:

• ‘f’ for drawing arrows with fixed lengths,
• ‘>’, ‘<’ for drawing arrows to or from the cell point (default is centering),
• ‘.’ for drawing hachures with dots instead of arrows,
• ‘=’ for enabling color gradient along arrows.

See also flow, dew.

MGL command: vect udat vdat wdat ['sch'='']

MGL command: vect xdat ydat zdat udat vdat wdat ['sch'='']

This is 3D version of the first functions. Here arrays ax, ay, az must be 3-ranged tensors with equal sizes and the length and color of arrows is proportional to \sqrtax^2+ay^2+az^2.

MGL command: dew udat vdat ['sch'='']

MGL command: dew xdat ydat udat vdat ['sch'='']

The function draws dew-drops for plane vector field {ax, ay} depending parametrically on coordinates x, y at level z=Min.z. Note that this is very expensive plot in memory usage and creation time! The color of drops is proportional to \sqrtax^2+ay^2. The number of drops depend on meshnum. See also vect.

MGL command: flow udat vdat ['sch'='']

MGL command: flow xdat ydat udat vdat ['sch'='']

The function draws flow threads for the plane vector field {ax, ay} parametrically depending on coordinates x, y at level z = Min.z. Number of threads is proportional to value option (default is 5). String sch may contain:

• color scheme – up-half (warm) corresponds to normal flow (like attractor), bottom-half (cold) corresponds to inverse flow (like source);
• ‘#’ for starting threads from edges only;
• ‘v’ for drawing arrows on the threads;
• ‘x’, ‘z’ for drawing tapes of normals in x-y and y-z planes correspondingly.

See also pipe, vect, tape, barwidth.

MGL command: flow udat vdat wdat ['sch'='']

MGL command: flow xdat ydat zdat udat vdat wdat ['sch'='']

This is 3D version of the first functions. Here arrays ax, ay, az must be 3-ranged tensors with equal sizes and the color of line is proportional to \sqrtax^2+ay^2+az^2.

MGL command: flow x0 y0 udat vdat ['sch'='']

MGL command: flow x0 y0 xdat ydat udat vdat ['sch'='']

The same as first one (flow) but draws single flow thread starting from point p0={x0,y0,z0}.

MGL command: flow x0 y0 z0 udat vdat wdat ['sch'='']

MGL command: flow x0 y0 z0 xdat ydat zdat udat vdat wdat ['sch'='']

This is 3D version of the previous functions.

MGL command: grad pdat ['sch'='']

MGL command: grad xdat ydat pdat ['sch'='']

MGL command: grad xdat ydat zdat pdat ['sch'='']

The function draws gradient lines for scalar field phi[i,j] (or phi[i,j,k] in 3d case) specified parametrically {x[i,j,k], y[i,j,k], z[i,j,k]}. Number of lines is proportional to value option (default is 5). If value<0 then lines start only from edges of axis range. Warm color corresponds to normal flow (like minimum). Cold one corresponds to inverse flow (like maximum). If string sch contain symbol ‘v’ then arrows are drawn on flow threads. See also dens, cont, flow.

MGL command: pipe udat vdat ['sch'='' r0=0.05]

MGL command: pipe xdat ydat udat vdat ['sch'='' r0=0.05]

The function draws flow pipes for the plane vector field {ax, ay} parametrically depending on coordinates x, y at level z = Min.z. Number of pipes is proportional to value option (default is 5). If ‘#’ symbol is specified then pipes start only from edges of axis range. The color of lines is proportional to \sqrtax^2+ay^2. Warm color corresponds to normal flow (like attractor). Cold one corresponds to inverse flow (like source). Parameter r0 set the base pipe radius. If r0<0 or symbol ‘i’ is specified then pipe radius is inverse proportional to amplitude. The vector field is plotted for each z slice of ax, ay. See also flow, vect.

MGL command: pipe udat vdat wdat ['sch'='' r0=0.05]

MGL command: pipe xdat ydat zdat udat vdat wdat ['sch'='' r0=0.05]

This is 3D version of the first functions. Here arrays ax, ay, az must be 3-ranged tensors with equal sizes and the color of line is proportional to \sqrtax^2+ay^2+az^2.

3.15 Other plotting

These functions perform miscellaneous plotting. There is unstructured data points plots (Dots), surface reconstruction (Crust), surfaces on the triangular or quadrangular mesh (TriPlot, TriCont, QuadPlot), textual formula plotting (Plots by formula), data plots at edges (Dens[XYZ], Cont[XYZ], ContF[XYZ]). Each type of plotting has similar interface. There are 2 kind of versions which handle the arrays of data and coordinates or only single data array. Parameters of color scheme are specified by the string argument. See section Color scheme.

MGL command: densx dat ['sch'='' sval=nan]

MGL command: densy dat ['sch'='' sval=nan]

MGL command: densz dat ['sch'='' sval=nan]

These plotting functions draw density plot in x, y, or z plain. If a is a tensor (3-dimensional data) then interpolation to a given sVal is performed. These functions are useful for creating projections of the 3D data array to the bounding box. For example, code like

gr->DensX(c.Sum("x"),"BbcyrR",-1); gr->DensY(c.Sum("y"),"",1); gr->DensZ(c.Sum("z"),"",-1);

will produce the following picture. See also ContXYZ, ContFXYZ, dens, Data manipulation.

MGL command: contx dat ['sch'='' sval=nan]

MGL command: conty dat ['sch'='' sval=nan]

MGL command: contz dat ['sch'='' sval=nan]

These plotting functions draw contour lines in x, y, or z plain. If a is a tensor (3-dimensional data) then interpolation to a given sVal is performed. These functions are useful for creating projections of the 3D data array to the bounding box. For example, code like

gr->ContX(c.Sum("x"),"BbcyrR",-1); gr->ContY(c.Sum("y"),0,1); gr->ContZ(c.Sum("z"),0,-1);

will produce the following picture. See also ContFXYZ, DensXYZ, cont, Data manipulation.

MGL command: contfx dat ['sch'='' sval=nan]

MGL command: contfy dat ['sch'='' sval=nan]

MGL command: contfz dat ['sch'='' sval=nan]

These plotting functions draw solid contours in x, y, or z plain. If a is a tensor (3-dimensional data) then interpolation to a given sVal is performed. These functions are useful for creating projections of the 3D data array to the bounding box. For example, code like

gr->ContFX(c.Sum("x"),"BbcyrR",-1); gr->ContFY(c.Sum("y"),0,1); gr->ContFZ(c.Sum("z"),0,-1);

will produce the following picture. See also ContFXYZ, DensXYZ, cont, Data manipulation.

MGL command: fplot 'y(x)' ['pen'='']

Draws command function ‘y(x)’ at plane z=Min.z where ‘x’ variable is changed in xrange. You do not need to create the data arrays to plot it. See also plot.

MGL command: fplot 'x(t)' 'y(t)' 'z(t)' ['pen'='']

Draws command parametrical curve {‘x(t)’, ‘y(t)’, ‘z(t)’} where ‘t’ variable is changed in range [0, 1]. You do not need to create the data arrays to plot it. See also plot.

MGL command: fsurf 'z(x,y)' ['sch'='']

Draws command surface for function ‘z(x,y)’ where ‘x’, ‘y’ variable are changed in xrange, yrange. You do not need to create the data arrays to plot it. See also surf.

MGL command: fsurf 'x(u,v)' 'y(u,v)' 'z(u,v)' ['sch'='']

Draws command parametrical surface {‘x(u,v)’, ‘y(u,v)’, ‘z(u,v)’} where ‘u’, ‘v’ variable are changed in range [0, 1]. You do not need to create the data arrays to plot it. See also surf.

MGL command: triplot idat xdat ydat ['sch'='']

MGL command: triplot idat xdat ydat zdat ['sch'='']

MGL command: triplot idat xdat ydat zdat cdat ['sch'='']

The function draws the surface of triangles. Triangle vertexes are set by indexes id of data points {x[i], y[i], z[i]}. String sch sets the color scheme. If string contain ‘#’ then wire plot is produced. First dimensions of id must be 3 or greater. Arrays x, y, z must have equal sizes. Parameter c set the colors of triangles (if id.ny=c.nx) or colors of vertexes (if x.nx=c.nx). See also dots, crust, quadplot.

MGL command: tricont vdat idat xdat ydat zdat cdat ['sch'='']

MGL command: tricont vdat idat xdat ydat zdat ['sch'='']

MGL command: tricont idat xdat ydat zdat ['sch'='']

The function draws contour lines for surface of triangles at z=v[k] (or at z = Min.z if sch contain symbol ‘_’). Triangle vertexes are set by indexes id of data points {x[i], y[i], z[i]}. Contours are plotted for z[i,j]=v[k] where v[k] are values of data array v. String sch sets the color scheme. Array c (if specified) is used for contour coloring. First dimensions of id must be 3 or greater. Arrays x, y, z must have equal sizes. Parameter c set the colors of triangles (if id.ny=c.nx) or colors of vertexes (if x.nx=c.nx). See also triplot, cont.

MGL command: quadplot idat xdat ydat ['sch'='']

MGL command: quadplot idat xdat ydat zdat ['sch'='']

MGL command: quadplot idat xdat ydat zdat cdat ['sch'='']

The function draws the surface of quadrangles. Quadrangles vertexes are set by indexes id of data points {x[i], y[i], z[i]}. String sch sets the color scheme. If string contain ‘#’ then wire plot is produced. First dimensions of id must be 4 or greater. Arrays x, y, z must have equal sizes. Parameter c set the colors of quadrangles (if id.ny=c.nx) or colors of vertexes (if x.nx=c.nx). See also triplot.

MGL command: dots xdat ydat zdat ['sch'='']

MGL command: dots xdat ydat zdat adat ['sch'='']

The function draws the arbitrary placed points {x[i], y[i], z[i]}. String sch sets the color scheme. If array a is specified then it define the transparency of dots. Arrays x, y, z, a must have equal sizes. See also crust, mark, plot.

MGL command: crust xdat ydat zdat ['sch'='']

The function reconstruct and draws the surface for arbitrary placed points {x[i], y[i], z[i]}. String sch sets the color scheme. If string contain ‘#’ then wire plot is produced. Arrays x, y, z must have equal sizes. See also dots, triplot.

3.16 Nonlinear fitting

These functions fit data to formula. Fitting goal is to find formula parameters for the best fit the data points, i.e. to minimize the sum \sum_i (f(x_i, y_i, z_i) - a_i)^2/s_i^2. At this, 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’). Usually user should supply initial values for fitted parameters by ini variable. But if he/she don’t supply it then the zeros are used. Parameter print=true switch on printing the found coefficients to Message (see Error handling).

Functions Fit() and FitS() do not draw the obtained data themselves. They fill the data fit by formula ‘f’ with found coefficients and return it. At this, the ‘x,y,z’ coordinates are equidistantly distributed in the axis range. Number of points in fit is selected as maximal value of fit size and the value of mglFitPnts. Note, that this functions use GSL library and do something only if MathGL was compiled with GSL support.

MGL command: fits res adat sdat 'func' 'var' [ini=0]

MGL command: fits res xdat adat sdat 'func' 'var' [ini=0]

MGL command: fits res xdat ydat adat sdat 'func' 'var' [ini=0]

MGL command: fits res xdat ydat zdat adat sdat 'func' 'var' [ini=0]

Fit data along x-, y- and z-directions for array specified parametrically a[i,j,k](x[i,j,k], y[i,j,k], z[i,j,k]) with weight factor s[i,j,k].

MGL command: fit res adat sdat 'func' 'var' [ini=0]

MGL command: fit res xdat adat sdat 'func' 'var' [ini=0]

MGL command: fit res xdat ydat adat sdat 'func' 'var' [ini=0]

MGL command: fit res xdat ydat zdat adat sdat 'func' 'var' [ini=0]

Fit data along x-, y- and z-directions for array specified parametrically a[i,j,k](x[i,j,k], y[i,j,k], z[i,j,k]) with weight factor 1.

MGL command: putsfit x y ['pre'='' 'fnt'='' size=-1]

Print last fitted formula with found coefficients (as numbers) at position p0. The string prefix will be printed before formula. All other parameters are the same as in Text printing.

3.17 Data manipulation

MGL command: hist RES xdat adat

MGL command: hist RES xdat ydat adat

MGL command: hist RES xdat ydat zdat adat

These functions make distribution (histogram) of data. They do not draw the obtained data themselves. These functions can be useful if user have data defined for random points (for example, after PIC simulation) and he want to produce a plot which require regular data (defined on grid(s)). The range for grids is always selected as axis range. Arrays x, y, z define the positions (coordinates) of random points. Array a define the data value. Number of points in output array res is selected as maximal value of res size and the value of mglFitPnts.

MGL command: fill dat 'eq'

MGL command: fill dat 'eq' vdat

MGL command: fill dat 'eq' vdat wdat

Fills the value of array according to the formula in string eq. Formula is an arbitrary expression depending on variables ‘x’, ‘y’, ‘z’, ‘u’, ‘v’, ‘w’. Coordinates ‘x’, ‘y’, ‘z’ are supposed to be normalized in axis range. Variable ‘u’ is the original value of the array. Variables ‘v’ and ‘w’ are values of arrays v, w which can be NULL (i.e. can be omitted).

MGL command: pde RES 'ham' ini_re ini_im [dz=0.1 k0=100]

Solves equation du/dz = i*k0*ham(p,q,x,y,z,|u|)[u], where p=-i/k0*d/dx, q=-i/k0*d/dy are pseudo-differential operators. Parameters ini_re, ini_im specify real and imaginary part of initial field distribution. Parameters Min, Max set the bounding box for the solution. Note, that really this ranges are increased by factor 3/2 for purpose of reducing reflection from boundaries. Parameter dz set the step along evolutionary coordinate z. At this moment, simplified form of function ham is supported – all “mixed” terms (like ‘x*p’->x*d/dx) are excluded. For example, in 2D case this function is effectively ham = f(p,z) + g(x,z,u). However commutable combinations (like ‘x*q’->x*d/dy) are allowed. Here variable ‘u’ is used for field amplitude |u|. This allow one solve nonlinear problems – for example, for nonlinear Shrodinger equation you may set ham="p^2 + q^2 - u^2". You may specify imaginary part for wave absorption, like ham = "p^2 + i*x*(x>0)", but only if dependence on variable ‘i’ is linear (i.e. ham = hre+i*him).

3.18 IDTF functions

These functions provide IDTF specific features. In all other cases they do nothing.

4. Data processing

This chapter describe commands for allocation, resizing, loading and saving, modifying of data arrays. Also it can numerically differentiate and integrate data, interpolate, fill data by formula and so on. Class supports data with dimensions up to 3 (like function of 3 variables – x,y,z). The internal representation of numbers is float. Float type was chosen because it has smaller size in memory and usually it has enough precision in plotting purposes. Data arrays are denoted by Small Caps (like DAT) if it can be (re-)created by MGL commands.

4.1 Public variables

MGL don’t support direct access to data arrays. See section Data filling

4.2 Data constructor

There are many functions, which can create data for output (see Data filling, File I/O, Make another data, Global functions). Here I put most useful of them.

MGL command: new DAT [nx=1 'eq']

MGL command: new DAT nx ny ['eq']

MGL command: new DAT nx ny nz ['eq']

Default constructor. Allocates the memory for data array and initializes it by zero. If string eq is specified then data will be filled by corresponding formula as in fill function.

MGL command: copy DAT dat2 ['eq'='']

MGL command: copy DAT val

Copy constructor. Allocates the memory for data array and copy values from other array. At this, if parameter eq is specified then the data will be modified by corresponding formula similarly to fill function.

MGL command: read DAT 'fname'

Reads data from tab-separated text file with auto determining sizes of the data.

MGL command: delete dat

Deletes the instance of class mglData.

4.3 Data resizing

MGL command: new DAT [nx=1 ny=1 nz=1]

Creates or recreates the array with specified size and fills it by zero. This function does nothing if one of parameters mx, my, mz is zero or negative.

MGL command: rearrange dat mx [my=0 mz=0]

Rearrange dimensions without changing data array so that resulting sizes should be mx*my*mz < nx*ny*nz. If some of parameter my or mz are zero then it will be selected to optimal fill of data array. For example, if my=0 then it will be change to my=nx*ny*nz/mx and mz will be 1.

MGL command: transpose dat ['dim'='yxz']

Transposes (shift order of) dimensions of the data. New order of dimensions is specified in string dim. This function can be useful also after reading of one-dimensional data.

MGL command: extend dat n1 [n2=0]

Increase the dimensions of the data by inserting new (|n1|+1)-th slices after (for n1>0) or before (for n1<0) of existed one. It is possible to insert 2 dimensions simultaneously for 1d data by using parameter n2. Data to new slices is copy from existed one. For example, for n1>0 new array will be a_ij^new = a_i^old where j=0...n1. Correspondingly, for n1<0 new array will be a_ij^new = a_j^old where i=0...|n1|.

MGL command: squeeze dat rx [ry=1 rz=1 sm=off]

Reduces the data size by excluding data elements which indexes are not divisible by rx, ry, rz correspondingly. Parameter smooth set to use smoothing (i.e. out[i]=\sum_{j=i,i+r} a[j]/r) or not (i.e. out[i]=a[j*r]).

MGL command: crop dat n1 n2 'dir'

Cuts off edges of the data i<n1 and i>n2 if n2>0 or i>n[xyz]-n2 if n2<=0 along direction dir.

MGL command: insert dat 'dir' [pos=off num=0]

Insert num slices along dir-direction at position pos and fill it by zeros.

MGL command: delete dat 'dir' [pos=off num=0]

Delete num slices along dir-direction at position pos.

MGL command: sort dat idx [idy=-1]

Sort data rows (or slices in 3D case) by values of specified column idx (or cell {idx,idy} for 3D case). Note, this function is not thread safe!

4.4 Data filling

MGL command: list DAT v1 ...

Creates new variable with name dat and fills it by numeric values of command arguments v1 .... Command can create one-dimensional and two-dimensional arrays with arbitrary values. For creating 2d array the user should use delimiter ‘|’ which means that the following values lie in next row. Array sizes are [maximal of row sizes * number of rows]. For example, command list 1 | 2 3 creates the array [1 0; 2 3]. Note, that the maximal number of arguments is 1000.

MGL command: list DAT d1 ...

Creates new variable with name dat and fills it by data values of arrays of command arguments d1 .... Command can create two-dimensional or three-dimensional (if arrays in arguments are 2d arrays) arrays with arbitrary values. Minor dimensions of all arrays in arguments should be equal to dimensions of first array d1. In the opposite case the argument will be ignored. Note, that the maximal number of arguments is 1000.

MGL command: var DAT num v1 [v2=nan]

Creates new variable with name dat for one-dimensional array of size num. Array elements are equidistantly distributed in range [v1, v2]. If v2=nan then v2=v1 is used.

MGL command: fill dat v1 v2 ['dir'='x']

Equidistantly fills the data values to range [v1, v2] in direction dir={‘x’,‘y’,‘z’}.

MGL command: fill dat 'eq'

MGL command: fill dat 'eq' vdat

MGL command: fill dat 'eq' vdat wdat

Fills the value of array according to the formula in string eq. Formula is an arbitrary expression depending on variables ‘x’, ‘y’, ‘z’, ‘u’, ‘v’, ‘w’. Coordinates ‘x’, ‘y’, ‘z’ are supposed to be normalized in axis range of canvas gr (in difference from Modify functions). Variable ‘u’ is the original value of the array. Variables ‘v’ and ‘w’ are values of vdat, wdat which can be NULL (i.e. can be omitted).

MGL command: modify dat 'eq' [dim=0]

MGL command: modify dat 'eq' vdat

MGL command: modify dat 'eq' vdat wdat

The same as previous ones but coordinates ‘x’, ‘y’, ‘z’ are supposed to be normalized in range [0,1]. If dim>0 is specified then modification will be fulfilled only for slices >=dim.

MGL command: fillsample dat 'how'

Fills data by ’x’ or ’k’ samples for Hankel (’h’) or Fourier (’f’) transform.

MGL command: put dat val [i=: j=: k=:]

Sets value(s) of array a[i, j, k] = val. Negative indexes i, j, k=-1 set the value val to whole range in corresponding direction(s). For example, Put(val,-1,0,-1); sets a[i,0,j]=val for i=0...(nx-1), j=0...(nz-1).

MGL command: put dat vdat [i=: j=: k=:]

Copies value(s) from array v to the range of original array. Negative indexes i, j, k=-1 set the range in corresponding direction(s). At this minor dimensions of array v should be large than corresponding dimensions of this array. For example, Put(v,-1,0,-1); sets a[i,0,j]=v.ny>nz ? v[i,j] : v[i], where i=0...(nx-1), j=0...(nz-1) and condition v.nx>=nx is true.

MGL command: idset dat 'ids'

Sets the symbol ids for data columns. The string should contain one symbol ’a’...’z’ per column. These ids are used in column function.

4.5 File I/O

MGL command: read DAT 'fname'

Reads data from tab-separated text file with auto determining sizes of the data. Double newline means the beginning of new z-slice.

MGL command: read DAT 'fname' mx [my=1 mz=1]

Reads data from text file with specified data sizes. This function does nothing if one of parameters mx, my or mz is zero or negative.

MGL command: readmat DAT 'fname' [dim=2]

Read data from text file with size specified at beginning of the file by first dim numbers. At this, variable dim set data dimensions.

MGL command: readall DAT 'templ' v1 v2 [dv=1 slice=off]

Join data arrays from several text files. The file names are determined by function call sprintf(fname,templ,val);, where val changes from from to to with step step. The data load one-by-one in the same slice if as_slice=false or as slice-by-slice if as_slice=true.

MGL command: readall DAT 'templ' [slice=off]

Join data arrays from several text files which filenames satisfied the template templ (for example, templ="t_*.dat"). The data load one-by-one in the same slice if as_slice=false or as slice-by-slice if as_slice=true.

MGL command: save dat 'fname'

Saves the whole data array (for ns=-1) or only ns-th slice to text file.

MGL command: readhdf DAT 'fname' 'dname'

Reads data array named dname from HDF5 or HDF4 file. This function does nothing if HDF5|HDF4 was disabled during library compilation.

MGL command: savehdf dat 'fname' 'dname'

Saves data array named dname to HDF5 file. This function does nothing if HDF5 was disabled during library compilation.

MGL command: datas 'fname'

Put data names from HDF5 file fname into buf as ’\t’ separated fields. In MGL version the list of data names will be printed as message. This function does nothing if HDF5 was disabled during library compilation.

MGL command: import DAT 'fname' 'sch' [v1=0 v2=1]

Reads data from bitmap file (now support only PNG format). The RGB values of bitmap pixels are transformed to float values in range [v1, v2] using color scheme scheme (see section Color scheme).

MGL command: export dat 'fname' 'sch' [v1=0 v2=0]

Saves data matrix (or ns-th slice for 3d data) to bitmap file (now support only PNG format). The data values are transformed from range [v1, v2] to RGB pixels of bitmap using color scheme scheme (see section Color scheme). If v1>=v2 then the values of v1, v2 are automatically determined as minimal and maximal value of the data array.

4.6 Make another data

MGL command: subdata RES dat xx [yy=: zz=:]

Extracts sub-array data from the original data array keeping fixed positive index. For example SubData(-1,2) extracts 3d row (indexes are zero based), SubData(4,-1) extracts 5th column, SubData(-1,-1,3) extracts 4th slice and so on. If argument(s) are non-integer then linear interpolation between slices is used. In MGL version this command usually is used as inline one dat(xx,yy,zz).

MGL command: subdata RES dat xdat [ydat=: zdat=:]

Extracts sub-array data from the original data array for indexes specified by arrays xx, yy, zz (indirect access). This function work like previous one for 1D arguments or numbers, and resulting array dimensions are equal dimensions of 1D arrays for corresponding direction. For 2D and 3D arrays in arguments, the resulting array have the same dimensions as input arrays. The dimensions of all argument must be the same (or to be scalar 1*1*1) if they are 2D or 3D arrays. In MGL version this command usually is used as inline one dat(xx,yy,zz).

MGL command: column RES dat 'eq'

Get column (or slice) of the data filled by formula eq on column ids. For example, Column("n*w^2/exp(t)");. The column ids must be defined first by idset function or read from files. In MGL version this command usually is used as inline one dat('eq').

MGL command: resize RES dat mx [my=1 mz=1]

Resizes the data to new size mx, my, mz from box (part) [x1,x2] x [y1,y2] x [z1,z2] of original array. Initially x,y,z coordinates are supposed to be in [0,1].

MGL command: evaluate RES dat idat [norm=on]

MGL command: evaluate RES dat idat jdat [norm=on]

MGL command: evaluate RES dat idat jdat kdat [norm=on]

Gets array which values is result of interpolation of original array for coordinates from other arrays. All dimensions must be the same for data idat, jdat, kdat. Coordinates from idat, jdat, kdat are supposed to be normalized in range [0,1] (if norm=true) or in ranges [0,nx], [0,ny], [0,nz] correspondingly.

MGL command: hist RES dat num v1 v2 [nsub=0]

MGL command: hist RES dat wdat num v1 v2 [nsub=0]

Creates n-th points distribution of the data values in range [v1, v2]. Array w specifies weights of the data elements (by default is 1). Parameter nsub define the number of additional interpolated points (for smoothness of histogram). See also Data manipulation

MGL command: momentum RES dat 'how' ['dir'='z']

Gets momentum (1D-array) of the data along direction dir. String how contain kind of momentum. The momentum is defined like as res_k = \sum_ij how(x_i,y_j,z_k) a_ij/ \sum_ij a_ij if var=‘z’ and so on. Coordinates ‘x’, ‘y’, ‘z’ are data indexes normalized in range [0,1].

MGL command: sum RES dat 'dir'

Gets array which is the result of summation in given direction or direction(s).

MGL command: max RES dat 'dir'

Gets array which is the maximal data values in given direction or direction(s).

MGL command: min RES dat 'dir'

Gets array which is the maximal data values in given direction or direction(s).

MGL command: combine RES adat bdat

Returns direct multiplication of arrays (like, res[i,j] = this[i]*a[j] and so on).

MGL command: trace RES dat

Gets array of diagonal elements a[i,i] (for 2D case) or a[i,i,i] (for 3D case) where i=0...nx-1. Function return copy of itself for 1D case. Data array must have dimensions ny,nz >= nx or ny,nz = 1.

4.7 Data changing

These functions change the data in some direction like differentiations, integrations and so on. The direction in which the change will applied is specified by the string parameter, which may contain ‘x’, ‘y’ or ‘z’ characters for 1-st, 2-nd and 3-d dimension correspondengly.

MGL command: cumsum dat 'dir'

Cumulative summation of the data in given direction or directions.

MGL command: integrate dat 'dir'

Integrates (like cumulative summation) the data in given direction or directions.

MGL command: diff dat 'dir'

Differentiates the data in given direction or directions.

MGL command: diff dat xdat ydat [zdat=0]

Differentiates the data specified parametrically in direction x with y, z=constant. Parametrical differentiation uses the formula (for 2D case): da/dx = (a_j*y_i-a_i*y_j)/(x_j*y_i-x_i*y_j) where a_i=da/di, a_j=da/dj denotes usual differentiation along 1st and 2nd dimensions. The similar formula is used for 3D case. Note, that you may change the order of arguments – for example, if you have 2D data a(i,j) which depend on coordinates {x(i,j), y(i,j)} then usual derivative along ‘x’ will be Diff(x,y); and usual derivative along ‘y’ will be Diff(y,x);.

MGL command: diff2 dat 'dir'

Double-differentiates (like Laplace operator) the data in given direction.

MGL command: sinfft dat 'dir'

Do Sine transform of the data in given direction or directions. The Sine transform is \sum a_i \sin(k i).

MGL command: cosfft dat 'dir'

Do Cosine transform of the data in given direction or directions. The Cosine transform is \sum a_i \cos(k i).

MGL command: hankel dat 'dir'

Do Hankel transform of the data in given direction or directions. The Hankel transform is \sum a_i J_0(k i).