trellis-runner 0.2.0

Calculation runner
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

//! # Target value policy
//!
//! Terminates when a metric crosses a predefined target threshold.
//!
//! ## Behaviour
//!
//! - Monitors `Progress::Measure` values.
//! - If any value <= `target`, termination is triggered.
//!
//! ## Termination
//!
//! Returns [`Termination::Converged`] when target is reached.
//!
//! ## Notes
//!
//! This policy assumes minimisation semantics.
//! For maximisation problems, invert the metric externally.
use super::EnginePolicy;

use crate::{
    engine::{EngineAction, EngineContext, EventBatch},
    progress::Progress,
    Termination,
};

use num_traits::float::FloatCore;

pub struct TargetValuePolicy<F> {
    target: F,
    tolerance: F,
    window: Vec<F>,
    window_size: usize,
}

impl<F: FloatCore> TargetValuePolicy<F> {
    pub fn new(target: F, tolerance: F, window_size: usize) -> Self {
        Self {
            target,
            tolerance,
            window: Vec::with_capacity(window_size),
            window_size,
        }
    }
}

impl<F> EnginePolicy<F> for TargetValuePolicy<F>
where
    F: FloatCore,
{
    fn decide(&mut self, batch: &EventBatch<F>, _context: &EngineContext) -> EngineAction {
        for event in &batch.events {
            let value = match event {
                Progress::Measure(v) => *v,
                Progress::Report { measure, .. } => *measure,
                _ => continue,
            };

            // symmetric distance to target
            let dist = (value - self.target).abs();

            self.window.push(dist);

            if self.window.len() > self.window_size {
                self.window.remove(0);
            }
        }

        if self.window.len() < self.window_size {
            return EngineAction::Continue;
        }

        // mean absolute distance
        let mean = self.window.iter().copied().fold(F::zero(), |a, b| a + b)
            / F::from(self.window.len()).unwrap();

        // tolerance-based stopping condition
        if mean < self.tolerance {
            return EngineAction::Stop(Termination::Converged);
        }

        EngineAction::Continue
    }
}

#[cfg(test)]
mod test {
    use super::*;
    use crate::engine::EngineContext;
    use crate::progress::Progress;

    fn batch(v: f64) -> EventBatch<f64> {
        EventBatch::new().add(Progress::Measure(v))
    }

    #[test]
    fn target_reached_stops() {
        let mut p = TargetValuePolicy::new(1.0, 0.01, 5);

        let ctx = EngineContext::default();

        for _ in 0..5 {
            p.decide(&batch(1.0), &ctx);
        }

        let res = p.decide(&batch(1.0), &ctx);

        assert!(matches!(res, EngineAction::Stop(_)));
    }

    #[test]
    fn target_not_reached_continues() {
        let mut p = TargetValuePolicy::new(1.0, 0.01, 5);

        let ctx = EngineContext::default();

        let res = p.decide(&batch(2.0), &ctx);

        assert!(matches!(res, EngineAction::Continue));
    }
}