Client

Warning

This interface documentation describes a deprecated version of the Analysis and Optimization Toolkit in JCMsuite. It has been superseded by JCMoptimizer and is retained solely for reference in legacy projects.

For all new simulation and optimization projects, use JCMOptimizer instead. The corresponding documentation is available here.

This class provides methods for creating new optimization studies.

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];

 study = client.create_study('domain', domain, 'name', 'basic example');

Methods

    check_server

        Purpose: Checks whether there is a running optimization server.
        Usage: client.check_server(warn)
        Input:
          warn: If true, shows warning messages.

    shutdown_server

        Purpose: Shuts down the optimization server
        Usage: client.shutdown_server()
        Input:
          port: The port where the optimization server is running. If not port is
               provided, the server started by calling jcmwave_optimizer_startup()
               is closed.
          force: If True the optimization server is closed even if a study
               is not yet finished.

    create_study

        Purpose: Creates a new optimization study object.
        Usage: client.create_study('domain', domain, 'name', 'basic example');
        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',
                     'categorial' 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.0,2.5,3.0]. For categorial inputs it is a list
                    of strings, e.g. {% raw %}{{'cat1','cat2','cat3'}}{% endraw %}. Note, that categorial
                    values are internally mapped to integer representations, which
                    are allowed to have a correlation. The categorial values should
                    therefore be ordered according to their similarity.
                    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 = 'x4';
                    domain(4).type = 'categorial';
                    domain(4).domain = {'a','b','c'};
                    domain(5).name = 'radius';
                    domain(5).type = 'fixed';
                    domain(5).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, tunc. 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+'.jcmo'
                 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 (jcmo-file) is saved. If false, no study 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 (deprecated)/Driver Reference

          dashboard: If true, a dashboard server will
                 be started for the study. (Default: true)

          open_browser: If true, a browser window with the dashboard is started.
                (Default: true)

    create_benchmark

        Purpose: Creates a new benchmark object for benchmarking different optimization
                 studies against each other.
        Usage: client.create_benchmark('num_average', 6);
        Input: key-value list to configure the benchmark
           benchmark_id: A unique identifier of the benchmark
           num_average: Number of study runs to determine average study performance