anagram-generator/docs/USAGE.md

Guide d'utilisation

Installation et compilation

# 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

# 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

# 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.

# 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.

# 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.

# 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é.

# 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é.

# 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).

# 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.

# 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

# 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

# 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

# Traiter chaque batch séparément
cargo run --release -- \
  --word "computer" \
  --count 50000000 \
  --batch-size 1000000 \
  --progress \
  | split -l 1000000 - batch_

Comparaison de performance

# 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

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

cargo run --release -- --word "test" --count 100 --min-score 60

Pour génération quotidienne

cargo run --release -- --word "myword" --count 10000 --streaming --progress

Pour génération massive

cargo run --release -- \
  --word "myword" \
  --count 100000000 \
  --batch-size 1000000 \
  --progress \
  --min-score 50 \
  > output.txt 2> progress.log

Pour mots difficiles

cargo run --release -- \
  --word "difficultword" \
  --count 1000 \
  --remove-letters 2 \
  --add-vowels 1 \
  --max-attempts 5000 \
  --min-score 65

Aide complète

# Afficher toutes les options
cargo run --release -- --help

Dépannage

Peu d'anagrammes générés

# 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

# 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

# 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