Here are the steps to create your first simulation scenario:
EV-Fleet-Sim requires you to create a folder for the scenario that you would like to simulate. This folder will contain the input data, and the simulation results.
Create a folder for the scenario that you want to create. Let’s call this folder
Open a terminal and run
ev-fleet-sim. The program will ask you for the scenario directory. Enter in
<scenario-dir>. Tip, you can also run
ev-fleet-sim <scenario-dir> to skip the prompt.
Follow the prompts. The program will ask you which “step” you want to execute. Since
this is a new scenario, you want to run step 0, which initialises the
scenario’s directory structure. Enter
0 to initialise the scenario.
After you have done that, you will need to follow the steps in the below initialisation instructions. The instructions are quite detailed, so please take your time at this step and contact us if you face any difficulties!
After you have initialised the scenario, proceed to run the remaining steps of the program, by running again:
Run the script with the steps that you would like to run. Typically, you will need to run all of the steps, but it depends on your needs.
For example, if you open a terminal in
<scenario-dir>, you can run:
ev-fleet-sim .. This will return the following result:
Available steps: 0: scenario_initialisation 1: data_visualisation 1.1: mapping 1.2: route_animation 1.3: map_size_calculation 2: spatial_analysis 2.1: spatial_clustering 2.2: date_filtering_and_separation 2.3: save_dates_remaining 3: temporal_analysis 3.1: stop_extraction 3.2: stop_duration_box_plots 3.3: temporal_clustering 4.x: mobility_simulation 4.1: routing **OR** 4.2: fcd_conversion 5.x: ev_simulation 5.1: sumo_ev_simulation **OR** 5.2: hull_ev_simulation 6: results_analysis 6.1: ev_results_analysis 6.2.x: reg_results_analysis 6.2.1: pv_results_analysis **OR** 6.2.2: wind_results_analysis Specify steps to be run as a comma-seperated list of floats without spaces (e.g. '1,2.2,4'):
If you look carefully, the last line asks us to specify the steps that we want to run. Typically, we will want to run all the steps. Since we already ran step 0, you can enter
1,2,3,4.1,5.1,6.1,6.2 to run the remaining steps.
This will run the simulation, starting from step 1, and ending at step 6.2.
Some of the steps provide two options. For example, for step 4, you should either run
4.2. If you simply enter
4, then the first option (i.e.
4.1) will be selected.
The list of steps are presented to you whenever your run
ev-fleet-sim. If you already know what steps you want to run, you can skip the prompt by running:
ev-fleet-sim <scenario-dir> --steps <steps>, where
<steps> are the list of steps that you want to run.
After step 0, you will find a
readme.json file in
<scenario-dir>. This file contains a list with the directory structure of the scenario. The order of sub-directories shown in this list is the order in which the program generates its outputs. I.e. Step 1 will generate its outputs in the 1st directory specified in the list.
Additional usage instructions can be found by entering
ev-fleet-sim --help in a terminal.
When using Windows, always run
ev-fleet-sim and all commands in this tutorial using
GIT Bash instead of
command prompt or
powershell. You can always open
GIT Bash from the start menu or by right clicking in a file explorer and selecting
GIT Bash Here.
You can quit the program at any time by pressing
ctrl + C.
<scenario-dir>/refers to the root directory of the scenario.
Firstly, run the scenario-initialisation step of EV-Fleet-Sim to create the
folder structure in your scenario directory (
Copy your fleet’s raw vehicle data to
EV-Fleet-Sim supports two data formats: floating car data (FCD) (also commonly referred to as “GPS traces”), and General Transit Feed Specification (GTFS). (GTFS is a way of digitally representing public-transport schedules.)
If the raw data is FCD, proceed to the next step.
If the raw data is GTFS data, it should be a zipped archive. Rename the
archive to “GTFS_Orig.zip”. Unzip the GTFS archive into:
Make sure that GTFS data complies to the following caveats:
Arrival times and departure times must be defined in
They should not be equal to the same value.
frequencies.txt must be defined for each and every trip.
As mentioned previously, your input data may be FCD or GTFS data. We need to convert the input data fromat to CSV files that can be read by EV-Fleet-Sim. Please see the table below which outlines the columns that are required in each CSV file, and the format that their values need to conform to.
If your input data is floating car data, you will need to create a script to transform the gps-traces to CSV files. You must generate one CSV file per vehicle in the fleet.
Some template scripts are available on our Git repository to help you create your script.
If your input data is of the GTFS data format, you should use the
GTFS_Splitter.py scripts which are also in our Git repository. You can use them as-is. No changes should be necessary. The scripts will generate one csv file per trip defined in the GTFS data.
GTFS_Convert.r. After running it, extract the new file:
After this, run the
GTFS_Splitter.py script. It will tell you the maximum
and minimum GPS coorindates encountered. Hold onto these values. They will
be useful when generating the road-network.
|GPSID||Time *||Latitude *||Longitude *||Altitude1 +||Heading||Satellites||HDOP2||AgeOfReading||DistanceSinceReading||Velocity *||StopID3 +|
|units||-||‘yyyy-mm-dd hr24:MM:ss’ 4||[-]11.11111||[-]11.11111||meters||degrees||-||meters||minutes?||meters||km/h||-|
The headings marked with
Headings marked with
+are conditionally required.
Unmarked headings are not required, and are not currently used by EV-Fleet-Sim. They may be used in the future.
If you are not using a coloumn, leave its fields blank. (i.e. Don’t fill it with zeroes.)
Copy the script(s) to the
<scenario-dir>/_Inputs/Traces/ directory and run
Make sure the processed traces are in
<scenario-dir>/_Inputs/Configs/ev_template.xml file in your
favourite text editor.
Choose a vehicle class that will represent your fleet in SUMO. Try to choose the class that most closely represents the type of vehicle you are trying to simulate. If you don’t know which one to choose, choose the “passenger” vehicle type.
(List of available vehicle classes: SUMO Documentation)
(Default parameters of the various vehicle classes: SUMO Documentation)
In this file, find the
<vType ... > ⋮ </vType>
vType element, find the
<vType ... vClass="value" ... >
Change this attribute’s value to the desired vehicle class. Change the other
attributes of the
vType element if desired. (To read more about the
attributes and what their values mean, refer: SUMO
<param key="..." value="..." >
If desired, you can change the values of the various parameters to modify the electric-vehicle model.
(Reference to electric vehicle parameters: SUMO Documentation)
<scenario-dir>/_Inputs/Map/Boundary. You will find a file called
boundary.csv. It is a csv file with two columns. Each row represents the
coordinates of each of the four points in the boundary box that you would
like to create.
This bounding box will be used during the simulation. For FCD, if a vehicle
leaves this bounding box on a particular day, that day’s data will be
discarded. For GTFS data, it is recommended to create a bounding box
corresponding to the values given by
GTFS_Splitter.py as explained
osm.pbf file which represents the country. Currently, they are
available from geofabrik.de. Other
are available and more information about pbf files can be found at the OSM
.osm.pbf file to
<scenario-dir>/_Inputs/Map/Construction. From here on, we will refer to this directory as
You will find a bash script called
<construction-dir>. Open it in a text editor. In MacOS and Linux, find the line which has
--bbox <min_lon>,<min_lat>,<max_lon>,<max_lat>. On Windows, find the line which has
-b=<min_lon>,<min_lat>,<max_lon>,<max_lat>. Modify the line to correspond with the values added to
Or in Windows:
Run the modified
.sh file to convert the
.osm.pbf file to a
.osm file, while cropping to the specified boundary. This should produce a file called
Optional step: Importing elevation data
By default, OSM does not include elevation data. If you would like to use elevation data to create a more realistic simulation, then you will need to follow the following instructions:
By default, OSM does not include elevation data. Elevation is supported by EV-Fleet-Sim to create more realistic simulations. In order to use that functionality, elevation data needs to be overlayed on the input OSM file. To do this, you need to install
osmosis, and the
To install them, follow the steps below:
Download and unpack Osmosis 0.45 in a folder in your computer. We will refer to the folder’s directory as
Download the pre-built jar file and place it in
Clone and build the osmosis-srtm plug-in repo.
Create a text file called
osmosis-plugins.conf in the
<osmosis-dir>/config/ directory and add this line to the file:
Downloading elevation data:
Create and sign into an account on Earth Explorer
Play around on the map until the entire area you want to cover is seen.
Click on the “Use map” button and continue to data set
Check the Use Data Set Prefilter box and type: “NASA SRTM3 SRTMGL3” in the Data Set Search bar. Make sure only the checkbox named “NASA SRTM3 SRTMGL3” is ticked
Click the “Results” button.
For each of the results, click “Download Options” and download the HGT file.
Unzip all of the downloads and place them together in the directory:
Overlaying elevation data on OSM:
As instructed in the previous step of the Initialising Road Network instructions, you should have a file called
<construction-dir>. Rename this file to
Run the following line in you command prompt:
<osmosis-dir>/bin/osmosis --read-xml <construction-dir>/map-without-elevation.osm --write-srtm locDir=<construction-dir>/Elevation/ repExisting=true tagName=ele --write-xml <construction-dir>/map-with-elevation.osm
Windows (GIT Bash):
<osmosis-dir>/bin/osmosis.bat --read-xml <construction-dir>/map-without-elevation.osm --write-srtm locDir=<construction-dir>/Elevation/ repExisting=true tagName=ele --write-xml <construction-dir>/map-with-elevation.osm
square_boundary.osm so that it can be used in the next step in the Initialising Road Network instructions.
You will also find a
net_convert.sh file in the
Construction directory. We will run this script to convert the
.osm file to a
.net.xml file (the road-network file-format that is compatible with SUMO).
But before we do that, you may want to take note of the
.typ.xml file that is present in the
Construction directory. This is a SUMO edge-type file.
.typ.xml file defines which vehicle classes are allowed to access the various road types. It can optionally be modified to suit the context of the scenario.
For example, gravel roads (
highway.track) are common in developing countries, and hence it would be expected that vehicles have access to those roads in the simulation (since tar roads are less common). In cities of developed countries, where gravel roads are less common, it may be appropriate to restrict vehicles from accessing them.
Optional step: Setting Road Access Permissions
Remember that previously we chose a vehicle class to represent our fleet? Now we can specify which road-types allow access for our fleet’s vehicle class.
.typ.xml file in your favourite text editor. For each road-type listed, change the
allow attributes to allow/disallow your vehicle class. You can also change the other attributes, such as the speed limits on the various road types.
(Description of the various road types: OpenStreetMap Wiki)
(More information on SUMO edge-type files: SUMO Documentation)
Now we can proceed to run the
The script will prompt you to ask you if the scenario has left- or right-handed traffic. It will also ask you if you want to import elevation data from the OSM file. This option will only work if you import elevation data as explained previously.
As the script runs, sometimes it
will throw many warnings due to badly formed data. If you have time, try and
fix the warnings by editing the
.net.xml file in NETEDIT. (I usually
ignore the errors, because most can be safely ignored.)
There is one warning that requires special mention: If you get the following
Warning: Discarding unusable type ..., it means that netconvert
encountered a road type which is not defined in the
In such cases, netconvert will ignore roads which have not been defined.
(I.e. It will pretend as if they didn’t exist.) If the road type is
important to you, add it to the
.typ.xml file, and set it’s access
Once the scrpt is done running, the
.net.xml file can be found in:
<scenario-dir>/_Inputs/Map/, and a log of the warnings will be saved as a
text file in the
(Description of netconvert warnings and the recommended actions: SUMO Documentation)
We have now initialised the road network. However, if you want to make small
changes, or view the generated road network graphically, you can open the
.net.xml file with the
Netedit software which comes with SUMO.
(Netedit usage instructions: SUMO Documentation)
Because EV-Fleet-Sim also does renewable energy calculations, you may also put
weather data files in the
<scenario-dir>/_Inputs/Weather directory. If you are
not interested in doing renewable energy calculations, you may leave the
This data can be obtained by first installing SAM, and using its user interface to download the data for the location that you need. This processs is described in the section “Running renewable energy simulations”.
In the case of solar energy data, SAM should have data for almost any location around the world. In the case of wind data, they only provide data for locations in the USA. In case they don’t have data for the location that you are interested in, or if you just want to use your own dataset, you will need to re-format the data into a format that can be read by SAM.
In case you want to use your own data, the following document describes the file format that is required for SAM weather files.
Follow a similar procedure to that described in the PV Simulations section, except using the “Wind/No Financial Model” option of SAM.