# mannuelf/predict-ev-growth-with-ml architecture

> Architecture diagram of the GitHub repository mannuelf/predict-ev-growth-with-ml, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mannuelf/predict-ev-growth-with-ml
- Repository: https://github.com/mannuelf/predict-ev-growth-with-ml

## Overview

This repository is a research prototype for EV infrastructure planning, with two principal workflows: forecasting Norwegian EV registrations with LSTMs, and optimizing charging-station placement with PPO on a synthetic demand grid. The forecast workflow loads and preprocesses SSB data, trains or tunes models, and produces recursive forecasts and visualizations. The placement workflow trains an agent in a coverage-and-budget environment and compares its results with random placement. README statements and sampled source support the main connections; unsampled modules are included where documented or indexed, but their internal wiring is not inferred.

Main entry points: [`src/models/train.py`](https://github.com/mannuelf/predict-ev-growth-with-ml/blob/main/src/models/train.py) (Model Training), [`src/models/forecast.py`](https://github.com/mannuelf/predict-ev-growth-with-ml/blob/main/src/models/forecast.py) (Forecast Runner), [`src/rl_agent/train_agent.py`](https://github.com/mannuelf/predict-ev-growth-with-ml/blob/main/src/rl_agent/train_agent.py) (Agent Training), [`src/visualization/plot_stations.py`](https://github.com/mannuelf/predict-ev-growth-with-ml/blob/main/src/visualization/plot_stations.py) (Station Visualizations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sales["EV Sales Forecasting"]
  node_lstm["Baseline LSTM<br/>[baseline_lstm.py]"]
  node_training["Model Training<br/>[train.py]"]
  node_tuning["Hyperparameter Study"]
  node_recursive["Recursive Forecast"]
  node_recursive_tuning["Recursive Tuning"]
  node_forecast_cli["Forecast Runner<br/>[forecast.py]"]
  node_checkpoints["Model Checkpoints"]
end

subgraph group_placement["Station Optimization"]
  node_env["Placement Environment<br/>[environment.py]"]
  node_ppo["PPO Agent<br/>[ppo_agent.py]"]
  node_agent_training["Agent Training<br/>[train_agent.py]"]
end

subgraph group_visuals["Results &amp; Analysis"]
  node_sales_viz["Sales Visualizations<br/>[plot_sales.py]"]
  node_station_viz["Station Visualizations<br/>[plot_stations.py]"]
  node_figures["Generated Figures"]
end

subgraph group_data["Data Handling"]
  node_data_processing["Data Processing<br/>[data_processing.py]"]
  node_ev_data["EV Data Module<br/>[baseline_lstm.py]"]
end

node_analyst(("Researcher"))
node_ssb["SSB Workbook"]

node_analyst -->|"trains model"| node_training
node_ssb -->|"supplies data"| node_training
node_training -->|"uses preprocessing"| node_ev_data
node_training -->|"trains"| node_lstm
node_training -->|"saves weights"| node_checkpoints
node_analyst -->|"runs study"| node_tuning
node_tuning -->|"tunes"| node_lstm
node_analyst -->|"requests forecast"| node_forecast_cli
node_forecast_cli -->|"loads model"| node_lstm
node_forecast_cli -->|"generates forecast"| node_recursive
node_forecast_cli -->|"renders forecast"| node_sales_viz
node_recursive -->|"uses model"| node_lstm
node_recursive_tuning -->|"tunes forecast"| node_recursive
node_analyst -->|"generates charts"| node_sales_viz
node_sales_viz -->|"loads and prepares"| node_ev_data
node_sales_viz -->|"writes charts"| node_figures
node_analyst -->|"trains agent"| node_agent_training
node_agent_training -->|"creates environment"| node_env
node_agent_training -->|"trains policy"| node_ppo
node_agent_training -->|"saves agent"| node_checkpoints
node_analyst -->|"compares placement"| node_station_viz
node_station_viz -->|"evaluates coverage"| node_env
node_station_viz -->|"runs agent"| node_ppo
node_station_viz -->|"writes charts"| node_figures
node_data_processing -.-> node_ev_data

click node_ssb "https://github.com/mannuelf/predict-ev-growth-with-ml/blob/main/data/07849_20251114-073957.xlsx"
click node_data_processing "https://github.com/mannuelf/predict-ev-growth-with-ml/blob/main/src/data_processing.py"
click node_ev_data "https://github.com/mannuelf/predict-ev-growth-with-ml/blob/main/src/models/baseline_lstm.py"
click node_lstm "https://github.com/mannuelf/predict-ev-growth-with-ml/blob/main/src/models/baseline_lstm.py"
click node_training "https://github.com/mannuelf/predict-ev-growth-with-ml/blob/main/src/models/train.py"
click node_tuning "https://github.com/mannuelf/predict-ev-growth-with-ml/blob/main/src/models/hyperparameter_tuning.py"
click node_recursive "https://github.com/mannuelf/predict-ev-growth-with-ml/blob/main/src/models/recursive_forecast.py"
click node_recursive_tuning "https://github.com/mannuelf/predict-ev-growth-with-ml/blob/main/src/models/recursive_tuning.py"
click node_forecast_cli "https://github.com/mannuelf/predict-ev-growth-with-ml/blob/main/src/models/forecast.py"
click node_sales_viz "https://github.com/mannuelf/predict-ev-growth-with-ml/blob/main/src/visualization/plot_sales.py"
click node_env "https://github.com/mannuelf/predict-ev-growth-with-ml/blob/main/src/rl_agent/environment.py"
click node_ppo "https://github.com/mannuelf/predict-ev-growth-with-ml/blob/main/src/rl_agent/ppo_agent.py"
click node_agent_training "https://github.com/mannuelf/predict-ev-growth-with-ml/blob/main/src/rl_agent/train_agent.py"
click node_station_viz "https://github.com/mannuelf/predict-ev-growth-with-ml/blob/main/src/visualization/plot_stations.py"
click node_checkpoints "https://github.com/mannuelf/predict-ev-growth-with-ml/tree/main/checkpoints"
click node_figures "https://github.com/mannuelf/predict-ev-growth-with-ml/tree/main/figures"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_lstm,node_training,node_tuning,node_recursive,node_recursive_tuning,node_forecast_cli,node_checkpoints toneBlue
class node_env,node_ppo,node_agent_training toneAmber
class node_sales_viz,node_station_viz,node_figures toneMint
class node_data_processing,node_ev_data toneRose
class node_analyst toneIndigo
class node_ssb toneTeal
```

## Components

### EV Sales Forecasting

- [Baseline LSTM](https://github.com/mannuelf/predict-ev-growth-with-ml/blob/main/src/models/baseline_lstm.py): `src/models/baseline_lstm.py`
- [Model Training](https://github.com/mannuelf/predict-ev-growth-with-ml/blob/main/src/models/train.py): `src/models/train.py`
- [Hyperparameter Study](https://github.com/mannuelf/predict-ev-growth-with-ml/blob/main/src/models/hyperparameter_tuning.py): `src/models/hyperparameter_tuning.py`
- [Recursive Forecast](https://github.com/mannuelf/predict-ev-growth-with-ml/blob/main/src/models/recursive_forecast.py): `src/models/recursive_forecast.py`
- [Recursive Tuning](https://github.com/mannuelf/predict-ev-growth-with-ml/blob/main/src/models/recursive_tuning.py): `src/models/recursive_tuning.py`
- [Forecast Runner](https://github.com/mannuelf/predict-ev-growth-with-ml/blob/main/src/models/forecast.py): `src/models/forecast.py`
- [Model Checkpoints](https://github.com/mannuelf/predict-ev-growth-with-ml/tree/main/checkpoints): `checkpoints`

### Station Optimization

- [Placement Environment](https://github.com/mannuelf/predict-ev-growth-with-ml/blob/main/src/rl_agent/environment.py): `src/rl_agent/environment.py`
- [PPO Agent](https://github.com/mannuelf/predict-ev-growth-with-ml/blob/main/src/rl_agent/ppo_agent.py): `src/rl_agent/ppo_agent.py`
- [Agent Training](https://github.com/mannuelf/predict-ev-growth-with-ml/blob/main/src/rl_agent/train_agent.py): `src/rl_agent/train_agent.py`

### Results & Analysis

- [Sales Visualizations](https://github.com/mannuelf/predict-ev-growth-with-ml/blob/main/src/visualization/plot_sales.py): `src/visualization/plot_sales.py`
- [Station Visualizations](https://github.com/mannuelf/predict-ev-growth-with-ml/blob/main/src/visualization/plot_stations.py): `src/visualization/plot_stations.py`
- [Generated Figures](https://github.com/mannuelf/predict-ev-growth-with-ml/tree/main/figures): `figures`

### Data Handling

- [Data Processing](https://github.com/mannuelf/predict-ev-growth-with-ml/blob/main/src/data_processing.py): `src/data_processing.py`
- [EV Data Module](https://github.com/mannuelf/predict-ev-growth-with-ml/blob/main/src/models/baseline_lstm.py): `src/models/baseline_lstm.py`

### Other components

- **Researcher**
- [SSB Workbook](https://github.com/mannuelf/predict-ev-growth-with-ml/blob/main/data/07849_20251114-073957.xlsx): `data/07849_20251114-073957.xlsx`

## Connections

- Researcher → Model Training: trains model (evidence: `README.md`)
- SSB Workbook → Model Training: supplies data (evidence: `README.md`)
- Model Training → EV Data Module: uses preprocessing (evidence: `README.md`)
- Model Training → Baseline LSTM: trains (evidence: `README.md`)
- Model Training → Model Checkpoints: saves weights (evidence: `README.md`)
- Researcher → Hyperparameter Study: runs study (evidence: `README.md`)
- Hyperparameter Study → Baseline LSTM: tunes (evidence: `src/models/hyperparameter_tuning.py`)
- Researcher → Forecast Runner: requests forecast (evidence: `src/models/forecast.py`)
- Forecast Runner → Baseline LSTM: loads model (evidence: `src/models/forecast.py`)
- Forecast Runner → Recursive Forecast: generates forecast (evidence: `src/models/forecast.py`)
- Forecast Runner → Sales Visualizations: renders forecast (evidence: `src/models/forecast.py`)
- Recursive Forecast → Baseline LSTM: uses model (evidence: `src/models/recursive_forecast.py`)
- Recursive Tuning → Recursive Forecast: tunes forecast (evidence: `src/models/recursive_tuning.py`)
- Researcher → Sales Visualizations: generates charts (evidence: `README.md`)
- Sales Visualizations → EV Data Module: loads and prepares (evidence: `src/visualization/plot_sales.py`)
- Sales Visualizations → Generated Figures: writes charts (evidence: `README.md`)
- Researcher → Agent Training: trains agent (evidence: `README.md`)
- Agent Training → Placement Environment: creates environment (evidence: `src/rl_agent/train_agent.py`)
- Agent Training → PPO Agent: trains policy (evidence: `src/rl_agent/train_agent.py`)
- Agent Training → Model Checkpoints: saves agent (evidence: `README.md`)
- Researcher → Station Visualizations: compares placement (evidence: `README.md`)
- Station Visualizations → Placement Environment: evaluates coverage (evidence: `src/visualization/plot_stations.py`)
- Station Visualizations → PPO Agent: runs agent (evidence: `src/visualization/plot_stations.py`)
- Station Visualizations → Generated Figures: writes charts (evidence: `README.md`)
- Data Processing → EV Data Module
