MGL script language
Reference manual for v.1.10
Alexey Balakin, 2007-2009
Contents
- Introduction
- Graphics setup
- Scaling, moving and rotating
- Axis and Colorbar
- Primitive drawing functions
- 1d plotting commands
- 2d plotting commands
- 3d plotting commands
- Dual plotting commands
- Other plotting function
- Program flow commands
- Data creation and file I/O
- New data extraction (forming)
- Data handling
- Nonlinear fitting
- Color specification
- Line style specification
- Color scheme specification
- Text and font specification
- Formulas and functions
- Command options
- Suffixes for variable
1. Introduction
MathGL library supports (from version 1.3) the simplest scripts for data handling and plotting. These scripts can be used independently (with the help of mgl2png, mgl2eps, mgl2svg programs and others) or in the frame of the library using.
MGL script language is rather simple. Each string is a command. First word of string is the name of command. Other words are command arguments. Command may have up to 1000 arguments (at least for now). Words are separated from each other by space or tabulation symbol. The upper or lower case of words is suficient, i.e. variables a and A are different variables. Symbol #
starts the comment (all characters after #
will be ignored). The exception is situation when #
is a part of some string. Also options can be specified at the end of string (after symbol ';
', see Sec. Command options). Symbol ':
' starts new command (like new line character) if it is not placed inside a string or inside brackets.
If string contain references to external parameters (substrings "$0", "$1" ... "$9") then before execution the values of parameter will be substituted instaed of reference. It allows to use the same MGL script for different parameters (filenames, paths, condition and so on).
Argument can be a string, a variable name or a number.
- The string is any symbols between ordinary marks (
'
).
- Variable name is arbitrary combination of symbols (except spaces and
'
) started from a letter and with length less than 64. It is possible to use subarrays (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)
.
If names for data columns was specified (by set_id command or in the file at string started with ##
) then it is possible to use any column combinations defined by formulas, like a('n*w^2/exp(t)')
.
Also, 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). Such variables can not be used as 1st argument for commands which create (return) the data (like new, read, hist and so on).
- Special variables
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. Also results of formulas with sizes 1x1x1 are treated as number (for example, pi/dat.nx
).
Before the first using all variables must bedefined with the help of commands new, var, list, copy or read.
All MGL commands can be divided on several groups. I will use the following notation for a command description: command names are bold, strings are denoted by commas, variable names are italic, numbers are typewriter. Optional arguments are placed in square brackets and default values for them are shown. Detailed description of color, line styles, color schemes, font types , TeX-like symbols and formulas can be found in corresponding section.
[contents]
2. Graphics setup
Commands in this group influences on overall graphics appearance. So all of them should placed before any actual plotting commands.
2.1. Transparency
There are several commands for setup transparency. The general command is alpha
which switch on/off the transparency for overall plot. It influence only for graphics which created after alpha
call. Command alphadef
specify the default value of alpha-channel. You may switch off transparency of selected plot by command transparent
. Finally, command transptype
set the kind of transparency.
- alpha [
val=on
]
Sets the transparency on/off. It is recommended to call this function before any plotting command. Initial value is off
. Use command transparent off
in particular plot to disable its transparency.
- alphadef
val
Default value of alpha channel for transparency for all plotting functions. Initial value is 0.5.
- transparent
val
Flag that temporarily switches transparency on/off for the plot. Initial value is on
.
- transptype
val
Type of transparency: 0 – normal transparency (below things is less visible than upper ones), 1 – glass-like transparency ( below and upper things are commutable and just decrease light intensity), 2 – light-like transparency (below and upper things are commutable and are the source of some additional light). Initial value is 0
.
2.2. Lighting
There are several commands for setup lighting. The general command is light
which switch on/off the lighting for overall plot. It influence only for graphics which created after light
call. You can specify up to 10 independent light sources. By default only one light source is active. It is source number 0
with white color, located at top of the plot.
- ambient
val
Sets the brightness of an ambient light. The value should be in range [0,1]. It is recommended to call this function before any plotting command. Initial value is 0.5.
- light [
val=on
]
Sets the using of light on/off. It is recommended to call this function before any plotting command. Initial value is lightning off.
- light
num xpos ypos zpos
['col'='w' br=0.5
]
The function adds a light source with identification num
at position {xpos, ypos, zpos
}. The color of light is 'col' (white by default). The brightness of light is br
in [0,1]. It is recommended to call this function before any plotting command.
- light
num val
Switches on/off n-th light source separately depending on parameter val
.
2.3. Fog
- fog
val [dist=0.25]
Set the density of fog val
for the picture. If val=0
then fog is absent. Fog will start from relative distance dist
from the leading edge.
2.4. Default sizes
These commands control the default (initial) values for most graphics parameters including sizes of markers, arrows, linewidth and so on. As any other settings these ones will influence only on plots created after the settings change.
- arrowsize
val
Base size for all arrows. Initial value is 1.
- barwidth
val
Sets relative width of rectangles in bars, barh, boxplot
. Default value is 0.7.
- linewidth
val
Base line width for all lines. Should be larger or equal to 1.
- marksize
val
Base size for all marks. Initial value is 1.
- 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.
- tickstl 'stl' ['sub'='']
The line style of axis ticks ('stl') and subticks ('sub'). If 'stl'='' then default style is used ('k'
or 'w'
depending on transparency type). If 'sub'='' then ticks style is used (i.e. 'sub'='stl').
2.5. Zooming
These commands control the overall zooming of the picture or the sub-picture. Normally you can use these variables and commands for removing "white" spaces around a plot.
- plotfactor
val
Factor for sizing overall (sub-)plot. Its value should be >1.6 (default value is =-1). If val=-1
then plot auto-sizing will be switched on. See also zoom.
- zoom
x1 y1 x2 y2
Zoom in/out the picture by projection of region [x1, x2]×[y1, y2] to entire picture. This comand also clear the picture like clf. See also plotfactor.
2.6. Cutting
These commands set the condition when the points are excluded (cutted) from the drawing.
- cut
val
Flag which determines how points outside the bounding box are drawn. If it is on
then points are excluded from the plot (it is default) otherwise the points are projected to edges of the bounding box.
- cut
x1 y1 z1 x2 y2 z2
Lower and upper edge of the box in which no points are drawn. If both edges are the same (the variables are equal) then the cutting box is empty.
- cut 'cond'
Command set 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.
2.7. Other settings
- axialdir 'dir'
Sets the direction around which curve rotated in axial and torus commands. Initial value is 'z'.
- font 'fnt' [
val=6
]
Font style for text and labels (see text). Initial style is 'fnt'='rC' – Roman font with centerin. 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 Sec. Text and font specification.
- meshnum
val
Sets approximate number of lines in mesh, fall and grid. Initially (=0) it draws all lines.
- palette 'colors'
Set the palette as selected colors. Deafult value is 'Hbgrcmyhlnqeup'. The palette is used mostly in 1D plots for curves which styles are not specified.
- rotatetext
val
The using of text rotation along axis. Initial value is on
.
2.8. Axis settings
These large set of commands control how the axis and ticks will be drawn. Note that there is 3-step transformation of data coordinates are performed. Firstly, coordinates are projected and cutting is applied, after it transformation formulas are applied, and finally the data was normalized in bounding box. For drawing functions see axis and colorbar.
- axis
x1 y1 x2 y2
axis x1 y1 z1 x2 y2 z2
ranges x1 x2 y1 y2 [z1=0 z2=0]
Sets the ranges (bounding box) of coordinates changing. Also it sets the range for coloring (analogous to caxis z1 z2
). Initial ranges are [-1, 1].
- axis 'fx' 'fy' ['fz'='' 'fc'='']
Sets the transformation formulas for curvilinear coordinates. 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 axis 'x*cos(y)' 'x*sin(y)' 'z'
. For removing of formulas the corresponding parameter should be ''. The using of transformation formulas will slightly slowing the program, i.e. axis '' '' ''
is faster than axis '1*x' '1*y' '1*z'
. Initially all formulas are absent (Cartesian coordinates are used). For more details about functions and formulas see Sec. Formulas.
- axis
how
Sets one of the predefined transformation formulas for curvilinear coordinate. Paramater how
define the coordinates:
0
– Cartesian coordinates (no transformation);
1
– Polar coordiantes {xn=x*cos(y), yn=x*sin(y), zn=z};
2
– Spherical coordinates {xn=x*sin(y)*cos(z), yn=x*sin(y)*sin(z), zn=x*cos(y)};
3
– Parabolic coordinates {xn=x*y, yn=(x2-y2)/2, zn=z};
4
– Paraboloidal coordinates {xn=(x2-y2)*cos(z)/2, yn=(x2-y2)*sin(z)/2, z_n=x*y};
5
– Oblate coordinates {xn=cosh(x)*cos(y)*cos(z), yn=cosh(x)*cos(y)*sin(z), zn=sinh(x)*sin(y)};
6
– Prolate coordinates {xn=sinh(x)*sin(y)*cos(z), yn=sinh(x)*sin(y)*sin(z), zn=cosh(x)*cos(y)};
7
– Elliptic coordinates {xn=cosh(x)*cos(y), yn=sinh(x)*sin(y), zn=z};
8
– Toroidal coordinates {xn=sinh(x)*cos(z)/(cosh(x)-cos(y)), yn=sinh(x)*sin(z)/(cosh(x)-cos(y)), zn=sin(y)/(cosh(x)-cos(y))};
9
– Bispherical coordinates {xn=sin(y)*cos(z)/(cosh(x)-cos(y)), yn=sin(y)*sin(z)/(cosh(x)-cos(y)), zn=sinh(x)/(cosh(x)-cos(y))};
10
– Bipolar coordinates {xn=sinh(x)/(cosh(x)-cos(y)), yn=sin(y)/(cosh(x)-cos(y)), zn=z}.
- caxis
c1 c2
Sets the range for surface coloring. Initial range is [-1, 1].
- origin
x0 y0 [z0=nan]
Places the point of intersection of coordinate axes to the point {x0, y0, z0
}. If one of values is nan
then MathGL library try to select optimal axis position.
- ternary
val
Flag that switch on/off drawing of ternary plot (triangular axis and so on).
- 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'.
- crange dat [
add=off frac=0
]
xrange dat [add=off frac=0
]
yrange dat [add=off frac=0
]
zrange dat [add=off frac=0
]
Sets the range for x-, y-, z-coordinate and colorbar as minimal and maximal values of data dat. Parameter add=on
shows that the new range will be joined to existed one (nut will not replace it). Parameter fact
add additional range increase on value (Max-Min)*fact
. See also axis.
- crange
v1 v2
xrange v1 v2
yrange v1 v2
zrange v1 v2
Sets the range for x-, y-, z-coordinate and colorbar as [v1, v2]
. See also axis and caxis.
- xtick
dx
[sx=0 tx=nan
]
ytick dx
[sx=0 tx=nan
]
ztick dx
[sx=0 tx=nan
]
ctick dx
Step for x-, y-, z-axis ticks and colorbar (if dx
>0) or it's number (if dx
<0). Zero value dx
=0 sets logarithmic ticks. Parameter sx
sets the number of subticks. Parameter tx
set the starting points for ticks (if not nan
).
- xtick 'template'
ytick 'template'
ztick 'template'
ctick 'template'
Set template (like '%g') for tick labels along x-, y-, z-axis ticks and colorbar. Do not influence on logarithmic ticks.
- xtick
val1
'lbl1' [val2
'lbl2' ...]
ytick val1
'lbl1' [val2
'lbl2' ...]
ztick val1
'lbl1' [val2
'lbl2' ...]
Manual positions val1, val2, ...
and labels 'lbl1', 'lbl2', ... for ticks along x-, y-, z-axis. Labels may contain TeX symbols also.
3. Scaling, moving and rotating
These command define the position of plot on the picture and its properties. There is a curtain order of calling of these functions for the better plot view. The first one should be subplot or inplot for specifying of the place. After it a rotate and aspect. And finally any other plotting function may be called. Alternatevely you can use columnplot for position plots in the column one by another without gap between plot axis (bounding boxes).
- 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 command.
- columnplot
num ind
Puts further plotting in ind
-th cell of column with num
cells. The position is relative to previous subplot call (or inplot with rel=off
).
- inplot
x1 x2 y1 y2 [rel=off]
Puts the further plotting in some region of the whole frame surface. This command 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=on
then the relative position to current sub- or inplot is used. This command sets any aspects or rotations off. So, it should be used first for creating subplot. See also subplot.
- perspective
val
Set perspective value. Parameter val
~1/zeff should be in range [0,1]. Initial value is 0 that correspond to ortho projection.
- rotate
tetz tetx
[tety=0
]
Rotates a further plotting relative to each axis (x, z, y) consecutively on angles tetz
, tetx
, tety
.
- rotate
tet x y z
Rotates a further plotting around vector {x,y,z
} on angle tet
.
- subplot
w h pos [dx=0 dy=0]
Puts further plotting in a pos
-th cell of w*h
grid of the whole frame area. Optional paramters dx, dy
add additional shifting of plotting (in units relative to subplot sizes). This function sets off any aspects or rotations. So, it should be used first for creating the subplot. From the aesthetical point of view it is not recommended to use this function with different matrices in the same frame. See also inplot.
[contents]
4. Axis functions
Axis functions control and draw the axes. There is the twofold axis representation in MGL. First one consists in normalizing of the data point coordinates in box specified in axis command. If cut is on
then the outer point is omitted otherwise it is projected to bounding box. Also the points are omitted if they are inside the box specified in cut command. After it transformation formulas 'fx', 'fy', 'fz' are applied to the data point. Finally, the data point is plotted by one of functions.
- axis ['dirs'='xyz'
adjust=off
]
Draws axes with ticks (defined by xtick, ytick, ztick) in directions determined by string parameter dir. If the string contains symbol '_' then tick labels are not printed. Font for ticks text is determined by font. Ticks will be automatically adjusted if adjust=on
.
- box ['stl'='k']
Draws bounding box outside the plotting volume with line style 'stl'.
- colorbar ['sch'=''
pos=0
]
colorbar vdat ['sch'='' pos=0
]
Draws colorbar with color scheme 'sch' (current scheme if 'sch'='') at the edge of plot. If parameter vdat is specified then sharp colors is used (like contd
command. Parameter pos
specifies the position of colorbar: 0 - at right (default), 1 - at left, 2 - at top, 3 - at bottom.
- colorbar 'sch'
pos x y w h
Draws colorbar with color scheme 'sch' (current scheme if '') at arbitrary position of subplot x y
(supposed to be in range [0,1]). Parameter pos
specifies the position of colorbar labels: 0 - at left, 1 - at right, 2 - at bottom, 3 - at top. Parameters w h
set the relative width and height of the colorbar.
- grid ['dir'='xyz' 'stl'='B-']
Draws grid lines perpendicular to direction determined by string parameter 'dir'. The step of grid lines is the same as tick step for an axis. The style of lines is determined by 'stl'.
- xlabel 'txt' [
pos=1 size=-1.4 shift=0
]
ylabel 'txt' [pos=1 size=-1.4 shift=0
]
zlabel 'txt' [pos=1 size=-1.4 shift=0
]
tlabel 'txt' [pos=1 size=-1.4 shift=0
]
Prints the label 'txt' for x-, y-, z-axis. 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. Font style and size are defined by font command. Parameter shift
specify additional shifting of the label. See also text. For more detail see Sec. Text and font specification.
5. Primitive drawing functions
These functions draw some simple objects like line, point, sphere, drop, cone and so on. Also the text printing, plots by formula and legend drawing is included in this section.
- clf
Clears up the picture. Removes all drawing from it. Does not change transformation matrix.
5.1. Lines, curves and figures
These functions draw some simple objects like line, point, sphere, drop, cone and so on.
- ball
x y
['col'='r']
ball x y z
['col'='r']
Draws a point (ball) at position {x y z
} with color 'col'.
- cone
x1 y1 z1 x2 y2 z2 r1
[r2=-1
'stl'='' edge=off
]
Draws truncated cone from point {x1, y1, z1
} with radius r1
to point {x2, y2, z2
} with radius r2
, using line style 'stl'. If radius r2<0
then the radius r1
is used (r2=r1
). Flag edge
set to draw or not the edges of the cone.
- curve
x1 y1 dx1 dy1 x2 y2 dx2 dy2
['stl'='']
curve x1 y1 z1 dx1 dy1 dz1 x2 y2 z2 dx2 dy2 dz2
['stl'='']
Draws Bezier-like curve from point {x1, y1, z1
} to {x2, y2, z2
} using line style 'stl'. At this tangent is co-directed with {dx1, dy1, dz1
}, {dx2, dy2, dz2
} and proportional to its amplitude.
- drop
x0 y0 dx dy r
['col'='' sh=1 asp=1
]
drop x0 y0 z0 dx dy dz r
['col'='' sh=1 asp=1
]
Draws drop with size r
starting from point {x0, y0, z0
} and directed to {dx, dy, dz
}. The drop color is determined by 'col'. Parameter sh
(in range [0, 1]) determines the drop oblongness. Parameter asp
set relative width of the drop.
- facex
x0 y0 z0 wy wz
['stl'='' d1=0 d2=0
]
facey x0 y0 z0 wx wz
['stl'='' d1=0 d2=0
]
facez x0 y0 z0 wx wy
['stl'='' d1=0 d2=0
]
Draws the solid rectangle perpendicular to x-, y-, z-axis at position x0, y0, z0
with widths wx, wy, wz
along corresponding directions. At this colors, specified by 'stl', can be the same for all vertexes or different if all 4 colors are specified for each vertex. Parameters d1,d2
≠0 set additional shift of the last vertex. See also rect.
- line
x1 y1 x2 y2
['stl'='']
line x1 y1 z1 x2 y2 z2
['stl'='']
Draws geodesic line (stright-line in Cartesian coordinates) from point {x1, y1, z1
} to {x2, y2, z2
}, using line style 'stl'.
- rect
x1 y1 x2 y2
['stl'='']
rect x1 y1 z1 x2 y2 z2
['stl'='']
Draws rectangle from point {x1, y1, z1
} to {x2, y2, z2
}, using colors 'stl'. If 'stl' have 4 or more colors then it defines colors for each rectangle vertex (useful for making gradients, like 'wwrr'
) else first color is used for whole rectangle.
- sphere
x0 y0 r
['col'='']
sphere x0 y0 z0 r
['col'='']
Draws sphere with radius r
and center at point {x0, y0, z0
} using color 'col'.
5.2. Text printing
These commands draw the text. There are commands for drawing text in arbitrary place, in arbitrary direction and along arbitrary curve. It is possible to use arbitrary font-faces and parse many TeX commands. The Unicode text is supported. The size
argument control the size of text: if positive it give the value, if negative it give the value relative to defined by font command. For more details see Sec. Text and font specification.
5.2. Text printing
These commands draw legend to the graph (useful for 1D plotting (MGL)). Legend entry is a pair of strings: one for style of the line, another one with description text (with included LaTeX parsing). The array of string are accumulated first to the internal arrays (by command addlegend
) and are plotted later. The position of the legend can be selected automatic or manually. Parameters 'fnt' and size
specify the font style and size. Parameter llen
set the relative width of the line sample and the text indent (default value is 0.1). If line style string for entry is empty then the corresponding text is printed without indent.
- addlegend 'txt' 'stl'
Adds string 'txt' to internal legend accumulator. The style of described line and mark is specified in string 'stl'. The maximal number of entries is 100. If 'stl'='' then the corresponding text is printed without indent.
- clearlegend
Clears saved legend strings.
- legend [
pos=3
'fnt'='rL' size=-1 llen=0.1
]
Draws legend of accumulated string 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 llen
set the relative width of the line sample and the text indent.
- legend
x y
['fnt'='rL' size=-1 llen=0.1
]
Draws legend of accumulated string by font 'fnt' with size
. Parameters x, y
sets the position of the legend. Parameter llen
set the relative width of the line sample and the text indent.
- legendbox
val
Switches on/off the drawing of a box near legend. By default, the box is drawn.
5.3. Plots by formula
These commands plots curves and surfaces defined by textual formulas. The actual number of points for curves is increased near singularities.
- fplot 'y(x)' ['pen'=''
zval=nan num=100
]
Draws curve y=y(x) at plane z=zval
for x distributed in xrange. You do not need to create the data arrays to plot it. The parameter num
set the minimal number of points along coordinate(s) for plots. See also plot.
- fplot 'x(t)' 'y(t)' 'z(t)' ['pen'=''
num=100
]
Draws parametrical curve {x(t), y(t), z(t)} where t is changed in range [0,1]. You do not need to create the data arrays to plot it. The parameter num
set the minimal number of points along coordinate(s) for plots.
- fsurf 'z(x,y)' ['sch'=''
num=100
]
Draws surface z=z(x,y) for x, y distributed in xrange, yrange. You do not need to create the data arrays to plot it. The parameter num
set the minimal number of points along coordinate(s) for plots. See also surf.
- fsurf 'x(u,v)' 'y(u,v)' 'z(u,v)' ['sch'=''
num=100
]
Draws surface {x(u,v), y(u,v), z(u,v)} where u, v is changed in range [0, 1]. You do not need to create the data arrays to plot it. The parameter num
set the minimal number of points along coordinate(s) for plots. See also surf.
6. 1d plotting commands
These functions perform plotting of 1D data. 1D means that the data depend on the only 1 parameter (index), like parametric curve {x(i),y(i),z(i)}, i=0...n-1. Most of commands have similar interface. There are version for drawing in 3d space or in plain. For the last one there is a possibility to use single data array.
If command allows to use parametric curve definition (depends on 2 or 3 data arrays) then its minor dimensions should be equal. If one of the arrays is 2d array (matrix) then the curves will be drawn for each of rows. At this the other arrays can be one-dimensional. If array xdat is not specified then its an automatic array is used with values equidistantly distributed along x. Also the zval
(the default is at the bottom of the bounding box) is used instead zdat if last is not specified.
Optional string parameter 'stl' sets the style and color of line and marks for all 1d plotting commands. By default ('stl'='') solid line with next color from palette is used. See also color and line styles specification.
- area ydat ['stl'=''
zval=nan
]
area xdat ydat ['stl'='' zval=nan
]
area xdat ydat zdat ['stl'='']
Draws continuous lines between points {xdat, ydat, zdat} and fills it down to axis (to axis plane in 3D).
- barh vdat ['stl'=''
zval=nan above=off
]
barh ydat vdat ['stl'='' zval=nan above=off
]
Draws horizontal bars from points {vdat, ydat} to x axis in plane z=zval
(the default is at the bottom of the bounding box). Bars are drawn side-by-side (if above = off
) or one above another (if above = on
). Marks at data points are not drawn.
- bars ydat ['stl'=''
zval=nan above=off
]
bars xdat ydat ['stl'='' zval=nan above=off
]
bars xdat ydat zdat ['stl'='' above=off
]
Draws vertical bars from points {xdat, ydat, zdat} to axis (to axis plane in 3D). Bars are drawn side-by-side (if above = off
) or one above another (if above = on
). Marks at data points are not drawn.
- boxplot adat ['stl'=''
zval=nan
]
boxplot xdat adat ['stl'='' zval=nan
]
Draws boxplot (also known as a box-and-whisker diagram) at points {xdat} in plane z=zval
(by default is at the bottom of the bounding box). This is five-number summaries of data adat (minimum, lower quartile (Q1), median (Q2), upper quartile (Q3) and maximum) along second (j-th) direction.
- chart dat ['col'='']
Draws colored stripes (boxes) for data in array dat. The number of stripes is equal to the number of rows in dat. The color of each next stripe is cyclically changed from colors specified in string 'col' or in palette (for 'col'=''). If a char in the sting is space (' ') then corresponding peace will be absent. The stripe width is proportional to value of element in dat. Chart is plotted only for data arrays with non-negative elements. If string 'col' has symbol # then black border lines are drawn. The most nice form the chart has in 3d (after rotation of coordiantes) or in cylindrical coordinates (the so called Pie chart).
- error ydat yerr ['stl'=''
zval=nan
]
error xdat ydat yerr ['stl'='' zval=nan
]
Draws vertical error boxes yerr in position of data points {xdat, ydat} (for example, experimental one) in plane z = zval
(the default is at the bottom of the bounding box). All dimensions of arrays yerr and ydat must be equal. See also plot.
- error xdat ydat xerr yerr ['stl'=''
zval=nan
]
Draws error boxes {xerr, yerr} in position of data points {xdat, ydat} (for example, experimental one) in plane z = zval
(the default is at bottom of bounding box). All dimensions of arrays xerr, yerr and xdat, ydat must be equal.
- mark ydat rdat ['stl'=''
zval=nan
]
mark xdat ydat rdat ['stl'='' zval=nan
]
mark xdat ydat zdat rdat ['stl'='']
Draws marks with relative size rdat in points {xdat, ydat, zdat}.
- plot ydat ['stl'=''
zval=nan
]
plot xdat ydat ['stl'='' zval=nan
]
plot xdat ydat zdat ['stl'='']
Draws continuous lines between points {xdat, ydat, zdat}.
- radar adat ['stl'=''
r=-1
]
Draws radar chart which is continuous lines between points located on an radial lines (like plot in Polar coordinates). The plots are drawn for each row if one of the data is the matrix. Parameter r
set the additional shift of data (i.e. the data adat+r
is used instead of adat). If r<0
then r=max(0, -min(adat)
. If string 'pen' containt '#' symbol then "grid" (radial lines and circle for r
) is drawn.
- region fdat gdat ['stl'=''
inside=off
]
region xdat fdat gdat ['stl'='' inside=off
]
Fills area between curves {xdat, fdat} and {xdat, gdat}. Parameter inside=off
set to fill are with y1<y<y2 else the area with y2<y<y1 will be also filled.
- stem ydat ['stl'=''
zval=nan
]
stem xdat ydat ['stl'='' zval=nan
]
stem xdat ydat zdat ['stl'='']
Draws vertical lines from points {xdat, ydat, zdat} to axis (to axis plane in 3D).
- step ydat ['stl'=''
zval=nan
]
step xdat ydat ['stl'='' zval=nan
]
step xdat ydat zdat ['stl'='']
Draws continuous stairs for points {xdat, ydat, zdat}.
- tens ydat cdat ['stl'=''
zval=nan
]
tens xdat ydat cdat ['stl'='' zval=nan
]
tens xdat ydat zdat cdat ['stl'='']
Draws continuous lines between points {xdat, ydat, zdat} with color defined by cdat.
- textmark ydat 'text' ['stl'=''
zval=nan
]
textmark ydat rdat 'text' ['stl'='' zval=nan
]
textmark xdat ydat rdat 'text' ['stl'='' zval=nan
]
textmark xdat ydat zdat rdat 'text' ['stl'='']
Draws 'text' with relative size rdat in points {xdat, ydat, zdat}.
- torus zdat ['stl'='']
torus rdat zdat ['stl'='']
Draws surface which is result of curve {rdat, zdat} rotation around axis. Size of arrays {rdat, zdat} must be the same. String 'stl' sets the color of the surface. First color of previous color scheme is used by default. If the string 'stl' contains symbols 'x', 'y' or 'z' then rotation axis axialdir will be set to specified direction. See also axial.
- tube ydat rdat ['stl'=''
zval=nan
]
tube xdat ydat rdat ['stl'='' zval=nan
]
tube xdat ydat zdat rdat ['stl'='']
Draws tube with variable radius rdat along the curve between points {xdat, ydat, zdat}.
- tube ydat
rval
['stl'='' zval=nan
]
tube xdat ydat rval
['stl'='' zval=nan
]
tube xdat ydat zdat rval
['stl'='']
Draws tube with constant radius rval
along the curve between points {xdat, ydat, zdat}.
2d plotting commands
These functions perform plotting of 2D data. 2D means that the data depend on 2 independent parameter (indexes). Most of commands have similar interface. There are 2 versions for drawing of the surface of single data array and for parametrically specified surface.
If command allows to use parametric surface definition (depends on 3 data arrays xdat, ydat, zdat) then its minor dimensions should be equal. At this arrays xdat, ydat can be one-dimensional. If arrays xdat, ydat are not specified then its an automatic arrays are used with values equidistantly distributed along x and y. If zdat is 3d array then the surfaces will be drawn for each of slices.
Optional string parameter 'stl' sets the color scheme. Previous color scheme is used by default. See also color and color schemes specification.
- axial zdat ['sch'=''
num=3
]
axial xdat ydat zdat ['sch'='' num=3
]
Draws num
-th surfaces which is result of contour plot rotation for the surface specified parametrically {xdat, ydat, zdat}. Contours are plotted at constant zdat. Surfaces are drawn only for the first z slice of the data.
- axial vdat zdat ['sch'='']
axial vdat xdat ydat zdat ['sch'='']
The same as previous one but contour levels are specified by vdat (i.e. contours are drawn for zdat=vdat[i]).
- belt zdat ['sch'='']
belt xdat ydat zdat ['sch'='']
Draws belts (types) for surface specified parametrically {xdat, ydat, zdat}. This plot can be used as 3d generalization of plot.
- boxs zdat ['sch'='']
boxs xdat ydat zdat ['sch'='']
Draws vertical boxes for surface specified parametrically {xdat, ydat, zdat} from data points to x-y axis plane.
- cont zdat ['sch'=''
num=7 zval=nan
]
cont xdat ydat zdat ['sch'='' num=7 zval=nan
]
Draws num
-th contour lines for the surface specified parametrically {xdat, ydat, zdat} at plane z = zval
(or at contour level if zval=nan
). Contours are plotted at constant zdat. If string contain 't' (or 'T') symbol then contour labels will be drawn below (or above) the contours. See also grid.
- cont vdat zdat ['sch'=''
zval=nan
]
cont vdat xdat ydat zdat ['sch'='' zval=nan
]
The same as previous one but contour levels are specified by vdat (i.e. contours are drawn for zdat=vdat[i]).
- contd zdat ['sch'=''
num=7 zval=nan
]
contd xdat ydat zdat ['sch'='' num=7 zval=nan
]
Draws num
-th solid contours for the surface specified parametrically {xdat, ydat, zdat} at plane z = zval
(or at contour level if zval=nan
) with manual colors. Contours are plotted at constant zdat with color sch[i%strlen(sch)]
(where i=0...num-1).
- contd vdat zdat ['sch'=''
zval=nan
]
contd vdat xdat ydat zdat ['sch'='' zval=nan
]
The same as previous one but contour levels are specified by vdat (i.e. contours are drawn for zdat=vdat[i] with color sch[i%strlen(sch)]
).
- contf zdat ['sch'=''
num=7 zval=nan
]
contf xdat ydat zdat ['sch'='' num=7 zval=nan
]
Draws num
-th solid contours for the surface specified parametrically {xdat, ydat, zdat} at plane z = zval
(or at contour level if zval=nan
). Contours are plotted at constant zdat.
- contf vdat zdat ['sch'=''
zval=nan
]
contf vdat xdat ydat zdat ['sch'='' zval=nan
]
The same as previous one but contour levels are specified by vdat (i.e. contours are drawn for zdat=vdat[i]).
- dens zdat ['sch'=''
zval=nan
]
dens xdat ydat zdat ['sch'='' zval=nan
]
Draws density plot for the surface specified parametrically {xdat, ydat, zdat} at plane z = zval
.
- fall zdat ['sch'='']
fall xdat ydat zdat ['sch'='']
Draws fall lines for surface specified parametrically {xdat, ydat, zdat}. This plot can be used as 3d generalization of plot. The number of lines depends on command meshnum.
- grid zdat ['sch'='']
grid xdat ydat zdat ['sch'='']
Draws plane grid for the surface specified parametrically {xdat, ydat, zdat} at plane z = zval
. The number of lines depends on command meshnum.
- mesh zdat ['sch'='']
mesh xdat ydat zdat ['sch'='']
Draws mesh lines for surface specified parametrically {xdat, ydat, zdat}. The number of lines depends on command meshnum.
- surf zdat ['sch'='']
surf xdat ydat zdat ['sch'='']
Draws solid surface specified parametrically {xdat, ydat, zdat}.
- tile zdat ['sch'='']
tile xdat ydat zdat ['sch'='']
Draws horizontal tiles for surface specified parametrically {xdat, ydat, zdat}. This plot can be used as 3d generalization of step. See also tile.
8. 3d plotting commands
These functions perform plotting of 3D data. 3D means that the data depended on 3 independent parameter (indexes). Most of commands have similar interface. There are 2 versions for drawing single data array and for parametrically specified data.
If command allows to use parametric surface definition (depends on 4 data arrays xdat, ydat, zdat, adat) then its minor dimensions should be equal. At this arrays xdat, ydat, zdat can be one-dimensional. If arrays xdat, ydat, zdat are not specified then its an automatic arrays are used with values equidistantly distributed along x, y and z.
Optional string parameter 'stl' sets the color scheme. Previous color scheme is used by default. See also color and color schemes specification.
- beam tr g1 g2 adat
r
['sch'='' flag=0 num=3
]
Draws num
-th isosurfaces for 3d array adat at constatnt values of adat. This is special kind of plot for adat specified in accompanied coordinates along curve tr with orts g1, g2 and with transverse scale r
. Variable flag
is bitwise flag: 0x1 - draw in accompanied (not laboratory) coordinates; 0x2 - draw projection to ρ×z plane; 0x4 - draw normalized in each slice field. The x-size of data arrays tr, g1, g2 must be nx≥3. The y-size of data arrays tr, g1, g2 and z-size of the data array adat must be equal.
- cloud adat ['sch'='']
cloud xdat ydat zdat adat ['sch'='']
Draws cloud plot for 3d array adat parametrically depending on coordinates {xdat, ydat, zdat}. This plot is a set of faces with color and transparency proportional to value of adat. The resulting plot looks like cloud – low value is transparent but higher ones are not. See also surf3.
- cont3 adat 'dir' [
val=-1
'sch'='' num=7
]
cont3 xdat ydat zdat adat 'dir' [val=-1
'sch'='' num=7
]
Draws num
-th contour lines for 3d array adat parametrically depending on coordinates {xdat, ydat, zdat}. Contours are plotted at constant adat
at slice sval
in 'dir' direction. If string contain 't' (or 'T') symbol then contour labels will be drawn below (or above) the contours.
- cont3 vdat adat 'dir' [
val=-1
'sch'='']
cont3 vdat xdat ydat zdat adat 'dir' [val=-1
'sch'='']
The same as previous one but contour levels are specified by vdat (i.e. contours are drawn for adat=vdat[i]).
- conta adat ['sch'=''
num=7
]
conta xdat ydat zdat adat ['sch'='' num=7
]
Draws num
-th contour lines for 3d array adat parametrically depending on coordinates {xdat, ydat, zdat}. Contours are plotted at constant adat
at all central slices (in 'x','y','z' directions). If string contain 't' (or 'T') symbol then contour labels will be drawn below (or above) the contours.
- contf3 adat 'dir' [
val=-1
'sch'='' num=7
]
contf3 xdat ydat zdat adat 'dir' [val=-1
'sch'='' num=7
]
Draws num
-th solid contours for 3d array adat parametrically depending on coordinates {xdat, ydat, zdat}. Contours are plotted at constant adat
at slice sval
in 'dir' direction.
- contf3 vdat adat 'dir' [
val=-1
'sch'='']
contf3 vdat xdat ydat zdat adat 'dir' [val=-1
'sch'='']
The same as previous one but contour levels are specified by vdat (i.e. contours are drawn for adat=vdat[i]).
- contfa adat ['sch'=''
num=7
]
contfa xdat ydat zdat adat ['sch'='' num=7
]
Draws num
-th solid contours for 3d array adat parametrically depending on coordinates {xdat, ydat, zdat}. Contours are plotted at constant adat
at all central slices (in 'x','y','z' directions).
- dens3 adat 'dir' [
val=-1
'sch'='']
dens3 xdat ydat zdat adat 'dir' [val=-1
'sch'='']
Draws density plot for 3d array adat parametrically depending on coordinates {xdat ydat zdat}. Density is plotted at slice sval
in 'dir' direction.
- densa adat ['sch'='']
densa xdat ydat zdat adat ['sch'='']
Draws density plot for 3d array adat parametrically depending on coordinates {xdat ydat zdat}. Density is plotted at all central slices (in 'x','y','z' directions).
- grid3 adat 'dir' [
val=-1
'sch'='']
grid3 xdat ydat zdat adat 'dir' [val=-1
'sch'='']
Draws grid for 3d array adat parametrically depending on coordinates {xdat, ydat, zdat}. Grid is plotted at slice sval
in 'dir' direction. The number of lines depends on command meshnum.
- grida adat ['sch'='']
grida xdat ydat zdat adat ['sch'='']
Draws grid for 3d array adat parametrically depending on coordinates {xdat, ydat, zdat}. Grid is plotted at all central slices (in 'x','y','z' directions). The number of lines depends on command meshnum.
- surf3 adat ['sch'=''
num=5
]
surf3 xdat ydat zdat adat ['sch'='' num=5
]
Draws num
-th isosurfaces for 3d array adat parametrically depending on coordinates {xdat, ydat, zdat} at constatnt values of adat.
- surf3 adat
val
['sch'='']
surf3 xdat ydat zdat adat val
['sch'=''
]
The same as previous one but isosurface levels are specified by val
(i.e. isosurface are drawn for adat=val
). See also cloud, surf3c, surf3a.
9. Dual plotting commands
These plotting functions draw two (or three) data arrays simultaneously in different forms: as coloring or transparing, vector field, flow chart or mapping. There are 2 versions for drawing single data array and for parametrically specified data.
If the command allows to use parametric surface definition (depends on 4, 5 or 6 data arrays xdat, ydat, zdat, adat, bdat, cdat) then its minor dimensions should be equal. At this arrays xdat, ydat, zdat can be one-dimensional. The dimensions of other data arrays (adat, bdat, cdat and so on) must be equal. If arrays xdat, ydat, zdat are not specified then its an automatic arrays are used with values equidistantly distributed along x, y and z.
Optional string parameter 'stl' sets the color scheme. Previous color scheme is used by default. See also color and color schemes specification.
Commands for general dual arrays:
- map udat vdat ['sch'=''
pnts=on
]
map xdat ydat udat vdat ['sch'='' pnts=on
]
Draws map plot for matrixes {udat, vdat} parametrically depending on coordinates {xdat, ydat}. The previous position of the cells (or points) is marked by color. Height is proportional to Jacobian(ax,ay). This plot is like Arnold diagram ???. If pnts=off
then face is drawn otherwise the color ball at matrix knots are drawn.
- stfa redat imdat
dn
['sch'='']
stfa xdat ydat redat imdat dn
['sch'='']
Draws spectrogram of complex array redat + i⋅imdat specified parametrically for Fourier size of dn
points.
- surfa zdat cdat ['sch'='']
surfa xdat ydat zdat cdat ['sch'='']
Draws solid surface specified parametrically {xdat, ydat, zdat}. Surface transparency is determined by values of cdat data array.
- surfc zdat cdat ['sch'='']
surfc xdat ydat zdat cdat ['sch'='']
Draws solid surface specified parametrically {xdat, ydat, zdat}. Surface coloring is determined by values of cdat data array.
- surf3a adat cdat ['sch'=''
num=5
]
surf3a xdat ydat zdat adat cdat ['sch'='' num=5
]
Draws num
-th isosurfaces for 3d array adat parametrically depending on coordinates {xdat, ydat, zdat} at constatnt values of adat. Isosurface transparency is determined by values of cdat data array.
- surf3a adat cdat
val
['sch'='']
surf3a xdat ydat zdat adat cdat val
['sch'='']
The same as previous one but isosurface levels are specified by val
(i.e. isosurface are drawn for adat=val
).
- surf3c adat cdat ['sch'=''
num=5
]
surf3c xdat ydat zdat adat cdat ['sch'='' num=5
]
Draws num
-th isosurfaces for 3d array adat parametrically depending on coordinates {xdat, ydat, zdat} at constatnt values of adat. Isosurface coloring is determined by values of cdat data array.
- surf3c adat cdat
val
['sch'='']
surf3c xdat ydat zdat adat cdat val
['sch'='']
The same as previous one but isosurface levels are specified by val
(i.e. isosurface are drawn for adat=val
).
- tile zdat rdat ['sch'='']
tile xdat ydat zdat rdat ['sch'='']
Draws horizontal tiles for surface specified parametrically {xdat, ydat, zdat}. The sizes of tiles are determined by rdat. This plot can be used as variant of surfa. See also tile.
Commands for vector fields:
- dew udat vdat ['sch'=''
val=nan
]
dew xdat ydat udat vdat ['sch'='' val=nan
]
Draws dew-drops (like drops under wind) for the plane vector field {udat, vdat} parametrically depending on coordinates {xdat, ydat} at level z = zval
. The color of drops is proportional to
. If string 'sch' contain 'A' then it looks as arrow plot (inverse drop direction). Note that this plot may require a lot of memory and CPU time.
- flow udat vdat ['sch'=''
num=5 val=nan
]
flow xdat ydat udat vdat ['sch'='' num=5 val=nan
]
Draws flow threads for the plane vector field {udat, vdat} parametrically depending on coordinates {xdat, ydat} at level z = zval
. The color of lines is proportional to
. Warm color corresponds to normal flow (like attractor). Cold one corresponds to inverse flow (like source).
- flow
x0 y0
udat vdat ['sch'='' zval=nan
]
flow x0 y0
xdat ydat udat vdat ['sch'='' zval=nan
]
Draws flow threads for the plane vector field {udat, vdat} parametrically depending on coordinates {xdat, ydat} from point {x0, y0
} at level z = zval
. The color of lines is proportional to
. Warm color corresponds to normal flow (like attractor). Cold one corresponds to inverse flow (like source).
- flow udat vdat wdat ['sch'=''
num=3
]
flow xdat ydat zdat udat vdat wdat ['sch'='' num=3
]
This is 3D version of the previous command. Here arrays {udat, vdat, wdat} must be 3-ranged tensors with equal sizes and the color of lines is proportional to
.
- flow
x0 y0 z0
udat vdat wdat ['sch'='']
flow x0 y0 z0
xdat ydat zdat udat vdat wdat ['sch'='']
Draws flow thread from point {x0, y0, z0
}. Arrays {udat, vdat, wdat} must be 3-ranged tensors with equal sizes and the color of lines is proportional to
.
- pipe udat vdat ['sch'=''
rad=0.05 num=5 val=nan
]
pipe xdat ydat udat vdat ['sch'='' rad=0.05 num=5 val=nan
]
Draws flow pipes for the plane vector field {udat, vdat} parametrically depending on coordinates {xdat, ydat} at level z = zval
. The color of pipes and its radius are proportional to
. Warm color corresponds to normal flow (like attractor). Cold one corresponds to inverse flow (like source). Negative rad
switch to pipe radius inverse proportional to
.
- pipe udat vdat wdat ['sch'=''
rad=0.05 num=3
]
pipe xdat ydat zdat udat vdat wdat ['sch'='' rad=0.05 num=3
]
This is 3D version of the previous command. Here arrays {udat, vdat, wdat} must be 3-ranged tensors with equal sizes and the color of pipes and its radius are proportional to
.
- traj xdat ydat udat vdat ['sch'=''
zval=nan len=0
]
traj xdat ydat zdat udat vdat wdat ['sch'='' len=0
]
Draws vectors {udat, vdat, wdat} along a curve xdat, ydat, zdat. The length and color of arrows are proportional to
.
- vect udat vdat ['sch'=''
val=nan
]
vect xdat ydat udat vdat ['sch'='' val=nan
]
Draws vector field for the plane vector field {udat, vdat} parametrically depending on coordinates {xdat, ydat} at level z = zval
. The length and color of arrows are proportional to
.
- vect udat vdat wdat ['sch'='']
vect xdat ydat zdat udat vdat wdat ['sch'='']
This is 3D version of the previous command. Here arrays {udat, vdat, wdat} must be 3-ranged tensors with equal sizes and the length and color of arrows are proportional to
.
- vectc udat vdat ['sch'=''
val=nan
]
vectc xdat ydat udat vdat ['sch'='' val=nan
]
Draws vector field for the plane vector field {udat, vdat} parametrically depending on coordinates {xdat, ydat} at level z = zval
. The color of hachures is proportional to
and changes from colder (lower) at the start to warmer (higher) at the end. It allows one to determine the direction of the vector field.
- vectc udat vdat wdat ['sch'='']
vectc xdat ydat zdat udat vdat wdat ['sch'='']
This is 3D version of the previous command. Here arrays {udat, vdat, wdat} must be 3-ranged tensors with equal sizes and the color of hachures is proportional to
.
- vectl udat vdat ['sch'=''
val=nan
]
vectl xdat ydat udat vdat ['sch'='' val=nan
]
Draws vector field for the plane vector field {udat, vdat} parametrically depending on coordinates {xdat, ydat} at level z = zval
. The length of hachures is proportional to
.
- vectl udat vdat wdat ['sch'='']
vectl xdat ydat zdat udat vdat wdat ['sch'='']
This is 3D version of the previous command. Here arrays {udat, vdat, wdat} must be 3-ranged tensors with equal sizes and the length of hachures is proportional to
.
10. Other plotting function
These plotting commands draw density plot or contour lines in x, y, or z plain. If dat is 3-dimensional data array then interpolation to a given sval
is performed. These functions are useful for creating projections of the 3D data array to the bounding box. Optional string parameter 'stl' sets the color scheme. Optional parameter val
sets the value of coordiante on the slice. Previous color scheme and axis origin are used by default. See also color and color schemes specification.
- contx dat ['sch'=''
val=nan num=7
]
conty dat ['sch'='' val=nan num=7
]
contz dat ['sch'='' val=nan num=7
]
Draws num
-th contour lines of data array dat at slice x,y,z = val
.
- contfx dat ['sch'=''
val=nan num=7
]
contfy dat ['sch'='' val=nan num=7
]
contfz dat ['sch'='' val=nan num=7
]
Draws num
-th solid contours of data array dat at slice x,y,z = val
.
- densx dat ['sch'=''
val=nan
]
densy dat ['sch'='' val=nan
]
densz dat ['sch'='' val=nan
]
Draws density plot of data array dat at slice x,y,z = val
.
These plotting commands draw rather rare plots like crust or dots which is arbitrary placed in space, or surface of triangles. If several data arrays for coordinates are specified then they should have the same size. These functions are useful for creating plots of unsorted or user-defined data arrays. Optional string parameter 'stl' sets the color scheme. Previous color scheme is used by default. See also color and color schemes specification.
- crust xdat ydat zdat ['sch'='']
Draws (and reconstruct) a surface for arbitrary placed points in the space xdat ydat zdat.
- dots xdat ydat zdat ['sch'='']
Draws dots for arbitrary placed points in the space xdat ydat zdat.
- triplot idat xdat ydat ['sch'=''
val=nan
]
triplot idat xdat ydat zdat ['sch'='']
triplot idat xdat ydat zdat cdat ['sch'='']
Draws the surface of triangles with vertexes specified as idat-th element of coordinates array xdat ydat zdat. Array idat should have nx≥3. Array cdat define colors of triangles (if cdat.nx=idat.ny) or color of vertexes (if cdat.nx=xdat.nx). Interpolated colors are used in last case.
10. Program flow commands
These commands control program flow, like, conditions, cycles, define script arguments and so on.
- call 'filename'
Executes script 'filename'.
- chdir 'path'
Changes the current directory to 'path'.
- define $N smth
Sets N-th script argument to smth. Note, that smth is used as is (with ' symbols if present).
- define id smth
Create scalar variable id
which have the numeric value of smth
. Later you can use this variable as usual number.
- if dat 'cond'
Starts block which will be executed if dat satisfy to 'cond'.
- if
val
Starts block which will be executed if val
is nonzero.
- elseif dat 'cond'
Starts block which will be executed if previous if or elseif is false and dat satisfy to 'cond'.
- elseif
val
Starts block which will be executed if previous if or elseif is false and val
is nonzero.
- else
Starts block which will be executed if previous if or elseif is false.
- endif
Finishes if/elseif/else block.
- for $N
v1 v2 [dv=1]
Starts cycle with N-th argument changing from v1
to v2
with the step dv
.
- for $N dat
Starts cycle with N-th argument changing for dat values.
- next
Finishes for cycle and start iteration with next argument value.
- break
Breaks for cycle.
- continue
Continue for cycle from starting point with next argument value.
- once
val
The code between once on
and once off
will be executed only once. Useful for large data manipulation in programs like UDAV.
- stop
Terminate execution.
- write 'fname' [
solid=off
]
Writes current picture/frame to file 'fname' (file type is determined by extension). Solid (usually white) background will be used if solid=on
. If 'fname'='' then the file frameNNNN.jpg
is used, where NNNN
is current frame id.
- setsize
w h
Sets size of picture in pixels. This function call have to be before any plotting command. In some program the call of this function is forbidden.
11. Data creation and file I/O
These commands create new variable with specified name. Note, that if a variable with the same name exists then it will be overwritten. The only exception is the command delete which deletes specified variable and makes its memory free.
- new dat [
numx=1 numy=1 numz=1
]
Creates new variable with name dat and array sizes numx, numy, numz
. Array elements are set to zero.
- 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.
- 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.
- 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.
- copy dat1 dat2 ['eq'=''
on_axis=on
]
copy dat val
Creates new variable with name dat1 and fills it by data values of array dat2. At this, if parameter 'eq' is not '' then the data will be modified by corresponding formula by the same way as in fill command (for on_axis=on
) or in modify command (for on_axis=off
).
- delete dat
Deletes variable dat and makes its memory free. Can be useful for huge data arrays.
- export dat 'pngname' 'scheme' [
v1=0 v2=0
]
Export data to PNG file. Data values are transformed to color values according to specified color scheme and will be used from range [v1, v2
]. Maximal and minimal values will be used if v1=v2
.
- import dat 'pngname' 'scheme' [
v1=0 v2=1
]
Create new variable with name data and fills it by importing data from PNG file. Color values are transformed to data values according to specified color scheme and will be placed in range [v1, v2
].
- read dat 'fname'
Creates new variable with name dat and fills it by data from file with name 'fname'. The sizes of data in the file are determined automatically.
- read dat 'fname'
numx
[numy=1 numz=1
]
Creates new variable with name dat and fills it by data from file with name 'fname'. The sizes of data in the file are determined by values numx, numy, numz
.
- readall dat 'templ' [
slice=off
]
Creates new variable with name dat and fills it by data joined 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 slice=off
or as slice-by-slice if slice=on
.
- readall dat 'templ'
v1 v2
[step=1 slice=off
]
Creates new variable with name dat and fills it by data joined from several text files. The file names are determined by function call sprintf(fname,templ,val)
, where val changes from v1
to v2
with step step
. The data load one-by-one in the same slice if slice=off
or as slice-by-slice if as slice=on
.
- readhdf dat 'fname' 'dataname'
Creates new variable with name dat and fills it by data 'dataname' from HDF5 file with name 'fname'.
- readmat dat 'fname' [
dim=2
]
Creates new variable with name dat and fills it by data from file with name 'fname'. The data dimensions is specified by dim
parameter. The sizes of data specified at beginning of the file (first dim
numbers).
- save dat 'fname'
Saves data array dat to text file with name 'fname'.
- savehdf dat 'fname' 'dataname'
Saves data array dat to HDF5 file with name 'fname' to the field with name 'dataname'.
12. New data extraction (forming)
This data write resulting data array in some other variable. Note, that if a variable with the same name exists then it will be overwritten.
- combine res adat bdat
Returns direct multiplication of arrays (like, res[i,j] = adat[i]*bdat[j] and so on).
- evaluate res dat idat [
norm=on
]
evaluate res dat idat jdat [norm=on
]
evaluate res dat idat jdat kdat [norm=on
]
Makes array res with data interpolated from dat for x=idat, y=jdat, z=kdat. If norm=on
then coordinates from idat, jdat, kdat are supposed to be normalized in range [0,1] otherwise in range [0,nx], [0,ny], [0,nz] correspondingly.
- jacobian res xdat ydat [zdat=0]
Computates the Jacobian for transformation ξ={i, j, k} to r={xdat, ydat, zdat} where initial coordinates {i, j, k} are data indexes normalized in range [0,1]. The Jacobian is determined by formula det||drα/dξβ||. All dimensions must be the same for all data arrays. Data must be 3D if all 3 arrays {xdat,ydat,zdat} are specified or 2D if only 2 arrays {xdat,ydat} are specified.
- hist res dat
num v1 v2 [nsub=0]
hist res dat wdat num v1 v2 [nsub=0]
Makes array res of num points as distribution (histogram) of dat data values in range [v1, v2
]. Data array wdat contains weights (all weight is 1 if wdat is not specified) and must have the same dimensions as array dat. Parameter nsub
define the number of additional interpolated points (for smoothness of histogram).
- max res dat 'dir'
Makes array res as maximal values of dat along direction(s) 'dir'.
- min res dat 'dir'
Makes array res as minimal values of dat along direction(s) 'dir'.
- momentum res dat 'how' ['dir'='z']
Get momentum (1D-array) of the data along direction 'dir'. String 'how' contain kind of momentum. The momentum is defined like resk = (∑ij how(xi,yj,zk)*aij / ∑ij aij) if 'dir'='z' and so on. Coordinates 'x', 'y', 'z' are data indexes normalized in range [0,1].
- resize res dat
mx
[my=1 mz=1
]
Makes array res of sizes mx, my, mz
with interpolated data of array dat.
- subdata res dat
kx [ky=: kz=:]
Makes array res as extracted sub-array data from the original dat array keeping fixed positive index. For example, subdata a b -1 2
extracts 2nd row, subdata a b 4 -1
extracts 4th column, subdata a b -1 -1 3
extracts 3d slice and so on.
- sum res dat 'dir'
Makes array res as summation of dat along direction(s) 'dir'.
- trace res dat 'dir'
Gets array of diagonal elements dat[i,i] (for 2D case) or dat[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.
- transform dat 'type' real imag
Do integral transformation of complex data real, imag on specified direction. Now only Fourier transformation is supported. The order of transformations is specified in string 'type': first character for x-dimension, second one for y-dimension, third one for z-dimension. The possible character are: 'f' is forward Fourier transformation, 'i' is inverse Fourier transformation, 'n' or ' ' is no transformation.
- transforma dat 'type' ampl phase
Do integral transformation of complex data ampl, phase on specified direction. Now only Fourier transformation is supported. The order of transformations is specified in string 'type': first character for x-dimension, second one for y-dimension, third one for z-dimension. The possible character are: 'f' is forward Fourier transformation, 'i' is inverse Fourier transformation, 'n' or ' ' is no transformation.
- stfad res real imag
dn
['dir'='x']
Short time Fourier analysis for real and imaginary parts. Output is amplitude of partial Fourier of length dn
. For example if 'dir'='x', result will have size {int(nx/dn), dn, ny} and it will contain res[i,j,k]=|∑d=0...dn exp(I*j*d) * (real[i*dn+d,k]+I*imag[i*dn+d,k])| / dn.
- 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. Coordinates of the equation (and the solution) are supposed to be in the bounding box. 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'='sth*(hre+i*him)').
- qo2d res 'ham' ini_re ini_im ray [
r=1 k0=100
xx=0 yy=0]
Solves equation du/dt = i*k0*ham(p,q,x,y,|u|)[u], where p=-i/k0*d/dx, q=-i/k0*d/dy are pseudo-differential operators (see pde for details). Parameters ini_re, ini_im specify real and imaginary part of initial field distribution. Parameters ray set the reference ray, i.e. the ray around which the accompanied coordinate system will be maked. You may use, for example, the array created by ray command. Note, that the reference ray must be smooth enough to make accompanied coodrinates unambiguity. Otherwise errors in the solution may appear. If xx and yy are non-zero then Cartesian coordinates for each point will be written into them.
- ray res 'ham'
x0 y0 z0 p0 q0 v0
[dt=0.1 tmax=10
]
Solves GO ray equation like dri/dt = d ham/dpi, dpi/dt = -d ham/dri. This is Hamiltonian equations for particle trajectory in 3D case. Here ham is Hamiltonian which may depend on coordiantes 'x', 'y', 'z', momentums 'p'=px, 'q'=py, 'v'=pz and time 't': 'ham'='H(x,y,z,p,q,v,t)'. The starting point (at t=0) is defined by variables {x0, y0, z0, p0, q0, v0
}. Parameters dt
and tmax
specify the integration step and maximal time for ray tracing. Result res is array of 7 columns {x,y,z,p,q,v,t} with dimensions 7×int(tmax/dt+1).
13. Data handling
13.1. Information
- info dat [
detail=off
]
Display information (sizes, maximum/minimum, momentums and so on) about the data dat. Show brief information by default (if detail=off
).
- info 'text'
Display 'text' as information (warning).
- set_id dat 'ids'
Set the symbol id for data columns. The string must contain one symbol 'a'…'z' per column (without spaces).
13.2. Data filling
- fill dat
v1 v2
['dir'='x']
Equidistantly fills the data values of dat to range [x1, x2
] along direction 'dir'.
- fill dat 'eq' [vdat=0 wdat=0]
Command 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 bounding box (in difference from modify commands). Variable 'u' is the original value of the array dat. Variables 'v' and 'w' are values of vdat, wdat.
- modify dat 'eqs' vdat [wdat=0]
Fills the value of dat array according to the formula in string 'eqs'. Formula is an arbitrary expression depending on variables 'x', 'y', 'z', 'u', 'v', 'w'. Coordinates 'x', 'y', 'z' are data indexes normalized in interval [0,1]. Variable 'u' is the original value of the array (see also Sec. Formulas). If optional data vdat, wdat (must be the same size as dat) is specified then variables 'v' and 'w' denote its values else it are zero.
- modify dat 'eqs' [
val=0
]
Fills the value of dat array according to the formula in string 'eqs' but do it only for slices ≥val
. Formula is an arbitrary expression depending on variables 'x', 'y', 'z', 'u'. Coordinates 'x', 'y', 'z' are data indexes normalized in interval [0,1]. Variable 'u' is the original value of the array (see also Sec. Formulas).
- put a
val [i=: j=: k=:]
Function sets value(s) of array a[i,j,k] = val
. Negative indexes i, j, k = :
set the value val
to whole range in corresponding direction(s). For example, put a val : 0 :
sets a[i,0,j]=val
for i=0...(a.nx-1), j=0...(a.nz-1).
- put a v
[i=: j=: k=:]
Function copies value(s) from array v to the range of array a. Negative indexes i, j, k = :
set the range in corresponding direction(s). At this minor dimensions of array v should be large than corresponding dimensions of array a. For example, put a v : 0 :
sets a[i,0,j]=v.ny>nz ? v[i,j] : v[i], where i=0...(a.nx-1), j=0...(a.nz-1) and condition v.nx>=a.nx is true.
13.3. Rearrange data
- crop dat
n1 n2
'dir'
Cuts off (crops) edges of data array dat with indexes n<n1
or >n2
along direction 'dir'.
- extend dat
dim1
[dim2=0
]
Increases the dimensions of the data dat by inserting new slices after (for n1
>0) or before (for n1
<0) the existing one. The nember of slices will be |n1|. It is possible to extend 2 dimensions simultaneously for 1d data by using parameter n2
. Data to new slices is the copy from the existing one. For example, for n1>0 new array will be aijnew = aiold where j = 0…n1. Correspondingly, for n1<0 new array will be ajinew = aiold where j = 0…|n1|.
- rearrange dat
mx [my=0 mz=0]
Rearrange dimensions without changing data array so that resulting sizes should be smaller initial one. If some of parameter my
or mz
are zero then it will be selected for optimal filling of data array. For example, if my
=0 then ny wil be equal to nx*ny*nz/mx and mz
will be 1.
- squeeze dat
rx
[ry=1 rz=1
]
Reduces the data size of array dat by excluding data elements which indexes are not divisible by rx, ry, rz
correspondingly.
- transpose dat ['dir'='yxz']
Transposes (shifts order of) dimensions of the data dat. New order of dimensions is specified in string 'dir'. This may be useful for the reading of one-dimensional data.
13.4. Commands on direction
- cumsum dat 'dir'
Cumulative summation of the data in given direction or directions.
- diff dat 'dir'
Differentiates the data in given direction or directions.
- diff dat xdat ydat [zdat=0]
Differentiates the data dat specified parametrically in direction xdat with ydat, zdat=constant. Parameter zdat can be omitted that correspond to 2D case. Parametrical differentiation uses the formula (for 2D case): da/dx = (aj*yi-ai*yj)/(xj*yi-xi*yj) where ai=da/di, aj=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 a x y
and usual derivative along 'y' will be diff a y x
.
- diff2 dat 'dir'
Double-differentiates (like Laplace operator) the data in given direction.
- envelop dat ['dir'='x']
Find envelop for data values along direction 'dir'. Only one direction can be specified at once.
- integrate dat 'dir'
Integrates (like cumulative summation) the data in given direction or directions.
- mirror dat 'dir'
Mirrors the left and right parts of the data dat in given direction 'dir' (like change index i to n-i).
- norm dat
v1 v2
[sym=off dim=0
]
Normalizes the data values of dat to range [v1, v2
]. If flag sym=on
then symmetrical interval [-max(|v1|, |v2|
), max(|v1|, |v2|
)] is used. The changes will be applied only for slices >dim
.
- normsl dat
v1 v2
['dir'='z' keep=on sym=off
]
Normalizes the data dat values for each slices in direction 'dir' to range [v1, v2
]. If flag sym=on
then symmetrical interval [-max(|v1|, |v2|
), max(|v1|, |v2|
)] is used. If keep=on
then maximal value of k-th slice will be limited by sqrt(Σ aij(k)/Σ aij(0)).
- sew dat ['dir'='xyz'
da=2*pi
]
Remove value steps (like phase jumps after inverse trigonometric functions) with period da
in given direction 'dir'.
- smooth dat
type
['dir'='xyz']
Smooths the data dat in specified direction(s) 'dir' by method type
. Now 4 methods are supported: 0 does nothing, 1 linear averaging by 3 points, 2 linear averaging by 5 points, 3 quadratic averaging by 5 points.
- swap dat 'dir'
Swaps the left and right parts of the data dat in given direction 'dir' (useful for Fourier spectrum).
13.5. Operators
- addto dat
val
Adds number to data.
- addto dat dat2
Adds data to data (cell-by-cell).
- subto dat
val
Subtracts number from data
- subto dat dat2
Subtracts data from data (cell-by-cell).
- multo dat
val
Multiplies data by number
- multo dat dat2
Multiplies data by data (cell-by-cell).
- divto dat
val
Divides data by number.
- divto dat dat2
Divides data by data (cell-by-cell).
14. Nonlinear fitting
These commands fit data to formula. Fitting goal is to find formula parameters for the best fit of the data points, i.e. to minimize the sum Σi (f(xi, yi, zi)-ai)2/si2. At this, the approximation function f can depend only on one argument x (1D case), on two arguments x, y (2D case) and on three arguments x, y, z (3D case). The function f also may depend on parameters. Normally the list of fitted parameters is specified by 'var' string (like, 'abcd'). Optional data ini set initial values for coefficients (by default zero values are used).
These commands fit and fits do not draw obtained data themselves. They just fill the data out by formula f with found coefficients. At this, the x, y, z coordinates in the formula are equidistantly distributed in bounding box. Number of points in out is selected as maximal value of out size or 100. Also you may print the last formula with found coefficients by putsfit command.
- fit out a 'eq' 'var' [ini=0]
Fits data along x-direction for each data row. This is 1D fitting with x equidistantly distributed in xrange and s=1.
- fit out x a 'eq' 'var' [ini=0]
Fits data along x-direction for each data row. This is 1D fitting with s=1.
- fit out x y a 'eq' 'var' [ini=0]
Fits data along x-, y-directions for each data slice. This is 2D fitting with s=1.
- fit out x y z a 'eq' 'var' [ini=0]
Fits data along x-, y-, z-directions. This is 3D fitting with s=1.
- fits out a s 'eq' 'var' [ini=0]
Fits data along x-direction for each data row. This is 1D fitting with x equidistantly distributed in xrange.
- fits out x a s 'eq' 'var' [ini=0]
Fits data along x-direction for each data row. This is 1D version of fitting.
- fits out x y a s 'eq' 'var' [ini=0]
Fits data along x-, y-directions for each data slice. This is 2D version of fitting.
- fits out x y z a s 'eq' 'var' [ini=0]
Fits data along x-, y-, z-directions. This is 3D version of fitting.
- putsfit
x y
['pre'='' 'fnt'='' size=-1
]
putsfit x y z
['pre'='' 'fnt'='' size=-1
]
Prints the last fitted formula with found coefficients at point {x, y, z
} by font 'fnt' with size
. String 'pre' sets the prefix which will be printed before formula. By default font parameters from font command are used. For more details see Sec. Text and font specification.
15. Color specification
MGL script have the only way for color specification. It is a symbols (characters) wkrgbcymhRGBCYMHW each of them define unique color. Normally capital letter gives darker color than lowercase one. The full list of characters is: k – black, 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).
[contents]
16. Line style specification
MGL script use strings for specifying the parameters of lines and marks. The string may contain specification for color (wkrgbcymhRGBCYMHW), dashing style (-|;:ji or space), width (0123456789) and marks (#o+xsd.^v). If one of type of information is omitted then the previous values are used. If string is empty then solid line with next color from palette is used. By default palette contain following colors:
dark gray 'H',
blue 'b',
green 'g',
red 'r',
cyan 'c',
magenta 'm',
yellow 'y',
gray 'h',
blue-green 'l',
sky-blue 'n',
orange 'q',
yellow-green 'e',
blue-violet 'u',
purple 'p'.
The color types are defined by symbols as described in Sec. 14.
Dashing styles has the following meaning: space – no line (usable for plotting only marks), – – solid line (■■■■■■■■■■■■■■■■), | – dashed line (■■■■■■■■□□□□□□□□), ; – small dashed line (■■■■□□□□■■■■□□□□), : – dotted line (■□□□■□□□■□□□■□□□), j – dash-dotted line (■■■■■■■□□□□■□□□□), i – small dash-dotted line (■■■□□■□□■■■□□■□□).
Marker types are: o – circle, + – cross, x – skew cross, s - square, d - rhomb (or diamond), . – point, ^ – triangle up, v – triangle down. If string contain # symbol then solid markers are used.
One may specify to draw special symbol (an arrow) at beginning and at the end of a line. It is possible if specification string contain one of following symbols: A – usual arrow, V – inner arrow, I – transverse hachures (or stop mark), K – arrow with hachures (or dimension mark), T – triangle, S – square, D – rhomb, O – circle, _ – nothing (it is default). At this there is a rule: first symbol specify the arrow at end of line, second symbol specify the arrow at beginning of line. For example, 'r-A' define red solid line with usual arrow at the end, 'b-AI' defien blue dash line with arrow at the end and with hachures at start, '-_O' define the line with current style and with circle at start. This styles are applicable also for any other plots (for example, plot).
contents
17. Color scheme specification
The color map scheme is used for coloring surfaces and other and is specified by the string. String may contain several characters which are color id (see Sec. 14) or character 'd' which denotes interpolation by 3d position instead of coloring by amplitude.
For coloring by amplitude (most common) the final color is linear interpolation of color array. The color array is constructed from string ids. The argument is the amplitude normalized between color range (see caxis, crange). For example, string containing 4 characters 'bcyr'
corresponds to colorbar from blue (lowest value) through cyan (next value) through yellow (next value) to red (highest value). String 'kw'
corresponds to colorbar from black (lowest value) to white (highest value). String 'm'
corresponds to simple magenta color. If color scheme specification contain symbol '|' then the colors are used as is (without interpolation) else the intermediate colors are found as result of linear interpolation (this is default).
There are several useful combination. String 'kw'
corresponds to simplest gray color scheme when higher values are brighter. String 'wk'
presents inverse gray color scheme when higher value is darker. Strings "kRryw"
, 'kGgw'
, 'kBbcw'
present the well-known "hot", "summer" and "winter" color schemes. Strings 'BbwrR'
and 'bBkRr'
allow to view bicolor figure on white or black background when negative values are blue and positive values are red. String 'BbcyrR'
gives color scheme similar to well-known "jet" color scheme.
Examples of the most popular color schemes
kw |  |
wk |  |
kHCcw |  |
kRryw |  |
kGgew |  |
kBbcw |  |
BbwrR |  |
BbwgG |  |
GgwmM |  |
bcwyr |  |
QqwcC |  |
CcwyY |  |
BbcyrR |  |
BbcwyrR |  |
bwr |  |
BbcyrR| |  |
bcyr |  |
bgr |  |
For coloring by coordinate the final color is determined by position of point in 3d space and is calculated by formula c=x*c[1] + y*c[2] + z*c[3]. Herec[1], c[2], c[3] are the first three elements of color array; x, y, z are normalized coordinates of the point. This type of coloring is useful for isosurface plot when color may show the exact position of peace of surface. For example, try surf3 a 'bgrd'
for some tensor data a.
[contents]
18. Text and font specification
Text style is specified by the string which may contain several characters of font (ribwou) and/or align (LRC) specifications. The string also may contatin the color id characters wkrgbcymhRGBCYMHW (see Sec. 14) after the symbol :. For example, 'biC:b'
sets the bold italic font style with aligning at the center and with blue color.
The font types are: r – roman font, i – italic style, b – bold style. By default roman roman font is used. The align types are: L – align left (default), C – align center, R – align right. Additional font effects are: w – wired, o – overlined, u – underlined. Also a parsing of the LaTeX-like syntax is provided.
The font size can be defined explicitly (if size>0) or relatively the base font size as |size|*fontsize (if size<0). The value size=0 specifies that the string will not be printed. The base font size is measured in internal "MathGL" units.
Parsing of the string to special (TeX-like) commands is switched on by default. There are commands for the font style changing inside the string: \a
or \overline
– overlined, \b
or \textbf
– bold, \i
or \textit
– italic, \r
or \textrm
– roman (throw any other attributes), \u
or \underline
– underlined, \w
or \wire
– wired, \big
– bigger size, @
– smaller size. The lower and upper indexes are specified by '_
' and '^
' symbols. At this the changed font style is applied only on next symbol or symbols in braces {}
. The text in braces {}
are treated as single symbol that allow one to print the index of index. For example, compare the strings 'sin (x^{2^3})'
and 'sin (x^2^3)'
. You may also change text color inside string by command #?
or by \color?
where '?' is symbolic id of the color. For example, words 'Blue' and 'red' will be colored in the string '#b{Blue} and \colorr{red} text'
and this string will be printed as "Blue and red text".
TeX parser recognize most of commands for special TeX or AMSTeX symbols (see below), the commands for font style changing (\textrm, \textbf, \textit, \overline, \underline
), accents (\hat, \tilde, \dot, \ddot, \acute, \check, \grave, \bar, \breve
), roots (\sqrt, \sqrt3, \sqrt4
), fractions (\frac
) and "stacked" text (\overset, \underset, \stack, \stackr, \stackl
). The full list contain approximately 2000 commands. Note that first space symbol after the command is ignored, but second one is printed as normal symbol (space). For example, the following strings produce the same result: '\tilde{a}'
; '\tilde a'
; '\tilde{}a'
.
There are some differences from LaTeX standard parsing:
- Several spaces are not ignored but printed one-by-one. This was done for allowing user to align the text inside string.
- Consecutive indexes (like,
'x^2^3'
) are not ignored but printed one-by-one. - The lower and upper indexes (like,
'x_2^3'
) are printed one-by-one. Use command \stackl
for printing aligned indexes (like, 'x\stackl{3}{2}'
or 'x\stackl 32'
).
The Greek letters are recognizable special symbols: α – \alpha, β – \beta, γ – \gamma, δ – \delta, ε – \epsilon, η – \eta, ι – \iota, χ – \chi, κ – \kappa, λ – \lambda, μ – \mu, ν – \nu, o – \o, ω – \omega, ϕ – \phi, π – \pi, ψ – \psi, ρ – \rho, σ – \sigma, θ – \theta, τ – \tau, υ – \upsilon, ξ – \xi, ζ – \zeta, ς – \varsigma, ɛ – \varepsilon, ϑ – \vartheta, φ – \varphi, ϰ – \varkappa; A – \Alpha, B – \Beta, Γ – \Gamma, Δ – \Delta, E – \Epsilon, H – \Eta, I – \Iota, C – \Chi, K – \Kappa, Λ – \Lambda, M – \Mu, N – \Nu, O – \O, Ω – \Omega, Φ – \Phi, Π – \Pi, Ψ – \Psi, R – \Rho, Σ – \Sigma, Θ – \Theta, T – \Tau, Υ – \Upsilon, Ξ – \Xi, Z – \Zeta.
The small part of most common special TeX symbols are: ∠ – \angle,
– \aleph, ⋅ – \cdot, ♣ – \clubsuit, ✓ – \checkmark, ∪ – \cup, ∩ – \cap, ♢ – \diamondsuit, ◇ – \diamond, ÷
– \div,
↓ – \downarrow, † – \dag, ‡ – \ddag, ≡ – \equiv, ∃ – \exists, ⌢ – \frown, ♭ – \flat, ≥ – \ge, ≥ – \geq, ≧ – \geqq, ← – \gets, ♡ – \heartsuit, ∞ – \infty,
– \in, ∫ – \int, \Int, ℑ – \Im, ♢ – \lozenge, ⟨ – \langle, ≤ – \le, ≤ – \leq, ≦ – \leqq, ← – \leftarrow, ∓ – \mp, ∇ – \nabla, ≠ – \ne, ≠ – \neq, ♮ – \natural, ∮ – \oint, ⊙ – \odot, ⊕ – \oplus, ∂ – \partial, ∥ – \parallel, ⊥ –\perp, ± – \pm, ∝ – \propto, ∏ – \prod, ℜ – \Re, → – \rightarrow, ⟩ – \rangle, ♠ – \spadesuit, ~ – \sim, ⌣ – \smile, ⊂ – \subset, ⊃ – \supset,
– \sqrt, § – \S, √ – \surd, ♯ – \sharp, ∑ – \sum, × – \times, → – \to, ∴ – \therefore, ↑ – \uparrow, ℘ – \wp.
[contents]
19. Formulas and functions
Formulas in MGL scripts is string with functions, operators, parentheses, variables, numbers and so on. There is no difference between lower or upper case in formulas. There are a lot of functions and operators available. The operators are: + – addition, – – subtraction, * – multiplication, / – division, ^ – integer power. Also there are logical "operators": < – true if x<y, > – true if x>y, = – true if x=y, & – true if x and y both nonzero, | – true if x or y nonzero. These logical operators have lowest priority and return 1 if true or 0 if false.
The basic functions are: sqrt(x) – square root of x, pow(x,y) power x in y, ln(x) – natural logarithm of x, lg(x) – decimal logarithm of x, log(a,x) – logarithm base a of x, abs(x) – absolute value of x,sign(x) – sign of x, mod(x,y) – x modulo y, step(x) – step function, rnd – random number, pi – number π = 3.1415926…
Trigonometric functions are: sin(x), cos(x), tan(x) (or tg(x)). Inverse trigonometric functions are: asin(x), acos(x), atan(x). Hyperbolic functions are: sinh(x) (or sh(x)), cosh(x) (or ch(x)), tanh(x) (or th(x)). Inverse hyperbolic functions are: asinh(x), acosh(x), atanh(x).
There are a set of special functions: gamma(x) – Gamma function Γ(x) = ∫0∞ tx-1 exp(-t) dt, psi(x) – digamma function ψ(x) = Γ′(x)/Γ(x) for x≠0, ai(x) – Airy function Ai(x), bi(x) – Airy function Bi(x), cl(x) – Clausen function, li2(x) (or dilog(x)) – dilogarithm Li2(x) = -ℜ∫0xds log(1-s)/s, sinc(x) – compute sinc(x) = sin(πx)/(πx) for any value of x, zeta(x) – Riemann zeta function ζ(s) = ∑k=1∞k-s for arbitrary s≠1, eta(x) – eta function η(s) = (1 - 21-s)ζ(s) for arbitrary s, lp(l,x) – Legendre polynomial Pl(x), (|x|≤1, l≥0), w0(x) – principal branch of the Lambert W function, w1(x) – principal branch of the Lambert W function. Function W(x) is defined to be solution of the equation: W exp(W) = x.
The exponent integrals are: ci(x) – Cosine integral Ci(x) = ∫0xdt cos(t)/t, si(x) – Sine integral Si(x) = ∫0xdt sin(t)/t, erf(x) – error function erf(x) = (2/
π) ∫0xdt exp(-t2) , ei(x) – exponential integral Ei(x) = -PV(∫-x∞dt exp(-t)/t) (where PV denotes the principal value of the integral), e1(x) – exponential integral E1(x) = ℜ∫1∞dt exp(-xt)/t, e2(x) – exponential integral E2(x) = ℜ∫1∞dt exp(-xt)/t2, ei3(x) – exponential integral Ei3(x) = ∫0xdt exp(-t3) for x≥0.
Bessel functions are: j(nu,x) – regular cylindrical Bessel function of fractional order nu, y(nu,x) – irregular cylindrical Bessel function of fractional order nu, i(nu,x) – regular modified Bessel function of fractional order nu, k(nu,x) – irregular modified Bessel function of fractional order nu.
Elliptic integrals are: ee(k) – complete elliptic integral is denoted by E(k) = E(π/2,k), ek(k) – complete elliptic integral is denoted by K(k) = F(π/2,k), e(phi,k) – elliptic integral E(φ,k) = ∫0φdt
(1 - k2sin2(t)), f(phi,k) – elliptic integral F(φ,k) = ∫0φdt 1/
(1 - k2sin2(t))
Jacobi elliptic functions are: sn(u,m), cn(u,m), dn(u,m), sc(u,m), sd(u,m), ns(u,m), cs(u,m), cd(u,m), nc(u,m), ds(u,m), dc(u,m), nd(u,m).
[contents]
20. Command options
Command options allow the easy setup of the plot by changing of global settings only for this plot. Options are specified at the end of string. Each option is separated from the previous text by symbol ';
'. Options work so that them remember the current settings, change settings as it being set in the option, execute command and return the original settings back. So, the options usage for data handling commands or for graphics setup commands is useless.
The most useful options are xrange, yrange, zrange. They sets the boundaries for data change. This boundaries are used for automatically filled variables. So, these options allow one to change the position of some plots. For example, in command plot y; xrange 0.1 0.9
the x coordinate will be equidistantly distributed in range 0.1 ... 0.9.
The full list of options are:
- alpha
val
Sets alpha value (transparency) of the plot. The value should be in range [0, 1].
- alphadef
val
Sets alpha value (transparency) of the plot. The value should be in range [0, 1].
- ambient
val
Sets brightness of ambient light for the plot. The value should be in range [0, 1].
- crange
val1 val2
Sets boundaries of color change for the plot.
- cut
val
Sets whether to cut or to project the plot points lying outside the bounding box.
- fontsize
val
Sets the size of text.
- legend 'txt'
Adds string 'txt' to internal legend accumulator. The style of described line and mark is taken from arguments of the plot command. The maximal number of entries is 100.
- marksize
val
Sets the size of marks.
- meshnum
val
Work like meshnum command.
- xrange
val1 val2
Sets boundaries of x coordinate change for the plot.
- yrange
val1 val2
Sets boundaries of y coordinate change for the plot.
- zrange
val1 val2
Sets boundaries of z coordinate change for the plot.
[contents]
21. Suffixes for variable
Suffixes can get some numerical value (like its size, maximal or minimal value, the sum of elements and so on) of the data array in variable and use it later as usual number in command arguments. The suffixes start from point '.' right after (without spaces) variable name or its subarray. For example, a.nx
give the x-size of data a b(1).max
give maximal value of second row of variable b c(:,0).sum
give sum of element in first column of c
and so on.
The full list of suffixes are:
- nx, ny, nz
Give the data size in x-, y-, z-direction correspondingly.
- max
Give maximal value of the data.
- min
Give minimal value of the data.
- mx, my, mz
Give x-, y-, z-position of data maximum.
- ax, ay, az, aa
Give x-, y-, z-position of data mass center or average data value.
- wx, wy, wz, wa
Give width in x-, y-, z-direction or data dispersion value.
- sx, sy, sz, sa
Give skewness in x-, y-, z-direction or data skewness value.
- kx, ky, kz, ka
Give kurtosis in x-, y-, z-direction or data kurtosis value.
- sum
Give sum of data values.
- a
Give first value of data array.
- fst
Give first nonzero value of data array.
- lst
Give last nonzero value of data array.
[contents]