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
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
//! A framework for the modular construction and evaluation of metaheuristics.
//!
//! MAHF allows easy construction and experimental analysis of metaheuristics by
//! decomposing them into their fundamental components.
//!
//! The framework supports not only evolutionary algorithms, but also any other
//! metaheuristic frameworks, including non-population-based,
//! constructive, and especially hybrid approaches.
//!
//! # Overview
//!
//! MAHF aims to make the construction and modification of metaheuristics as simple and reliable as possible.
//! It provides a comprehensive set of utilities for logging, evaluation, and comparison of these heuristics.
//!
//! Key features include:
//! - Simple and modular metaheuristic construction
//! - Effortless state management and tracking
//! - Ready-to-use collection of common operators
//! - Templates for popular metaheuristics
//! - Flexible logging of runtime information
//!
//! Although MAHF has been developed primarily as a research tool, it can be used to solve real-world problems.
//!
//! ## Example
//!
//! Defining a simple genetic algorithm for real-valued black-box optimization:
//!
//! ```
//! use mahf::prelude::*;
//!
//! # fn example<P: problems::SingleObjectiveProblem + problems::LimitedVectorProblem<Element = f64>>(
//! # population_size: u32,
//! # n: u32,
//! # num_selected: u32,
//! # size: u32,
//! # pc: f64,
//! # std_dev: f64,
//! # rm: f64,
//! # max_population_size: u32,
//! # ) -> Configuration<P> {
//! let ga = Configuration::builder()
//! .do_(initialization::RandomSpread::new(population_size))
//! .evaluate()
//! .update_best_individual()
//! .while_(conditions::LessThanN::iterations(n), |builder| {
//! builder
//! .do_(selection::Tournament::new(num_selected, size))
//! .do_(recombination::ArithmeticCrossover::new_insert_both(pc))
//! .do_(mutation::NormalMutation::new(std_dev, rm))
//! .do_(boundary::Saturation::new())
//! .evaluate()
//! .update_best_individual()
//! .do_(replacement::MuPlusLambda::new(max_population_size))
//! })
//! .build();
//! # ga
//! # }
//! ```
//!
//! # [`Component`]-based design
//!
//! MAHF is based on the concept of *unified metaheuristics*, which means that we interpret
//! metaheuristics to be composed of components and conditions that can be mixed and matched.
//! They are represented by the [`Component`] and [`Condition`] traits.
//!
//! Putting components together into a metaheuristic is as easy as writing pseudo-code thanks to
//! the [`Configuration::builder`], as you can see in the [example](crate#example).
//!
//!
//! # Runtime [`state`]
//!
//! Components can only realize complex functionality if they can communicate freely,
//! and the [`State`] offers a way to do it.
//! The [`State`] is a shared blackboard where components can insert, read, write, and remove
//! so-called [`CustomState`].
//!
//! # Optimization [`problems`]
//!
//! Optimization [`problems`] are represented by the [`Problem`] and [`Evaluate`] traits:
//! - [`Problem`] and subtraits offer a way to provide any problem-specific information to
//! components and allow them to be as generic as possible by only specifying the
//! minimal trait bounds they need to function
//! - [`Evaluate`] provides means of evaluating the objective function, e.g. in parallel
//!
//! Optimizing some problem is then as easy as calling [`Configuration::optimize`].
//!
//! [`Evaluate`]: problems::Evaluate
//!
//! # Meta[`heuristic`] templates
//!
//! [`heuristic`]: heuristics
//!
//! MAHF offers pre-built modular templates for a dozen of common meta[`heuristics`] as a starting point
//! for more complex hybrids.
//! Take a look at their implementation if you want to get a feel
//! for how different metaheuristics are represented in MAHF.
//!
//! # Citing MAHF
//!
//! If you use MAHF in a scientific publication, we would appreciate citations to the following paper:
//!
//! Helena Stegherr, Leopold Luley, Jonathan Wurth, Michael Heider, and Jörg Hähner. 2023. A framework for modular
//! construction and evaluation of metaheuristics. Fakultät für Angewandte
//! Informatik. <https://opus.bibliothek.uni-augsburg.de/opus4/103452>
//!
//! Bibtex entry:
//!
//! ```bibtex
//! @techreport{stegherr2023,
//! author = {Helena Stegherr and Leopold Luley and Jonathan Wurth and Michael Heider and J{\"o}rg H{\"a}hner},
//! title = {A framework for modular construction and evaluation of metaheuristics},
//! institution = {Fakult{\"a}t f{\"u}r Angewandte Informatik},
//! series = {Reports / Technische Berichte der Fakult{\"a}t f{\"u}r Angewandte Informatik der Universit{\"a}t Augsburg},
//! number = {2023-01},
//! pages = {25},
//! year = {2023},
//! }
//! ```
// TODO: #![warn(missing_docs)]
pub use derive_more;
pub use float_eq;
pub use rand;
pub use rand_distr;
pub use serde;
pub
pub use ExecResult;
pub use Component;
pub use Condition;
pub use Configuration;
pub use ;
pub use ;