REVOL-E-TION is an energy system model toolbox designed to optimize integration of electric vehicle fleets into local energy systems such as mini- and microgrids, company sites, apartment blocks or single homes and estimate the resulting technoeconomic potentials in terms of costs and revenues within the energy (and optionally also the mobility system). It is built as a wrapper on top of the oemof energy system model framework.

Philipp Rosner, M.Sc. and Brian Dietermann, M.Sc.
Institute of Automotive Technology
Department of Mobility Systems Engineering
TUM School of Engineering and Design
Technical University of Munich
[email protected]
September 2nd, 2021

Marcel Brödel, M.Sc. - Research Associate 01/2024-

David Eickholt, B.Sc. - Semester Thesis submitted 07/2021
Marcel Brödel, B.Sc. - Semester Thesis submitted 05/2022
Hannes Henglein, B.Sc. - Semester Thesis submitted 10/2022
Marc Alsina Planelles, B.Sc. - Master's Thesis submitted 10/2022
Juan Forero Yacaman - Bachelor's Thesis submitted 04/2023
Elisabeth Spiegl - Bachelor's Thesis submitted 06/2023
Alejandro Hernando Armengol, B.Sc. - Master's Thesis submitted 10/2023
Hannes Henglein, B.Sc. - Master's Thesis submitted 01/2024
Florian Melzig, B.Sc. - Master's Thesis submitted 10/2024

REVOL-E-TION is licensed under the Apache 2.0 open source license.
The full license text can be found in the LICENSE file in the root directory of the repository.

• P. Rosner and M. Lienkamp, "Unlocking the Joint Potential of Electric Mobility and Rural Electrification - A Concept for Improved Integration using Modular Batteries," 2022 IEEE PES/IAS PowerAfrica, Kigali, Rwanda, 2022, pp. 1-5, https://doi.org/10.1109/PowerAfrica53997.2022.9905305.
• P. Rosner, B. Dietermann, M. Brödel and M. Lienkamp, "REVOL-E-TION: A Flexible and Scalable Model to Optimally Integrate Bidirectional EV Fleets in Local Energy Systems", Poster, 2024 Vehicle2Grid Conference, Münster, Germany, 2024, https://doi.org/10.13140/RG.2.2.19632.16648

REVOL-E-TION is a scalable generator for (mixed integer) linear energy system models of local energy systems with or without electric vehicle fleets. It can be used to optimize component sizes and/or dispatch behavior of the system to achieve least cost in the simulation timeframe. Simulation results are later extrapolated and discounted to a project timeframe to estimate the technoeconomic potential of the system in the long run. Please note that this split between simulation and extrapolation improves computational effort, but creates possibly unwanted incentives for the optimizer (e.g. preferring low initial cost but operationally expensive power sources), especially when sizing components.

REVOL-E-TION groups oemof components and buses into blocks representing real-world systems (e.g. a PV array) for easy application. Electric vehicles (in fact any mobile storage devices) are modeled individually within a block called a CommoditySystem. Their behavior (i.e. when they depart and arrive again, how much energy they use in between and whether they can be charged externally) is described in a so called log file. Log files can be created using the integrated Discrete Event Simulation (DES), which is also capable of modeling range extension through a Battery CommoditySystem as well as multiple use cases in different time frames (e.g. summer/winter) for the commoditites.

The following system diagram shows the basic structure including one example of each block class (blocks are indicated by dashed lines):

REVOL-E-TION is designed to run under Windows 10, Ubuntu 22.04 LTS and MacOS 15 Sequoia, each with Python 3.11. While portability is generally built in, other operating systems are untested.

REVOL-E-TION is available at the institute's GitHub and can be cloned from there using

git clone https://github.com/TUMFTM/REVOL-E-TION.git

It is recommended to create and activate a clean virtual environment for the installation of REVOL-E-TION. This can be done using the following command:

python -m venv <path_to_virtual_environment>
source <path_to_virtual_environment>/bin/activate

or alternatively with conda:

conda create -n <name_of_virtual_environment> python=3.11
conda activate <name_of_virtual_environment>

Navigate to the root directory of the cloned repository and install the package and its dependencies using pip:

pip install -e .

This will install the revoletion package in editable mode, meaning that changes to the source code will be reflected in the installed package without reinstalling it.

REVOL-E-TION requires a pyomo compatible Mixed Integer Linear Programming (MILP) solver (as does oemof). The open-source cbc solver works well. The proprietary Gurobi solver is recommended however, as it is faster in execution, especially for large problems and offers a free academic license. If Gurobi is used, the version of Gurobi, gurobipy and the license file have to match. To ensure this get the version of both your gurobi license/installation (grbgetkey --version) and the installed gurobipy package (pip show gurobipy). If their major version numbers do not match, install the correct version of gurobipy using pip:

pip install gurobipy==<your_gurobi_version>

Running REVOL-E-TION requires closely defined scenario(s) to simulate and common simulation settings to operate on. Both are to be given as .csv-files specified as parameters in the terminal execution command using one of three options:

1. No parameters passed: graphical selection dialogs open automatically for scenario and settings files. (simple option)
2. Only filenames passed: scenario and settings files are searched in (a) the working directory and (b) in the package's example directory.
3. Valid paths to files passed: scenario and settings files are searched in the specified directories (best for remote execution on a server)

The actual terminal command can also be given in multiple forms:

1. Direct execution of the package's main module, e.g. python -m revoletion.main <scenario_file_parameter> <settings_file_parameter> (best for local execution on host machine, e.g. through a run configuration in PyCharm)
2. Call to the package's entry point, e.g. revoletion <scenario_file_parameter> <settings_file_parameter> (best for remote execution on a server as it works irrespective of the current working directory as long as the correct environment is active)

Example scenario and settings files are provided in the example directory. Formatting of the scenario and settings files can be taken from the example files and is explained in tabular form below. Some parameters in the scenario files reference to other files specified by file name within the input directory specified in the settings file. This mostly applies to timeseries data. Furthermore, to describe the mapping of different timeframes defining behavior of CommoditySystems (see below), modification of the mapper_timeframe_example.py code file might be necessary to fit the scenario as this is not simply and flexibly done in parameter files. The filename of the modified file has to be given in the scenario file under the key filename_mapper and the file has to be placed in the respective input directory specified in the settings file.

Concerning computational effort, REVOL-E-TION relies heavily on single core computing power for each scenario and especially in 'go' strategy uses significant memory. To avoid memory limitations, it is advised to limit the number of parallel scenarios to be executed in the settings file depending on the hardware used.

The following table details common terms occuring in further descriptions and the code:

Term	Description
Project	An application of REVOL-E-TION in a specific setting. All files (scenarios file, input data files, etc.) should be contained in a single directory. ./example is an example project.
Run	A single execution of REVOL-E-TION defined by a single scenario file (possibly containing multiple scenario definitions as columns) and settings file each. Common information and methods valid for all scenarios are defined in a SimulationRun object.
Scenario	A set of parameters (i.e. an energy system) to be simulated and/or optimized. It is defined by a column in the scenario file and some timeseries inputs.
Strategy	The (energy management) strategy to dispatch the energy system's blocks generally (see CommoditySystem capability levels later on for differences). REVOL-E-TION supports two strategies: "go" for single shot global optimization and "rh" for rolling horizon (i.e. time slotted myopic) optimization similar to Model Predictive Control (MPC). The former is a special case of the latter with just a single horizon. Component size optimization is only applicable in "go".
Horizon	A single optimization process by the solver, whether as the only one of the scenario ("go" strategy) or as a slice of the simulation timeframe ("rh" strategy). In the latter case, the total simulation time is split up into prediction horizons (each of which is represented in the code by a PredictionHorizon object) that are simulated consecutively. However, overlap between the horizons is necessary to ensure feasibilty of dispatch. Therefore, only the first part of the prediction horizon (called control horizon) is actually used for overall result calculation, while the rest is discarded. The simulation timeframe is automatically split up into horizons as per the defined length of prediction and control horizons from the scenario file. See the following diagram for clarification:
Block	A set of oemof components representing a real-world system including necessary converters and buses. Each is represented by an instance of the Block parent class with further child classes. The blocks present in the energy system are defined in the scenario file as a dictionary, except for the core block (of class SystemCore) containing the AC and DC buses as well as the converter(s) inbetween them. Multiple instances of one block can coexist in a model. The possible types (i.e. Classes) are laid out in the following chapter.
Component	A component is an oemof element that is either a source, a sink, a bus, a converter or a storage.

The following table details the classes of blocks that can be specified in the "blocks" parameter of the scenario in the scenario file with respective names for the instances. Block instances cannot be named "scenario". Each instance requires a certain set of parameters dependent on its class. These are specified in the following chapter.

The scenario file defines all noncomplex (i.e. integer, float, string, boolean) parameters of the scenarios. Complex (multidimensional) parameters are mostly defined through links to other files (by filename) in the scenario file. The following table specifies each parameter for each possible block class in the scenario file. If and only if a block of a certain class exists within the scenario are these parameters required and read in. Therefore not every scenario file contains all possible parameters. Multiple scenarios can be defined as multiple columns. The first row (header) of each scenario column defines the scenarios name. By adding a '#' to the start of the name of a scenario column, the scenario is ignored during the simulation process. The first column of the scenario file defines the name of the block the parameter in the second column applies to. An example scenario file is provided in the ./example directory. As all string values specified in the scenario definition file are converted to lower case, all files have to be named in lower case to be read in properly.

The settings file defines all common parameters for the scenarios in a simulation run. Its structure is much simpler than with the scenario file. The following table specifies each parameter of a complete settings file, all of which are required for every run.

Blocks of class GridConnection, which model a physical grid connection, allow to define different grid markets to sell and buy energy. Each of these markets is characterized by the following parameters specified in a file specified by the parameter "filename_markets":

• res_only: If activated, selling energy to the grid is restricted to energy produced by renewable energies blocks (PVSource, WindSource) in the current timestep and energy stored in a storage with activated "res_only" parameter
• opex_spec_g2s: Specific operational expenditures for buying energy from the market: cost in currency per energy in Wh. Can be given as float or filename of a csv file containing a timeseries
• opex_spec_s2g: Specific operational expenditures for selling energy to the market: cost in currency per energy in Wh. Can be given as float, filename of a csv file containing a timeseries, or set to 'equal' which then uses the same value as opex_spec_g2s and adds the specified cost_eps to avoid circular flows.
• pwr_g2s: Maximum power of the grid connection point towards the local grid in W.
• pwr_s2g: Maximum power of the grid connection point towards the public grid in W. Specifying a market file is optional and overrides the default market. If no markets file is specified, the default market is used with the parameters specified in the settings file. The default market inherits the sizes specified for the GridConnection. If several markets are specified, for every timestep the sum of all market's single powers (s2g and g2s) have to sum up to the current powers of the grid connection block. This is implemented to avoid unlimited simultaneous buying and selling of energy across different markets. Therefore, the specified power limits for each market are limited to the specified or optimized maximum power of the grid connection block.

The PVSource block models a photovoltaic system. If the insulation data is retrieved from an API (PVGIS or solcast) a API-specific parameter file can be passed to REVOL-E-TION to further specify the PV system. Examples for these files are ./example/pvgis_api_params.csv and ./example/solcast_api_params.csv This file is structured as follows if the PVGIS API is chosen:

For the solcast API the following parameters are required. Set values to 'None' to use the default values from the API:

Since REVOL-E-TION's main purpose is optimum EV integration, this is where focus lies in modelling detail, resulting in the DES and a priori power scheduling submodules. The following sections give more detail on these submodules:

The DES takes stochastically defined mobility or energy demand in multiple use cases and timeframes, samples an actual demand and assigns it to a CommoditySystem (more specifically to the individual MobileCommodities within it) in a first-come-first-serve approach. This enables to model the mobility/energy demand independently from the commodity fleet size. However, the DES is run a priori to the dispatch/sizing optimization, so no consideration of whether the resulting commodity dispatch is beneficial to the energy system is taken and limitations through battery aging and/or other limitations have to be covered by safety margins in dispatch to achieve a feasible energy system. Through the sampling, the DES also makes REVOL-E-TION outputs non-deterministic once it is activated even though the actual core optimization is deterministic. The DES is run separately for every scenario in a simulation run, but only once per scenario, as some CommoditySystems might be linked and can therefore not be simulated independently. It is built on the simpy library and is implemented in the commodity_des.py file. A modification is made to simpy in order to enable processes to require multiple resources at once, which is necessary for battery commodity use cases requiring high energy.

The core element of the DES is a so-called environment which is populated with processes that each represent one rental of a commodity from a store holding those commodities. The request time for each rental is sampled from a dual normal distribution over time of day defined for each timeframe and use case in the use case definition csv file. An example usecase file is distributed with REVOL-E-TION for both VehicleCommoditySystems and BatteryCommoditySystems (explanation see chapter "Classes of Blocks") in the respective input directories. Inside the code for the DES, RentalSystem instances are created for each CommoditySystem in the scenario as well as a RentalProcess instance for each process.

Each process not only covers the actual rental time (which itself is made up of an active part and idle time, both of which are sampled stochastically), but also a block time to give the energy system enough time to recharge before renting the commodity out again to a new request. For VehicleCommoditySystems, this block time is placed before each rental, while for BatteryCommoditySystems it is placed after. explanation of block time placement not clear.

Since VehicleCommoditySystems can be linked to BatteryCommoditySystems through the scenario parameter "rex_cs" for range extension, VehicleRentalSystems can also populate BatteryRentalSystems with additional processes representing range extension as a use case. Such a process then has a primary and secondary commodity, both of which need to be available for the process to be successful. For each RentalSystem, the primary commodity is the one from that RentalSystem, while the secondary is from the linked one. This results in range extension batteries being treated as primary in the BatteryRentalSystem and as secondary in the VehicleRentalSystem.

Once all stores have been populated with commodities and all processes have been created, the environment is run and determines which processes are successful (i.e. get their required commodities) and which ones fail. The successful processes are then converted to a time based log format for the core energy system optimization to use as input. This contains columns of availability in the energy system(called "<commodity_name>_atbase"), energy consumption while not at base, availability of external AC and DC charging and the Delta SOC ("<commodity_name>_dsoc") of a rental for every commodity and timestep. For VehicleCommoditySystems, this is expanded by a column with the trip distance, as even with a constant consumption this is no more traceable from the energy consumption due to the possibility of range extension. Only if the dispatch of the commodities is left to the optimizer (as opposed to the a priori power scheduling) myopically (i.e. in the "rh" strategy"), the dsoc column is actually transferred to a hard minimum SOC constraint for the optimizer, as all other cases handle this intrinsically.

Dependent on the chosen scheduling method ("mode_scheduling") of a commodity system a charging schedule for the commodity system's commodities is calculated before the linear optimization starts (a priori). This approach is applied to commodities in commodity systems with optimization level of all types of uncoordinated charging ('uc') and rulebased strategies ('equal', 'fcfs', 'soc'). All optimization levels causing an a priori calculation of the commodity's charging power require a unidirectional ('ud') integration level ("lvl_cap").
In addition to the optimization level, rule-based systems may implement a static load management system by defining the maximum available power using the "power_lim_static" parameter. If "power_lim_static" is set to 'None', static load management is disabled, and the system defaults to dynamic load management. For all commodities within uncoordinated or rulebased commodity systems in addition to the charging power when being plugged in at the local energy system the required charging power on-route at external charging infrastructure is calculated. The precomputed charging schedules are then enforced in the linear optimization model by applying them as fixed power constraints to the relevant model flows.

The a priori power scheduling process is iterative and operates on a per-timestep basis as the State of Charge (SOC) at each timestep is influenced by the previous timestep. Within a single timestep in a first step the charging powers for all commodities plugged in to the local energy system (column 'atbase' in log file is set to True) are calculated. Initially, the charging power calculation for uncoordinated commodities connected to the local energy system is determined, followed by rulebased commodity systems with static load management. In the next step the remaining available power within the local energy system is allocated to all commodities being part of the dynamic load management. The linear optimization algorithm subsequently handles the allocation of any excess power. Lastly, the external AC and DC charging power is calculated for commodities for which this infrastructure is currently available (indicated by the 'atac' or 'atdc' columns being True in the log file).

For rule-based commodity systems, a static power limit can be defined in the scenario file, which restricts the cumulative charging power of all commodities within the system. If no static power limit is set, the commodity system's commodities will be part of a dynamic load management. In this case, the available power within the local energy system is distributed among all commodities which are part of the dynamic load management. The available power is calculated by calculated subtracting the required power of FixedDemand blocks and the power already allocated to all unccordinated commodities and rulebased commodity systems with static load management from the maximum power output of GridConnection, PVSource, WindSource, and ControllableSource blocks. All rulebased commodity systems without a static power limit have to be of the same integration level as they are all controlled by the same dynamic load management system (can be seen as one large commodity system) and the rulebased charging strategy is applied as described. If this integration level is supposed to be 'equal' furthermore all commodity systems have to be connected to the same bus. As a dynamic load management system requires knowledge about the available power within the local energy system for each timestep, it is not possible to combine a dynamic load management system with a StationaryEnergyStorage block as this would require an a priori calculation of the StationaryEnergyStorage's SOC which is not possible in a straight-forward way, due to different prioritization of power sources based on their current opex and the efficiency of the SystemCore.

• uncoordinated charging: only a single commodity neglecting effects caused by other commodities is taken into account to determine its charging power.
  • 'uc':Once plugged in to the local energy system, the commodity charges at the maximum charging power specified for the commodity in the scenario file until the target SOC is reached. Charging power is determined for a single commodity in isolation, neither considering the influence of other commodities nor any type of load management system.
• rulebased charging strategies: multiple commodities (within the same commodity system for static load management or across several commodity systems for dynamic load management) are considered to determine their charging power.
  • 'equal': Charging power is evenly distributed among all commodities within the commodity system. Any surplus power, resulting from a commodity reaching its target SOC, is redistributed among the remaining commodities until all available power is allocated.
  • 'fcfs': Commodities are prioritized by their plug-in time, with the earliest plug-in receiving the highest priority. In cases where plug-in times are identical, commodities are prioritized alphabetically by name.
  • 'soc': Commodities are prioritized based on their SOC, with the lowest SOC receiving the highest priority. In cases where SOC levels are identical, priority is assigned alphabetically by name.
• optimized charging: The charging power of the commodities is optimized by the linear optimization algorithm without any a priori calculation.

The power for all commodities with available external charging infrastructure (column 'atac' or 'atdc' in log file is set to True) is calculated.

• AC charging: Once AC charging gets available, the required energy until the return to the local energy system is calculated. If the current SOC does not ensure a return SOC above the specified minimum return SOC (does not consider self-discharge), AC charging is activated. The specified charging power is then applied until the target SOC is reached.
• DC charging: If DC charging is available and the SOC at the next timestep with a charging possibility is below 5 %, DC charging is activated for the current timestep. The maximum SOC for DC charging is 80 % neglecting "soc_target".

Simple semi-empirical aging models are implemented for the BatteryCommoditySystem and StationaryEnergyStorage classes. More specifically, these are the Naumann model (publication 1 and publication 2) for LFP batteries and the Schmalstieg model for NMC batteries. They are both contained within the battery.py file and work on superposing calendric and cycle aging. The latter is based on cycling parameters (e.g. depths of discharge) determined using a rainflow algorithm for each horizon.

Results of the aging model (if activated through the scenario file parameter "aging") are evaluated and the capacity degradation applied as a restricted usable SOC window after every horizon. This results in a dependency of the aging model output on the horizon resolution (i.e. length) with the extreme case of the "go" strategy, where only the State of Health at the end of the simulation timeframe is evaluated. Please note that the lifetime used for economic extrapolation of simulation results is not connected to the aging model and sizing the battery block on its results is infeasible due to it being run a posteriori and nonlinearly. Therefore, the aging model's output does not have any influence on the economic results of the simulation, but is only of an informative character.

REVOL-E-TION creates a uniquely named (containing the runtimestamp and the scenario file name) result directory for every run. There, the following files are saved (some of them optionally):

• The log file of the run named <runtimestamp>_<scenario_file_name>_log.csv. This contains all terminal log messages of the run, including errors and warnings.
• (Optional) A single result summary file named <runtimestamp>_<scenario_file_name>_summary.csv if the setting "save_results" is True in the settings file. This contains all noncomplex (int, float, bool or string) attributes of the SimulationRun, Scenario, and all blocks in the scenario for quick overview of results.
• (Optional) One result timeseries file named <runtimestamp>_<scenario_file_name>_<scenario_name>_results.csv for every scenario in the run if the setting "save_results" is True in the settings file. This contains all timeseries results of the energy system for every timestep, facilitating easy plotting.
• (Optional) One DES processes and one log file named <runtimestamp>_<scenario_file_name>_<scenario_name>_<commodity_system_name>_processes.csv and <runtimestamp>_<scenario_name>_<commodity_system_name>_log.csv for every CommoditySystem of every scenario if the DES is executed for it and the setting "save_des_results" is True in the settings file. This facilitates debugging and reuse as an input for another scenario that is then deterministically run on that behavior.
• (Optional) One dispatch plot file named <runtimestamp>_<scenario_file_name>_<scenario_name>.html for every scenario if the setting "save_plots" is True in the settings file. This file contains an interactive line plot of the dispatch and state variables (i.e. SOCs and SOHs) of every block in the scenario.
• (Optional) One system graph file named <runtimestamp>_<scenario_file_name>_<scenario_name>_system_graph.pdf for every scenario if the setting "save_system_graph" is True in the settings file. This file contains a graph representation of the energy system, showing the connections between blocks and the energy flow.