MercuryDPM  Trunk
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Visualising data in xballs

xballs visualizes data files in a 2D representation, and draws them in an X11 window.

Each MercuryDPM simulation that outputs data files also outputs a small script to view the data in xballs; e.g. to view, execute ./Tutorial1.xballs

Screen output:

xballs creates a window with four smaller child-windows. Counting from top left to the right and then to the bottom: Window 1 contains particles at their position.

Windows 2 and 3 contains averages in slices where different colors mean:

  • Red: density in horizontal or vertical slices at right and bottom window respectively.
  • Grey: density in horizontal slices at right window (only the inner third of the system is averaged).
  • Blue: Kinetic energy
  • Green: Rotational energy

Window 4 contains information about number of particles and time

the coloured bar at the left of window 2 gives the color-scale in the order of increasing value.


This script calls xballs with the name of the data file, plus a few options for viewing:

xballs -format 14 -f -s 1.2 -cmode 0 -cmax -sort -solidf -v0 $*

Note, you can change the options to achieve different views of the simulation. Below we explain these options in detail:


Data files are differently formatted, depending if you use Mercury2D or Mercury3D. Therefore, you must tell xballs which format you want to read by adding

The data file must have one of the following formats (the format must be defined by the -format ## option):

  • For Mercury2D, use format 8 (i.e. the data file contains 8 columns): x z vx vz r ry wy species
  • For Mercury3D, use format 14 (i.e. the data file contains 14 columns): x y z vx vy vz r rx ry rz wx wy wz species

Other options

-f 'datafile'   define the filename
                'datafile'='-' allows stdin-input
-wf 'wallfile'  wall configuration data file
                (up to now xballs will plot just infinitely long lines)
                One dataset consists of seven numbers
                       1 ... wall-type (for future use)
                   2,3,4 ... normal vector to the wall
                   5,6,7 ... point the wall goes through
                You can ignore the numbers 1,3, and 6, but must give them !
                You need to wpecify -nw # (see below)
-nw #           number of walls to be read and plotted from wallfile

-of "filename.format"   creates one file per frame to the file ######.filename.format
                        ###### is the frame-number, starting with 000001 and ending
                        with 999999. -of uses the command "import" and is successful
                        only on machines which have this command. -of draws only the
                        picture window, not the data windows.
                        filename is arbitrary, format defines the output format, as
                        for example: ps, eps, giff, sgi, ...
-xof "filename.format"  see -of, but the whole window is drawn ...


-w #  width of top-left subwindow (600 pixels)
-h #  height of top-left subwindow (600 pixels)

-s #  scale (100)
-ss # scale (10000)
-o #  vertical offset (0 pixels)
      (with nonzero offset xballs draws only sidewalls)
-oh # horizontal offset (0 pixels)

-mo #  negative vertical offset (0 pixels)
       (with nonzero offset xballs draws only sidewalls)
-moh # negative horizontal offset (0 pixels)

-noborder # 0 (default) draws horizontal and vertical border
            1 draws vertical borders only
            2 draws horizontal borders only
            3 draws no borders at all
            4 does not even draw the grey area outside the system

-xcells #  draw #-1 vertical lines within the boundaries
-zcells #  draw #-1 horizontal lines within the boundaries


-tmin #  plot for time > #     (0 time in microseconds (1e-6 s))
-tmax #  plot for time < #     (infinity)

-p #     delay between pictures (1 arbitrary units)


-c  #  scale the colormap (10)
-c1 #  scale the colormap (1e-6)

(2D data - format 8)
-cmode # 0: (default) kinetic energy
            colorscale is sqrt(vx^2+vy^2)
         1: colorscale is x (column1)
         2: colorscale is y (column2)
         3: colorscale is vx (column3)
         4: colorscale is vy (column4)
         5: colorscale is rad (column5)
         6: colorscale is phi (column6)
         7: colorscale is ome (column7)
         8: colorscale is ix (column8)
         9: colorscale is x+y (column1+column2)
        10: colorscale is sqrt(vx^2+vy^2) (kinetic energy)
        11: colorscale is ome*rad (surface velocity)
        12: colorscale is sqrt(x*x+y*y) (radial distance)
        17: colorscale is (rad*ome)**2 rotational energy
        20: colorscale is particle number i=1,...,N

(3D data - format 7 )
-cmode # 0: (default) kinetic energy
            colorscale is sqrt(vx^2+vy^2+vz^2)
         1: colorscale is x (column1)
         2: colorscale is y (column2)
         3: colorscale is z (column3)
         4: colorscale is vx (column4)
         5: colorscale is vy (column5)
         6: colorscale is vz (column6)
         7: colorscale is rad (column7)
         8: colorscale is ix (column8)
         9: colorscale is x+y+z (column1+column2+column3)
        10: colorscale is sqrt(vx^2+vy^2+vz^2) (kinetic energy)
        12: colorscale is sqrt(x*x+y*y+z*z) (radial distance)
        13: colorscale is z/sqrt(x*x+y*y) (tan theta)
        14: colorscale is y/x (tan phi)
        15: colorscale is tangential velocity rel. to z rotation
        20: colorscale is particle number i=1,...,N
        21: colorscale is abs(x) (column1>0)
        22: colorscale is abs(y) (column2>0)
        23: colorscale is abs(z) (column3>0)
       110: colorscale is <qp_\alpha^2>
       111: colorscale is  qp_x (column11)
       112: colorscale is  qp_y (column12)
       113: colorscale is  qp_z (column13)
       114: colorscale is ix (column14)
       120: colorscale is <ome_\alpha^2>
       121: colorscale is ome_x (column8 )
       122: colorscale is ome_y (column9 )
       123: colorscale is ome_z (column10)

-nct      for cmode 8 divided by time-step

-crange #1 #2   select particles from #1 to #2 for aver. and
                colorcoding - together with -cmode only
-cpower #  modify the -cmode color by the power #/100

-cmax  set the largest value occuring to the maximum color
       attention: the meaning of colors changes from frame
       to frame with this option.
-cmaxset # set the max-value directly
-cmean set the largest value occuring to 4xmean value color
       attention: the meaning of colors changes from frame
       to frame with this option.
-coffset # set the min value offset (#=1000000 => offset=1)

-ch #  change color after every #th particle
-m     keep the center of mass in the center of the screen
-cm    velocity relative to the center of mass
       red: upwards - blue: downwards.
-phcm  indicates center of mass (vertical) by a line
-col0  sets the particles with zero velocity to blue
       default: is black for zero velocity

-scala # gives the values corresponding to the colors
         1 direct
         2 multiplicative factor given
         3 direct +statistics
         4 multiplicative factor given +statistics

       The colormap consists of three gauss lightsources
       -rgbr, -rgbg, and -rgbb control the position of the
       lightsource in the colormap and -rgbs controls the
       width of the gaussian spreading in the colormap.
-rgbr  position of Red in the colormap   (57)
-rgbg  position of Green in the colormap (32)
-rgbb  position of Blue in the colormap  (6)
-rgbs  width of the three colors         (51)

       the extensions -rgbb 60 -rgbg 60 -rgbr 60 -rgbs 70
       set a black and white colorscale.


-rred #   divide the real radius by #
-rmult #  multiply the real radius by #

-lines #  draw line from center to center if the separation
          of two particles is less than #/1000 of the diameter.

-vector   show the displacement vector from one time to the next
          to be combined with -step. Note also that -vscale can
          be used to change the length of the vectors - default is
          a length of 1/100, -vscale 100 sets it to 1, -vscale 1000 to 10.

-squares # plot squares instead of circles # = 1|2 uses column 6|7
           for colorcode

-step #   skip # frames

-draw #   skip #-1 particles
-drwmin #   skip particles with cvalue <drwmax#
-drwmax #   skip particles with cvalue >drwmax#


-v #        trace particle with number #  (5 pixel dot)
-mv #       trace particle with number #  (15 pixel dot)
-ncoll #    mark all particles with: info > (i_max - #)
            info is the value in column 8
            i_max is the maximum of those values


-die        ends the program after error or last image
            (default: the last image is kept on the screen)

-fast       draw only lines ...
-solid      draw circle around the disks (fills the gaps)
-solidf     draw circle around the disks (foreground color - black/white)
-solidb     draw circle around the disks (background color - white/black)

-px         use only 20 colors and no text

-a          add the density-data to get an average in time
            add the velocity-data to get an average in time
            add the ang.velo.-data to get an average in time

-x          write the vertical density-profile on screen


default: particle color marks kinetic energy
         quarter-circle color marks rotational energy (if larger 0)

-nct      color-code on divided by time-step
-ferro    show spin (blue = clockwise, red = counterclockwise)

-invert   invert foreground and background colors

Velocity vectors

-vvec       draws only the vetors of velocity
-v0         draws NOT the vectors of velocity
-w0         draws NOT the angles and angular velocities
-nodel      doesnot delete the buffer between frames

-vscale #   scale the vectors (length = radius is the default)
            try for example # = 10

-vq #       velocity scale in combination with -squares

Display options

-ltime #    put the time in the data window (#,#) pixels from the
            top left corner with a LARGE font
-stime #    put the time in the data window (#,#) pixels from the
            top left corner with a SMALL font

3D options

-sort       sort the particles with respect to their depth in the screen
            -> this creates a 3D image - front particles override rear particles

-3dturn #   view 3D files from different sides
            View directions are given for the positive x,y,z-axis
            where RH and LH indicates right- or left-handed coordinates
            (use options: -f testview.xb7 -format 7 -s 2 -solidf
                          -moh 200 -o 200 -sort -cmax -cmode 7
                          -redraw 1000 -drottheta 0.0001 -drotphi 0.0002
                          -3dturn 1   [ ... or 2,3,4,5,6]
             and the file testview.xb7 to check)

-translate # # #  move the whole system to (x,y,z)
-rotr #      zoom factor (#<1.0<#)
-rotphi #    phi rotation angle (0.0<#<2PI)
-rottheta #  theta rotation angle (0.0<#<PI))
-drotr #     increment zoom factor (#<1.0<#)
-drotphi #   increment phi rotation angle (0.0<#<2PI)
-drottheta # increment theta rotation angle (0.0<#<PI))

-unidist #  size enlargement (not yet functional)
-dunidist #  size enlargement (not yet functional)

-redraw #   redraws the same picture # times

-cube       draw a cube around the simulation volume (lines, not hidden)

-fog #      draw front particles in normal colors
            draw rear particles (farther away) somewhat more grey
            the input parameter shifts the greyscale
            meaning: is proportional to the fog-intensity
-fpower #   makes the fog more|less intensive close to the viewer