simspark library README

Please see NEWS.

General Information

simspark is a physical simulation system. The primary purpose of
this system is to provide a *generic* simulator for different kinds
of simulations. In these simulations, agents can participate as
external processes. To create specific simulations, important parts
of the simulator are build as plugins that can be replaced for
different simulations. The plugins can be exchanged at runtime.
Things designed as plugins are for example parts of agents: agents
can be using different actuators or perceptors. Other plugins are
responsible for the simulator protocol or also for the rules of
specific simulations.
Simulations for this simulator can be constructed to a great part by
changing text files with no further recompilation. The basic simulator
concept was presented on the 2003 RoboCup Symposium in Padova [1].

If you installed simspark-0.x before, make sure to clean
the ~/.simspark/ directory prior to using the new version. Also
better remove the old installed libraries in /usr/local/lib/
simspark manually. Sorry for this inconvenience.

For scientific simulations, it is useful to be able to keep track of
the time used by different agents for thinking. A special plugin
makes it possible to use the simulator together with SPADES, a
middleware system for agent based simulations. SPADES was presented
on the 2002 RoboCup Symposium in Fukuoka [2] (SPADES itself is not
part of this package). 

Package Overview

The different parts of this package are organized in different
directories as follows:

./lib             The main simulator parts as libraries. The         
                  simulator consists of these parts:                 
./lib/salt        This library provides a collection of useful       
                  general purpose classes. It contains mostly        
                  math-and system-related functionality, such as a 3D
                  Vector class, a Matrix class, a file I/O wrapper   
                  and an abstraction for loading/accessing shared    
                  libraries.                                         
./lib/zeitgeist   The Zeitgeist library provides two major features. 
                  It implements a mechanism to work with class       
                  objects in C++. A class object is just a factory of
                  class instances. In addition to this mechanism, it 
                  also implements an object hierarchy. This hierarchy
                  is essentially a virtual file system, where the    
                  'directories' and 'files' are instances of C++     
                  classes. These two concepts are quite intertwined  
                  with each other, as class objects can also live    
                  inside the object hierarchy. Objects within the    
                  hierarchy are identified with a unique name. On top
                  of these two features, the Zeitgeist library also  
                  provides three very important 'built-in' services. 
                  Each basic service is usually represented by a     
                  'server' class in our terminology. An instance of  
                  such a class provides the service to other parts of
                  the system. The three services built into the      
                  Zeitgeist library are the LogServer, the           
                  FileServer, and the ScriptServer.                  
./lib/oxygen      Oxygen is the actual engine which is used for the  
                  simulation. It is implemented on top of the        
                  Zeitgeist framework and provides a multitude of    
                  different services to a client application. It     
                  handles the physics aspect (PhysicsServer), the    
                  geometry aspect (PhysicsServer) and the agent      
                  aspect (AgentAspect, ControlAspect). Another       
                  important part of this library is performing the   
                  world simulation (SceneServer).                    
./lib/kerosin     Kerosin handles the visualization aspect           
                  (ImageServer, FontServer, OpenGLServer,            
                  TextureServer, MaterialServer). The classes in the 
                  library also provide basic interfaces for receiving
                  input in interactive simulations (InputServer) and 
                  for playing sounds (SoundServer). Currently, it is 
                  not used for the simulator.                        
./plugin          directory containing plugins to extend the simulator
./data            contains some common data files which can be used
                  for creating simulations using simspark                              
./test            applications for testing different subsystems of the        
                  simulator.                   
./carbon          The carbon library contains a gui-framework and a
                  simulation-framework which wraps simspark using qt.
                  Its main features are:
                  - Offering a graphical user interface which can be extended
                    by visual and functional plugins. The plugins can be used
                    to write easy-to-use interfaces to simspark simulations.
                  - Creating, managing and executing simspark-simulations
                    alongside with any additional threads and processes.
                  - The gui can be altered flexibly. Its main window with
                    "attachment points" is loaded from a shared library, and
                    its used plugins are loaded from shared libraries too.
                    Plugins with visual representation can be attached to the
                    Gui.
./guilayout       Layout projects for the Gui. They export main windows for
                  the carbon gui from a shared library. You can easily and
                  quickly create a new layout for the gui by creating a new
                  layout project. A gui-layout (main window) may define
                  attachment points for gui-plugins.

                  Initial layout projects:
                  - guigridlayout: Contains 4 attachment points (left, center,
                    right, bottom)
                  - guisimplelayout: Contains 2 attachment points (left, right)
./guiplugin       Generic (not soccer related) plugins for the carbon gui.
                  Plugins can be anything to extend the gui with. There are
                  three types: Simple Plugins (can be executed), Signal
                  Plugins (can communicate), and AttachableFrame Plugins (can
                  be embedded into the Gui). Examples which can be created
                  really easily and quickly, are: executable plugins running in
                  a new thread, function libraries, toolboxes or menu entries,
                  or visual plugins made for user interaction.

                  Initial plugins (all of them are plugins that can be attached
                  to attachment points):
                  - logframe: logs and displays messages
                  - setupframe: creates simulation setups for the gui
                  - simulationframe: displays and controls simulation tasks and
                    processes in the gui
                  - scenegraphframe: displays and controls the whole scene graph
                    of a spark simulation. The user can freely change the values
                    of several types of nodes.
                    This interaction can be extended with additional plugins.
                  - monitorframe: renders a spark simulation

Literature:

[1] Marco Kögler and Oliver Obst. Simulation League: The Next Generation.
    In Daniel Polani, Andrea Bonarini, Brett Browning, and Kazuo
    Yoshida, editors, RoboCup 2003: Robot Soccer World Cup VII,
    Lecture Notes in Artificial Intelligence, Springer, Berlin,
    Heidelberg, New York, 2004.

[2] Patrick Riley. MPADES: Middleware for Parallel Agent Discrete
    Event Simulation. In Gal A. Kaminka, Pedro U. Lima, and Raul
    Rojas, editors, RoboCup-2002: Robot Soccer World Cup VI, Lecture
    Notes in Artificial Intelligence, pp. 162-178, Springer Verlag,
    Berlin, 2003.

---------------------------------------------------------------------

Oliver Obst
Last modified: Thu Jan 29 10:57 IRDT 2009 (By Hedayat Vatankhah)
