The manual is made of a collection of web pages connected with hyperlinks explaining the functions of all aspects of any Lsd model program (see help pages on LMM for the documentation on the creation of Lsd model programs). This manual includes a section for each Lsd windows, and can be used during an actual session with a Lsd model so to have a direct explanation for all aspects of Lsd.

Table of Contents

• Introduction what is Lsd and why should I use it
• Tutorials. The manual includes three tutorials on the use of Lsd: first time users, using an existing model, writing a new model.
• Lsd Model Manager (LMM) the program used to manage Lsd models
• Lsd Windows  list of the main windows used by Lsd
• Lsd Main Browser the control center of Lsd to run, edit or create a model configuration. The commands (most of them are accessible also via shortcuts) are defined in the following menus:
• Menu File
• Menu Model
• Menu Data
• Menu Run
• Menu Help
• FAQs frequently Asked Questions, with definitions of the most recurrent terms.
• Lsd Debugger The debugger allows to observe the values of the model during the simulation runs, and possibly to change some of the numerical values.
• Lsd Equation Functions the equations in Lsd are written in C++ plus some special Lsd functions to deal with Lsd models specific commands.

Introduction
Lsd (Laboratory for Simulation Development) is a simple and powerful language for simulation models. Lsd has been conceived and developed in order to provide automatically all the technical elements required to run a simulation program, although enjoying the maximum freedom to implement whatever computational model, since at its core is just pure C++ (meaning speed, reliability, portability etc.).

A Lsd model is composed by its computational content, the equations, and by the model structure. A developing environment (Lsd Model Manager, LMM) permits to write with extreme simplicity the equations of the model, expressed like difference equations and implemented either in C++ or in an equivalent simplified macro-language. Using LMM the equations are compiled and embedded in a stand-alone program, together with the rest of the code for Lsd.. The resulting Lsd model program allows to define the model and run the simulations, complete with graphical interfaces for any possible operation on the model, from defining the initial values to plot the final results.

Modellers and users of Lsd models need to concentrate exclusively on the model neglecting every technical aspect of programming (not related to the actual model). For example, a simple entry in LMM creates a new model, and another compiles the equations, checks for errors and runs the Lsd program. Lsd models are endowed with controls catching errors whenever they occur, providing information on how to fix them before they crash the program.

Users of an existing Lsd model can load a pre-packaged configuration of the model (e.g. initial values, number of steps) and repeat the simulation as suggested by the model author. New configurations are created with extremely simple and intuitive interfaces, so that even users ignoring totally any programming language can make use of simulation models.

Lsd is particularly suited to implement agent-based models, given its embedded multi-layered system. However, at the very core Lsd is nothing else that pure C++ (inheriting its speed, reliability and portability), with an added a layer of graphical interfaces, so that any computational structure can be implemented in Lsd. A model is composed by chunks of C++ representing the equations of the model (normally very simple). Modellers define the entities of the model and the initial data using simple and intuitive graphical interfaces. At run time the system automatically arranges the pieces of code in the correct sequence and collects the results.

A crucial characteristic of a Lsd model is that it is inherently modular. You can (an should) implement one piece per time, test it, and then extend the model with a new part. Since the equation are represented like difference equations, the system automatically sorts out the correct sequence of computations during a simulation time step, signalling possible inconsistencies. The system provides automatically all the documentation concerning the model (e.g. which equation uses which parameter), so that even very complex models can easily be reviewed without getting lost in a lot of messy code.

Lsd appeals to novel programmers because facilitates a gradual, trial and error process to modelling, signalling errors and suggesting solutions. However, Lsd is also useful for expert programmers because the language does not pose any limitation to the models it can implement and facilitates the management of very complex models.

An exenstive documentation covers every aspect of Lsd, with tutorials, explanations of the interfaces, hints on programming.
return to the top

The main advantage of Lsd is that it minimises the code modellers are requested to write for a model. When the model is ready, users of the model have available a huge set of interfaces for dealing with the model (e.g. running simulations, changing initial data, observing the results, etc.). These interfaces are added without any intervention from the modeller, and permit the thorough exploitation of a model even to users with scarce computer experience.

A very important aspect of Lsd is that it provides a complete documentation of a model. This is important for the modeller, since he can easily control the effect of a modification even in large and complex models. But this is even more important for users of a model, since the documentation provides a complete and informative way to understand the very functioning of a model.

Although Lsd offers several tools to facilitate the writing of simulation models, it does not limit at all the scope of models that it can implement. In fact, all Lsd does is to wrap C++ code with "smart" interfaces, and therefore expert users can include in a Lsd model whatever C++ code they like. This implies that a Lsd model is extremely fast to run, and it is virtually unlimited in the dimensions of the model.

The cost of using C++ is that it generally requires quite advanced tools and programming experience. Using Lsd and the programming environment LMM modellers create models writing only the code for the equations of the model, while the technical operations for actually producing the program are hidden behind “smart” graphical interfaces.
A non secondary feature of Lsd is that it favours gradual programming, limiting the scope for errors. The typical cycle to build a Lsd model is the following:

• create a model with one single Variable and all parameters
• write one equation for the Variable
• test the model result (and fix the errors)
• transform one Parameter in a Variable (or add a new Variable)
• write the equation code for the new Variable
• go to 3.

In Lsd this is possible because it is extremely easy to modify a model adding extra elements (or removing existing ones), and editing its code. Moreover, the interfaces provide many powerful ways to explore the functioning of the model (e.g. step by step running, conditional breaks, modification of values during the simulation etc.).

return to the top

Installation and Content
The installation includes:

• the Lsd source code
• several Lsd example models
• LMM
• the manuals for Lsd and LMM
• other required software (Windows installation only)

Windows installation (95/98/NT/2000)
Unzip the distribution file in any directory controlling that there are no spaces in the any parent directory. For example C:\Program files does not work. Once unzipped, you will find a new directory called Lsd. Click on the file RUN.BAT. LMM will start, and from there you can select an existing model or create a new one. In case of errors, control that the directory where you placed the system does not have any parent directory with spaces.

Unix installation
To use the Lsd system it is necessary to have a GNU GCC compiler with the standard libraries, the Tcl/Tk package 8.3 (or newer). Moreover, if you want to hard-debug models you need the GNU GDB debugger.

The procedure to install the system consists in: unpack the files; compile LMM; run LMM to create and run Lsd models. Installation problems can be due to different location of Tcl/Tk or other libraries required by your compiler. Here are few hints to fix the most frequent problems.

To unpack the file LsdXXunix.tgz (XX is for the version nummber) use the command:
# tar xzf LsdXXunix.tgz
This will create the whole directory structure.  If the file is in format .zip, then simple unzip it.

To compile LMM move in the new Lsd directory and use the makefile "makefile.ln":

# make -fmakefile.ln

If the compilation succeeds run LMM with:

# ./lmm

If the compilation fails the most likely source is the need to specify further libraries requested by Tcl/Tk. Add missing libraries to the "DUMMY" variable in the makefile.

Another possible reason for a failed compilation is the mispecification of the location and/or version number of the Tcl/Tk libraries included in the development distribution.  Any version up to the 8.4 seems to work nicely. In this case you need to adjust the makefile.ln to your system. Try to replace /usr/lib with /usr/share/lib or /usr/local/lib. You need to find the location for the files libtcl8.4.a and libtk8.4.a (or 8.3 for the older version). Once you find it, write the path in the variables "PATH_TCL_LIB=". Similarly, the compilation expects the tcl.h and tk.h files in /usr/include directory. If they are not there, write their location in the variables "PATH_TCL_HEADER=" and "PATH_TK_HEADER=". If you edit the makefile, then, the first time to try to compile a Lsd model, you need to set the "System Compilation Options", in the menu "Model" of LMM. These operations are requested only the very first time you use the system.

For persisting problems email me: mv@business.auc.dk
return to the top