Code documentation

Below, the scripts and modules of SpiceEV are explained. The structure of the documentation follows the one from the GitHub repository.

Generate

The generate script and corresponding generate modules prepare input files for the simulation with SpiceEV. For an example configuration file see /examples/configs/generate.cfg.

update_namespace(args)	Prepare generate-arguments for function call.
generate(args)	Generate scenario JSON.

Generate schedule

The generate_schedule script, together with the generate_schedule module, generates a CSV file containing a schedule from the grid operator containing grid signals. The path to the CSV file is also added to an existing scenario.json. For an example configuration file see /examples/configs/generate_schedule.cfg.

Simulate

The simulate script reads in the simulation input arguments, sets up the scenario and runs the simulation. It serves as a wrapper for the simulation. For an example configuration file see /examples/configs/simulate.cfg.

simulate(args)

Read simulation input arguments, set up scenario and run the simulation.

Calculate costs

The calculate costs script calculates the electricity costs based on the price sheet of the respective distribution grid operator. The calculation can be done during the simulation or independently afterwards. For the latter case a configuration file is needed. For an example see /examples/configs/calculate_costs.cfg.

read_simulation_csv(csv_file)

Read prices, power values and charging signals for each timestamp from simulation results.

spice_ev

The spice_ev folder contains the modules called by the scripts above.

Generate

Depending on the mode selected in the generate.cfg one of the following modules is called by the generate.py.

Generate_from_csv

This module generates a scenario.json from a CSV file with a rotation schedule of the vehicle fleet. For an example configuration file see /examples/configs/generate_from_csv.cfg.

generate_from_csv(args)	Generate a scenario JSON from CSV rotation schedule of fleets to/from one grid connector.
csv_to_dict(csv_path)	Read CSV file and returns a dict with each element representing a trip
assign_vehicle_id(input, vehicle_types[, export])	Assign all rotations to specific vehicles with distinct vehicle_id.

Generate_from_statistics

This module generates a scenario.json with random dummy trips for a set up defined by the input arguments. For an example configuration file see /examples/generate_from_statistics.cfg.

datetime_from_string(s)
generate_trip(v_type_info)	Create randomly generated trips from average input arguments.
generate_from_statistics(args)	Generate a scenario JSON with trips from statistical input parameters.

Generate_from_simbev

This module generates a scenario.json from SimBEV [1] results. For an example configuration file see /examples/configs/generate_from_simbev.cfg.

parse_vehicle_types(tech_data)	Get vehicle data from SimBEV metadata.
generate_from_simbev(args)	Generate a scenario JSON from SimBEV results.

Generate_schedule

This module generates a schedule with grid signals needed by some charging strategies and incentive schemes. For an example configuration file see /examples/configs/generate_schedule.cfg.

generate_flex_band(scenario, gcID[, ...])	Generate flexibility potential for total vehicle fleet with perfect foresight.
generate_individual_flex_band(scenario, gcID)	Generate flexibility potential for individual vehicles with perfect foresight.
generate_schedule(args)	Generate schedule for grid signals based on total vehicle fleet.

Strategies

Different strategies can be applied on the vehicle fleet. For more information on the strategies see section Charging strategies. Depending on the strategy selected in the simulate.cfg one of the following modules is called by the simulate.py.

Balanced

Each vehicle is charged such that it uses its complete standing time to reach the desired state of charge (SOC). May charge more power (and above the desired SOC) if there is surplus from local generation or if the energy price falls below a certain PRICE_THRESHOLD.

Balanced(components, start_time, **kwargs)	Charging with minimum required power to reach desired SoC during estimated parking time.
Balanced.step()	Calculates charging power in each timestep.
load_vehicle(strategy, cs, gc, vehicle, ...)	Load one vehicle with balanced charging strategy.

Balanced Market

When using this strategy, price information within the next HORIZON hours is evaluated. The goal is to divide standing times into periods of equal prices. A vehicle is now charged such that is uses the entire duration of all periods with the lowest price combined to reach its desired SOC. In case that time is not sufficient the periods of the second cheapest price are used to charge as much of the remaining delta SOC as possible, again in a balanced way with respect to power.

BalancedMarket(components, start_time, **kwargs)	Price oriented charging at times of low energy price.
BalancedMarket.step()	Calculate charging power in each timestep.

Distributed

Unlimited grid connectors (GCs) are supported. Vehicles that arrive at a charging station with opportunity charging are charged with strategy greedy, those arriving at a depot station are charged with strategy balanced. Possible use cases are bus scenarios.

Distributed(components, start_time, **kwargs)	Strategy that allows for greedy charging at opp stops and balanced charging at depots.
Distributed.step()	Calculates charging power in each timestep.

Flex window

An attempt is made to charge the vehicles mainly in time windows during which charging is encouraged by the grid operator. During these time windows the vehicles are charged with a sub-strategy that can be selected in the simulate.cfg

FlexWindow(components, start_time, **kwargs)	Charging during given time windows.
FlexWindow.step()	Calculate charging power in each timestep.
FlexWindow.distribute_balanced_vehicles(...)	Charge vehicles with balanced method according to time windows.
FlexWindow.distribute_balanced_batteries(...)	Charge/discharge stationary batteries with balanced method according to time windows.
FlexWindow.distribute_balanced_v2g(timesteps)	Charge/discharge vehicles with v2g with balanced method according to time windows.
FlexWindow.distribute_peak_shaving_vehicles(...)	Charge vehicles with peak shaving method according to time windows.
FlexWindow.distribute_peak_shaving_batteries(...)	Charge/discharge batteries with peak shaving method according to time windows.
FlexWindow.distribute_peak_shaving_v2g(timesteps)	Charge/discharge vehicles with v2g with peak shaving method according to time windows.
FlexWindow.distribute_power(vehicles, ...)	Charge vehicle batteries with available power according to LOAD_STRAT.
FlexWindow.load_surplus_to_batteries()	Charge batteries with surplus energy.

Greedy

With this strategy one vehicle after the other is charged with full power until the desired SOC is reached. Depending on the maximum permitted power at the GC, multiple vehicles may be charged in one timestep.

Greedy(components, start_time, **kwargs)	Uncontrolled charging with max power immediately after connecting to charging station.
Greedy.step()	Calculate charging power in each timestep.
load_vehicle(strategy, cs, gc, vehicle, ...)	Load one vehicle with greedy strategy.

Peak load window

Given a time window of high load, this strategy tries to charge outside of this time window. Different sub-strategies are supported.

PeakLoadWindow(components, start_time, **kwargs)	Charging strategy that prioritizes times outside of high load time windows.
PeakLoadWindow.step()	Calculate charging power in each timestep.
PeakLoadWindow.distribute_power(vehicles, ...)	Distribute total_power to vehicles in iterable vehicles according to self.LOAD_STRAT

Schedule

This strategy distributes the power according to a schedule given by the respective grid operator.

Schedule(components, start_time, **kwargs)	Charging according to a given schedule, that depends on the grid situation.
Schedule.dt_to_end_of_time_window()	Return timedelta between now and end of core standing time (resolution: one minute).
Schedule.sim_balanced_charging(vehicle, dt, ...)	Simulate a balanced charging process for a single vehicle.
Schedule.collect_future_gc_info([dt])	Get grid connector info for each future timestep until all vehicles left.
Schedule.evaluate_core_standing_time_ahead()	Evaluate provided energy per timestep by schedule and needed energy in total.
Schedule.charge_vehicles_during_core_standing_time()	Charge vehicles during core standing time.
Schedule.charge_vehicles_during_core_standing_time_v2g(...)
Schedule.charge_vehicles_after_core_standing_time(...)	Charge vehicles balanced between end of core standing time and departure.
Schedule.charge_vehicles()	Charge vehicles.
Schedule.charge_individually()
Schedule.utilize_stationary_batteries()	Adjust deviation with batteries.
Schedule.step()	Calculate charging power in each timestep.

Battery

This module contains the class Battery and its methods which describe the behaviour of a vehicle battery.

Battery(capacity, loading_curve, soc[, ...])	Battery class
Battery.load(timedelta[, max_power, ...])	Adjust SoC, return average charging power for given timedelta and max charging power.
Battery.unload(timedelta[, max_power, ...])	Discharge battery.
Battery.load_iterative(timedelta, ...)	Adjust SoC, return average charging power for given timedelta and max charging power.
Battery.get_available_power(timedelta)	Returns maximum available power for timedelta duration.
Battery._adjust_soc(timedelta, ...)	Helper function that loads or unloads battery to a given target SoC.

Components

This module contains all Components relevant for the distribution of the electrical energy at a site, except for the fixed load.

Components(obj)	Components class
GridConnector(obj)	GridConnector class
GridConnector.add_load(key, value)	Add power value to current_loads dict under key, return updated value.
GridConnector.get_current_load([exclude])	Get sum of current loads not in exclude list.
GridConnector.add_avg_fixed_load_week(...)	Compute average load using EnergyValuesList.
GridConnector.get_avg_fixed_load(dt, interval)	Get average fixed load for specific timeslot.
ChargingStation(obj)	ChargingStation class
Photovoltaics(obj)	PV power plant class
VehicleType(obj)	VehicleType class
Vehicle(obj, vehicle_types)	Vehicle class
Vehicle.get_delta_soc()	Calculates delta soc
Vehicle.get_energy_needed([full])	Calculate energy needed to reach desired SoC (positive or zero).
StationaryBattery(obj)	StationaryBattery class

Costs

This module is called by the calculate_costs.py and contains all cost related functions.

get_flexible_load(power_grid_supply_list, ...)	Determine power of flexible load.
find_prices(price_sheet_path, strategy, ...)	Read commodity and capacity charge from price sheets.
calculate_commodity_costs(price_list, ...)	Calculate commodity costs for all types of customers.
calculate_capacity_costs_rlm(...)	Calculate the capacity costs per year and simulation period for RLM customers.
calculate_costs(strategy, voltage_level, ...)	Calculate costs for the chosen charging strategy.

Events

This module sets up the events for the simulation period.

Events(obj, dir_path)	Events class
Events.get_event_steps(start_time, ...)	Create list of all events within simulation time.
Event()	Event class
LocalEnergyGeneration(kwargs)	LocalEnergyGeneration class
FixedLoad(kwargs)	FixedLoad class
EnergyValuesList(obj, dir_path)	EnergyValuesList class
EnergyValuesList.get_events(name, value_class)	Set up local generation and fixed_load events from input.
GridOperatorSignal(obj)	GridOperatorSignal class
get_energy_price_list_from_csv(obj, dir_path)	Get energy price list from input csv.
get_schedule_from_csv(obj, dir_path)	Read out schedule CSV file and generate list of GridOperatorSignal events.
VehicleEvent(obj)	VehicleEvent class

Loading curve

This module contains the class LoadingCurve and its methods which are needed for the batteries.

LoadingCurve(points)	LoadingCurve class
LoadingCurve.power_from_soc(soc)	Perform a lookup.
LoadingCurve.clamped(max_power[, pre_scale, ...])	Return a new instance with clamped power.
LoadingCurve.get_section_boundary(soc)	Find linear section where given SOC value is located.

Report

This module contains functions to aggregates the simulation results, store them in files and visualize them if the respective options are selected in the simulate.cfg.

aggregate_global_results(scenario)	Aggregate and reorder simulation data across grid connectors.
aggregate_local_results(scenario, gcID)	Aggregate results of simulation for a single grid connector.
split_feedin(grid, generation, cs_sum[, ...])	Split feed-in to grid into local power generation, V2G and battery for one time step.
aggregate_timeseries(scenario, gcID)	Compute various timeseries for a given grid connector.
generate_soc_timeseries(scenario)	Generate SoC timeseries for each vehicle.
plot(scenario)	Plot various timeseries collected over the duration of the simulation.
generate_reports(scenario, options)	Generate reports and save them.

Scenario

This module is called by the simulation.py. It sets up components, events, start time and the interval of the simulation. The simulation is run stepwise, calling the module strategy for each timestep.

Scenario(json_dict[, dir_path])	Sets up a scenario from input JSON.
Scenario.run(strategy_name, options)	Run the scenario.

Strategy

This module serves as a wrapper for the individual charging strategies and determines how excess energy is distributed to the other flexible loads.

Strategy(components, start_time, **kwargs)	Parent class for the individual strategies.
Strategy.step([event_list])	Prepare next timestep for specific charging strategy.
Strategy.distribute_surplus_power()	Distribute surplus power to vehicles.

Util

This modul contains some utility functions needed by different scripts and modules.

datetime_from_isoformat(s)	Convert isoformat str to datetime.
datetime_within_window(dt, time_windows)	Check if a given datetime is within any of the given time windows.
dt_within_core_standing_time(dt, ...)	Check if datetime dt is in inside core standing time.
set_attr_from_dict(source, target, keys, ...)	Set attributes of target from a source dictionary.
get_cost(x, cost_dict)	Return cost based on the cost type.
get_power(y, cost_dict)	Return power for a given price.
clamp_power(power, vehicle, cs)	Return power that is actually available at charging station.
set_options_from_config(args[, check, verbose])	Update given options from config file.
sanitize(s[, chars])	Remove special characters from string.

Footnotes

[1]

https://github.com/rl-institut/simbev