frostfire 0.1.2

A modular, mathematically rigorous, performant, reusable simulated annealing optimization engine
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

//! Energy (cost function) representation for simulated annealing.
//!
//! The `Energy` trait defines the cost function to be minimized
//! during the simulated annealing process.

use crate::core::state::State;

/// The `Energy` trait defines the cost function to be minimized
/// during the simulated annealing process.
///
/// In simulated annealing, we seek to find a state that minimizes
/// the energy (cost) function. This trait associates a numerical
/// value with each state, allowing the annealer to compare different
/// states and guide the optimization process.
///
/// # Examples
///
/// ```
/// use frostfire::prelude::*;
///
/// #[derive(Clone)]
/// struct VectorState(Vec<f64>);
///
/// impl State for VectorState {
///     // Implementation omitted for brevity
///     # fn neighbor(&self, rng: &mut impl rand::Rng) -> Self { self.clone() }
/// }
///
/// struct QuadraticEnergy;
///
/// impl Energy for QuadraticEnergy {
///     type State = VectorState;
///
///     fn cost(&self, state: &Self::State) -> f64 {
///         // Simple quadratic function: sum of squares
///         state.0.iter().map(|x| x * x).sum()
///     }
/// }
/// ```
pub trait Energy {
    /// The type of state this energy function evaluates.
    type State: State;

    /// Calculates the cost (energy) of a given state.
    ///
    /// This function associates a numerical value with each state,
    /// which the annealer seeks to minimize.
    ///
    /// # Parameters
    ///
    /// * `state`: The state to evaluate
    ///
    /// # Returns
    ///
    /// The cost (energy) of the given state as a floating-point value.
    /// Lower values are considered better in the annealing process.
    fn cost(&self, state: &Self::State) -> f64;
}