Skip to main content

autoeq_optim/cli/
display.rs

1use super::super::optim::get_all_algorithms;
2use super::peq_model::PeqModel;
3use std::fmt::Write as _;
4use std::process;
5
6/// Render the algorithm list to a string (used by tests and by the CLI printer).
7pub fn render_algorithm_list() -> String {
8    let mut out = String::new();
9    let _ = writeln!(out, "Available Optimization Algorithms");
10    let _ = writeln!(out, "=================================\n");
11
12    let algorithms = get_all_algorithms();
13
14    // Group algorithms by library
15    let mut metaheuristics_algos = Vec::new();
16    let mut autoeq_algos = Vec::new();
17
18    for algo in &algorithms {
19        match algo.library {
20            "Metaheuristics" => metaheuristics_algos.push(algo),
21            "AutoEQ" => autoeq_algos.push(algo),
22            _ => {} // Skip unknown libraries
23        }
24    }
25
26    // Display Metaheuristics algorithms
27    if !metaheuristics_algos.is_empty() {
28        let _ = writeln!(out, "๐Ÿงฌ Metaheuristics Library Algorithms:");
29        let _ = writeln!(
30            out,
31            "   Nature-inspired global optimization (penalty-based constraints)\n"
32        );
33
34        for algo in metaheuristics_algos {
35            let _ = write!(out, "   - {:<20}", algo.name);
36            let description = match algo.name {
37                "mh:de" => " | Differential Evolution (robust, good convergence)",
38                "mh:pso" => " | Particle Swarm Optimization (fast exploration)",
39                "mh:rga" => " | Real-coded Genetic Algorithm (diverse search)",
40                "mh:tlbo" => " | Teaching-Learning-Based Optimization (parameter-free)",
41                "mh:firefly" => " | Firefly Algorithm (multi-modal problems)",
42                _ => "",
43            };
44            let _ = writeln!(out, "{}", description);
45        }
46        let _ = writeln!(out);
47    }
48
49    // Display AutoEQ algorithms
50    if !autoeq_algos.is_empty() {
51        let _ = writeln!(out, "๐ŸŽต AutoEQ Custom Algorithms:");
52        let _ = writeln!(
53            out,
54            "   Specialized algorithms developed for audio filter optimization\n"
55        );
56
57        for algo in autoeq_algos {
58            let _ = write!(out, "   - {:<20}", algo.name);
59            let _ = write!(out, " | Constraints: ");
60            if algo.supports_nonlinear_constraints {
61                let _ = write!(out, "โœ… Nonlinear");
62            } else {
63                let _ = write!(out, "โŒ Penalty-based");
64            }
65
66            let description = match algo.name {
67                "autoeq:cobyla" => " | Pure-Rust constrained local optimization",
68                "autoeq:isres" => " | Pure-Rust stochastic constrained global optimization",
69                "autoeq:cmaes" => " | Covariance Matrix Adaptation Evolution Strategy",
70                "autoeq:bo" => " | Gaussian-process Bayesian optimization",
71                "autoeq:nsga2" => " | NSGA-II multi-objective optimization",
72                "autoeq:nsga3" => " | NSGA-III many-objective optimization",
73                "autoeq:de" => " | Adaptive Differential Evolution with constraint handling",
74                _ => "",
75            };
76            let _ = writeln!(out, "{}", description);
77        }
78        let _ = writeln!(out);
79    }
80
81    let _ = writeln!(out, "Deprecated NLopt compatibility aliases:");
82    let _ = writeln!(
83        out,
84        "   nlopt:cobyla, nlopt:slsqp, nlopt:bobyqa, nlopt:neldermead, nlopt:sbplx"
85    );
86    let _ = writeln!(out, "      โ†’ autoeq:cobyla");
87    let _ = writeln!(out, "   nlopt:isres, nlopt:ags, nlopt:origdirect");
88    let _ = writeln!(out, "      โ†’ autoeq:isres");
89    let _ = writeln!(
90        out,
91        "   nlopt:crs2lm, nlopt:direct, nlopt:directl, nlopt:gmlsl,"
92    );
93    let _ = writeln!(out, "   nlopt:gmlsllds, nlopt:stogo, nlopt:stogorand");
94    let _ = writeln!(out, "      โ†’ autoeq:de");
95    let _ = writeln!(
96        out,
97        "   These names are migration aliases, not separate available backends.\n"
98    );
99
100    let _ = writeln!(out, "Usage Examples:");
101    let _ = writeln!(out, "==============\n");
102    let _ = writeln!(out, "  # Use ISRES (recommended global optimizer):");
103    let _ = writeln!(out, "  autoeq --algo autoeq:isres --curve input.csv\n");
104    let _ = writeln!(out, "  # Use COBYLA (fast local optimizer):");
105    let _ = writeln!(out, "  autoeq --algo autoeq:cobyla --curve input.csv\n");
106    let _ = writeln!(out, "  # Use Differential Evolution from metaheuristics:");
107    let _ = writeln!(out, "  autoeq --algo mh:de --curve input.csv\n");
108    let _ = writeln!(
109        out,
110        "  # Short compatibility alias (maps to autoeq:cobyla):"
111    );
112    let _ = writeln!(out, "  autoeq --algo cobyla --curve input.csv\n");
113
114    let _ = writeln!(out, "Recommendations:");
115    let _ = writeln!(out, "===============\n");
116    let _ = writeln!(
117        out,
118        "  ๐ŸŽฏ For best results: autoeq:isres (global) + --refine with autoeq:cobyla (local)"
119    );
120    let _ = writeln!(
121        out,
122        "  โšก For speed: autoeq:cobyla (if you have a good initial guess)"
123    );
124    let _ = writeln!(
125        out,
126        "  ๐Ÿงช For experimentation: mh:de or mh:pso from metaheuristics library"
127    );
128    let _ = writeln!(
129        out,
130        "  โš–๏ธ  For constrained problems: Prefer algorithms with โœ… Nonlinear constraint support"
131    );
132
133    out
134}
135
136/// Display available optimization algorithms with descriptions and exit
137pub fn display_algorithm_list() -> ! {
138    print!("{}", render_algorithm_list());
139    process::exit(0);
140}
141
142/// Render the DE strategy list to a string.
143pub fn render_strategy_list() -> String {
144    let mut out = String::new();
145    let _ = writeln!(out, "Available Differential Evolution (DE) Strategies");
146    let _ = writeln!(out, "===============================================\n");
147
148    let strategies = [
149        (
150            "best1bin",
151            "Best1Bin",
152            "Use best individual + 1 random difference (binomial crossover)",
153            "Global exploration with fast convergence",
154        ),
155        (
156            "best1exp",
157            "Best1Exp",
158            "Use best individual + 1 random difference (exponential crossover)",
159            "Similar to best1bin with different crossover",
160        ),
161        (
162            "rand1bin",
163            "Rand1Bin",
164            "Use random individual + 1 random difference (binomial crossover)",
165            "Good diversity, slower convergence",
166        ),
167        (
168            "rand1exp",
169            "Rand1Exp",
170            "Use random individual + 1 random difference (exponential crossover)",
171            "Similar to rand1bin with different crossover",
172        ),
173        (
174            "rand2bin",
175            "Rand2Bin",
176            "Use random individual + 2 random differences (binomial crossover)",
177            "High exploration, may be slower",
178        ),
179        (
180            "rand2exp",
181            "Rand2Exp",
182            "Use random individual + 2 random differences (exponential crossover)",
183            "Similar to rand2bin with different crossover",
184        ),
185        (
186            "currenttobest1bin",
187            "CurrentToBest1Bin",
188            "Blend current with best + random difference (binomial)",
189            "Balanced exploration/exploitation (recommended)",
190        ),
191        (
192            "currenttobest1exp",
193            "CurrentToBest1Exp",
194            "Blend current with best + random difference (exponential)",
195            "Similar to currenttobest1bin",
196        ),
197        (
198            "best2bin",
199            "Best2Bin",
200            "Use best individual + 2 random differences (binomial crossover)",
201            "Fast convergence, may get trapped locally",
202        ),
203        (
204            "best2exp",
205            "Best2Exp",
206            "Use best individual + 2 random differences (exponential crossover)",
207            "Similar to best2bin",
208        ),
209        (
210            "randtobest1bin",
211            "RandToBest1Bin",
212            "Blend random with best + random difference (binomial)",
213            "Good balance of diversity and convergence",
214        ),
215        (
216            "randtobest1exp",
217            "RandToBest1Exp",
218            "Blend random with best + random difference (exponential)",
219            "Similar to randtobest1bin",
220        ),
221        (
222            "adaptivebin",
223            "AdaptiveBin",
224            "Self-adaptive mutation with top-w% selection (binomial)",
225            "Advanced adaptive strategy (experimental)",
226        ),
227        (
228            "adaptiveexp",
229            "AdaptiveExp",
230            "Self-adaptive mutation with top-w% selection (exponential)",
231            "Advanced adaptive strategy (experimental)",
232        ),
233    ];
234
235    let _ = writeln!(out, "๐ŸŽฏ Classic DE Strategies (well-tested, reliable):");
236    for &(name, _enum_name, description, recommendation) in strategies.iter().take(12) {
237        if name.starts_with("adaptive") {
238            continue;
239        }
240        let _ = writeln!(out, "   - {:<20} | {}", name, description);
241        let _ = writeln!(out, "     {:<20} | ๐Ÿ’ก {}", "", recommendation);
242        if name == "currenttobest1bin" {
243            let _ = writeln!(out, "     {:<20} | โญ Recommended default strategy", "");
244        }
245        let _ = writeln!(out);
246    }
247
248    let _ = writeln!(
249        out,
250        "๐Ÿงฌ Adaptive DE Strategies (experimental, research-based):"
251    );
252    for &(name, _enum_name, description, recommendation) in strategies.iter() {
253        if !name.starts_with("adaptive") {
254            continue;
255        }
256        let _ = writeln!(out, "   - {:<20} | {}", name, description);
257        let _ = writeln!(out, "     {:<20} | ๐Ÿ’ก {}", "", recommendation);
258        let _ = writeln!(
259            out,
260            "     {:<20} | ๐Ÿ”ง Requires --adaptive-weight-f and --adaptive-weight-cr",
261            ""
262        );
263        let _ = writeln!(out);
264    }
265
266    let _ = writeln!(out, "Strategy Naming Conventions:");
267    let _ = writeln!(out, "==========================\n");
268    let _ = writeln!(
269        out,
270        "  โ€ข 'bin' = Binomial (uniform) crossover - each gene has equal probability"
271    );
272    let _ = writeln!(
273        out,
274        "  โ€ข 'exp' = Exponential crossover - contiguous segments are more likely"
275    );
276    let _ = writeln!(
277        out,
278        "  โ€ข Numbers (1, 2) indicate how many difference vectors are used\n"
279    );
280
281    let _ = writeln!(out, "Usage Examples:");
282    let _ = writeln!(out, "==============\n");
283    let _ = writeln!(out, "  # Use recommended default strategy:");
284    let _ = writeln!(
285        out,
286        "  autoeq --algo autoeq:de --strategy currenttobest1bin --curve input.csv\n"
287    );
288    let _ = writeln!(out, "  # Use adaptive strategy with custom weights:");
289    let _ = writeln!(
290        out,
291        "  autoeq --algo autoeq:de --strategy adaptivebin --adaptive-weight-f 0.8 --adaptive-weight-cr 0.7\n"
292    );
293    let _ = writeln!(out, "  # Use classic exploration strategy:");
294    let _ = writeln!(
295        out,
296        "  autoeq --algo autoeq:de --strategy rand1bin --curve input.csv\n"
297    );
298
299    let _ = writeln!(out, "Recommendations:");
300    let _ = writeln!(out, "===============\n");
301    let _ = writeln!(
302        out,
303        "  โญ For general use: currenttobest1bin (good balance of exploration and exploitation)"
304    );
305    let _ = writeln!(
306        out,
307        "  ๐Ÿš€ For fast convergence: best1bin or best2bin (may get trapped in local optima)"
308    );
309    let _ = writeln!(
310        out,
311        "  ๐ŸŒ For thorough exploration: rand1bin or rand2bin (slower but more robust)"
312    );
313    let _ = writeln!(
314        out,
315        "  ๐Ÿงช For research/experimentation: adaptivebin or adaptiveexp (requires parameter tuning)"
316    );
317
318    out
319}
320
321/// Display available DE strategies with descriptions and exit
322pub fn display_strategy_list() -> ! {
323    print!("{}", render_strategy_list());
324    process::exit(0);
325}
326
327/// Render the PEQ model list to a string.
328pub fn render_peq_model_list() -> String {
329    let mut out = String::new();
330    let _ = writeln!(out, "Available PEQ Models");
331    let _ = writeln!(out, "===================");
332    let _ = writeln!(out);
333    let _ = writeln!(
334        out,
335        "The PEQ model defines the structure and constraints of the equalizer filters."
336    );
337    let _ = writeln!(out);
338
339    for model in PeqModel::all() {
340        let _ = writeln!(out, "  --peq-model {}", model);
341        let _ = writeln!(out, "    {}", model.description());
342        let _ = writeln!(out);
343    }
344
345    let _ = writeln!(out, "Examples:");
346    let _ = writeln!(
347        out,
348        "  autoeq --peq-model pk           # All peak filters (default)"
349    );
350    let _ = writeln!(out, "  autoeq --peq-model hp-pk        # Highpass + peaks");
351    let _ = writeln!(
352        out,
353        "  autoeq --peq-model hp-pk-lp     # Highpass + peaks + lowpass"
354    );
355
356    out
357}
358
359/// Display available PEQ models with descriptions and exit
360pub fn display_peq_model_list() -> ! {
361    print!("{}", render_peq_model_list());
362    process::exit(0);
363}
364
365#[cfg(test)]
366mod tests {
367    use super::*;
368
369    #[test]
370    fn render_algorithm_list_contains_headers_and_known_algorithms() {
371        let s = render_algorithm_list();
372        assert!(s.contains("Available Optimization Algorithms"));
373        assert!(s.contains("autoeq:cobyla"));
374        assert!(s.contains("autoeq:isres"));
375        assert!(s.contains("autoeq:de"));
376        assert!(!s.contains("NLOPT Library Algorithms"));
377        assert!(s.contains("Deprecated NLopt compatibility aliases"));
378        assert!(s.contains("not separate available backends"));
379        assert!(s.contains("Usage Examples"));
380        assert!(s.contains("Recommendations"));
381    }
382
383    #[test]
384    fn render_strategy_list_contains_recommended_strategy() {
385        let s = render_strategy_list();
386        assert!(s.contains("Available Differential Evolution"));
387        assert!(s.contains("currenttobest1bin"));
388        assert!(s.contains("Recommended default strategy"));
389        assert!(s.contains("adaptivebin"));
390    }
391
392    #[test]
393    fn render_peq_model_list_contains_all_models() {
394        let s = render_peq_model_list();
395        assert!(s.contains("Available PEQ Models"));
396        for model in PeqModel::all() {
397            assert!(s.contains(&format!("--peq-model {}", model)));
398            assert!(s.contains(model.description()));
399        }
400    }
401}