prep submission

README.md

@@ -0,0 +1,9 @@
+# AI cup 2020 edition -- Claudio Maggioni
+
+Please use the following file directory to find where each report is:
+
+- `code/`: the code folder. Instructions on how to compile and run the code can be found in `execute.md` in the root directory of the ZIP file;
+- `AI_cup_2020_ClaudioMaggioni.xls`: The Excel file with results of my submission;
+- `execute.md`: A file containing the instructions needed and commands to execute in order to reproduce my best runs;
+- `sysinfo.md`: A file containing all the details about the system I used for the runs;
+- `approach.md`: A document with the description of my approach.

approach.md

@@ -1,14 +1,30 @@
-# System information
+<!-- vim: set ts=2 sw=2 et tw=80: -->
 
-Here is a summary of the system characteristics of the machine used to measure the execution time and 
-execution results for my AI cup submission:
+# Approach used to solve the AI cup
 
-| Characteristic | Value     |
-| :------------- | :----------: | 
-| Machine used | Macbook Pro 2018 15" |
-| OS Version | MacOS Catalina 10.15.7 |
-| Kernel | Mach 19.6.0 |
-| Interpreter used (Python wrapper) | CPython 3.8.3 (default, Jul 2 2020, 11:26:31) |
-| Compiler used (C++ companion program) | Apple clang version 12.0.0 (clang-1200.0.32.21) |
-| Compiler optimization level (C++ companion program) | `-O2` |
-| CPU | Intel i7-8750H (12) @ 2.20GHz |
+My submission for the AI cup uses a _Ant Colony Optimization_ algorithm
+implementation paired with a 3-opt optimizer.
+
+For efficiency's sake, both the
+algorithm and the optimizer were implemented in C++. However, solution checking
+and the calculation of the euclid distance matrix are still computed in a
+modified version of the Python 3 code of the `AI2020BsC` repository from Mr.
+Montegazza.
+
+The Python code first compiles the C++ portion of the code in an executable.
+Then, a Python wrapper is used to call said executable. The distance matrix is
+computed by the Python implementation and then saved in a .txt file. The C++
+executable reads said file and, after executing the algorithm and the optimizer,
+the program writes on the standard output a python expression containing the
+solution array. This expression is then read by the Python wrapper and evaluated
+using `eval(...)`, and then is is checked and displayed thanks to the original
+`AI2020BsC` code.
+
+More details on how to compile and run the program can be found in `execute.md`.
+
+The C++ implementation is by default non-parallel, as I interpreted the
+"Single CPU" restriction described in the cup introductory PDF as meaning that
+the code must run on a single core. The implementation can however be easily
+converted in a multi-core one ant per thread implentation by changing the
+`#define SINGLE_CORE` flag in `aco.cc` to `0`. Note that the 3 minute limit is
+of course never reached even when using the single core implementation.