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

// file: mod.rs
//
// Copyright 2015-2016 The RsGenetic Developers
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// 	http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

use pheno::Phenotype;

pub mod seq;
pub mod select;
mod iterlimit;
mod earlystopper;

/// A `Builder` can create new instances of an object.
/// For this library, only `Simulation` objects use this `Builder`.
pub trait Builder<T: ?Sized> {
    /// Return the result.
    fn build(self) -> T where T: Sized;
}

/// Simulation run time is defined in nanoseconds.
pub type NanoSecond = i64;
/// The result of a simulation, containing the best phenotype
/// or an error message.
pub type SimResult<T> = Result<T, String>;

/// The result of running a single step.
#[derive(PartialEq,Eq,Debug)]
pub enum StepResult {
    /// The step was successful, but the simulation has not finished.
    Success,
    /// The step was not successful.
    Failure,
    /// The step was successful and the simulation finished.
    Done,
}

/// The result of running an entire simulation.
#[derive(PartialEq,Eq,Debug)]
pub enum RunResult {
    /// An error occurred somewhere during simulation.
    Failure,
    /// The simulation finished without errors.
    Done,
}

/// A `Simulation` is an execution of a genetic algorithm.
pub trait Simulation<T: Phenotype> {
    /// A `Builder` is used to create instances of a `Simulation`.
    type B: Builder<Self>;

    /// Create a `Builder` to create an instance.
    fn builder() -> Self::B where Self: Sized;
    /// Run the simulation completely.
    fn run(&mut self) -> RunResult;
    /// Make one step in the simulation. This function returns a `StepResult`:
    ///
    /// * `StepResult::Success` when a step was successful, but the simulation is not done.
    /// * `StepResult::Failure` when an error occurred. Check the result of `get()`.
    /// * `StepResult::Done` on convergence or reaching the maximum iterations.
    ///
    /// Be careful to check for failures when running `step()` in a loop,
    /// to avoid infinite loops. To run the simulation until convergence or until
    /// reaching a maximum number of iterations, consider using `run()` instead:
    /// This function is mostly useful for making illustrations of the evolution.
    fn step(&mut self) -> StepResult;
    /// Get the result of the latest step or of a complete run.
    ///
    /// This function will either return the best performing individual,
    /// or an error string indicating what went wrong.
    fn get(&self) -> SimResult<T>;
    /// Get the number of nanoseconds spent running, or `None` in case of an overflow.
    ///
    /// When `Self` is `par::Simulator`, i.e. a parallel simulator is used,
    /// the duration is the average duration of all child simulators.
    fn time(&self) -> Option<NanoSecond>;
    /// Get the number of iterations the `Simulator` has executed so far.
    ///
    /// When `Self` is `par::Simulator`, i.e. a parallel simulator is used,
    /// this returns the number of iterations made by the parallel simulator itself.
    fn iterations(&self) -> u64;
}

/// Whether to maximize or to minimize the fitness value.
#[derive(Copy, Clone)]
pub enum FitnessType {
    /// The `Simulation` will try to increase the fitness value of phenotypes.
    Maximize,
    /// The `Simulation` will try to decrease the fitness value of phenotypes.
    Minimize,
}