Perceptron_Pizz2/README.md

> Dorian HAMDANI, Aubin DORIVAL, Rémi SCHIRRA

# Table of Contents  

- [🇬🇧 Perceptron Report](#-perceptron-report)  
  - [Introduction](#introduction)  
  - [Running the Program](#running-the-program)  
    - [Build](#build)  
    - [Execution](#execution)  
  - [Structure](#structure)  
  - [Comparison](#comparison)  
    - [Linear Perceptron](#linear-perceptron)  
      - [Linear Data](#linear-data-accuracy-1000)  
      - [Moon Data](#moon-data-accuracy-809)  
      - [Two Circles](#two-circles-accuracy-330)  
    - [General Perceptron](#general-perceptron)  
      - [Linear Data](#linear-data-accuracy-1000-1)  
      - [Moon Data](#moon-data-accuracy-974)  
      - [Two Circles](#two-circles-accuracy-1000)  
  - [MNIST Usage](#mnist-usage)  
  - [Our Experience](#our-experience)  

- [🇫🇷 Rapport Perceptron](#-rapport-perceptron)  
  - [Introduction](#introduction-1)  
  - [Lancer le programme](#lancer-le-programme)  
    - [Build](#build-1)  
    - [Exécution](#exécution)  
  - [Structure](#structure-1)  
  - [Comparaison](#comparaison)  
    - [Perceptron Linéaire](#perceptron-lineaire)  
      - [Linear Data](#linear-data-accuracy-1000-2)  
      - [Moon Data](#moon-data-accurancy-809)  
      - [Two Circles](#two-circles-accuracy-330-1)  
    - [Perceptron Générale](#perceptron-générale)  
      - [Linear Data](#linear-data-accuracy-1000-3)  
      - [Moon Data](#moon-data-accuracy-974-1)  
      - [Two Circles](#two-circles-accuracy-1000-1)  
  - [Utilisation MNIST](#utilisation-mnist)  
  - [Notre expérience](#notre-expérience)  


# 🇬🇧 Perceptron Report  

## Introduction  
This report presents the perceptron project, implemented in Java, that we successfully carried out without particular difficulties.  

## Running the Program  

### Build  
```bash
javac -d build src/main/java/fr/perceptron/*.java 
```

### Execution  

MNIST (training):  
```bash
java -cp build fr.perceptron.MnistMain
```

MNIST (results):  
```bash
java -cp build fr.perceptron.MnistWindow
```

2D Dataset:  
```bash
java -cp build fr.perceptron.Main
```

## Structure  
We structured the project as follows:  
- Main  
- NeuralNetwork  
  - Layers  
  - DataSet  
    - DataPoint  

The main execution file allows choosing the layer sizes used in the perceptron, as well as the dataset. The program will convert them into an easy-to-use format: a `DataSet` composed of `DataPoint`.  

## Comparison  

We first developed a linear version of the perceptron, without any modular approach. Then, in the second part, we designed a more flexible version, which allowed us to adapt the perceptron to different situations much more easily. Below is a comparison of the results obtained with the same dataset on both versions of the perceptron:  

### Linear Perceptron  

#### Linear Data (Accuracy: 100.0%)  
![linear_data_linear](images/linear_data_linear.png)  

#### Moon Data (Accuracy: 80.9%)  
![moon_data_linear](images/moon_data_linear.png)  

#### Two Circles (Accuracy: 33.0%)  
![twocircles_data_linear](images/twocircles_data_linear.png)  

### General Perceptron  

#### Linear Data (Accuracy: 100.0%)  
![linear_data](images/linear_data.GIF)  

#### Moon Data (Accuracy: 97.4%)  
![moon_data](images/moon_data.GIF)  

#### Two Circles (Accuracy: 100.0%)  
![twocircles_data](images/twocircles_data.GIF)  

## MNIST Usage  
On 2D datasets, once the perceptron is trained on the data, we can display a window that predicts the data separation for each pixel of the screen:  

On the handwritten digit dataset, after training the perceptron, we can visualize the results on dataset images or even on a digit drawn by hand:  

![mnist](images/mnist.png)  

However, some cases can be ambiguous and lead to a detection error, as in this example (a 2 is predicted while the image is actually labeled as a 7):  

![mnist_error](images/mnist_error.png)  

Nevertheless, the perceptron achieved a success rate of 97.24%.  

## Our Experience  
Starting from very abstract knowledge in the field of artificial intelligence, this perceptron project taught us a lot.  

First, regarding understanding, a significant amount of time was devoted to studying the course material, as it was necessary to fully grasp and connect the mathematical formulas.  

The implementation, which we initially thought would be quick, also required a lot of time, due to the rigor involved and the complexity of debugging. However, the object-oriented Java implementation approach allowed us to realize certain points: training a perceptron is actually similar to solving a system, and we also understood why AI training is performed on the GPU: because the calculations are simple and intuitively parallelizable.  

Finally, one problem we encountered was the interpretation of the results. We initially thought that the perceptron would output the equation of a line/hyperplane (linear or not) separating the data, but in fact, the perceptron classifies new data based on what it has “learned.”  


# 🇫🇷 Rapport Perceptron
## Introduction
Ce rapport présente le projet de perceptron, implémenté en Java que nous avons mené à bien, sans difficultés particulière.

## Lancer le programme
### Build
```bash
javac -d build src/main/java/fr/perceptron/*.java 
```
### Exécution
MNIST (entraînement) :
```bash
java -cp build fr.perceptron.MnistMain
```
MNIST (résultats) :
```
java -cp build fr.perceptron.MnistWindow
```

Jeu de donnée 2D :
```bash
java -cp build fr.perceptron.Main
```


## Structure
Nous avons structuré le projet de la manière suivante :
- Main
- NeuralNetwork
	- Layers
	- DataSet
		- DataPoint

Le fichier d'exécution principal permet le choix des tailles des couches utilisées dans le perceptron, et des données utilisée. Le programme se chargera de les convertir en un format facile à utiliser : un DataSet composé de DataPoint.

## Comparaison 

Nous avons commencé par développer une version linéaire du perceptron, sans aucune approche modulaire. Ensuite, dans la deuxième partie, nous avons conçu une version
plus flexible, ce qui nous a permis d'adapter le perceptron à différentes situations de manière bien plus aisée. Voici une comparaison des résultats obtenus avec le
même jeu de données sur les deux versions du perceptron :
### Perceptron Lineaire

#### Linear Data (Accuracy: 100.0%)
![linear_data_linear](images/linear_data_linear.png) 

#### Moon Data (Accurancy 80.9%)

![moon_data_linear](images/moon_data_linear.png)  

#### Two Circles (Accuracy: 33.0%)

![twocircles_data_linear](images/twocircles_data_linear.png)

### Perceptron Générale

#### Linear Data (Accuracy: 100.0%)

![linear_data](images/linear_data.GIF) 

#### Moon Data (Accuracy: 97.4%)

![moon_data](images/moon_data.GIF)  

#### Two Circles (Accuracy: 100.0%)
![twocircles_data](images/twocircles_data.GIF)

## Utilisation MNIST
Sur les jeux de données 2D, nous pouvons, après avoir entraîné le perceptron sur les données, afficher un fenêtre qui prédit la séparation des données pour chaque pixel de l'écran : 


Sur le jeu de donnée d'écriture manuscrite, après entraînement du perceptron, on peut visualiser les résultats sur des images du jeu de donnée ou bien un chiffre dessiné à la main :

![mnist](images/mnist.png)

Néanmoins, certains cas peuvent être ambigües et provoquer une erreur de détection comme ici (un 2 est prédit alors que l'image est marquée étant un 7) :

![mnist_error](images/mnist_error.png)

Le perceptron a tout de même un taux de 97.24% de bonne réponses.

## Notre expérience
A partir de nos connaissances très abstraites sur le domaine de l'intelligence artificielle, ce projet de perceptron nous a beaucoup apprit.

A commencer par la compréhension, une période de temps non négligeable a été consacrée à la lecture du cours, il a fallu réussir à comprendre et lier les formules mathématiques entre elles.

L'implémentation, que nous pensions au départ être rapide, a également demandé beaucoup de temps, en raison de la rigueur demandée et la détection de bug plus complexe. L'approche d'implémentation en Java (POO) nous a néanmoins permit de réaliser certains points : l'entraînement d'un perceptron ressemble en fait à la résolution d'un système, et nous avons aussi comprit pourquoi l'entraînement d'IA est exécutée sur la carte graphique : car les calculs effectués sont simples et intuitivement parallélisable.

Pour finir, un problème que nous avons rencontré, a été l'interprétation des résultats. Nous pensions que le perceptron renverrai l'équation d'une droite / hyperplan (linéaire ou non) séparant les données, mais en fait, le perceptron classifie une donnée nouvelle en fonction de ce qu'il a "apprit".