-
Notifications
You must be signed in to change notification settings - Fork 0
User Manual
The core simulation of Bike Balance runs in Python 3.10+ and relies on NumPy and SciPy. If you're not sure whether you have NumPy and SciPy installed, you can try running the simulation and a pop-up window will inform you if a package is missing.
If the simulation fails to launch entirely, try setting the Python interpreter to the direct path of your Python installation:
- Open the Settings tab near the top right corner of the window.
- Type in or paste the path to your Python installation, e.g., "C:/Users/<user>/AppData/Local/Programs/Python/Python311/python.exe" and press return.
Simulation parameters can be adjusted prior to running the simulation using the Agent, Simulation, and Station tabs, as well as the map.
The Agent tab sets parameters related to the agent rebalancing bike stations.
-
Start Station- The index of the station at which the agent begins its excursion
-
End Station- The index of the station at which the agent ends its excursion
-
Excursion Time- The length of time within the simulation before the agent should arrive at the End Station.
-
Agent Mode- The strategy used by the agent to determine its actions
- Basic uses a simple greedy algorithm that finds the next station with the highest immediate reward per trip time.
- Smart uses a limited Monte Carlo tree search to estimate the best next station to earn the highest overall reward over the course of the excursion.
The simulation tab sets general simulation parameters.
-
Warmup Time- The amount of simulated time before the agent begins its excursion
- Warmup time allows the stations to become more unbalanced and increases the overall rewards available.
-
Mode-
Single Run- Simulates the agent taking a single excursion.
- If no static seed is used, a random seed will be generated.
-
Batch- Performs replications of the single excursion simulation using random seeds.
-
-
Randomize Start/End Station- If this box is checked, each replication uses random start and end stations. The currently selected start/end station settings in the other tabs and map are ignored.
-
Confidence Level- The confidence level used to determine the margin of error for batch results.
-
Parallel Batch Size- The number of replications to run as parallel processes. Batch simulations iteratively run parallel batches of this size until the target sample size or precision is reached (depending on Batch Mode).
-
Max Runtime- If a simulation batch exceeds this runtime (in real time), the process will stop (regardless of other parameters).
-
Batch Mode-
Fixed Sample Size- The simulation batch will run the given number of replications (rounded up to the nearest multiple of the selected Parallel Batch Size).
-
Precision Based- The program progressively calculates the margin of error for results and the replications stop once one of the given margin of error thresholds is met for every statistic.
-
Min sample size- The minimum number of samples before the program begins calculating margin of error. If this value is too low, the margins of error in the results will be inaccurate.
-
Markers indicate bike stations, labeled by index for indentification. The green marker indicates the agent's start station, and the checkered marker indicates the agent's end station.
- Click and drag the map to pan, and use the scroll wheel to zoom.
- Click on a station to bring up information about it in the Station tab (the lower right section of the main window).
In the Station tab, press the slider next to Is Start Station or Is End Station to set the currently selected station to be the agent's start or end station respectively. Note that theses sliders are hidden when the Results tab is open. To show the sliders, select the agent or Simulation tab in the top right of the main window.
The ID shown in the Station tab is used by Citi Bike to identify stations, while the index shown on the marker is used by this software and the backend simulation.
Press Run Simulation at the bottom right of the main window to run the simulation (or batch of simulations, depending on your parameters).
Press Cancel while the simulation is running to stop early without getting or saving results.
After the simulation is complete, the Results tab will open automatically and statistics about the simulation will be displayed.
The path taken by the agent is drawn on the map, and the sequence of actions taken by the agent are listed at the end of the results.
Actions are displayed in the following format:
> <current_station> (<current_time>)
Rent: <indices of stations with rental rewards>
Return: <indices of stations with return rewards>
⭕ <bike/walk> to <next_station> (<trip_duration>) +<reward_gained>
Station-specific results are displayed in the Station tab when the Results tab is open.
The results shown in the Results tab are the mean values of the statistics from single run results, with the margins of error calculated based on the given confidence level.
There is no map information for batch results currently.
Results are saved to a timestamped JSON in results/ every time a simulation (or batch) is run. The filepath of displayed results is given at the top of the Results tab.
Logs can be enabled in simulate.py for saving terminal outputs to logs/, but that is beyond the scope of this user manual. Any Python errors that occur during simulation are reported to the user in a pop-up window.
On exit, the program prunes the oldest results and logs in the results/ and logs/ directories until the number of results and logs is each less than or equal to the maximum of 20. Only results and logs with the exact timestamped format generated by the program are counted and pruned. To save results or logs, rename them or move them to a different directory (e.g. saved_results/).