EV2Gym: A Realistic EV-V2G-Gym Simulator for EV Smart Charging

Develop and evaluate any type of smart charging algorithm: from simple heuristics, Model Predictive Control, Mathematical Programming, to Reinforcement Learning!

EV2Gym is fully customizable and easily configurable!

The EV2Gym Paper can be found at: link.

The developed MPC algorithms Paper can be found at: link.

Installation

Install the package using pip: bash pip install ev2gym

Run the example code below to get started ... ```python from ev2gym.models.ev2gym_env import EV2Gym from ev2gym.baselines.mpc.V2GProfitMax import V2GProfitMaxOracle from ev2gym.baselines.heuristics import ChargeAsFastAsPossible

configfile = "ev2gym/exampleconfig_files/V2GProfitPlusLoads.yaml"

Initialize the environment

env = EV2Gym(configfile=configfile, savereplay=True, saveplots=True) state, _ = env.reset() agent = V2GProfitMaxOracle(env,verbose=True) # optimal solution

or

agent = ChargeAsFastAsPossible() # heuristic for t in range(env.simulationlength): actions = agent.getaction(env) # get action from the agent/ algorithm new_state, reward, done, truncated, stats = env.step(actions) # takes action

- ### For Reinforcement Learning: To train an RL agent, using the [StableBaselines3](https://stable-baselines3.readthedocs.io/en/master/) library, you can use the following code: python import gymnasium as gym from stablebaselines3 import PPO, A2C, DDPG, SAC, TD3 from sb3contrib import TQC, TRPO, ARS, RecurrentPPO

from ev2gym.models.ev2gym_env import EV2Gym

Choose a default reward function and state function or create your own!!!

from ev2gym.rlagent.reward import profitmaximization, SquaredTrackingErrorReward, ProfitMaxTrPenaltyUserIncentives from ev2gym.rlagent.state import V2Gprofitmax, PublicPST, V2Gprofitmaxloads

configfile = "ev2gym/exampleconfigfiles/V2GProfitPlusLoads.yaml" env = gym.make('EV2Gym-v1', configfile=configfile, rewardfunction=rewardfunction, statefunction=state_function)

Initialize the RL agent

model = DDPG("MlpPolicy", env)

Train the agent

model.learn(totaltimesteps=1000000, progressbar=True)

Evaluate the agent

env = model.get_env() obs = env.reset() stats = [] for i in range(1000): action, _states = model.predict(obs, deterministic=True) obs, reward, done, info = env.step(action)

if done:
    stats.append(info)

``` !!! You can develop your own reward and state functions and use them in the environment.

Table of Contents

• Installation
• Overview
• Configuration File
• File Structure
• Citing
• License
• Contributing

Overview

• The simulator can be used to evaluate any type of algorithm to gain insights into its efficiency.
• The “gym environment” can readily support the development of RL algorithms.
• Replays of simulations are saved and can be solved optimally using the Gurobi Solver.
• Easy to incorporate additional functionality for any use-case.
• Does not simulate the grid yet, but groups EV chargers at the level of the transformer/ parking lot, etc, so extra functionality can be easily added.
• The number and the topology of Transformers, Charging stations, and Electric Vehicles are parameterizable.
• The user can import custom data.
• Uses only open-source data:
  • EV spawn rate, time of stay, and energy required are based on realistic probability distributions ElaadNL conditioned on time, day, month and year.
  • Pecan Street data is used for the load profiles.
  • Renewables Ninja data is used for the PV generation profiles.
  • EV and Charger characteristics are based on real EVs and chargers existing in NL (RVO Survey).
  • Charging/ Discharging prices are based on historical day-ahead prices from ENTSO-e.

Focused on realistic parameters and fully customizable:

• Power Transformer model:
  • Max Power Limit
  • Inflexible Loads, PV, Capacity Reduction events
• Charging Stations model:
  • Min and Max charge/discharge power/ Current
  • Voltage and phases, AC or DC
  • List of connected transformers
• Electric Vehicle model:
  • Connected charging station and port
  • Min and Max battery energy level
  • Time of arrival and departure
  • Energy at arrival/ desired energy at departure
  • Min and Max power levels
  • Charge and discharge efficiency
  • Constant-Current/ Constant-Voltage load-curve option
• Battery Degradation model:
  • Cyclic aging
  • Calendar aging

An EV2Gym simulation comprises three phases: the configuration phase, which initializes the models; the simulation phase, which spans $T$ steps, during which the state of models like EVs and charging stations is updated according to the decision-making algorithm; and finally, in the last phase, the simulator generates evaluation metrics for comparisons, produces replay files for reproducibility, and generates real-time renders for evaluation.

Configuration File

The configuration file is used to set the parameters of the simulation. The configuration file is a YAML file that contains the following parameters: ```yaml

Simulation Parameters

timescale: 15 # in minutes per step simulation_length: 96 #90 # in steps per simulation

Date and Time

Year, month,

year: 2022 # 2015-2023 month: 1 # 1-12 day: 17 # 1-31

Whether to get a random date every time the environment is reset

random_day: False # True or False

Simulation Starting Hour and minute do not change after the environment has been reset

hour: 12 # Simulation starting hour (24 hour format) minute: 0 # Simulation starting minute (0-59)

Simulate weekdays, weekends, or both

simulation_days: both # weekdays, weekends, or both

EV Spawn Behavior

scenario: public # public, private, or workplace spawn_multiplier: 10 # 1 is default, the higher the number the more EVs spawn

Prices

dischargepricefactor: 1.2 # how many times more abs(expensive/cheaper) it is to discharge than to charge

Charging Network

v2genabled: True # True or False numberofchargingstations: 15 numberoftransformers: 3 numberofportspercs: 2

Provide path if you want to load a specific charging topology,

else write None for a randomized one with the above parameters

chargingnetworktopology: None #./configfiles/chargingtopology_10.json

Power Setpoints Settings

How much the power setpoints can vary in percentage compared to the nominal power

The higher the number the easier it is to meet the power setpoints, the opposite for negative numbers

powersetpointflexiblity: 20 # (in percentage +/- %)

Inflexible Loads, Solar Generation, and Demand Response

Whether to include inflexible loads in the transformer power limit, such as residential loads

tr_seed: -1 # Seed for the transformer loads, -1 for random

inflexibleloads: include: False # True or False inflexibleloadscapacitymultipliermean: 0.8 # 1 is default, the higher the number the more inflexible loads forecastmean: 100 # in percentage of load at time t% forecast_std: 0 # in percentage of load at time t%

PV solar Power

solarpower: include: False # True or False solarpowercapacitymultipliermean: 2 # 1 is default, the higher the number the more solar power forecastmean: 100 # in percentage of load at time t% forecast_std: 0 # in percentage of load at time t%

Whether to include demand response in the transformer power limit

demandresponse: include: False # True or False eventsperday: 1 #How much of the transformer power limit can be used for demand response eventcapacitypercentagemean: 25 # (in percentage +/- %) eventcapacitypercentagestd: 5 # (in percentage +/- %) eventlengthminutesmin: 60 eventlengthminutesmax: 60 eventstarthourmean: 18 eventstarthourstd: 2 # How many minutes ahead we know the event is going to happen notificationofeventminutes: 15

EV Specifications

heterogeneousevspecs: False #if False, each EV has the same specifications

such as battery capacity, charging rate, etc.

Default Model values

These values are used if not using a charging network topology file or

if the EV specifications are not provided

Default Transformer model

transformer: max_power: 100 # in kW

Default Charging Station model

chargingstation:
minchargecurrent: 0 # Amperes maxchargecurrent: 56 # Amperes mindischargecurrent: 0 # Amperes maxdischarge_current: -56 # Amperes voltage: 230 # Volts phases: 3 # 1,2, or 3

Default EV model

ev: batterycapacity: 50 # in kWh minbatterycapacity: 10 # in kWh desiredcapacity: 40 # in kWh maxacchargepower: 22 # in kW minacchargepower: 0 # in kW maxdcchargepower: 50 # in kW maxdischargepower: -22 # in kW mindischargepower: 0 # in kW evphases: 3 transitionsoc: 1 # 0-1 (0% - 100%) chargeefficiency: 1 # 0-1 (0% - 100%) dischargeefficiency: 1 # 0-1 (0% - 100%) mintimeofstay: 120 # in minutes ```

File Structure

The file structure of the EV2Gym package is as follows: bash ├── ev2gym │ ├── baselines │ │ ├── gurobi_models/ │ │ ├── mpc/ │ │ ├── heuristics.py │ ├── data/ │ ├── models │ │ ├── ev2gym_env.py │ │ ├── ev.py │ │ ├── transformer.py │ │ ├── ev_charger.py │ │ ├── replay.py │ │ ├── grid.py │ ├── rl_agent │ │ ├── reward.py │ │ ├── state.py │ ├── utilities │ │ ├── loaders.py │ │ ├── utils.py │ │ ├── arg_parser.py │ ├── example_config_files │ │ ├── BusinessPST.yaml │ │ ├── PublicPST.yaml │ │ ├── V2GProfitPlusLoads.yaml │ ├── visuals │ │ ├── plots.py │ │ ├── renderer.py │ ├── scripts/

Class Diagram of the EV2Gym Environment:

Citing EV2Gym

If you use this code in your research, please cite as: bibtex @ARTICLE{10803908, author={Orfanoudakis, Stavros and Diaz-Londono, Cesar and Emre Yılmaz, Yunus and Palensky, Peter and Vergara, Pedro P.}, journal={IEEE Transactions on Intelligent Transportation Systems}, title={EV2Gym: A Flexible V2G Simulator for EV Smart Charging Research and Benchmarking}, year={2025}, volume={26}, number={2}, pages={2410-2421}, keywords={Vehicle-to-grid;Smart charging;Optimization;Benchmark testing;Batteries;Data models;Schedules;Reinforcement learning;Prediction algorithms;Power transformers;Electric vehicle optimization;gym environment;reinforcement learning;mathematical programming;model predictive control (MPC)}, doi={10.1109/TITS.2024.3510945}}

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

Contributing

EV2Gym is an open-source project and welcomes contributions! Please get in contact with us if you would like to discuss about the simulator.