seSue is an open source tool to aid research on static path-based Stochastic User Equilibrium models.
Stochastic User Equilibrium (SUE) is a relaxation of Wardrop's equilibrium principles which is defined as the traffic equilibrium wherein no driver can unilaterally change routes to improve his/her perceived travel times.
A path-based SUE model alone transforms the following inputs:
into SUE link and path flows.
On the other hand, SUE is one of the most popular methods that is used as the traffic assignment procedure within many other applications.
Typically, discrete choice models are associated with the stochastic route choice behavior of the users in a SUE model. The same choice model may be assigned for all users or different choice models may be assigned to the users in different OD pairs (hybrid). SUE models are distinguished with respect to the associated discrete choice models as different route choice behaviors lead to different equilibrium flows.
Another factor that significantly affects the equilibrium flows in a path-based SUE model is choice set generation. In a real-sized traffic network, there exist a huge number of cycle-free paths, or routes, connecting an origin to a destination; and possibly infinitely many paths when cycling is allowed. In general, a route choice set containing 'efficient' routes is generated for each OD pair a priori to finding the SUE flows.
Since the users will be assigned to the predetermined routes, the size of the route choice sets and the routes included play an important role in the equilibrium flows. Computationally, the increase in the size of the route choice sets increases the running time for both generating the paths and solving the SUE model; while a small choice set may result in unrealistic assignments.
seSue is a Windows Forms Application developed with .NET Framework 4.5.
It is designed to carry out experiments to analyze the effects of:
on the route choice probabilities and equilibrium link flows.
It also allows to carry out sensitivity analysis to predict the effects of perturbations in the OD demands and generalized link travel cost functions.
Current version of seSue allows to associate the following discrete choice models and their combinations with the path-based SUE model, in addition to the Wardrop's (1952) user equilibrium:
Path generation algorithms listed below and their combinations can be used to generate the route choice sets of the OD pairs:
Data files of real cities that can be readily used with seSue are provided in the Downloads section. These data files are converted from the data files published in http://www.bgu.ac.il/~bargera/tntp/, which is an excellent source of transportation network test problems. The website is managed by Professor Hilel Bar-Gera and the data files are provided by valuable researchers. Custom networks can also be created and analyzed with seSue. A Macro-enabled Excel workbook (xlsm) that converts spreadsheets to seSue data files is provided in the Downloads section.
Method of Successive Averages (MSA) algorithm implemented in seSue can be used to find the equilibrium flows of all provided SUE models in order to allow fair comparison of convergence performances.
seSue allows visualization of congestion in road networks by color-coding the links with respect to the amount of traffic, travel costs or traffic density of the links.
Finally, a Sensitivity Analysis module is available. In particular, it allows to carry out sensitivity analysis with respect to perturbations in the OD demands and link cost functions.
Setup files of the latest version (v1) of seSue can be downloaded using the link below.
Source codes of the latest version (v1) of seSue and of the included libraries can be downloaded using the link below.
Data files converted from the data files published in Professor Hilel Bar-Gera's website http://www.bgu.ac.il/~bargera/tntp/ can be downloaded using the link below.
Marco-enabled Excel file to create custom network topologies can be downloaded using the link below:
Download the setup files seSueSetup.zip.
Unzip the folder, double click setup.exe file, and follow the instructions of the setup wizard.
A desktop shortcut should be created in the Desktop. Use this shortcut or search seSue in programs to run seSue.
In this part, the steps to create a custom seSue file using the macro-enabled Excel workbook are explained. The steps will be illustrated on Braess network displayed in the figure on the left which has a single OD pair a-d.
The minimal information that needs to be entered in the workbook to create a seSue file includes:
In addition, the following information may be entered in the workbook:
Alternatively, paths may be generated and / or route choice models may be entered later using the software.
Download the macro-enabled workbook SueFileGenerator.xlsm.
In order to use the data file generator, you need to enable the macros. If you need help in enabling macros, follow the instructions in the following link.
It is not required for this tutorial, however you can check the instructions in the UserGuide worksheet of the file for details.
The sample network has 5 links: a-b, a-c, b-c, b-d, and c-d.
Open the Arcs worksheet and enter the links and corresponding link travel cost coefficients as follows.
The sample network has a single OD pair, a-d with a demand of 6 users.
Open the ODs worksheet and enter the OD pair information as follows.
seSue data file with minimal information is ready to be created. Perform the validation checks and create the seSue data file with the following steps:
Open the created SUE file by
The sample network has a single OD pair with three possible routes: a-b-d, a-b-c-d, and a-c-d.
In real-sized traffic networks, there may exist a huge (or ininite) number of routes. A subset of 'efficient' routes may be generated using the algorithms provided in seSue.
In this part, the method of providing the route choice set externally to seSue is illustrated.
Follow the steps 2.1.1., 2.1.2., and 2.1.3. to enter the links and OD pairs of the network.
You may enter any subset of the routes that you want to include in the route choice set. In this example, three of the routes will be entered in the Paths workseet as follows.
Follow the step 2.1.4. to create the seSue file with the routes.
Route choice models of OD pairs can be assigned using the wizards of seSue.
Alternatively, they may be assigned during data file generation step as will be described in this section. Suppose that we would like to set the route choice model of OD pair a-d as the multinomial logit (MNL) model with a dispersion parameter of 0.1.
Follow the steps 2.1.1., 2.1.2., and 2.1.3. to enter the links and OD pairs of the network.
Add the choice model information in the ODs worksheet as follows.
Follow the step 2.1.4. to create the seSue file with the assigned choice model.
In this section, we generate a seSue file with both a working route choice set and assigned choice models.
Alternatively, they may be assigned during data file generation step as will be described in this section. Suppose that we would like to set the route choice model of OD pair a-d as the multinomial logit (MNL) model with a dispersion parameter of 0.1.
Follow the steps 2.1.1., 2.1.2., and 2.1.3. to enter the links and OD pairs of the network.
Follow the step 2.2.1. to enter the paths.
Add the following information in the ODs worksheet as follows to set the choice model as the path-size logit (PSL) model with dispersion parameter 0.1.
Follow the step 2.1.4. to create the seSue file with the routes and assigned choice model. Notice that path-sizes are included as the deterministic correction terms.
Model files of seSue use extension .sue. Therefore, files generated with SueFileGenerator.xlsm and created by seSue automatically have this extension.
When the software is set up in your computer, the extension .sue is associated with seSue.
Download the file SiouxFalls.zip, and unzip to extract the seSue file.
You can simply open the file with seSue by double clicking the file SiouxFalls.sue in the file explorer window.
Alternatively, you can run seSue by using the shortcut created on the desktop or searching it in the programs; and then click File > Open, or Ctrl + O, to browse and open the file.
It is important to note that opened sue files are read into memory and they are not locked.
In order to save the changes made in a sue file, you may click File > Save, or press Ctrl + S. This will overwrite the existing file.
In order to save the file with a different name use File > Save As, or Ctrl + Alt + S.
In this section, path generation algorithms implemented in seSue to generate route choice sets are be explained.
Available algorithms in the current version are as follows:
Download SiouxFalls.zip, extract and open SiouxFalls.sue file which includes 528 OD pairs and no paths yet (Step 3.1).
Click Path Generation > Yen's Algorithm to open the algorithm's form.
The form has three inputs:
Once the inputs are provided, click RUN button to run the algorithm. You will be prompted the running time of the algorithm as soon as the search is complete. Then close the algorithm's form with the x button, and go to Paths tab to check the generated routes. Also check the Graph tab to observe the statistics related with routes.
Download SiouxFalls.zip, extract and open SiouxFalls.sue file which includes 528 OD pairs and no paths yet (Step 3.1).
Click Path Generation > Dial's Algorithm to open the algorithm's form.
The form has five inputs:
Once the inputs are provided, click RUN button to run the algorithm. You will be prompted the running time of the algorithm as soon as the search is complete. Then close the algorithm's form with the x button, and go to Paths tab to check the generated routes. Also check the Graph tab to observe the statistics related with routes.
Download SiouxFalls.zip, extract and open SiouxFalls.sue file which includes 528 OD pairs and no paths yet (Step 3.1).
Click Path Generation > Link Penalty to open the algorithm's form.
The form has five inputs:
Once the inputs are provided, click RUN button to run the algorithm. You will be prompted the running time of the algorithm as soon as the search is complete. Then close the algorithm's form with the x button, and go to Paths tab to check the generated routes. Also check the Graph tab to observe the statistics related with routes.
Download SiouxFalls.zip, extract and open SiouxFalls.sue file which includes 528 OD pairs and no paths yet (Step 3.1).
Click Path Generation > Link Elimination to open the algorithm's form.
The form has three inputs:
Once the inputs are provided, click RUN button to run the algorithm. You will be prompted the running time of the algorithm as soon as the search is complete. Then close the algorithm's form with the x button, and go to Paths tab to check the generated routes. Also check the Graph tab to observe the statistics related with routes.
Download SiouxFalls.zip, extract and open SiouxFalls.sue file which includes 528 OD pairs and no paths yet (Step 3.1).
Click Path Generation > Link Penalty > Link Elimination to open the algorithm's form.
This procedure sequentially runs Link Penalty and Link Elimination algorithms. Routes generated with Link Penalty algorithm are kept, and new routes found by the Link Elimination algorithm are appended to the route choice set.
The form has six inputs:
Once the inputs are provided, click RUN button to run the algorithm. You will be prompted the running time of the algorithm as soon as the search is complete. Then close the algorithm's form with the x button, and go to Paths tab to check the generated routes. Also check the Graph tab to observe the statistics related with routes.
Click Path Generation > Link Elimination > Link Penalty to open the algorithm's form.
This procedure sequentially runs Link Elimination and Link Penalty algorithms. Routes generated with Link Elimination algorithm are kept, and new routes found by the Link Penalty algorithm are appended to the route choice set.
The instructions are the same with Link Penalty Algorithm followed by Link Elimination Algorithm except for the running order of the algorithms.
The two procedures Link Penalty Algorithm followed by Link Elimination Algorithm and Link Elimination Algorithm followed by Link Penalty Algorithm are two combinations of the path generation algorithms.
Procedures with other combinations may be carried out with seSue as well by using the:
and running the desired algorithms sequentially.
In this section, route choice model assignment to the OD pairs by Choice Model Wizards is explained.
Available discrete choice models in the current version are as follows:
It is important to note that the route choice sets need to be generated a priori to choice model assignment.
Download SiouxFallsWithPaths.zip, extract and open SiouxFallsWithPaths.sue file which includes 528 OD pairs and 5280 paths generated with Link Penalty algorithm.
Click Choice Model Wizard > Deterministic. The wizard has a single step.
All OD pairs in the network are listed in the 'Apply To' tab. Check the OD pairs to which you want to assign a choice model.
The OD pairs with no assigned choice models will be automatically selected.
You can double-click on the data table to check / uncheck all OD pairs.
In order to proceed at least one OD pair needs to be selected.
After selecting the desired OD pairs, click Finish.
Once you have finished the steps of the choice model wizard, open the 'OD Pairs' tab to check the choice model assignment.
The key word Det(max) corresponds to utility maximization with a deterministic utility function.
Resulting model is the user equilibrium (UE) model, the solution of which satisfies Wardrop's (1952) principles.
Download SiouxFallsWithPaths.zip, extract and open SiouxFallsWithPaths.sue file which includes 528 OD pairs and 5280 paths generated with Link Penalty algorithm.
Click Choice Model Wizard > Logit. The wizard has four steps.
All OD pairs in the network are listed in the 'Apply To' tab. Check the OD pairs to which you want to assign a choice model.
The OD pairs with no assigned choice models will be automatically selected.
You can double-click on the data table to check / uncheck all OD pairs.
In order to proceed at least one OD pair needs to be selected.
After selecting the desired OD pairs, click Next.
This is the main step that defines the settings of the choice model.
The two dropdown lists at the top of the form correspond to:
As you change the settings, check the formulations below to understand the corresponding models and route choice probability expressions.
The parameters that will be used in the assignment can be entered in the Parameters data table.
After selecting the desired settings and entering the values of the parameters, click Next.
The data table in this step displays the assigned dispersion parameters (theta) according to the selected dispersion parameter setting in the previous step for the OD pairs that are selected in 'Apply To' tab.
If these are the desired dispersion parameters, click Next to proceed.
You can also customize the model by manually changing the dispersion parameters of the desired OD pairs.
The data table in this step displays the assigned correction terms according to the selected deterministic correction parameter setting in the 'Settings' tab for the OD pairs that are selected in 'Apply To' tab.
If these are the desired correction terms, click Finish to complete the choice model assignment.
You can also manually update the deterministic correction terms in the 'CT' column.
Once you have finished the steps of the choice model wizard, open the 'OD Pairs' tab to check the choice model assignment.
Download SiouxFallsWithPaths.zip, extract and open SiouxFallsWithPaths.sue file which includes 528 OD pairs and 5280 paths generated with Link Penalty algorithm.
Click Choice Model Wizard > Weibit. The wizard has four steps.
All OD pairs in the network are listed in the 'Apply To' tab. Check the OD pairs to which you want to assign a choice model.
The OD pairs with no assigned choice models will be automatically selected.
You can double-click on the data table to check / uncheck all OD pairs.
In order to proceed at least one OD pair needs to be selected.
After selecting the desired OD pairs, click Next.
This is the main step that defines the settings of the choice model.
The dropdown list at the top of the form correspond to the deterministic correction term setting:
As you change the settings, check the formulations below to understand the corresponding models and route choice probability expressions.
The parameters that will be used in the assignment can be entered in the Parameters data table.
After selecting the desired settings and entering the values of the parameters, click Next.
The data table in this step displays the assigned shape (beta) and location (xi) parameters of the underlying Weibull distribution of the weibit model according to the entered parameters in the previous step for the OD pairs that are selected in 'Apply To' tab.
If these are the desired dispersion parameters, click Next to proceed.
You can also customize the model by manually changing the shape and location parameters of the desired OD pairs.
The data table in this step displays the assigned correction terms according to the selected deterministic correction parameter setting in the 'Settings' tab for the OD pairs that are selected in 'Apply To' tab.
If these are the desired correction terms, click Finish to complete the choice model assignment.
You can also manually update the deterministic correction terms in the 'CT' column.
Once you have finished the steps of the choice model wizard, open the 'OD Pairs' tab to check the choice model assignment.
This wizard helps assign Marginal Distribution Model with exponential marginal distributions as the route choice model.
Download SiouxFallsWithPaths.zip, extract and open SiouxFallsWithPaths.sue file which includes 528 OD pairs and 5280 paths generated with Link Penalty algorithm.
Click Choice Model Wizard > MDM with Exponential MDs. The wizard has three steps.
All OD pairs in the network are listed in the 'Apply To' tab. Check the OD pairs to which you want to assign a choice model.
The OD pairs with no assigned choice models will be automatically selected.
You can double-click on the data table to check / uncheck all OD pairs.
In order to proceed at least one OD pair needs to be selected.
After selecting the desired OD pairs, click Next.
This is the main step that defines the settings of the choice model.
The two dropdown lists at the top of the form correspond to:
As you change the settings, check the formulations below to understand the corresponding models and route choice probability expressions.
The parameters that will be used in the assignment can be entered in the Parameters data table.
After selecting the desired settings and entering the values of the parameters, click Next.
The data table in this step displays the assigned route-specific rate and location parameters of the exponential marginal distributions according to the selected settings in the previous step.
If these are the parameters, click Finish to complete the choice model assignment.
You can also customize the model by manually changing the exponential distribution parameters of the desired routes.
Once you have finished the steps of the choice model wizard, open the 'OD Pairs' tab to check the choice model assignment.
This wizard helps assign Marginal Distribution Model with normal marginal distributions as the route choice model.
Download SiouxFallsWithPaths.zip, extract and open SiouxFallsWithPaths.sue file which includes 528 OD pairs and 5280 paths generated with Link Penalty algorithm.
Click Choice Model Wizard > MDM with Normal MDs. The wizard has three steps.
All OD pairs in the network are listed in the 'Apply To' tab. Check the OD pairs to which you want to assign a choice model.
The OD pairs with no assigned choice models will be automatically selected.
You can double-click on the data table to check / uncheck all OD pairs.
In order to proceed at least one OD pair needs to be selected.
After selecting the desired OD pairs, click Next.
This is the main step that defines the settings of the choice model.
The two dropdown lists at the top of the form correspond to:
As you change the settings, check the formulations below to understand the corresponding models and route choice probability expressions.
The parameters that will be used in the assignment can be entered in the Parameters data table.
After selecting the desired settings and entering the values of the parameters, click Next.
The data table in this step displays the assigned route-specific means and standard deviations of the normal marginal distributions according to the selected settings in the previous step.
If these are the parameters, click Finish to complete the choice model assignment.
You can also customize the model by manually changing the normal distribution parameters of the desired routes.
Once you have finished the steps of the choice model wizard, open the 'OD Pairs' tab to check the choice model assignment.
In order to find the SUE flows, the following should be satisfied:
Once these two steps are completed, the SUE flows can be obtained by the same MSA algorithm that can be used with all implemented route choice models.
Download SiouxFallsMSA.zip, extract and open SiouxFallsMSA.sue file.
Open 'MSA' tab and click on the button on the left ('MSA (Standard(1,0),100,0.01)') to open the settings of the algorithm.
The implemented algorithm uses two stopping conditions:
Four different step size settings are available in the current version of seSue which can be selected using the dropdown list:
Check the formulations displayed on the right when you change the step size setting, where alpha(n) designates the step size at the nth iteration of the MSA algorithm.
Click the Run button in the 'MSA' tab to run the algorithm.
You will be prompted the running time and number of iterations until the algorithm converged.
The data table in the 'MSA' tab shows the following information at each iteration of the MSA algorithm:
The last row of this data table corresponds to the SUE flows.
Once the SUE model is solved, SUE link flows and link travel costs can be observed in the 'SUE View' tab of the 'Links' tab.
Route choice probabilities, SUE path flows and route travel costs can be observed in the 'Paths' tab.
Download SiouxFallsSolved.zip, extract and open SiouxFallsSolved.sue file.
The sue file contains route choice sets, assigned choice models and the SUE solution.
Click Report > Network Visualization to open the network visualization module.
The module has two settings:
Once you have entered the desired settings, click Generate button to create the network visualization. The sample network below displays the network elements for OD pair 1-9, where the least (most) congested links are colored by green (red).
Sensitivity Analysis module allows to analyze the effects of the perturbations in:
on the equilibrium flows, costs, and choice probabilities.
Download SiouxFallsSolved.zip, extract and open SiouxFallsSolved.sue file.
The sue file contains route choice sets, assigned choice models and the SUE solution.
Click Sensitivity Analysis > Perturb OD Demand to open the network visualization module.
The form includes three settings.
Click the RUN button when the settnigs are determined. For the settings in the example above, seSue will
Note that original OD demands and MSA settings will be stored at the end of the MSA runs for the sensitivity analysis.
Open 'Reports' tab to analyze the effects of OD demand perturbation.
Reports of the changes in the following metrics are available:
For all metrics, values of the selected metrics are presented in the columns with the values of epsilon as the header (columns 1, 0.5 and 2 in the above example), while the columns with headers starting with Delta display the percent deviations from the current SUE solution (column 1 in this example).
Steps to carry out sensitivity analysis for Perturbations in link FFTT are exactly the same with the steps described above.
This software is developed by
at the Engineering Systems and Design (ESD) pillar in Singapore University of Technology and Design (SUTD).
Address: 8 Somapah Road, Singapore 487372 (view directions).
We would love to have feedback on seSue. Please send your comments, questions, etc. to ugur_arikan@sutd.edu.sg .