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
)
Search
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 then_step_max
is reached (see docs forCEM.search/2
).
@spec replace(CEM.Problem.t(), atom(), (... -> any())) :: CEM.Problem.t()
Replace a required function in the CEM.Problem
struct.
@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 is100
.:f_elite
- The fraction between 0 and 1 of the sample size used to select the elite set. The default value is0.1
.:f_interp
- The fraction between 0 and 1 used to interpolate between the current and previous parameters. The default value is0.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 whenterminate?
is not provided by the user inCEM.new/1
, and it is a fail-safe to prevent infinite recursion. The default value is100
.:other_opts
(keyword/0
) - User-specified options. Warning: these options are not validated. The default value is[]
.