Apppublic

GargiG15/SOLAR_MICROGRID

sourceHugging Faceupdated 6mo agoView on Hugging Face

0likes

App README

☀️ SolarMicrogridEnv — OpenEnv-Compliant Solar Energy RL Environment

An OpenEnv-compliant environment simulating a solar-powered microgrid serving multiple homes. An AI agent learns to optimally allocate solar-generated electricity between direct use and battery storage, while reacting to weather patterns and demand peaks.

🌍 Real-World Task

Managing a solar microgrid is a genuine engineering challenge:

—Solar generation is intermittent and weather-dependent
—Home demand peaks at morning and evening hours
—Battery storage has limited capacity and degrades with overuse
—Grid import is costly (especially at peak hours)
—Blackouts cause serious harm to residents

This environment trains agents that could control real residential microgrids, with direct application to home energy management systems (HEMS), virtual power plants (VPPs), and rural electrification projects.

🎯 Tasks

Task	Difficulty	Homes	Hours	Features
`single_home_basic`	Easy	1	24	Fixed weather, basic demand
`multi_home_seasonal`	Medium	4	72	Seasonal solar variation, load balancing
`grid_resilience`	Hard	6	168	Grid outages, TOU pricing, 6 homes

🔧 Action Space

json

{
  "battery_charge_kw": 2.5,      // Positive=charge, negative=discharge
  "grid_import_kw": 0.0,         // Extra power from utility grid
  "grid_export_kw": 0.5,         // Surplus to sell to grid
  "load_priority": [0, 1, 2, 3]  // Home priority during shortage
}

👁️ Observation Space

json

{
  "hour": 14,
  "day": 2,
  "solar_generation_kw": 3.2,
  "weather": "partly_cloudy",
  "battery_soc": 0.65,
  "battery_health": 0.998,
  "battery_capacity_kwh": 40.0,
  "home_demand_kw": [1.2, 0.8, 1.5, 0.9],
  "total_demand_kw": 4.4,
  "grid_import_kw": 0.0,
  "grid_export_kw": 0.0,
  "grid_price_per_kwh": 0.12,
  "blackout_homes": [],
  "solar_forecast": [2.8, 1.5, 0.2],
  "demand_forecast": [4.6, 5.2, 4.0],
  "episode_step": 32,
  "max_steps": 72,
  "cumulative_reward": 21.4
}

🏆 Reward Function

The reward signal provides partial progress at every step:

Component	Range	Description
Self-sufficiency bonus	0 to 0.8	Fraction of demand met by solar/battery
Grid import penalty	-∞ to 0	Proportional to import × price
Blackout penalty	-0.5/home	Per home without power per step
Battery health penalty	≤ 0	Proportional to health degradation
Export bonus	≥ 0	Revenue from selling surplus

🚀 Quick Start

Run locally

bash

# Clone and install
pip install -r requirements.txt

# Run tests
python tests/test_env.py

# Run baseline
python scripts/run_baseline.py

# Start server
python server/app.py

Run with Docker

bash

docker build -t solar-microgrid-env .
docker run -p 7860:7860 solar-microgrid-env

API Usage

bash

# Reset environment
curl -X POST http://localhost:7860/reset \
  -H "Content-Type: application/json" \
  -d '{"task": "single_home_basic", "seed": 42}'

# Take a step
curl -X POST http://localhost:7860/step \
  -H "Content-Type: application/json" \
  -d '{"battery_charge_kw": 2.0, "grid_import_kw": 0.0, "grid_export_kw": 0.5}'

# Get state
curl http://localhost:7860/state

# Get score
curl http://localhost:7860/score

Run AI agent

bash

# Start server first
python server/app.py &

# Set your API credentials
export HF_TOKEN=hf_your_token
export MODEL_NAME=Qwen/Qwen2.5-72B-Instruct
export SOLAR_TASK=single_home_basic

# Run inference
python inference.py

📊 Baseline Scores (Heuristic Policy)

Task	Score	Blackout Rate	Avg Self-Sufficiency
singlehomebasic	~0.52	0%	~85%
multihomeseasonal	~0.44	<5%	~78%
grid_resilience	~0.38	~8%	~72%

Scores will vary slightly by seed. Run `python scripts/run_baseline.py` to reproduce.

📁 Project Structure

solar_microgrid_env/
├── solar_microgrid_env.py  # Core environment (models + physics)
├── graders.py              # Task graders (easy/medium/hard)
├── inference.py            # OpenAI-client inference script
├── openenv.yaml            # OpenEnv metadata
├── requirements.txt
├── Dockerfile
├── server/
│   └── app.py              # FastAPI HTTP server
├── tests/
│   └── test_env.py         # Full test suite
├── scripts/
│   └── run_baseline.py     # Baseline scoring script
└── README.md

📝 License

MIT License — free to use for research and training.