This is my implementation of the bus network simulator in Python. The branch submit is the code that I am submitting for this assignment. The branch master is my main development branch. At this point they are the same. The branch deadline1 is the code from my submission for the first deadline.

I picked Python as my programming language because it's nice. I have developed for version 2.7 since I am making use of some features only available from that version such as Counter from the collections library. Python is probably my favourite language - I like its syntax. Also, since I had used it before I did not have to learn a new language for the practical which gave me more time to focus on the actual implementation. That being said, I would like to rewrite the practical in a functional language such as Haskell or OCaml one day.

You may notice that I have changed quite a lot of code from the first deadline (branch deadline1). I have decided to rewrite the way I compute all the possible events and the total rate. Instead of recomputing these every step of the simulation, I update them dynamically depending on the last chosen event. This was kind of tricky since there are many possibilities for each event and I really hope I covered all of them. In the end it was actually quite fun and I am glad I did it. The profiling of this change is detailed in the Optimisations part.

Furthermore, I now only allow passengers to board the first bus in the bus queue (as per the requirements) as opposed to all buses in the queue like in the first version.

I have also added support for analysis, experimentation, validation and optimisation as per the requirements.

It may seem that World is a God object but it seemed like a better idea than passing around a bunch of parameters with every function call (see the funct branch in my git log) for my attempt to make the simulation more functional which was abandoned.

To run the simulator on DiCE run python2.7 run.py <inputfile> in the simulator directory.

Run any of the test files in the tests directory like so python2.7 -m tests/models_tests. Or run them all with a bash script ./tests/all. The update_tests.py and analysis_tests.py are probably not really unit tests but they work pretty well.

You can supply the following arguments:

1. input file (required) - python2.7 run.py tests/test1 will take input from file tests/test1
2. output file (optional) - python2.7 run.py tests/test1 out.txt will output to file out.txt

Updating possible events dynamically has maybe decreased the maintainability and difficulty of the code but I have benchmarked both versions with the time command on student.compute and the results are pretty impressive. The average running times over 10 runs are listed in the table below (best viewed as html):

Unit tests for validation are in the file validation_tests.py. These tests detail what inputs create warnings and errors. More information is found in the docstrings and comments of the validate methods of the world and network and the parse_lines function of the parser module.

Warnings I generate a warning on the following occasions since they don't affect the simulation in a harmful way:

1. Road rate for two stops is specified but the road is not on any route.
2. Road rate for two stops is specified but at least one of them is not on any route.
3. Road rate for a stop to itself.

Errors I generate an error on the following occasions:

1. Road rate for a road that is on at least one route is not specified.
2. Any of the rates is not specified.
3. Stop time is not specified.
4. Route has the same stop consecutively (twice in a row).
5. Route has only one stop.
6. Two routes with the same id are specified.
7. Road rate is specified more than once.
8. Stop time is specified more than once.
9. Any of the event rates is specified more than once.
10. Any of the event rates is zero.
11. Stop time is zero
12. Number of buses or capacity on any route is zero.

Some of these errors could be considered warnings, such as specifing a road rate twice (just use either one), but I think it's more beneficial to flag them as errors so the user of the system can fix them (they may have expected the other road rate to be used). I have also decided to not allow having a route with just one stop or having a route with the same stop twice in a row. Moreover, I am not allowing buses with 0 capacity, routes with 0 buses or stop time being 0.

I have made use of the termcolor library for the color_log function in the events package. In a nutshell, it gives you colored output in the terminal making it easier to distinguish between different event types in your output. This library has MIT license and is located in lib/termcolor.py.

In conclusion, I thank you for this assignment - it was quite fun to finally do some actual coding. At first I was aiming for the early submission bus since I was working part-time and 3rd year is generally pretty busy I thought I'd rather do it properly than rush through it and make mistakes. Don't get me wrong, I still think that there are improvements I could make to my simulator (as always) but I think I definitely spent at least the recommended 100 hours on this.