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

//! A collection of Black-Box Optimization algorithms.
//!
//! "yamakan" is a Japanese translation of "guesswork".
#![warn(missing_docs)]

#[macro_use]
extern crate trackable;

use rand::Rng;
#[cfg(feature = "serde")]
use serde::{Deserialize, Serialize};

pub use self::budget::Budget;
pub use self::error::{Error, ErrorKind};
pub use self::observation::{MfObs, Obs, ObsId};

pub mod domains;
pub mod generators;
pub mod optimizers;

mod budget;
mod error;
mod observation;

/// This crate specific `Result` type.
pub type Result<T, E = Error> = std::result::Result<T, E>;

/// This trait provides ask-and-tell interface for black-box optimization.
pub trait Optimizer {
    /// The parameter to be optimized.
    type Param;

    /// The value obtained as a result of a parameter evaluation.
    type Value;

    /// Asks the next parameter to be evaluated.
    ///
    /// The evaluation result should be told to this optimizer.
    fn ask<R: Rng, G: IdGen>(&mut self, rng: R, idg: G) -> Result<Obs<Self::Param>>;

    /// Tells the result of an observation to this optimizer.
    ///
    /// If there is an existing observation that has the same identifier,
    /// the state of the observation should be overwritten by the new one.
    ///
    /// # Errors
    ///
    /// Some implementations may return an `ErrorKind::UnknownObservation` error
    /// if this optimizer does not known (or has not generated) the specified observation.
    fn tell(&mut self, obs: Obs<Self::Param, Self::Value>) -> Result<()>;
}

/// This trait provides ask-and-tell interface for multi-fidelity black-box optimization.
pub trait MultiFidelityOptimizer {
    /// The parameter to be optimized.
    type Param;

    /// The value obtained as a result of a parameter evaluation.
    type Value;

    /// Asks the next parameter to be evaluated.
    ///
    /// The evaluation result should be told to this optimizer.
    fn ask<R: Rng, G: IdGen>(&mut self, rng: R, idg: G) -> Result<MfObs<Self::Param>>;

    /// Tells the result of an observation to this optimizer.
    ///
    /// If there is an existing observation that has the same identifier,
    /// the state of the observation should be overwritten by the new one.
    ///
    /// # Errors
    ///
    /// Some implementations may return an `ErrorKind::UnknownObservation` error
    /// if this optimizer does not known (or has not generated) the specified observation.
    fn tell(&mut self, obs: MfObs<Self::Param, Self::Value>) -> Result<()>;
}

/// Parameter search domain.
pub trait Domain {
    /// A specific point in this domain.
    type Point;
}

/// Observation ID generator.
pub trait IdGen {
    /// Generates a new identifier.
    fn generate(&mut self) -> Result<ObsId>;
}
impl<'a, T: IdGen + ?Sized> IdGen for &'a mut T {
    fn generate(&mut self) -> Result<ObsId> {
        (**self).generate()
    }
}
impl<T: IdGen + ?Sized> IdGen for Box<T> {
    fn generate(&mut self) -> Result<ObsId> {
        (**self).generate()
    }
}

/// Ranked value.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub struct Ranked<T> {
    /// Rank (lower is better).
    pub rank: u64,

    /// Value.
    pub value: T,
}