# erc-fhv/open-ev-fleet architecture

> Architecture diagram of the GitHub repository erc-fhv/open-ev-fleet, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/erc-fhv/open-ev-fleet
- Repository: https://github.com/erc-fhv/open-ev-fleet

## Overview

Open-EV-Fleet is a research framework for preparing electric-fleet data, modeling scenarios, and comparing charging simulations and optimization algorithms. A typical workflow converts operational data into fleet tables, constructs a scenario, runs a simulation or optimization, and examines analysis results. The tree and README document MILP, heuristic, greedy/lazy/FCFS/load-balanced simulation, charging scenarios, and VDV452/DIVA conversion; sampled source confirms scenario modeling, IVU conversion, simulation, preprocessing, and load-balancer responsibilities. Some subsystem connections are omitted where excerpts do not establish the caller or data flow.

Main entry points: [`packages/openevfleet/src/openevfleet/simulation/abstract_infra.py`](https://github.com/erc-fhv/open-ev-fleet/blob/main/packages/openevfleet/src/openevfleet/simulation/abstract_infra.py) (Simulation engine), [`packages/openevfleet/scripts/public/run_algorithm.py`](https://github.com/erc-fhv/open-ev-fleet/blob/main/packages/openevfleet/scripts/public/run_algorithm.py) (Run scripts), [`packages/openevfleet/src/openevfleet/system/scenario.py`](https://github.com/erc-fhv/open-ev-fleet/blob/main/packages/openevfleet/src/openevfleet/system/scenario.py) (Scenario), [`packages/openevfleet/src/openevfleet/optimization/heuristic_minload.py`](https://github.com/erc-fhv/open-ev-fleet/blob/main/packages/openevfleet/src/openevfleet/optimization/heuristic_minload.py) (Min-load heuristic)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_io["Data conversion"]
  node_parser["Input parsers"]
  node_ivu["IVU conversion<br/>[ivu_data_trans.py]"]
  node_gps["GPS mapping"]
end

subgraph group_model["Fleet model"]
  node_scenario["Scenario<br/>[scenario.py]"]
  node_tables["Fleet tables<br/>[data_table.py]"]
  node_datasets["Fleet records"]
end

subgraph group_execution["Simulation and optimization"]
  node_preprocess["MILP preprocessing<br/>[milp_preprocess.py]"]
  node_simbase["Simulation engine<br/>[abstract_infra.py]"]
  node_simvariants["Simulation variants"]
  node_heuristic["Min-load heuristic"]
  node_milp["MILP objectives"]
  node_balancer["Load balancers"]
  node_state["Event state"]
end

subgraph group_results["Analysis results"]
  node_timetables["Power timetables"]
  node_analysis["Analysis<br/>[analysis.py]"]
end

node_operator(("Researcher"))
node_run["Run scripts<br/>[run_algorithm.py]"]
node_ivuinput["IVU data"]
node_x10input["X10 files"]

node_operator -->|"starts run"| node_run
node_x10input -->|"parses X10"| node_parser
node_ivuinput -->|"parses IVU"| node_parser
node_parser -->|"provides tables"| node_ivu
node_ivu -->|"creates fleet data"| node_tables
node_tables -->|"builds scenario"| node_scenario
node_scenario -->|"holds records"| node_datasets
node_scenario -->|"supplies trips"| node_simbase
node_run -->|"selects scenario"| node_scenario
node_run -->|"selects algorithm"| node_milp
node_run -->|"selects simulation"| node_simvariants
node_heuristic -->|"runs reference simulation"| node_simvariants
node_heuristic -->|"prepares optimization input"| node_preprocess
node_simbase -->|"updates events"| node_state
node_simvariants -->|"implements engine"| node_simbase
node_simbase -->|"requests power allocation"| node_balancer
node_milp -->|"prepares MILP input"| node_preprocess
node_milp -.->|"uses load balancing"| node_balancer
node_simbase -->|"records power results"| node_timetables
node_analysis -->|"exposes results"| node_timetables
node_heuristic -->|"creates analysis"| node_analysis
node_gps -.->|"maps IVU locations"| node_ivu

click node_run "https://github.com/erc-fhv/open-ev-fleet/blob/main/packages/openevfleet/scripts/public/run_algorithm.py"
click node_parser "https://github.com/erc-fhv/open-ev-fleet/tree/main/packages/openevfleet_io/src/openevfleet_io/parser"
click node_ivu "https://github.com/erc-fhv/open-ev-fleet/blob/main/packages/openevfleet_io/src/openevfleet_io/model/ivu_data_trans.py"
click node_gps "https://github.com/erc-fhv/open-ev-fleet/blob/main/packages/openevfleet_io/src/openevfleet_io/gps/ivu_data_trans_gps.py"
click node_scenario "https://github.com/erc-fhv/open-ev-fleet/blob/main/packages/openevfleet/src/openevfleet/system/scenario.py"
click node_tables "https://github.com/erc-fhv/open-ev-fleet/blob/main/packages/openevfleet/src/openevfleet/data_tables/data_table.py"
click node_datasets "https://github.com/erc-fhv/open-ev-fleet/tree/main/packages/openevfleet/src/openevfleet/data_sets"
click node_preprocess "https://github.com/erc-fhv/open-ev-fleet/blob/main/packages/openevfleet/src/openevfleet/milp_utils/milp_preprocess.py"
click node_simbase "https://github.com/erc-fhv/open-ev-fleet/blob/main/packages/openevfleet/src/openevfleet/simulation/abstract_infra.py"
click node_simvariants "https://github.com/erc-fhv/open-ev-fleet/tree/main/packages/openevfleet/src/openevfleet/simulation"
click node_heuristic "https://github.com/erc-fhv/open-ev-fleet/blob/main/packages/openevfleet/src/openevfleet/optimization/heuristic_minload.py"
click node_milp "https://github.com/erc-fhv/open-ev-fleet/tree/main/packages/openevfleet/src/openevfleet/optimization"
click node_balancer "https://github.com/erc-fhv/open-ev-fleet/tree/main/packages/openevfleet/src/openevfleet/load_balancer"
click node_state "https://github.com/erc-fhv/open-ev-fleet/tree/main/packages/openevfleet/src/openevfleet/state_machine"
click node_timetables "https://github.com/erc-fhv/open-ev-fleet/tree/main/packages/openevfleet/src/openevfleet/time_tables"
click node_analysis "https://github.com/erc-fhv/open-ev-fleet/blob/main/packages/openevfleet/src/openevfleet/system/analysis.py"

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_parser,node_ivu,node_gps toneBlue
class node_scenario,node_tables,node_datasets toneAmber
class node_preprocess,node_simbase,node_simvariants,node_heuristic,node_milp,node_balancer,node_state toneMint
class node_timetables,node_analysis toneRose
class node_operator,node_ivuinput,node_x10input toneIndigo
class node_run toneTeal
```

## Components

### Data conversion

- [Input parsers](https://github.com/erc-fhv/open-ev-fleet/tree/main/packages/openevfleet_io/src/openevfleet_io/parser): `packages/openevfleet_io/src/openevfleet_io/parser`
- [IVU conversion](https://github.com/erc-fhv/open-ev-fleet/blob/main/packages/openevfleet_io/src/openevfleet_io/model/ivu_data_trans.py): `packages/openevfleet_io/src/openevfleet_io/model/ivu_data_trans.py`
- [GPS mapping](https://github.com/erc-fhv/open-ev-fleet/blob/main/packages/openevfleet_io/src/openevfleet_io/gps/ivu_data_trans_gps.py): `packages/openevfleet_io/src/openevfleet_io/gps/ivu_data_trans_gps.py`

### Fleet model

- [Scenario](https://github.com/erc-fhv/open-ev-fleet/blob/main/packages/openevfleet/src/openevfleet/system/scenario.py): `packages/openevfleet/src/openevfleet/system/scenario.py`
- [Fleet tables](https://github.com/erc-fhv/open-ev-fleet/blob/main/packages/openevfleet/src/openevfleet/data_tables/data_table.py): `packages/openevfleet/src/openevfleet/data_tables/data_table.py`
- [Fleet records](https://github.com/erc-fhv/open-ev-fleet/tree/main/packages/openevfleet/src/openevfleet/data_sets): `packages/openevfleet/src/openevfleet/data_sets`

### Simulation and optimization

- [MILP preprocessing](https://github.com/erc-fhv/open-ev-fleet/blob/main/packages/openevfleet/src/openevfleet/milp_utils/milp_preprocess.py): `packages/openevfleet/src/openevfleet/milp_utils/milp_preprocess.py`
- [Simulation engine](https://github.com/erc-fhv/open-ev-fleet/blob/main/packages/openevfleet/src/openevfleet/simulation/abstract_infra.py): `packages/openevfleet/src/openevfleet/simulation/abstract_infra.py`
- [Simulation variants](https://github.com/erc-fhv/open-ev-fleet/tree/main/packages/openevfleet/src/openevfleet/simulation): `packages/openevfleet/src/openevfleet/simulation`
- [Min-load heuristic](https://github.com/erc-fhv/open-ev-fleet/blob/main/packages/openevfleet/src/openevfleet/optimization/heuristic_minload.py): `packages/openevfleet/src/openevfleet/optimization/heuristic_minload.py`
- [MILP objectives](https://github.com/erc-fhv/open-ev-fleet/tree/main/packages/openevfleet/src/openevfleet/optimization): `packages/openevfleet/src/openevfleet/optimization`
- [Load balancers](https://github.com/erc-fhv/open-ev-fleet/tree/main/packages/openevfleet/src/openevfleet/load_balancer): `packages/openevfleet/src/openevfleet/load_balancer`
- [Event state](https://github.com/erc-fhv/open-ev-fleet/tree/main/packages/openevfleet/src/openevfleet/state_machine): `packages/openevfleet/src/openevfleet/state_machine`

### Analysis results

- [Power timetables](https://github.com/erc-fhv/open-ev-fleet/tree/main/packages/openevfleet/src/openevfleet/time_tables): `packages/openevfleet/src/openevfleet/time_tables`
- [Analysis](https://github.com/erc-fhv/open-ev-fleet/blob/main/packages/openevfleet/src/openevfleet/system/analysis.py): `packages/openevfleet/src/openevfleet/system/analysis.py`

### Other components

- **Researcher**
- [Run scripts](https://github.com/erc-fhv/open-ev-fleet/blob/main/packages/openevfleet/scripts/public/run_algorithm.py): `packages/openevfleet/scripts/public/run_algorithm.py`
- **IVU data**
- **X10 files**

## Connections

- Researcher → Run scripts: starts run
- X10 files → Input parsers: parses X10
- IVU data → Input parsers: parses IVU
- Input parsers → IVU conversion: provides tables
- IVU conversion → Fleet tables: creates fleet data
- Fleet tables → Scenario: builds scenario
- Scenario → Fleet records: holds records
- Scenario → Simulation engine: supplies trips
- Run scripts → Scenario: selects scenario
- Run scripts → MILP objectives: selects algorithm
- Run scripts → Simulation variants: selects simulation
- Min-load heuristic → Simulation variants: runs reference simulation
- Min-load heuristic → MILP preprocessing: prepares optimization input
- Simulation engine → Event state: updates events
- Simulation variants → Simulation engine: implements engine
- Simulation engine → Load balancers: requests power allocation
- MILP objectives → MILP preprocessing: prepares MILP input
- MILP objectives → Load balancers: uses load balancing
- Simulation engine → Power timetables: records power results
- Analysis → Power timetables: exposes results
- Min-load heuristic → Analysis: creates analysis
- GPS mapping → IVU conversion: maps IVU locations