GitHub release v2.0.0

Author: GabrieleSpini

.gitignore

@@ -102,7 +102,7 @@ ipython_config.py
 #   This is especially recommended for binary packages to ensure reproducibility, and is more
 #   commonly ignored for libraries.
 #   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
-# poetry.lock
+poetry.lock
 
 # pdm
 #   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.

README.md

@@ -1,15 +1,32 @@
 # MUPOL MPC Solution for the Collaborative Freighter Delivery Problem :articulated_lorry: :closed_lock_with_key:
 
+## Overview :telescope:
+
+This library forms the second component of the MUPOL MPC demonstrator, namely, the MPC solver itself.
+In a nutshell, given a problem instance generated with the MUPOL plaintext library (hence a map with orders and trucks at given locations, where orders need to be brought to other locations with a given priority), the MPC solver will find a solution by making use of MPC, and hence by preserving the confidentiality of the trucks and orders information.
+
 ## Installation :wrench:
 
 ### Dependency management
 
 Installation and dependencies are managed by [Poetry](https://python-poetry.org/), which can be installed with `pipx install poetry`.
 
+Once you've cloned the project, just run `poetry install` and you should be good to go.
+
 ### Internal dependencies
 
-Furthermore, this project uses [MUPOL plaintext](https://github.com/ait-crypto/MUPOL-Plaintext).
-The project code is currently not provided in a Python package, hence it is up to the user to create such a package and add it to the Python virtual environment.
+This project uses a non-PyPI repository, [MUPOL plaintext](https://github.com/ait-crypto/MUPOL-Plaintext), as a dependency.
+It will be installed from source by Poetry when you run `poetry install`, so this should not affect the user.
+
+## Content :clipboard:
+
+The library files are contained in the `mupol/mpc` folder;
+they primarily consists of the `solver.py` file (containing the main class to solve a MUPOL problem instance with MPC) and of the `input_uploader.py` file (that "uploads" MUPOL objects to the MPyC framework).
+The `utils` folder contains files for arguments handling and logging, and some MPyC utility functions.
+
+The necessary configuration files can be found in the `config` folder.
+
+Finally, the root folder contain an example wrapper `example.py`, that will generatae a MUPOL problem instance and solve it, and a `profiler.py` for benchmarking.
 
 
 ## Example usage :checkered_flag:
@@ -20,6 +37,6 @@ If you want to fully simulate several parties (e.g., 3) with separate processes,
 
 ## Credits
 
-This project was partially funded by the Austrian Research Promotiion Agency (FFG) with the "Digitale Technolgien" funding frame under grant agreement no. 902669 (MUPOL).
+This project was partially funded by the Austrian Research Promotiion Agency (FFG) with the "Digitale Technologien" funding frame under grant agreement no. 902669 (MUPOL).
 
 Authors: Gabriele Spini and Stephan Krenn, AIT.

config/config.ini

@@ -14,6 +14,9 @@ num_iters: 1000
 [MPC solver parameters]
 dummy_node: -1
 dummy_freighter_id: -1
+use_priorities: 1
+test_mode: 1
+norm_weight: 0.5
 
 [MPC parameters]
 bit_length_sectypes: 10

config/config_scalability.ini

@@ -1,5 +1,5 @@
 [Problem parameters]
-num_freighters: 3
+num_freighters: 1
 min_num_trucks: 1
 max_num_trucks: 4
 truck_capacity: 32
@@ -14,6 +14,9 @@ num_iters: 1000
 [MPC solver parameters]
 dummy_node: -1
 dummy_freighter_id: -1
+use_priorities: 0
+test_mode: 1
+norm_weight: 1
 
 [MPC parameters]
 bit_length_sectypes: 10

config/logger_config_scalability.ini

@@ -21,7 +21,7 @@ propagate=0
 class=FileHandler
 level=DEBUG
 formatter=mupolMPCFormatter
-args=(__import__("datetime").datetime.now().strftime('logs/mupol_mpc_log_%%Y-%%m-%%d_%%H-%%M-%%S.log'), 'a')
+args=(__import__("datetime").datetime.now().strftime('logs/mupol_mpc_log_%%Y-%%m-%%d_%%H-%%M.log'), 'a')
 
 [formatter_mupolMPCFormatter]
 format=%(asctime)s - %(name)s - %(levelname)s - %(message)s

example.py

@@ -5,6 +5,7 @@
 from mupol.plaintext.freighters_day_planning.random_problem_generator import (
     RandomProblemGenerator,
 )
+from mupol.plaintext.freighters_day_planning.simple_solver import SimpleSolver
 
 from mupol.mpc.input_uploader import prepare_mpc_data
 from mupol.mpc.solver import MPCSolver
@@ -27,15 +28,37 @@ async def main() -> None:
         args.random_seed,
     )
     problem: Problem = generator.get_problem()
+    logger.debug("Problem instance: %s", str(problem))
+
+    plain_solver = SimpleSolver()
+    logger.info(
+        "Plain solver result with hardcoded weight: %s", plain_solver.solve(problem)
+    )
 
     logger.debug("Uploading data in MPC")
     await prepare_mpc_data(
         problem, args.dummy_freighter_id, args.dummy_node, args.bit_length_sectypes
     )
 
+    if args.test_mode == 1:
+        for order in problem.orders:
+            logger.debug(
+                "Order: volume %s origin %s destination %s",
+                await mpc.output(order.volume),
+                await mpc.output(order.origin),
+                await mpc.output(order.destination),
+            )
+
     logger.debug("Running solver")
     solver = MPCSolver(
-        problem, args.dummy_freighter_id, args.dummy_node, args.truck_capacity, logger
+        problem,
+        args.dummy_freighter_id,
+        args.dummy_node,
+        args.truck_capacity,
+        args.use_priorities,
+        args.test_mode,
+        logger,
+        args.norm_weight,
     )
     await solver.solve_problem()
 

mupol/mpc/input_uploader.py

@@ -1,5 +1,6 @@
 """
-This module contains the functions to upload the input data to the MPyC framework.
+This module contains the functions to 'upload' the input data to the MPyC framework
+(i.e. secret-share it).
 """
 
 from mpyc.runtime import mpc
@@ -10,17 +11,25 @@
 
 async def upload_order(order: Order, secint: type) -> None:
     """Function to secret-share a single order object.
+    Notice that we assume that the order object always comes from the first MPC player:
+    this is enough for the current MUPOL demonstrator but will need to be made more
+    flexible when moving to highter TRL or more realistic experiments.
 
     :param order: the order to be secret-shared
     :param secint: the desired type of MPyC secret sharing
     """
+    order.id = mpc.input(secint(order.id), senders=0)
     order.origin = mpc.input(secint(order.origin), senders=0)
     order.destination = mpc.input(secint(order.destination), senders=0)
     order.volume = mpc.input(secint(order.volume), senders=0)
+    order.priority = mpc.input(secint(order.priority), senders=0)
 
 
 async def initialize_order(order: Order, secint: type, dummy_freighter_id: int) -> None:
     """Set initial order variables.
+    Notice that we assume that the order object always comes from the first MPC player:
+    this is enough for the current MUPOL demonstrator but will need to be made more
+    flexible when moving to highter TRL or more realistic experiments.
 
     :param order: the relevant order object
     :param secint: the desired type of the MPyC secret-shared values
@@ -33,6 +42,9 @@ async def initialize_order(order: Order, secint: type, dummy_freighter_id: int)
 
 async def upload_truck(truck: Truck, secint: type) -> None:
     """Function to secret-share a single truck object.
+    Notice that we assume that the truck object always comes from the first MPC player:
+    this is enough for the current MUPOL demonstrator but will need to be made more
+    flexible when moving to highter TRL or more realistic experiments.
 
     :param truck: the truck to be secret-shared
     :param secint: the desired type of MPyC secret sharing
@@ -44,6 +56,9 @@ async def upload_truck(truck: Truck, secint: type) -> None:
 
 async def initialize_truck(truck: Truck, dummy_node: int, secint: type) -> None:
     """Set initial truck variables.
+    Notice that we assume that the truck object always comes from the first MPC player:
+    this is enough for the current MUPOL demonstrator but will need to be made more
+    flexible when moving to highter TRL or more realistic experiments.
 
     :param truck: the relevant truck object
     :param dummy_node: which value to use for truck with no destination assigned