Lsd Model Manager - LMM 


 Topics

 

Introduction
Lsd Models Manager (LMM) is an integrated environment used to generate, modify and access one or more Lsd models. It consists of a normal text editor (particularly suited for dealing with C++ source code), plus a series of commands to manage Lsd model programs. If LMM is loaded with a model, then its Lsd-related functionalities apply to that model. Otherwise, with no model loaded, LMM is just a simple editor.
Starting LMM you are shown a window with three options:


  • Browse existing Lsd modelsl. Browse all the models installed to select one to work on. This option allows also to create, move or delete models.
  • Open a text file. The system does not load any model, but offers the possibility to use the LMM editor on an existing file.
  • Create a new text file. The system does not load any model, and the editor contains an empty text file. It is possible to name the file when saving.


 Both LMM and Lsd are extensively documented by help pages in HTML format. This document covers the use of LMM; it is roughly organized for menu entries, and each section is referred to in the buttons Help in any interfaces. For help on the use of a Lsd model refer to the Lsd manual, or look at the Help on Help section.


LMM Installation

The code for the Lsd system is identical under any platform, since it uses the same C++ compiler and libraries. Consequently, all the distributions of Lsd can be used on any system. 

The installation consists unpacking the files and run LMM. Once this is successfully done, LMM is used to generate run and generate Lsd models.

There are three different packaging facilitating the installation procedures on MS Windows, Linux and Mac systems. Details on the installation are available in the README.txt file

 

A 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 MinGW port of the GNU project under Windows environment (ditributed under the GNU General Public License). See www.mingw.org.
Under Unix environment LMM compiles the Lsd model programs exploiting the GNU gcc compiler and the Tcl/Tk 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.
LsdX.Y\WorkWorking directory, where the user will place the newly generated models.

 


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
The user can specify the following options: consolle terminal; HTML browser; font and exact name of the wish,. The terminal is the command to be used when launching the GDB debugger. The browser is used to show the helpl pages. The font is the name of the fonts to be used in LMM as text. Wish is used to run interpreted scripts in Tcl/Tk languages, mainly used by TkDiff (see TkDiff and Compare Models in menu Edit). If these functionalities do not work then open a terminal in your system and find out how wish is called (e.g. wish8.4). Clicking on the default button provides the most common options for the operative system used.


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:

The Replace window accepts as keys the button Return for Search and Esc as Close.

(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) Wrap Text/No Wrap (shortcut Ctrl+'w'):
The text window can be set either to wrap the text so to not spill over the right side. At the start, the default is no wrapping, so that the end part of long lines can be read only scrolling the text on the right. Choosing this item the setting alternate between wrapping and not wrapping the text. The wrapping does not affect the saved file, but only the appearence.

(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.  



(menu Edit) Indent and Deindent Selection (shortcut Ctrl+'>' and Ctrl+'<'): Add or remove spaces in the beginning of the selected line(s)


(menu Edit) TkDiff a WYSWYG interface for "diff" based on Tk, written by John M. Klassa (see its About ...). It shows differences between two files, useful to compare equations' code differences in two versions of the same model.


(menu Edit) Compare models. This interface allows to run TkDiff using selecting automatically the equation files of two model. The interface shows the complete list of the models present in the Lsd distribution. Users need to select one model and then click on the "Insertt" button on the right hand of the windows. TkDiff will show the differences between the equation files of the two models.

 

Menu Model

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:

When necessary, the above functions will request the relevant information in self-explaining forms. In all cases pressing Escape will abort the current operation.

(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:

Both in case of error or warning a new window gives the details of the messages from the compilation process. The warning message is issued when the compilation did issue messages, but a copy of the Lsd model program exists. This may happen in radically different cases:
1) the compilation problems did not prevent a successful creation of the Lsd model program, which is therefore updated with the latest equations' code;
2) the compilation failed, but an old copy of the Lsd model program (with old equations) exists. In this case, the copy does not contain the latest (faulty) equations' code. This happens when a previous version of the Lsd model program had been successfully compiled (and is still present on the disk).

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 re-compile.


(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 Makefile
This item shows the content of the "makefile". This is a simple text file that contains the commands necessary to build a model program using the Lsd source code (both the general system code and the model specific equation' code) with the compiler.
The makefile's for the models are always created merging three files: model_options.txt, system_options.txt and makefile_base.txt. The first is peculiar to one model, while the others are common to all models (located in the Lsd root).
Any time the makefile is required (e.g. to compile a model before running it) this is created again. Therefore, a direct change to the makefile does not have any effect. To modify compilation options see System and Model Compilation Options.

(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) Model Info
Shows summary information on the model:
- the model name (editable);
- the version number (editable);
- the date of creation;
- the date of the latest modification of the equations;
- the directory containig the model files.

(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

(the version of Tcl/Tk library needs to be  changed according to the installed one)
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.
EXT=.exe(empty)


Generate NO WINDOW makefile
This option generates a packaged version of the LSD model, including the LSD source code and the model, to be compiled without using the graphical interfaces. This version of LSD requires only a GCC compiler to run a simulation, so that it can be run on systems not endowed with TCL/TK.
Since there are no interfaces, the NO WINDOW version needs a configuration file (.lsd) already prepared. The simulation results will be automatically stored in files, to be loaded in a normal version of LSD for analysis and/or conversion in different formats.

To use the non graphical version of the system you need the following files, taken from the model directory:
  1. Equation file, normally called fun_mymodel.cpp
  2. One or more configuration files, extension .lsd
  3. the makefile called "makefileNW"
  4. the whole directory "src" contained within the model directory.
To compile and use the non graphical version of LSD, follow these steps:
  1. Move the model directory on the system you want to use. You actually need only the files indicated above. The "src" directory must be contained within the model directory.
  2. compile the lsd model program with the command: make -f makefileNW. You may need to adjust the variables in the makefileNW depending on your system. The makefileNW includes the options used on the original system, but they are mostly not used, since, for example, the non-graphical version does not link to the TclTk libraries.
  3. the resulting exectuable file requires a Lsd configuration file describing the model and its initializations and options. Run a simulation with the command: lsd_gnu -f sim1.lsd, where the name of the executable can change depending on your makefileNW ( variable TARGET) and sim1.lsd must be replaced with your configuration file.
  4. After each simulation run the system automatically generates a LSD result file (extension .res) containing the data for the variables indicated with the option Saved.
  5. Open the result files with any graphical version of LSD to analyse the results and/or export the data in other formats.


 

Menu Help

The Help menu contains five entry points to the Lsd manual pages (see the Introduction to Lsd help manual on using Lsd manual):


Help on Help
The menu Help in LMM, as well as the menu Help in the Lsd model programs, provides access to an extensive set of help pages, covering every aspect of model writing and using. The help pages are necessary to fully exploit this language, and therefore users are strongly invited to make use of the manual pages. Generally speaking, help pages are structured as a hypertextual document where each window or function related to Lsd is devoted a section, so to answer the questions "What does this mean?" or "How do I use this?". Of course, each section is filled with links to sections for related issues.
There are three levels of documentation: users are expected to test every aspect of the software, and to see in the manual the related page for instruction on its use (or explanation on "what does this mean?").

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.



 

Using Lsd on Mac OS X < 10.4

Matthieu Farcot managed to install Lsd on a Mac OS X and kindly offers these guidelines.

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