From 4656c04ad9296160d8bbf89789498f95f38816b3 Mon Sep 17 00:00:00 2001 From: augustin64 Date: Fri, 9 Dec 2022 22:18:58 +0100 Subject: [PATCH] Add mnist & webserver documentation --- doc/README.md | 7 +++ doc/{cnn.md => cnn/neuron_io.md} | 2 +- doc/mnist/README.md | 18 +++++++ doc/mnist/main.md | 78 ++++++++++++++++++++++++++++++ doc/{nn.md => mnist/neuron_io.md} | 2 +- doc/mnist/preview.md | 13 +++++ doc/mnist/utils.md | 32 ++++++++++++ doc/webserver/README.md | 13 +++++ src/mnist/include/neural_network.h | 3 +- 9 files changed, 165 insertions(+), 3 deletions(-) create mode 100644 doc/README.md rename doc/{cnn.md => cnn/neuron_io.md} (97%) create mode 100644 doc/mnist/README.md create mode 100644 doc/mnist/main.md rename doc/{nn.md => mnist/neuron_io.md} (95%) create mode 100644 doc/mnist/preview.md create mode 100644 doc/mnist/utils.md create mode 100644 doc/webserver/README.md diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 0000000..e68b914 --- /dev/null +++ b/doc/README.md @@ -0,0 +1,7 @@ +# README + +Plusieurs fichiers sont disponibles: +- [mnist](/doc/mnist/README.md) Réseau de neurones non convolutif +- [cnn](/doc/cnn/README.md) Réseau de neurones convolutif +- [webserver](/doc/webserver/README.md) Serveur web (python) pour créer des entrées manuellement +- [Ressources](/doc/resources.md) Ressources utilisées \ No newline at end of file diff --git a/doc/cnn.md b/doc/cnn/neuron_io.md similarity index 97% rename from doc/cnn.md rename to doc/cnn/neuron_io.md index a1d7a7f..fa1b0c8 100644 --- a/doc/cnn.md +++ b/doc/cnn/neuron_io.md @@ -1,4 +1,4 @@ -# Réseau de neurones convolutionnel [lien](/src/cnn) +# Neuron IO ## Lecture/ Écriture du réseau de neurone: Le fichier est au format IDX (format binaire) diff --git a/doc/mnist/README.md b/doc/mnist/README.md new file mode 100644 index 0000000..8100010 --- /dev/null +++ b/doc/mnist/README.md @@ -0,0 +1,18 @@ +# Réseau de neurones simple [code](/src/mnist) + +Cette partie du code implémente un réseau de neuron simple (non convolutif) + +## Compilation +```bash +make mnist +``` + +## Fichiers +- [main](/src/mnist/main.c) [[Documentation](/doc/mnist/main.md)] Contient la fonction main et les fonctions principales à appeler +- [mnist](/src/mnist/mnist.c) [[Documentation](/src/mnist/include/mnist.h)] Partagé avec le cnn, lit les fichiers du jeu de données [MNIST](http://yann.lecun.com/exdb/mnist/) +- [neural_network](/src/mnist/neural_network.c) [[Documentation](/src/mnist/include/neural_network.h)] Contient le coeur du nn: forward et backward propagation ainsi que quelques utilitaires (copie et patch) +- [neuron_io.c](/src/mnist/neuron_io.c) [[Documentation](/doc/mnist/neuron_io.md)] Écrire et lire le réseau de neurones depuis un fichier +- [neuron.h](/src/mnist/include/neuron.h) Définit la structure `Network` et les structures qui y sont liées + +- [preview.c](/src/mnist/preview.c) [[Documentation](/doc/mnist/preview.md)] Afficher les images chargées +- [utils.c](/src/mnist/utils.c) [[Documentation](/doc/mnist/utils.md)] Contient un ensemble de fonctions utiles à des fins de débogage \ No newline at end of file diff --git a/doc/mnist/main.md b/doc/mnist/main.md new file mode 100644 index 0000000..3e99114 --- /dev/null +++ b/doc/mnist/main.md @@ -0,0 +1,78 @@ +# Main + +## Compilation + +```bash +make mnist-main +``` + +## Options à la compilation + +- La définition de la taille des batches se fait dans l'un des [`#define`](/src/mnist/main.c#L15) +- Le multi-threading est activé par défaut, réduisible à un seul thread actif en remplaçant [`get_nprocs()`](/src/mnist/main.c#L144) par 1 +- L'ajustement du nombre de couches, bien qu'étant une option en ligne de commande, ne définit pas les valeurs pour chaque couche. On préférera donc modifier directement ces valeurs dans le code [ici](/src/mnist/main.c#L140) et [ici](/src/mnist/main.c#L378) + +## Utilisation +```bash +Usage: build/mnist-main ( train | recognize | test ) [OPTIONS] + +OPTIONS: + train: + --epochs | -e [int] Nombre d'époques (itérations sur tout le set de données). + --couches | -c [int] Nombres de couches. + --neurones | -n [int] Nombre de neurones sur la première couche. + --recover | -r [FILENAME] Récupérer depuis un modèle existant. + --images | -i [FILENAME] Fichier contenant les images. + --labels | -l [FILENAME] Fichier contenant les labels. + --out | -o [FILENAME] Fichier où écrire le réseau de neurones. + --delta | -d [FILENAME] Fichier où écrire le réseau différentiel. + --nb-images | -N [int] Nombres d'images à traiter. + --start | -s [int] Première image à traiter. + recognize: + --modele | -m [FILENAME] Fichier contenant le réseau de neurones. + --in | -i [FILENAME] Fichier contenant les images à reconnaître. + --out | -o (text|json) Format de sortie. + test: + --images | -i [FILENAME] Fichier contenant les images. + --labels | -l [FILENAME] Fichier contenant les labels. + --modele | -m [FILENAME] Fichier contenant le réseau de neurones. + --preview-fails | -p Afficher les images ayant échoué. +``` + +## Entraînement + +Entraînement du réseau de neurones + +Exemple: +```bash +build/mnist-main train \ + -e 15 \ + -i data/mnist/train-images-idx3-ubyte \ + -l data/mnist/train-labels-idx1-ubyte \ + -o reseau.bin +``` + +Le réseau de neurones est sauvegardé dans le fichier de sortie à la fin de chaque époque. + +## Reconnaissance d'images + +La reconnaissance d'images se fait avec un fichier formaté de la même manière que le jeu de données MNIST. +Le plus simple pour dessiner à la main est d'utiliser le [serveur web](/doc/webserver/README.md) prévu à cet effet + +Exemple: +```bash +build/mnist-main recognize \ + -m reseau.bin \ + -i .cache/image-idx3-ubyte \ + -o json +``` + +## Test sur le jeu prévu à cet effet + +Exemple: +```bash +build/mnist-main test \ + -i data/mnist/t10k-images-idx3-ubyte \ + -l data/mnist/t10k-labels-idx1-ubyte \ + -m reseau.bin +``` \ No newline at end of file diff --git a/doc/nn.md b/doc/mnist/neuron_io.md similarity index 95% rename from doc/nn.md rename to doc/mnist/neuron_io.md index f11d2de..4bf79f4 100644 --- a/doc/nn.md +++ b/doc/mnist/neuron_io.md @@ -1,4 +1,4 @@ -# Réseau de neurones simple [lien](/src/mnist) +# Neuron IO ## Lecture/ Écriture du réseau de neurone: Le fichier est au format IDX (format binaire) diff --git a/doc/mnist/preview.md b/doc/mnist/preview.md new file mode 100644 index 0000000..fac0111 --- /dev/null +++ b/doc/mnist/preview.md @@ -0,0 +1,13 @@ +# Preview + +## Compilation + +```bash +make mnist-preview +``` + +## Utilisation + +```bash +build/mnist-preview data/mnist/t10k-images-idx3-ubyte data/mnist/t10k-labels-idx1-ubyte +``` \ No newline at end of file diff --git a/doc/mnist/utils.md b/doc/mnist/utils.md new file mode 100644 index 0000000..79ee99a --- /dev/null +++ b/doc/mnist/utils.md @@ -0,0 +1,32 @@ +# Utils + +## Compilation + +```bash +make mnist-utils +``` + +## Utilisation + +```bash +Usage: build/mnist-utils ( print-poids | print-biais | creer-reseau | patch-network ) [OPTIONS] + +OPTIONS: + print-poids: + --reseau | -r [FILENAME] Fichier contenant le réseau de neurones. + print-biais: + --reseau | -r [FILENAME] Fichier contenant le réseau de neurones. + count-labels: + --labels | -l [FILENAME] Fichier contenant les labels. + creer-reseau: + --out | -o [FILENAME] Fichier où écrire le réseau de neurones. + --number | -n [int] Numéro à privilégier. + patch-network: + --network | -n [FILENAME] Fichier contenant le réseau de neurones. + --delta | -d [FILENAME] Fichier de patch à utiliser. + print-images: + --images | -i [FILENAME] Fichier contenant les images. + print-poids-neurone: + --reseau | -r [FILENAME] Fichier contenant le réseau de neurones. + --neurone | -n [int] Numéro du neurone dont il faut afficher les poids. +``` \ No newline at end of file diff --git a/doc/webserver/README.md b/doc/webserver/README.md new file mode 100644 index 0000000..52e2c1a --- /dev/null +++ b/doc/webserver/README.md @@ -0,0 +1,13 @@ +# Webserver + +## Pré-requis + +```bash +pip install flask +``` + +## Utilisation + +```bash +make webserver +``` \ No newline at end of file diff --git a/src/mnist/include/neural_network.h b/src/mnist/include/neural_network.h index c392691..7bfe67f 100644 --- a/src/mnist/include/neural_network.h +++ b/src/mnist/include/neural_network.h @@ -66,7 +66,8 @@ void network_modification(Network* network, uint32_t nb_modifs); void network_initialisation(Network* network); /* -* Les deux réseaux donnés sont supposés de même dimensions +* Les deux réseaux donnés sont supposés de même dimensions, +* Applique les modifications contenues dans delta à network */ void patch_network(Network* network, Network* delta, uint32_t nb_modifs);