Merge pull request #176 from mahf-opt/update-problems

Integrate problem changes from PR draft #173

Cargo.toml

@@ -1,40 +1,34 @@
 [package]
-authors = ["Leopold Luley <git@leopoldluley.de>"]
-edition = "2021"
 name = "mahf"
 version = "0.1.0"
+authors = ["Leopold Luley <git@leopoldluley.de>", "Helena Stegherr <helena.stegherr@uni-a.de>", "Jonathan Wurth <jonathan.wurth@uni-a.de>"]
+edition = "2021"
 description = "A framework for modular construction and evaluation of metaheuristics."
+readme = "README.md"
 license = "GPL-3.0-or-later"
 repository = "https://github.com/mahf-opt/mahf"
 keywords = ["heuristic", "metaheuristic", "optimization"]
 categories = ["science", "algorithms"]
 
 [dependencies]
-anyhow = "1.0.51"
-ciborium = "0.2.0"
-coco-rs = "0.6"
-derive_more = { version = "0.99.17", features = ["deref", "deref_mut"]}
-embed-doc-image = "0.1.4"
-erased-serde = "0.3.16"
-float_eq = "0.7.0"
-num_cpus = "1.13.0"
-pest = "2.1.3"
-pest_consume = "1.1.1"
-pest_derive = "2.1.0"
-rand = "0.8.4"
-rand_distr = "0.4.2"
-ron = "0.7.0"
-rprompt = "1.0.5"
-serde = {version = "1.0.131", features = ["derive"]}
+better_any = { version = "0.2.0", features = ["derive"] }
+thiserror = "1.0.40"
+eyre = "0.6.8"
+color-eyre = "0.6.2"
 trait-set = "0.3.0"
-dyn-clone = "1.0.9"
+serde = { version = "1.0.160", features = ["derive"] }
+erased-serde = "0.3.25"
+derive_more = { version = "0.99.17", features = ["deref", "deref_mut", "add", "mul", "not"] }
+rand = "0.8.5"
+rand_distr = "0.4.3"
+dyn-clone = "1.0.11"
 derivative = "2.2.0"
+ciborium = "0.2.0"
+serde_json = "1.0.96"
+rayon = "1.7.0"
+test-case = "3.1.0"
+float_eq = "1.0.1"
+contracts = "0.6.3"
 itertools = "0.10.5"
-better_any = { version = "0.2.0", features = ["derive"] }
-scoped_threadpool = "0.1.9"
-
-[dev-dependencies]
-proptest = "1.0.0"
-
-[build-dependencies]
-cc = "1.0.72"
+ron = "0.8.0"
+indicatif = { version = "0.17.4", features = ["rayon"] }

README.md

@@ -1,10 +1,11 @@
 # MAHF
 
-A framework for modular construction and evaluation of meta-heuristics.
+A framework for modular construction and evaluation of metaheuristics.
 
 # Purpose and Features
 
-MAHF aims to make construction and modification of metaheuristics as simple and reliable as possible. In addition to construction it also provides utilities for tracking, evaluation and comparison of those heuristics.
+MAHF aims to make construction and modification of metaheuristics as simple and reliable as possible. In addition to
+construction it also provides utilities for tracking, evaluation and comparison of those heuristics.
 
 - Simple modular construction of metaheuristics
 - State management and state tracking
@@ -32,21 +33,42 @@ MAHF aims to make construction and modification of metaheuristics as simple and
 MAHF has extensive documentation which should make it easy to get started.
 
 Just run
+
 ```sh
 $ cargo doc --open
 ```
+
 to build and open the documentation.
 
 # Examples
 
 Examples on how to use MAHF for evaluation can be found in the [examples](examples) directory.
 
-Examples of heuristics can be found under [heuristics](src/heuristics) and components under [components](src/components).
+Examples of heuristics can be found under [heuristics](src/heuristics) and components
+under [components](src/components).
 
 # Additional Resources
 
 None yet.
 
-# Papers and Projects using MAHF
+# Publications
 
-None yet.
+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},
+}
+```

examples/sphere.rs

@@ -0,0 +1,81 @@
+use mahf::prelude::*;
+use mahf::problems::KnownOptimumProblem;
+use mahf::SingleObjective;
+use std::ops::Range;
+
+pub struct Sphere {
+    pub dim: usize,
+}
+
+impl Sphere {
+    pub fn new(dim: usize) -> Self {
+        Self { dim }
+    }
+}
+
+impl problems::Problem for Sphere {
+    type Encoding = Vec<f64>;
+    type Objective = SingleObjective;
+
+    fn name(&self) -> &str {
+        "Sphere"
+    }
+}
+
+impl problems::VectorProblem for Sphere {
+    type Element = f64;
+
+    fn dimension(&self) -> usize {
+        self.dim
+    }
+}
+
+impl problems::LimitedVectorProblem for Sphere {
+    fn domain(&self) -> Vec<Range<Self::Element>> {
+        std::iter::repeat(-1.0..1.0).take(self.dim).collect()
+    }
+}
+
+impl problems::ObjectiveFunction for Sphere {
+    fn objective(solution: &Self::Encoding) -> Self::Objective {
+        solution
+            .iter()
+            .map(|x| x.powi(2))
+            .sum::<f64>()
+            .try_into()
+            .unwrap()
+    }
+}
+
+impl KnownOptimumProblem for Sphere {
+    fn known_optimum(&self) -> SingleObjective {
+        0.0.try_into().unwrap()
+    }
+}
+
+fn main() {
+    // Specify the problem: Sphere function with 10 dimensions.
+    let problem: Sphere = Sphere::new(/*dim: */ 10);
+    // Specify the metaheuristic: Particle Swarm Optimization (pre-implemented in MAHF).
+    let config: Configuration<Sphere> = pso::real_pso(
+        /*params: */
+        pso::RealProblemParameters {
+            num_particles: 20,
+            weight: 1.0,
+            c_one: 1.0,
+            c_two: 1.0,
+            v_max: 1.0,
+        },
+        /*termination: */
+        termination::FixedIterations::new(/*max_iterations: */ 500)
+            & termination::DistanceToOpt::new(0.01),
+    );
+
+    // Execute the metaheuristic on the problem with a random seed.
+    let state: State<Sphere> = config.optimize(&problem);
+
+    // Print the results.
+    println!("Found Individual: {:?}", state.best_individual().unwrap());
+    println!("This took {} iterations.", state.iterations());
+    println!("Global Optimum: {:?}", problem.known_optimum());
+}