Garp3 is a workbench for building, simulating, and inspecting qualitative models.
All those tools have been integrated into Garp3
A good practice is to save your models in a separate directory outside your Garp3 directory. It is a bad idea to save your models in the Garp3 directory, since when you upgrade Garp3 you might accidentily delete your old Garp3 directory including your models. Furthermore it is good practice to save different versions of your model during development. This makes it easier to go back if a certain new representation proves not to work, or certain changes were counterproductive. It also makes the model corruption less disastrous. A common practice is to add the suffix vs0x to model files to indicate version numbers. A further suffix a, or b can be used to distinguish different competing improvements to the same model.
One good practice is to save models often and as different files, as when a model becomes corrupt it is possible to go back to a previous version. When collaborating with other people make sure that you both run the same version of Garp3, as opening and saving a model from a recent version in an older version of the software maye cause model corruption.
By default KDE has window focus stealing prevention on. This has to be set to None so applications can make the correct windows active. To deactivate window focus stealing prevention go to 'Control Center', 'Desktop', 'Window Behaviour'. In the 'Advanced' tab set 'Focus stealing prevention level' to 'None'. The correct Garp3 windows should now become active.
Causal chains often start with an influence (I), which may be followed by proportionalities (P) that propagate the effect. Chains of proportionalities (P) following each other occur quite often, but chains of multiple influences (I) following each other are likely to be incorrect. If you have both I and P dependencies affecting the same quantity, it is generally advised to remove one of the two. A directed loop of proportionalities is also incorrect, since the reasoning engine cannot resolve the derivatives of the quantities. The reason for this is that to determine the derivative of each quantity the derivative of the previous quantity has to be known. In a loop of proportionalities this is impossible.
Influences should be used when the following relation has to be modelled: "If the magnitude of the source quantity has a non-zero value, the target quantity will change." When the relation "If the source quantity changes, the target quantity will change too." has to be modelled, proportionalities should be used. Influences use the magnitude of a quantity to derive the derivative of the target quantity, while proportionalities use the derivative of a quantity to derive the derivative of the target quantity.
A feedback loop is an effect on an influencing quantity from a quantity that the influencing quantity directly or indirectly affects. One example is shown in the Tree and Shade model: Growth has a positive influence on the size of a tree, and the growth is proportional to the size of the tree (this feedback is modelled as a proportionality from size to growth). Another example is shown in the Communicating vessels model: Flow has a negative influence on the Volume of the liquid in the container. There are positive proportionalities from Volume to Height, and from Height to Pressure. Finally, there is a positive feedback (a proportionality) from Height to Flow.
A correspondence can be used to ensure that values always occur together. Be aware that this may not be the case when there are multiple opposing influences on the quantities involved. In that case, a correspondence may be too strict.
Is there a causal connection with a particular direction? In that case, the correspondence should probably be directed (with the same direction as the causality). Or do the corresponding values always occur together? In that case, the correspondence should be undirected (= bidirectional).
The quantity space should contain just the right amount of distinctive values that are necessary to model the behaviour of that particular quantity in a qualitatively meaningful way. Think about whether zero should be included as a point value, and which other point values might be necessary (e.g., as thresholds for the specification of conditions for model fragments). Is it possible for the quantity to assume a negative value? Since the amount of possible states greatly depends on the size of quantity spaces, it often helps to reduce the number of states by limiting the number of values in a quantity space.
Garp3 prohibits the creation of inequalities between zero and other values, since it would only add superfluous knowledge. Every zero is by definition equal to each other zero. The only reason to create an inequality would be to indicate that a certain point value is greater (or smaller) than zero. A better way to indicate that a point value is greater (or smaller) than zero is to add the value zero in the quantity space.
Introducing an extra quantity for a calculation can be a good idea when this result has an intuitive meaning, and will be used at several places itself (e.g., in conditions of model fragments, or other calculations). Sometimes, the new quantity can be considered as an aggregate of multiple other quantities (e.g., population growth as an aggregate of more basic processes birth, death, immigration and emigration). However, be aware that introduction of new quantities can lead to an increase in complexity.
Yes you can, by selecting the derivative symbols of two quantities and adding an (in)equality statement.
If the magnitude or derivative of a quantity cannot be determined (via causal dependencies, plus or minus relations, equality relations or correspondences), normally the quantity would have unset values for the magnitude or derivative. However, the engine has a reasoning-assumption mechanism for conditional values and inequalities that cannot be proven to be true (cannot be derived, but are possibly true). For example, if a quantity has an unset magnitude, and a model fragment has a conditional magnitude value for that quantity, the engine tries to assume that the condition holds (i.e. the quantity has that particular value). As always, if an inconsistency can be derived (possibly due to the assumed value), the state is deleted. The same mechanism applies for inequalities. If a conditional inequality cannot be derived, it is assumed. Examples of model fragments with only conditional inequalities or values can be found in the full envisionment version (version 2) of the communicating vessels model.
No, by definition zeros are universally equal throughout the model. This means that even zeros belonging to different quantity spaces can be considered as having an equality relation between them. Adding these equalities is superfluous.
No, the qualitative simulator can infer this by itself, adding the statement would be superfluous. This inference is called transitive inequality reasoning.
Specifying that two values are equal means that those values are quantitatively the same. For example two cups could have the same maximum height (e.g. 5cm). This does not mean that the quantities have the same value at the same time. Specifying that two quantities are equal means that they will have the same value at the same time during simulation.
It is strange to specify that a quantity cannot have a specific value, as there should be a reason this value was defined in the quantity space. A good reason to constrain the possible values of a quantity is to minimize a simulation. In this case the assumption is made that the quantity has smaller than, equal to or greater than some specific value. The best way to model this is to create a new model fragment in which the entity/agent with the corresponding quantity is included along with an assumption, all as conditions. Furthermore, the inequality should be added as a consequence. Once the assumption is included in a scenario, the states in which the value is zero will be removed from the state graph. By removing the assumption from the scenario the states will reappear.
Especially the values of derivatives should be inferred by the qualitative simulator using proportionalities and influences. By setting these you model that something should have a specific value in a specific situation, but not why it should have that value. When proportionalities and influences are used, the cause of change within a system is modelled, and not the result of some process. For this reason setting values of quantities should be reduced to a minimum, and setting values of derivatives should be avoided at all times.
In principle, there is no boundary to the amount of information in a model fragment (MF). However, it is good modelling practice to use separate MFs for distinct concepts or ideas. This facilitates systematic model building, exploring alternative possibilities, debugging the model, and possible reuse of model fragments.
Model ingredients can be incorporated into model fragments as conditions or consequences. The conditions indicate the model ingredients a scenario has to contain in order to become active. The consequences in a model fragment represent the model ingredients that have to be added to a simulated scenario if the model fragment applies. A model fragment can be read as: 'When these conditions are met, these consequences have to be true.'
Model fragments with only conditions fire normally when the conditions are fulfilled, but will have no effect unless it contains inequalities or value assignments. If a conditional value assignment or inequality is not inconsistent with the other derived knowledge then Garp3 will assume the condition to be true. There is a specific purpose to model fragments with only conditional inequalities and values.
In an incomplete model fragment not every entity and agent is structurally related. There should always be a path of configurations leading from each entity or agent to each other entity or agent.
Static fragments are used to model stable characteristics of a system, such as the structure of the system. They may also contain proportionalities, but they cannot contain influences or agents. Process fragments are used to model processes that induce change within the system. Agent fragments are used to model external effects on the system. Influences can be used in process and agent fragments. Agents can only be used in agent fragments.
Assumptions (e.g., inequalities between certain quantities) can be used to constrain the simulation in some way. It is common practice to define an assumption with a name that corresponds to the MF, and use this as a condition for the MF. To control external quantities, it may be nicer to use agents in model fragments.
This depends on whether you know the inequality is true from the start (in this case, you can put it in the scenario), or is used as a trigger for a particular MF (in this case, put it in the conditions of the MF), or is true when a MF fires (in this case, put it in the consequences of the MF). Sometimes, however, it is not necessary to specify the inequality at all, if it can be derived automatically from the quantity values. If it is possible to let the machine determine it automatically, this is preferred, so that the number of inequality specifications in MFs and scenarios can be kept to a minimum.
It is common practice to model a process (or agent) with a process quantity (e.g., flow) whose value is calculated by the difference between two other quantities, and influence(s) originating from this process quantity. This way, the influence(s) become inactive when the difference is zero, i.e., when the balance is restored. Alternatively, it is possible to use specific activation conditions for process (or agent) MFs to fire, but then care should be taken that when the process becomes inactive, this does not lead to discontinuous changes.
This can be done by creating 3 subtype model fragments that say 'assume X smaller than Y', 'assume X equal to Y', and 'assume X greater than Y', with the appropriate (in)equality statements as conditions.
When an MF is reused (e.g., by creating a child MF, or by incorporating an MF as a condition), all of its elements are put into the new model fragment. When multiple MFs are reused in one new MF, this may lead to multiple elements (entities, quantities, etc.) with the same name. If two occurrences are meant to refer to the same thing, they should be connected by an identity link in the new MF.
The same quantity attached to the same entity, but with a different quantity spaces is still considered a different concept. This means that two quantities (with the same name but different quantity spaces) in two model fragments (or a model fragment and a scenario) cannot be unified. As a result, if one model fragment (or scenario) introduces the quantity as a consequence, it does not fulfil the quantity as a condition in another model fragment. Instead of using the same quantity with different quantity spaces, consider creating a new quantity with the different quantity space to represent the conceptual difference caused by the different quantity spaces.
When the model contains the right set of entities, it is often straightforward to determine which entity a quantity should belong to. When in doubt between different entities, first check whether these entities are really modelling different concepts, and whether any entities are missing. Think about the other quantities of each candidate entity: does the quantity fit well into one of these lists? In the case of a quantity related to a process involving multiple entities (e.g. a flow from one container E1 to another container E2), the quantity may be modelled as belonging to entity E1, entity E2, or to an entity modelling something related to the process itself (e.g., a pipe entity E3).
Agents are used to model processes that affect the system of interest, but are external to it. For example, if the system of interest is a river, a polluting factory might be modelled as an agent that adds pollution to the river, while not being part of the river itself. Agents are labels that are applied within scenarios and model fragments. If a particular label appears in a scenario, model fragments that contain that agent label as a condition are applied. If the label does not appear in the scenario, these model fragments are ignored.
It is a good idea to first think about the system you want to model and your models goals, before actually creating the model. A structured approach to go through this process is by following the Framework for conceptual QR description of case studies. At the implementation stage it is crucial not to try and implement the entire model at once. Instead it is better to create and test individual model fragments one-by-one as much as possible. Also focus on model fragments that model single processes. Describe (explicate) the behaviour you expect each model fragment will generate. For each of these processes create at least one scenario to test the model fragments. Improve the single model fragments until the behaviour is correct and move on to the next model fragment. Then try to combine different model fragments in the simulation and improve them to generate the correct behaviour. Work towards the end result in a stepwise manner, ensuring the correctness of each individual step. Do not immediately start creating dozens of model fragments, as it will make the debugging of models extremely difficult.
When running a simulation produces no states, this is due to an inconsistency. To resolve this issue the inconsistency has to be resolved. When the inconsistency is resolved the simulation should generate at least one state, namely the state describing the scenario (even when no model fragments fire). If after resolving the inconsistency only one state is generated when more are expected, there is probably no cause for change (e.g. no model fragments with influences fire, or the influences have no effect).
Inconsistencies are combinations of facts that contradict each other (i.e. cannot both be true at once). For example, A > 0 and A = 0. A state description (an interpreted scenario, or state in the simulation) that contains an inconsistency does not become a valid state. As a result it is possible to produce a simulation result without any states. A typical example of an inconsistency is caused when the facts specified in the scenario and/or the consequences of one or more model fragments clash. However, there are other sources of facts that can cause inconsistencies:
The first step in resolving an inconsistency is determining which inequalities are causing it. The simulation tracer shows all the inferences the simulation engine makes. When it encounters an inconsistency it specifies which inequalities cause the inconsistency, and what the last model fragment was which was added. To determine if this model fragment is the real cause of the inconsistency the model fragment can be deactivated. This should resolve the inconsistency. If it does not, there may be other inconsistencies that should be diagnosed using the tracer. If the conflicting model fragment is found, the model ingredient causing the inconsistency should be removed, and the model fragment should be activated again.
A model fragment only fires if a state fulfils its conditions. If one or more of the conditions is not fulfilled the model fragment does not fire. Check the following to see if this is the case:
If only one state is generated, this means that the scenario has only one possible interpretation (which is often a good thing), and that no successor state can be generated. If successor states were expected, check whether the model fragment(s) that should induce changes to the system have fired as expected, resulting in quantities increasing or decreasing.
Often, this is due to specifying too many constraints in the scenario, or in model fragments, e.g., value statements, inequality statements, or correspondences. The more knowledge is specified, the higher the chances of conflicts arising.
Pick a state that should lead to one (or more) successor state(s), and try to find out why this is not generated. Check whether the terminations you expect are generated, by turning on the Simulation Display option 'show termination nodes', and opening the transitions view for the originating state. If the termination is there, but doesn't lead to a successor state, the tracer can provide information about why the termination was unsuccessful (especially, the options 'Show search for possible terminations', 'Show ordering and removal of possible terminations', and 'Show search for successor states' should be turned on). If the terminations you expected are not being generated, check whether the quantity derivatives are as expected, and check whether the model fragments fire as expected. When you understand the problem, try to fix the model in such a way that the successor state(s) is/are generated, and proceed with the next state.
There may be several reasons for this:
If the number of states is approximately what you would expect, look at paths of behaviour and see if the behaviour makes sense. Look at the values of (all) states to see if the right combinations of values occur. Look at individual states to check at a more detailed level. Do the right model fragments fire? Do the end states represent proper end states, in which a maximum/minimum is reached, or the system behaviour has stabilized? If cyclic (repetitive) behaviour was expected, check whether this is present in the simulation.
The simulation probably contains many states and/or transitions which have to be calculated. If this is not what you expected, try running the simulation again step by step and check if you can notice anything going wrong by looking into individual states and their transitions. Another option is to limit the depth of reasoning in Garp3, by setting a value (e.g., 5) for Maximum Inequality Reasoning Depth, in the Simulation preferences (Advanced).
At the bottom of the Simulate main screen, there are three buttons 'Terminate selected states', 'Order selected states', and 'Find successors for selected states'. In the display menu, turn on 'Show termination nodes'. Select a particular state (or multiple states) and press one of the three buttons to run the simulation step by step.
If you have a small model and expect a small simulation, running a full simulation will produce the results faster, but running it step by step can help you detect problems early, especially when the simulation gets large.
On the bottom of the Simulate screen, in the selected states field, enter the state number between square brackets, for example '[45]'.
This is in fact impossible - there must be a difference between states, in either the values or the equations. If you can't see a difference in the quantity values between the two states , there must be a difference in the equations. You can check this by opening the equation history for the states in question.
It could be that the inequality is used in different forms in different model fragments, or it could be that the machine adds it in a particular form, in case there is a transition involving an inequality change. In general, only one of the two is necessary, because Garp3 knows that they mean the same thing.
There may be several reasons why an expected end state is not reached:
When a state or path is selected, pressing the button 'Transition history' will present the list of relevant transitions. When selecting one of the transitions in this list and pressing the button 'Transition details', or double-clicking on a transition directly, more details about the selected transition are shown.
When a quantity has no derivative there are two possible issues. Firstly, the quantity is being influenced via a proportionality relation by a quantity that has no derivative. In that case, making sure that quantity has a derivative solves the issue. Secondly, the quantity is being influenced via an influence by a quantity that has no magnitude. Giving the influencing quantity a magnitude will solve the issue. Another possible solution is to give the quantity an exogenous behavior that gives the quantity a behavior.
When a quantity has no magnitude there are three possible issues. Firstly, it could be that there was no value set of the quantity in the simulated scenario. Setting the value in the simulated scenario solves this issue. Secondly, it could be that the quantity magnitude was known in the previous state, but not in the current state, and the derivative of the quantity was unknown in the previous state. Then, making sure the derivative of the quantity is set in the previous state will allow Garp3 to determine the magnitude of the quantity in the current state. Thirdly, the magnitude of a quantity can be calculated by using the plus or minus operator (adding or subtracting two quantities, and indicating that a third quantity is equal to the result). It could be that the model fragment that adds the operator does not fire, or that one of the quantities that is being added (or subtracted) has an unknown magnitude. Making sure that the model fragment fires, or the magnitude of the quantities is set, will solve the issue.
Values specified in a scenario are only initial values. This means that they indicate the value of a quantity in the initial states, but can change during simulation. Therefore during simulation the value of a derivative can become unknown if it is not influenced in some way, and the magnitude of the quantity can change to other values. If a value of a magnitude or derivative has to have a specific value during simulation a value assignment has to be set to that specific value in a firing model fragment (e.g. in combination with a conditional assumption to allow simulations in which the value does change). Another option is to define exogenous quantity behaviour in the scenario.
Consider the following. If a quantity is changing into the direction of the dominant influencing quantity in the context of two opposing influencing quantities, and the stronger influence is removed, the resulting overall influence suddenly changes into the other direction. Due to continuity constraints this is not possible, a derivative can only change direction if it first becomes stable. One way to solve this issue is by making the stronger influence become smaller when it approaches zero. Another representation is to introduce a new quantity and subtracts the two influencing quantities using the minus operator and use an equality relation to specify that the result is equal to the new quantity. This new quantity then causes a single influence.
The issue is probably that the originating quantity does not have a zero value in its quantity space. As a result the engine cannot determine whether the influence should cause a negative or a positive influence. Therefore it is unable to determine the derivative value of the target quantity.
It could be possible that the number of possible transitions is too large to be calculated without running out of memory. This does not really matter, as the resulting state graph would have become to large to understand anyway. A possible solution is to try to reduce the number of states. (see "I have far too much states. How can I reduce them?")
It is a good idea to run a simulation as soon as you have a small scenario and a few model fragments ready, to test if they work as expected. Try to predict what will happen first, and check your predictions. If something is wrong, determine whether it is the model, or your prediction. It is generally wise to fix any error before adding additional elements to the model. This way, you will develop a feel for how the simulation engine works, and how subsequent changes to the model affect your simulation results.
Think about whether they should be agents or processes. Conceptually it may be nicer to model human activities as agents, although it may also depend on whether the human behaviour is affected by something else. In that case, the human behaviour may be considered a process rather than an external influence. From a technical point of view, it does not matter. To decide about the type of causal dependencies to use, consider the following. If you have only one rate (I), that will generally drive the simulation in one direction, without being able to control it. Therefore, to model a certain action happening, it may be handier to use a P, than an I. But if you have opposing actions or processes, having multiple I's may be an even better solution.
Yes, it is possible to model cyclic behaviour. Whenever a particular state-transition leads to a state which already exists, a cycle is created, which represents a possible behaviour that repeats itself.
The proper way to do this involves modelling explicit causes (i.e., processes) that cause quantities to increase and then decrease again (or vice versa), in such a way that a path can lead back to an earlier state. A shortcut way to model this is to open a quantity definition in a scenario and specify that it should be an exogenous quantity, with sinusoidal behaviour.
If you are in doubt over the name of a term that you use in your model, this may be an indication that something is wrong with it. Will other people understand what you mean by it? Is it in the right place? Check if the concept you want to model is not already present somewhere else in the model. Does the concept fit in the perspective of the other elements in the model? Discuss the concept with somebody else, or study the literature for inspiration. Make sure you use the Remarks-field to enter your thoughts about the concept, including your doubts. However, note that from a technical point of view, the actual name does not matter for Garp3, as long as it is unique within its context.
Tip: using labels with numbers to precede the name of MFs (e.g., 'Mf15...' and scenarios (e.g., 'Sc3...') makes it easy to refer to them in discussions, and gives you control over how they are ordered.
Garp3 has functionality to export diagrams as Encapsulated Post Script (.eps) files. EPS is a so-called vector graphics format, which means it allows infinite zooming without degrading the quality of the image. It is the perfect format for publications. EPS files can be imported as an image in Word. Word creates a preview of the image which usually looks quite bad on the computer screen. However, when the Word-file is converted to PDF the actual EPS graphic is used, and the resulting document has the best quality. PrimoPDF is a free PDF converter (printer driver) which can be used to convert Word files to PDF (Windows only).
Garp3 image files are in EPS format. Depending on your workflow they can either be included directly to your Latex file, or need to be converted to PDF first. When using the 'latex' command (followed by dvips or dvipdf) the EPS files can be incorporated as is (as described in Section 4.1 of the The Not So Short Introduction to Latex). When using the 'pdflatex' command (which is much faster), the EPS files have to be converted to PDF files before they can be included. The best solution is to use 'ps2pdf' to convert the EPS to a PDF, and then use PDFCrop to create a correctly sized image. The resulting PDF file can be included in the latex file (as described in Section 4.7.3 of the The Not So Short Introduction to Latex). A fast way to convert a large set of images is as follows: for file in *.eps; do `ps2pdf14 $file`; done;. Followed by: for file in *.pdf; do pdfcrop $file $file; done;.
The EPS images of diagrams that can be exported from Garp3 are not suitable to use in PowerPoint presentations, since EPS support in PowerPoint is poor. It will not show the EPS images in presentations. However, creating screenshots of Garp3 is a bad alternative, since the screen-shots do not have a high enough resolution to create nice looking images. Instead, the EPS should be converted into another format, as explained below.
Probably the best file format for images in PowerPoint (if the PowerPoint file is not converted to pdf) is Portable Network Graphics (.png). Adobe Photoshop and Adobe Illustrator have built-in eps/png support, but are commercial solutions. The GIMP is a free image processing solution which can be used to convert eps to png. It requires the GTK+ toolkit to work, which is also available from the GIMP website. There is a slight drawback, as the eps support is not built-in. Ghostscript has to be installed and the GS_PROG environment variable has to be set to the full path of gs.exe, as described in the GIMP FAQ. The guide to setting environment variables in Windows XP might be a helpful resource to set the GS_PROG variable.
Garp3 does not support creating images of the Garp3 interface. The only way to create images of Garp3 is by creating a screenshot of the application using functionality native to your operating system.