# hpcclab/felare architecture

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

- Interactive diagram: https://gitdiagram.com/hpcclab/felare
- Repository: https://github.com/hpcclab/felare

## Overview

FELARE is a discrete-event simulator for fair scheduling of machine-learning workloads across heterogeneous edge machines. The main workflow initializes configuration and machines, loads a workload into arrival events, dispatches events through a selected scheduler, and reports simulation results; a GUI can drive and visualize the same simulation. Scheduling, task/machine execution, workload generation, and analysis are distinct product areas. The README identifies the research goal, while source excerpts show only part of runtime wiring; unsampled report and scheduler relationships are therefore not inferred.

Main entry points: [`CODE/utils/simulator.py`](https://github.com/hpcclab/felare/blob/main/CODE/utils/simulator.py) (Event simulator), [`CODE/utils/machine.py`](https://github.com/hpcclab/felare/blob/main/CODE/utils/machine.py) (Edge machine), [`CODE/main.py`](https://github.com/hpcclab/felare/blob/main/CODE/main.py) (Run driver), [`CODE/gui.py`](https://github.com/hpcclab/felare/blob/main/CODE/gui.py) (Simulation GUI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Run and visualize"]
  node_main["Run driver<br/>[main.py]"]
  node_gui["Simulation GUI<br/>[gui.py]"]
end

subgraph group_sim["Simulation runtime"]
  node_config["Configuration<br/>[config.py]"]
  node_simulator["Event simulator<br/>[simulator.py]"]
  node_events["Event model<br/>[event.py]"]
  node_eventqueue["Event queue<br/>[event_queue.py]"]
  node_task["Task state<br/>[task.py]"]
  node_tasktypes["Task types<br/>[task_type.py]"]
  node_machine["Edge machine<br/>[machine.py]"]
  node_basemachine["Machine base<br/>[base_machine.py]"]
  node_queue["Task queue<br/>[queue.py]"]
end

subgraph group_sched["Scheduling policies"]
  node_basescheduler["Scheduler base<br/>[base_scheduler.py]"]
  node_ee["Energy-efficient policy<br/>[EE.py]"]
  node_fee["Fair energy policy<br/>[FEE.py]"]
  node_mmu["MMU policy<br/>[MMU.py]"]
  node_otherpolicies["Other policies"]
end

subgraph group_work["Workload modeling"]
  node_workloadgen["Workload generator"]
  node_workload["Workload model<br/>[workload.py]"]
  node_sampling["Sampling and timing<br/>[random_sample.py]"]
  node_execution["Execution estimates<br/>[execution_time.py]"]
end

subgraph group_analysis["Results analysis"]
  node_reports["Analysis reports"]
end

node_operator(("Operator"))

node_operator -->|"starts"| node_main
node_operator -->|"interacts"| node_gui
node_main -->|"initializes"| node_config
node_main -->|"creates"| node_machine
node_main -->|"runs"| node_simulator
node_main -->|"opens"| node_gui
node_gui -->|"controls"| node_simulator
node_config -->|"creates"| node_eventqueue
node_config -->|"creates"| node_tasktypes
node_simulator -->|"creates"| node_events
node_simulator -->|"loads"| node_task
node_simulator -->|"queues arrivals"| node_eventqueue
node_simulator -->|"dispatches events"| node_basescheduler
node_simulator -->|"selects policy"| node_ee
node_simulator -->|"selects policy"| node_fee
node_simulator -->|"selects policy"| node_mmu
node_simulator -->|"selects policy"| node_otherpolicies
node_simulator -->|"handles events"| node_machine
node_machine -->|"extends"| node_basemachine
node_machine -->|"uses"| node_queue
node_machine -->|"schedules execution"| node_events
node_ee -->|"extends"| node_basescheduler
node_fee -->|"extends"| node_basescheduler
node_mmu -->|"extends"| node_basescheduler
node_ee -->|"maps tasks"| node_machine
node_fee -->|"admits tasks"| node_machine
node_mmu -->|"maps tasks"| node_machine
node_workloadgen -->|"generates"| node_workload
node_workloadgen -->|"initializes"| node_config
node_workloadgen -->|"imports"| node_execution
node_workload -->|"samples"| node_sampling
node_workload -->|"estimates"| node_execution
node_simulator -->|"writes results"| node_reports
node_gui -->|"requests report"| node_reports

click node_main "https://github.com/hpcclab/felare/blob/main/CODE/main.py"
click node_gui "https://github.com/hpcclab/felare/blob/main/CODE/gui.py"
click node_config "https://github.com/hpcclab/felare/blob/main/CODE/utils/config.py"
click node_simulator "https://github.com/hpcclab/felare/blob/main/CODE/utils/simulator.py"
click node_events "https://github.com/hpcclab/felare/blob/main/CODE/utils/event.py"
click node_eventqueue "https://github.com/hpcclab/felare/blob/main/CODE/utils/event_queue.py"
click node_task "https://github.com/hpcclab/felare/blob/main/CODE/utils/task.py"
click node_tasktypes "https://github.com/hpcclab/felare/blob/main/CODE/utils/task_type.py"
click node_machine "https://github.com/hpcclab/felare/blob/main/CODE/utils/machine.py"
click node_basemachine "https://github.com/hpcclab/felare/blob/main/CODE/utils/base_machine.py"
click node_queue "https://github.com/hpcclab/felare/blob/main/CODE/utils/queue.py"
click node_basescheduler "https://github.com/hpcclab/felare/blob/main/CODE/utils/base_scheduler.py"
click node_ee "https://github.com/hpcclab/felare/blob/main/CODE/utils/schedulers/EE.py"
click node_fee "https://github.com/hpcclab/felare/blob/main/CODE/utils/schedulers/FEE.py"
click node_mmu "https://github.com/hpcclab/felare/blob/main/CODE/utils/schedulers/MMU.py"
click node_otherpolicies "https://github.com/hpcclab/felare/tree/main/CODE/utils/schedulers"
click node_workloadgen "https://github.com/hpcclab/felare/blob/main/CODE/workload_generator.py"
click node_workload "https://github.com/hpcclab/felare/blob/main/CODE/utils/workload.py"
click node_sampling "https://github.com/hpcclab/felare/blob/main/CODE/utils/random_sample.py"
click node_execution "https://github.com/hpcclab/felare/blob/main/CODE/utils/execution_time.py"
click node_reports "https://github.com/hpcclab/felare/tree/main/CODE/utils/report"

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_main,node_gui toneBlue
class node_config,node_simulator,node_events,node_eventqueue,node_task,node_tasktypes,node_machine,node_basemachine,node_queue toneAmber
class node_basescheduler,node_ee,node_fee,node_mmu,node_otherpolicies toneMint
class node_workloadgen,node_workload,node_sampling,node_execution toneRose
class node_reports,node_operator toneIndigo
```

## Components

### Run and visualize

- [Run driver](https://github.com/hpcclab/felare/blob/main/CODE/main.py): `CODE/main.py`
- [Simulation GUI](https://github.com/hpcclab/felare/blob/main/CODE/gui.py): `CODE/gui.py`

### Simulation runtime

- [Configuration](https://github.com/hpcclab/felare/blob/main/CODE/utils/config.py): `CODE/utils/config.py`
- [Event simulator](https://github.com/hpcclab/felare/blob/main/CODE/utils/simulator.py): `CODE/utils/simulator.py`
- [Event model](https://github.com/hpcclab/felare/blob/main/CODE/utils/event.py): `CODE/utils/event.py`
- [Event queue](https://github.com/hpcclab/felare/blob/main/CODE/utils/event_queue.py): `CODE/utils/event_queue.py`
- [Task state](https://github.com/hpcclab/felare/blob/main/CODE/utils/task.py): `CODE/utils/task.py`
- [Task types](https://github.com/hpcclab/felare/blob/main/CODE/utils/task_type.py): `CODE/utils/task_type.py`
- [Edge machine](https://github.com/hpcclab/felare/blob/main/CODE/utils/machine.py): `CODE/utils/machine.py`
- [Machine base](https://github.com/hpcclab/felare/blob/main/CODE/utils/base_machine.py): `CODE/utils/base_machine.py`
- [Task queue](https://github.com/hpcclab/felare/blob/main/CODE/utils/queue.py): `CODE/utils/queue.py`

### Scheduling policies

- [Scheduler base](https://github.com/hpcclab/felare/blob/main/CODE/utils/base_scheduler.py): `CODE/utils/base_scheduler.py`
- [Energy-efficient policy](https://github.com/hpcclab/felare/blob/main/CODE/utils/schedulers/EE.py): `CODE/utils/schedulers/EE.py`
- [Fair energy policy](https://github.com/hpcclab/felare/blob/main/CODE/utils/schedulers/FEE.py): `CODE/utils/schedulers/FEE.py`
- [MMU policy](https://github.com/hpcclab/felare/blob/main/CODE/utils/schedulers/MMU.py): `CODE/utils/schedulers/MMU.py`
- [Other policies](https://github.com/hpcclab/felare/tree/main/CODE/utils/schedulers): `CODE/utils/schedulers`

### Workload modeling

- [Workload generator](https://github.com/hpcclab/felare/blob/main/CODE/workload_generator.py): `CODE/workload_generator.py`
- [Workload model](https://github.com/hpcclab/felare/blob/main/CODE/utils/workload.py): `CODE/utils/workload.py`
- [Sampling and timing](https://github.com/hpcclab/felare/blob/main/CODE/utils/random_sample.py): `CODE/utils/random_sample.py`
- [Execution estimates](https://github.com/hpcclab/felare/blob/main/CODE/utils/execution_time.py): `CODE/utils/execution_time.py`

### Results analysis

- [Analysis reports](https://github.com/hpcclab/felare/tree/main/CODE/utils/report): `CODE/utils/report`

### Other components

- **Operator**

## Connections

- Operator → Run driver: starts (evidence: `CODE/main.py`)
- Operator → Simulation GUI: interacts (evidence: `CODE/gui.py`)
- Run driver → Configuration: initializes (evidence: `CODE/main.py`)
- Run driver → Edge machine: creates (evidence: `CODE/main.py`)
- Run driver → Event simulator: runs (evidence: `CODE/main.py`)
- Run driver → Simulation GUI: opens (evidence: `CODE/main.py`)
- Simulation GUI → Event simulator: controls (evidence: `CODE/gui.py`)
- Configuration → Event queue: creates (evidence: `CODE/utils/config.py`)
- Configuration → Task types: creates (evidence: `CODE/utils/config.py`)
- Event simulator → Event model: creates (evidence: `CODE/utils/simulator.py`)
- Event simulator → Task state: loads (evidence: `CODE/utils/simulator.py`)
- Event simulator → Event queue: queues arrivals (evidence: `CODE/utils/simulator.py`)
- Event simulator → Scheduler base: dispatches events (evidence: `CODE/utils/simulator.py`)
- Event simulator → Energy-efficient policy: selects policy (evidence: `CODE/utils/simulator.py`)
- Event simulator → Fair energy policy: selects policy (evidence: `CODE/utils/simulator.py`)
- Event simulator → MMU policy: selects policy (evidence: `CODE/utils/simulator.py`)
- Event simulator → Other policies: selects policy (evidence: `CODE/utils/simulator.py`)
- Event simulator → Edge machine: handles events (evidence: `CODE/utils/simulator.py`)
- Edge machine → Machine base: extends (evidence: `CODE/utils/machine.py`)
- Edge machine → Task queue: uses (evidence: `CODE/utils/machine.py`)
- Edge machine → Event model: schedules execution (evidence: `CODE/utils/machine.py`)
- Energy-efficient policy → Scheduler base: extends (evidence: `CODE/utils/schedulers/EE.py`)
- Fair energy policy → Scheduler base: extends (evidence: `CODE/utils/schedulers/FEE.py`)
- MMU policy → Scheduler base: extends (evidence: `CODE/utils/schedulers/MMU.py`)
- Energy-efficient policy → Edge machine: maps tasks (evidence: `CODE/utils/schedulers/EE.py`)
- Fair energy policy → Edge machine: admits tasks (evidence: `CODE/utils/schedulers/FEE.py`)
- MMU policy → Edge machine: maps tasks (evidence: `CODE/utils/schedulers/MMU.py`)
- Workload generator → Workload model: generates (evidence: `CODE/workload_generator.py`)
- Workload generator → Configuration: initializes (evidence: `CODE/workload_generator.py`)
- Workload generator → Execution estimates: imports (evidence: `CODE/workload_generator.py`)
- Workload model → Sampling and timing: samples (evidence: `CODE/utils/workload.py`)
- Workload model → Execution estimates: estimates (evidence: `CODE/utils/workload.py`)
- Event simulator → Analysis reports: writes results (evidence: `CODE/utils/simulator.py`)
- Simulation GUI → Analysis reports: requests report (evidence: `CODE/gui.py`)
