Windows Main Browser Lsd
This menu is used by the model authors to create or modify a model
(see the hints on model structure building).
Therefore, it should never be used by users who want to run simulations
with an existing model: to change the numerical values in a simulation
configuration see the the Menu Data (for
specific values) or
Menu Run (for
general simulation settings).
Other Menus of the Browser:
Menu "Model" Entries:
Changes the label of the Object currently shown in the main Browser
or delete it (by assigning an empty string).
The name cannot contain any end-of-string character. An empty name
will cause the Object and all its descendants to be deleted. The field
Compute checked on (default) means that the Objects
from the currently shown Object will be explored to have the contained
Variables computed. If the field is checked off the Variables contained
in the descending Objects (and their own descendants) will not be
by default by the system. To be checked off to speed up the simulation
in case many instances contain only Parameters and no Variables. Note
Variables in these Objects may still be computed if they are requested
by other equations. However, their data cannot be saved.
Insert a new Variable in the Object currently pointed to by the
The Variable label cannot contain string-terminating characters, that
it can use: letters, digits and usual characters (underscores, dashes
Lsd is case sensitive, therefore Price and PRICE are different.
Any instance of the Object currently pointed to by the Browser will
contain a copy of the newly created Variable.
For a simulation model to run it is necessary that for any Lsd Variable
defined in the model structure there exists an equation in the model
The equations are stored in an equation file that can be accessed and
through LMM asking for the Equation
in menu Model.
The number of lags for a Variable indicate how many past values for
the Variable are used in the model's equations. That is, if the
is used in an equation with 2 lags (its value at two previous time
than when Var1 is created in the model it must be declared as
2 lags. As a consequence, before starting a simulation run the
contain 2 initial values to be used at time t=1 and t=2 for use in the
equation where its past values are requested (see Init.
Values for setting the initial values).
In case of errors (e.g. when modeller specifies 0 lag for a Variable
that is requested by another equation with one lag), the system will
an error message during the first attempt to run a simulation. It is
to edit the name of a Variable, remove the Variable, or change its
by accessing the properties of the
clicking on its label in the main Browser.
Insert a new Parameter in the Object currently pointed to by the
The Parameter is like a Variable without an equation: it does never
value during a simulation unless some equation in a model (attached to
a Variable) does not overwrite its value (for example, see the Lsd
This command inserts a new Object type descending from the one
pointed by the Browser.
Lsd is case sensitive and does not accept spaces or other
characters for entities labels. Moreover, the label must be unique,
is cannot be identical to an Object already existing in the model.
The new Object type is inserted with a single instance in all the
of the parent Object. To change the number of instances for the newly
Objects use the menu Data.
a New Parent
Insert a new Object as a parent of the currently pointed by the
Each instance of the currently pointed Object will be moved as
of the new, otherwise empty, Object. The same rules for Lsd labels
case sensitiveness and no string-terminating characters.
Note the difference with Add a Descendant: in the latter case, the
created Object is added as descending from the currently shown Object.
In this case, instead, the new Object will be inserted between the
shown Object and its previous parent. Of course, this command cannot be
used in Root, since this must be the top Object of any model.
Assign to the model an equation file, that is, the file containing
the code for the equations of the model. The system should be able to
the equation file automatically (it reads the filename from the
when the first model structure is created, and then it is stored in the
configuration file). However, in some cases the modeller may want to
IMPORTANT: the code contained in the equation files is used by the
Lsd interfaces for presentation purposes only. Changing such a code
not modify the models equations, since this requires the re-compilation
of the code (see LMM introduction).
The code used to express the equations in Lsd is C++ for the
operations (algebrical, logical, cycles etc.). In the equations a set
Lsd functions are used to retrieve the information about model's value
(see Lsd Equation Language)
The report is the most efficient way to present the model structure,
code and initial values of a configuration. It is composed by several
listing the elements of the model (Objects, Variables and Parameters)
also the very code of the model equations. It is very useful because,
example, specifies which elements are used in an equation, and in which
equations an element it used. See the Lsd
Quick Help page on its content, or better try to build one and test
the automatic linking.
The creation of the model report is completely automatic, and the user
needs only to choose among few options. The following window sets the
Model title (by default it is the name of the model as
LMM). This title is placed in the top position of the report
Variables listing format The report contains the lists
Variables and Parameters for the whole model and for each object
It is possible to use scrolling boxes, where the HTML browser supports
them, or simple lists of text.
First extra section and second extra section (default
on and Section 2 off); the author can include up to two documents (text
or HTML formatted text) that are placed in the beginning of the report
as verbal introduction of the model. Check on the options to include
sections, set the name of the sections and to change the names of the
from which to take the text. If the field "Accept HTML formatting tags"
is set on the text is directly copied in the report. In this case, for
example, the character '<' is interpreted as the beginning of a
tag. Otherwise, the system translate the character as "<", so
in the report it will appear literally the lesser-than symbol.
New name the report is saved under a different name. In this
the report will not be opened when the user calls it from the model
of Lsd Model Browser.
This option should be used with care, since it replaces any current
documentation present in the model. Only modeller should use it when
The documentation of a model element is a text associated with any
Variable or Parameter in the model, called Description. This text is
when the user clicks on the model element (see help on the main Browser)
and in the model report. Model
are free to include any comment to the description of the item. The
for an item automatically list the Variables whose equation contains
label of the item. In this way, one is immediately aware where the item
affects the model's working. Moreover, the automatic documentation for
Variables includes also the early lines of comments included in the
of the Variable equation's code.
Generally, when a model is fairly complete, model writers may
the automatic documentation as a base for a complete documentation of
model, before creating the model report.
It is possible to generate the automatic documentation for all the
in the model (Objects, Parameters and Variables) or for Variables only.
This is because it is frequent the case of modifying the equations,
Parameters are not affected.
Note that it is possible to generate the automatic description for a
single item in its option window (see, for example, the help page for Variables
Find an element of the model
This window permits to find a variable or a parametet in the model.
The Browser will point to the object containing the searched for
element, and the element will be selected. This searching functionality
is useful for large models with many elements.
Notice that the window above is endowed with autocompletion: while you
type the entry proposes the first element with the described initial
Hints on Model Structure Building
The model structure is the collection of Objects containing Variables,
Parameters and other Objects forming the backbone of the model. Given
Variables and Parameters the modeller decides to use in a model, the
is to create the Object structure to contain them. This section gives
hints on how to decide in which Objects Variables and Parameters should
be placed in the model. The structure determines how many copies of the
Variables and Parameters a user will be able to define in a
(only Objects can be multiplied in many copies, each containing the
Variables, Parameters and descending Objects). The structure determines
also the results produce by the use of the Lsd functions in the
In the following it is assumed that the reader is already familiar
the basics of Lsd equation writing. In fact, generally the model
is quite obvious for simple models, with few equations, while the
on how to implement the structure can become a complex task only for
complex models. Therefore, we assume that a modeller has written the
code for few equations, and now is deciding how to implement the model
structure. Note that, depending on the structure, it is possible that
equations will need to be modified. In case of doubts, the best way to
ensure that an equation is computed exactly as expected, the modeller
use the Lsd debugger, which shows exactly
an equation does during a simulation run.
The discussion on the model structure is basically a discussion on
Variables and Parameters should be placed. To simplify the explanation,
we will consider only two Variables (it applies also to Parameters,
the equations are not involved). Suppose that we have written two
for Variables x and y. There are two basic questions that the modeller
must answer when building the structure:
To answer the first question the modeller needs to consider the case of
a configuration where there are many copies of the Variables x and y.
the two Variables are placed in the same Object, then they must will
replicate in the model in the same number. That is, there will be as
copies of x's as y's. If this makes sense, given the meaning of x and
then almost certainly placing x and y in the same Object is the correct
answer. Instead, if the reality represented in the model can be
with different numbers of copies of x and y, then they would
be placed in different Objects.
Should I place Variable x and Variable y in the same Object or in
Given that x and y must be in different Objects (say X and Y
should these Objects be related hierarchically or not? In other words,
should one Object contain the other, or "parallel" in the model
The second question is more tricky, and this is due to the fact that
each Object type in a model structure can be replicated by users in a
in many copies. And that any copy of an Object must be exactly the same
(that is, with the same type of Variables, Parameters and descending
although the numbers may differ (e.g. values of Parameters, number of
of descendants). The modeller decides the model structure once and for
all, but when the model is released to users, they can (and will)
the number of copies. Therefore, the modeller must ensure that the
structure provides the necessary constraints such that the model's
is kept whatever numerical configuration is decided by users. So,
X as descending from Y, means that every copy of Y will contain at
one copy of X, and possibly many. Instead, placing them "parallel" in
hierarchy, e.g. both descending from the same Object, can allow to
model configurations with as many copies of Y and X as desired, with no
Therefore, a first criterion that can be used to decide whether to
X as descendant of Y, place Y as descendant of X, or just parallel, is
to see if, in the interpretation of the model meaning, it makes sense
X must always have more copies of Y, Y have more copies of X, or if
is not relevant.
However, the definitive decision must come from the understanding of
the use of the model structure by the Lsd simulation manager, i.e. how
the model structure affects the computation of the model equations. For
simplicity, let's assume that the equation for a Variable in X, say x,
needs to use the an element contained in Y, suppose the Variable y: x =
f(y). If this is not the case, the decision does not, of course, change
the way Lsd computes the equations. Otherwise, the structure is
to determine which copy of y is used when computing the equation for
copy of x. This is due to the fact that in Lsd the model writer does
specify where to get the values required, but only their label, much
difference equation notation. During a simulation, at the very moment
equations are computed, the system automatically tries to satisfy the
written in the equations code. Therefore, the modeller must use one of
the Lsd functions to implement the desired
(i.e. choose the correct copy of y for each copy of x). These functions
are implemented in such a way to write in extremely simple ways the
obvious operations, even when these involve a lot of operational
Let's now see how the desired value for a Variable (y) is retrieved in
different ways within an equation (x), depending on the model
As said, we need to consider that a model configuration can have
copies of Object X and of Y, and therefore also many copies of the
x and y. The same equations code for x will be used by all the copies
We may have three cases, depending on the relation between Objects
X and Y in the model hierarchy:
many copies of x need to compute their values using the value of a
copy of y. In this case, the Object X must be placed as descendant of Y
(Y is a high level Object that contains Object X). This is, for example
the case where x is the Variable Profit contained in Object Firm (X)
with the Variable Price (y) contained in Market (Y). There may be many
copies of Objects Market and of Objects Firm, but any group of Objects
Firm will always use the value same copy of Price. That is, each Market
(one or more copies) will have many copies of Object Firm as
In this case, the modeller can use in the equation for Profit the line:
v = p->cal("Price",0);
and the system will automatically ensure that any copy of Profit (x)
will execute its equation using the value of Price (y) taken from the
of Market (Y) that contains the copy of Object Firm whose equation for
Profit is under computation.
- each copy of x needs to use many copies of y, and always the
same. In this
case X must be defined as container of Y. For example, this may be the
case where Variable Price (x) contained in Market (X) is computed from
a demand function over the sum of the values of Variable Quantity (y)
in Firm (Y). In this case, the modeller can use in the equation for
v = p->sum("Quantity",0);
and the system will automatically ensure that any copy of Price will
use the values of Quantity taken from the same copies of Objects Firm.
Note that a line like this:
v = p->cal("Quantity",0);
will always return only the value of Quantity contained the very first
copy of Firm descending from Market (see the description of Lsd
- any time a copy of x is computed it needs to use a (potentially)
copy of y. In this case, Objects X and Y must be placed as descendants
from a common Object, say Z. Note that the modeller must provide an
equation to determine which copy x must use any time is computed. As
consider the Object Consumer (X) containing the Variable Money (x)
needs to use the Variable Price (y) contained in Seller (Y). There are
many Objects Consumer and Seller, and a Consumer can choose any one
of the Objects Seller (assume that Object Seller has a Paameter
a unique identification number for each Seller). The model structure
then be such that the Object Market (Z) contains a Variable Choose and
both Objects Consumer and Seller, each potentially replicated in many
The equation for Money will then have the lines:
v = p->cal("Choose", 0); //ask
in Z to choose a seller
cur = p->search_var_cond("IdSeller", v, 0); //find
the Seller with the given IdSeller
v = cur->cal("Price",0); //take the
of the chosen Seller
The first line asks Choose to compute the identification number of
one Seller (for example, a random choice proportional to the Seller's
shares). The second line asks the system to find the copy of Object
with the chosen identification number. Finally, the third line uses
copy to obtained the desired value of Price. The equation for Choose
contain the lines: