{"id":13724001,"url":"https://github.com/StavrosOrf/EV2Gym","last_synced_at":"2025-05-07T17:32:15.446Z","repository":{"id":231115449,"uuid":"667407131","full_name":"StavrosOrf/EV2Gym","owner":"StavrosOrf","description":"A V2G Simulation Environment for large scale EV charging optimization","archived":false,"fork":false,"pushed_at":"2024-10-15T22:21:45.000Z","size":98370,"stargazers_count":42,"open_issues_count":0,"forks_count":14,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-10-29T21:00:08.722Z","etag":null,"topics":["deep-reinforcement-learning","electric-vehicles","gurobi","gym","mathematical-programming","model-predictive-control","simulator"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/StavrosOrf.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-17T12:39:41.000Z","updated_at":"2024-10-23T13:22:45.000Z","dependencies_parsed_at":"2024-04-02T14:47:53.332Z","dependency_job_id":"b3973076-f4dd-44fc-991f-69b170530e1b","html_url":"https://github.com/StavrosOrf/EV2Gym","commit_stats":{"total_commits":374,"total_committers":3,"mean_commits":"124.66666666666667","dds":"0.19518716577540107","last_synced_commit":"bf5f2f01a9b95dd6d1b51b155eda92bbb8033d38"},"previous_names":["stavrosorf/ev2gym"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StavrosOrf%2FEV2Gym","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StavrosOrf%2FEV2Gym/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StavrosOrf%2FEV2Gym/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StavrosOrf%2FEV2Gym/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/StavrosOrf","download_url":"https://codeload.github.com/StavrosOrf/EV2Gym/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224628258,"owners_count":17343303,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deep-reinforcement-learning","electric-vehicles","gurobi","gym","mathematical-programming","model-predictive-control","simulator"],"created_at":"2024-08-03T01:01:48.260Z","updated_at":"2025-05-07T17:32:15.408Z","avatar_url":"https://github.com/StavrosOrf.png","language":"Python","funding_links":[],"categories":["Consumption"],"sub_categories":["Mobility and Transportation"],"readme":"\n# EV2Gym: A Realistic EV-V2G-Gym Simulator for EV Smart Charging\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg align=\"center\" src=\"https://github.com/StavrosOrf/EV2Gym/assets/17108978/86e921ad-d711-4dbb-b7b9-c69dee20da11\" width=\"55%\"/\u003e\n\u003c/div\u003e\n\n[![Python 3.6](https://img.shields.io/badge/python-3.6%2B-blue.svg)](https://www.python.org/downloads/release/python-360/) [![PyPI](https://img.shields.io/pypi/v/ev2gym.svg)](https://pypi.org/project/ev2gym/) ![License](https://img.shields.io/github/license/AI4Finance-Foundation/finrl.svg?color=brightgreen)\n---\n\nDevelop and evaluate **any type of smart charging algorithm**: from simple heuristics, Model Predictive Control, Mathematical Programming, to Reinforcement Learning!\n\nEV2Gym is **fully customizable** and easily **configurable**!\n\nThe EV2Gym **Paper** can be found at: [link](https://arxiv.org/abs/2404.01849).\n\nThe developed MPC algorithms **Paper** can be found at: [link](https://arxiv.org/abs/2405.11963).\n\n## Installation\n\nInstall the package using pip:\n```bash\npip install ev2gym\n```\n\n Run the example code below to get started ...\n```python\nfrom ev2gym.models.ev2gym_env import EV2Gym\nfrom ev2gym.baselines.mpc.V2GProfitMax import V2GProfitMaxOracle\nfrom ev2gym.baselines.heuristics import ChargeAsFastAsPossible\n\nconfig_file = \"ev2gym/example_config_files/V2GProfitPlusLoads.yaml\"\n\n# Initialize the environment\nenv = EV2Gym(config_file=config_file,\n              save_replay=True,\n              save_plots=True)\nstate, _ = env.reset()\nagent = V2GProfitMaxOracle(env,verbose=True) # optimal solution\n#        or \nagent = ChargeAsFastAsPossible() # heuristic\nfor t in range(env.simulation_length):\n    actions = agent.get_action(env) # get action from the agent/ algorithm\n    new_state, reward, done, truncated, stats = env.step(actions)  # takes action\n\n```\n- ### For Reinforcement Learning:\nTo train an RL agent, using the [StableBaselines3](https://stable-baselines3.readthedocs.io/en/master/) library, you can use the following code:\n```python\nimport gymnasium as gym\nfrom stable_baselines3 import PPO, A2C, DDPG, SAC, TD3\nfrom sb3_contrib import TQC, TRPO, ARS, RecurrentPPO\n\nfrom ev2gym.models.ev2gym_env import EV2Gym\n# Choose a default reward function and state function or create your own!!!\nfrom ev2gym.rl_agent.reward import profit_maximization, SquaredTrackingErrorReward, ProfitMax_TrPenalty_UserIncentives\nfrom ev2gym.rl_agent.state import V2G_profit_max, PublicPST, V2G_profit_max_loads\n\nconfig_file = \"ev2gym/example_config_files/V2GProfitPlusLoads.yaml\"\nenv = gym.make('EV2Gym-v1',\n                config_file=config_file,\n                reward_function=reward_function,\n                state_function=state_function)\n# Initialize the RL agent\nmodel = DDPG(\"MlpPolicy\", env)\n# Train the agent\nmodel.learn(total_timesteps=1_000_000,\n            progress_bar=True)\n# Evaluate the agent\nenv = model.get_env()\nobs = env.reset()\nstats = []\nfor i in range(1000):\n    action, _states = model.predict(obs, deterministic=True)\n    obs, reward, done, info = env.step(action)\n\n    if done:\n        stats.append(info)\n```\n!!! You can develop your own reward and state functions and use them in the environment.\n\n\n## Table of Contents\n\n- [Installation](#Installation)\n- [Overview](#Overview)\n- [Configuration File](#Configuration-File)\n- [File Structure](#File-Structure)\n- [Citing](#Citing-EV2Gym)\n- [License](#License)\n- [Contributing](#Contributing)\n\n\u003c!-- Bullet points with all the benefits --\u003e\n## Overview\n\n![EV2Gym](https://github.com/StavrosOrf/EV2Gym/assets/17108978/4695efa7-5c92-4118-9470-4cd16d262cf9)\n\n- The simulator can be used to evaluate any type of algorithm to gain insights into its efficiency.\n- The “gym environment” can readily support the development of RL algorithms.\n- Replays of simulations are saved and can be solved optimally using the Gurobi Solver.\n- Easy to incorporate additional functionality for any use-case.\n- 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.\n- The number and the topology of Transformers, Charging stations, and Electric Vehicles are parameterizable.\n- The user can import custom data.\n- Uses only open-source data:\n  - EV spawn rate, time of stay, and energy required are based on realistic probability distributions *ElaadNL* conditioned on time, day, month and year.\n  - *Pecan Street* data is used for the load profiles.\n  - *Renewables Ninja* data is used for the PV generation profiles.\n  - EV and Charger characteristics are based on real EVs and chargers existing in NL (*RVO Survey*).\n  - Charging/ Discharging prices are based on historical day-ahead prices from *ENTSO-e*.\n\nFocused on **realistic** parameters and **fully customizable**:\n\n- **Power Transformer** model:\n  - Max Power Limit\n  - Inflexible Loads, PV, Capacity Reduction events\n- **Charging Stations** model:\n  - Min and Max charge/discharge power/ Current\n  - Voltage and phases, AC or DC\n  - List of connected transformers\n- **Electric Vehicle** model:\n  - Connected charging station and port\n  - Min and Max battery energy level\n  - Time of arrival and departure\n  - Energy at arrival/ desired energy at departure\n  - Min and Max power levels\n  - Charge and discharge efficiency\n  - Constant-Current/ Constant-Voltage load-curve option\n- **Battery Degradation** model:\n  - Cyclic aging\n  - Calendar aging\n\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg align=\"center\" src=\"https://github.com/StavrosOrf/EV2Gym/assets/17108978/d15d258c-b454-498c-ba7f-634d858df3a6\" width=\"90%\"/\u003e\n\u003c/div\u003e\n\nAn 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.\n\n## Configuration File\n\nThe configuration file is used to set the parameters of the simulation. The configuration file is a YAML file that contains the following parameters:\n```yaml\n##############################################################################\n# Simulation Parameters\n##############################################################################\ntimescale: 15 # in minutes per step\nsimulation_length: 96 #90 # in steps per simulation\n\n##############################################################################\n# Date and Time\n##############################################################################\n# Year, month, \nyear: 2022 # 2015-2023\nmonth: 1 # 1-12\nday: 17 # 1-31\n# Whether to get a random date every time the environment is reset\nrandom_day: False # True or False\n# Simulation Starting Hour and minute do not change after the environment has been reset\nhour: 12 # Simulation starting hour (24 hour format)\nminute: 0 # Simulation starting minute (0-59)\n# Simulate weekdays, weekends, or both\nsimulation_days: both # weekdays, weekends, or both\n# EV Spawn Behavior\nscenario: public # public, private, or workplace\nspawn_multiplier: 10 # 1 is default, the higher the number the more EVs spawn\n\n##############################################################################\n# Prices\n##############################################################################\ndischarge_price_factor: 1.2 # how many times more abs(expensive/cheaper) it is to discharge than to charge\n\n##############################################################################\n# Charging Network\n##############################################################################\nv2g_enabled: True # True or False\nnumber_of_charging_stations: 15\nnumber_of_transformers: 3\nnumber_of_ports_per_cs: 2\n# Provide path if you want to load a specific charging topology,\n# else write None for a randomized one with the above parameters\ncharging_network_topology: None #./config_files/charging_topology_10.json\n\n##############################################################################\n# Power Setpoints Settings\n##############################################################################\n# How much the power setpoints can vary in percentage compared to the nominal power\n# The higher the number the easier it is to meet the power setpoints, the opposite for negative numbers\npower_setpoint_flexiblity: 20 # (in percentage +/- %)\n\n##############################################################################\n# Inflexible Loads, Solar Generation, and Demand Response\n##############################################################################\n# Whether to include inflexible loads in the transformer power limit, such as residential loads\ntr_seed: -1 # Seed for the transformer loads, -1 for random\n\ninflexible_loads:\n  include: False # True or False\n  inflexible_loads_capacity_multiplier_mean: 0.8 # 1 is default, the higher the number the more inflexible loads\n  forecast_mean: 100 # in percentage of load at time t%\n  forecast_std: 0 # in percentage of load at time t%\n\n# PV solar Power\nsolar_power:\n  include: False # True or False\n  solar_power_capacity_multiplier_mean: 2 # 1 is default, the higher the number the more solar power\n  forecast_mean: 100 # in percentage of load at time t%\n  forecast_std: 0 # in percentage of load at time t%\n\n# Whether to include demand response in the transformer power limit\ndemand_response:\n  include: False # True or False\n  events_per_day: 1\n  #How much of the transformer power limit can be used for demand response\n  event_capacity_percentage_mean: 25 # (in percentage +/- %)\n  event_capacity_percentage_std: 5 # (in percentage +/- %)\n  event_length_minutes_min: 60\n  event_length_minutes_max: 60\n  event_start_hour_mean: 18\n  event_start_hour_std: 2\n  # How many minutes ahead we know the event is going to happen\n  notification_of_event_minutes: 15\n\n##############################################################################\n# EV Specifications\n##############################################################################\nheterogeneous_ev_specs: False #if False, each EV has the same specifications\n# such as battery capacity, charging rate, etc.\n\n##############################################################################\n# Default Model values\n##############################################################################\n# These values are used if not using a charging network topology file or \n# if the EV specifications are not provided\n\n# Default Transformer model\ntransformer:\n  max_power: 100 # in kW\n# Default Charging Station model\ncharging_station:  \n  min_charge_current: 0 # Amperes\n  max_charge_current: 56 # Amperes\n  min_discharge_current: 0 # Amperes\n  max_discharge_current: -56 # Amperes\n  voltage: 230 # Volts\n  phases: 3 # 1,2, or 3\n# Default EV model\nev:\n  battery_capacity: 50 # in kWh\n  min_battery_capacity: 10 # in kWh\n  desired_capacity: 40 # in kWh\n  max_ac_charge_power: 22 # in kW\n  min_ac_charge_power: 0 # in kW\n  max_dc_charge_power: 50 # in kW\n  max_discharge_power: -22 # in kW\n  min_discharge_power: 0 # in kW\n  ev_phases: 3\n  transition_soc: 1 # 0-1 (0% - 100%)\n  charge_efficiency: 1 # 0-1 (0% - 100%)\n  discharge_efficiency: 1 # 0-1 (0% - 100%)\n  min_time_of_stay: 120 # in minutes\n```\n\n## File Structure\nThe file structure of the EV2Gym package is as follows:\n```bash\n├── ev2gym\n│   ├── baselines\n│   │   ├── gurobi_models/\n│   │   ├── mpc/\n│   │   ├── heuristics.py\n│   ├── data/\n│   ├── models\n│   │   ├── ev2gym_env.py\n│   │   ├── ev.py\n│   │   ├── transformer.py\n│   │   ├── ev_charger.py\n│   │   ├── replay.py\n│   │   ├── grid.py\n│   ├── rl_agent\n│   │   ├── reward.py\n│   │   ├── state.py\n│   ├── utilities\n│   │   ├── loaders.py\n│   │   ├── utils.py\n│   │   ├── arg_parser.py\n│   ├── example_config_files\n│   │   ├── BusinessPST.yaml\n│   │   ├── PublicPST.yaml\n│   │   ├── V2GProfitPlusLoads.yaml\n│   ├── visuals\n│   │   ├── plots.py\n│   │   ├── renderer.py\n│   ├── scripts/\n```\n\nClass Diagram of the EV2Gym Environment:\n\u003cdiv align=\"center\"\u003e\n\u003cimg align=\"center\" src=\"https://github.com/StavrosOrf/EV2Gym/assets/17108978/8ca5bf11-6ed4-44f6-9faf-386382609af1\" width=\"55%\"/\u003e\n\u003c/div\u003e\n\n## Citing EV2Gym\n\nIf you use this code in your research, please cite as:\n```bibtex\n@ARTICLE{10803908,\n  author={Orfanoudakis, Stavros and Diaz-Londono, Cesar and Emre Yılmaz, Yunus and Palensky, Peter and Vergara, Pedro P.},\n  journal={IEEE Transactions on Intelligent Transportation Systems}, \n  title={EV2Gym: A Flexible V2G Simulator for EV Smart Charging Research and Benchmarking}, \n  year={2025},\n  volume={26},\n  number={2},\n  pages={2410-2421},\n  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)},\n  doi={10.1109/TITS.2024.3510945}}\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE.md](LICENSE) file for details.\n\n\n## Contributing\n\nEV2Gym is an open-source project and welcomes contributions! Please get in contact with us if you would like to discuss about the simulator.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FStavrosOrf%2FEV2Gym","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FStavrosOrf%2FEV2Gym","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FStavrosOrf%2FEV2Gym/lists"}