Topic
Topic
It should therefore be clear the difference between Lsd and LMM: the former is a language, embodied in the Lsd model programs, while LMM is the environment available for modellers to create and manage easily a set of Lsd models.
A Lsd model (a model, hereafter) is a single program whose source code (all written in C++) is composed by two separate parts: one is common to every model, the Lsd system code, and another specific to each model, the equation file. When a model is compiled (i.e. system code and equations' code is translated in an executable program) the users che exploit the model interfaces to modify any numerical specification of the simulation, but cannot modify the actual functional form of the equations of the model. To change the equations users need to re-compile the model, that is, to edit the equations' code and re-create a new Lsd model program emboding the new equations.
The steps for compiling a model, editing the equations, re-compile a new model (and possibly fix the programming errors) require to access several files and issue specific commands to the operative system. LMM users do not need to worry for these: LMM allows to access all the relevant files through standard menus, as well as offering the commands required. Morever, when creating a new model LMM asks the user the basic information concerning the new model and then creates all the required components. A new model (which must be always placed in a dedicated directory) includes the following file:
Besides the files strictly required for running simulation exercises Lsd models produce also another type of files: the Model Reports. These are files meant to describe in detail and in an easily understandable way how a model is implemented. The Model Reports shows the code for each equation, as well as the comments introduced by the model author, and the values used for the initialization. All of this is automatically organized in a hypertextual form and saved in a standard HTML file that users of the Lsd model program can access from the usual menu Help. This document describes how to use LMM in order to work on a model up to the definition of the equaitons' code and the launch of the Lsd model program emboding this code. The Lsd manual describes how to use the Lsd interfaces for defining the model configurations and running simulation exercies.
The Lsd system is designed to work identically under the Windows and
Unix operative systems without requiring any additional package (for
the
installation on a Mac OS X see here). There are two
distributions containing identical Lsd system code; the Windows
distribution
includes also programs and libraries normally present on any Unix
systems.
Both distributions are composed by one single compressed file. To
install
the system read the following instructions
The distribution includes:
| Directory | Content |
| LsdX.Y | LMM program and other distribution files (e.g. Readme.txt, GPL.txt, compilation batch files). |
| LsdX.Y\src | System source code. This directory and its content should never be removed. Updates of Lsd will need to be placed here |
| LsdX.Y\Manual | Manual pages for using Lsd and LMM |
| LsdX.Y\gnu (Windows distribution only) | The compiler, linker, libraries, headers, and any other file
required
to compile C++ programs and run them under Windows. This part is taken
from the Cygnus port of the GNU project under Windows environment
(ditributed
under the GNU General Public License). See www.cygnu.com.
Under Unix environment LMM compiles the Lsd model programs exploiting the GNU gcc compiler and the Tcl/Tk 8.3 libraries, normally installed on every Unix systems. |
| LsdX.Y\ExampleModels
(and any other directory) |
The distribution includes a set of example models that can be loaded and run using LMM. Each model is contained in a directory, possibly located in a directory tree organized according to groups of related models. Users can generate new groups of models according to their requirements using the Model Browser in LMM. |
The LMM editor
The LMM window is formed by a header bar and by a text editor. The
header bar contains the four menus (File, Edit,
Model,
Help)
and indicates: the model selected, if any; the model's version number;
the file currently loaded in the editor, and the columns and line
position
of the cursor.
The editor applies the usual rules for browsing text, selecting, deleting etc. Note that the most frequently used editing functions have also key-based shortcuts for faster access while typing, indicated along the items in the menus. Moreover, a short popup menu is activated with the right button of the mouse.
Although the editor deals with any kind of text file, when it loads
a file with extension cpp (or any extension related with C language)
are
applied different colors to facilitate the code reading. The C++
comments
(all the text included in between a /* and */ couple of characters, or
the line beginning with //) are highlighted in green. Moreover, strings
(all text included in between double quotes, excluding the \" cases)
are
written in blue.
Another binding useful for editing programming code is the automatic
tabbing. When a new line is inserted (pressing the key Return), the
editor
fills the beginning of the new line with as many spaces as in the
previous
line, facilitating the standard programming tab styles. See in Menu
Edit a set of entries also useful for C++ coding.
Menu File
This menu is pretty self-explanatory.
New Text File : create a new text document, initially labelled 'noname.txt'. When saving the document it is possible to change its name.
Open (shortcut Ctrl+o): open a new file closing the previous one (asking whether to save it, in case it is changed). Note that it is not necessary to open the files required by Lsd models since these can be accessed directly using the menu items in menu Model.
Save (shortcut Ctrl+s): save the current file with the same name used to open it. Check carefully whether you want to overwrite existing files.
Save as (shortcut Ctrl+a): save the current file asking for a new name.
Quit (shortcut Ctrl+q): Quit LMM.
System Options
For Unix systems only, the user can specify the Html browser to use
for showing the help pages and the terminal to use for the GDB
debugger.
Menu Edit
This menu deals with the editing of the file shown in the LMM editor.
Besides the usual copy/paste operation, it offers several facilities
targeted
to operate on C++ source code, and Lsd equations in particular:
Note that most of the commands can be activated using intuitive
shortcuts of the type Control+X to speed up their use.
(menu Edit) Goto Line (shortcut:
Ctrl+l):
Go to the chosen line number in the shown text. The corresponding line
is moved at the center of the window and highlighted. This function is
very useful to find error messages in compilation, since they are
referred
to by the line number.
(menu Edit) Find Text (shortcut:
Ctrl+f):
Find a text in the document shown. The search start from the current
position of the cursor downwards or upwards, depending as specified,
and
is interrupted at the first instance found. It is possible to make
either
a case sensitive or insensitive search. If the searched characters are
found, they are brought in the center of the text window and
highlighted.
Otherwise, the small entry window to insert the text remains visible
and
its content is selected for an easy replacement. The small entry window
accepts, besides the buttons Ok and Esc commands, also the equivalent
keys
Return and Escape.
(menu Edit) Find Again
(shortcut: F3):
Find again the same text as specified in the previous Find Text (and
applies the same settings). Provide a quick way to find one specific
instance
of a frequently repeated pattern.
(menu Edit) Replace (shortcut:
Ctrl+r):
Search for a text pattern and replace the text, if found. Three buttons
are available in the Replace window:
(menu Edit) Match { } (shortcut:
Ctrl+m):
Find the graph bracket matching the one close to the current insertion
cursor. It is very useful when working with C++. In fact, in complex
C++
programs the blocks of lines (for example, in the if-then-else
statements, the for and while
cycles,
etc.) are defined by { and } graph brackets. It is very easy to get
lost
in the sequences of open and close brackets, and errors due to the
absence
or redundancy of a bracket are very difficult to identify.
The function is very simple to use. If the character on the right of the insertion cursor is a {, then the function scans downward the text stopping at the } character matching the initial {, that is, skipping the couples {} found during the research. In case the character on the right of the insertion point is a }, then the scan is made backwards.
When the matching bracket is found, both the initial and the found one are highlighted, while the text shows the part of the code containing the found one. If the two brackets are pretty far apart in the text, the user may want either to focus on the initial bracket or on the just found one. Users have are alternatives after a successful search: using the arrow keys, the window immediately return showing the initial bracket. Otherwise, clicking with the mouse over the shown area, that becomes the active one and can be treated normally.
In case the search fails, meaning that the end of the text were reached before finding the matching bracket, an error sound is emitted. In case the character on the right of the insertion point is neither a } or a {, then the function does nothing.
(menu Edit) Match ( ) (shortcut:
Ctrl+p):
Same as for Match { } but applies to the
parenthesis.
(menu Edit) Insert
{ (shortcut: Ctrl+'(' ):
In some systems endowed with international settings (non USA keyboards)
it is difficult to insert the badly needed graph brackets. This items,
and specially its shortcuts, saves a lot of laborious work.
(menu Edit) Insert
} (shortcut: Ctrl+')' ):
In some systems endowed with international settings (non USA keyboards)
it is difficult to insert the badly needed graph brackets. This items,
and specially its shortcuts, saves from a lot of laborious work.
(menu Edit) Insert
Lsd
Script (Shortcur: Ctrl+i):
Insert in the insertion cursor point a frequently used Lsd script (the
equation style between C++ or Lsd macros depends on the option
chosen). This function is merely implemented to allow modellers to
quickly
include frequently used code, minimizing the number of typing mistakes.
It is possible, of course, to edit the text inserted with this
function,
as any text typed manually.
The item activates a window listing the scripts currently available
for automatic insertion (see the help page on Lsd
functions for the complete set of Lsd functions available). When a
choice is made, an interface requesting the values necessary for the
script
appears. The interfaces contain already a default value for each item
to
insert, and modellers can move from one item to the next just pressing
Return
(the usual key Escape aborts the process at any moment).
Pay attention to the highlighted letters in the list of available functions. They are also used as short-cuts pressing Control and one of the upper case letters. For example, pressing Control and 'V' the interface to insert a V(...) function is activated.
(menu Edit) Larger Font
(shortcut Ctrl+'+'): Increase the fonts used in the editor.
(menu Edit) Smaller Font (shortcut Ctrl+'-'): Decrease the fonts used in the editor.
(menu Edit) Change
Font:
Set the fonts to use in the editor.
The items in menu Model activates all the necessary functions to
create,
revise or run an existing model. Only two items are available when a
model
is not selected: Select Model or New Model. When a model is selected
then
also the other items are available, and their function (e.g. compile,
run
etc.) refer to the active model only.
Items available in menu Model:
(menu Model) Equation
Coding Style
Allows to choose between the traditional C++ form for expressing the
code in the Lsd equations, or to use the simpler macro
language. Depending on which coding style is used, LMM will provide
the corresponding Lsd script to be inserted
in
the equations, and will mutate the Help page on the
equation
coding.
Note that users can blend the two languages in the same models,
expressing
some part of the code in C++ and others in the Lsd macro.
(menu Model) Equation
Codying Style
Tell LMM to use pure C++ codying style or the simpler Lsd macro codying
style.
Lsd models implement the Variables' equations in C++, which are stored
as blocks of code in the model equations file. Besides writing the
equations
in C++, users can also use a macro language, which uses shorter
keywords
for the most common operations. It is also possible to mix in the same
model standard C++ and the macro language, although generally this may
be confusing.
Depending on this option, LMM will insert the Lsd
scripts in the chosen style. Also the Lsd
equation
help menu item will be selected according to this option.
(menu Model) Browse
Models
This functionality allows to manage the models available on your Lsd
installation. The models are organized each in one directory, and these
directories are organized in "groups" containing related models.
Users willing to experiment with one of the existing model need only
to browse the models available and choose one to work with. The system
will automatically refer to the files concerning the chosen model.
Modellers developing new model programs can use the other
functionalities
to organize properly the set of models in suitable groups (e.g. move a
finished model from the "Work" group to the "PaperXXX" group).
Using the "Lsd Models" browser windows it is possible to:
(menu Model) Run Lsd Model
Compile, if necessary, and run the Lsd model program.
The system checks that all the files necessary for the Lsd model
program
have been compiled, and then run the resulting Lsd model program (see here
the manual for the Lsd model program interfaces).
Three possible outputs are possible from this command:
The compilation messages indicate which of the two cases you are in. Compilation messages indicating only warnings are innocuous. Instead, terms like errors, failure, stop etc. indicate that the compilation failed. See in the following for information on the most frequent errors.
Frequent Compilation Errors
In case of compilation errors, the system issues a warning and presents
the compiler's error messages (the window containing the errors can be
close and re-opened with the command Show Compilation Results
in
menu Run). There are two possible sources of errors:
programming
bugs and LMM configuration errors.
Programming errors are caused by violations of the C++ grammar in the equation files (of course, a C++ legal equation code is not necessarily doing what it is expected to do, but this can be seen only at run time). Programming errors are signalled with lines like:
XXX.cpp:301 ...
meaning that in the file XXX.cpp (typically the equation file of the
model) at line 301 an error has been found (note the command Goto
Line
in menu Edit).
The possibilities of the compiler to indicate exactly where the error
is located are limited. For example, a missing semi-colon (possibly the
most frequent error) is indicated in the message as an error in the
following
line.
The compilation of the source files is sequential, so that frequently
one error on one line causes a number of (apparent) other errors in the
following lines. Fix the errors indicated in the earliest positions
(top
messages) and try to recompile without searching for the mass of
following
errors.
The nastiest errors are caused by the wrong number of open- and
close-brackets:
{ and }. The compiler fails to individuate the location of the missing
(or redundant) bracket, although it totally misread all the code,
therefore
issuing a lot of fake messages. If everything seems correct at the
lines
indicated in the error messages, test the brackets of the equation file
(starting with the very first one) using the command Match {}
in
menu Edit (see here for help on this):
each
open bracket must match with a closing one. If no matching bracket is
found,
then there is the problem.
It is impossible to write code without writing bugs, so that it is important to learn to discover them quickly. However, this is possible only if one has a reasonable idea where to start the research, and therefore it is highly recommended to write few lines and then compile. Even if the written code does not mean anything yet, at least one can clean-up the typing mistakes.
Configuration errors occur when the system does not find required libraries where expected, or they are mispelled. These errors cause messages like:
No rule to make target `XXX.cpp'
or
cannot open -ltcl8.0: No such file or directory
and, in general, messages not related to the content of the equation file. In this case the error signals that either the whole package is not configured properly, or that the model does not contain some crucial information. These errors generally occur once during the very first time the system is used, and then they never appear again. Use the commands for the System Compilation Options and Model Compilation Options in menu Model to fix the errors (see here for help on this topic).
The system allows to run many copies of the same Lsd model program. However they must all share the same equation file. This is because it is not possible to replace the files of programs currently running. Therefore, if you are using a Lsd model program for a simulation run, and then try to recompile it with a modified equation file, the system may give a message like this:
ld: cannot open output file lsd_gnu.exe: Permission denied
In this case, either close the running Lsd model program, or compile later.
(menu Model) Debug
Use the gdb debugger to follow the simulation
instruction-by-instruction.
A debugger is a program that allows other programs to run in a
controlled
environment. When a program is run in a debugger, it is possible to
observe
in detail what it does, for example interrupting its calculations and
checking
the values of its internal variables. The debugger works as if the
single
lines of code fire their commands only when explicitly directed.
Note that the gdb is a C++ debugger, which, therefore, knows nothing of Lsd equations, Objects etc., but their technical representation. gdb permits, for example, to investigate line by line the execution of an equation. However, this means that one has also to follow line-by-line a lot of non-interesting technical code. Lsd programmers may find much more useful the Lsd Debugger: it permits to follow a simulation by individual equations. When one Variable, marked to be debugged, is computed, the Lsd debugger interrupts the simulation, shows the value produced in the equation, the values of v[n] temporary values, the whole models' values, etc., permitting to understand, most of times, the cause of an error. See the Lsd Debugger help page. However, the gdb debugger is still useful in case of very hard problems.
The Lsd model program in the debugger runs as usual (slightly slower, if anything) but the user can interrupt the program at any point, check the value of any variable, make the program proceed by single steps, and a whole series of other functionality meant to help finding out misbehaviours or errors in the program.
In case of a Lsd model program, it is usually useful to focus on one equation and see the behaviour of the program while executing that code. In the following, few gdb commands are reported. They all take the form of commands to be typed at the line prompt of the gdb shell. More information can be found in the gdb manual, available on the net, or simply typing help in the gdb shell, possibly followed by a precise command.
For more information on this and other commands, use the help in
gdb (just type help and the name of the command). Moreover, in gdb
works
the command completion, so that typing, for example, "disp" and then
pressing
the tab key, the command display is automatically completed. In case of
possible ambiguity (e.g. typing only "dis" and tab) the prompt shows
the
list of alternative among which to choose (this is also a weird, but
rather
useful, way to discover new functionalities).
(menu Model) Show Equation
The entry Show Equation opens in the LMM editor the file
containing
the equations for the selected model. The equation file is a normal C++
source file, that LMM uses to create a Lsd model program. The modeller
writes in this file the code for the equations in separated blocks,
whose
order is of no importance for the actual order the Variables are
updated.
There are two possibilities to express the code for an equation: the
standard C++ expressions (see here the
manual)
or a macro language, much simpler especially
for
novel modellers.
The equation file shown in LMM should be used only for editing a model
and should not be used just for studying a model, since it is not easy
to reconstruct the functioning of a model looking at the code of the
equations
only. In fact, there is no relation between the order of the variables
blocks and their actual order of execution during a simulation run. To
browse a model's code Lsd model programs offers to far better
alternatives.
Lsd model programs contains several facilities to browse the model
structure
(i.e. Object, Variables and Parameters) and equations (see, for
example,
the
equations windows). Moreover,
the Lsd models produce HTML documents ( Model
Report), accessible directly from the Help menu of the Lsd model
programs,
that list all the elements of the model including the equations' code.
(menu Model) Show
Compilation Results
This items causes LMM to show the results from the latest compilation
in a new window. If the compilation did not issue any error the window
is empty. This option is useful whenever there are many errors in the
equation
file (see run for a discussion on the most frequent
compilation errors).
(menu Model) Show
Description
Shows the description of the model, a verbal summary of the model
content
and aims prepared as presentation of the modeller.
(menu Model)System
and
Model Compilation Options
Set the compilation options for the whole system and for the model
respectively. That is, these options are used to create the makefiles
used
to compile and link the models according to the local settings and
user's
preferences.
Creating a Lsd model program requires, besides the code, the exact
name and location of several system files. This information is not
perfectly
standard, particularly comparing Windows and Unix environment. These
two
commands permit to fix problems due to non-standars systems, or to
easily
compile a model developed under a different operative system.
Generally,
the default values proposed should suit most cases, and are applied by
the buttons for the Windows and Linux OS's . However, in the following
I list the details of how Lsd model programs are created (non-expert
users
can ignore this).
Lsd is compiled with a standard C++ GNU compiler. It is assumed that most Unix system have already installed this. The Windows version comes with an extract of the CYGWIN package, a port of the GNU project under Win32 by Cygnus (released under the GNU GPL). The Windows installation stores in the directory LsdXXX/src all the necessary stuff. In this way, identical code is compiled seamlessly under different OS's, e.g., both under Linux and Windows 2000.
The makefile's for the models are created by three different parts:
- Model specific settings, valid for a single model (stored in the
model_options.txt in each model directory)
- System-wide settings, valid for all the models (stored in the file
system_options.txt in the Lsd root directory)
- The body of a makefile used by all models (stored in the file
makefile_base.txt
in the Lsd root directory)
When a makefile must be created (e.g creating a new model or changing the compilation options), the system merge the three parts above. Using the system and model compilation option commands users can modify the first and second part indicated above, since the body of the makefile does not neet any customization. The required settings are indicated in the following tables, along with the default values.
Model Options
| Variables | Default | Comments |
| TARGET= | lsd_gnu | The name of the Lsd model program (Windows version attach the .exe extension automatically). |
| FUN= | fun_XXX | Name of the equation file for model XXX, that is the C++ source file containing the code for the model's equations. The extension .cpp must not be included. When creating a model the system by default assigns the name fun_XXX.cpp to this file, where XXX is the name of the directory where to store the model files. |
| SWITCH_CC= | -g | Any optional switch to the compiler can be assigned to this variable. The -g option includes in the code the debugging information, used by the gdb debugger. Options like -O, -O1, -O2, -O3 etc generate faster code. See the manual for your gcc compiler for further, system-specific optimization options |
System Options
| Variables | Windows | Linux | Comments |
| TCL_VERSION= | 83 | 8.3 | Version numbering attached to the Tcl library. On some
systems there
is no need for any number, or it may be 82, or 8.2. In case of linker
errors
like:
cannot open -ltcl8.3: No such file or directory try a different version number, and with or without separating
dot. |
| TK_VERSION= | 83 | 8.3 | Version numbering attached to the Tk library. On some systems
there
is no need for any number, or it may be 82, or 8.2. In case of linker
errors
like:
cannot open -ltk8.3: No such file or directory try a different version number, and with or without separating dot. |
| LSDROOT | C:/Lsd5.1 | /home/myusername/Lsd51 | This is the root of the Lsd system directory |
| DUMMY= | -Wl,--subsystem,windows | (empty) | The CYGWIN compiler under Windows accepts this options in order to compile graphical programs without the console window. |
| PATH_TCL_LIB= | ../gnu/lib | . | Path (relative to a model directory) of the Tcl library. |
| PATH_TK_LIB= | ../gnu/lib | . | Path (relative to a model directory) of the Tk library. |
| PATH_TK_HEADER= | ../gnu/include | (empty) | Path (relative to a model directory) of the Tk header file. |
| PATH_TCL_HEADER= | ../gnu/include | (empty) | Path (relative to a model directory) of the Tcl header file. |
| PATH_LIB= | ../gnu/lib | . | Path (relative to a model directory) of the standard C++ libraries. |
| INCLUDE_LIB= | -I../gnu/include | (empty) | Path (relative to a model directory) of the standard header directory. |
| SRC= | src | src | Directory containing the Lsd source code. You will probably never need to use this option. It serves in order to test different versions of Lsd. In this latter case, insert here the directory you want to use to compile a new model |
| EXTRA_PAR= | -lz |
-lz | Insert here any extra parameter to be used in the
compilation, for
example some specific libraries needed on your system. By default it is
used the zlib library to generate zipped result files. If your system
does not include this library, leaves empty this variable (e.g.
EXTRA_PAR= ) and remove the LIBZ macro in the beginning of the code in
the file src\analysis.cpp. |
| SSWITCH_CC= | -O2 |
-O2 |
Any optional switch to the
compiler can be assigned to this variable.
The -g option includes in the code the debugging information, used by
the
gdb debugger. Options like -O, -O1, -O2, -O3 etc generate faster code.
See the manual for your gcc compiler for further, system-specific
optimization options. |
The Help menu contains five entry points to the Lsd manual pages (see the Introduction to Lsd help manual on using Lsd manual):
The manual is written as HTML pages (like web documents) that users are supposed to keep open in a Netscape (or any web browser like Internet Explorer) while working with Lsd. The manual pages are endowed with links that permit to "jump" to related topics. Usually, using the "back" command of Netscape permits to find any help required. If users get lost in a pattern of subsequent "jumps", the best way is to re-start from the first manual page used.
The manual contains at least one page for each operation. For LMM and Lsd the help pages are organized according to the menus where the commands are placed. Each help page begins with the picture of the interface, and the list of the commands available (see, for example, the help on menu Data, and then use the button "back" to return here). Any Lsd help page has a link to the Table of Contents listing the whole content of the manual, and also links to other potentially relevant topics, in the very first line on the top of the page.
For the very early users the best way is to follow the three tutorials listed in the LMM help menu. For a manual page on a Lsd interface, the usual starting page for using Lsd is the Table of Contents, offering links to the main Lsd windows and other useful topics. A short list of help on frequently used operations is contained in the Quick Help page.
Lsd Model Creation
This paragraph contains some advice on the strategy for creating a
Lsd model. Before that, however, readers are strongly recommended to
use
some of the existing example Lsd models so to be familiar with the
terms
used. On this, follow the two tutorials for early users of Lsd:
This paragraph gives the logical steps to be followed when creating a model. For detailed instructions on the technical information required to write Lsd models, see the Tutorial 3 - Writing Lsd models, better after having read this paragraph.
To create a Lsd simulation model means to create a C++ program which can execute simulations when loaded with a model configuration. The LMM environment and the Lsd interaces attached to a model reduce to the very minimum the technical difficulty to build the model. However, Lsd requires the modeller to include all the specification of the model, offering no "black box" producing fancy results from a magic wand. In part, this is the price to pay for having efficient programs, but, at the same time, it is also part of the value added in using the simulation methodology. Modellers should not think of building simulation programs only as a technical job, meant to reproduce in C++ what it is crystal clear in their mind. Rather, the very process of translating abstract concepts in a computer language, with its intrisic dynamic nature and its unavoidable logic consistency, forces to organize the modeller's intuition in a very particular and disciplined way. It is like a testing bed where one can see whether all pieces of a puzzle, developed reasoning on a problem, do hold together after all; if some part of the puzzle is missing; or one piece initially considered relevant is actually part of another puzzle. As result, even when only a small portion of a model is implemented, usually the modeller has increased his/her knowledge of the subject, just because the language "shows" the errors and incompleteness of the early intuitions. For this reason, it is strongly recommended that researchers do not delegate code writing to others, technically skilled but often unaware of the scientific bases of the model. Basically, Lsd has been conceived for helping non-programmer social scientists in doing their homework when use simulations.
Before starting to create a simulation model, one should obviously have in mind what kind of results it is possible to obtain. Obviously, a simulation model produces just numbers, and cannot be other way. However, in most cases, especially in social sciences and concerning agent based models, the knowledge that a model is able to provide is not limited to the plots of the series produced during one or more simulation runs. It comes from the in-depth understanding of what happens within the model. Using a rather fashionable, but often unclear, terminology, the modeller hunts for the "emergent properties" developing in the virtual histories developed during simulation runs. Whatever this may mean, it does not involve only the production of numbers, but also the understanding of why those numbers were produced. And, for the results be of any use, it is also necessary that the understanding can be passed to others, allowing non technical people to replicate, and and therefore share, the knwoledge acquired with the simulation. This implies that the modeller must not only build a simulation program, but also understand how it works in detail, and to document it properly so that others can use it. Lsd offers all the necessary tools for doing this.
In the following, the typical steps for developing models are
listed.
As mentioned earlier, the comments below consider only the logical
steps.
Refer to the Tutorial 3 for the
technical
instructions on their implementation.
The use of simulation models suffers from an unavoidable contradiction:
for the model to be of interest, it should be complex such that to
include
all the elements of interest in a given context. But the value of the
model
lies in the possibility to understand how the model works, which is
more
and more difficult while the model gets complicated. Using Lsd "breaks"
this contradiction by allowing the gradual creation of a model.
Although
all the elements of a model depend on each other, the model author can
exploit the Lsd properties to develop one small portion of the model,
test
it, and expand the model. This strategy provides robust models, with no
errors, and can bring to the construction of extremely complex models.
As an example of different styles, the code of the equation for the
Variable X in the traditional C++ style is:
if(!strcmp(label,"X"))
{
//any code here
res=a_value;
goto end;
}
while in the macro form is:
EQUATION("X")
//any code here
RESULT(a_value)
As another example, to request a value of a Variable (or Parameter)
called X, using the traditional expression, you should write:
p->cal("X",0);
In the Lsd macro language it becomes:
V("X");
Therefore, the equation for a Variable computed as the sum of two other Variables in the macro style is:
EQUATION("X")
//any code here
RESULT( V("Y") + V("Z") )
Given that it is possible to mix th two expressions, it is also possible to write:
EQUATION("X")
//any code here
RESULT( V("Y") + p->cal("Z",0) )
Either in the case the user decides to use the pure C++ form or the macro equivalent, LMM provides shortcuts to insert in the equation file the most commonly used expressions. A switch allows users to choose which style of coding is preferred. The complete series of macros available to express Lsd equations is listed here, while the equivalent C++ expressions can be found here.
As LSD was designed to work on UNIX, why couldn’t we use it under
MAC
OSX? This little help file is here to do just what it should: show you
how to install LSD on OSX. Now one would ask: if this application is
written
to run on a UNIX system, why can’t I run it on MAC OSX? WellŠ Part of
an
answer lies here:
http://developer.apple.com/macosx/architecture
As you see or might know, the roots of Mac OS X lie on Darwin. And
on the other end, we have that nice Aqua interface. The problem is that
LSD can run on Darwin, but not using Aqua. So what we need to do is
install
first another window management "system", one that would be compatible
with both Aqua and LSD. And of course, we need to implement a few
libraries
that are not installed as standard on Mac OSX. And of course, all
software
that we will use will be open-source.
1 Let’s begin
Make sure that you have admin and/or root access on the Macintosh you
want to work on:
To enable the root user, open netInfo Manager, and select menu
domain/security/autentification.
You will be prompted for an admin right login window.
Once that is filled, if you go again in the domain/security menu,
you’ll
see a new option: "enable root user". Select it. You then will be
prompted for a root
password.
One word about that password: never, EVER forget it. Trust me. And
don’t use the root account for everyday’s use.
1.1 System requirements:
- A computer (Macintosh, preferably) - MAC OS X (min 10.1.x) with an
administrative privileged account - The latest MAC OS X Developer Tools
(free
download at http://connect.apple.com ) - Some basic knowledge of the
terminal - A good Internet connection - A good amount of free disk
space
1.2 - LSD 5 download
Start by downloading the LSD 5.0 Unix Zip archive (3.2 MB) from
http://www.business.auc.dk/lsd
Stuffit Expander should UnZip automatically a LSD
folder on your Desktop. Check the ReadMe.txt in the folder for any
new updates.
If you like working in the OSX’s GUI, first be sure to install
TinkerTool,
from http://www.bresink.de/osx/TinkerTool2.html and to check in this
System
Preference module the "show hidden files and system files" box under
the Finder tab. Very useful to see the hidden directories we will work
with.
1.3 GCC download
We will need the GNU Compiler Collection to use LSD. Some part of what
is need has been installed by the developer tools installation, but we
need a bit
more.
So connect to: http://gcc.gnu.org/gcc-3.0 And download the binaries
from the mirror server the closer to your place.
UPDATE: GCC 3 is now part of the latest deveoper tools. How-to is to
be modified.
1.4 GDB download
To get the GNU Project Debugger, connect to this site:
http://sources.redhat.com/gdb
And again, select the archive the closer to you.
The choice is now yours. In part 2, we suppose you have a fast
Internet
access on your computer. We will use Fink, an excellent package
management
tool
greatly inspired by DEBIAN to easily install Xfree86 (an X Window
server)
and the TCL/TK libs.
*-*-*-*-*-*-*-*
2.1 Fink install
What is Fink? As stated on their website (http://fink.sourceforge.net),
the Fink project is a modification of UNIX software so that they can
compile
and run
on Darwin. This is the tool we’ll use to install the different
libraries
needed to run LSD.
So. Start by downloading the fink install image here: http://prdownloads.sourceforge.net/fink/fink-0.4.0-installer.dmg
Run the installation package that is on the newly mounted image.
Open a new Terminal window, and type:
pico .cshrc
source /sw/bin.csh (press enter here)
Press control-o, enter and control-x.
Close the terminal window. Re-launch one. Fink should be set up and
working. To test it, type sudo apt-get update in your terminal. Then,
type
sudo fink
list and after a while, fink should show you a list of packages to
install.
2.2 - Xfree86 installation
To install Xfree, a X Window integration in Mac OSX, we will use the
newly installed app. In your terminal type :
sudo apt-get install xfree86-base
The downloaded file will automatically compile and install itslef.
Once that process is over, type in your terminal window:
sudo apt-get install xfree86-rootless
Done now for X Windows! Check in your application folder: there should
be a new app, Xdarwin. Open it, select the rootless mode, and after a
few
minutes, a few apps should load in the new X Window System we installed
Note: it can take some time to load at first Beware, as the
keyboard layout
is in the QWERTY format on the X Terminal. To change that format, in
Xdarwin, go to the preferences pane, in start up, select another
keyboard
file in the
list.
2.3 Tcl/TK installation
Again in your terminal, type :
sudo fink install tcltk
That’s it !
*-*-*-*-*-*-*-*
3.1 - Xfree Installation
The version of the X Windows system will be Xfree86 4.1 You can grab
the binaries here:
ftp://ftp.xfree86.org/pub/Xfree86/4.2.0/binaries/Darwin-ppc-5.x/ (be
sure to check their README file). Download all the files in here, and
simply
put them
all in a folder on your desktop (here called xfree for the example).
After, use the terminal application to install it by typing:
cd ~/Desktop/xfree sudo sh Xinstall.sh
The first command indicates that you want to go to the xfree folder
on your desktop, whereas the second one will prompt you for your root
password
(check the first part for help about that) and start the installation.
Install all of the modules by answering "yes" to the different
questions
that you will be asked, apart from the last one, about creating a link
to the restart
utility, that should be answered "no".
Xfree86 is now installed. But one more thing remains to be settled
about it: make the X Window run "rootless", or otherwise, it would run
full screen.
To make it run rootless, download this patch:
http://prdownloads.sourceforge.net/xonx/Xdarwin1.0.6.1.tgz
and then use your terminal to type:
cd / sudo tar zxvf ~/Desktop/Xdarwin1.0.0.6.1.tgz cd ~/Library mkdir
init cd init mkdir tcsh cd tcsh pico path
(in pico, then type:)
set path =($path /usr/X11R6/bin)
(save by typing control-o then enter, and quit using the control-x
and enter commands, then type:)
cp /usr/X11R6/lib/X11/xinit/xinitrc ~/.xinitrc
Done now for X Windows! Check in your application folder: there should
be a new app, Xdarwin. Open it, select the rootless mode, and after a
few
minutes, a few apps should load in the new X Window System we installed
Note: it can take some time to load at first Beware, as the
keyboard layout
is in the QWERTY format on the X Terminal. To change that format, in
Xdarwin, go to the preferences pane, in start up, select another
keyboard
file in the
list.
3.2: TCL/TK installation
Start by grabbing those two tar.gz files:
http://dev.scriptics.com/download/tcl/tcl8_3/tk8.3.3.tar.gz
and
http://dev.scriptics.com/download/tcl/tcl8_3/tcl8.3.3.tar.gz
unpack the Tcl files with the command:
# tar xzf tcl8.3.3.tar.gz
cd to the directory tcl8.3.3/unix and type the three commands:
# ./configure
# ./make
# ./make install
repeat the same for the Tk files