Migrate core-midpoint-trapeze benchmark to new architecture

[ocots]

Contexte

Les étudiants ont réalisé un excellent travail dans la PR #116 pour comparer les méthodes de discrétisation midpoint vs trapeze avec les solveurs Ipopt et MadNLP sur ExaModels. Cependant, leur travail est basé sur l'ancienne architecture de documentation qui a depuis été refactorisée.

Cette issue vise à migrer leur travail vers la branche main en utilisant la nouvelle architecture basée sur le système de registre.

Objectif

Intégrer le benchmark core-midpoint-trapeze dans la documentation en :

• Préservant tous les résultats de benchmark des étudiants
• Adaptant le code à la nouvelle architecture (registre de profils, nouvelle syntaxe de templates)
• Maintenant la cohérence avec les autres benchmarks existants

Travail des étudiants à migrer

Depuis la branche 115-general-add-run-bench-core-midpoint-4-combos-exa :

✅ À copier tel quel (61 fichiers) :

• Script de benchmark : benchmarks/core-midpoint-trapeze.jl
• Résultats complets : docs/src/assets/benchmarks/core-midpoint-trapeze/ (60 fichiers : JSON, TOML, 28 SVG, 28 PDF)

⚙️ À réécrire avec nouvelle architecture :

• Ajout dans benchmarks/benchmarks-config.json
• Nouveau profil dans docs/src/docutils/Handlers/DefaultProfiles.jl
• Template docs/src/core/midpoint-trapeze.md.template (nouvelle syntaxe)
• Entrées dans docs/make.jl (processing + menu)

Plan d'implémentation

Phase 1 : Migration des fichiers

• Créer branche feature/core-midpoint-trapeze depuis main
• Copier script benchmark et résultats depuis branche étudiante
• Ajouter entrée dans benchmarks-config.json

Phase 2 : Intégration documentation

• Ajouter profil midpoint_trapeze_cpu dans DefaultProfiles.jl
• Créer template avec nouvelle syntaxe des blocs
• Mettre à jour docs/make.jl (processing + menu)

Phase 3 : Vérification

• Build documentation localement
• Vérifier génération des profils de performance
• Vérifier affichage des tableaux de résultats
• Valider navigation et rendu

Phase 4 : Finalisation

• Commit avec message descriptif
• Créer PR liée à cette issue
• Review et merge

Détails techniques

Profil de performance : Utilise [:disc_method, :solver] au lieu de [:model, :solver] pour comparer les 4 combinaisons :

1. (trapeze, ipopt)
2. (trapeze, madnlp)
3. (midpoint, ipopt)
4. (midpoint, madnlp)

Problèmes testés : 14 problèmes de contrôle optimal (beam, chain, double_oscillator, ducted_fan, electric_vehicle, glider, insurance, jackson, robbins, robot, rocket, space_shuttle, steering, vanderpol)

Configuration : Grid size 200, tolérance 1e-8, ExaModels uniquement

Références

• PR étudiante : test bench midpoint trapeze #116
• Issue originale : [General] add bench core-midpoint vs trapeze 4 combos-exa #115
• Documentation preview : https://control-toolbox.org/CTBenchmarks.jl/previews/PR116/
• Rapport de planification : reports/core_midpoint_trapeze_migration_planning.md

[ocots]

✅ Migration Complete

The migration of the core-midpoint-trapeze benchmark from the student branch to main has been completed successfully.

📦 What Was Done

Phase 1: File Migration (commit 8f3ec5b6)

• ✅ Benchmark script: benchmarks/core-midpoint-trapeze.jl
• ✅ Complete results: docs/src/assets/benchmarks/core-midpoint-trapeze/ (32 files)

Phase 2: Documentation Integration (commit a7e2bb2d)

• ✅ Performance profile midpoint_trapeze_cpu added to DefaultProfiles.jl
• ✅ Template docs/src/core/midpoint-trapeze.md.template with new syntax
• ✅ Configuration in benchmarks-config.json
• ✅ Menu entry in docs/make.jl

Phase 3: Bug Fixes and Refactoring (commits 3aa0818f, 29b517b9)

• ✅ Bug discovered: plotting code assumed [:model, :solver] columns only
• ✅ Fix: made generic to support [:disc_method, :solver] and any other combination
• ✅ Refactoring: extracted helper functions following SRP principle
• ✅ Tests: comprehensive suite of 31 tests to prevent regressions (test/test_plot_styling.jl)

Phase 4: Verification

• ✅ Tests: 105/105 passing (41 performance_profile + 33 internals + 31 plot_styling)
• ✅ Documentation: build successful, template processed without errors
• ✅ Profiles: correct plot generation

🔧 Technical Improvements

1. Genericity: Profile system now supports any number of solver columns (2, 3, or more)
2. Variadic functions: get_color() and get_marker_style() accept variable number of parameters
3. Design principles: Applied SRP, DRY, and Open/Closed principles
4. Regression tests: Prevents the discovered bug from happening again

📊 Benchmark Details

• 14 problems tested (beam, chain, double_oscillator, etc.)
• 4 combinations: (trapeze, ipopt), (trapeze, madnlp), (midpoint, ipopt), (midpoint, madnlp)
• Configuration: Grid size 200, tolerance 1e-8, ExaModels only

🔗 Branch and Commits

Branch: feature/core-midpoint-trapeze

Commits:

• 8f3ec5b6 - Phase 1: Migrate core-midpoint-trapeze benchmark files
• a7e2bb2d - Phase 2: Integrate midpoint-trapeze into documentation system
• 3aa0818f - Fix: Make performance profile plotting generic for any solver columns
• 29b517b9 - Refactor: Generic performance profile plotting + tests

📝 Next Steps

• PR review
• Merge to main
• Close student PR test bench midpoint trapeze #116 with reference
• Close issue [General] add bench core-midpoint vs trapeze 4 combos-exa #115

---

Student work preserved: All benchmark results from the students have been preserved and are now integrated into the current project architecture.

Closes #115
Related to #116

[ocots]

✅ Travail accompli - Standardisation de l'ordre des arguments (Phase 1)

En plus de la migration du benchmark core-midpoint-trapeze, nous avons identifié et résolu un bug important lié à l'ordre des arguments dans les handlers de documentation.

🐛 Problème identifié

Lors de la vérification de la documentation, nous avons découvert que certains tableaux de résultats affichaient "No results to display" au lieu des données de benchmark. La cause : une incohérence dans l'ordre des arguments passés à _print_benchmark_table_results.

Diagnostic :

• Les templates générés automatiquement passaient 2 arguments : (bench_id, problem)
• Les templates manuels passaient 1 argument : (bench_id)
• Le TextEngine injectait SRC_DIR comme argument supplémentaire
• Résultat : SRC_DIR était incorrectement interprété comme problem, causant des filtres vides

🔧 Solution appliquée : Dependency Inversion Principle (DIP)

Nous avons standardisé l'ordre des arguments pour tous les handlers critiques en suivant le principe d'inversion de dépendance :

Convention adoptée : func(injected_dependency, business_arg1, business_arg2, ...)

📝 Changements de code (Phase 1)

1. FigureEngine.jl

# Avant
return func(args..., extra_args...)

# Après  
return func(extra_args..., args...)

2. Figure handlers (3 fonctions)

• _plot_time_vs_grid_size(src_dir, problem, bench_id)
• _plot_time_vs_grid_size_bar(src_dir, problem, bench_id; max_bar_width)
• _plot_iterations_vs_cpu_time(src_dir, problem, bench_id)

Toutes les signatures ont été réordonnées pour mettre src_dir en premier, et les docstrings ont été mis à jour.

📚 Documentation mise à jour

• documentation_process.md : Signatures corrigées
• docutils_templates.md : Tutoriel et exemples mis à jour avec le principe DIP

✅ Vérification

• ✅ Tous les tests passent (105 tests)
• ✅ Documentation se construit sans erreurs
• ✅ Tous les tableaux de résultats affichent correctement les données
• ✅ Tous les plots se génèrent correctement
• ✅ Pas de warnings "No results to display"

📦 Commits

1. 125e1bc : "Fix: Phase 1 - Standardize argument order for figure handlers (DIP)"
2. fe0d6d7 : "Docs: Update handler signatures to reflect Phase 1 DIP changes"

🎯 Impact

Cette standardisation améliore :

• Cohérence : Tous les handlers suivent la même convention
• Maintenabilité : Plus facile de comprendre quels arguments sont injectés vs. fournis
• Fiabilité : Évite les bugs de confusion d'arguments
• Testabilité : Les dépendances sont explicites et peuvent être mockées facilement

---

Note : Une Phase 2 avait été envisagée pour standardiser également les handlers appelés directement dans les templates (@example blocks), mais elle a été abandonnée car elle introduisait trop de complexité sans bénéfice proportionnel. La Phase 1 résout le bug initial et améliore significativement la qualité du code pour les handlers critiques.