Here you can find help on various aspects of using MASyV. The information found herein refers to the latest version of MASyV so if you find that instructions here don't work out for you, first make sure that you are running the latest version of MASyV. If things still don't work out for you, please don't be shy and file a Bug report. I'll deal with it promptly.
You can get help on:
Download the latest release of MASyV, MASyV-0.X.tar.gz, from SourceForge here.
To compile MASyV, you'll need the GNU C compiler, gcc, which you really should have anyways. If you want to run MASyV's GUI (which you do, trust me), then you'll also need to make sure you have the following installed:
Under Debian, selecting the package libgtkglext1-dev should pull in the other two packages and their requirements.
In addition to the above, you may also want to get the following OPTIONAL dependencies:
You might want to consider using the GNU Scientific Library in your own clients. It is a neat library which provides a set of very useful scientific functions like Airy or Bessel functions, and a whole range of random number distributions such as Chi-squared, Gaussian, and Exponential. If you do scientific programming, this library is something you should really have anyways.
gstreamer + the codecs you'll want
(to capture simulation to compressed movie file)
GSL - The GNU Scientific Library
(to compile some of the clients)
I compile and run MASyV on a Linux system (Debian) but I suspect it should work on any platform which supports Unix domain sockets and for which the above requirements are available, e.g. Mac OS X (for this, see also "More specific directives for the Mac OS X users" below).
You should now have a file named something like MASyV-0.X.tar.gz. Here is how to procede from there:
- Unpack the file
tar -xzf MASyV-0.X-tar.gz
- Move into unpacked directory
- Configure installation to your specific machine
if you want it installed in a different location than the default location for your system when you'll type "make install" later (e.g. above in the local subdirectory of your home directory).
Here, you want to pay attention to the error messages if any. If GSL is not found, you'll see a warning that says
*** WARNING: The client simulations that depend on GSL will NOT be built. This means that your GNU Scientific Library was not found so the clients which require it will not be compiled. If either GTK or GtkGLExt was not found, you'll instead see
*** Gtk+-2.0 and/or GtkGLExt-1.0 NOT found.
*** MASyV's GUI, masyv, will NOT be built.
*** Use logmasyv instead to run your clients.
This means that masyv, the GUI that you would run to visualize your simulations cannot be compiled. You will have to run your client simulations using logmasyv instead. That maybe ok if all you want is to run your client from the command-line and have it output the statistics to stdout.
- Build/compile MASyV
- Install MASyV
You may require super-user privileges to do this depending on the location chosen for the installation. It can either be your system's default (usually /usr/local) or whichever location you selected when you typed ./configure above using the --prefix option (see step 3).
- Just to make sure it worked, test logmasyv
server/logmasyv -s clients/ma_hello
- Then to make sure MASyV's GUI works too, try
server/masyv -s clients/ma_hello
Of course, if you encountered an error when running ./configure stating that masyv will not be built (see step 3), then you won't be able to run masyv here.
More specific directives for the Mac OS X users
The easiest way to get MASyV on a Mac OS X is to first get Fink. Here are the steps you should follow:
- Download the latest Fink (it'll make installing the rest much simpler)
You may also want to get Fink Commander (a user-friendly GUI for Fink)
After installing Fink, if you were working from a terminal, you'll have to re-start the terminal so that Fink's /sw path gets added to your PATH variable.
Once you have Fink installed and working, you'll need to use it to install the following packages:
While trying to install gtk+2, if it complains about the absence of /usr/X11R6/lib/libXinerama.1.dylib, here is what you can do:
- gtk+2, gtk+2-dev, gtk+2-shlibs
- gtkglext1, gtkglext1-shlibs
- gsl, gsl-shlibs (only needed to run some clients, not needed by MASyV)
Because dependencies in Fink have not be appropriately been set, you'll also have to install the following packages:
You will now unpack and compile MASyV:
MASyV has now been compiled. If typing configure produced errors, see above in the general section to help you troubleshoot.
- Open a terminal (Applications -> Utilities -> Terminal)
- "cd" to the location where MASyV-0.X.tar.gz is located
- Type "tar -xzf MASyV-0.X.tar.gz" or "tar -xf MASyV-0.X.tar"
- Type "cd MASyV-0.X"
- Type "./configure" then type "make"
Start X11 (Finder -> Applications -> Utilities -> X11), and open an X11 terminal (Applications -> Terminal or %N).
We will now run MASyV's ma_ants client from the X11 Terminal:
and beautiful ants should appear crawling around on your screen. If you encounter problems, see above in the general section to help you troubleshoot.
- "cd" into the MASyV-0.X directory
- Type "./server/masyv -s clients/ma_ants/ma_sqr_ants"
MASyV's graphical user interface
MASyV's GUI is built using GTK+ widgets and functions. For better graphics performance, the display screen widget, which displays the client simulation, makes use of GtkGLExt's OpenGL extension which provides an additional application programming interface (API) enabling GTK+ widgets to render 3-D scenes using OpenGL. For more information about GTK+, its libraries and its widgets, please consult the GTK+ Tutorial and API references. Here, the discussion will be limited to describing the overall capabilities of MASyV's GUI rather than the GTK+ structures from which it was built. MASyV's GUI is mainly composed of a notebook widget containing three tabs which I will now describe.
The Simulation tab
The Simulation tab displays the visual representation of the client simulation. The buttons, Pause, Advance, and Play, can respectively be used to pause, advance by one time step, or by several sequential time steps, the client simulation. The Screenshot button captures the display screen to a PNG file and brings up a file selection dialog which allows the user to chose the name and location of the file to be saved. The "Save animation" check box is only enabled when all the correct information has been entered in the capture tab. Checking the enabled check box will initiate a call to gstreamer, which will begin encoding the simulation to a compressed movie file using the codec specified by the user in the Properties tab. Finally, a "Step #" label indicates the current time step of the client simulation being displayed on the display screen.
The Simulation tab presenting MASyV's GUI running the client module|
ma_sqr_ant which models ant depositing and following pheromone trails.
The Statistics tab
In the Statistics tab, MASyV posts the statistics sent by the client simulation. The "Log to file" check button, the text entry box and the "Browse..." button enable the user to save the statistics from the simulation to a file of his/her choice. When the check button is enabled and checked, the file whose name has been entered in the text entry box is opened and the statistics start being written to the file. When the check button is unchecked, the statistics stop being written and the file is closed. Clicking again on the check button will re-open the file and append the new statistics as they arrive.
The Statistics tab presenting MASyV's GUI displaying the statistics from|
the client module ma_sqr_ant which models ant depositing and following
The Properties tab
The Properties tab currently offers to the user the possibility to control many aspects of the capture of the simulation to a compressed movie file. At the moment, MASyV only supports raw capture, and capture using the XviD, Windows Media Video, and Apple QuickTime codecs. Capture of the content of the display screen to a compressed movie file is made through a call to transcode, which provides a list of utilities to transcode various video, audio, and container formats.
The Properties tab of MASyV's GUI.
Both server programs, masyv and logmasyv, can be called from the command-line. The command-line options available for masyv are as follows:
prompt> masyv -h
MASyV v0.10 - Multi-Agent System Visualization (C) 2002 Catherine Beauchemin
Usage: masyv [masyv options] -- [client options]
e.g. masyv -s my_client -- --number_of_ants 3
-s name name of client simulation to be run
-f file name of output file for the statistics
-i num print every num steps
-t time total number of steps (-1 is infinity)
-r factor rescaling factor for simulation area
-x factor clipping factor for simulation area
-w use off-screen instead of on-screen rendering (faster if supported)
-h displays options and exits
The command-line options for logmasyv are the same but exclude the -f, -r, -x, and -w options. The -f option is not needed by logmasyv since the program's only output, the statistics from the client, is sent to the standard output stream, stdout, which can be redirected to any file. Let's illustrate masyv's command-line usage by an example.
prompt> masyv -s ma_client -f stats.dat -t 200 -- --rule 90
This command would start up masyv, run the client ma_client for 200 steps and log the statistics to the file stats.dat. Note that masyv will not log the statistics to stats.dat until the "Log to file" check box on the Statistics tab has been checked. The "--" separates the server options like -s, -f, and -t, from the client option like --rule. It is up to the client to define which arguments it will take and parse them when they are passed to it by the server (see MASyV's API (or Writing your own client simulations)). The command to run logmasyv with the same options is
prompt> logmasyv -s ma_client -t 200 -- --rule 90 > stats.dat
MASyV is still under development. Below are known problems or new features currently under development or on my long-term TODO list.
Screen must be visible when encoding the simulation to a movie file
When using the MASyV GUI, masyv, the simulation window must be on top at all times when recording to movie or taking a screenshot. Othewise, any obscured area will be omited (corrupted) in the encoded movie or screenshot image. This is because masyv uses on-screen rendering by default instead of off-screen rendering and when the rendering surface is obscured, capturing it produces junk in the unrendered (obscured) area. Since MASyV-0.10, off-screen rendering is also available and can be selected by running masyv with the command-line option "masyv -w". Off-screen rendering is done onto a GLX Pixmap. Unfortunately, GLX Pixmaps are not well supported at the moment. As support becomes more main stream, off-screen rendering will become the default mode of operation for MASyV. In the mean time, the lucky few for which off-screen rendering is supported can make this bug go away by always using masyv -w.
libMASyV wrapper for Octave and Python
At the moment, writing a client simulation for MASyV requires the user to know C programming. I hope to lower this requirement by building wrappers for the MASyV library (using swig) so that users will be able to write clients in octave (a free open-source Matlab clone) or python. I hope to be able to have this feature added to MASyV in version 0.12.
Last modified: July 22, 2008, 13:39.