PTV Vissim and PTV Viswalk include “attribute modifications” as a very versatile feature. This rather technical term stands for no less than “scripting without a script”, a “context generator” to model rare and specific situations for which a dedicated feature might be missing. In this tutorial you will learn how to define and use attribute modifications for PTV Vissim and PTV Viswalk. The model files for following the tutorial hands-on as well as the examples are included with the current PTV Vissim version.
Hello, and welcome to the PTV Vissim tutorial ‘Attribute Modifications‘. With attribute modifications Vissim provides a versatile tool to model actions or specific data handling without requiring scripts.
In this tutorial you will learn how to define and use attribute modifications for PTV Vissim and Viswalk. Step by step we will build a simplified energy management of an electric bus. Then I will point you to a few examples briefly, giving you some ideas what else you can do with attribute modifications.
CHAPTER 1: SIMULATE ENERGY CONSUMPTION
Attribute modifications allow to automatically change attribute values of network objects. While typically this is done during a simulation run, it can also be done before or after, for example for initialization. During simulation, all those attributes can be modified which also could be edited manually (for example in a list). The selection list for the target attribute contains only those attributes.
The new attribute value is computed by a formula which is similar as the formulas used for user-defined attributes or routing, for example. A filter condition allows you to modify only a subset of objects, or even a single object only.
Now you will see you hands-on, how to monitor the current charge state of the battery of an electric bus. As this depends on various parameters, we want to define our own formula for the energy consumption which in turn reduces the battery’s charge state.
To keep this tutorial straight, we use very simple formulas. While these may not be suitable for real-life projects, they help you understanding the principle of attribute modifications. For more realistic applications you can easily adapt the formulas later.
So lets start:
The files accompanying this tutorial are included with your Vissim installation at
…\Tutorials & Guides\Tutorial Videos - Vissim Files\Attribute Modifications
The example network is pretty simple: Here is just an electric bus that circulates in an endless loop. While the battery charge state is not a native vehicle attribute, we define a user-defined attribute for it. And the formula to change the charge state during the simulation is defined in an attribute modification.
First open the list of user-defined attributes.
Then define the vehicle attribute SoC (State-of-Charge). This holds the charge state in percent, so the default value is 100. Then open the list of attribute modifications
Add a new attribute modification with the following settings:
- Object type: Vehicles in Network
- Target attribute: State-of-Charge
The target attribute is the one that will be modified.
When will it be modified? This is defined by the time settings to the left: The start and end time define the duration when this modification is active. The period defines how often the modification is executed: in every simulation time step, or for example only every 10th time step.
Finally, the execution type defines if the modification is to be executed during a simulation run (like here at time step start), or at the beginning or the end of a simulation.
By the way: These settings are very similar to the settings of scripts and work in the same way.
As the next step you define how the new value for the desired attribute is computed. This is where you define your formula for energy consumption. The formula editor works in the same way as in other places in Vissim.
When pressing the button marked X, all attributes for the selected object type are listed. Here these are the vehicle attributes.
Let’s start very simple: for every time step, reduce the charge state by 0.01%. So from this list, choose State-of-Charge. Here the attribute is also available in the Fast access section as we have used it before.
Now watch the simulation.
To see the attribute change, have a look in the vehicle list.
Another option is to show the State-of-Charge as vehicle label.
Or in 3D mode as 3D information sign. This needs to be done outside the simulation.
I’ve already prepared the style of such a sign for you, so let’s just add it from a predefined file using Read Additionally.
Start the simulation again and switch to 3D mode…
Now, what happens if the bus drives faster? To check, just increase the speed of the bus to 60 km/h. Well, the discharge rate stays the same as it depends only on the simulation time. This obviously is not realistic.
Therefore, stop the simulation and modify the computation formula to be speed-dependent:
We just use the square of the speed and scale it by an artificial factor of 100000. This is only to be able to show you some effect during the simulation as such that the factor changes in short time.
In the field, the discharge rate would be much lower of course.
Now you see that one round takes about 5% off the battery charge.
Changing again the speed to 60 km/h now also increases the energy consumption (about 10% for each round).
Besides the speed, also the vehicle acceleration should be considered in the computation formula. To test this, we add a PT stop…
..and let the bus stop every round for 5 seconds by defining a partial PT route.
Now enhance the computation formula: In addition to the speed, also the acceleration reduces battery charge state.
But – wait a minute: the acceleration can become negative as well, namely while braking. Yes, and in modern electric vehicles this actually recharges the battery. This is what happens here as well:
Sometimes just before the bus stops, you can watch the charge percentage increasing. So, besides the speed now both, positive and negative acceleration is considered, too.
But eventually the time comes when the battery is low and must be recharged.
We add a charge station next to the main road by adding another PT stop. With the context menu this is done with a single click.
Add another Partial PT route, change its alignment into the stop and set the stop parameters.
Now: How does the bus now when to enter the charge lay-by? Typically, this is done when the state of charge falls below a certain threshold value. This is exactly what we do here by using a formula-based route:
Change the route choice method to formula and define the desired threshold.
We have now routed the vehicle with low battery into the charge station. But how is the actual charge process done? By means of another attribute modification:
Duplicate the existing one and change the formula. Here in the example, we assume to have a real quick charger that increases capacity by 1% for each simulation second. So here an if condition is used to check if the current state still is below 100% and then increases it (its actually 99.5 % to avoid states > 100 due to rounding issues). If not, the charge state is set to 100.
But as we want this formula to be executed only in every simulation second (not every time step) make sure to change the period to 10.
By the way: This also increases simulation speed in contrast to an attribute modification which is to be executed in every time step. So whenever possible, try to use a period higher than 1.
Now: Can you imagine what happens if we would run the simulation now?
The charge state does not change any more and is constant at 100%. Why? Well, because the charging is done now not only on the charge link, but anywhere in the network. So, we need to restrict the charging to vehicles inside the charge station.
The easiest way to do this is to define a filter condition for attribute modification 2 so it affects only vehicles in PT stop 2:
Open the filter section and from the list of vehicle attributes choose the relation to Public Transport Stop and then Number. (This is important as you cannot compare the stop directly with “2”).
Finally, after charging is completed, the bus wants to leave the charge station. This is done by a 3rd attribute modification which is a duplicate of number 2.
Here the dwell time of the charging vehicle is modified to 0 once it is fully charged. Therefore, change the target attribute to Dwell Time.
As we have defined a time distribution of only 5 s in the partial PT route, we also must take care that the bus does not leave prematurely.
So, the if condition, which checks for the charge state, does repeatedly set the dwell time of the bus to 5 s – every simulation second. Only once the charging is finished, it is set to 0 s and the bus leaves the charge station.
Please note that also here the same filter condition is required.
Watch now the entire process.
Another option for executing attribute modifications is that you can run them manually.
So, if you don’t want to wait until the battery is low to check the recharging functionality, you can just use another attribute modification that will change the State-of-Charge to 15.
Assign run type ‘Manual’ and ensure to define it for vehicle no. 1 only 😊.
Let’s try this…
As a final step let’s see, how what we have modelled so far also works for mixed traffic.
Therefore, I’ve included some non-electric vehicles in the network.
They are distinguished by leaving the attribute State-of-Charge empty.
For the vehicle class Bus an attribute decision ensures that they enter with a value of 100 %.
If you would like other vehicle classes to be included in the energy management, simply set State-of-Charge to a value greater than 0 for them as well.
As the computation formula for energy consumption just checks for a State-of-Charge > 0 % it is used for all vehicle classes.
If you would like to have different formulas per vehicle class, you could duplicate the attribute modification and add a check for the desired vehicle class to the filter condition.
For the charge station it is important to define the route in such a way, that only electric vehicles enter it. Here this is done by checking State-of-Charge > 0 % in the route formula.
If only buses should enter this charge station, then in addition the routing decision is to be defined for vehicle class Bus only.
This way, the energy management is applied to electric vehicles only, whereas all other vehicles in the same network remain unaffected.
CHAPTER 2: EXAMPLES OF USE
Before we close, I would like to show you 4 other examples that utilize attribute modifications. All of these are included in your Vissim installation
Here a barrier is animated which controls the entry and exit of a hotel. The barrier is modelled with several 3D states, each with a different angle of the barrier bar.
The attribute modifications simply change these states based on the current state of the signal that controls the vehicle.
Taking this further, you can also model an entire car park with a guidance system. Here not only the barriers are done by attribute modifications, but also the display of remaining spaces as well as the route shares into each section of the car park:
First, the section closest to the terminal gets the majority of the traffic (as it is the most attractive one). Later, if one of the sections is fully occupied, the route shares change accordingly.
This third example shows a railway station with long distance and local trains. Alighting passengers do either exit the station or transfer to a different train. Boarding passengers originate from the station, or they transfer from another train.
The number of transferring passengers varies not only on train type, but also on each individual train. To achieve this, each passenger receives the train number when alighting from it. This is done by an attribute modification looking for pedestrians on the construction element PT vehicle.
This way alighting passengers are routed to different directions with different shares - all depending on the train line or number.
This example also shows a new functionality in Vissim 2022 which allows to define the PT line shares of boarding passengers by formulas (instead of fixed shares only). So, train numbers can also be used for boarding specific PT lines, and it is now possible to use a single waiting area on a platform even for passengers transferring from one train to another.
Finally, this is an example which uses several attribute modifications to model a simple courier service, carrying goods between 4 terminal locations. Each terminal can have different states depending on the presence or absence of goods and vehicles. You can see the state of each terminal visualized here.These states along with the transitions to another state are modelled by means of attribute modifications. The model only requires two small scripts: one for generating new goods, and another one for redirecting vehicles to other terminal if required.
Congratulations! You’ve now successfully finished the tutorial.
You’ve learned how to create attribute modifications and use them for functionality, that was not built-in directly in Vissim. While there still are applications that require scripting, for example if you would like to add vehicles or pedestrians during a simulation run, with attribute modifications you can perform advanced modelling tasks easily. Now you’re ready to continue using attribute modifications in your own projects.
Thanks for watching.