perf: Add MEMORY_TRADEOFFS and PERFORMANCE documentation

- Introduced MEMORY_TRADEOFFS.md to explain memory vs deduplication trade-offs in anagram generation. - Added PERFORMANCE.md detailing optimizations for handling large volumes of anagram generation efficiently. - Created USAGE.md for comprehensive usage instructions, including installation, basic commands, and advanced generation modes. - Enhanced generator with streaming and batch processing capabilities for improved memory management. - Implemented quick hashing for deduplication to reduce memory footprint. - Updated main.rs to support new command-line arguments for streaming and batch modes. - Added tests to ensure letter removal maintains minimum word length and to verify anagram sorting functionality.
2025-11-06 23:38:05 +01:00
parent ebdbe60e04
commit 02cf48088a
12 changed files with 1733 additions and 19 deletions
--- a/docs/USAGE.md
+++ b/docs/USAGE.md
@@ -0,0 +1,296 @@
+# Guide d'utilisation
+
+## Installation et compilation
+
+```bash
+# Compiler en mode release (optimisé)
+cargo build --release
+
+# L'exécutable se trouve dans
+target/release/anagram-generator
+```
+
+## Utilisation basique
+
+### Générer des anagrammes d'un mot
+```bash
+# 10 anagrammes par défaut
+cargo run --release -- --word "programming"
+
+# Spécifier le nombre d'anagrammes
+cargo run --release -- --word "programming" --count 100
+
+# Avec un score minimum de prononçabilité
+cargo run --release -- --word "programming" --count 50 --min-score 60
+```
+
+### Générer des mots aléatoires prononçables
+```bash
+# 10 mots de 6 lettres par défaut
+cargo run --release
+
+# Spécifier la longueur et le nombre
+cargo run --release -- --count 20 --length 8
+
+# Avec un préfixe
+cargo run --release -- --count 10 --prefix "sup"
+
+# Avec un score minimum
+cargo run --release -- --count 50 --min-score 70
+```
+
+## Modes de génération avancés
+
+### Mode Streaming (recommandé pour > 10k anagrammes)
+
+Le mode streaming génère les anagrammes à la demande avec une mémoire plafonnée.
+
+```bash
+# Générer 1 million d'anagrammes en streaming
+cargo run --release -- --word "programming" --count 1000000 --streaming
+
+# Avec indicateur de progression
+cargo run --release -- --word "programming" --count 1000000 --streaming --progress
+
+# Rediriger vers un fichier
+cargo run --release -- --word "programming" --count 10000000 --streaming > anagrams.txt
+```
+
+**Avantages** :
+- Mémoire plafonnée (~8MB maximum)
+- Premiers résultats immédiats
+- Idéal pour pipeline avec autres outils
+
+**⚠️ Important - Déduplication limitée** :
+- Les **100 000 premiers** anagrammes sont garantis **uniques**
+- Au-delà, des **duplicatas peuvent apparaître** (la mémoire reste constante à ~8MB)
+- Pour une déduplication **100% complète**, utilisez le **mode batch** à la place
+
+### Mode Batch (recommandé pour > 1M anagrammes)
+
+Le mode batch traite les anagrammes par groupes pour optimiser la mémoire.
+
+```bash
+# Générer 10 millions d'anagrammes par batches de 100k
+cargo run --release -- --word "programming" --count 10000000 --batch-size 100000
+
+# Avec progression
+cargo run --release -- --word "programming" --count 10000000 --batch-size 100000 --progress
+
+# Batch size optimal selon RAM disponible
+# RAM 4GB : batch-size 50000-100000
+# RAM 8GB : batch-size 100000-500000
+# RAM 16GB+ : batch-size 500000-1000000
+```
+
+**Avantages** :
+- Mémoire contrôlée (proportionnelle au batch size)
+- Déduplication globale
+- Idéal pour très grandes générations
+
+### Mode Standard (recommandé pour < 10k anagrammes)
+
+Mode par défaut, tous les anagrammes en mémoire.
+
+```bash
+# Simple et rapide pour petites quantités
+cargo run --release -- --word "programming" --count 1000
+```
+
+## Options de transformation
+
+### Suppression de lettres
+
+Permet de retirer des lettres pour améliorer la prononçabilité.
+
+```bash
+# Autoriser la suppression de jusqu'à 2 lettres
+cargo run --release -- --word "programming" --count 50 --remove-letters 2
+
+# Utile pour mots difficiles
+cargo run --release -- --word "strengths" --count 20 --remove-letters 3 --min-score 70
+```
+
+### Ajout de voyelles
+
+Ajoute des voyelles pour améliorer la prononçabilité.
+
+```bash
+# Ajouter jusqu'à 2 voyelles
+cargo run --release -- --word "rhythm" --count 30 --add-vowels 2
+
+# Combiné avec score minimum
+cargo run --release -- --word "crypt" --count 20 --add-vowels 2 --min-score 65
+```
+
+### Ajout de lettres communes
+
+Ajoute des voyelles et consonnes communes (r, s, t, n, l).
+
+```bash
+# Ajouter jusqu'à 3 lettres communes
+cargo run --release -- --word "xyz" --count 50 --add-letters 3 --min-score 60
+```
+
+## Configuration avancée
+
+### Nombre de tentatives
+
+Contrôle le nombre d'essais pour générer chaque anagramme.
+
+```bash
+# Augmenter pour mots difficiles ou scores élevés
+cargo run --release -- --word "xyz" --count 10 --max-attempts 5000 --min-score 70
+
+# Réduire pour génération plus rapide (au risque de générer moins d'anagrammes)
+cargo run --release -- --word "hello" --count 100 --max-attempts 500
+```
+
+## Exemples d'utilisation avancée
+
+### Pipeline avec tri et filtrage
+```bash
+# Générer, filtrer et trier
+cargo run --release -- --word "programming" --count 10000 --streaming \
+  | grep -v "^[0-9]*\. .*x" \
+  | sort -t':' -k2 -nr
+```
+
+### Génération massive vers fichier
+```bash
+# 100 millions d'anagrammes en streaming
+cargo run --release -- \
+  --word "algorithm" \
+  --count 100000000 \
+  --streaming \
+  --progress \
+  --min-score 55 \
+  > anagrams_100M.txt 2> progress.log
+```
+
+### Génération par batches avec traitement
+```bash
+# Traiter chaque batch séparément
+cargo run --release -- \
+  --word "computer" \
+  --count 50000000 \
+  --batch-size 1000000 \
+  --progress \
+  | split -l 1000000 - batch_
+```
+
+### Comparaison de performance
+```bash
+# Mode standard (petite quantité)
+time cargo run --release -- --word "test" --count 1000
+
+# Mode streaming (grande quantité)
+time cargo run --release -- --word "test" --count 100000 --streaming > /dev/null
+
+# Mode batch (très grande quantité)
+time cargo run --release -- --word "test" --count 1000000 --batch-size 100000 > /dev/null
+```
+
+## Benchmarks
+
+### Exécuter les benchmarks de performance
+```bash
+cargo bench
+```
+
+Les benchmarks comparent :
+- Génération standard vs streaming
+- Différentes tailles de batches
+- Impact mémoire
+
+### Résultats typiques (indicatifs)
+
+| Mode | Quantité | Temps | Mémoire |
+|------|----------|-------|---------|
+| Standard | 1,000 | ~0.5s | ~5MB |
+| Standard | 10,000 | ~5s | ~50MB |
+| Streaming | 100,000 | ~50s | ~10MB |
+| Streaming | 1,000,000 | ~8min | ~10MB |
+| Batch (100k) | 10,000,000 | ~80min | ~50MB |
+
+## Recommandations
+
+### Pour développement et tests
+```bash
+cargo run --release -- --word "test" --count 100 --min-score 60
+```
+
+### Pour génération quotidienne
+```bash
+cargo run --release -- --word "myword" --count 10000 --streaming --progress
+```
+
+### Pour génération massive
+```bash
+cargo run --release -- \
+  --word "myword" \
+  --count 100000000 \
+  --batch-size 1000000 \
+  --progress \
+  --min-score 50 \
+  > output.txt 2> progress.log
+```
+
+### Pour mots difficiles
+```bash
+cargo run --release -- \
+  --word "difficultword" \
+  --count 1000 \
+  --remove-letters 2 \
+  --add-vowels 1 \
+  --max-attempts 5000 \
+  --min-score 65
+```
+
+## Aide complète
+
+```bash
+# Afficher toutes les options
+cargo run --release -- --help
+```
+
+## Dépannage
+
+### Peu d'anagrammes générés
+```bash
+# Solutions :
+# 1. Réduire le score minimum
+--min-score 40
+
+# 2. Augmenter les tentatives
+--max-attempts 5000
+
+# 3. Activer les transformations
+--remove-letters 2 --add-vowels 1
+```
+
+### Performance lente
+```bash
+# Solutions :
+# 1. Compiler en mode release
+cargo build --release
+
+# 2. Utiliser le mode streaming pour grandes quantités
+--streaming
+
+# 3. Utiliser des batches plus petits
+--batch-size 50000
+```
+
+### Mémoire insuffisante
+```bash
+# Solutions :
+# 1. Utiliser le mode streaming
+--streaming
+
+# 2. Réduire la taille des batches
+--batch-size 10000
+
+# 3. Rediriger vers fichier au lieu de garder en mémoire
+> output.txt
+```