add files via upload

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Francesco Capuano
+
+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.

README.md

@@ -1,13 +1,73 @@
----
-title: NebulOS
-emoji: 📉
-colorFrom: gray
-colorTo: green
-sdk: streamlit
-sdk_version: 1.26.0
-app_file: app.py
-pinned: false
-license: mit
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+<div align="center">
+  <a href="https://ibb.co/gTkPrng">
+    <img src="https://i.ibb.co/FXYXZfD/Nebul-OS-logo.png" alt="Nebul-OS-logo" border="0">
+  </a>
+</div>
+
+# NebulOS: Fair, green AI. For Real 🌿
+Welcome to the GitHub repository of the 18th ASP cycle coolest project! 🚀
+
+With NebulOS, we push the boundaries AI adoption, focusing on how to design architectures tailored for the hardware on which they run.
+During this wonderful journey, we counted on the support of the amazing people at [Nebuly](https://www.nebuly.com/) (8.3k 🌟 on GitHub), as well the guidance and help by Prof. [Barbara Caputo](linkedin.com/in/barbara-caputo-a610201a7/?originalSubdomain=it) (Politecnico di Torino, Top50 Universities world-wide), and Prof. [Stefana Maja Broadbent](https://www.linkedin.com/in/stefanabroadbent/?originalSubdomain=uk) (Politecnico di Milano, Top20 Universities world-wide).
+
+Give us a star to show your support for the project ⭐
+You can find an extended abstract of this project [here](https://sites.google.com/view/nebulos)
+
+## Foreword 📝
+### Alta Scuola Politecnica (ASP)
+Alta Scuola Politecnica (more [here](https://www.asp-poli.it/)) is the **joint honors program** of Italy's best technical universities, Politecnico di Milano ([18th world-wide, QS Rankings](https://www.topuniversities.com/university-rankings/university-subject-rankings/2023/engineering-technology?&page=1)) and Politecnico di Torino ([45th world-wide, QS Rankings](https://www.topuniversities.com/university-rankings/university-subject-rankings/2023/engineering-technology?&page=1)). 
+Each year, 90 students from Politecnico di Milano and 60 from Politecnico di Torino are selected from a highly competitive pool and those who succeed receive free tuition for their MSc in exchange for ~1.5 years working as **student consultants** with a partner company for an industrial project.
+
+The project we present has been carried out with the invaluable support of folks at [Nebuly](https://www.nebuly.com/), the company behind the very well-known [`nebullvm`](https://github.com/nebuly-ai/nebuly/tree/main/optimization/nebullvm) open-source AI-acceleration library 🚀
+
+Alongside them, we have developed a stable and reliable AI-acceleration tool that capable of designing just the right network for each specific target device. 
+With this, we propose a new answer to an old Deep Learning question: how to bring large models to tiny devices. **Screw forcing a circle in a square-hole**: we feel like we are the trouble-makers here, *better to change the model from the ground up!*
+
+## Contributions 🌟
+NebulOS takes a step further by adopting actual hardware-aware metrics (such as the architectures' energy consumption 🌿) to perform the automated design of Deep Neural Architectures.
+
+## How to Reproduce the Results 💻
+1. **Clone the Repository**: `git clone https://github.com/fracapuano/NebulOS.git`
+2. **Install Dependencies**: 
+After having made sure you have a working version of `conda` on your machine (you can double-check running the command `conda` in your terminal), go ahead:
+- Creating the environment (this code has been fully tested for Python 3.10)
+```bash
+conda create -n nebulosenv python=3.10 -y
+```
+- Activating the environment
+```bash
+conda activate nebulosenv
+```
+- Installing the (very minimal) necessary requirements
+```bash
+pip install -r requirements.txt
+```
+3. **Run the Code**: Use the provided scripts and guidelines in the repository.
+To reproduce our results you can simply run the following command:
+```bash
+python nas.py
+```
+
+To specialize your search, you can select multiple arguments. You may select those of interest to you using Python args. To see all args available you run:
+
+```bash
+python nas.py --help
+```
+
+For instance, you can specify a search for an NVIDIA Jetson Nano device on ImageNet16-120 by running:
+```bash
+python nas.py --device edgegpu --dataset ImageNet16-120
+```
+## Live-demo ⚡
+Our live demo is currently hosted as an Hugging Face space. You can find it at [spaces/fracapuano/NebulOS](https://huggingface.co/spaces/fracapuano/NebulOS)
+
+## Next modules and roadmap
+We are actively working on obtaining the next results.
+
+- [ ] Extending this work to deal with Transformer networks in NLP.
+- [ ] Bring actual AI Optimization to LLMs.
+
+## Conclusions 🌍
+We really hyped up about NebulOS because we feel it is way more than an extension; it's a revolution in the field of Green-AI. This project stays as a testament of our commitment toward truly sustainable AI, and by adopting actual hardware-aware metrics, we are making a tangible difference in the world of Deep Neural Architectures. 
+
+Join us in this journey towards a greener future! Help us keep AI beneficial to all. This time, for real.

app.py

@@ -0,0 +1,250 @@
+from src.search.ga import GeneticSearch
+from src.hw_nats_fast_interface import HW_NATS_FastInterface
+from src.utils import DEVICES, DATASETS
+import streamlit as st
+import numpy as np
+import pandas as pd
+import matplotlib.pyplot as plt
+import plotly.graph_objects as go
+from collections import OrderedDict
+st.set_page_config(layout="wide")
+
+TIME_TO_SCORE_EACH_ARCHITECTURE=0.15
+DAYS_7 = 604800
+NEBULOS_COLOR = '#FF6961'
+TF_COLOR = '#A7C7E7'
+
+@st.cache_data(ttl=DAYS_7)  
+def load_lookup_table():
+    """Load recap table of NebulOS metrics and cache it.
+    """
+    df_nebuloss = pd.read_csv('data/df_nebuloss.csv').rename(columns = {'test_accuracy' : 'validation_accuracy'})
+    
+    return df_nebuloss
+
+@st.cache_data(ttl=DAYS_7)  
+def subset_dataframe(df_nebuloss, dataset):
+    """Subset df_nebuloss based on the right dataset.
+    """    
+    return df_nebuloss[df_nebuloss['dataset'] == dataset]
+
+@st.cache_data(ttl=DAYS_7)  
+def compute_quantiles(df_nebuloss_dataset):
+    """Turn the values of df_nebuloss (of a certain dataset) into the corresponding quantiles, computed along the columns
+    """
+    # compute quantiles
+    quantiles = df_nebuloss_dataset.drop(columns = ['idx']).rank(pct = True)
+    # re-attach the original indices
+    quantiles['idx'] = df_nebuloss_dataset['idx']
+
+    return quantiles
+
+# Streamlit app
+def main():
+    # mapping the devices pseudo-symbols to actual names
+    device_mapping_dict = {
+        "edgegpu": "NVIDIA Jetson nano",
+        "eyeriss": "Eyeriss",
+        "fpga": "FPGA",
+    }
+
+    inverse_device_mapping_dict = {
+        "NVIDIA Jetson nano": "edgegpu",
+        "Eyeriss": "eyeriss",
+        "FPGA": "fpga"
+    }
+
+    # load the lookup table of NebulOS metrics
+    df_nebuloss = load_lookup_table()
+    # add a title
+    st.sidebar.title("🚀 NebulOS: Fair Green AI🌿")
+    st.sidebar.write(
+    """
+    Welcome to the live demo of NebulOS! This Streamlit app serves the scope of presenting the results obtained with our 
+    Hardware-Aware Training-Free Automated Architecture Design procedure.
+    
+    You can check out the source code for the search process at https://www.github.com/fracapuano/NebulOS.
+    You can find an extended abstract of our solution at https://sites.google.com/view/nebulos.
+    
+    Drop us a line if you want to know more about the project (and forget to ⭐ our GitHub repo). 
+    
+    Contact person: Francesco Capuano ({first}.{last}@asp-poli.it)
+    """
+    )
+
+    # dropdown menu for dataset selection
+    dataset = st.sidebar.selectbox("Select Dataset", DATASETS)
+
+    # dropdown menu for device selection
+    device = st.sidebar.selectbox("Select Device", list(inverse_device_mapping_dict.keys()))
+
+    # mapping selected device to usable one
+    device = inverse_device_mapping_dict[device]
+
+    # slider for performance weight selection
+    performance_weight = st.sidebar.slider(
+        "Select trade-off between PERFORMANCE WEIGHT and HARDWARE WEIGHT.\nHigher values will give larger weight to validation accuracy, with less and less importance to the hardware performance.",
+        min_value=0.0, 
+        max_value=1.0,
+        value=0.5,
+        step=0.05
+    )
+    # hardware weight (complementary to performance weight)
+    hardware_weight = 1.0 - performance_weight
+
+    # subset the dataframe for the current daset and device
+    df_nebuloss_dataset = subset_dataframe(df_nebuloss, dataset)
+
+    # best architecture index
+    best_arch_idx = 9930
+
+    # Trigger the search and plot NebulOS Architecture
+    searchspace_interface = HW_NATS_FastInterface(device=device, dataset=dataset)
+    search = GeneticSearch(
+        searchspace=searchspace_interface,
+        fitness_weights=np.array([performance_weight, hardware_weight])
+    )
+
+    results = search.solve(return_trajectory=True)
+
+    arch_idx = searchspace_interface.architecture_to_index["/".join(results[0].genotype)]
+
+    # Create scatter plot
+    scatter_trace1 = go.Scatter(
+        x=df_nebuloss_dataset.loc[df_nebuloss['dataset'] == dataset, f'{device}_energy'],
+        y=df_nebuloss_dataset.loc[df_nebuloss['dataset'] == dataset, 'validation_accuracy'],
+        mode='markers',
+        marker=dict(color='#D3D3D3', size=5),
+        name='Architectures in the search space'
+    )
+
+    # Scatter plot for best architecture
+    scatter_trace2 = go.Scatter(
+        x=df_nebuloss_dataset.loc[df_nebuloss_dataset['idx'] == best_arch_idx, f'{device}_energy'],
+        y=df_nebuloss_dataset.loc[df_nebuloss_dataset['idx'] == best_arch_idx, 'validation_accuracy'],
+        mode='markers',
+        marker=dict(color=TF_COLOR, symbol='circle-dot', size=12),
+        name='Best TF-Architecture'
+    )
+
+    scatter_trace3 = go.Scatter(
+        x=df_nebuloss_dataset.loc[df_nebuloss_dataset['idx'] == arch_idx, f'{device}_energy'],
+        y=df_nebuloss_dataset.loc[df_nebuloss_dataset['idx'] == arch_idx, 'validation_accuracy'],
+        mode='markers',
+        marker=dict(color=NEBULOS_COLOR, symbol='circle-dot', size=12),
+        name='NebulOS Architecture'
+    )
+    scatter_layout = go.Layout(
+        title=f'Validation Accuracy vs. {device_mapping_dict[device]} Energy Consumption',
+        xaxis=dict(title=f'{device.upper()} Energy'),
+        yaxis=dict(title='Validation Accuracy'),
+        showlegend=True
+    )
+    scatter_fig = go.Figure(data=[scatter_trace1, scatter_trace2, scatter_trace3], layout=scatter_layout)
+
+    # Extracting quantile values
+    metrics_considered = OrderedDict()
+    # these are the metrics that we want to plot
+    metrics_considered["flops"] = "FLOPS", 
+    metrics_considered["params"] = "Num. Params", 
+    metrics_considered["validation_accuracy"] = "Accuracy",
+    metrics_considered[f"{device}_energy"] = f"{device_mapping_dict[device]} - Energy Consumption",
+    metrics_considered[f"{device}_latency"] = f"{device_mapping_dict[device]} - Latency"
+
+
+    # this retrieves the optimal row
+    best_row_to_plot = df_nebuloss_dataset.loc[
+        df_nebuloss_dataset['idx'] == best_arch_idx, 
+        list(metrics_considered.keys())
+    ].values
+
+    # this retrieves the row that has been found by the NAS search
+    row_to_plot = df_nebuloss_dataset.loc[
+        df_nebuloss_dataset['idx'] == arch_idx, 
+        list(metrics_considered.keys())
+    ].values
+
+    row_to_plot = row_to_plot/best_row_to_plot
+    best_row_to_plot = best_row_to_plot/best_row_to_plot
+
+    best_row_to_plot = best_row_to_plot.flatten().tolist()
+    row_to_plot = row_to_plot.flatten().tolist()
+
+    # Bar chart for NebulOS Architecture
+    bar_trace1 = go.Bar(
+        x=list(metrics_considered.keys()),
+        y=row_to_plot,
+        name='NebulOS Architecture',
+        marker=dict(color=NEBULOS_COLOR)
+    )
+    # Bar chart for Best TF-Architecture
+    bar_trace2 = go.Bar(
+        x=list(metrics_considered.keys()),
+        y=best_row_to_plot,
+        name='Best TF-Architecture Found',
+        marker=dict(color=TF_COLOR)
+    )
+    # Layout configuration
+    bar_layout = go.Layout(
+        title=f'Hardware-Agnostic Architecture (blue) vs. NebulOS (red)',
+        yaxis=dict(title="(%)Hardware-Agnostic Architecture Value"),
+        barmode='group'
+    )
+
+    # Combining traces with the layout
+    bar_fig = go.Figure(data=[bar_trace2, bar_trace1], layout=bar_layout)
+
+    # Create two columns in Streamlit to show data near each other
+    col1, col2 = st.columns(2)
+
+    # Display scatter plot in the first column
+    with col1:
+        st.plotly_chart(scatter_fig)
+
+    # Display bar chart in the second column
+    with col2:
+        st.plotly_chart(bar_fig)
+
+    best_architecture = df_nebuloss_dataset.loc[
+        df_nebuloss_dataset['idx'] == best_arch_idx, 
+        list(metrics_considered.keys())
+    ]
+
+    best_architecture_string = searchspace_interface[best_arch_idx]["architecture_string"]
+
+    found_architecture = df_nebuloss_dataset.loc[
+        df_nebuloss_dataset['idx'] == arch_idx, 
+        list(metrics_considered.keys())
+    ]
+
+    message = \
+    f"""
+        <h4>NebulOS Search Process: Outcome</h4>
+        <p>
+        This search took ~{results[-1]*TIME_TO_SCORE_EACH_ARCHITECTURE} seconds (scoring {results[-1]} architectures using ~{TIME_TO_SCORE_EACH_ARCHITECTURE} seconds each)
+        </p>
+        The architecture found for <b>{device_mapping_dict[device]}</b> is: <b>{searchspace_interface[arch_idx]["architecture_string"]}</b><br>
+        The optimal (hardware-agnostic) architecture in the searchspace is <b>{best_architecture_string}</b>
+        </p>
+        <p>
+        You can find the recap, in terms of the percentage of the Training-Free metric found in the table to your right 👉
+        </p>
+    """
+
+    # Sample data - replace these with your actual ratio values
+    data = {
+        "Metric": ["FLOPS", "Number of Parameters", "Validation Accuracy", "Energy Consumption", "Latency"],
+        "NebulOS vs. Hardware Agnostic Network": ["{:.2g}%".format(val) for val in row_to_plot]
+    }
+    
+    col1, _, col2 = st.columns([2,1,2])
+    recap_df = pd.DataFrame(data).sort_values(by="Metric").set_index("Metric")
+    
+    with col1:
+        st.write(message, unsafe_allow_html=True)
+    
+    with col2:
+        st.dataframe(recap_df)
+
+if __name__ == "__main__":
+    main()

nas.py

@@ -0,0 +1,79 @@
+from src.search import GeneticSearch
+from src.hw_nats_fast_interface import HW_NATS_FastInterface
+from src.utils import DEVICES, union_of_dicts
+import numpy as np
+import argparse
+import json
+
+def parse_args()->object: 
+    """Args function. 
+    Returns:
+        (object): args parser
+    """
+    parser = argparse.ArgumentParser()
+    # this selects the dataset to be considered for the search
+    parser.add_argument(
+        "--dataset", 
+        default="cifar10", 
+        type=str, 
+        help="Dataset to be considered. One in ['cifar10', 'cifar100', 'ImageNet16-120'].s",
+        choices=["cifar10", "cifar100", "ImageNet16-120"]
+        )
+    # this selects the target device to be considered for the search
+    parser.add_argument(
+        "--device", 
+        default="edgegpu", 
+        type=str, 
+        help="Device to be considered. One in ['edgegpu', 'eyeriss', 'fpga'].",
+        choices=["edgegpu", "eyeriss", "fpga"]
+        )
+    # when this flag is triggered, the search is hardware-agnostic (penalized with FLOPS and params)
+    parser.add_argument("--device-agnostic", action="store_true", help="Flag to trigger hardware-agnostic search.")
+
+    parser.add_argument("--n-generations", default=50, type=int, help="Number of generations to let the genetic algorithm run.")
+    parser.add_argument("--n-runs", default=30, type=int, help="Number of runs used to compute the average test accuracy.")
+
+    parser.add_argument("--performance-weight", default=0.65, type=float, help="Weight of the performance metric in the fitness function.")
+    parser.add_argument("--hardware-weight", default=0.35, type=float, help="Weight of the hardware metric in the fitness function.")
+
+    return parser.parse_args()
+
+def main():
+    # parse arguments
+    args = parse_args()
+
+    dataset = args.dataset
+    device = args.device if args.device in DEVICES else None
+    n_generations = args.n_generations
+    n_runs = args.n_runs
+    performance_weight, hardware_weight = args.performance_weight, args.hardware_weight
+
+    if performance_weight + hardware_weight > 1.0 + 1e-6:
+        error_msg = f"""
+            Performance weight: {performance_weight}, Hardware weight: {hardware_weight} (they sum up to {performance_weight + hardware_weight}).
+            The sum of the weights must be less than 1.
+        """
+        raise ValueError(error_msg)
+    
+    nebulos_chunks = []
+    for i in range(4):  # the number of chunks is 4 in this case
+        with open(f"data/nebuloss_{i+1}.json", "r") as f:
+            nebulos_chunks.append(json.load(f))
+    
+    searchspace_dict = union_of_dicts(nebulos_chunks)
+
+    # initialize the search space given dataset and device
+    searchspace_interface = HW_NATS_FastInterface(datapath=searchspace_dict, device=args.device, dataset=args.dataset)
+    search = GeneticSearch(
+        searchspace=searchspace_interface, 
+        fitness_weights=np.array([performance_weight, hardware_weight])
+        )
+    # this perform the actual architecture search
+    results = search.solve(max_generations=n_generations)
+
+    print(f'{dataset}-{device.upper() if device is not None else device}')
+    print(results[0].genotype, results[0].genotype_to_idx["/".join(results[0].genotype)], results[1])
+    print()
+
+if __name__=="__main__": 
+    main()

requirements.txt

@@ -0,0 +1,4 @@
+matplotlib==3.7.2
+numpy==1.25.2
+pandas==2.1.0
+streamlit==1.26.0

split_in_chunks.ipynb

@@ -0,0 +1,109 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import json\n",
+    "with open(\"data/nebuloss.json\", \"r\") as f:\n",
+    "    data = json.load(f)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def split_dict(d, n):\n",
+    "    \"\"\"\n",
+    "    Splits a dictionary into n dictionaries with almost equal number of items.\n",
+    "\n",
+    "    Parameters:\n",
+    "    - d (dict): The input dictionary.\n",
+    "    - n (int): The number of dictionaries to split into.\n",
+    "\n",
+    "    Returns:\n",
+    "    - list of dict: A list of n dictionaries.\n",
+    "    \"\"\"\n",
+    "    items = list(d.items())\n",
+    "    length = len(items)\n",
+    "    \n",
+    "    # Calculate the size of each chunk\n",
+    "    chunk_size = length // n\n",
+    "    remainder = length % n\n",
+    "\n",
+    "    # Split the items into chunks\n",
+    "    chunks = []\n",
+    "    start = 0\n",
+    "\n",
+    "    for i in range(n):\n",
+    "        if remainder:\n",
+    "            end = start + chunk_size + 1\n",
+    "            remainder -= 1\n",
+    "        else:\n",
+    "            end = start + chunk_size\n",
+    "        chunks.append(dict(items[start:end]))\n",
+    "        start = end\n",
+    "\n",
+    "    return chunks\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "chunk_1, chunk_2, chunk_3, chunk_4 = split_dict(data, n=4)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 13,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "with open(\"data/nebuloss_1.json\", \"w\") as f:\n",
+    "    json.dump(chunk_1, f, indent=4)\n",
+    "with open(\"data/nebuloss_2.json\", \"w\") as f:\n",
+    "    json.dump(chunk_2, f, indent=4)\n",
+    "with open(\"data/nebuloss_3.json\", \"w\") as f:\n",
+    "    json.dump(chunk_3, f, indent=4)\n",
+    "with open(\"data/nebuloss_4.json\", \"w\") as f:\n",
+    "    json.dump(chunk_4, f, indent=4)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "hackenv",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.12"
+  },
+  "orig_nbformat": 4
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

src/__init__.py

@@ -0,0 +1,3 @@
+from .hw_nats_fast_interface import *
+from .genetics import *
+from .utils import *

src/genetics.py

@@ -0,0 +1,301 @@
+from typing import Iterable, Callable, Tuple, List, Union, Dict
+import numpy as np
+from copy import deepcopy as copy
+from .utils import *
+from itertools import chain
+from abc import abstractproperty, abstractmethod
+from .hw_nats_fast_interface import HW_NATS_FastInterface
+
+
+class Individual:
+    """
+    Base Class for all individuals in the population.
+    Base class attributes are the genotype identifying the individual (and, therefore, the network) and its
+    index within the search space it is drawn from.
+    """
+    def __init__(self, genotype:List[str], index:int):
+        self._genotype = genotype
+        self.index=index
+        self._fitness = None
+    
+    @abstractproperty
+    def genotype(self): 
+        """This class is used to define the network architecture."""
+        raise NotImplementedError("Implement this property in child classes!")
+    
+    @abstractproperty
+    def fitness(self):
+        """This class is used to define the fitness of the individual."""
+        raise NotImplementedError("Implement this property in child classes!")
+
+    @abstractmethod
+    def update_idx(self):
+        """Update the index of the individual in the population"""
+        raise NotImplementedError("Implement this method in child classes!")
+    
+    @abstractmethod
+    def update_genotype(self, new_genotype:List[str]): 
+        """Update current genotype with new one. When doing so, also the network field is updated"""
+        raise NotImplementedError("Implement this method in child classes!")
+    
+    @abstractmethod
+    def update_fitness(self, metric:Callable, attribute:str="net"): 
+        """Update the current value of fitness using provided metric"""
+        raise NotImplementedError("Implement this method in child classes!")
+    
+
+class FastIndividual(Individual): 
+    """
+    Fast individuals are used in the context of age-regularized genetic algorithms and, therefore, are
+    characterized by an additional field, i.e. age.
+    """
+    def __init__(
+        self,
+        genotype:List[str],
+        index:int, 
+        genotype_to_idx:Dict[str, int],
+        age:int=0):
+        
+        # init parent class
+        super().__init__(genotype, index)
+
+        self.age = age
+        self.genotype_to_idx = genotype_to_idx
+        
+    @property
+    def genotype(self): 
+        return self._genotype
+    
+    @property
+    def fitness(self): 
+        return self._fitness
+    
+    def update_idx(self):
+        self.index = self.genotype_to_idx["/".join(self._genotype)]
+
+    def update_genotype(self, new_genotype:List[str]): 
+        """Update current genotype with new one. When doing so, also the network field is updated"""
+        self._genotype = new_genotype
+        self.update_idx()
+    
+    def update_fitness(self, metric:Callable, attribute:str="net"): 
+        """Update the current value of fitness using provided metric"""
+        self._fitness = metric(getattr(self, attribute))
+
+class Genetic: 
+    def __init__(
+        self, 
+        genome:Iterable[str], 
+        searchspace:HW_NATS_FastInterface,
+        strategy:Tuple[str, str]="comma", 
+        tournament_size:int=5):
+        
+        self.genome = set(genome) if not isinstance(genome, set) else genome
+        self.strategy = strategy
+        self.tournament_size = tournament_size
+        self.searchspace = searchspace
+
+    def tournament(self, population:Iterable[Individual]) -> Iterable[Individual]:
+        """
+        Return tournament, i.e. a random subset of population of size tournament size. 
+        Sampling is done without replacement to ensure diversity inside the actual tournament.
+        """
+        return np.random.choice(a=population, size=self.tournament_size, replace=False).tolist()
+    
+    def obtain_parents(self, population:Iterable[Individual], n_parents:int=2) -> Iterable[Individual]:
+        """Obtain n_parents from population. Parents are defined as the fittest individuals in n_parents tournaments"""
+        tournament = self.tournament(population = population)
+        # parents are defined as fittest individuals in tournaments
+        parents = sorted(tournament, key = lambda individual: individual.fitness, reverse=True)[:n_parents]
+        return parents
+    
+    def mutate(self, 
+               individual:Individual, 
+               n_loci:int=1, 
+               genes_prob:Tuple[None, List[float]]=None) -> Individual: 
+        """Applies mutation to a given individual"""
+        for _ in range(n_loci): 
+            mutant_genotype = copy(individual.genotype)
+            # select a locus in the genotype (that is, where mutation will occurr)
+            if genes_prob is None:  # uniform probability over all loci
+                mutant_locus = np.random.randint(low=0, high=len(mutant_genotype))
+            else:  # custom probability distrubution over which locus to mutate
+                mutant_locus = np.random.choice(mutant_genotype, p=genes_prob)
+            # mapping the locus to the actual gene that will effectively change
+            mutant_gene = mutant_genotype[mutant_locus]
+            operation, level = mutant_gene.split("~")  # splits the gene into operation and level
+            # mutation changes gene, so the current one must be removed from the pool of candidate genes
+            mutations = self.genome.difference([operation])
+            
+            # overwriting the mutant gene with a new one - probability of chosing how to mutate should be selected as well
+            mutant_genotype[mutant_locus] = np.random.choice(a=list(mutations)) + f"~{level}"
+
+        mutant_individual = FastIndividual(genotype=None, genotype_to_idx=self.searchspace.architecture_to_index, index=None)
+        mutant_individual.update_genotype(mutant_genotype)
+
+        return mutant_individual
+    
+    def recombine(self, individuals:Iterable[Individual], P_parent1:float=0.5) -> Individual: 
+        """Performs recombination of two given `individuals`"""
+        if len(individuals) != 2: 
+            raise ValueError("Number of individuals cannot be different from 2!")
+        
+        individual1, individual2 = individuals
+        recombinant_genotype = [None for _ in range(len(individual1.genotype))]
+        for locus_idx, (gene_1, gene_2) in enumerate(zip(individual1.genotype, individual2.genotype)):
+            # chose genes from parent1 according to P_parent1
+            recombinant_genotype[locus_idx] = gene_1 if np.random.random() <= P_parent1 else gene_2
+
+        recombinant = FastIndividual(genotype=None, genotype_to_idx=self.searchspace.architecture_to_index, index=None)
+        recombinant.update_genotype(list(recombinant_genotype))
+
+        return recombinant
+
+class Population: 
+    def __init__(self,
+                 searchspace:object,
+                 init_population:Union[bool, Iterable]=True,
+                 n_individuals:int=20,
+                 normalization:str='dynamic'): 
+        self.searchspace = searchspace
+        if init_population is True:
+            self._population = generate_population(searchspace_interface=searchspace, n_individuals=n_individuals)
+        else: 
+            self._population = init_population
+        
+        self.oldest = None
+        self.worst_n = None
+        self.normalization = normalization.lower()
+    
+    def __iter__(self): 
+        for i in self._population: 
+            yield i
+    
+    @property
+    def individuals(self):
+        return self._population
+    
+    def update_population(self, new_population:Iterable[Individual]): 
+        """Overwrites current population with new one stored in `new_population`"""
+        if all([isinstance(el, Individual) for el in new_population]):
+            del self._population
+            self._population = new_population
+        else:
+            raise ValueError("new_population is not an Iterable of `Individual` datatype!")
+
+    def fittest_n(self, n:int=1): 
+        """Return first `n` individuals based on fitness value"""
+        return sorted(self._population, key=lambda individual: individual.fitness, reverse=True)[:n]
+    
+    def update_ranking(self): 
+        """Updates the ranking in the population in light of fitness value"""
+        sorted_individuals = sorted(self._population, key=lambda individual: individual.fitness, reverse=True)
+        
+        # ranking in light of individuals 
+        for ranking, individual in enumerate(sorted_individuals):
+            individual.update_ranking(new_rank=ranking)
+
+    def update_fitness(self, fitness_function:Callable): 
+        """Updates the fitness value of individuals in the population"""
+        for individual in self.individuals: 
+            fitness_function(individual)
+    
+    def apply_on_individuals(self, function:Callable)->Union[Iterable, None]: 
+        """Applies a function on each individual in the population
+        
+        Args: 
+            function (Callable): function to apply on each individual. Must return an object of class Individual.
+        Returns: 
+            Union[Iterable, None]: Iterable when inplace=False represents the individuals with function applied.
+                                   None represents the output when inplace=True (hence function is applied on the
+                                   actual population.
+        """
+        self._population = [function(individual) for individual in self._population]
+
+    def set_extremes(self, score:str):
+        """Set the maximal&minimal value in the population for the score 'score' (must be a class attribute)"""
+        if self.normalization == 'dynamic':
+            # accessing to the score of each individual
+            scores = [getattr(ind, score) for ind in self.individuals]
+            min_value = min(scores)
+            max_value = max(scores)
+        elif self.normalization == 'minmax':
+            # extreme_scores is a 2x`number_of_scores`
+            min_value, max_value = self.extreme_scores[:, self.scores_dict[score]]
+        elif self.normalization == 'standard':
+            # extreme_scores is a 2x`number_of_scores`
+            mean_value, std_value = self.extreme_scores[:, self.scores_dict[score]]
+
+        if self.normalization in ['minmax', 'dynamic']:
+            setattr(self, f"max_{score}", max_value)
+            setattr(self, f"min_{score}", min_value)
+        else:
+            setattr(self, f"mean_{score}", mean_value)
+            setattr(self, f"std_{score}", std_value)
+
+    def age(self): 
+        """Embeds ageing into the process"""
+        def individuals_ageing(individual): 
+            individual.age += 1
+            return individual
+
+        self.apply_on_individuals(function=individuals_ageing)
+    
+    def add_to_population(self, new_individuals:Iterable[Individual]): 
+        """Add new_individuals to population"""
+        self._population = list(chain(self.individuals, new_individuals))
+    
+    def remove_from_population(self, attribute:str="fitness", n:int=1, ascending:bool=True): 
+        """
+        Remove first/last `n` elements from sorted population population in `ascending/descending`
+        order based on the value of `attribute`.
+        """
+        # check that input attribute is an attribute of all the individuals
+        if not all([hasattr(el, attribute) for el in self.individuals]):
+            raise ValueError(f"Attribute '{attribute}' is not an attribute of all the individuals!")
+        
+        # sort the population based on the value of attribute
+        sorted_population = sorted(self.individuals, key=lambda ind: getattr(ind, attribute), reverse=False if ascending else True)
+        # new population is old population minus the `n` worst individuals with respect to `attribute`
+        self.update_population(sorted_population[n:])
+
+    def update_oldest(self, candidate:Individual): 
+        """Updates oldest individual in the population"""
+        if candidate.age >= self.oldest.age: 
+            self.oldest = candidate
+        else: 
+            pass
+
+    def update_worst_n(self, candidate:Individual, attribute:str="fitness", n:int=2): 
+        """Updates worst_n elements in the population"""
+        if hasattr(candidate, attribute): 
+            if any([getattr(candidate, attribute) < getattr(worst, attribute) for worst in self.worst_n]):
+                # candidate is worse than one of the worst individuals
+                bad_individuals = self.worst_n + candidate
+                # sort in increasing values of fitness
+                bad_sorted = sorted(bad_individuals, lambda ind: getattr(ind, attribute))
+                self.worst_n = bad_sorted[:n]  # return new worst individuals
+    
+    def set_oldest(self): 
+        """Sets oldest individual in population"""
+        self.oldest = max(self.individuals, key=lambda ind: ind.age)
+    
+    def set_worst_n(self, attribute:str="fitness", n:int=2): 
+        """Sets worst n elements based on the value of arbitrary attribute"""
+        self.worst_n = sorted(self.individuals, key=lambda ind: getattr(ind, attribute))[:n]
+        
+
+def generate_population(searchspace_interface:HW_NATS_FastInterface, n_individuals:int=20)->list: 
+    """This function generates a population of FastInviduals based on the searchspace interface"""
+    # at first generate full cell-structure and unique network indices
+    cells, indices = searchspace_interface.generate_random_samples(n_samples=n_individuals)
+    
+    # mapping strings to list of genes (~genomes)
+    genotypes = map(lambda cell: searchspace_interface.architecture_to_list(cell), cells)
+    # turn full architecture and cell-structure into genetic population individual
+    population = [
+        FastIndividual(genotype=genotype, index=index, genotype_to_idx=searchspace_interface.architecture_to_index) 
+        for genotype, index in zip(genotypes, indices)
+    ]
+    
+    return population

src/hw_nats_fast_interface.py

@@ -0,0 +1,245 @@
+from typing import Set, Text, List, Tuple, Dict
+from itertools import chain
+from .utils import get_project_root
+import numpy as np
+import json
+
+class HW_NATS_FastInterface:    
+    def __init__(self, 
+                 datapath:str=str(get_project_root()) + "/data/nebuloss.json", 
+                 indexpath:str=str(get_project_root()) + "/data/nats_arch_index.json",
+                 dataset:str="cifar10", 
+                 device:Text="edgegpu", 
+                 scores_sample_size:int=1e3):
+        
+        AVAILABLE_DATASETS = ["cifar10", "cifar100", "ImageNet16-120"]
+        AVAILABLE_DEVICES = ["edgegpu", "eyeriss", "fpga"]
+        # catch input errors
+        if dataset not in AVAILABLE_DATASETS:
+            raise ValueError(f"Dataset {dataset} not in {AVAILABLE_DATASETS}!")
+        
+        if device not in AVAILABLE_DEVICES and device is not None:
+            raise ValueError(f"Device {device} not in {AVAILABLE_DEVICES}!")
+
+        if isinstance(datapath, str):
+            # parent init
+            with open(datapath, "r") as datafile:
+                self._data = {
+                    int(key): value for key, value in json.load(datafile).items()
+                }
+        elif isinstance(datapath, dict):
+            self._data = {
+                    int(key): value for key, value in datapath.items()
+                }
+        else: 
+            raise ValueError(f"Datapath must be either a string or a dictionary, not {type(datapath)}")
+        
+        # importing the "/"-architecture <-> index from a json file
+        with open(indexpath, "r") as indexfile:
+            self._architecture_to_index = json.load(indexfile)
+
+        # store dataset field
+        self._dataset = dataset
+        self.target_device = device
+        # architectures to use to estimate mean and std for scores normalization
+        self.random_indices = np.random.choice(len(self), int(scores_sample_size), replace=False)
+
+    def __len__(self)->int:
+        """Number of architectures in considered search space."""
+        return len(self._data)
+    
+    def __getitem__(self, idx:int) -> Dict: 
+        """Returns (untrained) network corresponding to index `idx`"""
+        return self._data[idx]
+
+    def __iter__(self):
+        """Iterator method"""
+        self.iteration_index = 0
+        return self
+
+    def __next__(self):
+        if self.iteration_index >= self.__len__():
+            raise StopIteration
+        # access current element 
+        net = self[self.iteration_index]
+        # update the iteration index
+        self.iteration_index += 1
+        return net
+    
+    @property
+    def data(self):
+        return self._data
+
+    @property
+    def architecture_to_index(self):
+        return self._architecture_to_index
+
+    @property 
+    def name(self)->Text:
+        return "nats"
+    
+    @property
+    def ordered_all_ops(self)->List[Text]:
+        """NASTS Bench available operations, ordered (without any precise logic)"""
+        return ['skip_connect', 'nor_conv_1x1', 'nor_conv_3x3', 'none', 'avg_pool_3x3']
+
+    @property
+    def architecture_len(self)->int: 
+        """Returns the number of different operations that uniquevoly define a given architecture"""
+        return 6
+    
+    @property
+    def all_ops(self)->Set[Text]:
+        """NASTS Bench available operations."""
+        return {'skip_connect', 'nor_conv_1x1', 'nor_conv_3x3', 'none', 'avg_pool_3x3'}
+    
+    @property
+    def dataset(self)->Text: 
+        return self._dataset
+    
+    @dataset.setter
+    def change_dataset(self, new_dataset:Text)->None: 
+        """
+        Updates the current dataset with a new one. 
+        Raises ValueError when new_dataset is not one of ["cifar10", "cifar100", "imagenet16-120"]
+        """
+        if new_dataset.lower() in self.NATS_datasets: 
+            self._dataset = new_dataset
+        else: 
+            raise ValueError(f"New dataset {new_dataset} not in {self.NATS_datasets}")
+    
+    def get_score_mean(self, score_name:Text)->float:
+        """
+        Calculate the mean score value across the dataset for the given score name.
+
+        Args:
+            score_name (Text): The name of the score for which to calculate the mean.
+
+        Returns:
+            float: The mean score value.
+
+        Note:
+            The score values are retrieved from each data point in the dataset and averaged.
+        """
+        if not hasattr(self, f"mean_{score_name}"):
+            # compute the mean on 1000 instances
+            mean_score = np.mean([self[i][self.dataset][score_name] for i in self.random_indices])
+
+            # set the mean score accordingly
+            setattr(self, f"mean_{score_name}", mean_score)
+            self.get_score_mean(score_name=score_name)
+        
+        return getattr(self, f"mean_{score_name}")
+
+    def get_score_std(self, score_name: Text) -> float:
+        """
+        Calculate the standard deviation of the score values across the dataset for the given score name.
+
+        Args:
+            score_name (Text): The name of the score for which to calculate the standard deviation.
+
+        Returns:
+            float: The standard deviation of the score values.
+
+        Note:
+            The score values are retrieved from each data point in the dataset, and the standard deviation is calculated.
+        """
+        if not hasattr(self, f"std_{score_name}"):
+            # compute the mean on 1000 instances
+            std_score = np.std([self[i][self.dataset][score_name] for i in self.random_indices])
+
+            # set the mean score accordingly
+            setattr(self, f"std_{score_name}", std_score)
+            self.get_score_std(score_name=score_name)
+        
+        return getattr(self, f"std_{score_name}")
+
+    def generate_random_samples(self, n_samples:int=10)->Tuple[List[Text], List[int]]:
+        """Generate a group of architectures chosen at random"""
+        idxs = np.random.choice(self.__len__(), size=n_samples, replace=False)
+        cell_structures = [self[i]["architecture_string"] for i in idxs]
+        # return tinynets, cell_structures_string and the unique indices of the networks
+        return cell_structures, idxs
+    
+    def list_to_architecture(self, input_list:List[str])->str:
+        """
+        Reformats genotype as architecture string. 
+        This function clearly is specific for this very search space.
+        """
+        return "|{}|+|{}|{}|+|{}|{}|{}|".format(*input_list)
+    
+    def architecture_to_list(self, architecture_string:Text)->List[Text]: 
+        """Turn architectures string into genotype list
+
+        Args: 
+            architecture_string(str): String characterising the cell structure only. 
+
+        Returns: 
+            List[str]: List containing the operations in the input cell structure.
+                       In a genetic-algorithm setting, this description represents a genotype. 
+        """
+        # divide the input string into different levels
+        subcells = architecture_string.split("+")
+        # divide into different nodes to retrieve ops
+        ops = chain(*[subcell.split("|")[1:-1] for subcell in subcells])
+        
+        return list(ops)
+
+    def list_to_accuracy(self, input_list:List[str])->float: 
+        """Returns the test accuracy of an input list representing the architecture. 
+        This list contains the operations.
+
+        Args:
+            input_list (List[str]): List of operations inside the architecture.
+
+        Returns:
+            float: Test accuracy (after 200 training epochs).
+        """
+        # retrieving the index associated to this particular architecture
+        arch_index = self.architecture_to_index["/".join(input_list)]
+        return self[arch_index][self.dataset]["test_accuracy"]
+
+    def architecture_to_accuracy(self, architecture_string:str)->float:
+        """Returns the test accuracy of an architecture string.
+        The architecture <-> index map is normalized to be as general as possible, hence some (minor) 
+        input processing is needed.
+
+        Args:
+            architecture_string (str): Architecture string.
+
+        Returns:
+            float: Test accuracy (after 200 training epochs).
+        """
+        # retrieving the index associated to this particular architecture
+        arch_index = self.architecture_to_index["/".join(self.architecture_to_list(architecture_string))]
+        return self[arch_index][self.dataset]["test_accuracy"]
+
+    def list_to_score(self, input_list:List[Text], score:Text)->float:
+        """Returns the value of `score` of an input list representing the architecture. 
+        This list contains the operations.
+
+        Args:
+            input_list (List[Text]): List of operations inside the architecture.
+            score (Text): Score of interest.
+
+        Returns:
+            float: Score value for `input_list`.
+        """
+        arch_index = self.architecture_to_index["/".join(input_list)]
+        return self[arch_index][self.dataset].get(score, None)
+
+    def architecture_to_score(self, architecture_string:Text, score:Text)->float:
+        """Returns the value of `score` of an architecture string.
+        The architecture <-> index map is normalized to be as general as possible, hence some (minor) 
+        input processing is needed.
+
+        Args:
+            architecture_string (Text): Architecture string.
+            score (Text): Score of interest.
+
+        Returns:
+            float: Score value for `architecture_string`.
+        """
+        # retrieving the index associated to this particular architecture
+        arch_index = self.architecture_to_index["/".join(self.architecture_to_list(architecture_string))]
+        return self[arch_index][self.dataset].get(score, None)

src/search/__init__.py

@@ -0,0 +1 @@
+from .ga import * 

src/search/ga.py

@@ -0,0 +1,228 @@
+from src.hw_nats_fast_interface import HW_NATS_FastInterface
+from src.genetics import FastIndividual
+from src.genetics import Genetic, Population
+from typing import Iterable, Union, Text
+import numpy as np
+from collections import OrderedDict
+
+FreeREA_dict = {
+    "n": 5,  # tournament size
+    "N": 25,  # population size
+    "mutation_prob": 1.,  # always mutates
+    "recombination_prob": 1.,  # always recombines
+    "P_parent1": 0.5,  # fraction of child that comes from parent1 (on average)
+    "n_mutations": 1,  # how many loci to mutate at a time
+    "loci_prob": None,  # the probability of mutating a given locus (if None, uniform)
+}
+
+class GeneticSearch:
+    def __init__(self, 
+                 searchspace:HW_NATS_FastInterface,
+                 genetics_dict:dict=FreeREA_dict,
+                 init_population:Union[None, Iterable[FastIndividual]]=None,
+                 fitness_weights:Union[None, np.ndarray]=np.array([0.5, 0.5])):
+        
+        # instantiating a searchspace instance
+        self.searchspace = searchspace
+        # instatiating the dataset based on searchspace
+        self.dataset = self.searchspace.dataset
+        # instatiating the device based on searchspace
+        self.target_device = self.searchspace.target_device
+        # hardware aware scores changes based on whether or not one uses a given target device
+        if self.target_device is None:
+            self.hw_scores = ["flops", "params"]
+        else:
+            self.hw_scores = [f"{self.target_device}_energy"]
+
+        # scores used to evaluate the architectures on downstream tasks
+        self.classification_scores = ["naswot_score", "logsynflow_score", "skip_score"]
+        self.genetics_dict = genetics_dict
+        # weights used to combine classification performance with hardware performance.
+        self.weights = fitness_weights
+
+        # instantiating a population
+        self.population = Population(
+            searchspace=self.searchspace, 
+            init_population=True if init_population is None else init_population, 
+            n_individuals=self.genetics_dict["N"],
+            normalization="dynamic"
+        )
+
+        # initialize the object taking care of performing genetic operations
+        self.genetic_operator = Genetic(
+            genome=self.searchspace.all_ops, 
+            strategy="comma", # population evolution strategy
+            tournament_size=self.genetics_dict["n"], 
+            searchspace=self.searchspace
+        )
+
+        # preprocess population
+        self.preprocess_population()
+   
+    def normalize_score(self, score_value:float, score_name:Text, type:Text="std")->float:
+        """
+        Normalize the given score value using a specified normalization type.
+
+        Args:
+            score_value (float): The score value to be normalized.
+            score_name (Text): The name of the score used for normalization.
+            type (Text, optional): The type of normalization to be applied. Defaults to "std".
+
+        Returns:
+            float: The normalized score value.
+
+        Raises:
+            ValueError: If the specified normalization type is not available.
+
+        Note:
+            The available normalization types are:
+            - "std": Standard score normalization using mean and standard deviation.
+        """
+        if type == "std":
+            score_mean = self.searchspace.get_score_mean(score_name)
+            score_std = self.searchspace.get_score_std(score_name)
+            
+            return (score_value - score_mean) / score_std
+        else:
+            raise ValueError(f"Normalization type {type} not available!")
+
+    def fitness_function(self, individual:FastIndividual)->FastIndividual: 
+        """
+        Directly overwrites the fitness attribute for a given individual.
+
+        Args: 
+            individual (FastIndividual): Individual to score.
+
+        # Returns:
+        #     FastIndividual: Individual, with fitness field.
+        """
+        if individual.fitness is None:  # None at initialization only
+            scores = np.array([
+                self.normalize_score(
+                    score_value=self.searchspace.list_to_score(input_list=individual.genotype, 
+                                                            score=score), 
+                    score_name=score
+                )
+                for score in self.classification_scores
+            ])
+            hardware_performance = np.array([
+                self.normalize_score(
+                    score_value=self.searchspace.list_to_score(input_list=individual.genotype, 
+                                                            score=score),
+                    score_name=score
+                )
+                for score in self.hw_scores
+            ])
+            # individual fitness is a convex combination of multiple scores
+            network_score = (np.ones_like(scores) / len(scores)) @ scores
+            network_hardware_performance =  (np.ones_like(hardware_performance) / len(hardware_performance)) @ hardware_performance
+            
+            # in the hardware aware contest performance is in a direct tradeoff with hardware performance
+            individual._fitness = np.array([network_score, -network_hardware_performance]) @ self.weights
+        
+        # return individual
+
+    def preprocess_population(self): 
+        """
+        Applies scoring and fitness function to the whole population. This allows each individual to 
+        have the appropriate fields.
+        """
+        # assign the fitness score
+        self.assign_fitness()
+
+    def perform_mutation(
+            self,
+            individual:FastIndividual,
+            )->FastIndividual:
+        """Performs mutation with respect to genetic ops parameters"""
+        realization = np.random.random()
+        if realization <= self.genetics_dict["mutation_prob"]:  # do mutation
+            mutant = self.genetic_operator.mutate(
+                individual=individual, 
+                n_loci=self.genetics_dict["n_mutations"], 
+                genes_prob=self.genetics_dict["loci_prob"]
+            )
+            return mutant
+        else:  # don't do mutation
+            return individual
+
+    def perform_recombination(
+            self, 
+            parents:Iterable[FastIndividual],
+        )->FastIndividual:
+        """Performs recombination with respect to genetic ops parameters"""
+        realization = np.random.random()
+        if realization <= self.genetics_dict["recombination_prob"]:  # do recombination
+            child = self.genetic_operator.recombine(
+                individuals=parents, 
+                P_parent1=self.genetics_dict["P_parent1"]
+            )
+            return child
+        else:  # don't do recombination - simply return 1st parent
+            return parents[0]  
+
+    def assign_fitness(self):
+        """This function assigns to each invidual a given fitness score."""
+        # define a fitness function and compute fitness for each individual
+        fitness_function = lambda individual: self.fitness_function(individual=individual)
+        self.population.update_fitness(fitness_function=fitness_function)
+
+    def obtain_parents(self, n_parents:int=2): 
+        # obtain tournament
+        tournament = self.genetic_operator.tournament(population=self.population.individuals)
+        # turn tournament into a local population 
+        parents = sorted(tournament, key = lambda individual: individual.fitness, reverse=True)[:n_parents]
+        return parents
+
+    def solve(self, max_generations:int=100, return_trajectory:bool=False)->Union[FastIndividual, float]: 
+        """
+        This function performs Regularized Evolutionary Algorithm (REA) with Training-Free metrics. 
+        Details on the whole procedure can be found in FreeREA (https://arxiv.org/pdf/2207.05135.pdf).
+        
+        Args: 
+            max_generations (int, optional): TODO - ADD DESCRIPTION. Defaults to 100.
+        
+        Returns: 
+            Union[FastIndividual, float]: Index-0 points to best individual object whereas Index-1 refers to its test 
+                                      accuracy.
+        """
+        
+        MAX_GENERATIONS = max_generations
+        population, individuals = self.population, self.population.individuals
+        bests = []
+        history = OrderedDict()
+
+        for gen in range(MAX_GENERATIONS):
+            # store the population
+            history.update({self.searchspace.list_to_architecture(ind.genotype): ind for ind in population})
+            # save best individual
+            bests.append(max(individuals, key=lambda ind: ind.fitness))
+            # perform ageing
+            population.age()
+            # obtain parents
+            parents = self.obtain_parents()
+            # obtain recombinant child
+            child = self.perform_recombination(parents=parents)
+            # mutate parents
+            mutant1, mutant2 = [self.perform_mutation(parent) for parent in parents]            
+            # add mutants and child to population
+            population.add_to_population([child, mutant1, mutant2])
+            # preprocess the new population - TODO: Implement a only-if-extremes-change strategy
+            self.preprocess_population()
+            # remove from population worst (from fitness perspective) individuals
+            population.remove_from_population(attribute="fitness", n=2)
+            # prune from population oldest individual
+            population.remove_from_population(attribute="age", ascending=False)
+            # overwrite population
+            individuals = population.individuals
+       
+        best_individual = max(history.values(), key=lambda ind: ind._fitness)
+        # appending in last position the actual best element
+        bests.append(best_individual)
+
+        test_accuracy = self.searchspace.list_to_accuracy(best_individual.genotype)
+
+        if not return_trajectory:
+            return (best_individual, test_accuracy)
+        else: 
+            return (best_individual, test_accuracy, bests, len(history))

src/utils.py

@@ -0,0 +1,25 @@
+from pathlib import Path
+
+DATASETS = ["cifar10", "cifar100", "ImageNet16-120"]
+DEVICES = ["edgegpu", "eyeriss", "fpga"]
+
+def get_project_root(): 
+    """
+    Returns project root directory from this script nested in the commons folder.
+    """
+    return Path(__file__).parent.parent
+
+def union_of_dicts(dicts):
+    """
+    Returns a dictionary that represents the union of all input dictionaries.
+
+    Parameters:
+    - dicts (iterable): An iterable of dictionaries.
+
+    Returns:
+    - dict: The union of all dictionaries.
+    """
+    result = {}
+    for d in dicts:
+        result.update(d)
+    return result