Simulating with SpiceEV

Command line options

You can set parameters through the command line or from a configuration file. If unsure, you can type python script.py –help to get detailed information.

Where the default is an Array ([]), the option can be set multiple times.

generate.py

Generate scenarios as JSON files for vehicle charging modelling.

command line options	short form	configuration file	description	default	example
(positional)		mode	Input type. Possible values: statistics, simbev, csv	statistics	./generate.py statistics -o scenario.json
–output	-o	output	Output file name. Required.	(must be set)	./generate.py -o scenario.json
–vehicle-types		vehicle_types	location of vehicle type definitions	None	–vehicle-types examples/data/vehicle_types.json
–interval		interval	Set number of minutes for each timestep (Δt)	15	–interval 1
–gc-power		gc_power	Set possible power at grid connection point in kW	100	–gc-power 150
–min-soc		min-soc	Set minimum desired SOC (0%-100%) for each charging process	80	–min-soc 50
–cs-power-min		cs_power_min	Set minimal power of charging station in kW	0.1 * cs_power	–cs-power-min 3.7
–discharge-limit		discharge_limit	Minimum SOC to discharge to during V2G [0-1]	0.5	–discharge-limit 0
–voltage-level	-vl	voltage_level	Set voltage level for cost calculation (possible voltage levels: HV, HV/MV, MV, MV/LV, LV)	None	-vl MV
–pv-power		pv_power	Set nominal power for local photovoltaic power plant in kWp	0	–pv-power 100
–seed		seed	Set random seed	None	–seed 1
–verbose	-v	verbose	Set verbosity level. 0: only errors and important warnings, 1: additional warnings and info	0	-v 1
–battery	-b	battery	Add battery with specified capacity in kWh and C-rate	[]	-b 100 0.5
–include-fixed-load-csv		include_fixed_load_csv	Include CSV for fixed load. Path is relative to output file.	None	–include-fixed-load-csv load.csv
–include-fixed-load-csv-option	-eo	include_fixed_load_csv-option	Set additional arguments for fixed load. See below.	[]	-eo column energy
–include-local-generation-csv		include_local_generation_csv	Include CSV for local energy generation, e.g., local PV. Path is relative to output file.	None	–include-local_generation-csv feed_in.csv
–include-local-generation-csv-option	-fo	include_local_generation_csv_option	Set additional arguments for local generation. See below.	[]	-fo step_duration 900
–include-price-csv		include-price-csv	Include CSV for energy price. Path is relative to output file.	None	–include-price-csv price.csv
–include-price-csv-option	-po	include_price_csv_option	Set additional arguments for price signals. See below.	[]	-po column price
–config		(no effect)	Use configuration file to set arguments. Overrides command line arguments.	None	–config examples/configs/generate.cfg

Special options for mode *statistics*:

command line options	short form	configuration file	description	default	example
–vehicles		vehicles	Set number of vehicles for a vehicle type	( [] , continues with 1 golf and 1 sprinter)	–vehicles 100 sprinter
–start-time		start_time	Provide start time of simulation in ISO format, precision is 1 second	2023-01-01T01:00:00+02:00	–start-time 2023-01-01T01:00:00+02:00
–days		days	Set duration of scenario as number of days	30	–days 7
–holidays		holidays	Specify dates in ISO format of no driving	[]	–holidays [2023-01-01]
–buffer		buffer	Set buffer on top of needed SOC for next trip	0.1	–buffer 0

Special options for mode *simbev*:

command line options	short form	configuration file	description	default	example
–simbev		simbev	Directory with SimBEV files. Required.	(must be set)	–simbev /path/to/simbev/output/
–region		region	Set name of region	None	–region region_1
–ignore-simbev-soc		ignore_simbev_soc	Don’t use SOC columns from SimBEV files	false	–ignore-simbev-soc
–min-soc-threshold		min_soc_threshold	SOC below this threshold will trigger a warning	0.05	–min-soc-threshold 0

Special options for mode *csv*:

command line options	short form	configuration file	description	default	example
–input-file	-f	input_file	Input file name (rotations_example_table.csv). Required.	(must be set)	–input-file examples/data/rotations_example_table.csv
–days		days	Set duration of scenario as number of days	30	–days 7
–export-vehicle-id-csv		export_vehicle_id_csv	Export csv after assigning vehicle_id, path relative to output scenario.json	None	–export-vehicle-id-csv vehicle_id.csv
–min-soc-threshold		min_soc_threshold	SOC below this threshold will trigger a warning	0.05	–min-soc-threshold 0

generate_schedule.py

Compute flexibility and schedule for a given scenario. Automatically includes schedule in scenario file.

command line options	short form	configuration file	description	default	example
(positional)		scenario	Scenario JSON file name	(must be set)	./generate_schedule.py example.json
–input		input	Timeseries of grid situation with columns ‘curtailment’ and ‘residual load’	(must be set)	–input grid_situation.csv
–output	-o	output	Resulting schedule file name	<scenario>_schedule.csv	-o schedule.csv
–individual	-i	individual	Schedule based on individual vehicles instead of vehicle park	False	-i
–core-standing-time		core_standing_time	Time and full days during which the fleet is guaranteed to be available	None	see config example file
–visual	-v	visual	Plot flexibility and schedule	False	-v
–config		(no effect)	Use configuration file to set arguments. Overrides command line arguments.	None	–config examples/generate.cfg

CSV file options

Options to be set when using csv files.

key	description	example value
step_duration_s	Interval between rows in seconds	3600
grid_connector_id	ID of grid connector	GC1
column	Column name with values of interest	energy

simulate.py

Simulate different charging strategies for a given scenario.

command line options	short form	configuration file	description	default	example
(positional)		input	scenario json file	(must be set)	./simulate.py example.json
–strategy	-s	strategy	charging strategy	greedy	–strategy balanced
–visual	-v	visual	Show plots of the results.	None	./simulate.py example.json -v
–eta		eta	Show estimated remaining time instead of progress bar. Not recommended for fast computations.	False	./simulate.py example.json –eta
–margin	-m	margin	Add margin for desired SOC [0.0 - 1.0] margin=0.05 means the simulation will not abort if vehicles reach at least 95%% of the desired SOC before leaving. margin=1 -> the simulation continues with every positive SOC value	0.05	–margin 1
–strategy-option	-so	strategy_option	set charging strategy options. For configuration file, see simulate.cfg in examples directory. For supported options, refer to the strategy options.		-so CONCURRENCY 0.5
–cost-calc	-cc	cost_calc	Calculate electricity costs.	False
–cost-parameters-file	-cp	cost_parameters_file	Get cost parameters from json file	None
–output	-o	output	Generate output file.	None	–output output.csv
–save-timeseries		save_timeseries	Write timeseries to file.	None	–output timeseries.csv
–save-results		save_results	Write general information to file.	None	–save-results results.json
–save-soc		save_soc	Write SOCs of vehicles to file.	None	–save-soc soc.csv
–testing		testing	Stores testing results.	False
–config		(no effect)	Use configuration file to set arguments. Overrides command line arguments.	None	–config examples/simulate.cfg

All charging strategies support the EPS option, which defines the difference under which two floating point numbers are considered equal. In other words, the value chosen for EPS determines the precision of the simulation. The smaller it is the more precise the calculations are. The downside to this is an increase running time. For some numerical procedures the algorithm might get stuck completely if EPS is too small. The default is 10^(-5).

Every strategy also supports the strategy options ALLOW_NEGATIVE_SOC and RESET_NEGATIVE_SOC. They control how to proceed should the state of charge (SOC) of a vehicle become negative. Both are False by default, which means the simulation will abort in such a case. If ALLOW_NEGATIVE_SOC is set, the simulation continues instead of aborting. If RESET_NEGATIVE_SOC is set, the SOC of the vehicle is set to zero. These options are helpful when simulating plug-in hybrids. NOTE: For SOC<0 batteries are charged/discharge with the amount of power specified on the charging/discharging curve at SOC=0. Make sure that Power(SOC=0) > 0, in case you want use the strategy option ALLOW_NEGATIVE_SOC. NOTE: By default, discharging below SOC=0 only applies to vehicles while driving. To discharge below SOC=0 for stationary batteries or V2G, you need to set the target SOC parameter of the battery.unload function accordingly.

Strategy options

Strategy option	Default	Explanation	Greedy	Balanced	Balanced Market	Schedule	Peak load window	Flex window	Distributed
CONCURRENCY	1.0	Reduce maximum available power at each charging station. A value of 0.5 means only half the power is available.	x		x			x
PRICE_THRESHOLD	0.001	A price below this is considered cheap. Unit: € / 1 kWh	x	x	x			x	x
ITERATIONS	12	Minimum depth of binary search to find charging power		x
HORIZON	24	number of hours to look ahead			x			x
DISCHARGE_LIMIT	0	V2G: maximum depth of discharge [0-1]			x			x	x
ALLOW_NEGATIVE_SOC	False	simulation does not abort if SOC becomes negative							x
C-HORIZON	3	loading time in min reserved for vehicle if number of cs is limited							x
LOAD_STRAT	Flex window: “balanced” Schedule: “collective” Peak load window: “needy”	Sub-strategies for behaviour within charging windows (see description above for options and explanations)				x	x	x

Input and output file formats

SpiceEV uses human-readable files for inputs, scenario definitions, configuration files and outputs. Not every type of input is part of the repository, as some data is classified and/or should be created by the user according to need.

generate.py

Input for mode `statistics` and `simbev`

• Fixed load (CSV): This file needs one column with the drawn power in kW (can have more columns, but only one is relevant). The file is read line-by-line, with events starting at start_time and updating every interval (configurable).

• Local generation (CSV): This file needs one column with the power generation in kW (can have more columns, but only one is relevant). The file is read line-by-line, with events starting at start_time and updating every interval (configurable).

• Energy price (CSV): This file needs one column with the energy price in €/kWh (can have more columns, but only one is relevant). The file is read line-by-line, with events starting at start_time and updating every interval (configurable).

• Configuration (CFG): Refer to generate_from_statistics.cfg and generate_from_simbev.cfg in the`examples` folder.

Output for mode `statistics` and `simbev`

• Scenario (JSON): This file is used in simulate.py. It defines the general information (start_time, interval, n_intervals), components (vehicle types, vehicles, grid connectors, charging stations, batteries) and events (fixed loads, local generation, grid operator signals and vehicle events).

Input for mode `csv`

• Trips schedule (CSV): Each row in the CSV file represents one trip. The following columns are needed: “departure_time” (datetime), “arrival_time” (datetime), “vehicle_type” (str), “soc” (numeric) / “delta_soc” (numeric) / “distance” (numeric). The following column is optional: “vehicle_id” (str)

• Configuration (CFG): Refer to generate_from_csv.cfg in the examples folder or the generate_from_csv_template.csv in the subfolder data.

Output for mode `csv`

• Scenario (JSON): This file is used in simulate.py. It defines the general information (start_time, interval, n_intervals), components (vehicle types, vehicles, grid connectors, charging stations, batteries) and events (fixed loads, local generation, grid operator signals and vehicle events).

• Trips schedule (CSV, optional): The input file with the trips schedule is updated by the “vehicle_id”

generate_schedule.py

Input

• Grid situation (CSV): The following columns are needed: “curtailment” (numeric), “residual load” (numeric)

• Scenario (JSON): Is created by generate scripts.

Output

• Schedule (CSV): For some charging strategies, this file is needed for the simulation. The file contains the timestamp, schedule [kW], charging signal (0 or 1), residual load an curtailment before and after applying the schedule as well as the power drawn at the specific charging stations.

simulate.py

Input

• Scenario (JSON): The scenario.json is created by the generate scripts.

Output (optional)

• Simulation timeseries (CSV): For each simulated point in time this CSV file contains the following values stored in columns:

  Column	Description
  timestep	simulation timestep, starting at 0
  time	datetime of timestep, isoformat
  price [EUR/kWh]	energy price
  grid supply [kW]	power drawn from grid
  fixed load [kW]	sum of fixed loads, e.g. building power (omitted if not present)
  local generation [kW]	sum of locally generated power from renewable sources(omitted if not present)
  battery power [kW]	sum of stationary battery power (omitted if not present)
  bat. stored energy [kWh]	sum of energy stored in stationary batteries (omitted if not present)
  flex band min, base and max [kW]	minimum and maximum flexibility per timestep
  generation feed-in [kW]	Feed-in to grid from local generation (omitted if not present)
  V2G feed-in [kW]	Feed-in to grid from V2G-capable vehicles (omitted if not present)
  battery feed-in [kW]	Feed-in to grid from battery (omitted if not present)
  schedule [kW]	schedule for grid supply (omitted if not present)
  window signal [-]	charging signal (omitted if not present)
  sum CS power [kW]	total of power drawn by charging stations
  # occupied CS [-]	number of charging stations with a vehicle connected to it
  # CS in use [-]	number of charging stations charging vehicles at the same time
  CS _ vehicle type _ grid connector [kW]	power at each charging station