StudyΒΆ

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.
           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).

       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