| title | author | date | output |
|---|---|---|---|
RunVehicleCirculation Documentation |
gmarburger |
11/8/2020 |
markdown |
This is the documentation for the program RunVehicleCirculation which creates vehicle circulations for MATSim scenarios. RunVehicleCirculation is integrated into the program GTFS2MATSim, such that TransitSchedules may be created with vehicle circulations.
Each method has its own explanation. Firstly, input is written in italics along with an explanation of the input and what is expected from the user. Secondly a short description of the method follows including some of the key elements. of the function. Some methods had design choices which are also briefly explained.
create()
scenario A MATSim scenario
minTimeToWait Minimal time difference for a vehicle after ending a route and serving the next Departure
overrideDelay If minTimeToWait should be overwritten. Useful to create less S + U Vehicles in the Berlin Scenario
This is the main part of the program. It will call other functions so as to create vehicle workings for the scenario considering the integer minTimeToWait. If overrideDelay is set to true the program will override the integer and set it to 900 seconds for TransitRoutes from the S-Bahn and U-Bahn.
Design Choices
Firstly two Maps are being created to document which new TransitVehicles should be added to the TransitVehicles dataset as well as which nodes should be connected. At the end of the code it will call another function addTransitVehicles() to add the previously created vehicles.
While iterating through the TransitSchedule this function will call other functions. Firstly will it call getMapOfAllDeparturesOnLine() to create a TreeMap. Instead of iterating through each TransitLine I found it easier to simply iterate through a Map with Departures sorted by DepartureTime.
If the TransitVehicle of a Departure was already created by this function the Departure will remain unchanged. If however the Departure has not yet been modified a new vehicle will be created and assigned to this Departure. It will be added to the previously mentioned Map. The integer used to create these Ids will be increased by one.
The function getNextDepartureFromEndstation() will be called to change future Departures.
The end of the function is marked by the output of a string containing the amount of newly created vehicles.
getMapOfAllDeparturesOnLine()
transitLine A MATSim TransitLine
Since this program is being used to create vehicle workings for an entire TransitLine, this method collects every Departure of every TransitRoute and orders them by departure time.
Design Choices
Due to complications with other methods and writing my own comparator, I decided to use a String replacing a comparator for the TreeMap. Generally this should not be an issue, even though it might not appear clean. The keys in the Map are the departure times from the Departures, they are ordered as Strings. The Strings consist of 27 characters, the first 7 indicate which time the TransitVehicle leaves the station. The other 20 are only used to create a unique key for the Departure. Currently DepartureIDs are unique, with a length of 11 characters. These last 20 are however needed, since it is possible to have the exact same departure time at two different stops.
getUmlaufVecId()
transitLine A MATSim TransitLine
iteration This is an integer that should be used for an Id
This method creates a new TransitVehicleID containing information about the TransitLine.
getRouteFromDeparture()
transitLine A MATSim TransitLine
departure A MATSim Departure
Returns the TransitRoute which corresponds with departure.
Design Choices
Currently GTFS2MATSim Departures already contain information about the TransitRoute. A simple String parser can return information about which TransitRoute is being served by a TransitVehicle. After looking at other programs that create TransitVehicles I preferred a more complicated approach at returning the TransitRoute, since so as future programs on this basis are less prone to complications.
I am aware that this method requires more resources due to large TransitLines especially in Berlin, however I believe that iterating over each TransitRoute and Departure is justified.
getEndStationFromRoute()
transitRoute A MATSim TransitRoute
Returns the last stop of a TransitRoute.
getNextDepartureFromEndstation()
mapOfAllDeparturesOnLine A Map which holds all Departures from a TransitLine
transitLine A MATSim TransitLine
currentDeparture The Departure which is currently being modified, the next modified Departure will use this vehicle
setOfVecOnLine A Set of all vehicles which have already been created by this program
minWaitTimeAtEndStation Minimal time a vehicle should wait until it servers the next Departure
network A MATSim network
iteratorLinkId Integer which is used for unique LinkIds
setOfCreatedLinks Set of all previously created links
overrideMinDelay If minTimeToWaitAtEndStop should be overwritten. Useful to create less S + U Vehicles in Berlin Scenario
Sets following parameters: A VehicleId from the currentDeparture, the last Stop of the transitLine and the duration the vehicle has to wait to serve a new Departure. This parameter depends on the Boolean overrideMinDelay. If it is set to true transitLines of S-Bahn or U-Bahn will have a turn-over time of 15 minutes, else it will have a turn-over time of minWaitTimeAtEndStation. This turn-over time symbolizes the time the vehicle waits at the last stop of the transitLine before it could start a new Departure at this node.
To find a new Departure for the vehicle this method iterates over all Departure of mapOfAllDeparturesOnLine to find the next Departure which meets the requirements.
meetsRequirements()
departureTimeAtNewLocatiom Departure time at the new stop
earliestPossibleDepartureTime Arrival time of old TransitRoute stop plus min turn-over time
startStopName Name of the next possible stop
endStopName Name of the last stop on the current TransitLine
This method was created to make it possible to interchange filtering options. It is used to check, if a TransitRouteStop can be used as a new starting stop for the TransitVehicle. Currently, it returns true if:
- The departure time is greater than the earliest possible starting time
- The stop names are equal or if one is contained in the other
Design Choices
This adjustment was made after running into issues with the Berlin bus line M44. It ends in a stop name called "Alt-Buckow" and the next first stop would be called "Alt-Buckow [Dorfteich]". If this method proves faulty it will be changed back to the 2nd element being "stop names have to be equal".
addTransitVehicles()
transitVehicles A MATSim TransitVehicles dataset
mapOfVehicles A Map of VehicleIds as key set with their corresponding VehicleType
Iterates through the Map and creates for each Id a vehicle with the corresponding VehicleType. Afterwards it is added to the TransitVehicles dataset.
addLinkBetweenEndAndStart()
network A MATSim network dataset
startStop The stop which should be connected to the other stop. This will be the to-Node
endStop The stop which should be connected. This will be the from-Node
iterator A unique integer to identify the link
setOfCreatedLinks This is a place-holder and currently not in use, however I might want to add a functionality to identify already created links to be able to reduce the amount of newly created links
Reads the Nodes from both stops and afterwards creates a link to connect both. The end of a link is the startStop-Node, the beginning is the endStop-Node. The link is also added to the network.
The iterator is used to create unique names for the links. The prefix 'umlauf' is used to determine the links created after a simulation has run. The iterator is also increased by one before it is returned.
Design Choices
Important aspects of link creation are as follows:
- length is set to 50, since this is the same length as the loop for a beginning of a TransitRoute.
- freespeed is set to 10, which is a big value to insure rapid passage across the link.
- capacity is set big enough to store vehicles.
- lanes is set to a value greater than 1, so that vehicles could overtake one another. It could be possible for vehicles in the program to have to overtake another to be able to serve a Departure.
writeFiles()
scenario a MATSim scenario
This functionality is currently not in use. It was created so as network, transit-schedule and transit-vehicles files may be created.