LSD Manual
The manual is composed of a collection of web pages explaining all aspects of LSD.
1. Introduction to what is LSD and why should I use it.
2. Installation of LSD in any computer.
3. LSD Model Manager (LMM), the program used to develop and manage LSD models.
4. LSD Browser, the control center of LSD to run, edit or create model configurations:
a. Menu File
b. Menu Model
c. Menu Data
d. Menu Run
e. Menu Help
5. LSD Analysis of Results module, used to analyze and export simulation data.
6. LSD debugger, a tool to observe and change the model state during the simulation runs.
7. LSD Web Interface, a HTML web server interface to LSD models in any device.
8. LSD new features and change log, showing what is new in the latest LSD updates.
9. Other useful documents:
a. Quick help reference, with brief definitions, how-to’s, and fixes to common problems.
b. Windows visual guide to the main windows used by LSD for quick reference and help.
c. Model glossary with definitions for the terms related to LSD model elements.
d. FAQ’s (frequently asked questions) about LSD.
e. Guide to the LSD macro language used to write the models.
f. Reference to the (deprecated) LSD function language for dealing with old models.
g. Tutorials on the use of LSD for newcomers:
ii. Using an existing LSD model
LSD (Laboratory for Simulation Development) is a powerful language and platform for the creation and execution of simulation models. LSD has been conceived and developed in order to automatically manage all the technical elements required to run a simulation program. Yet, the modeler still enjoys great freedom to implement whatever computational model she desires, since the LSD core is, technically speaking, a pure C++ API (application programmer interface). This way, LSD provides the benefits of C++ (flexibility, speed, reliability, portability) while retaining the simplicity and productivity of an integrated development environment (IDE).
A LSD model is composed by its computational content, the equations, and by the model configuration. A developing environment (LSD Model Manager, LMM) permits to write the equations of the model in an easy way, expressing them like standard difference equations using a simplified macro language (a more advanced C++ interface is also available). Using LMM the equations are compiled and automatically embedded in a standalone native program, together with the required LSD libraries. The resulting LSD model program allows the definition of the model configuration and the running of the simulation using an easy-to-use graphical user interface (GUI). This way, the entire model development cycle can be managed from the LSD’s GUI, from the equation design and coding to the definition of the parameter and initial values and the presentation of the results.
Modelers and users of LSD models need to concentrate exclusively on the model, avoiding dealing with technical aspects of programming not related to the actual model. For example, a simple menu command in LMM creates a new model, and another compiles the equations, checks for errors and runs the LSD program. LSD models are endowed with advanced controls, catching errors whenever they occur and providing information on how to fix them.
Users of existing LSD models can load pre-packaged configurations of the model (e.g., initial values, number of steps) and reproduce the simulation, as suggested by the model author, without requiring any programming knowledge. New configurations are created with extremely simple and intuitive interfaces, so that even non-technical users can make use of simulation models.
LSD is particularly suited to implement agent-based models, given its embedded multi-layered, object-oriented nature. However, at its very core, LSD is nothing else than a pure, high-efficiency C++ parallel scheduling engine. However, with the added layer of graphical interfaces, any computational structure can be implemented in LSD with ease.
A model is composed by chunks of basic, macro-driven C++ code representing the (normally simple) difference equations of the model. Modelers define the equations of the model and the initial required data using simple and intuitive graphical interfaces. At the run time LSD automatically arranges the pieces of code in the correct sequence and collects the results, signaling possible inconsistencies.
A crucial characteristic of a LSD model is their inherently modularity. You can (and should) implement one piece (equation) at a time, test it, and then extend the model with a new part. LSD also automatically provides all the documentation concerning the model (e.g., which equation uses which parameter), so that even very complex models can be easily reviewed without one getting lost in the middle of messy code.
LSD appeals to novel programmers because it facilitates a gradual, trial-and-error learning process to modelling, signaling errors and suggesting solutions. However, LSD is also useful for experienced programmers because the language does not pose any limitation to the models it can implement while the platform significantly facilitates the management of complex models.
An extensive documentation covers every aspect of LSD, with tutorials, explanations of the interfaces and hints on (macro) programming.
A LSD model is simple to write, to use and it is as fast and capable as any (well-designed) pure C++ program. LSD logical organization differentiates between the model computational content and its numerical configuration values. The former is a subject for modelers, who are requested a minimum of computer-programming skills. The latter can be accessed and modified by any user, given the simple interfaces and the automatic documentation functions provided by LSD.
One key advantage of LSD is that it significantly reduces the amount of code modelers are requested to write and test for producing an operating model. When the model is ready, users of the model have a huge set of interfaces available for dealing with the model (e.g., running simulations, changing initial data, observing the results, etc.). These interfaces are created without any intervention from the modeler and permit the thorough exploration of a model even by users with scarce computer experience.
A very important aspect of LSD is that it provides a complete documentation set for each model, including a “playground” web interface. This is important for the modeler, since he can easily control the effects of a modification even in large and complex models. But this is even more important for the users of the model, since the supplied tools provide a complete and informative way to understand the very functioning of the model.
Although LSD offers several tools to facilitate the writing, testing and usage of simulation models, it does not limit at all the scope of the models that can be implemented. In fact, all LSD does is to wrap C++ code with “smart” interfaces and libraries. Therefore, expert users can still include in a LSD model whatever C++ code and libraries they like. This ensures that LSD models are extremely fast to run, as any (well-designed) C++ model, while offering a much faster development cycle and milder learning curve steepness.
The cost of directly using C++ in developing simulation models is the requirement of quite advanced tools, substantial programming experience and, most of all, a lot of time. By using the LSD integrated development environment, modelers can create models by writing only the code required for the equations of the model, which usually represent a modest share of the required programming for a full-blown C++ simulation program.
Another important feature of LSD is favoring gradual model development, limiting the scope for errors. The typical cycle to build a LSD model is the following:
1. Create a model with one (or a few) variable(s) while keeping the all the rest constant (parameters)
2. Write the equation(s) for the initial variable(s)
3. Test the model results and fix the errors
4. Transform one parameter into a variable (or add a new variable)
5. Write the equation code for the new variable
6. Go back to item 3 until all the required variables/equations are defined
This approach is possible in LSD because it is extremely easy to modify a model adding extra elements (or changing existing ones). This is not typically the case for pure code written by less-experienced programmers. Moreover, the LSD interface provides many powerful ways to explore the operation of the model (e.g., step by step running, conditional breaks, debugging, modification of values during the simulation, etc.).
LSD is available to the three desktop computer platforms: Windows, Linux and macOS. Any relatively recent configuration is supported. The LSD IDE does not have any special requirement in terms of memory or CPU capabilities. However, large models may require substantial amounts of memory and may demand fast and/or multiple-core CPUs to be processed in reasonable time.
LSD is distributed as a single compressed (zip) file which can be installed in any platform. It contains binaries and code compatible with the three supported platforms. Installation is done by simply decompressing the full directory structure contained in the zip file into the user’s home folder (~/) in Linux and macOS or the root folder of any hard disk (e.g., C:\) in Windows.
The standard installation of LSD includes:
· The LMM executable
· The LSD source code
· Several LSD example models
· The manuals for LSD
· Platform-specific utilities
· Basic pre-requisite software (Windows 32-bit only)
Detailed installation instructions for each platform are available in the Readme.txt file contained in the zip file. Please refer to it after decompressing LSD directory structure in the appropriate location. Also, there are some common software pre-requisites for the installation of LSD in all platforms (except for the basic operation in Windows 32-bit mode). The details are available in the Readme.txt file, please check them before trying to use LSD.
LSD installation is composed of a main LSD directory (for instance, at C:\Lsd-X.Y in Windows or ~/Lsd-X.Y in Linux/macOS, X and Y representing the major and minor version numbers) and several subdirectories. The table below details the main contents of each one.
|
|
Directory |
Content |
|
|
Lsd-X.Y |
LMM program and LSD command line utilities for all systems, and other support files (Readme.txt, installation scripts, LMM make files, Windows launch batches). |
|
|
Lsd-X.Y/src |
LSD source code and build files. This directory and its content should never be removed. Changes to LSD code should be done only by experienced C++ and Tcl/Tk programmers. |
|
|
Lsd-X.Y/R |
R libraries and source code for the LSD-specific packages. The libraries are also available in CRAN (the standard R repository) and do not have to be loaded from here. |
|
|
Lsd-X.Y/gnu |
Used by Windows configurations only. It contains an old (but small) version of the C++ compiler, linker, libraries, headers, and other files required to LSD compilation under Windows 32-bits. It also includes some utilities, used by all versions of Windows configurations. |
|
|
LsdX.Y/gnu64 |
Used by Windows 64-bit configurations only. It contains the Tcl/Tk libraries and headers required to LSD compilation under Windows 64-bit. It also includes some Windows 64-bit utilities, like make and GDB. |
|
|
Lsd-X.Y/LMM.app |
Used by macOS only. It maps in macOS as the LMM program. |
|
|
Lsd-X.Y/Manual |
Manual pages for using LSD and LMM plus several additional document files (see LSD_documentation.html for the full list). |
|
|
Lsd-X.Y/Example |
A set of example LSD models. Each model is contained in a subdirectory, located in a subdirectory tree organized according to groups of related models. |
|
|
Lsd-X.Y/Work |
The default user working directory. New models and groups created by the user are located in (home) subdirectories located here. |
|
|
Lsd-X.Y/lwi |
The LSD Web Interface web server template directory. This subdirectory tree must be copied to the appropriate web server directory and configured before use, see the manual. |