---
name: plan-rozwoju-aplikacji
description: Plan Rozwoju Aplikacji dla projektu Hybrydowy Ekosystem EVSE & BSS, krok po kroku od mapy miasta, przez teorię kolejek i model agentowy, aż po optymalizację wielokryterialną.
---

# Plan Rozwoju Aplikacji: Hybrydowy Ekosystem EVSE & BSS

## Faza 1: Fundamenty Geoprzestrzenne i Środowisko (Cyfrowa Plansza)
Celem tej fazy jest przygotowanie "planszy", na której będą operować agenci i algorytmy, z maksymalną optymalizacją czasu dostępu do danych dróg.

### 1.1. Inicjalizacja projektu i mapy miasta:
- [x] Pobranie granic Wrocławia (zrealizowane za pomocą API Nominatim).
- [x] Przygotowanie danych demograficznych (oczyszczone i przefiltrowane dane REJSTAT/REJURB dla Wrocławia).
- [ ] Pobranie grafu drogowego za pomocą biblioteki OSMnx.
- [ ] Filtrowanie grafu (tylko drogi przejezdne dla samochodów, odrzucenie ścieżek rowerowych itp.).

### 1.2. Wdrożenie Siatki H3 (Uber):
- Nałożenie siatki heksagonalnej (**rozdzielczość 8**) na poligon Wrocławia za pomocą biblioteki h3-py.
- Zmapowanie każdego aktywnego heksagonu na "reprezentatywny" węzeł drogowy grafu OSMnx (np. węzeł najbliższy środkowi heksagonu).
- **Suitability Map:** Odfiltrowanie heksagonów nienadających się pod zabudowę (parki, woda) na podstawie danych Land Use / POI.

### 1.3. Generowanie i Caching Macierzy O-D (Origin-Destination):
- Napisanie skryptu, który raz oblicza najkrótsze czasy i dystanse przejazdu pomiędzy wszystkimi reprezentatywnymi węzłami heksagonów (np. algorytmem Dijkstry wywoływanym z biblioteki NetworkX lub igraph dla wydajności).
- **Traffic Factor:** Implementacja dynamicznego mnożnika czasu przejazdu (np. 1.5x w godzinach szczytu) dla zwiększenia realizmu w ABM.
- Zapisanie wyników do szybkiej struktury w pamięci (np. tablica NumPy lub słownik Pythonowy) oraz na dysk (np. plik `.pickle` lub `.parquet`), aby przy kolejnych uruchomieniach ładować macierz w ułamku sekundy.

## Faza 2: Szybka Ewaluacja i Modele Analityczne (Teoria Kolejek)
Przygotowanie funkcji kosztu i szybkiej oceny rozwiązań, zanim wejdziemy w ciężką symulację.

### 2.1. Modelowanie infrastruktury (CAPEX i OPEX):
- Zdefiniowanie kosztów budowy stanowisk EVSE, stacji BSS oraz Stacji Wielousługowych (współdzielone przyłącze = niższy koszt).
- Opracowanie modelu kosztów degradacji baterii i zysków z arbitrażu (ToU / V2G).

### 2.2. Implementacja Teorii Masowej Obsługi (M/M/s/N):
- Napisanie klas estymujących czasy oczekiwania i długości kolejek dla podanej przepustowości stacji i przewidywanego natężenia ruchu.
- **Peak-Hour Logic:** Przygotowanie "szybkiej funkcji oceny" opartej na scenariuszu najgorszego przypadku (godzina szczytowa), a nie średniej dobowej, aby uniknąć niedoszacowania kolejek.
- Funkcja wypluwa szacunkowy całkowity czas obsługi i VoT (Value of Time) dla populacji.

## Faza 3: Silnik Symulacji Agentowej (ABM) i Macro-ruch
Budowa rdzenia symulacji opartego na architekturze zdarzeniowej (Event-Driven).

### 3.1. Wybór i konfiguracja środowiska ABM:
- Wstępny setup biblioteki **Mesa** (z opcją późniejszej migracji na SimPy w przypadku problemów z wydajnością przy dużej skali).

### 3.2. Implementacja logiki stacji (Zasoby):
- Stacje ładujące jako zasoby o ograniczonej pojemności.
- **BSS Inventory Management:** Śledzenie stanu naładowania (SoC) każdej baterii w magazynie stacji z osobna. Jeśli liczba naładowanych baterii wynosi 0, czas wymiany wydłuża się do czasu naładowania pierwszej dostępnej baterii.
- Logika nocnego ładowania (tani prąd) i oddawania do sieci (V2G/B2G).

### 3.3. Agenci i Zdarzeniowy Macro-ruch:
- Zdefiniowanie klasy agentów (kierowcy prywatni o zróżnicowanym VoT i profilach dojazdów).
- Implementacja Macro-ruchu: Zamiast aktualizować pozycję agenta w każdej sekundzie symulacji, agent generuje zdarzenie: odpytaj macierz O-D -> dodaj czas_dojazdu do czas_obecny -> zaplanuj przyjazd na stację.
- Mechanizm wyboru: Agent przed wyjazdem analizuje dynamiczne ceny, swoje VoT i szacowany czas dojazdu, po czym decyduje: "jadę do BSS za 100 PLN" albo "jadę do EVSE za 40 PLN, bo mam czas".

### 3.4. Rejestrowanie Metryk (Logowanie):
- Zliczanie odrzuconych klientów, realnego czasu spędzonego w korkach/kolejkach, wydatków agentów i ROI dla stacji.

## Faza 4: Optymalizacja Wielokryterialna (NSGA-II)
Budowa "mózgu" decyzyjnego generującego układy stacji.

### 4.1. Reprezentacja Chromosomu (Genotyp):
- **Fixed-Length Representation:** Chromosom o stałej długości (np. lista 100 potencjalnych lokalizacji) z flagą "aktywny/nieaktywny" dla każdej stacji.
- Kodowanie: `[Is_Active, H3_Index, Typ, Liczba_EVSE, Liczba_Baterii_BSS]`.

### 4.2. Algorytm Genetyczny:
- Integracja biblioteki do optymalizacji (np. pymoo lub DEAP).
- Implementacja operatorów krzyżowania i mutacji specyficznych dla mapy (np. mutacja przesuwająca stację do sąsiedniego heksagonu H3).

### 4.3. Zdefiniowanie Funkcji Celu:
- $f_1$: Minimalizacja CAPEX (Koszt budowy) + **Kara za nadmiarowość** (penalty za każdą aktywną stację powyżej minimum).
- $f_2$: Minimalizacja VoT + OPEX + Kary (Koszt społeczny wg scenariusza szczytowego).

## Faza 5: Pętla Sprzężenia Zwrotnego (Iterative Closed-Loop)
Połączenie wszystkich klocków w samodoskonalący się mechanizm.

### 5.1. Filtr Top 5%:
- Logika wyłuskująca rozwiązania leżące najbliżej wygenerowanego Frontu Pareto po fazie analitycznej (Teoria Kolejek).

### 5.2. Pipeline Egzekucji:
- Automatyczne wstrzykiwanie najlepszych chromosomów z punktu 5.1 do silnika ABM (uruchomienie Macro-ruchu).

### 5.3. Mechanizm Kary (Penalty System):
- Obliczanie delty pomiędzy wynikiem szybkim (kolejkowym) a wynikiem rzeczywistym (z ABM - uwzględniającym np. to, że agenci zablokowali jedną konkretną stację przez źle obliczone opłaty ToU).
- Zwrócenie zmodyfikowanego $f_2$ z powrotem do algorytmu NSGA-II dla kolejnych generacji.

## Faza 6: Ewaluacja, Wizualizacja i Praca Pisemna

### 6.1. Wizualizacja Frontu Pareto:
- Wykresy 2D/3D z użyciem matplotlib / plotly.

### 6.2. Mapping:
- Wygenerowanie interaktywnej mapy końcowych rozwiązań na siatce H3 w folium lub kepler.gl (pokazujące gdzie we Wrocławiu algorytm postawił BSS, a gdzie EVSE).

### 6.3. Analiza wrażliwości:
- Testowanie modelu dla różnych parametrów wejściowych (np. zmiana ceny prądu, zmiana średniego dochodu/VoT mieszkańców, zmiana zasięgu pojazdów).