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