Lsd models for simple users and developers

Lsd models for simple users and developers

This note gives a quick background on Lsd models from two apparently very different viewpoints: users versus developers. However, both groups should read both sections. It may also be relevant to inspect the note on the Lsd between the closed and open source software culture.

Approaching Lsd from the user's viewpoint

The main user of a simulation model is often the person who has developed the model. So the tools provided by the Lsd user interface should be helpful for the developer-user of the model. There are, however, a number of other types of users. The developer may engage the help of some friends to test and explore the model with fresh eyes. There might also be an employer who have commissioned the model and wants to check it before accepting the results. Similarly, a journal editor may be happy if the model that underlies an article is made publicly available. Students might use the model for project work. Finally, other researchers may try to develop the model further or explore some of the modelling tricks that are revealed by the code.

It is not easy to find a system that takes care of all these, partially differing, needs. But Lsd's use of a standard interface allows users to change roles and even to become Lsd developers. This feature represents a maximum of flexibility that can only be obtained if users download and install a full Lsd system (including the GNU C Compiler). This is no problem for Linux/Unix users, but users who have Ms Windows or NT will have to install a version of GCC (and Tcl/Tk) - eg. as an integrated part of the Lsd Model Manager system. In the following we shall consider the Lsd system from the viewpoint of typical members of the closed-source Windows world who nevertheless been persuaded to correctly install the Lsd system and Lsd model directories that include compiled models (an extensive hands-on description for such users is found in Valente and Andersen 1999).

Simple use of Lsd

The user (you) start by locating the executable Lsd model and start it. As a result there will be opened a window referred to as the Lsd Browser-which has the same construction for all Lsd models. You are, however, facing a browser that includes the code for a particular Lsd model. To run this model you first load the model's structure and initial values. Then you run the model and in a plot window follow the computation of preselected variables that are particularly representative for the simulation. During the simulation the Lsd system stores information on a (large) number of other variables, which you after the simulation has finished can study in the Data Analysis window. This window gives us access to e.g. screen plots of the variables and to save the variables for further analysis in programs like Excel and SAS.

After you have studied the results of a simulation, you reload the model structure and initial values, and now you are ready for simulation experiments. These experiments are not restricted to the change of parameters, initial values and the seed of the random number generator. You may also change the number of objects (e.g. industries and firms), and you have tools for making repeated runs to be used for statistical analysis. Finally, you have advanced tools (the so-called debugger system) that allows is to interrupt the simulation at selected events and then inspect the values of all the variables.

Towards an advanced use of Lsd

All this is pretty easy for untrained computer users (who are, however, supposed to have some understanding of the economic meaning of the model). But at some point of time you have explored the possibilities of the compiled equations. At that point of time it is helpful that Lsd allows us to explore equations online and jump from equation to equation by using hyperlinks. Based on this study you may decide to change the model by inserting new variables and parameters, new objects (like departments of firms), etc. Simple changes can easily be performed by untrained users. However, you have to understand that the changes should both be recorded in the Lsd file with structure and initial values and in the Lsd/C++ file that determines the computation of the variables. Since all such files have a pure text format, you should take care that e.g. MS Word does not mess up the files by including special formatting. When you have made the changes (e.g. starting by duplicating an existing Lsd/C++ equation definition and changing the copy to define a new variable), you have to recompile the model. This can e.g. be done from the DOS command line-an arcane feature that is still available on MS Windows/NT. Without further interference GCC starts to recompile the model based on the project management tool (make). After the successful completion of the compilation, you can start exploring the new model.

The problem for members of the closed-source community is, of course, what to do when things go wrong. This will typically be the case of the strategy of incremental change of a given Lsd model has not been followed (remember what your physics teacher told you about only changing one parameter at a time in an experiment?). But even the deletion of a single bracket in the Lsd/C++ program is enough to create trouble. By comparing the new code with correctly functioning equations you will normally be able to find out what went wrong. But sooner or later you will reach the limits of your instinctive approach. At that point of time you have three options: (1) to drop ambitions and stick to minor changes, (2) to find a friend from the open-source community that can help you or (3) to try to become a member of the open-source community yourself.

A shift between the two software cultures is not easy. But your experience with Lsd will define the minimal steps. The first is to use an advanced editor program that communicates with the GCC compiler. In such an editor you will be informed where the compilation went wrong, and you can make a change and restart the compilation without leaving the editor. You can also access the advanced GNU debugging tools. The next step is to learn about the syntax and semantics of the Lsd programming language and the C++ programming language. This will allow you to make use of some of the enormous amount of software tools that are available for scientific programming and simulation in the Linux/Unix world (see the 5,000 items in Baum Linux encyclopedia). Most of these are available even if you develop an open-source environment on top of the MS Windows/NT platform. The final step will be to add generic solutions to the Lsd code library, to suggest and develop modifications of the overall Lsd system, or to explore alternative systems (like the Swarm system of the Santa Fe Institute. Several alternative simulation environments are described by Gilbert and Troitzsch in their Open University Press book.

Approaching Lsd from the developer's viewpoint

As mentioned above there the user of an Lsd model is often also its main developer. But a developer (as well as the designers of the Lsd system) have a much larger set of options than ordinary users.

Choice of programming language

The first major task in relation to the design of Lsd was to choose a programming language. Potential Lsd developers often have previous experience with programming languages (like Pascal, APL, Fortran, C, C++, Lisp, etc.) and/or modelling tools (like Matlab, Maple, Mathematica, etc.). Lsd cannot please all these developers to the same degree, so the best choice seems to build Lsd on a language that has become industrial standard and at the same time includes features that are very close to evolutionary modes of thinking and modelling. This language is C++ (including nearly all of C).

C++ has been designed for the most difficult tasks of large-scale programming (including operation systems), so it has a very strong support for modularity and other aspects of advanced programming. Furthermore, the C++ language grew out of experiences with the classical simulation-oriented language (Simula), so it has also strong support for simulation-oriented concepts. The advantages of C++ are so large that most developers that still use e.g. Pascal or Fortran are interested in making the move. Through the creation of a special Lsd language for writing equations that works on top of C++, the move has been made much easier, and actually rather advanced Lsd models can be developed without more than a rudimentary knowledge of programming in general and C++ in particular.

There are many commercial implementations of C++, but in order to promote a wide and unfettered spread of Lsd we suggest using GCC, the GNU C Compiler (that includes C++). The GNU compiler is not only freely distributable (e.g. as Cygnus for MS Windows) but it is also an integrated part of practically all Linux and Unix systems. An additional advantage of such a common choice is that the linking of the different elements of an Lsd model (the model in a narrow sense, the Lsd tools, the graphical user interface) can be done through a standardised project management tool (the GNU make application) that only requires minor modifications for the creation of new models.

Choice of graphical user interface

The second major task in the design of Lsd was the choice of a Graphical User Interface (GUI). Here the choice fell on the GUI defined by the graphical toolkit (Tk) of the Tool Command Language (Tcl). This graphical toolkit with buttons, menus, listboxes, scrollbars, etc. is very popular since it defines a simple way of programming with windows and since Tcl/Tk can in a simple way be embedded in C++ programs. It is a freely available open-source system, but contrary to the GNU GPL the licensing conditions are so that it can be freely modified and included closed-source software as well as open-source software (the GNU project has provided alternatives, but they are less wide-spread than Tcl/Tk). As long as Lsd developers does not want to make a change of the basic Lsd system but just want to make models, then they can leave the problems of the GUI to Tcl/Tk and Lsd. Their only task is to make sure that they have a copy of Tcl/Tk on their computer system.

Choice of distribution format of Lsd

The third issue about the design of Lsd was how Lsd models are supposed to be distributed. As indicated above a full Lsd system includes the GNU C Compiler, the Tcl/Tk interface toolkit, the C++ files that defines the functioning of Lsd, and at least one Lsd model. This system is distributed as Internet downloads of self-installing files and on CDs. Given that the receiver has installed the other elements of a full Lsd system, a new or modified Lsd model is distributed as a (compressed) directory with several files. The directory should be clearly named, and if a model is changed the directory should be given a new name or a new version number. The directory will be placed directly in the Lsd main directory. The model directory should include

the C++ source file that specifies the equations of the simulation model by applying the Lsd rules
the Lsd file that that specifies the structure of the model and its initial values
a makefile that links the different components needed for compiling the fully functional Lsd model
optionally, a compiled version of the model that is ready to run as a standalone application (but the application is using 1 and 2, and thus presupposes an open-source approach)
an HTML documentation of the model
further documentation of the model (optional)

Among the elements of a model directory the documentation is the least well-defined and the part that is most likely to be pushed aside. Therefore, it is important to remember that a model without documentation is just an arbitrary software artefact and not a part of evolutionary economics or other social science areas. A fairly simple model is very hard to decipher-even by its author after a period of a few months. The best documentation can undoubtedly be written after the completion of the project but it is a well-known fact than it is also a difficult and potentially boring task that is likely to be dropped. Therefore, we suggest that the documentation is written in parallel with the development work:

Initially, a text document should be written about the purpose and the main structure of the model.
Then the model will be developed as a set of Lsd equations - one for each variable. During the writing of the equations comments should be inserted into the C++ program, and any change in an equation immediately be reflected in the comments.
Finally, a short text document should be written about the default set-up of parameters and initial values, and on the results that have been obtained with the model.

Given these files, Lsd can automatically generate an HTML document with purpose, model structure, comments on initial values, and all the equations and their related comments (in different colours). The document has hyperlinks so that the logic of the model can easily be followed in a web browser.

The suggested method is obviously only a partial solution to the difficult problem of documentation. However, the fact that even a naive user can easily generate an automatic model report (that may have been forgotten by the developer) should put a certain pressure on Lsd developers. The possibility of adding the documentation to articles submitted to journals or to other requests for information about the model may also serve to improve the quality of documentation. The potential use of the reports in different kinds of advanced university teaching is yet another reason for making good documentation according to the suggested method. This method simply work, although it is admittedly crude and does not live up to all the demands of Donald Knuth's great idea of "Literate Programming". However, a little attention to e.g. the sequence in which the equations are presented (they can have any sequence in an Lsd C++ program) might increase the readability of the report. But in the end there may be a need for a separately written documentation of the model and the simulations. This document (which can easily reach the size of a book!) should be well structured and as short as possible to make revisions as easy as possible.

General issues on closed and open source software

See the note on the Lsd between the closed-source and open-source software cultures.

Lsd is a system for developing and compiling simulation models as stand-alone application as well as a system for exploring model applications without any knowledge of programming. Lsd is developed and maintained by Marco Valente. The ordinary Lsd web site includes manuals and downloads. The present web pages includes additional Lsd-related materials and downloads. It is not necessarily in sync with the latest Lsd version.

Maintained by Esben Sloth Andersen, email: esa@business.aau.dk.
Revision: 09 August 2004, 13:35.