Package: bussim2
bussim2Table of contents[[TOC]]Installationpip install bussim2AboutBussim is a program created to estimate depot energy and power needs. It has been created to work with MTA data, but could be altered to accept data from other agencies.The program works by simulating realworld bus activity, simulated using theSimPy Python module. SimPy is a "process-based discrete-event simulation framework based on standard Python." Buses are "dispatched" to run blocks (which are sequences of bus trips). Bus simulations are run for a predetermined period of time: They are given a real start date and a number of days to run for. Start dates should be in 2022, as the simulation loads the MTA's 2022 holiday calendar. The simulation also optionally loads real world hourly temperatures for 2022.Bus dispatchesoccur based on provided block files, which are contained in bussim2/sources/blocks.db. Buses will only be dispatched for a particular block if they have enough battery state of charge to complete service. Any bus with enough available battery for a block can be dispatched, whether or not it is actively charging. Dispatch behavior can also be adjusted with an optional waittime paramter, to allow the dispatcher to either cancel a block immediately if no bus is available, or to wait for a given amount of time.Bus charging behavioris meant to simulate realworld bus behavior. When buses get back to the depot, they either begin charging (with an optional buffer) or, if no chargers are available, they queue for a charger.Bus charging speedis limited by charger power, depot power supply and an optional peak time power constraint. If total charging speed exceeds depot power supply, busses will share available power equally. The simulation can also account for solar energy and energy storage installations that can be used to raise the maximum charging speed of the depot.Bus energy consumptionis determined by formulas included in bussim2/utilities.py. These formulas were calculated by performing nonlinear "MARS" regressions on real world std and art bus data, with energy consumption a function of block speed and outside temperature. This modeling work was done separately, and code is not contained in the bussim codebase.Running a simulationThe easiest way to create a bussim simulation and to view outputs is from the command line. After installing bussim2, a basic simulation can be run from the command line. The following command will generate a bussim report using the default configuration, will output a simulation report in the folder "report_dir", and will then open an HTML file with report details.%python-mbussim2make_report-sDEFAULT-oOUTPUT_DIRScenarios can be configured for reports, and available scenarios can be listed, with with the following commands:%python-mbussim2config# configure bussim scenarios%python-mbussim2scenarios# view available scneariosA minimization routine can be created using the following command. This routine finds the scenario for the given depot with the lowest possible number of buses, chargers, and power supply under which all block service can be fullfilled. The final resulting scenario will be the same as the output for a normal bussim. Note that running a minimization process can take around 10 minutes, as a few dozen bussim scenarios will be run to discover a working minimum scenario.%python-mbussim2min-dDEPOT-oOUTPUT_DIRWhile the command line is the easiest way to create bussim simulations, more powerful simulation analysis can be performed when bussim is used within an interactive python environment, especially within a Jupyter Notebook. Within a Python environment, the bussim program operates by creating "BusSim" objects that represent a self-contained simulation of a bus depot providing electric bus service.Objects are created by creating a new object with required arguments and assigning the object to a variable so that it can be accessed later. For example:importbussim.bussimasbs# set variablesdepot_name="KB"#KB for Kinsbridgenum_days=3charger_power=150...# create bus sim objectbus_sim=bs.BusSim([variablesgohere])# optionally use a preconfigured scenariobus_sim=bs.config_sim(scenario="DEFAULT")Once you have created a bussim object you can then generate plots or access details about its operation - such as the number of blocks that were run or failed, energy and power use for the depot, battery state of charge (SOC) for each bus, and more.For example, to see how many blocks were run and dropped by type of bus, you could type:bus_sim.blocks_bustype_table()num_blocksmiles_1000sduration_hoursvehicle_typestatusartdropped_no_bus61218.0894863260.800000run691.659155271.516667stddropped_no_bus60320.4373753471.633333run641.932952293.716667Methods for creating BusSim charts and plots include:BusSim.make_report(self, output_folder): Create a full HTML report and export to an output folder.BusSim.bus_activity_gantt(): View a gantt chart of bus activity.BusSim.bus_plot(self, chart_days=0, out=False): View a chart of bus activity throughout the simulation, including buses on blocks and buses charging.chart_days: Change number of days represented in the chart.BusSim.power_plot(self, chart_days=0, out=False): View a plot of depot power by energy source.BusSim.bus_battery_plot(self, chart_days=0, num_buses=0): View a plot of bus battery state of charge over time.BusSim.bus_battery_plot2(self, bus_name, chart_days=0): View a plot of battery SoC for a specific bus.BusSim.battery_pct_plot(self, chart_days=0): View SoC for a depot's stationary battery.Methods for generating output tables include:BusSim.def energy_costs_monthly(self): Generate a table of monthly energy and power costs for the depot.BusSim.blocks_bustype_table(self): Generate a table of blocks by bus type that ran or failed.BusSim.activity_tracker_df(self, buses=None, df=True): Generate a table of activity by bus, similar to data used for a Gantt chart.Optimizing depot infrastructure needsOne of the main functions of the bussim program is to find the minimum amount of infrastructure needed to maintain service: Number of buses, chargers, power supply, etc. The bussim program has a "minbus" program that can do this, given a depot. This can be run from the command line, as detailed above. Minbus functions can also be run within an interactive environment. This program operates using the "MIN" scenario contained in the bussim config file. Base settings can be altered in the config file, or by passing an "other_settings" option within python.importbussim2.minbusasmb# run a minbus optimization process on the Kingsbridge depot.min_sim=mb.find_min_all("KB")# run a minbus process with a solar installation and higher speed chargers.min_sim=mb.find_min_all("KB",other_settings={'solar_kw':500,'charger_power':300})# view number of buses, chargers, and power found by the minbus routine:min_sim.num_busesmin_sim.chargersmin_sim.depot_power_supplyProgram structure and operation.The following sections describe key files that govern the operation of the bussim program.bussim: Contains code for creating bussim objects. Each bussim object is a self-contained simulation, with methods and properties for viewing charts and data tables for the bussim.minbus: Contains code for running the minbus optimization.bussimclasses: Contains major classes representing real-world things: Ebus, depot, dispatcher, solar, battery.utilities: Utility functions for running the sim, primarily intangible functions such as block handling, determining utility TOUs, etc.sources/: Directory of data files used for running the sim, including all block data contained in blocks.db.Licensebussim2is distributed under the terms of theMITlicense.