Mozi documentation

This documentation describes mozi-1.0.3.

Knowing my programming skills I do not think I will publish anything even at beta level.




Table of contents

  1. Description
  2. Command line arguments
  3. Input formats
    1. General
    2. Body Types
    3. Parameter
    4. Texture
    5. Stationary objects
    6. Current file format (Type 4)
    7. Future file format (Type 6)
    8. XYZ file format
  4. Menu
    1. File
    2. View
    3. Control
    4. Set
    5. Constraint
    6. Help
  5. Control
    1. Mouse control
    2. Key control
  6. Control window
    1. Frame frequency frame
    2. Animation frame
    3. Create moive frame
    4. Object position frame
    5. Object orientation frame
    6. Background color frame
    7. Light frame
    8. Constraints frame
  7. Constraint
    1. Editing
    2. Commands
    3. Expressions
  8. Movie creation
  9. rc file
  10. Download
  11. Compilation and Installation



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.

For copyright see the GNU licence.

mozi is the Hungarian word for movie.




2. Command line arguments

usage: mozi [-h] [-B] [-c contraint] [-d] [-f ttf font] [-b max bodies]
            [-r] [-s] [-t] [-w] [-g clength] [moviefile]
-h
--help
Prints usage
-b #
number of max bodies
for obscure reasons dynamical memory allocation for bodies did not work (surely my fault!). 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.
-d
Do not double bodies, save memory. Otherwise, you have the option to tell mozi not to redo constraint calculation and look around fast.
-f
ttf font file. Unfortunately, mozi can handle only on font file to print text on screen. You can sepcify it here or in rc file.
-s
Initially do not show objects. Switches off check buttons in constraints frame.
-r
Do not read rc file. Fall on hardcoded config.
-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.
-B
Switch out boldface commands in the constraint field, which sometimes messes up copy-paste.
-c filename
Read constraint from filename. Please note that still you have to update constraits in order to have the effect.
-g length
Calculate coarse graining velocities with length



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

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 and Type 6) 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 below 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.
type4demo.png
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
type4demo1.png
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
type4demo2.png

On 32 bit, 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.


Type 6

Essentially the same as Type 4 but also color of a body can be specified. It is untested yet but soon will become the official format.

The only difference is that texture (tex) is an integer that stores the following information:


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 the following:

*Never destroy popup windows. In most cases it makes mozi crash. Use cancel or hide window button to get rid of unwanted windows.




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. Change numerical value, This is active when the cursor is over a number in the constraint text window and you press 'd' in the GL window or Alt-D in the control window. Press it again to go back to normal mode.
  6. Any button+up/down => Change value. The amount of change is shown in a text field above the constraint text. Change it by hand or as below:
    - '0' Set factor to 1
    - '1' Set factor to 1
    - '2' multiply factor by 1/10
    - '3' multiply factor by 1/2
    - '4' multiply factor by 1/1.3
    - '5' multiply factor by 1/1.1
    - '6' multiply factor by 1.1
    - '7' multiply factor by 1.3
    - '8' multiply factor by 2
    - '9' multiply factor by 10
    - '  ' set value back to original (value when 'd' was pressed)
    - '=' set value back to original (value when 'd' was pressed)
Key control

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




6. Control window

controldemo.png

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.




7. Constraint

In this section the text processing algorithm is described. You may well guessed that the change from clicking to text editing was done by a linux user but it has many advanteges. First of all it can be saved and reloaded. Easy to change, suspend and much more flexible. The price you pay is at the beginning it sounds too complicated and one needs some practice. I try to present some examples at the end of this section that may help.

This chapter is organized as follows:

Commands sectin requires some knowledge about the expressions. Follow links if unclear.

Editing

The text box for contraints has only the very basic GTK editing features. Line breaking does not play a role and as will be described later it is easy to add comments to the commads. Organize it as you like.

There is an undo/redo system in mozi but that only works among stages that were successfully updated.

Copy and paste works from other windows but inside the same box does not. During editing a lot of on the fly staff is performed that prevents copy-paste into itself. Be carefull because it can destroy your text. Copy to an other place and paste back. Or cut and then paste multiple times.

Save anything that seems useful and reuse it.

Commands

There are 12 keywords or commands that mozi understands. They are listed above the text field. When entered they appear in bold face fonts. They have a number of parameters which must be written between a pair of brackets '[' ']'. The parameters are seperated by semicolons ';'. Generally, parameters are optional. The different commands should be listed one after an other. In some cases (described below order does metter). Any text outside the pair of brackets are ignored and can be used as comments except for the star '*' following the closing bracket which means to switch out the preceeding command.

Example:

Cut[0;0.001] Size[dx/2;1;3]* Kukucs Show[dx>0.01;3]

The second 'Size' command is switched off. 'Kukucs' is text outside brackets considered as a remark and ignored.

While you enter the text a small help about the current parameter is shown above the text fild on the right hand side of the window. When you press update and there is an error that will be printed at the same place but with underlined text. Be careful! After the description in paratheses the nature of the parameter is indicated, (v) is vector, (s) is scalar. It is general for constraints that there is no error message for mixing up vectors and scalars. You mast be keep track of them the general scheme is that if scalar was supplied instead of vector this scalar will be the x component, the rest will be zero. On the other hand if scalar is expected and vector is supplied then the length of the vector is taken.

Some commands behave similarly they are described together: Simple commands (Arrow, Color, Cut, Dir, Position, Show, Size, Texture), The rest is detailed one by one: Transparency, Print. Var, New)

Simple commands

They all perform actions on the properties of an individual body. Order does matter. Changing a property in a command effects its usage in a command placed after it. If a parameter is not supplied zero or nulvector is taken as default.

All of these have the same last two parameters: expr;type] that is described below

expr: An arbitrary expression. The result is taken to be a scalar if that is larger than zero the constraint is performed. If missing, default is 1.

type: An arbitrary expression. The result is taken to be a scalar and truncated to an integer if this is equal to the group type (the number behind the check box label) then the command is interpreted to only this group. If missing all groups are considered.

Example:

Arrow[...;;] All bodies are plotted with arrows.

Arrow[...;;1] All bodies of group 1 are plotted with arrows.

Arrow[...;dx>1;1] All bodies of group 1 which have a diameter larger than 1 are plotted with arrows.

Arrow[...;dx>1;] All bodies which has a diameter larger than 1 are plotted with arrows.

Show[dx>1;1] Show only bodies in group 1 which have a diameter larger than 1 (other groups are not effected).

Description:

Arrow
Plots and arrow instead of the particle. Used to plot velocity of the particles. If you want to keep the particle and add an arrow to it use the New command.
Parameters:
  1. Direction of the arrow (vector)
  2. Length of the arrow (scalar)
  3. Width of the arrow (scalar)
  4. Expr
  5. Type
Color
Change the color
Parameters:
  1. If it is a vector then the RGB values are set according to the xyz values of the vector. If it is a scalar then it is the Red value.
  2. Green value (scalar) or ignored if the first parameter was a vector
  3. Blue value (scalar) or ignored if the first parameter was a vector
  4. Alpha value (scalar), important only for transparency
  5. Expr
  6. Type
Cut
Cut out a slice perpendicular to the point of view. I found it useful to look at three dimensional samples by cuts.
Parameters:
  1. Distance from the origin (scalar). Positive cuts farther from the viewer.
  2. Width of the cut (scalar)
  3. Expr
  4. Type
Dir
Direction of the body. By no rotation unrotated object look vertical (i_z).
Parameters:
  1. Direction (vector)
  2. Expr
  3. Type
Position
Position of the body.
Parameters:
  1. Position (vector)
  2. Expr
  3. Type
Show
If expression is true body is shown.
Parameters:
  1. Expr
  2. Type
Size
Size of the body.
Parameters:
  1. Dimensions (vector), objects have the following dimensions:
  2. Expr
  3. Type
Texture
Texture of the body.
Parameters:
  1. Texture (scalar). Value truncated to integer. Zero means no texture, currently only four (1-4) textures are available.
  2. Expr
  3. Type

Transparency

GL handels very nice objects hiding eachother but transparent objects must be drawn after non-transparent ones. That also implies that transparent objects hiding eachother are not handeled correctly. At least up to my knoledge. So first non-transparent objects are drown then transparent ones.

In the current state mozi checks each body twice. It would be too much unneccessary duty to do the constraint calculation twice too. So Transparency command is handeled first then the transparency of each object is determined and then in each routine only those objects who are the correct transparency calculated. This should also be considered when order of changes is important.

An other annoying consequence of this is that by removing the command does not change back the value to the original. You have to do it by hand.

Apart from this Transparency command behaves as a Simple command.

Transparency
Transparency of the body.
Parameters:
  1. Transparency (scalar). Value larger than zero means transparent.
  2. Expr
  3. Type

Print

A typical example of lazyness but may consider as a feature because this command may have the place elsewhere. This command prints text to the GL screen. You may print the value of any variable to the screen. Unfortunately, only one font can be used that is specified by the command line, the rc file or mozi falls on the hardcoded location.

There are two ways of positioning the text. One is the position on the screen. In this case x and y coordinates may vary from 0 to 1 representing the screen fraction. In this case there is no depth, the sign of the x coordinate decides that the text is placed before or behind the objects. The second method is distinguished by supplying vector variable at the y parameter which then means a position as the objects in the datafile. Thus one can print text next to an object that moves with it. In this case the value of the parameter of the x coordinate is neglected if its sign is negative the fonst will be transparent.

Print
Parameters:
  1. Text in printf format see below.
  2. x coordinate (scalar). Range is [0:1] represents screen fraction. Normally text is behind objects. If you want it on top of the objects that it is always visible give the value you want with negative sign (e.g. -0.1 instead of 0.1). OR a positive or negative number for non-transparent/transparent fonts.
  3. y coordinate (scalar/vector). Range is [0:1] represents screen fraction OR a vector of the position of the text as other bodies.
  4. Color (vector). See vector constants.
  5. Angle (scalar). Always degrees.
  6. Size (scalar/vector). If it is a scalar then the text's size is multiplied with the result. It if is a vector then x and y coordinates are multiplied seperately according to the x and y coordinates of the vector. E.g. alongate the width twice but keep the height, enter: i_x*2+i_y

The text format:

The format in general follows that of printf with restrictions and modifications. Here is the summary of the differences that may not be complete

Var

This command has two usage: Either it may alter global variables like object orientation and position, or define variable. The use of the latter can be manyfold. The 'Var' command is calculated before changing the properties of the bodies and can be much faster when looking for the maximum or the minimum of something.

Var
Parameters:
  1. Name or number of the variable.
  2. Value of the variable
  3. Expr
  4. Type

Global variables

You may set the global orientation and the position of the system. You may set them as a vector or componentwise. The first parameter of 'Var' must be one of the following:

Note, that if any of them is set the change with mouse is only temporary. Redraw changes back the position.

Example:

You want to look around the system: Var[gl.phiy;fpos]

This changes the point of view by one degrees at each frame. This is at every timestep or if frame repeat is set to some value the same configuration is shown from different angles.

Local variables

The first parameter is evaluated to an integer. This can be anything from 0 to 3*body_alloc (see -b command line option). Afterwards the value can be used in var() function.

It is advisable to put any neccessary Array Functions in a Var argument otherwise mozi slows down enormously.

New

This command lets the user to create new objects. This command has a very complex interpretation and may not be free from bugs. There are three levels of new objects creation: one single new object, maximum one new object for each body, N objects for each body (with N number of bodies).

The new objects (all of them even if generated by multiple New commands) will have the type one larger than the maximum different objcet types in the datafile. (E.g. demo.dat: Wall(1), Cylinder(2), Ball(3), so new objects will have type 4).

The number ('num' variable) of the new objects starts from body_alloc-1 and decreases. This is done to haev the possibility to save them from timestep to timestep and trace a particle.

New
Parameters:
  1. Type(s) refer Body Types section for parameters
  2. Empty/Expr when should it be created
  3. Dimension (vector)
  4. Position (vector)
  5. Color (vector)

Single object

If second parameter left empty, only one object will be created. Ideal for marking positions, angle etc. All simple variables refer to the very first object in datafile.

Example:

To Mark the height of the center of mass of the balls by a yellow disk in demo, use the following constraint:

Var[0;Av(z);1;3] New[disk;;0.005;var(0)*i_z;;Yellow]

First the zeroth variable is assigned the value of the average z coordinate (all balls are identical) of the balls (type=3). Then a single disk is created by 'New' at height var(0). See resulting image.

One object per particle

Mozi evaluates expr for each body and for which it finds it true creates a new body with the parameters supplied. All simple variables refer to the same body.

Example:

Show direction of each ball in demo by and arrow. Change to Radian units and type:

New[arrow;type=3;0.002*i_x+0.0001*i_z;Pos;Rot(Orient,phi,i_z);Yellow]

The created object will be an arrow. It is created only for type=3 bodies (Balls). Length is 0.002 width is 0.0001 units. Its position is the same as the ball it belongs to. Orientation must be get by the above rotation as in the standard data format orientation is supplied by an axes and an angle. If the z axes is rotated arount the axes (Orient) by phi radians we get the corrrect orientation.

Result is on this image.

N object per particle

There is an array variable (i) in mozi. If it appears in an expression it is evaluated with each body and i is substituted by the num variable of the cycle. This will be explained later in detail. In 'New' if it appears in any of parameters (1-4, Expr, Dimension, Position, Direction) the 'New' command is processed N2 times. This allows to create objects depending on the properties of two objects. Use carefully as it can be extremely slow in large systems.

Example:

In the demo file we want to draw a line between those particles which touch each other. We explain the corresponding constraint step by step. See also the image.

New[cylinder;(P.type(i)=3) && (type=3) && (abs(Pos-P.Pos(i))<(dx+P.dx(i))/2) && (i>num); (dx+P.dx(i))/2*i_z+0.0002*i_x; P.Pos(i); Pos-P.Pos(i);Yellow] Size[dx/2;1;3]

Explanation:

  1. parameter (type)
  2. cylinder
    The type of object we want to make. We could have used its numerical value 3 instead.
  3. parameter (expr)
  4. (P.type(i)=3) && (type=3) && (abs(Pos-P.Pos(i))<(dx+P.dx(i))/2) && (i>num)
    If this expression is true an object will be created. All expressions are connected with the and relation so all must be true.
  5. parameter (dimensions)
  6. (dx+P.dx(i))/2*i_z+0.0002*i_x
    The size of the cylinder. The x component of the resulting vector is its width (diameter) and the z component is its length which is just the distance between the particles. The followind would be equivalent: Vector(0.0002,0,(dx+P.dx(i))/2)
  7. parameter (position)
  8. P.Pos(i)
    The position of the cylinder. Note, that here we could have chosen Pos too and revert the sign of the next field.
  9. parameter (direction)
  10. Pos-P.Pos(i)
    The direction of the cylinder. An unnormalized arrow pointing from one particle to the other.
  11. parameter (color)
  12. Yellow
    The color of the cylinder. Note that this argument is not searched for array variable when determined which method is used but it is evaluated for it. So you can use the Vector function with i in it.

Expressions

mozi understands normal mathematical expressions (e.g.: 1+2), groupped with paranthesis ('()' or '{}'). The functions are discussed below. All numbers are considered double precision scalar or vector even if the result is expected to be an integer. There is no error message for vector/scalar mixup. The only error messages you may get if the formula you supplied cannot be converted to RPN (Reverse Polish Notation) format. These errors include unpaired brackets, not enough operand for a function or unknown symbols.

mozi is in generaly case insensitive only the scalar variables are case sensitive.

The following groups are discussed:

Scalar Constants

Numbers are treated as scalar constants. mozi understands decimal point numbers and scientific (e.g. 1.5e-3) format.

Name   Value
pi3.14159265...
e2.7182818...
wall1
ball2
cylinder3
disk4
force6
arrow12
cone13

Vector Constants

The first three vectors are the principal axes, the fourth the nul vector, the rest are color definitions.

Name   Value Name   Value Name   Value Name   Value
i_x(1,0,0) i_y(0,1,0) i_z(0,0,1) Nul(0,0,0)
White(1,1,1) Black(0,0,0) Red(1,0,0) Green(0,1,0)
Blue(0,0,1) Yellow(1,1,0) Magenta(1,0,1) Cyan(0,1,1)
Orange(1,0.66,0) Brown(0.5,0.11,0.11) Grey20(0.2,0.2,0.2) Grey40(0.4,0.4,0.4)
Grey60(0.6,0.6,0.6) Grey70(0.7,0.7,0.7) Grey80(0.8,0.8,0.8) Grey90(0.9,0.9,0.9)
Red2(0.75,0,0) Red3(0.5,0,0) Green2(0,0.75,0) Green3(0,0.5,0)
Blue2(0,0,0.75) Blue3(0,0,0.5) Yellow2(0.75,0.75,0) Yellow3(0.5,0.5,0)
Purple(0.6,0.11,1)

Variables

DescriptionScalarsVector
Number/type: numtype
Size/force index: dxdydzi1i2Dim
Position: xyzPos
Orientation: rxryrzphiOrient
Color: crcgcbcaCol
Coordination number: Z
Velocity: vxvyvzVelo
Force: fxfyfzForce
Angular velocity: omxomyomzAngVelo
Torque: txtytzTorque
Tr. Velocity: tvxtvytvzTrVelo
Tr. Force: tfxtfytfzTrForce
Tr. Angular velocity: toxtoytozTrAngVelo
Time: pstfpos

Variables are the parameters of the objects read from the data file. In general data file contains a lot of information. Refer to fileformat.txt supplied with mozi for a detailed description. In normal visualization mozi uses the Size, Position and the Orientation fields. Only Size is obligatory.

Most of the parameters are vectors (like 'Pos' position) but its components are also available. In some cases when the parameter is a group of scalar they are also available as vector to facilitate the handling of them. The color (Col=(cr,cg,cb) (Red,Gree,Blue), and Dim=(sx,sy,sz) (X dimension, Y dimension, Z dinemsion).

These variables are case sensitive in mozi.

If these variables are used in a constrant they are filled up with the parameters of the actual body. For example: Size[Dim*2] Position[Pos*2] will make the system and every paricles twice as big as both positions and size are doubled.

If you change any of them by a command, let's say 'Pos' by the Position command, then in commands after this the modified value will be used. So be careful with the order of the commands.

Description of the variables

Here we describe the meaning only of the variables which is not trivial. In most cases the meaning is clear for example if you supply Tr. Velocity in the datafile then mozi knows from the parameter part of the type fields. The the values are read and stored in scalar variables tvx,tvy,tvx and vector variable TrVelo of each particle.

num
Each body has a uniqe number. The numbering starts from 0. In some cases (e.g. P.variable(num))it may be important to know the number of an object. Either you know it from the datafile (use getcol4 command) or there is a function that returns the starting 'num' value (gbeg(#)) and the number of elements (gnum(#)) of each group of partciles.
type
The particles are partitioned into groups. The default is that the grouping follows the data file but grouping can be performed by texture and type difference. See -t command line option. The grouping helps you to manage display easier. The groups are shown on the control window by check buttons. The group number is also printed in paranthesis after the type string. It starts with 1. Basically every command has a type parameter field where you can specify for which type of particles the command is applied for. So this is one of the most important parameters
ps
The position in the datafile. The same number that you have in the box in the Animation frame next to the slider bar. This has the same value for all particles.
t
Each line in the data file starts with a time value. This value is assigned to 't' which has also the same value for all particles.
fpos
If framerepeat is set to be larger than one this should be used instead of 'ps'. It is incremented by one at every frame plotted so in general it has a value framerepet*ps but also counts the repeated frames one by one. This is extremely useful if you want to make a movie from one frame while flying over or looking around.

Using other particle's parameters

It is possible to use other variable's parameters but you have to know it's number (num).

P.Pos(3)

The above variable will take the position (which is a vector) of the object with num=3. With this method you can include in a constraint any property of any body. See 'New' example for a demonstration.

Unary Functions

Unary functions expect one argument between parenthesis. Except for 'norm' all functions work with scalars. If vector is given as argument then its length [=sqrt(x*x+y*y+z*z)] is taken as argument. So for example abs(v) gives the length of a vector.

sinsinus (s)
coscosinus (s)
tgtangent (s) {=sin(s)/cos(s)}
ctgcotangent (s) {=cos(s)/sin(s)}
asinarcussinus (s)
acosarcuscosinus (s)
atgarcustanget (s)
actgarcuscotangent (s)
sqrtsquare root of absolute value (s) {=sqrt(abs(s))}
sqrsquare (s)
absabsolut value (s)
sgnsign function (s) {=1 if s>0; =0 if s=0; =-1 if s<0}
expexponential (s)
lognatural logarithm (s)
intinteger part (s)
normsgn (s), normalization (v) {=v/abs(v)}
varvalue of variable int(s): (s) return value depends on the definition in the Var command
gbegnum of the first body of group (s)
gnumnumber of bodies in group (s)

Binary Operators

Binary operators are placed between its two arguments like 1+2. The order follows the usual mathematical convention and listed below. The smaller value at order shows which operations are made first. Two operators haveing the same order are evaluated in the writing order at the same step (e.g. 6*4/3*2=16). If you want to change the order use parenthesis [e.g. (1+2)*3=9].

The most contraversal part of the constraint implementation in mozi is the dealing with binary operations dealing with mixtures of vector and scalar. There is no way to know in advance the nature of some quantities so no error message is printed e.g. for dividing by a vector but some 'reasonable' answer is made.

Description:

Notations:

x1,x2: first and second argument, not specified if vector or scalar
s1,s2: first and second argument if scalar
v1,v2: first and second argument if vector

If x1 or x2 is a vector then s1=abs(v1) and s2=abs(v2). For Vector function see Vector functions.

[S] or [V] indicate scalar or vector return value

OperatorOrders1,s2s1,v2v1,s2v1,v2
^1Power [S]=s1^s2 Vectorial product [V]=v1^v2
*2Multiplication [S]=s1*s2 Scalar product [S]=v1*v2
/2Division [S]=s1/s2
%2Integer modulus [S]=s1%s2
+3Addition [S]=s1+s2Addition [V]=v1+Vector(1,1,1)*s2Addition [V]=v1+v2
-3Substruction [S]=s1-s2Substruction [V]=v1-Vector(1,1,1)*s2Substruction [V]=v1-v2
>=4[S]=(s1>=s2) The result is 1 if true and 0 if false
= or ==4[S]=(s1==s2) The result is 1 if true and 0 if false
<=4[S]=(s1<=s2) The result is 1 if true and 0 if false
!=4[S]=(s1!=s2) The result is 1 if true and 0 if false
>4[S]=(s1>s2) The result is 1 if true and 0 if false
<4[S]=(s1<s2) The result is 1 if true and 0 if false
& or &&5[S]=(s1&&s2) The result is 1 if both are positive and 0 otherwise
| or ||5[S]=(s1||s2) The result is 1 if any of them is positive and 0 otherwise

Vector Functions

The following subset of functions is called Vector functions. They do most common vector operations except from vectorial and scalar product which is done by binary operators. The parameters of these functinos are seperated by comma ','.

The major difference between these functions and the previous ones that they work only with correct function arguments. If scalar is supplied instead of vector or vica versa they do not do anything. In that case the result will be the first argument irrespect of its type.

FunctionParametersDescription
Rotr[v]=Rot(t[v],phi[s],x[v]) Rotates vector x around axis t with angle phi
Mirrorr[v]=Mirror(t[v],x[v]) Mirrors vector x on the plane perpendicular to t
Lincombr[v]=Lincomb(a[v],b[v]) Componentwise sum: r_x=a_x+b_x, r_y=a_y+b_y, r_z=a_z+b_z
Ifr[s/v]=If(e[s],t[s/v],f[s/v]) If e>0 then r=t otherwise r=f. t and f must be of the same kind
Vectorr[v]=Vector(x[s],y[s],z[s]) Returns vector given by the three components
Compr[s]=Comp(x[v],c[s]) Returns c component of vector. c must be 0, 1, 2
Projlr[v]=Projl(p[v],x[v]) Projects x on the vector p. The result is one dimensional
Projpr[v]=Projp(p[v],x[v]) Projects x on the plane perpendicular to p

Array Functions

Array functions have arbitrary number of parameters, seperated by comma ','. The most general usage of them is to average, get the minimum, etc. of some material property.

The second usage of the array variable 'i' apart from the command 'New' is with these functions. If the array variable 'i' appears in one of the arguments of these function then 'i' is substituted by each 'num' for which the expression and type of the command fulfills. In such a way the number of arguments of these functions is increased.

Let us note that of course this can be very time consuming. To reduse time of the constraint calculation use these commands preferably only with 'Var' command. 'Var' command is evaluated seperately from the other commands and before them. Calculating the minimum of a property in 'Var' needs N operations (N being the number of particles), while using it in a Simple command (e.g. Position) takes N2 operations as the minimum is calculated at the drawing procedure of each particle.

The only function that is different from the others is 'Foreach'. This is used as an argument of the other functions if the parameter list should be further restricted. This may happen if two of these appear in one command.

The only function that is different from the others is 'Foreach'. This is used as an argument of the other functions if the parameter list should be further restricted. This may happen if two of these appear in one command.

FunctionDescription
MinMinimum of arguments
MaxMaximum of arguments
AvAverage of arguments
SumSum of arguments
Minpnum of minimum of arguments
Maxpnum of maximum of arguments
Foreachreturns num only if argument is true (>0)




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

Note 2: In older versions there was a possibility to change the origin in the above window. Since now it can be done by constraints it is removed from here. The present system is more convenient since you can preview what you will get.




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

At present .mozirc is first searched for in the current directory, if not found $HOME is searched for. Writing always goes to the global one. (TODO: local writing should be enabled.)

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

List of parameters written into .mozirc

The latter two may include several lines and are rewritten even if you do not make mozi write rc file. The other options are changed only at your request.

In some cases it may happen that mozi crashes at the wrong time or multiple mozi session destroy or mess up the constrain section of the rc file then please take a look at .mozirc~ and .mozirc_ files. And if you find them better copy them back. In general .mozirc~ is the rc file before the last and .mozirc_ the so far longest file.




10. Download

Mozi


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


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