make project public

Author: Impelon

LICENSE.md

@@ -0,0 +1,11 @@
+This license applies to all files besides the `writing`and `code/examples/fedzero`  subdirectory.
+
+The MIT License (MIT)
+
+Copyright (c) 2024-2025 Ovidiu Victor Tătar (Impelon)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

code/README.md README.mdcode/README.md renamed to README.md

@@ -1,34 +1,41 @@
-# Introduction
+# About
+
+This project aimed at designing and implementing a general framework for energy-aware federated learning, supporting both simulations and physical deployments.
+The framework is evaluated through multiple case studies, that showcase the benefits of the architectural design and feature set. This includes a case study of running a previously proposed carbon-aware client selection algorithm ([FedZero](https://github.com/dos-group/fedzero)) with real-time energy measurements.
+Skim through the [accompanying thesis](writing/thesis.pdf) for more details on the architecture, case studies and limitations of the approach.
+
+
+## General Idea behind `fleaf`
+
+- Each FL Client runs its training, but is able to speak to its (local) energy system via a socket API (TCP/Unix) providing a stateless HTTP (REST) service.
+- Each Client reports back on its energy consumption, battery level, etc. (which it collected through the HTTP service).
+- The FL Server / Coordinator archives the information received by the clients and may take (selection) decisions based on it.
+- In principle, the HTTP service of each Client could run anywhere. In a real-world scenario it would probably run on the same system as the Client, or in the same local network.
+- In our case, the energy systems are simulated through `flessim` but can also include real-time measurements of the physical hardware. A central thread simulates all microgrids via Vessim, and a separate API instance is created for each microgrid that runs in a separate thread.
+
+## Components
 
 `fleaf` is the name of the framework devised in this thesis project. There are 3 components:
 
-- `fleafapi`
+- [`fleafapi`](code/fleafapi)
 
   `fleafapi` is a low-dependency collection of interfaces that describe which methods a service should support in order to be interoperable with `fleaf`.
 
-- `fleaf`: _Federated Learning Energy-Aware Framework_
+- [`fleaf`](code/fleaf): _Federated Learning Energy-Aware Framework_
 
   The `fleaf` component provides an easy-to-use integration into the `flwr` framework.
   This is done by
   1. providing extensions to FL clients that allow them to interact with a service (cohering to the semantics of `fleafapi`) to make queries about their energy usage and carbon footprint.
   2. providing a `Strategy` wrapper which collects and aggregates measurements from FL clients.
 
-- `flessim`: _`fleafapi` + `vessim`_
+- [`flessim`](code/flessim): _`fleafapi` + `vessim`_
 
   `flessim` is an implementation of a `fleafapi` HTTP service.
   It provides details about the energy dynamics of a user-defined energy network through simulation using `vessim`.
 
 `fleaf` and `flessim` are independent of each other, each only depending on `fleafapi`.
 Yet, they complement each other, making it easy to prototype energy- and carbon-aware solutions to federated learning.
 
-## General Idea behind `fleaf`
-
-- Each FL Client runs its training, but is able to speak to its (local) energy system via a socket API (TCP/Unix) providing a stateless HTTP (REST) service.
-- Each Client reports back on its energy consumption, battery level, etc. (which it collected through the HTTP service).
-- The FL Server / Coordinator archives the information received by the clients and may take (selection) decisions based on it.
-- In principle, the HTTP service of each Client could run anywhere. In a real-world scenario it would probably run on the same system as the Client, or in the same local network.
-- In our case, the energy systems are simulated through `flessim` but can also include real-time measurements of the physical hardware. A central thread simulates all microgrids via Vessim, and a separate API instance is created for each microgrid that runs in a separate thread.
-
 # Try it out
 
 1.  clone the repository via
@@ -54,4 +61,4 @@ Yet, they complement each other, making it easy to prototype energy- and carbon-
     python3 -m examples.fleaf_simple
     ```
 
-See [`examples/fedzero`](./examples/fedzero) for a more intricate example of how to use fleaf with an existing carbon-aware FL algorithm.
+See [`code/examples/fedzero`](./code/examples/fedzero) for a more intricate example of how to use fleaf with an existing carbon-aware FL algorithm.