XFBP¶
Author: | Klaus Koepernik |
---|
- Python scripting
- Native Scripting
- Comments
- File loading
- Print commands
- Paper commands
- Graph/Group/Set/Weight descriptors
- With command
- World commands
- View commands
- Legend box commands
- Graph commands
- Shape commands
- Text box commands
- Tic mark commands
- Group commands
- Set commands
- Set attribute commands
- Weight commands
- Weight settings
- Weightlabel definitions
- Line style commands
- Fill style commands
- Font style commands
- Symbol style commands
- Kill commands
- Copy/Move commands
- Hook commands
- Cursor reference
- Assignments/Definitions
- Expressions
- GUI
- Logarithmic plots
- Data
- Files
- Command line options
- Data file types
- Set Dialog
- Color Model dialog
Python scripting¶
If the program was compiled with python support the pyxfbp help is displayed when F1 is hit in the
script/transform dialog if the editor is set to python mode. The
python scripts should have the extension .xpy
since they do not
work in other python shells.
Native Scripting¶
The Transform Dialog is actually a script editor, where xfbp commands from the file description language and some more commands can be used. For python mode go here.
The commands can be saved to file or loaded from file (extension
.cmd
). To get familiar with the commands you can use the insert
functionality of the editor. We also recommend to look at the .xfp
files: save the current plot (.xfp
) (not the current script) and
look at the .xfp
file.
We try to describe the scripting language in the following, including examples. To copy these examples into the script editor, select and copy them via Ctrl-C and paste them (Ctrl-V) into the script editor.
The language is made of statements. Each statement is a single line.
In the following optional parts of a statement are enclosed in square
brackets []
. A construct like (a|b|c|....)
means that at this
position in the command either a
or b
or c
… can be
used. If parentheses (
and )
appear without a |
between
them they are literals, which means you have to type them (example:
sin(x)
). They will be set in bold face in the command
description. Similarly square brackets [
and ]
can appear in
vector element constructs (example: s1.x[6]=12.5
).
In the following key words are denoted by keyword. They are not case sensitive. Values are denoted by value. There are different values:
sub commands like linestylecommands
expressions like exp, which can be numbers, variables, parameters and some other constructs. They evaluate to scalars or vectors
strings, which are used for file names and text. They must be enclosed within double quotes, example:
read xny "+dos.total" read bandweight "+bweights"
parameters are values defined on the command line via option -a and are available in the script editor via $parametername. Example: Create a command file
t.cmd
with the content:kill all read xny $pp with g1.gr1.s1 line width $w legend $leg title "Density of states"
From the command line call:
xfbp t.cmd -a pp:"+dos.sort001" -a leg:"Fe" -a w:2
- Of course, you have to make sure that there is actually a file
+dos.sort001
for this to work.
Important: when graphs, groups, sets or weights are referenced in the script, they will be made current, which means that they will be remembered until the next such explicit reference makes another graph… the current object. This allows to skip these specifiers in many contexts.
Content
File loading¶
read filetype (string | parameter ) [(into (graphdesc | groupdesc ) | into new graph)]
Read file with name string or with its name provided in a parameter into current graph (or a specific graph/group) enforcing data type filetype. (string | parameter) is something like “myfile.dat”. Band structure data cannot be read into specified groups, since they are organized into groups by the programm.
Examples:
# killall and initialize graph 1 killall # read band strcture into current graph (graph 1) read band "+band" # read two files into graph 2 read xny "+dos.total" into g2 read xny "+dos.sort001" into g2.gr5
Print commands¶
Currently there is only two options to print: png
and eps
files. The printed eps
format is not yet fully eps standard, but
works, especially embedded in LaTeX.
print to (string | parameter) [dpi int (quality real) | quality real (dpi int )]
export plot to file named string in
eps
orpng
format (the file extension determines which). Example:print to "bands.png" dpi 300 quality 0.95
print filename (string | parameter)
set the the file name for print commands to string or parameter.
print to file
export plot in
eps
orpng
format to file. (The filename must have been defined before.)
Paper commands¶
paper size int , int
set paper size from width and height (integer). Example:
paper size 400,200
paper size papersizes
set paper size from paper size names, e.g. a1…a10, letter, lettersmall, legal, statement, tabloid, ledger, folio, quarto. Example:
paper size a4 paper orientation portrait
paper orientation (portrait | landscape)
set orientation. Only for predefined paper sizes.
arrange ( paperwidth , Nx , xgap0 , xgap1 , deltawidth , Ny , ygap0 , ygap1 , deltaheight , aspectratio, commonxaxis, commonyaxis, commontitle )
arrange Nx* Ny graphs on a grid. The graphs can already exist. Otherwise they are created. The index runs row by row. xgap0/xgap1 are the spaces left/right of the first/last viewbox in percent/100 of the paper width. Similarily ygap0/ygap1. deltawidth/deltaheight are the in-between gaps in percent/100 of the individual viewbox width/height. aspectratio determines the individual viewbox aspect ratio. Note, that the point scale of the graphs depends on the paperwidth. You need to experiment with the gap values a bit to get the labels/ticmarks/titles properly displayed in the page. If commonxaxis is nonzero the in-between-viewboxes tic labels and xaxis labels are switched off and in each column the world x axis is made equivalent. Similarily, for commonyaxis. For this to work the arrange command must be issued after setting up the graphs. If commontitle is nonzero the titles in between rows are switched off:
arrange(800, 3,0.12,0.03,0.1, 2,0.12,0.15,0.1, 1.0, 1,1,1)
Graph/Group/Set/Weight descriptors¶
Data belong to graphs and are organized in groups and sets. graph/group/set/weight s have descriptors, which are explained here. Note, that there is the concept of a current graph/group/set/weight. The current object is memorized after a descriptor appeared in the script until another object becomes current by the appearance of another descriptor . Hence we can write:
g1.gr2.s1 line color 0xff
line width 2.5
line symbol ...
to change the settings of set 1 in group2 in graph 1.
gint
graph int: g4 is graph 4.
grint
group int in the current graph (if valid)
sint
set int in the current graph and current group
gint1 . grint2
group int2 in graph int1
[[gint1 . ]grint2 . ]sint3
set int3 in current group or group int2 in current graph or graph int1
[(groupdesc | setdesc) . ](x | y)
vector of x/y values in groupdesc/setdesc or current group/set. Example:
g1.gr1.x=x+1
, will increase all x values of all sets ing1.gr1
by one. The full command would beg1.gr1.x=g1.gr1.x+1
, but this is not necessary. Andg1.gr1.s2.y=y*2
, will multiply all y values of setg1.gr1.s2
by two.
Note, that each descriptor resets the higher level to invalid, such that following works:
g1.gr1.s3 line color 0x00
# now current set is s3, current group is gr1
line width 2.4
# it is still set 3
g1.gr1.x=mesh(...)
# after g1.gr1 the current set is invalid and
# hence all x of group1 get assigned a mesh
line width 2.4
# now we just set the line width for all sets in group 1
Each set can have a number of weights associated with them. If all sets of a group refer to the same set of weights (same set of weight labels.) the group can be used to manipulate the weight appearance. (bandweight plots)
[(groupdesc | setdesc) . ]wint
weight number int in groupdesc/setdesc or current group or set (whichever was defined/refered-to previously). Example:
g1.gr1.w8 off # turns off weight 8 in group 1.
[(groupdesc | setdesc) . ]wstring
weight with name string in specified or current group/set. The names must match the existing weight labels exactly. Example:
w"Cu(001)3s+0" off.
With command¶
The current graph/group/set/weight descriptors can be set without reference to a particular commmand.
with (graphdesc | groupdesc | setdesc | weightdesc)
set the current . Example:
with g1.gr1.s3 line color 0xff0000 symbol style circle # now weigths with implicit with (remembered from the last weightdescriptor) w1 off w"Cu(001)3d+0" on # set this weights color color 0xff0000 # and the skippage skip 5
World commands¶
World commands refer to a certain graph, which either is specified explicitly or was set as current graph before.
[graphdesc] world (xmin | xmax | ymin | ymax) exp
set world
,
,
or
for graph. Example:
world xmin -1
[graphdesc] world (x | y) exp , exp
set the x or y interval of the world coordinates. Example:
world x -1,10
autoscale [(x | y)]
autoscale all, x-only or y-only. Example:
autoscale x
autoscale offset exp , exp
define the autoscale offset for both directions. This is the space in percent*100 of the total world interval, which will be added on both sides of the intervall. If non-zero, an autoscale will leave the specified percentage of space at either side of the plotted curves.
The current settings can be loaded from the insert menu in the script editor.
View commands¶
The view is the area spanned by the frame of the graph. It is defined in relative coordinates with respect to the paper. A view of width 1 and x-origin 0 would produce a graph frame spanning the whole breadth of the paper. In the following graphdesc can be left out if previously a graph was referenced (with gint, or other references).
[graphdesc] view exp , exp , exp , exp
set x-origin, width, y-origin and height of the view. x,y=(0,0) is the upper left corner and x,y=(1,1) the lower right corner. exp must evaluate to a scalar.
[graphdesc] view frame (on | off)
switch frame of view on or off
[graphdesc] view frame rim linestylecommands
use linestylecommands for the rim of the view frame
[graphdesc] view frame fill fillstylecommands
use fillstylecommands for the view frame filling
The current settings can be loaded from the insert menu in the script editor.
Legend box commands¶
The legend box belongs to a particular graph. The following commands refer to the current graph. They can also be prefixed with a graphdesc or follow after with gint to set the current graph (as indicated in graphcommands).
legend (on | off)
switch legend box on or off
legend font fontstylecommands
use fontstylecommands for text in legendbox
legend line spacing exp
set spacing between legend box entries (lines). exp must evaluate to a scalar.
legend symbol marker spacing exp
set spacing between symbol and text
legend symbol marker width exp
set width of symbol before the text
legend frame (on | off)
switch frame on or off
legend frame rim linestylecommands
use linestylecommands for the rim
legend frame border spacing exp
set spacing between rim (border) and content (symbols, text)
legend frame fill fillstylecommands
use fillstylecommands for the frame
legend position exp , exp
set legend position relative to the view frame (y=0 is on the top). The position refers to the point of the legend box given as origin (see below)
legend origin exp , exp
define the point of the legend box, which is considered its origin. (the position command places this point.)
The current settings can be loaded from the insert menu in the script editor.
Graph commands¶
Graph commands will manipulate graphs. A graph is a single view-frame/plot with axes, which can contain several groups/sets. Graphs have (irregular) tic mark settings and can contain shapes (lines/ellipses). Graphs can be scaled.
graphdesc (on | off | toggle)
switch graph on or off or toggle on/off (for hookcommands). Example:
g2 on
new graph
create a new graph. More control is achieved via switching a particular graph on or off.
[graphdesc] textboxcommands
use textboxcommands for the current/specified graph. Example:
g1 subtitle on subtitle "some subtitle" subtitle font color 0xff
[graphdesc] legendboxcommands
use legendboxcommands for the current/specified graph.
[graphdesc] ticmarkcommands
use ticmarkcommands for the current/specified graph.
[graphdesc] irregularticmarkcommands
use irregularticmarkcommands for the current/specified graph.
[graphdesc] graph line width scale exp
set an overall line width scale for the current/specified graph. This affects all line widths.
[graphdesc] graph point size scale exp
set an overall point size scale for the current/specified graph. This affects font and symbol sizes and line widths.
[graphdesc] shapecommands
manipulate shapes (arrows/lines/ellipses), see shapecommands. Example:
g1 line1 on line1 line width 2
Shape commands¶
In the moment line shapes (lines/arrows) and ellipses (circles) can be added to a graph. First let us define shape descriptors:
ellipse[ ]int
reference to ellipse number int. The space between the keyword and the number is optional. Example:
ellipse3
line[ ]int
reference to line shape number int. This can be an arrow not just a line. The space between the keyword and the number is optional. Example:
line 2
Now, we give the details for each shape type. Some commands are specific for the particular shape kind others are common.
shapedesc (on | off)
switch on (create it of not yet existing) or off a shape. Example:
line1 on
shapedesc name (string | parameter)
give the shape a name. This is usefull in the GUI, where all shapes appear in a list. Example:
line1 name "my-fancy-line-name"
shapedesc line linestylecommands
use linestylecommands for the shape’s rim/line.Example:
line1 line color 0xff line1 line style dot
shapedesc coordinatesystem (view | world)
use this coordinate system’s units for the shape’s size/positional settings. World coordinates refer to the physical coordinates of the underlying plot. Hence, changing the zoom of the plot will move the shape with it. View coordinates refer to the graph’s view/frame. These are rleative coordinates, where
x,y=(0,0)
is the upper left corner andx,y=(1,1)
is the lower right corner of the view.ellipsedesc fill fillstylecommands
use fillstylecommands for the ellipse’s interior. Example:
ellipse1 fill color 0xff ellipse1 fill on
ellipsedesc angle exp
set the angle about which the ellipse is rotated.
ellipsedesc center exp , exp
set the center of the ellipse. This refers either to world or view coordinates.
ellipsedesc radii exp , exp
set the two radii of the ellipse. This refers either to world or view coordinates.
ellipsedesc radius exp
set both radii of the ellipse to the same value (making it a circle). This refers either to world or view coordinates.
linedesc arrow fill fillstylecommands
use fillstylecommands for the line. Note, that only the fill color command does work here, i.e. closed arrow heads allways have
fill on
. If an empty head is required, usefill color 0xffffff
(white).linedesc (arrow | cap) position (none | start | end | both)
set the position of the arrow head or cap on the line shape. A cap is a little runding off at the end of the line. better visible if the line width is larger.
linedesc arrow style (open**| **closed)
open arrows are made of lines, closed ones are haveing a filling.
linedesc arrow (size | sharpness) exp
set the size or sharpness of the arrow head.
linedesc (start | end) exp , exp
set the start and the end of the line shape. (refers to the specified coordinatesystem.)
The current settings of existing shapes can be loaded from the insert menu in the script editor.
Text box commands¶
Text boxes are used for axis labels but can also be placed freely in the graphs. They belong to a particular graph. The special text boxes like axes- and tic labels can impose restrictions on each others placement, which are used to keep them at reasonable distance from each other. Text boxes have an origin, with respect to which the position is defined.
Textboxes are identified by a descriptor:
textbox[ ]int
the general text box number int. The space is optional. Example:
textbox1 #or textbox 1
- (title | subtitle | xaxislabel | yaxislabel |
oppositexaxislabel | oppositeyaxislabel)
one of the special textboxes
Now, the commands:
textboxdesc (on | off)
switch textbox on or off
textboxdesc (string | parameter )
set the content of textbox to string or parameter. The string can contain formating. Example:
title "N$_0$.$x{-0.7}$^$iFe$n$."
will produce
textboxdesc font fontstylecommands
use fontstylecommands for textbox. Example:
title font color 0xff00ff
textboxdesc frame (on | off)
switch this textbox’s frame on or off.
textboxdesc frame rim linestylecommands
use linestylecommands for the frame rim of textbox
textboxdesc frame fill fillstylecommands
use fillstylecommands for the filling of textbox’s frame
textboxdesc frame border spacing exp
define the space between the frame rim and the text.
textboxdesc coordinatesystem (view | world)
Set the coordinatesystem for the text position.
textboxdesc position exp , exp
set the position of the textbox. This referes to the specified coordinate system. See origin below.
textboxdesc origin exp , exp
The textbox has an origin, which is positioned accoding to the position command.
textboxdesc angle exp
set the rotation angle of the textbox
textboxdesc restriction (+x | -x | +y | -y) exp
restrict the movement of this textbox to the positive/negative x/y-axis and shift it in this direction by the amount exp. Example:
title restriction -Y 0.03
textboxdesc restriction none
define that there are no additional placement restrictions for this textbox
textboxdesc restriction additional [ int [ int [ int…]]]
define a list of int values, encoding various additional restrictions refering to the special text boxes. The list can be empty.
x-tic labels int y-tic labels int sub-title/axis-labels int opposite x tic label height 1 opposite y tic label width 5 subtitle offset 9 opposite x tic label offset 2 opposite y tic label offset 6 subtitle height 10 normal x tic label height 3 normal y tic label width 7 opposite x-axis label offset 11 normal x tic label offset 4 normal y tic label offset 8 opposite x-axis label height 12
The current settings of existing textboxes can be loaded from the insert menu in the script editor.
Tic mark commands¶
Tics come in two varieties: regular tics, which are graph specific and irregular tics which can belong to a graph or a group.
Regular tic commands:¶
(x | y) auto tic[s] (on | off)
auto tics on means that the tic spacing is determined automatically, off means that the user has to set the major tic spacing and the minor tic subdivisions. Example:
x auto tics off
- (x | y) axis scaling (log[arithmic] |
lin[ear])
set the axis scaling to linear or logarithmic. Also read Logarithmic plots. Example:
x axis scaling log
(x | y) tic[s] side (none | normal | opposite | both)
on which side to place the tics. Example:
x tic side opposite
(x | y) (major | minor) tic[s] (on | off)
switch the drawing of x/y major/minor tics on or off. Example:
x minor tics off
(x | y) major tic[s] spacing exp
the distance of major tics in world units. For logarithmic axes the spacing between two major tics is determined by multiplication with this number instead. Example:
x major tic spacing 0.1
y (major | minor) separate tic[s] length (on | off)
if switched on, the length of the y axis tics is set separatly. Otherwise it is the same physcial length as for the x-axis tics. Example:
y major separate tic length on x major tic length 0.03 y major tic length 0.05
(x | y) (major | minor) tic[s] length exp
set the length of the tics in view units.
(x | y) minor tic[s] subdiv int
set the number of subdivisions of a major tic interval to define the position of the minor tics.Example:
x minor tic subdiv 2
(x | y) (major | minor) tic[s] line linestylecommands
use linestylecommands for the tics. Example:
x major tic line color 0xff00
(x | y) tic[s] label[s] decimals int
set the number of decimals to be printed in the tic labels. A negative number signals to use the automatic default. Example:
x tic label decimals 2
(x | y) tic[s] label[s] offset exp
the label offset from the axis in view units. Example:
x tic label offset 0.1
(x | y) tic[s] label[s] side (none | normal | opposite | both)
where to draw the tic labels. Example:
x tic label side both
(x | y) tic[s] label[s] font fontstylecommands
use fontstylecommands for label’s text. Example:
x tic label font color 0xffff
Irregular tic commands¶
Irregular tics can be owned by graphs and groups. Group owned irregular tics will be visible if the group is visible. These commands must follow after a particular graph/group was specified by a previous command (graphcommands, groupcommands) or via a with-command. The group irregular tic mark commands always need a groupdesc prefix.
irregular tic[s] (on | off)
switch on irregular tics. Example:
gr1 on g1.gr1 irregular tics on
The irregular tics get descriptors formed in the following way:
itic[ ]int
an irregular tic descriptor. The space is optional. Example:
itic1
Now the commands
iticdesc type (x | y) (major | minor)
define if itic is an x or a y tic and if it is major or minor. Major tics can have labels. Example:
itic1 type y major
iticdesc length exp
define the tic length of itic. This is in view units. a length of 1 creates a line spanning the whole view area. Example:
# span the full itic1 length 1
iticdesc position exp
the tic position in world units. Example:
itic1 position 0
iticdesc label[s] (string | parameter)
the itic’s label. Only for major labels. Example:
itic1 label "E$_F$."
iticdesc tic[s] side (none | normal | opposite | both)
at which side to draw the itic
iticdesc label[s] side (none | normal | opposite | both)
at which side to draw the itic label:
itic1 tic side normal itic1 label side opposite
iticdesc label[s] offset exp
the label offset from the axis in view units. Example:
itic1 label offset 0.07
iticdesc line linestylecommands
use linestylecommands for the itic. Example:
itic1 line style dot
Example: the Fermi level can be done like this:
gr1 on
g1.gr1 irregular tics on
itic1 type y major
itic1 length 1
itic1 position 0
itic1 label "$~e$_F$."
itic1 label side opposite
itic1 line style dot
Group commands¶
Group commands manipulate groups. They act on the current group, which can be set either explicitly or implicitly as explained in so many other places.
[groupdesc] use attributes (on | off)
if on, the group attributes will be used for each set of the current or specified group. When switched off, each set’s individual properties will be used.
[groupdesc] setattribcommands
use setattribcommands for the current or specified group
[groupdesc] weightsettings
use weightsettings for the current or specified group
groupdesc irregularticmarkcommands
define irregularticmarkcommands for this group.
Set commands¶
Set commands are commands, which modify a single set (sometimes all sets of a group). The set can be made current via the with command or via at least one explicit set descriptor.
Example:
# we assume that the current graph and group are already set
s1 on
# alternatively
with s1
# now the properties
line color 0xff0000
symbol style circle
convolute(s1,0.5)
[setdesc] setattribcommands
use setattribcommands for this set
[setdesc] weightsettings
use weightsettings for this set
[(setdesc | groupdesc) . ](x | y) = exp
assign exp to the x/y-vector of this group/set. exp can be a vector or scalar expression. Example:
# this will create a parabola by setting y[i]=x[i]^2 # for each point i in the set g1.gr1.s1.y=x^2 # or with g1.gr1.s1 y=x^2
convolute ( setdesc , exp )
convolute the set with a Gaussian of half width exp.
setdesc length exp
set the length of the x and y vectors. (The set must by of xy-type.)
bspline ( setdesc , int1 , int2 )
construct the int2-th derivative of the B-spline interpolation of order int1 of the set and apply it to the set. B-splines are spline interpolations of arbitrary order. Note, that there must be a minimum number of data points to construct it. Zeroth order means histogram. First order means linear interpolation second order quadratic spline-interpolation and so on. Note, that int2=0 means zeroth derivative and that nothing changes, since the bspline is an exact interpolation at the data points and a zeroth derivative is an identity. To calculate derivatives you chose a spline order, which does not lead to too many wiggles but is high enough to smoothly represent the data. Example:
killall with g1.gr1 s1 on N=100 m=mesh(0,10,N) s1 length N x=m y=sin(x) line color 0xff copy s1 to s2 s2.y=cos(x) line color 0xff0000 #first derivative bspline(s1,2,1) copy s1 to s3 #difference s3.y=y-s2.y line color 0xff00 legend "error" autoscale
bspline ( setdesc , int1 , int2 , identifier )
construct the int2-th derivative of the B-spline of order int1 and interpolate it onto the x-vector pointed to by identifier, which must be a vector. The result is saved in set.y. Example
kill all g1.gr1.s1 on data xy 0 0 1 1 2 4 end data legend "raw data\char" line color 0xf00 symbol style circle symbol fill on line style none N=100 m=mesh(-1,3,N) copy s1 to s2 bspline(s2,1,0,m) s2 legend "spline order 1" line color 0xff0000 copy s1 to s3 bspline(s3,2,0,m) s3 legend "spline order 2" line color 0xff00 autoscale
integrate ( setdesc )
running sum integral of set. This produces the curve
for each point
in the set (upper boundary indefinite integral). For derivatives see bspline. If you need the value of the integral in a script do something like:
integrate(s1) sum=y[length-1]
- data datatypedatalinesend data
define a block of data of datatype
datatype explanantion xy standard y(x) grid/xynz z(x,y) xynw y(x) and w(x,y) The datalines depend on the datatype. They may contain identifier and things like world.xmin. Example. Also look at saved
.xfp
files. [setdesc] weightlabel[s] reference[ ]int
set the weight label reference of the current set to int. This refers to a particular weightlabeldefinitions, defined elswhere. Sets with the same reference are treated as having the same set of weights. This allows to manipulate the weights settings of all these sets together (especially when grouped). The number of weights and dimensions of x/y of all these sets must be the same!
Set attribute commands¶
Set attributes can be applied to groups or sets. The last group/set descriptor or with command will decide which object’s attributes are defined. You can also prefix each command or at least the first of a series of such commands with an explicit group/set descriptor.
(on | off)
switch the current group/set on or off.
toggle
toggle the current group/set. (For hookcommands)
line linestylecommands
use linestylecommands for the current group/set.
symbol symbolstylecommands
use symbolstylecommands for the current group/set.
legend (string | parameter)
set the legend string for the current group/set.
showin legend (on | off)
decide if group/set this is shown in the legend box.
interpolationdepth int
set the interpolation depth for grid/density plots.
max cutoff exp
set the upper cutoff for density grid/density plots. see “scalemax” in Section SetDialog.
min cutoff exp
set the lower cutoff for density grid/density plots. see “scalemin” in Section SetDialog.
min color hexconstant
set the data-background color for density grid/density plots. see “z0” in Section SetDialog.
null cutoff exp
set the z-value under which data background color is gradually inserted for density grid/density plots. see “z0” in Section SetDialog.
zpower exp
set the power law for mapping of z-values onto colormaps for density grid/density plots. see “zpower” in Section SetDialog.
zcomponent exp
set which z-component is ploted for density grid/density plots. This is usually 0. see Section SetDialog.
colormap from exp , exp
exp must be hex constants and represent colors. The resulting colormap is interpolated between the two.
colormap name string
select a predefined colormap
Terrain Hot Autumn RainBow Heat Winter Magma Spring Gnuplot Inferno Summer Seismic RainBow2 RainBow3 - colormap expreal : hexconstant real : hexconstant …real : hexconstant real : hexconstant ……colormap end
This is a list of pairs of z-values in
[0,1]
and hex-colors. Each line can contain arbitrary number of pairs. There can be arbitrary number of lines. There are no commas. This defines a set of mappings of z-values from the standard interval onto colors. If exp is nonzero the interpolation is done in RGB space, otherwise in the circular hue-saturation space. use secondderivative (on | off)
(deprecated does not work) decide the use of second derivatives for grid/density plots.
setcomment string
set the “set-comment” of the current group/set. Set-comments denote, where the data came from. This is mostly used in the *.xfp files, which get saved and loaded by xfbp.
Weight commands¶
Weight commands determine the appearance of individual weights of groups or sets. The internal organization of weights into groups is a bit confusing. As long as your weights came from an fplo bandweights file it should work alright. Weight descriptors can be made current via a with command or by using a weightdesc (at least for the first command which belongs to a particular weight) Examples:
w11 on
plotorder 1
name "yx"
# or
with w11
on
plotorder 1
name "yx"
[weightdesc] (on | off)
switch the weight on or off. Note, that if the current weightdesc is invalid but some other descriptor is valid, this command switches the currently valid graph/group/set. Example:
with g1 on # we switched graph 1 with gr1.w2 # implicit g1 explicit gr1 and w2 on # now, we switched weight 2
[weightdesc] plotorder int
the weight with the higher plotorder gets plotted later.
[weightdesc] name (string | parameter)
rename the weight. This affects the legend entry. Note, that a name change also means that the weightdesc
w"weigthname"
changes as well. Furthermore the weight label/name is unique in that it is a property of the weight itself such that if one changes the name of a weight in a group it also changes the name of this weight in all sets, which are assoziated to this weight. i.e. all sets of all groups, which are belonging together, like spin up and down groups of a +bweights plot.[weightdesc] color hexconstant
set the weights color to hexconstant
[weightdesc] skip exp
skip as many symbols between plotted symbols (unless weight style is connected). skip 0 means: plot all symbols.
[weightdesc] symbol fill (on | off)
fill symbols or not. (only if is weight style individual).
[weightdesc] symbol line width exp
for open symbols the symbol line width matters. (only if weight style is individual).
[weightdesc] symbol style symboltype
set the symboltype. (only if weight style is individual).
Weight settings¶
Weight settings can be applied to groups or sets. The last group/set descriptor or with command will decide which object’s settings are defined. Weight settings affect the appearance of all visible weights of a group or set.
weight max exp
set the symbol size, which represents a weight value of 1. exp is in a scale like font sizes.
weight min exp
set the weight symbol size, under which no symbols will be plotted. This depends on max since it scales everything up.
weight factor exp
scale all weights by this factor, before applying max and min. (This is somehow superfluous).
weight style (dots | connected | individual)
set the style of the weights.
dots individual filled circles for each data point connected connect the circles by linear intepolation individual each weight can have its own symbol
Weightlabel definitions¶
This is special stuff to define tables of weightlabels especially in saved files.
- weightlabel definition[s]weightlabels[ ]int1stringlistend weightlabel[s]…weightlabels[ ]intnstringlistend weightlabel[s]
define tables of weightlabels with references int1 through intn. See weightlabel references. stringlist is a list of weight labels (strings), each on a separate line.
Line style commands¶
Line style commands are used in several other commands.
color hexconstant
define the color using a hex number, which encodes the RGB (red-green-blue) color components. The constant contains three bytes (leading zeros need not be specified) the left-most is red, then green and right-most is blue:
hex color red green blue 0x000000=0x0 black 0 0 0 0xff0000 red 255 (ff) 0 0 0x00ff00=0xff00 green 0 255 (ff) 0 0x0000ff=0xff blue 0 0 255 (ff) 0x800000 darkred 128 (80) 0 0 0xffffff white 255 (ff) 255 (ff) 255 (ff) width exp
set line with
style (linestyle | int)
set line style via name or number
linestyle int linestyle int linestyle int none 0 long dash 7 solid 1 dash dot 4 long dash dot 8 dash 2 dash dot dot 5 long dash dot dot 9 dot 3 dot dash dash 6 dot long dash long dash 10 Example:
s1 line style dash # or s1 line style 2
Fill style commands¶
These commands appear in various other commans and usually cannot stand by themselfs (they are preceded by … fill).
color hexconstant
define fill color using a hexconstant
(on | off)
switch filling on or off
Font style commands¶
These commands are used in several commands after font.
size exp
set the font size to exp, which must evaluate to a number.
subscriptscale exp
set the scaling down ratio of subscript
color hexconstant
define font color using a hexconstant
Symbol style commands¶
These commands are used in other commands and preceded by symbol.
style (symboltype**int)
set symbol style by name or number
symboltype int symboltype int symboltype int none 0 triangleup 4 plus/+ 8 circle 1 triangleleft 5 cross/x 9 square 2 triangledown 6 star/* 10 diamond 3 triangleright 7 Example:
s1 symbol style square # or s1 symbol style 2
size exp
set the symbol size to exp, which must evaluate to a number. The symbol sizes have the same scale as font sizes.
fill fillstylecommands
use fillstylecommands for the symbol.
line linestylecommands
use linestylecommands for the rim
Example:
g1.gr1.s1 symbol style diamond
symbol size 18
symbol fill on
symbol fill color 0xff0000
symbol line color 0x0000ff
symbol line width 2
Kill commands¶
kill[ ]all
kill everything (clean slate) and initialize graph 1 in default state. The space between the keyword and the number is optional.
kill (graphdesc | groupdesc | setdesc)
remove graph/group/set. If the last graph was killed graph 1 is initialized in a default state. Example:
kill g1.gr12
Copy/Move commands¶
Use these to move sets around or copy them.
(copy | move) setdesc1 to setdesc2
copy/move set1 to set2. Moving is essentially renaming. Note, that you can move a set to a different graph and/or group:
# here I shall have a g1.gr1.s1 g2 on # now we have graph 2 gr3 on # now we have a group3 in graph 2 # in order to move g1.gr1.s1 there, we have to explicitly spell out g1.gr1, # since the last command defined the current descriptor as g2.gr3, hence: move g1.gr1.s1 to g2.gr3.s11 # now we have moved the set into s11 in graph 2 group 3 # in order to move the s11 to s1 in g2.gr3 we do not have to change groups or graphs # hence, move s11 to s1 # will work
Hook commands¶
Sometimes it is usefull to have the program do something when the mouse is clicked on a certain point in a graph. This can be done by ”hooking” a particular command to the mouseclick.
hook mouseclick left command-as-string
set the command in command-as-string to be hooked onto the left mouse click. In the moment only left mouse click is implemented. When hooking is active the current world point (at clicking) is written into the file
+currentpoint
. command-as-string can stretch over multiple lines to allow for several commands. Example:hook mouseclick left " with g1.gr10 s1 on s1 length 2 x[0]=cursor.x x[1]=cursor.x y[0]=world.ymin y[1]=world.ymax line color 0xff0000 "
This will draw a vertical red line at the mouse position when clicked.
Cursor reference¶
If hook commands are active the world coordinates pointed to by the mouse cursor can be references.
cursor . (x | y)
reference the world coorinate under the mouse cursor. Example:
hook mouseclick left "world xmin cursor.x world ymin cursor.y"
Note, the newline within the string!
Assignments/Definitions¶
- One can in a limited way define variables: scalars and vectors.
identifier = exp
define a variable name identifier and assign it exp. Note, that “length” cannot be an identifier name. Example:
N=100 m=mesh(0.1,12.3,N)
[setdesc . ](x | y) [ exp1 ] = exp2
this assigns the exp2 to a value x[exp1] or y[exp1] in the current or specified set. Note, that the square brackets are for real. It is a vector element reference. The vector assignment is explained here . Example:
s1.y[0]=0 s1.y[length-1]=0
Expressions¶
exp can be anything of the following:
world . (xmin | xmax | ymin | ymax)
reference to the current world limits. (For hookcommands and other usefull stuff.)
mesh ( exp1 , exp2 , exp3 )
define a vector of length exp3 made of equidistant points between exp1 and exp2. Example:
s1 on N=100 s1 length N x=mesh(0.1,12.3,N) y=x^2
real
any real or integer number.
identifier
any previously defined identifier
parameter
any parameter defined on the command line. See parameter.
cursor . (x | y)
a reference to the mouse cursor position. (For hookcommands ) See Cursor reference.
[setdesc . ] length
the length of the set’s x/y-vectors. Example:
with s1 x[length-1]=100
[setdesc . ] (x | y)
[groupdesc . ] (x | y)
the group’s x/y-vectors
setdesc . (x | y) [ exp ]
the exp-th element of the x/y-vector of set. The square brackets are for real here. Example:
s1.x[10]
moment ( setdesc , exp1 , exp2 , exp3 )
the exp1-th moment of set.y in the x-interval [exp2,*exp3*]. These are normalized moment
, hence
. The second moment corrected for the center of gravity is defined as
. Example:
killall N=1000 a=0.5 x0=-0.6 x1=1.6 w=0.2 g1.gr1.s1 on s1 length N x=mesh(x0,x1,N) y=exp(-((x-a)/w)^2/2)*3 m1=moment(s1,1,x0,x1) m2=moment(s1,2,x0,x1) # calculate the normalized width wi=sqrt(m2-m1^2) echo "wi=",wi gr1 irregular tics on itic1 type x major itic1 position m1 itic1 length 1 itic1 label side opposite itic1 label "m1" itic2 type x major itic2 position m1+wi itic2 length 1 itic2 label side opposite itic2 label "wi" itic2 line style dash autoscale
( exp )
we can use parentheses around any expression. Example:
a*(b+c)
function ( exp )
These functions can be used on scalars or vectors
function meaning function meaning function meaning sqrt(x) sin(x) asin(x) abs(x) cos(x) acos(x) exp(x) tan(x) atan(x) log(x) cot(x) log10(x) theta(x) function ( exp , exp )
These functions can be used on scalars and vectors, and mixed arguments
function meaning min(x1,x2) max(x1,x2) sign(x1,x2) atan2(x1,x2) (min | max) ( vectorexp )
return a scalar containing the maximum or minimum of all values in the vectorexp, which must be a vector. Example:
m=min(g1.gr1.s1.y) # or with g1.gr1 m=max(min(s1.y),1.0e-5) # mixed scalar and vector expression: each element of s1.y will be the larger of # either the element or m. y=max(y,m)
exp1 ^ exp2
exp1 raised to the power of exp2.
exp1 (* | /) exp2
(+ exp | - exp)
exp (+ | -) exp
- format( string, exp )format( string, exp, exp )format( string, exp, exp, exp )format( string, exp, exp, exp, exp )
string must be a format string, as in C, where each “%” marker refers to one of the other arguments. There must be as many markers as exp arguments and the type must match.
Typical markers are %s for strings, %ld for integer, %g for real, %10.5f for fixed format real with width 10 and 5 digits after the decimal point. Example:
i=42 suffix="x1" print to format("file\%ld_\%s.png",i,suffix)
GUI¶
Plotting window¶
Use the right mouse key on an objects and double click (depends on where you do this). Have a look at the mouse button tips.
If the zoom buttons on the left are used, some of them change the cursor into a cross hair shape. This means that the corresponding function is switched on. To cancel the function use a right mouse click.
Hotkeys:
- zoom in
- Ctrl-+
- zoom out
- Ctrl- -
- autoscale all
- Ctrl-a
- autoscale x
- Ctrl-x
- autoscale y
- Ctrl-y
- scroll
- Ctrl-left, Ctrl-right, Ctrl-up, Ctrl-down
Hover with the mouse pointer over GUI elements to get tooltips.
To make a graph the current graph double click on empty space in the graph far enough away from sets and other objects. If several graphs overlap where you double click the current graph is changeing everytime you double click (loop through all graphs under the mouse cursor). You can also double click on empty space outside of any graph to loop through all the graphs. The current graph is displayed at the buttom of the window.
Scripting window¶
Have a look at the edit and insert menus for usefull functions.
- Searching:
- Start search via Ctrl-F, type the search term, use backspace for corrections. Hit Ctrl-F to find next hit. If end of script is reached (colored search bar) hit Ctrl-F again to go back to start searching at the beginning of script. Use any cursor movement to cancel search mode. If Ctrl-F is hit to initiate search, hit it again to bring back the previous search string (if it exists).
Logarithmic plots¶
In log scale invalid data points are converted into very small numbers before plotting. This way the data sets are never invalid but the world scale will look weird.
For ellipses in world coordinate units the radii for the y/x direction denote the upper/right radius in world scale when the ellipse were placed at 1,1. Example:
killall
g1 on
x axis scaling log
y axis scaling log
world x 0.1 , 100
world y 0.1 , 100
Ellipse1 on
Ellipse1 name ""
Ellipse1 line style solid
Ellipse1 line width 1
Ellipse1 line color 0x0
Ellipse1 fill on
Ellipse1 fill color 0xeeeeee
Ellipse1 coordinate system World
Ellipse1 center 1,1
Ellipse1 radii 9,9
Ellipse1 angle 0
with g1.gr1
s1 on
data xy
10 0.1
10 100
end data
s2 on
data xy
0.1 10
100 10
end data
textbox1 on
textbox1 coordinate system World
textbox1 "radius 9"
textbox1 position 11 , 1
textbox2 on
textbox2 coordinate system World
textbox2 "center at 1,1"
textbox2 position 11 , 9
Line1 on
Line1 coordinate system World
Line1 start 11.2658,5.96763
Line1 end 1.01985,0.796076
Data¶
The data are organized in groups and sets. Groups and sets have attributes. The group attributes can be set to hold for each set of the group irrespective of the individual set’s settings.
Files¶
xfbp saves files in its own format (which is a subset of the
scripting language). The extension is .xfp
. It
can also save and load the scripts, usually with the extension
.cmd
. It can load a set of data files.
If compiled with python support, it loads .xpy
(and .py
) files
from the command line and executes them. The .xpy
extension
denotes a python script, which is using pyxfbp bindings. These files cannot be executed in a normal python
shell, since they need xfbp to run properly.
Command line options¶
The program can be called with filenames as argument. If the file type
has to be specified explicitely a file type flag has to preceed the filename. Most common files are
automatically recognized via some heuristics. These are fplo band
and bandweight files and xfbp’s own files: .cmd
, .xfp
and
.xpy
(or .py
if you insist). If no file type is specified,
data files are loaded with an implicit -xny
flag (blocks of
columnar data). In general each file is read into its own group. Spin
polarized band structures create two groups if there are two spin
directions (not full relativistic):
-cwd make the directory of following file current directory in the application. (I do not know, what this was for.) -oi
- open in observe mode, to monitor calculation
- progress (especially usefull for an on-machine fplo run).
-a namevalue specify a parameter name – value pair, separated by a colon, e.g:
-a p1:"filename1"in generic command/script files, where the parameter
$p1
(orp1
in python) will be available in the script and contain"filename1"
. Also see python specifiaction Commmand line parameters.-die in connection with a script use this option to quit xfbp after script execution:
xfbp -die script.xpy
File type flags¶
A file on the command line can be preceeded by a file type flag to force a certain file type. For more details on the data strutures see data files.
-xny xny data -xynw xnyw data -xynz xynz gridded data -band band structure data -bandweight band weights data -akbl Bloch-Spectral-Density data -p a parameter file, containing scripting commands (only native).
Data file types¶
- xny
- Data sets are read, assuming that an empty line starts a new
data block. In each multi column block with N columns the first
column is
and the other
columns are
, resulting in
sets for each data block in the file. All sets end up in a new group.
- xynw
- The first column of each block is
. The second is
and the following columns are weights.
- xynz
- First comes a block of
-values, each line one value, followed by a blank line. Then comes a similar block of
-values followed by a blank line. Finally a block of
-values, one value per line. The resulting plot will be a density plot where the
-values define the color.
- band
- An FPLO band structure file.
- bandweight or bandweights
- An FPLO band weights file.
- akbl
- An FPLO Bloch-Spectral-Density file. (CPA FPLO5, pyfplo.Slabify)
Set Dialog¶
For xynz
functions a density plot is performed, which plots a
color code for each . If you double click on a density
plot in the viewport area this dialog opens.
The tab “DensityPlot” controls the appearance of the plot.
An
xynz
file can contain several components, e.g. the Bloch spectral function of the CPA modul (old) produced a gross (component 0) and net (component 1) spectral density in the same file.By default component 0 is plotted unless it is chosen differently (component-spinbox in the dialog, zcomponent or
pyxfbp.Set.zcomponent
). If the underlying data are coarse, use interploation depth in the dialog (interpolationdepth orpyxfbp.Set.interpolationdepth
) to smoothly add more data points (dont use overly large values!).Chose a colormodel ( colormap … or
pyxfbp.Set.colormap
).Look at the histogram, which shows the number of data points for each z-value and the z-interval which is mapped to the color map. By default the whole interval is mapped with a small modification. On loading the file (and through
pyxfbp.Set.adjustDensPlot
) an automatic detection of background data and upper data cut-off is attempted This can be changed and often needs to be changed.- if scalemax is decreased (from default 1 – no upper cut-off) more values at the higher end of z-values get painted with the maximum-value color. Basically all z values right of the right rim of the color bar have maximum-value color.
- if z0 (null cutoff or
pyxfbp.Set.z0
) is larger than the minimum z-value the lowest color value of the color model is interpolated into the data background color for z-values lower than z0. This can be used to plot values below a certain z-value with another color (to clean a data background). The default data-background color (min color orpyxfbp.Set.databackgroundcolor
) is magenta to alert the user that something might need adjustment. - if scalemin (min cutoff or
pyxfbp.Set.scalemin
) is smaller than 1 the interpolation reaches full data-background-color already for z-values larger thanmin(z)
but smaller than z0. This way the background cleaning color spreads more aggresively. - zpower (zpower or
pyxfbp.Set.zpower
) is used to map the z-values in a non-linear fashion onto the colormap.
Just try it. For completeness the scalar
which maps linearly to the colormap is defined as
and the
which interpolates between the lower end of the colormap and the data-background color is defined as
Color Model dialog¶
The color map editor has a “more” button from which one can choose pre-made color maps.
A map consists of a chain of nodes, each with a certain hue-saturation combination and a certain value (darkness). These nodes are interpolated to obtain all colors. The interpolation happens either on straight lines in the Hue-Sat space or in rgb space. The latter will happen if the interpol. rgb checkbox is on. The difference is most visible if two colors are chosen such that their connection line crosses the white center of the circle.
Right click somewhere and a node gets added.
- If there is no node yet, a single node appears.
- If there is one node a second appears and will be connected to the first node by a line.
- If there are more than two nodes ,the new node will be connected to the closest end node, or it will be inserted if the mouse click was close to a connection line. (Currently, a straight line between neighboring nodes is considered and not the curved lines which appear in rgb interpolation scheme. If you click on the visible line close to a node it should work in almost all cases)
Imediately after the right click the new node can be dragged around.
Right click on a node and it gets deleted.
Left click on a node the move it around.
Shift-left click a node to set a precise color.
Any of the 4 color widgets can be clicked on.
If you prefer to wrap your own color model start with a two color map. Choose more->clear to remove all prior nodes. Right click into the round Hue-Sat widget and drag the new node to your color of choice. Right click somewhere else in the same widget and drag to the desired color. This is a colormap.
Now, optionally, switch on/off the interpol. rgb checkbox. This will interpolate between the two end nodes either in RGB or Hue-Saturation colorspace. These two-end-color maps are usually rather usefull, especially with RGB interpolation.
You can invert the node sequence (more->invert)
The more->set-equal-distance function will make the gradient nodes equidistant.