Home

A Guide to Running bussim

A lot of this will be using the bash shell. Look up unix shell or linux shell or bash shell for some basic knowledge if you think that might help.

Setup

First things first, let's do some setup. We're going to assume you are logged into a Mac or Linux computer and go is installed. The Linux machines provided by UCSC fulfill this requirement. Open a terminal and run this command:

echo "export PATH=\$PATH:$HOME/go/bin" >> ~/.bashrc

This command only has to be run once! After you run it, close the current terminal and open a new one. This will allow you to easily run programs installed with go get (or go install).

Installation

This part is easy - just run

go get github.com/spencer-p/bussim

in the terminal. Now if you try to run the command bussim it should output this:

Usage of bussim:
  -input string
    	Input JSON file
  -output string
    	File to output JSON agent history

Congrats, we have it up and running!

Updating it

The simulation will likely be updated to be better of perhaps to fix bugs. To update, run this command:

go get -u github.com/spencer-p/bussim

Note the -u (for update).

Using it

Running the program looks like this:

bussim -input <MY_INPUT_FILE_NAME_HERE> -output <MY_OUTPUT_FILE_NAME_HERE>

Obviously we need some input files. Check out the example input in the repo for a start.

Be careful about naming your output files. If you specify a file that already exists, bussim will overwrite that file with new simulation results.

Getting around with Linux

There should be an easy to find file manager (probably called "Files") that will let you graphically manage your files. You can choose to manage input and output files however you like. If you drag and drop a file onto the terminal, it will copy the file location in (so you don't have to type it yourself!).

There should also be a text editor (probably called "Text Editor") that you can use to create your input files and view output files.

Input fields

Bus routes

Field	Description
ToStop	The bus stop that this bus goes to
FromStop	The bus stop this bus comes from
Distance	Distance between those two stops (unit doesn't matter)
Capacity	Number of people that can ride said bus
Speed	Speed at which the bus travels (units per hour)
VehicleCount	Number of buses running this route

Please note that to encode an entire bus route, you must specify one of these objects for each connection between bus stops. Also be aware that these bus routes are unidirectional - the bus does not go both ways unless you have two objects with the from/to swapped.

Agents

The agents are not literal agents but information to generate agents.

Field	Description
Count	Number of agents to generate
Destination	Where the generated agents will be headed
Start	Where the generated agents will start from
MaxLeaveTime	The time that agents leave in the morning will be in the range [0, MaxLeaveTime] (integer, minutes)

Errors

Short errors that say something readable in english will probably be input errors. Double check to make sure your starts and destinations are actual bus stops and that the commas and brackets match properly.

If something long and gross with lots of numbers comes out, then save the error and send it to me, since it is probably my fault.