View Source CEM (cem v0.1.0)

The primary interface for defining a CEM optimization problem and executing the search.

TODO:

  • summarize the functional flow of CEM optimization, with supporting diagram

Define a problem

A CEM problem is a struct that holds seven (7) required functions. In many situations, it will make sense to define some or all of these functions in a module and then create the problem struct using CEM.new/1.

For example, here's a module that defines a simple one-dimensional optimization problem:

defmodule MyProblem do
  alias CEM.Helpers
  alias CEM.Random
  alias CEM.Stats

  def init(_opts), do: %{mean: 0, std: 100}

  def draw(%{mean: mean, std: std}), do: Random.normal(mean, std)

  def score(x), do: :math.exp(-x * x)

  def update(sample) do
    {mean, std} = Stats.sample_mean_and_std(sample)
    %{mean: mean, std: std}
  end

  def smooth(params, params_prev, f_interp) do
    %{
      mean: Helpers.interpolate(params.mean, params_prev.mean, f_interp),
      std: Helpers.interpolate(params.std, params_prev.std, f_interp)
    }
  end

  def terminate?([entry | _], _opts), do: entry.params.std < 0.001
end

Now build the struct:

problem =
  CEM.new(
    init: &MyProblem.init/1,
    draw: &MyProblem.draw/1,
    score: &MyProblem.score/1,
    update: &MyProblem.update/1,
    smooth: &MyProblem.smooth/3,
    terminate?: &MyProblem.terminate?/2
  )

Once the problem struct is defined, execute the search with CEM.search/2:

CEM.search(problem, opts)

where opts is a keyword list of options (see the documentation for CEM.search/2). After the options are validated, opts is turned into a map, and any functions passed to CEM.new/1 that take opts as an argument expect a map.

Summary

Types

Map of options used internally.

Parameters of the the probability distribution used to generate candidate solutions.

Iteration count for the CEM search.

Functions

Create a new CEM.Problem struct from a keyword list of required functions.

Replace a required function in the CEM.Problem struct.

Search for the optimal solution instance.

Types

@type opts() :: map()

Map of options used internally.

@type params() :: any()

Parameters of the the probability distribution used to generate candidate solutions.

@type step() :: non_neg_integer()

Iteration count for the CEM search.

Functions

@spec new(keyword()) :: CEM.Problem.t()

Create a new CEM.Problem struct from a keyword list of required functions.

The required functions are:

  • :init (function of arity 1) - Required. Function to initialize the parameters of the probability distribution used to generate candidate solutions.

  • :draw (function of arity 1) - Required. Function to draw a random instance from the probability distribution with the given parameters.

  • :score (function of arity 1) - Required. Function to score a candidate solution.

  • :update (function of arity 1) - Required. Function to update the parameters of the probability distribution using a sample of candidate solutions.

  • :smooth (function of arity 3) - Required. Function to smooth the parameters of the probability distribution by linearly interpolating between the most recent sample-based update and the parameters from the previous optimization iteration.

  • :terminate? (function of arity 2) - Function to decide if the search should be terminated based on the log so far. If not provided, the search will end when the n_step_max is reached (see docs for CEM.search/2).

Link to this function

replace(problem, fun_name, fun)

View Source
@spec replace(CEM.Problem.t(), atom(), (... -> any())) :: CEM.Problem.t()

Replace a required function in the CEM.Problem struct.

Link to this function

search(problem, opts \\ [])

View Source
@spec search(CEM.Problem.t(), opts :: keyword()) :: map()

Search for the optimal solution instance.

Given a CEM struct and optional parameters, return the optimal solution instance and its score, the corresponding parameters of the probabiity distribution, and a log of optimization progress.

Options

  • :n_sample (non_neg_integer/0) - The size of the sample generated before selecting the elite set. The default value is 100.

  • :f_elite - The fraction between 0 and 1 of the sample size used to select the elite set. The default value is 0.1.

  • :f_interp - The fraction between 0 and 1 used to interpolate between the current and previous parameters. The default value is 0.1.

  • :mode - The optimization mode, either :min (minimization) or :max (maximization). The default value is :max.

  • :n_step_max (non_neg_integer/0) - The maximum number of CEM steps at which the search is terminated. This is the default termination condition when terminate? is not provided by the user in CEM.new/1, and it is a fail-safe to prevent infinite recursion. The default value is 100.

  • :other_opts (keyword/0) - User-specified options. Warning: these options are not validated. The default value is [].