1. Open Ventity.

If this is your first time using Ventity, it will open to the home screen, shown below. (Ventity opens the model that was open at the end of the last session, or the home screen if that doesn't apply.)

2. Create a new model.

Click "New Model..." under the "Start" heading, or choose New Model from the File Menu. Enter the name of the model and choose a directory to store the model folder:

3. Your model is now open in Ventity, but does not yet contain any information.

•On the left (below), you see the Model Overview, which lists information about all four modes of working in Ventity (entity definition, initialization, simulation, and examination of results).

•Below that is the Scenario Entity Overview, which is used to control which outputs are included on graphs.

•In the center is the diagram panel where you will create a visual representation of the logic and assumptions in your model.

•On the right, the Entity Type inspector organizes and makes visible all the elements of each entity type.

Looking at the Model Overview (top left), we see that our new model already has two entity types: Model, and Exercise 1. Ventity creates a Model entity for every model; it can be ignored for now. Ventity also will create a default entity type with the same name as the model, so here, it's named Exercise 1. That's not a very helpful name in this case, because this model is actually about pastures, and we will need pasture entities. So in the model overview, right-click the Entity 1 entity type and rename it to Pasture:

The Pasture entity type will now appear in the model overview, and in the Entity Type Inspector on the right:

What do we need to calculate about a pasture? To keep things simple let's focus on one thing only: the height of the grass.

Variables in Ventity come in four flavors: stocks, flows, auxiliaries and aggregates. Briefly,

•A stock is a cumulative quantity.

•A flow is an inflow or an outflow to a stock. Flows are the rates of change that are accumulated in stocks.

•An auxiliary is any variable that is not a stock or a flow. Auxiliaries are generally used either to break down and simplify the calculation of flows, or as reporting variables.

•An aggregate is a variable computed from a collection of entities, for example, the total assets of all business entities in a simulation.

A full discussion is available in the variables section of this manual. For our purposes, the height of the grass is a stock. The flow that is being accumulated is the process of grass growing. So we'll need a stock and a flow:

4. Drag the Stock icon from the palette to the diagram. When you release it, it will automatically be named "Stock1".

5. Replace "Stock1" with the name "grass height". Press the enter key, and the stock is complete:

The symbol indicates that the stock currently has errors. In this case, that's because it has no default initial value, but we'll get to that later.

What flow affects this stock? The flow that is accumulated in "grass height" is grass growing. So we need a flow called "growing" that flows into "grass height".

In Ventity, every flow must have a source and destination. If the destination is "grass height", what is the source? The actual source of grass biomass is carbon dioxide from the atmosphere. Since we don't need to calculate how much carbon remains in the atmosphere as the grass grows, we don't need to make a stock to represent the source. Instead we use a cloud, which is a symbol that says "I don't care where growing grass comes from or how much remains at the source." In short, a cloud is an infinite source, or infinite sink.

6. Drag a cloud onto the diagram:

7. To create the flow from the cloud to the stock, float your cursor over the edge of the cloud until it becomes a hand (),

and click and drag an arrow to grass height:

Since the arrow is from a cloud to a stock, Ventity will automatically recognize it as a flow, change the diagram style to a pipe and name it Flow1:

Alternatively, by right-clicking on the stock, you can select "Add Inflow" to create the cloud and inflow to the stock automatically. You can read more about this option by clicking [here].

8. Replace the "Flow1" name with "growing". The green handles are used to reshape the pipe, but we will leave it as is.

When you click anywhere else on the diagram, or press the esc key, the green handles disappear and you will be left with a completed stock-and-flow diagram:

With the diagram complete, we next add equations.

9. Right-click on the "grass height" stock and choose "Edit Stock":  

10. In the editor, add units and a description. For stocks, no equation is required; Ventity will automatically calculate them starting with an initial value and then cumulating the net inflow (inflows minus outflows) each time period. All we need to do is provide the initial value. Here we've used 2 cm. (The field is labeled "Default Initial Value" because this is the value that will be used if no overriding value is provided in the next stage, Initialization.) Close this window.

11. We do need to provide an equation for our flow. Right-click and choose "Edit Flow" ...

12. ... and enter the equation. We need to provide units (cm/day), a description, and the equation itself. Here we use a constant, .1 cm/day. Note that the source ("From Stock") and destination ("To Stock") are automatically listed from the diagram.

We have now defined our "pasture" entity type: a pasture is characterized by the height of the grass, which will start at the default value 2 cm and grow by .1 cm/day, unless overriding values are provided during the next stage: initialization.

Initialization is how you tell Ventity how many of each type of entity exists at the start of the simulation, and how you specify the individual characteristics of each entity. If you don't provide this information, Ventity uses default values.

By default,

•One of each type of entity is included at the start of simulation

•Specific values are determined by the definitions and equations you wrote in stage 1.

For this first run, we will skip Initialization, and use the default values. Thus, our simulation will include one pasture, with initial grass height of 2 cm and a growth rate for grass of .1 cm/day.

To run the model, the only configuration that must be done is to set the time span of simulation.

13. In the Model Overview, either double-click Run Control, or right-click it and choose "Edit".

The Run Control dialog will appear:

It is currently set to simulate for an Initial Time of 0, a Final Time of 120, and with a time step of 1 day. This means that Ventity will do the following:

•Set all stocks to their initial values at the Initial Time.

•Calculate the values of all flows.

•Use the flow values to update the stocks after one time step (in this case, one day)

•Recalculate the flows for the next time step

•Update the stocks based on the recalculated flows

... and so on until the Final Time.

These settings are fine for our purpose so we can leave them as they are. The model is now ready to run, and you can close the Run Control panel.

One last thing before we run the model. Since most model calculations are so fast that they seem to occur instantly, it is helpful to see Ventity's report of the run in progress. Messages from Ventity about the status of the run are displayed in the Console panel.

14. To view the console, open the Console panel from the View menu:

It will appear at the bottom center of the Ventity window:

15. Now, we can run the model! Either click the green arrow in the toolbar, or choose "Run Model" from the model menu.

The model has run. As shown on the figure below, you can view the output as a Run by right-clicking Results in the Model Overview (1) and selecting Edit. Log messages reporting the start and finish of the run also appear in the Console (2).

The most immediate way to look at a variable over the time period of the calculation is with a line graph.

16. Right-click on the "grass height" stock and choose Line Chart:

17. The graph of grass height vs. time appears. Float your cursor over the graph to get specific values for any point in time:

The graph shows the expected behavior: at the beginning of the simulation, grass is 2.0 cm high. It then grows at a steady .1 cm/day for the four months of the simulation. You can right-click any variable in the model to see a line graph of that variable. Later in this tutorial we will see how to graph more than one entity, run, or variable at the same time.

18. All the Ventity™ panels are dockable. Click and drag the title bar of the line graph, and when you see the docking controls appear, drop it on the icon just to the right of center:  

19. Your line chart is now docked between the diagram and the entity type inspector. By dragging the title bar of any panel, you can move it to other locations in the Ventity™ window, or can close the graph by clicking the x next to the graph's title in the upper right.

Congratulations - you've just completed all four stages of using Ventity:

You can find this model in the Sample Projects folder, named Exercise 1 Complete.

On the next page we use the four stages to compare runs with different input assumptions, which will be entered during the initialization stage.