genetic_algorithms 2.2.0

Library for solving genetic algorithm problems
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123

//! Metrics-facade observer that records per-generation gauges, operator timing
//! histograms, and event counters via the [`metrics`] crate.
//!
//! Enabled only when the `observer-metrics` feature flag is active.
//! When no metrics recorder is installed, all macro calls are zero-cost no-ops.
//!
//! # Metric Catalog
//!
//! | Metric | Kind | Hook |
//! |--------|------|------|
//! | `ga.generation.best_fitness` | gauge | `on_generation_end` |
//! | `ga.generation.mean_fitness` | gauge | `on_generation_end` |
//! | `ga.generation.diversity` | gauge | `on_generation_end` |
//! | `ga.operator.selection_ms` | histogram | `on_selection_complete` |
//! | `ga.operator.crossover_ms` | histogram | `on_crossover_complete` |
//! | `ga.operator.mutation_ms` | histogram | `on_mutation_complete` |
//! | `ga.operator.fitness_eval_ms` | histogram | `on_fitness_evaluation_complete` |
//! | `ga.operator.survivor_ms` | histogram | `on_survivor_selection_complete` |
//! | `ga.event.new_best` | counter | `on_new_best` |
//! | `ga.event.stagnation` | counter | `on_stagnation` |
//! | `ga.event.extension_triggered` | counter | `on_extension_triggered` |
//!
//! # Usage
//!
//! ```ignore
//! use std::sync::Arc;
//! use genetic_algorithms::MetricsObserver;
//!
//! let mut ga = Ga::new()
//!     // ... configuration ...
//!     .with_observer(Arc::new(MetricsObserver::new("experiment_42")))
//!     .build()
//!     .unwrap();
//! ```

use std::time::Duration;
use crate::observer::{ExtensionEvent, GaObserver, IslandGaObserver, Nsga2Observer};
use crate::stats::GenerationStats;
use crate::traits::ChromosomeT;

/// Observer that records per-generation metrics via the [`metrics`] facade crate.
///
/// Construct with [`MetricsObserver::new`], passing a static string `run_id`
/// label that will be attached to every metric as a label/tag — used to
/// disambiguate runs in shared dashboards.
///
/// The `metrics` recorder (e.g., `metrics-exporter-prometheus`) is the user's
/// responsibility. When no recorder is installed, all metric calls are
/// zero-cost no-ops (noop recorder installed by default).
pub struct MetricsObserver {
    run_id: &'static str,
}

impl MetricsObserver {
    /// Create a new `MetricsObserver`.
    ///
    /// `run_id` is attached as a label to every emitted metric.
    /// Use a descriptive static string such as `"experiment_42"` or `"production_run"`.
    pub fn new(run_id: &'static str) -> Self {
        Self { run_id }
    }

    /// Returns the run_id this observer was constructed with.
    pub fn run_id(&self) -> &'static str {
        self.run_id
    }
}

impl Default for MetricsObserver {
    fn default() -> Self {
        Self::new("default")
    }
}

impl<U: ChromosomeT> GaObserver<U> for MetricsObserver {
    fn on_selection_complete(&self, _generation: usize, duration: Duration, _population_size: usize) {
        metrics::histogram!("ga.operator.selection_ms", "run_id" => self.run_id)
            .record(duration.as_secs_f64() * 1000.0);
    }

    fn on_crossover_complete(&self, _generation: usize, duration: Duration, _offspring_count: usize) {
        metrics::histogram!("ga.operator.crossover_ms", "run_id" => self.run_id)
            .record(duration.as_secs_f64() * 1000.0);
    }

    fn on_mutation_complete(&self, _generation: usize, duration: Duration, _population_size: usize) {
        metrics::histogram!("ga.operator.mutation_ms", "run_id" => self.run_id)
            .record(duration.as_secs_f64() * 1000.0);
    }

    fn on_fitness_evaluation_complete(&self, _generation: usize, duration: Duration, _population_size: usize) {
        metrics::histogram!("ga.operator.fitness_eval_ms", "run_id" => self.run_id)
            .record(duration.as_secs_f64() * 1000.0);
    }

    fn on_survivor_selection_complete(&self, _generation: usize, duration: Duration, _population_size: usize) {
        metrics::histogram!("ga.operator.survivor_ms", "run_id" => self.run_id)
            .record(duration.as_secs_f64() * 1000.0);
    }

    fn on_new_best(&self, _generation: usize, _best: U) {
        metrics::counter!("ga.event.new_best", "run_id" => self.run_id).increment(1);
    }

    fn on_stagnation(&self, _generation: usize, _stagnation_count: usize) {
        metrics::counter!("ga.event.stagnation", "run_id" => self.run_id).increment(1);
    }

    fn on_extension_triggered(&self, _event: ExtensionEvent) {
        metrics::counter!("ga.event.extension_triggered", "run_id" => self.run_id).increment(1);
    }

    fn on_generation_end(&self, stats: &GenerationStats) {
        metrics::gauge!("ga.generation.best_fitness", "run_id" => self.run_id).set(stats.best_fitness);
        metrics::gauge!("ga.generation.mean_fitness", "run_id" => self.run_id).set(stats.avg_fitness);
        metrics::gauge!("ga.generation.diversity", "run_id" => self.run_id).set(stats.diversity);
    }
}

impl<U: ChromosomeT> IslandGaObserver<U> for MetricsObserver {}

impl<U: ChromosomeT> Nsga2Observer<U> for MetricsObserver {}