# 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
    - Regular tic commands:
    - Irregular tic 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
  - Plotting window
  - Scripting window
- Logarithmic plots
- Data
- Files
- Command line options
  - File type flags
- 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 | Group commands | Kill commands
> Print commands | Set commands | Copy/Move commands
> Paper commands | Set attribute commands | Hook commands
> Graph/Group/Set/Weight descriptors | Weight commands | Cursor reference
> With command | Weight settings | Assignments/Definitions
> World commands | Weightlabel definitions | Expressions
> View commands | Line style commands |
> Legend box commands | Fill style commands |
> Graph commands | Font style commands |
> Shape commands | Symbol style commands |
> Text box commands |  |
> Tic mark commands |  |
> Irregular tic commands |  |

### Comments

- # blah blah

  Full line comment. There are no inline comments!

top

### 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

top

### 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` or `png` 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` or `png` format to file. (The filename must have been defined before.)

top

### 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)

top

### 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.

- g int

  graph int: g4 is graph 4.

- gr int

  group int in the current graph (if valid)

- s int

  set int in the current graph and current group

- g int1 . gr int2

  group int2 in graph int1

- [[g int1 . ]gr int2 . ]s int3

  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 in `g1.gr1` by one. The full command would be `g1.gr1.x=g1.gr1.x+1`, but this is not necessary. And `g1.gr1.s2.y=y*2`, will multiply all y values of set `g1.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) . ]w int

  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) . ]w string

  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.

top

### 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

top

### 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.

top

### 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 g int, 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.

top

### 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 g int 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.

top

### 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

top

### 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 and `x,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, use `fill 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.

top

### 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.

top

### 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

top

#### 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

top

### 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.

top

### 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 datatype
  datalines
  end 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!

top

### 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 exp
  real : 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.

top

### 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).

top

### 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

top

### Weightlabel definitions

This is special stuff to define tables of weightlabels especially in saved files.

- weightlabel definition[s]
  weightlabels[ ]int1
  stringlist
  end weightlabel[s]
  …
  weightlabels[ ]intn
  stringlist
  end 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.

top

### 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

top

### 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

top

### 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

top

### 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

top

### 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

top

### 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

top

### 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.

top

### 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!

top

### 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

top

### 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)

  the set’s x/y-vector. Example.

- [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)

top

## 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` (or `p1` 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.

The densityplot tab of the set dialog.

- 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 or `pyxfbp.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 or `pyxfbp.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 than `min(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.

The colormap editor.

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.