Ennio Italiano

MSc CS Thesis #09 - Building the Graph

Mon, 07 Sep 2026 13:41:00 +0100

Given an Instanceand a Config, it’s now time to build the graph. Particularly, we will use those two objects to instantiate a GraphBuilder object.

We will now analyze in detail what happens inside the Build() method of the GraphBuilder class, which has the following signature:

std::tuple<melon::static_forward_digraph, std::vector<double>> Build() const;

The return type of the method is a tuple made of a static_forward_digraph (a type of graph from the MELON library) and a vector of double.

MSc CS Thesis #08 - Computing Costs

Mon, 07 Sep 2026 11:20:00 +0100

The cost calculation logic has been divided in three different components: DistanceMatrix, CostEvaluator, and TransitionCost.

`DistanceMatrix`

The DistanceMatrix class simply stores the number of total locations (including depots), the travel cost multiplier ($\beta$), and a std::vector<double> containing the euclidean distances between every possible pair of stations. Particularly, the latter is computed inside DistanceMatrix’s constructor body.

To access a distance between two locations, the

double DistanceMatrix::GetDistance(int from_station_id, int to_station_id) const;

method is exposed; inside it, the convention that location (≠ station) 0 corresponds to the depot and locations 1..N are the inner stations is enforced, and after having computed the two “real” locations corresponding to the passed stations, distances_[loc_u * total_locations_ + loc_v] is returned.

MSc CS Thesis #07 - The Nodes

Thu, 03 Sep 2026 17:43:00 +0100

We need a way to represent a single node in memory. To this aim, the Node struct has been created:

struct Node {
 int station_id;
 int scooter_load;
 int battery_load;
};

This matches what we already said about each node of the graph, which is a combination of the e-scooters and fully-charged batteries load at a given station.

Encoding Nodes

We are dealing with a layered graph in which we know:

the number of layers: the number of stations of a given cluster;
the number of nodes per layer: $(C+1)\times(B+1)$, where $C$ and $B$ are respectively the e-scooters capacity of the truck and its fully-charged batteries capacity.¹

Hence, a NodeCodec class has been created to encode (and, conversely, decode) each Node into an integer number via mixed-radix encoding:

MSc CS Thesis #06 - Parsing & Loading

Thu, 03 Sep 2026 14:33:00 +0100

Spreadsheet-to-JSON

To first parse the dataset spreadsheet and convert it to a more manageable JSON object, a Python script has been vibe-coded. It parses all the sheets (stations, coordinates, clusters, depots, daily demands, and SOC matrices) from datasets formatted like the one we inherited and produces a structured, clean JSON file to be used in my C++ program.

The usage is very simple, since it’s enough to run this command from the terminal:

MSc CS Thesis #05 - Input Data

Wed, 02 Sep 2026 15:01:00 +0100

Now it’s time to jump into the code, starting from what will be the program’s input data.

The Dataset

We already have a reference input dataset coming from the old Python project, containing some data about e-scooters traffic in the city of Bari, Italy. Unfortunately, it is an Excel (.xlsx) spreadsheet. But let’s analyze its structure first.

The spreadsheet contains 19 different sheets:

giorni: list of days taken into account for the experiment;
we: binary variable indicating whether a certain day is a weekday;
id z: id numbers of 293 different locations;
id z cluster zone wd / id z cluster zone we: maps each zone/station to an equity cluster (defined in p coeff zone wd / p coeff zone we);
p coeff zone wd / p coeff zone we: social equity clusters. Each row defines values to compute cost/penalty function for the Gini index associated with that cluster - ideal number of vehicle per cluster, and money penalty for shortage or excess;
START conf: total e-scooters availability per station, for each day;
START conf carichi 17.5: e-scooters with charge >= 17.5% per station, for each day - used as target demand;
START conf scarichi 17.5: e-scooters with charge < 17.5% per station, for each day;
START conf pert / START conf pert carichi 17.5 / START conf pert scarichi 17.5: perturbed data starting from base (real) data to test algorithms’ robustness wrt demand/state variations - used as effective state at the beginning of the truck’s tour;
START soc matrix / START soc pert matrix: each row defines a day, the id of a station, the id of an e-scooter and its SoC for that combination. The perturbed matrix is used to introduce a more realistic discharge level, increasing battery swap/scooters pickup operations;
XY: coordinates of each of the 293 locations;
XY DEPOTS: coordinates of (real) depots;
id z cluster rilocazione: the 293 locations are partitioned in 3 different clusters; the mapping is done here;
XY CLUSTER DEPOTS: “virtual” depot (start/end point for the truck in that zone) for each cluster, obtained by running k-medoids algorithm on each cluster.

Model Parameters

Other than the dataset spreadsheet, there’s also some other configuration data, that were hardcoded in one of the Python files composing the old project. That data was about global parameters for the optimisation model and vehicles.

MSc CS Thesis #04 - The Library

Wed, 02 Sep 2026 10:36:00 +0100

I want to attack the shortest path problem first, given a pre-defined sequence of stations.

Before jumping into the code, a PhD student working on similar problems suggested me some C++ libraries about graphs to look into. The suggested ones are graph-v3, Graaf and MELON.

graph-v3 is an implementation of a C++ standardization proposal. While it is generic and idiomatic C++20 (and also supports custom graph structures), standard library proposals prioritize safety, generality, and interface stability over the absolute bleeding-edge performance achievable by specialized operations research libraries.

MSc CS Thesis #03 - The Task

Wed, 02 Sep 2026 10:18:00 +0100

After having described the problem and the selected approach (also detailing cost calculation), now it’s time to talk about what my actual task for this Master Thesis is.

The already described approach was implemented by Lombardo in Python, but the other professors working with him found the results of the experiment ok but not really satisfying as expected.

The doubt they now want to clarify is whether the approach is fundamentally wrong, or if it’s just an implementation problem. To find out, they gave me the task of re-implementing the system using C++, with all the memory optimizations and tricks that come with it.

MSc CS Thesis #02 - The Cost Function

Wed, 02 Sep 2026 08:59:00 +0100

We already saw that we are dealing with a layered DAG, in which we’d like to find the tour with minimum cost from/to the depot. A crucial point to this aim is to clearly define how we’d like such cost to be computed.

As a matter of fact, distance alone would not be that useful to us: we’d like to factor in also demand fulfillment at each station (meaning how distant we are from target demand of vehicles after the operation we did there) and deviation from social equity (trying to minimize the differences in availability between different zones, not favoring central/nice/rich neighborhoods over others).

MSc CS Thesis #01 - The Approach

Tue, 01 Sep 2026 17:43:00 +0100

I will not define myself a way to approach the e-Vehicle Rebalancing Tour Problem (will be more precise later on about what exactly is my task for this master thesis).

In fact, the approach has been already defined by Vincenzo Lombardo, a student from Milan who decided to model the problem using shortest paths on a specific weighted graph.

Particularly, he decided to move away from mathematical programming, modeling the distribution of e-vehicles in a city as a layered directed acyclic graph (DAG), with one layer per station (intended as different stage to pickup/drop-off scooters) and each node representing the state of the truck in terms of loaded vehicles and (charged) batteries.

MSc CS Thesis #00 - The Problem

Tue, 01 Sep 2026 16:24:00 +0100

Among different categories of bike (or scooters) sharing systems, free-floating ones are characterized by the fact that users can leave the chosen mean of transportation wherever they want, without worrying about precise placement at dedicated stations.

This comes with a downside: after a day of intensive use of the system, places in which they would have been very useful and requested could be left without enough of them. At the same time, it could be that some of them are completely abandoned in front of some random user’s door from the previous day, without being used at all.