This class provides methods for controlling a numerical optimization study.
Example:
study.set_parameters('max_iter', 80);
objective = @(x1,x2) 10*2 + (x1.^2-10*cos(2*pi*x1)) + (x2.^2-10*cos(2*pi*x2));
while(not(study.is_done))
sug = study.get_suggestion();
val = objective(sug.sample.x1, sug.sample.x2);
obs = study.new_observation();
obs = obs.add(val);
study.add_observation(obs, sug.id);
end
Methods:
set_parameters
Purpose: Sets parameters for the optimization run.
Usage: study.set_parameters('max_iter', 100, 'num_parallel', 5);
Input:
num_parallel: Number of parallel observations of the objective function
(default: 1).
max_iter: Maximum number of evaluations of the objective 2
function (default: inf).
max_time: Maximum optimization time in seconds (default: inf).
Note: The full list of parameters depends on the chosen driver.
For a parameter description, see the documentation of the driver.
start_clock
Purpose: The optimization stops after the time 'max_time'
(see set_parameters()). This function resets the
clock to zero.
Usage: study.start_clock();
Note: The clock is also set to zero by calling set_parameters.
info
Purpose: Get information about the status of the study.
Usage: info = study.info();
Returns: Struct with entries
num_parallel: Number of parallel observations set.
is_done: True if the study has finished (i.e. some stopping criterion was met)
status: Status message
open_suggestions: List of open suggestions
min_params: Parameters of the found minimum.
struct('x1', 0.1, 'x2', 0.7)
min_objective: Minimum value found.
num_dim: Number of variable dimensions of the search space.
get_minima
Purpose: Get information about the local minima after the
optimization run.
Usage: minima = study.get_minima('n_output', 10);
Note: This function is only available for studies using a
Bayesian driver, e.g. 'BayesOptimization' (default driver).
Input:
n_samples: Number of initial samples for searching
(default: automatic determination).
n_output: Maximum number of minima that are returned (Default: 10)
epsilon: Parameter used for identifying identical minima (i.e.
minima with distance < length scale * epsilon)
and minima with non-vanishing gradient (e.g. minima at the
boundary of the search space) (default: 0.2)
delta: parameter used for approximating second derivatives
(default: 0.2)
min_dist: To increase the performance, it is possible to use
a sparsified Gaussian process. One can define the minimal distance
between the datapoints in this Gaussian process in units of the
length scales. (default: 0.0)
Returns: List of structs with information about local minimas
with the objective value, the uncertaitny of the objective value,
the parameter values and the width in each parameter direction
(i.e. standard deviation after a fit to a
gaussian)
get_data_table
Purpose: Get table with data of the acquisitions.
Usage: data = study.get_data_table();
Returns: Strunct with entries
iteration: List of iteration number
datetime: List of dates and times of the creation of the
corresponding suggestion.
cummin: List of cummulative minima for each iteration.
objective_value: List of the objective values aquired at each iteration.
parameters: Dictionary containing a list of parameter values for each
parameter name.
driver_info
Purpose: Get driver-specific information.
Usage: data = study.driver_info();
Returns: Struct with multiple entries. For a description of
the entries, see the documentation of the driver.
is_done
Purpose: Checks if the study has finished.
Usage: if study.is_done() break; end;
Returns: True if some stopping critereon set by
set_parameters() was met.
Note: Before returning true, the function call waits until all open
suggestions have been added to the study.
get_suggestion
Purpose: Get a new suggestion to be evaluated by the user.
Usage: suggestion = study.get_suggestion();
Returns: Suggestion() object with properties
id: Id of the suggestion
sample: Struct of the parameters. E.g. struct('x1', 0.1, 'x2', 0.2)
Warning: The function has to wait until the number of open suggestions is smaller
than 'num_parallel' before receiving a new suggestion. This can cause a deadlock
if no observation is added.
clear_suggestion
Purpose: If the calculation of an objective value for a certain suggestion
fails, the suggestion can be cleared from the study.
Usage: study.clear_suggestion(suggestion.id, 'Computation failed');
Input:
suggestion_id: Id of the suggestion to be cleared.
message: An optional message that is printed out.
new_observation
Purpose: Create a new observation object.
Usage:
observation = study.new_observation();
observation.add(1.2);
observation.add(0.1,'x1');
Returns: 'Observation()' object with the method 'add()' that has the arguments
value: Observed value of objective function
derivative (optional): Name of the derivative paramter. E.g. for
'derivative='x1'', the value is interpreted as the derivative
of the objective with respect to 'x1'.
add_observation
Purpose: Adds an observation to the study.
Usage: study.add_observation(observation, suggestion.id)
Input:
observation: 'Observation()' object with added values
(see new_observation())
suggestion_id: Id of the corresponding suggestion if it exists, else NaN.
sample (optional): If the observation does not belong to an open suggestion,
the corresponding sample must be provided.
E.g. struct('x1', 0.1, 'x2', 0.2)
add_many
Purpose: Adds observations for many user-defined samples to the study.
Usage: study.add_observation(samples, observations)
Input:
samples: Cell array of samples.
E.g. {struct('x1', 0.1, 'x2', 0.2), struct('x1', 0.3, 'x2', 0.4)}
observations: Cell array of 'Observation()' objects
(see new_observation())
predict
Purpose: Predict the value and the uncertainty of the objective function.
Usage: study.predict('samples',{[1,0,0],[2,0,1]})
Note: This function is only available for studies using the
driver 'BayesOptimization' (default driver).
Input:
samples: List of samples, i.e. list with parameter values.
derivatives: Whether derivatives of the means and uncertainties are
computed.
min_dist: To increase the performance for making many
predictions at once, it is possible to use a
sparsified Gaussian
process. One can define the minimal distance
between the datapoints in this Gaussian process in units of the
length scales. (default: 0.0)
Returns: A list of predictions
get_statistics
Purpose: Determines statistice of the objective function which can be
optionally weighted with the functions "funcs". By default the probability
density of the parameters is a uniform distribution in the whole parameter
domain. Other parameter distributions can be defined via
study.set_parameters(distribution = dist).
Usage:
dist = {};
dist(1).name = 'param1';
dist(1).dist = 'normal';
dist(1).mean = 1.0;
dist(1).variance = 2.0;
dist(2).name = 'param2';
dist(2).dist = 'uniform';
dist(2).domain = [1.0,2.0];
study.set_parameters('distribution',dist)
study.get_statistics('funcs',{'1.0','x1','x1+x2'},'abs_precision',0.001)
Note: This function is only available for studies using a Bayesian driver,
e.g. "BayesOptimization" (default driver).
Note: For the Monta Carlo integration, only samples fulfilling the
contraints of the parameters are used.
Inputs:
funcs: A function string or a list of functions strings.
For functs=f the value of g(r) = objective(r)*f(r) is analyzed
For functs=[f_1,f_2,...] a list of function [g_i(r)=objective(r)*f_i(r)]
is analyzed.
abs_precsion: The Monte Carlo integration is stopped when
the absolute precision of the mean value or the uncertainty of the
mean value is smaller than abs_precision. (Default: 1e-9)
rel_precsion: The Monte Carlo integration is stopped when
the relative precision of the mean value or the relative uncertainty
of the mean value is smaller than rel_precision.
(Default: 1e-3)
max_time: The Monte Carlo integration is stopped when the
time max_time has passed. (Default: inf)
max_iter: The Monte Carlo integration is stopped after max_iter
samples. (Default: 1e5)
compute_uncertainity: Whether the uncertainty of the integral is
computed based on the uncertainty of the Gaussian-process predictions.
(Default: True)
min_dist: To increase the performance, it is possible to use
a sparsified Gaussian process. One can define the minimal distance
between the datapoints in this Gaussian process in units of the
length scale. (default: 0.0)
Returns: A struct with the following entries
mean: Expectation value <g> of the (weighted) objective under the
parameter distribution
variance: Variance <g^2> - <g>^2 of the (weighted) objective under the
parameter distribution
uncertainty_mean: Uncertainty of the mean value determined from the
uncertainty of the Gaussian process regression.
lower_quantile: 16% quantile of (weighted) objective values under the
parameter distribution
median: 50% quantile of (weighted) objective values under the
parameter distribution
upper_quantile: 84% quantile of (weighted) objective values under the
parameter distribution
num_sampling_points: Number of sampling points that were used in the
Monte Carlo integration. The numerical uncertainty of the computed
mean value is Sqrt(variance/N).
optimize_hyperparameters
Purpose: Optimize the hyperparameters of the Gaussian
process manually. This is usually done automatically. See the
documentation of the driver 'BayesOptimization' for parameters steering
this process.
Usage: study.optimize_hyperparameters();
Note: This function is only available for studies using the
driver 'BayesOptimization' (default driver).
open_jobs
Purpose: Collects all ids of open jobs belonging to a suggestion.
Usage: study.open_jobs(job_ids, suggestion);
Input:
job_ids: List of job ids as returned from jcmwave_solve in daemon mode.
suggestion: A suggestion object.
run_mcmc
Purpose: Runs a Markov Chain Monte Carlo (MCMC) sampling over the posterior
probability density of the parameters. This method should be run only after
the minimization of the likelihood is completed.
Usage:
study.run()
dist = [{name="param1", dist="normal", "mean"=1.0, "variance"=2.0},
{name="param2", dist="gamma", "alpha"=1.2, "beta"=0.5},
{name="param3", dist="uniform"}]
study.set_parameters(distribution=dist)
samples = study.run_mcmc()
Note: The function is only available for the BayesLeastSquare driver.
Input:
num_walkers: Number of walkers (default: automaticcally chosen).
max_iter: Maximum absolute chain length (default: 1e4).
chain_length_tau: Maximum chain length in units of the
correlation time tau (default: 100).
multi_modal: If true, a more explorative sampling strategy
is used (default: false).
append: If true, the samples are appended to the samples of
the previous MCMC run (default: false).
min_dist: To increase the performance of the sampling,
it is possible to us a sparsified Gaussian process.
One can define the minimal distance between the datapoints in this
Gaussian process in units of the length scalesss. (default: 0.0)
max_sigma_dist: If set, the sampling is restricted to a
a distance max_sigma_dist * sigma to the maximum likelihood
estimate. E.g. max_digma_dist=3.0 means that only the 99.7% p
robability region of each parameter is sampled. (default: inf)
marginalize_uncertainties: If true, the mean value
of the likelihood is determined by marginalizing over the
uncertainties of the Gaussian process regression. This is more
reliable in parameter regions with fewer function acquisitions
but leads also to a slower MCMC sampling. (default: false).
Returns: A struct with the following entries:
samples: The drawn samples without "burnin" samples thinned by
half of the correlation time.
medians: The medians of all random parameters
lower_uncertainties: The distances between the medians
and the 16% quantile of all random parameters
upper_uncertainties: The distances between the medians
and the 84% quantile of all random parameters
gather_results
Purpose: Waits for open jobs to finish until all the jobs from one of
the open suggestion are completed.
Usage: [sug_results, sug_id, sug_logs] = study.gather_results();
Returns:
sug_results: Cell array of results from the corresponding jobs.
sug_id: Id of the corresponding suggestion.
sug_logs: Cell array of logging messages from the corresponding jobs