Mozi documentation

This documentation describes mozi-0.9alpha1.




Table of contents

  1. Description
  2. Command line arguments
  3. Input formats
  4. Menu
  5. Control
  6. Constraint
  7. Movie creation
  8. rc file
  9. Download
  10. Compilation and Installation
  11. Changes



1. Description

mozi is small GL based program intended to visualize simulations of granular material. It has been optimized to view sequences of images of different particles and their physical properties which are stored in a specially crafted file. It can represent velocities, forces, etc. by arrows or color code and has the ability to show only a subset of the particles described by totally free constraints. Finally it may create an mpeg movie in the background.

Important remark: This code was written by a physicist who is not in any mean a good programmer. I spent 10 years in writing small, few hundred line codes for simulations that are entirely free from any on run checking. Programs were to be efficient and not user friendly. As I was the only user of them they were not user safe at all and of course they contained no documentation. So bad input and miscellaneous usage is very badly checked and may result in an unwanted behavior. This is also true for this program however I made my best to make it more robust. Meanwhile use it really at your own risk! I write this documentation because people started using this program and found it useful. Please, send remarks and suggestions to me.

mozi is the Hungarian word for movie.




2. Command line arguments

usage: mozi [-h] [-b max bodies] [-w] [moviefile]
-h
--help
Prints usage
-b #
number of max bodies
for obscure reasons dynamical memory allocation for bodies does not work. Either compile it with larger body_alloc (line 4 of main() in mozi.c) or give it vie this option. Too large values result in a very large memory consumption.
-t
group objects by texture and type. If set all objects are read and then checked in sequential order if there is any difference in texture or in type if there is not they will be treated under one constraint group. (This is the default behaviour prior to version 0.9alpha.). The grouping in the input file has no influence in this case. If option is not set stationary objects are considered as seperate group each and input file grouping is followed
-w
write rc file (~/.mozirc) after exit.



3. Input formats

mozi comes with a file fileformat.txt which contains the up to date information of file format. Being input for mozi is not the sole purpose of datafiles described here they must be also eligible for easy access of properties of particles. getcol4.c is the program the extracts these information. Any suggestion for new fileformat should come in this spirit.

This manual describes in detail different supported fileformats. You may skip to the currently supported one.

A line in the input file is considered as one snapshot except for the header. In text file it is indeed one line. In binary format it is terminated by the BT_EOL object.


General

Some fileformats are text, others are binary. Currently no architecture independent binary (XDR) is supported for binary format. A stupid check is performed although this must be changed later on. All data files start with a small text header that is described bellow.

Most fileformat start with the line

#type X

where X is a number that specifies the version of the input file. In binary formats the above line is extended as follows:

#type X I D L

where X is the same as before, I: sizeof(int), D sizeof(double), L linelength if that is fixed and known. if L==-1 than at start mozi sweeps through the whole file and determines each line length. It is very important if fixed linelength is used moziassumes that each line contains the same set of objects with the same parameters. If linelength varies the first line must contain all objects even if in the first timestep their number is zero. In this case insert it with number zero. Later unused object may be left out but in certain conditions it may lead to unwanted behavior. If the objects are different this does not happen.

Note, that speed can be increased by using binary formats and especially fixed linelength.

All header lines start with #. In text formats data starts after the last header option. In binary file a line with a single hash marks the end of the header and what comes after the new line character is considered as data.


Body Types

This parameter is an integer. Each object has a certain number of compulsory parameter. Generally it is its size. In currently supported fileformat (Type 4) these parameters appear at the beginning of each object. The symbols (e.g. rx) are used in constraints.

BT_EOL          0   (00000)
End of line in binary mode. This should be a last object in a snapshot.
BT_Wall         1   (00001)   dx(double), dy(double)
Rectangle, original orientation is in the xy plane.
BT_Ball         2   (00010)   dx(double)
Sphere, dx is diameter.
BT_Cylinder     3   (00011)   dx(double), dz(double)
Cylinder, dx is diameter, dz height. Position is the center of the lower end of the cylinder.
BT_Disk         4   (00004)   dx(double)
Disk, dx is diameter. orientation as BT_Wall
BT_BallCC       5   (00101)   dx(double), dy(int) 
Sphere, dx is diameter. This is a depreciated object, do not use it. It has two parameters the diameter which is double and the coordination number which is int. In type 4 this parameter is converted to double and stored in dy. In other types it is disregarded.
BT_Force        6   (00110)   dx(double), dz(double), i1(int), i2(int)
Cylinder, dx is diameter, dz height. This object is to display inter-particle forces. The width is thus proportional to the strength of the normal force, height is the distance between the two particle. Its position is same as one of the particles and reaches to the center of the other. i1, i2 are the sequential number of the particles generally Balls.
BT_STBall       7   (00111)   dx(double)
Sphere, dx is diameter. Used for modeling rubber membrane. Can be used for a different sphere type.
BT_DTEdge       8   (01000)   dx(double), dz(double), i1(int), i2(int)
Cylinder, similar to BT_Force. It is used to represent the triangulation mesh.
BT_DGBall       9   (01001)   dx(double)
Sphere, dx is diameter. Used for the measure of the local deformation.

Parameter

Each object may have different parameters. Only position and orientation is used during default plot. Others can be accessed in constraints. Both orientation and position can be omitted. Default orientation is along the y axes, default position is origin.

Pos
32, [3 double] x, y, z
position Euclidean coordinates. At no rotation x points to the right, z out from the screen, y up.
Orient
64, [4 double] rx, ry, rz, phi
orientation, default is in the y direction. Orientation is given by a vector (first three components) and an angle (fourth component) of rotation around the vector.
Coord
128, [1 int] Z
coordination number, the number of contact the object has.
Velo
256, [3 double] vx, vy, vz
velocity
Force
512, [3 double] fx, fy, fz
force
AngVelo
1024, [3 double] omx, omy, omz
angular velocity
Torque
2048, [3 double] tx, ty, tz
torque
TrVelo
4096, [3 double] tvx, tvy, tvz
averaged velocity
TrForce
8192, [3 double] tfx, tfy, tfz
averaged force
TrAngVelo
16384, [3 double] tox, toy, toz
averaged angular velocity

Texture

Currently 4 different textures are supported by mozi. Texture field is a byte that is split into two parts. The lower 4 bits (0-15) determine the texture number or the color scheme (the latter is still in the to do list, sorry.). If bit 5 is set than no texture is used the object is colored. If bit 6 is set the object is transparent.

This field can be totally reset in mozi.


Stationary objects

mozi allows for setting up stationary objects in the header that does not move and always there through the whole run. This may save space in certain conditions. In the beginning this was important but now I think this should become depreciated.

After the type element any number of the following object may follow:

#object type(byte) tex(byte) num(int) {Pos Orient}*num


Type 0

Text format

This fileformat is depreciated but so simple that it will be kept.

This format plots only balls except for #object.

Line format:

time(int) num(int) {Pos Orient}^num


Type 1

Text format

This fileformat is depreciated.

Line format:

time(int) type(int) tex(int) num(int) {Pos Rot dx [dy] [dz]}^num type(int) ....

This format knows only BT_Ball, BT_Wall, BT_Cylinder, BT_BallCC. There is no BT_EOL as it reads until text file end of line.

Note: the size of the object is at the end of the data record while in currently supported formats is at the beginning.


Type 2

Binary format of type 1

Not supported any more. Some code is still there but conflicts with type 4. Should be removed.


Type 3

Text format of type 4

Never was supported.


Type 4

Binary format

The currently supported format. Use this!

This is described more in detail as this is what you supposed to use:

Header

#type 4 I D L
#object ...
#

where I: sizeof(int), D sizeof(double), L linelength if that is fixed and known. if L==-1 than at start mozi sweeps through the whole file and determines each line length. In most cases you have

#type 4 4 8 -1

The data starts after the line with only a single '#' and a new line.

Each line is a snapshot and displayed at once. A line is constructed as follows:

time(double) {object} {object} ... BT_EOL

Time is a double variable, that will be accessible in constraints. Then come different objects as described bellow and at the end BT_EOL which is just a 0(int).

An object is a given number of particles with the same geometric shape but with different parameters. It is constructed as follows:

type(int) tex(byte) num(int) {parameters}^num

The lower 5 bit of the type was defined above. The upper bits show which parameters are present as described above. tex is the texture as described above. num is the number of bodies. The parameter set is expected to be repeated num times.

Example

Here a simple example is described. We have one stationary object, a cylinder, In the first snapshot a wall with only position and orientation, in the second timestep a ball appears.

Stationary object:
Cylinder diameter: 0.003, height: 0.009, position: origin orientation default. Transparent and no texture.
t=0
Square: width: 0.006, height: 0.006, position: origin, orientation default. Not transparent, texture: 0.
t=1
Square: width: 0.006, height: 0.006, position: origin, orientation default. No other value. Not transparent, texture: 0.
Ball: diameter: 0.002, position: (0.0005, 0.001, 0.0), velocity, (0.0, 0.0007, 0.0005), Not transparent, texture: 1
t=2
Square: width: 0.006, height: 0.006, position: origin, orientation default. No other value. Not transparent, texture: 0.
Ball: diameter: 0.002, position: (0.0005, 0.001, 0.001), velocity, (0.0005, 0.0007, 0.0005), Not transparent, texture: 1

On 32 bit IBM, intell or AMD processor the input file contains the following:

First three lines are text:

#type 4 4 8 -1
#object 3 99 1 0.0 0.0 0.0 0.0 0.0 1.0 0.0 0.003 0.009
#

Binary part: Format typecharacter and value. Type: i=int, d=double, c=char/byte. eg double 0.003 => d0.003.

First `line', note that Ball is represented here with 0 number to inform mozi about its presence, 354=2+32+64+256=BT_Ball+Pos+Orient+Velo.

time type(Wall) tex(yes:0) num(1) size_x size_y
 d0     i1         c0        i1   d0.006 d0.006
     type(Ball) tex(yes:1) num(0)
       i354        c1        i0
     type(EOL)
        i0

Second and third line line (no eol! just continue)

time type(Wall) tex(yes:0) num(1)   dx     dy
 d1     i1         c0        i1   d0.006 d0.006
     type(Ball) tex(yes:1) num(1)   dx       x       y     z      rx   ry   rz   phi   vx        vy      vz
       i354        c1        i1   d0.002  d0.0005 d0.001  d0.0   d1.0 d0.0 d0.0 d0.78 d0.0    d0.0007 d0.0005
     type(EOL)
        i0
time type(Wall) tex(yes:0) num(1)   dx     dy
 d2     i1         c0        i1   d0.006 d0.006
     type(Ball) tex(yes:1) num(1)   dx       x       y     z      rx   ry   rz   phi   vx        vy      vz
       i354        c1        i1   d0.002  d0.0005 d0.001  d0.001 d1.0 d0.0 d0.0 d0.78 d0.0005 d0.0007 d0.0005
     type(EOL)
        i0

The resulting file can be downloaded from here.


XYZ

mozi currently supports XYZ files. This support is experimental and its future lies upon the development of the constraints. In this state it is not very useful compared to other viewers developed for the chemist community. The only relevance of this is the movie creation which is a weak point of freely available chemical softwares. Please, let me know whether this support might be useful if bonds and other properties can be calculated via constraints or free chemical viewers do a much better job. In this case the different snapshots are separate XYZ data connected to one file.




4. Menu

The menu system of mozi is not very developed.




5. Control

GL window

The GL window is used to move and rotate the object.

Mouse control
  1. Normal mode
  2. Left button+up/down => Orientation X
    Left button+left/right => Orientation Z
    Middle button+up/down => Position Y
    Middle button+left/right => Position X
    Right button+up/down => Position Z
    Right button+left/right => Orientation Y
  3. Light (Light frame connected to mouse)
  4. Left button+up/down => Z coordinate
    Left button+left/right => X coordinate
    Middle button+up/down/left/right => Y coordinate
    Right button+up/down/left/right => Alpha value
  5. Cut constraint, This is active when current constraint is a Cut and 'd' is pressed. Press 'd' again to go back to normal mode
  6. Any button+up/down => Cut position. Note, that any expression will be deleted and replaced by a single value.
Key control

Keys are case sensitive. For orientation and position control see also Set/Key step menu option.

Control window

Control window is divided into frames according to function. Except for animation frame all of them can be switched off by pressing the 'Off' button. In order to show them again use View menu.




6. Constraint

You can add and remove constraints in this subframe. Only objects which fulfill all restrictive constraints are shown. There are constraints that modify color or appearance.

NOTE: constraint is the most developing part of mozi and thus subject of massive change in the near future. The basics remain the same, but the appearance and the ordering will be altered.

For simplicity I use the following notification for the menus and text boxes in the order from left to right from top to bottom:

With the Number menu you can select an already existing constraint or a new one. The new constraint comes into effect only if 'Add' button is pressed. 'Del' button erases an existing constraint.

In the upper row you can set simple constraints easily. As soon as some text is inserted in the lower line the lower constraint selector is active

The numerical expression you enter in the Formula editor is evaluated. Variables as eg. 'x', 'tvz', etc. are substituted by the current value of every single particle of the given type. The result is always a single number.

Known functions

Note that in these expression trigonometric function use radian. An option will be added soon.

Constraint types are the following




7. Movie creation

The movie creation is done with Mesa off screen rendering and mpeg_encode. Unfortunately, this does not work with nvidia accelerated driver. We could not find other solution than to have two versions of mozi. One is compiled with the accelerated GL library with -D _NoMesa option. This version does not allow movie creation but still you can make snapshots the other version is compiled with the non-accelerated libraries. It is a little slower but can make mpeg movies. See also Compilation section.

After pressing 'Create movie' button a new window appears. Very few parameters can be set here so set everything before coming here. In the created mpeg file every active constraint remains in effect.

Here is the detailed description of the parameters

Under Linux a fork is done so an other process is generated for the movie creation. You may continue with playing around in mozi. This is useful if you want to make movies with the same setup form the same view with different settings. Just close the windows when you finished and wait for the result.

Note: At the beginning there was an other program called dat2mpg for the movie creation. Which was very convenient if one wants to create mpegs on computers without display. That time movie created a configuration file that was given as an input to dat2mpg. With the appearance of constraints the information that one must send became so enormous that I gave up developing two codes similarly. Maybe it would be nice to free the file reading and the GL plotting from all gtk and put in a separate file that could be included in both codes. For the time being I am happy with the one program concept.




8. rc file

That is a part that should improve a lot. The ideal state would be to be able to save the current configuration entirely and go back to the same state after new startup also with a different datafile. I am working on it. Please, be patient. Once it is done I will experience with a mozi free from gtk to be able to use in command line.

rc file is written if the menupoint is selected. Or the -w command line switch is selected.

List of parameters written into .mozirc




9. Download

Mozi


10. Compilation and Installation

Mozi works on Linux and windows. However for the latter you need really a hard work to do. A detailed description should come soon.

Needed libraries

Just type make and hope the best

11. Changes

From first online version 0.9alpha1

----- 0.9alpha1
	- big snapshot added.
	- File->Save/Save As menus renamed to Save snapshot
	- File->Create snapshot Mesa based snapshot, works only in
	  mozi and not in nmmozi.
	- size of Animation slider is fixed. Due to the complicated
	  box it did not allow for a decrease in size after increase.
	  On Suse this led to a continuous increas of window size.
	- command line option -t added. With -t mozi works as before,
	  objects are grouped by texture and type, without this option
	  objects are seperated as in input file.
	- File->Grey added. Shows the current snapshot in greyscale.
	  Az most of the printout is done by grayscale printers it is
	  useful option.  After redraw, rotation the image is back to
	  color again.

Created by János Török
Last modified: 30. January 2004.
This page was created by vim.