argmin/core/state/
mod.rs

1// Copyright 2018-2024 argmin developers
2//
3// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
4// http://apache.org/licenses/LICENSE-2.0> or the MIT license <LICENSE-MIT or
5// http://opensource.org/licenses/MIT>, at your option. This file may not be
6// copied, modified, or distributed except according to those terms.
7
8pub mod iterstate;
9pub mod linearprogramstate;
10pub mod populationstate;
11
12pub use iterstate::IterState;
13pub use linearprogramstate::LinearProgramState;
14pub use populationstate::PopulationState;
15
16use crate::core::{ArgminFloat, Problem, TerminationReason, TerminationStatus};
17use std::collections::HashMap;
18use web_time::Duration;
19
20/// Minimal interface which struct used for managing state in solvers have to implement.
21///
22/// These methods expose basic information about the state which is needed in
23/// [`Executor`](`crate::core::Executor`) and
24/// [`OptimizationResult`](`crate::core::OptimizationResult`) but can also be useful in
25/// [`observers`](`crate::core::observers`).
26///
27/// The struct implementing this trait should keep track of
28/// * the current parameter vector
29/// * the cost associated with the current parameter vector
30/// * the current best parameter vector
31/// * the cost associated with the current best parameter vector
32/// * the iteration number where the last best parameter vector was found
33/// * the target cost function value (If this value is reached, the optimization will be stopped).
34///   Set this to `Self::Float::NEG_INFINITY` if not relevant.
35/// * the current number of iterations
36/// * how often each function of the problem has been called
37/// * the time required since the beginning of the optimization until the current point in time
38/// * the status of optimization execution ([`TerminationStatus`])
39///
40/// Since the state in general changes for each iteration, "current" refers to the current
41/// iteration.
42///
43/// [`State::Param`] indicates the type of the parameter vector while [`State::Float`] indicates
44/// the precision of floating point operations. Any type implementing [`ArgminFloat`] can be used
45/// for this (so far f32 and f64).
46pub trait State {
47    /// Type of parameter vector
48    type Param;
49    /// Floating point precision (f32 or f64)
50    type Float: ArgminFloat;
51
52    /// Construct a new state
53    fn new() -> Self;
54
55    /// This method is called after each iteration and checks if the new parameter vector is better
56    /// than the previous one. If so, it will update the current best parameter vector and current
57    /// best cost function value.
58    ///
59    /// For methods where the cost function value is unknown, it is advised to assume that every
60    /// new parameter vector is better than the previous one.
61    fn update(&mut self);
62
63    /// Returns a reference to the current parameter vector
64    fn get_param(&self) -> Option<&Self::Param>;
65
66    /// Returns a reference to the current best parameter vector
67    fn get_best_param(&self) -> Option<&Self::Param>;
68
69    /// Returns maximum number of iterations that are to be performed
70    fn get_max_iters(&self) -> u64;
71
72    /// Increment the number of iterations by one
73    fn increment_iter(&mut self);
74
75    /// Returns current number of iterations
76    fn get_iter(&self) -> u64;
77
78    /// Returns current cost function value
79    fn get_cost(&self) -> Self::Float;
80
81    /// Returns best cost function value
82    fn get_best_cost(&self) -> Self::Float;
83
84    /// Returns target cost
85    fn get_target_cost(&self) -> Self::Float;
86
87    /// Set all function evaluation counts to the evaluation counts of another operator
88    /// wrapped in `Problem`.
89    fn func_counts<O>(&mut self, problem: &Problem<O>);
90
91    /// Returns current cost function evaluation count
92    fn get_func_counts(&self) -> &HashMap<String, u64>;
93
94    /// Set time required since the beginning of the optimization until the current iteration
95    fn time(&mut self, time: Option<Duration>) -> &mut Self;
96
97    /// Get time passed since the beginning of the optimization until the current iteration
98    fn get_time(&self) -> Option<Duration>;
99
100    /// Returns iteration number where the last best parameter vector was found
101    fn get_last_best_iter(&self) -> u64;
102
103    /// Returns whether the current parameter vector is also the best parameter vector found so
104    /// far.
105    fn is_best(&self) -> bool;
106
107    /// Sets the termination status to [`Terminated`](`TerminationStatus::Terminated`) with the given reason
108    #[must_use]
109    fn terminate_with(self, termination_reason: TerminationReason) -> Self;
110
111    /// Returns termination status.
112    fn get_termination_status(&self) -> &TerminationStatus;
113
114    /// Returns the termination reason if terminated, otherwise None.
115    fn get_termination_reason(&self) -> Option<&TerminationReason>;
116
117    /// Return whether the algorithm has terminated or not
118    fn terminated(&self) -> bool {
119        matches!(
120            self.get_termination_status(),
121            TerminationStatus::Terminated(_)
122        )
123    }
124}
argmin/core/state/mod.rs

argmin/core/state/
mod.rs
