Matlab Command ReferenceΒΆ

The following sections give the documentations to the Matlab interface scripts of JCMoptimizer.

The functions jcmwave_optimizer_... allow for controlling the optimization server and for creating new optimization studies.

Create a new study

In the most cases it is sufficient to create a new Study instance by calling jcmwave_optimizer_create_study(). This will also automatically start a new instance of the JCMoptimizer if required.

Usage: jcmwave_optimizer_create_study(options)

Purpose: Creates a Study instance that controls the optimization.

Example: study = jcmwave_optimizer_create_study('domain', domain, 'name', 'Test');

Input: key-value list to configure the optimization study
    domain: Cell array of domain definitions for each parameter. A domain
        definition consists of a struct with the entries:

        name: Name of the parameter. E.g. 'x1'. The name should contain
             no spaces and must not be equal to function names like
             'sin', 'cos', 'exp' etc.
        type: Type of the parameter. Either 'continuous', 'discrete', or
             'fixed'. Fixed parameters are not optimized, but can be used
             in the constraint functions.
        domain: The domain of the parameter. For continuous parameters this
             is a tuple [min, max]. For discrete parameters this is a list
             of values, e.g. [1,2,3,4,5]. Note that it is assumed, that
             the objective values are correlated not only for continuous but
             also for discrete values. For uncorrelated values (i.e.
             categorial values) one should rather setup independent studies.
             For fixed parameters the domain is a single parameter value.

        Example:
             domain = {};
             domain(1).name = 'x1';
             domain(1).type = 'continuous';
             domain(1).domain = [-1.5, 1.5];
             domain(2).name = 'x2';
             domain(2).type = 'continuous';
             domain(2).domain = [-1.5, 1.5];
             domain(3).name = 'x3';
             domain(3).type = 'discrete';
             domain(3).domain = [-1,0,1];
             domain(4).name = 'radius';
             domain(4).type = 'fixed';
             domain(4).domain = 2;

    constraints: List of constraints on the domain. Each list element is a
        dictionary with the entries

        name: Name of the constraint.
        constraint: A string defining a function that is smaller zero if and
              only if the constraint is met. The following operations and
              functions may be used: +,-,*,/,^,sqrt,sin,cos,tan,abs,round,
              sgn, trunc. E.g. 'x1^2 + x2^2 + sin(x1+x2)'

        Example:
              constraints = {};
              constraints(1).name = 'circle';
              constraints(1).constraint = 'x1^2 + x2^2 - 4';
              constraints(2).name = 'triangle';
              constraints(2).constraint = 'x1 - x2';

    study_id: A unique identifier of the study. All relevant information on
          the study are saved in a file named study_id+'.mpk'
          If the study already exists, the 'domain' and 'constraints'
          do not need to be provided. If not set, the study_id is set to
          a random unique string.

    name: The name of the study that will be shown in the dashboard.

    save_dir: The path to a directory, where the study file (mpk-file) is saved.

    output_precision: Precision level for output of parameters. (Default: 1e-10)

        Note: Rounding the output can potentially lead to a slight
              breaking of constraints.

    driver: Driver used for the study (default: 'BayesOptimization').
              For a list of drivers, see the
              Analysis and Optimization Toolkit/Driver Reference

Controlling JCMoptimizer

The following functions allow to start and stop the server JCMoptimizer manually and configure the port for the communication between the server and the client.

Usage: jcmwave_optimizer_startup([options])

Purpose: Starts optimizer on local machine.

Input:
  options: key-value list to configure the optimization server
     port: The port that the optimization server is listening on.
     dashboard_port: The port that the dashboard server is listening on.
     persist: ('yes' or 'no') In persistent mode the optimization server
          will stay alive after Matlab has closed. Otherwise the server
          will shut down automatically.
Usage: jcmwave_optimizer_check(true)

Purpose: Checks if the optimization server is running.

Input:
  warn: If true, warning messages are shown if the check fails.

Returns: True if the optimization server is running.
Usage: jcmwave_optimizer_shutdown(force, port)

Purpose: Shuts down the optimization server

Input:
   force: If true the optimization server is closed even if a study
      is not yet finished.
   port: The port where the optimization server is running. If no port is
      provided, the server started by calling jcmwave_optimizer_startup()
      is closed.

Create a client instance

The function jcmwave_optimizer_client() allows to create a Client instance that is connected with a specific instance of JCMoptimizer that is listening on a given port. This is useful to connet to a server that was manually started at a remote computer.

Usage: jcmwave_optimizer_client([port])

Purpose: Creates a Client instance, that can communicate with an optimization server.
         If no server is running, it will be started automatically.
Input:
  port: The port that the optimization server is listening on.
       If no port is specified, the client communicates with the server that was
       started by calling jcmwave_optimizer_startup().

Returns: An instance of the class 'Client'

Note: This function is useful if you want to start the optimization server on another
      computer. In this case you can do the following:

      1. Login to the other computer
      2. Start the optimization server manually by calling
         '$JCMROOT/ThirdPartySupport/Python/bin/JCMoptimizer'.
      3. Forward the ports of the optimizer and the dahsboard to your local computer, e.g. by calling
        'ssh -NL 4554:localhost:4554 -NL 4555:localshost:4555 user@remotehost'
      4. Create a Client instance 'client'.
      5. Create a new study by calling client.create_study().

Create a benchmark instance

The function jcmwave_optimizer_create_benchmark() allows to create a new Benchmark instance.This allows to compare the performance of different drivers or driver configurations for a specific objective function.