dovrebbe convergere su mnist, da completare con persistenza e visualizzatore

2026-03-25 13:00:09 +01:00
parent 524f33a690
commit 0b31a0e0d7
13 changed files with 528 additions and 675 deletions
@@ -1,2 +1,199 @@
-# cifar_10
+# Classificatore di Immagini con Rete Neurale

+Implementazione in C di una rete neurale from-scratch per la classificazione di immagini sui dataset MNIST e CIFAR-10.
+
+## Panoramica
+
+Questo progetto implementa una rete neurale fully-connected con:
+- **Attivazione**: funzione sigmoide
+- **Addestramento**: backpropagation con discesa del gradiente
+- **Predizione**: softmax per classificazione multi-classe
+
+## Struttura del Progetto
+
+```
+.
+├── classificatore.c          # Programma principale
+├── percettroni.h             # Libreria core della rete neurale (header-only)
+├── xor_manager.h             # Manager dataset XOR (4 campioni, test rapido)
+├── mnist/
+│   └── mnist_manager.h       # Manager dataset MNIST (28x28 pixel)
+├── cifar-10/
+│   └── cifar10_manager.h     # Manager dataset CIFAR-10 (32x32 RGB)
+├── visualizzatore.c          # Visualizzatore immagini (richiede Allegro)
+└── rete_pesi.bin             # Pesi pre-addestrati
+```
+
+## Compilazione
+
+### Classificatore MNIST (default)
+```bash
+gcc -o classificatore_mnist classificatore.c -lm
+./classificatore_mnist
+```
+
+### Test XOR (validazione rapida)
+Modifica `percettroni.h`:
+- Commenta: `// #include "mnist/mnist_manager.h"`
+- Decommenta: `#include "xor_manager.h"`
+
+```bash
+gcc -o classificatore_xor classificatore.c -lm
+./classificatore_xor
+```
+
+### Visualizzatore
+```bash
+gcc -o visualizzatore visualizzatore.c -lalleg -lm
+```
+
+## Componenti Principali
+
+### percettroni.h
+
+Libreria header-only che implementa la rete neurale completa.
+
+**Strutture dati:**
+- `Percettrone`: singolo neurone con pesi, bias e dimensione
+- `Layer`: strato di percettroni
+- `ReteNeurale`: rete completa con array di layer
+
+**Funzioni principali:**
+
+```c
+// Inizializzazione
+ReteNeurale inizializza_rete_neurale(int numero_input, int numero_layers, 
+                                      int numero_percettroni_iniziali, 
+                                      int numero_percettroni_finali);
+
+// Forward propagation
+double **elabora_sigmoidi(ReteNeurale *rete, Istanza istanza);
+
+// Backpropagation
+double **elabora_gradienti(ReteNeurale *rete, byte output_corretto, double **sigmoidi);
+void aggiorna_pesi(ReteNeurale *rete, double **sigmoidi, double **gradienti, Istanza istanza);
+
+// Predizione
+int previsione_softmax(double *output, int size);
+
+// Persistenza
+void salvaReteNeurale(const char *filename, ReteNeurale *rete);
+ReteNeurale *caricaReteNeurale(const char *filename);
+```
+
+**Architettura dinamica:**
+I layer intermedi riducono progressivamente i percettroni secondo la formula:
+```
+percettroni = percettroni_iniziali * (layer_rimanenti / layer_totali)
+```
+
+### classificatore.c
+
+Programma principale che configura e addestra la rete.
+
+```c
+#define EPOCHE 50
+
+void main() {
+    // Rete: 784 input (MNIST), 10 layer, 256 percettroni iniziali, 10 output
+    ReteNeurale rete = inizializza_rete_neurale(N_INPUTS, 10, 256, 10);
+    Dataset mnist = *get_dataset();
+
+    for(int epoca = 0; epoca < EPOCHE; epoca++) {
+        if (addestra(&rete, mnist))
+            break;  // Stop se accuratezza 100%
+    }
+}
+```
+
+### Manager Dataset
+
+Ogni manager definisce:
+- `N_INPUTS`: dimensione input (es. 784 per MNIST 28x28)
+- `Istanza`: struct con `classificazione` e `dati[]`
+- `Dataset`: struct con array di istanze e dimensione
+- `get_dataset()`: funzione che carica i dati
+
+#### xor_manager.h
+Dataset semplice per test (4 campioni):
+- Input: 2 valori binari
+- Output: 1 valore (XOR)
+- Perfetto per verificare convergenza
+
+#### mnist/mnist_manager.h
+Dataset MNIST:
+- Input: 784 pixel (28×28)
+- Output: 10 classi (cifre 0-9)
+- Formato IDX: header binario + pixel raw
+- Supporta train (60k) e test (10k) set
+
+#### cifar-10/cifar10_manager.h
+Dataset CIFAR-10:
+- Input: 3072 valori (32×32 RGB)
+- Output: 10 classi (oggetti)
+- Formato binario: label + pixel RGB
+
+## Configurazione Dataset
+
+In `percettroni.h`, includi il manager desiderato:
+
+```c
+// Per MNIST
+#include "mnist/mnist_manager.h"
+
+// Per XOR (testing)
+// #include "xor_manager.h"
+
+// Per CIFAR-10
+// #include "cifar-10/cifar10_manager.h"
+```
+
+## Costanti Principali
+
+- `LRE = 0.1`: learning rate
+- `soglia_sigmoide = 0.5`: soglia per predizione binaria
+- `EPOCHE`: numero epoche addestramento
+
+## Debugging
+
+```bash
+# Ispezione pesi
+stampa_pesi_rete(&rete);
+
+# Controllo memory leak
+valgrind --leak-check=full ./classificatore_mnist
+
+# Monitoraggio training
+// Modifica addestra() per stampare errore per epoca
+```
+
+## Note Tecniche
+
+- **Normalizzazione**: input byte (0-255) convertiti in double (0.0-1.0)
+- **Inizializzazione**: pesi casuali in [-1, 1]
+- **Attivazione**: sigmoide con formula `1/(1+e^(-x))`
+- **Softmax**: usato solo sull'output per probabilità multi-classe
+- **Prestazioni**: training CPU-intensive (minuti per epoca su MNIST)
+
+## Esempio Output Training
+
+```
+Layer 0 -> percettroni: 256
+Layer 1 -> percettroni: 230
+...
+Layer 9 -> percettroni: 10
+Rete neurale da 123456 parametri
+Risposte corrette: 85%
+Risposte corrette: 92%
+...
+```
+
+## Requisiti
+
+- GCC o compilatore C compatibile
+- Libreria math (`-lm`)
+- Allegro (solo per visualizzatore)
+
+## Licenza
+
+Progetto didattico - Implementazione from-scratch per scopi educativi.