Refactor algorithm macro to generate pub type aliases for algorithms (#262)

Author: andresliszt

README.md

@@ -106,7 +106,7 @@ fn main() -> Result<(), AlgorithmError> {
         .build()?;
 
     algorithm.run()?;
-    let population = algorithm.population()?;
+    let population = algorithm.population?;
     println!("Done! Population size: {}", population.len());
 
     Ok(())

moors/README.md

@@ -77,7 +77,7 @@ fn main() -> Result<(), AlgorithmError> {
         .build()?;
 
     algorithm.run()?;
-    let population = algorithm.population()?;
+    let population = algorithm.population?;
     println!("Done! Population size: {}", population.len());
 
     Ok(())

moors/benches/dtlz2.rs

@@ -7,8 +7,8 @@ use ndarray::{Array2, Axis, stack};
 
 use moors::{
     CloseDuplicatesCleaner, DanAndDenisReferencePoints, GaussianMutation, Nsga3Builder,
-    Nsga3ReferencePoints, Nsga3ReferencePointsSurvival, RandomSamplingFloat,
-    SimulatedBinaryCrossover, StructuredReferencePoints, impl_constraints_fn,
+    Nsga3ReferencePointsSurvival, RandomSamplingFloat, SimulatedBinaryCrossover,
+    StructuredReferencePoints, impl_constraints_fn,
 };
 
 /// DTLZ2 for 3 objectives (m = 3) with k = 0 (so num_vars = m−1 = 2):
@@ -34,8 +34,7 @@ fn fitness_dtlz2_3obj(pop: &Array2<f64>) -> Array2<f64> {
 
 fn bench_nsga3_dtlz2(c: &mut Criterion) {
     // 1) prepare 3-objective reference points once
-    let base_rp = DanAndDenisReferencePoints::new(1000, 3).generate();
-    let nsga3_rp = Nsga3ReferencePoints::new(base_rp, false);
+    let rp = DanAndDenisReferencePoints::new(1000, 3).generate();
     impl_constraints_fn!(MyConstr, lower_bound = 0.0, upper_bound = 1.0);
 
     c.bench_function("nsga3_dtlz2_3obj", |b| {
@@ -45,7 +44,8 @@ fn bench_nsga3_dtlz2(c: &mut Criterion) {
                 .sampler(RandomSamplingFloat::new(0.0, 1.0))
                 .crossover(SimulatedBinaryCrossover::new(20.0))
                 .mutation(GaussianMutation::new(0.05, 0.1))
-                .survivor(Nsga3ReferencePointsSurvival::new(nsga3_rp.clone()))
+                .reference_points(rp.clone())
+                .are_aspirational(false)
                 .duplicates_cleaner(CloseDuplicatesCleaner::new(1e-6))
                 .fitness_fn(fitness_dtlz2_3obj)
                 .constraints_fn(MyConstr)
@@ -63,7 +63,7 @@ fn bench_nsga3_dtlz2(c: &mut Criterion) {
 
             algorithm.run().expect("NSGA3 run failed");
             // prevent optimizer from eliding the result
-            black_box(algorithm.population().expect("Population getter failed"));
+            black_box(algorithm.population.expect("Population getter failed"));
         })
     });
 }

moors/benches/zdt1.rs

@@ -48,7 +48,7 @@ fn bench_nsga2_zdt1(c: &mut Criterion) {
 
             algorithm.run().expect("NSGA2 run failed");
             // prevent the optimizer from eliding the result
-            black_box(algorithm.population().expect("Population getter failed"));
+            black_box(algorithm.population.expect("Population getter failed"));
         })
     });
 }

moors/src/algorithms/builder.rs

@@ -89,6 +89,7 @@ pub struct GeneticAlgorithmParams<
     num_vars: usize,
     population_size: usize,
     num_offsprings: usize,
+    #[builder(field(vis = "pub"))]
     num_iterations: usize,
     #[builder(default = "0.2")]
     mutation_rate: f64,

moors/src/algorithms/macros.rs

@@ -1,8 +1,9 @@
 use crate::{
-    create_algorithm, selection::moo::RankAndScoringSelection, survival::moo::AgeMoeaSurvival,
+    define_algorithm_and_builder, selection::moo::AgeMoeaRankCrowdingSelection,
+    survival::moo::AgeMoeaSurvival,
 };
 
-create_algorithm!(
+define_algorithm_and_builder!(
     /// AGE-MOEA algorithm wrapper.
     ///
     /// This struct is a thin facade over [`GeneticAlgorithm`] preset with
@@ -23,36 +24,6 @@ create_algorithm!(
     /// pp. 595–603, July 2019.
     /// DOI: 10.1145/3321707.3321839
     AgeMoea,
-    RankAndScoringSelection,
+    AgeMoeaRankCrowdingSelection,
     AgeMoeaSurvival
 );
-
-impl<S, Cross, Mut, F, G, DC> Default for AgeMoeaBuilder<S, Cross, Mut, F, G, DC>
-where
-    S: SamplingOperator,
-    Cross: CrossoverOperator,
-    Mut: MutationOperator,
-    F: FitnessFn<Dim = ndarray::Ix2>,
-    G: ConstraintsFn,
-    DC: PopulationCleaner,
-    AlgorithmBuilder<S, RankAndScoringSelection, AgeMoeaSurvival, Cross, Mut, F, G, DC>: Default,
-{
-    fn default() -> Self {
-        let mut inner: AlgorithmBuilder<
-            S,
-            RankAndScoringSelection,
-            AgeMoeaSurvival,
-            Cross,
-            Mut,
-            F,
-            G,
-            DC,
-        > = Default::default();
-        inner = inner
-            .selector(RankAndScoringSelection::default())
-            .survivor(AgeMoeaSurvival);
-        AgeMoeaBuilder {
-            inner_builder: inner,
-        }
-    }
-}

moors/src/algorithms/moo/agemoea.rs

@@ -17,13 +17,16 @@
 //!
 //! The default configuration keeps a single population (no external archive).
 
+use ndarray::Array1;
+
 use crate::{
-    create_algorithm,
-    selection::moo::RankAndScoringSelection,
-    survival::moo::{IbeaHyperVolumeSurvivalOperator, SurvivalScoringComparison},
+    define_algorithm_and_builder,
+    operators::{
+        selection::moo::IbeaScoringSelection, survival::moo::IbeaHyperVolumeSurvivalOperator,
+    },
 };
 
-create_algorithm!(
+define_algorithm_and_builder!(
     /// IBEA algorithm wrapper.
     ///
     /// Thin façade over [`GeneticAlgorithm`] preset with IBEA’s selection/survival strategy.
@@ -39,48 +42,7 @@ create_algorithm!(
     /// Zitzler & Künzli (2004), *Indicator-Based Evolutionary Algorithm for Multiobjective Optimization*,
     /// EMO 2004, LNCS 3248, Springer.
     Ibea,
-    RankAndScoringSelection,
-    IbeaHyperVolumeSurvivalOperator
+    IbeaScoringSelection,
+    IbeaHyperVolumeSurvivalOperator,
+    survival_args = [reference: Array1<f64>, kappa: f64],
 );
-
-impl<S, Cross, Mut, F, G, DC> Default for IbeaBuilder<S, Cross, Mut, F, G, DC>
-where
-    S: SamplingOperator,
-    Cross: CrossoverOperator,
-    Mut: MutationOperator,
-    F: FitnessFn<Dim = ndarray::Ix2>,
-    G: ConstraintsFn,
-    DC: PopulationCleaner,
-    AlgorithmBuilder<
-        S,
-        RankAndScoringSelection,
-        IbeaHyperVolumeSurvivalOperator,
-        Cross,
-        Mut,
-        F,
-        G,
-        DC,
-    >: Default,
-{
-    fn default() -> Self {
-        let mut inner: AlgorithmBuilder<
-            S,
-            RankAndScoringSelection,
-            IbeaHyperVolumeSurvivalOperator,
-            Cross,
-            Mut,
-            F,
-            G,
-            DC,
-        > = Default::default();
-
-        // Selector operator uses scoring survival given by the raw fitness but it doesn't use rank
-        let selector =
-            RankAndScoringSelection::new(false, true, SurvivalScoringComparison::Maximize);
-
-        inner = inner.selector(selector);
-        IbeaBuilder {
-            inner_builder: inner,
-        }
-    }
-}

moors/src/algorithms/moo/ibea.rs

@@ -54,36 +54,10 @@
 //!         .build()?;               // ← macro‑generated .build()
 //!
 //!     algorithm.run()?;
-//!     println!("Done – final pop: {}", algorithm.population()?.len());
+//!     println!("Done – final pop: {}", algorithm.population?.len());
 //!     Ok(())
 //! }
 //! ```
-//!
-//! ### Writing your **own** algorithm
-//!
-//! 1. **Pick / implement** a [`SelectionOperator`] and a [`SurvivalOperator`].
-//! 2. Use them with helper macro `create_algorithm!`:
-//!
-//!    ```rust, ignore
-//!    create_algorithm!(MyNewAlgorithm, NewSelector, NewSurvival);
-//!    ```
-//!
-//! From there, a new algorithm struct will be created
-//! ```rust, ignore
-//!    pub struct MyAlgo<S, Cross, Mut, F, G, DC> {
-//!        inner: GeneticAlgorithm<S, NewSelector, NewSurvival, Cross, Mut, F, G, DC>
-//!    }
-//!    ```
-//! Also, the its respective builder is availble `MyAlgoBuilder`
-//!
-//! ## GeneticAlgorithm – generic core
-//!
-//! The struct [`GeneticAlgorithm`] is **not** intended to be used
-//! directly by most users; it’s the reusable engine that handles initial
-//! sampling, iterative evolution, evaluation and survivor selection.  Concrete
-//! algorithms customise its behaviour exclusively through trait objects, so
-//! they stay **zero‑cost abstractions** once monomorphised.
-
 //! ---
 //!
 //! *Evolution is a mystery*  Feel free to open an issue or PR if you implement a new

moors/src/algorithms/moo/mod.rs

@@ -21,11 +21,13 @@
 //! you need custom behaviour.
 
 use crate::{
-    create_algorithm, selection::moo::RankAndScoringSelection,
-    survival::moo::Nsga2RankCrowdingSurvival,
+    define_algorithm_and_builder,
+    operators::{
+        selection::moo::Nsga2RankAndScoringSelection, survival::moo::Nsga2RankCrowdingSurvival,
+    },
 };
 
-create_algorithm!(
+define_algorithm_and_builder!(
     /// NSGA-II algorithm wrapper.
     ///
     /// This struct is a thin facade over [`GeneticAlgorithm`] preset with
@@ -46,37 +48,6 @@ create_algorithm!(
     /// pp. 182–197, Apr. 2002.
     /// DOI: 10.1109/4235.996017
     Nsga2,
-    RankAndScoringSelection,
+    Nsga2RankAndScoringSelection,
     Nsga2RankCrowdingSurvival
 );
-
-impl<S, Cross, Mut, F, G, DC> Default for Nsga2Builder<S, Cross, Mut, F, G, DC>
-where
-    S: SamplingOperator,
-    Cross: CrossoverOperator,
-    Mut: MutationOperator,
-    F: FitnessFn<Dim = ndarray::Ix2>,
-    G: ConstraintsFn,
-    DC: PopulationCleaner,
-    AlgorithmBuilder<S, RankAndScoringSelection, Nsga2RankCrowdingSurvival, Cross, Mut, F, G, DC>:
-        Default,
-{
-    fn default() -> Self {
-        let mut inner: AlgorithmBuilder<
-            S,
-            RankAndScoringSelection,
-            Nsga2RankCrowdingSurvival,
-            Cross,
-            Mut,
-            F,
-            G,
-            DC,
-        > = Default::default();
-        inner = inner
-            .selector(RankAndScoringSelection::default())
-            .survivor(Nsga2RankCrowdingSurvival);
-        Nsga2Builder {
-            inner_builder: inner,
-        }
-    }
-}