OptionsMatlab

Options optimisation and design search package

OptionsMatlab makes the Options optimisation and design search package available to Matlab, calling user-defined constraint and objective functions defined as Matlab functions. OptionsMatlab also supports a number of Response Surface Model algorithms that allow optimisation to be carried out cheaply using approximations of the values of the objective function and/or constraints.

Syntax

STRUCTOUT = OptionsMatlab(STRUCTIN)

STRUCTOUT = OptionsMatlab(STRUCTIN,STRUCTOUT)

Description

STRUCTOUT = OptionsMatlab(STRUCTIN) where STRUCTIN is a Matlab structure containing the problem definition and control parameters for the optimisation algorithms, and STRUCTOUT is a structure containing optimum design variables and the objective function and constraint values at this point.

STRUCTOUT2 = OptionsMatlab(STRUCTIN,STRUCTOUT) where STRUCTIN is a Matlab structure containing the problem definition and control parameters for an optimisation over a Response Surface Model (RSM), and where STRUCTOUT is the trace history of a previous design search which contains the information required to generate the RSM. STRUCTIN should contain values for either of the parameters OBJMOD or CONMOD which specify the RSM used, if any, for the objective function and constraints. The design search used to generate data points from which the RSM is produced should ideally be a space-filling search such as a Genetic Algorithm (GA) or Design of Experiments (DoE).

Input argument

The structure STRUCTIN must contain a number of mandatory fields, and may also contain a number of optional control parameters. The mandatory fields required are:

DNULL: A number that corresponds to a NULL value in the problem setup

OLEVEL: [optional] The output level of the OptionsMatlab package [0-10]. Default value OLEVEL = 1.

MAXJOBS: [optional] Allows the user to limit the number of parallel jobs. Default value MAXJOBS = 1.

NVRS: The number of design variables

VARS: A vector of NVRS design variables corresponding to the initial design variables to be evaluated

VNAM: A cell array of length NVRS containing the names of the design variables for the internal GENDAT database (variable names must not exceed 10 chars)

LVARS: A vector of length NVRS representing the lower limits to the design variable values.

UVARS: A vector of length NVRS representing the upper limits to the design variable values.

NDVRS: [optional] The maximum number of discrete design variable values for any single design variable. Default value NDVRS = 0, where all design variables are contiguous.

DVARS: [required if NDVRS > 0] A matrix of size NVRS by NDVRS of the discrete design variable values (set to DNULL if contiguous)

NCONS: [optional] The number of design constraints. If NCONS is set to zero the problem will be unconstrained, and OPTCON will not be invoked. Default value NCONS = 0.

CNAM: [required if NCONS > 0] A cell array of length NCONS containing the names of the design constraints for the internal GENDAT database (constraint names must not exceed 10 chars)

LCONS: [required if NCONS > 0] A vector of length NCONS representing the lower limits to the design constraints (set to DNULL if no lower limit)

UCONS: [required if NCONS > 0] A vector of length NCONS representing the upper limits to the design constraints (set to DNULL if no upper limit)

NPARAMS: [optional] The number of user-defined parameters. If NPARAMS are set to zero an empty parameter array will be passed to the user-defined functions. Default value NPARAMS = 0.

PARAMS: [required if NPARAMS > 0] A vector of NPARAMS user-defined parameter values

PNAM: [required if NPARAMS > 0] A cell array of length NPARAMS containing the names of the user-defined parameters for the internal GENDAT database (parameter names must not exceed 10 chars)

ONAM: A char array (max length 10 chars) containing the name of the objective function in the internal GENDAT database.

OMETHD: The number of the optimisation or design search algorithm to be used. The available search methods are:

0.0 to just evaluate the user's problem code at the point specified

1.1 for OPTIVAR routine ADRANS

1.2 for OPTIVAR routine DAVID

1.3 for OPTIVAR routine FLETCH

1.4 for OPTIVAR routine JO

1.5 for OPTIVAR routine PDS

1.6 for OPTIVAR routine SEEK

1.7 for OPTIVAR routine SIMPLX

1.8 for OPTIVAR routine APPROX

1.9 for OPTIVAR routine RANDOM

2.1 for user specified routine OPTUM1

2.2 for user specified routine OPTUM2

2.3 for NAG routine E04UCF

2.4 for bit climbing

2.5 for dynamic hill climbing

2.6 for population based incremental learning

2.7 for numerical recipes routines

2.8 for design of experiment based routines

3.11 for Schwefel library Fibonacci search

3.12 for Schwefel library Golden section search

3.13 for Schwefel library Lagrange interval search

3.2 for Schwefel library Hooke and Jeeves search

3.3 for Schwefel library Rosenbrock search

3.41 for Schwefel library DSCG search

3.42 for Schwefel library DSCP search

3.5 for Schwefel library Powell search

3.6 for Schwefel library DFPS search

3.7 for Schwefel library Simplexsearch

3.8 for Schwefel library Complexsearch

3.91 for Schwefel library twomembered evolution strategy

3.92 for Schwefel library multimembered evolution strategy

4 for genetic algorithm search

5 for simulated annealing

6 for evolutionary programming

7 for evolution strategy

DIRCTN: The search direction (in the range +/2). The optimizers try to minimize the objective function if this argument is 1, maximize it if is +1, minimize the log of the function if it is 2 or maximize the log if it is +2

NITERS: The maximum number of iterations to be used

OPTJOB: The name of the Matlab function responsible for calling the user-defined objective and constraint functions (maximum length 255 chars)

OPTFUN: A string describing the user-defined objective function routine to be called by the OPTJOB (maximum length 255 chars)

OPTCON: [required if NCONS > 0] A string describing the user-defined constraint function routine to be called by the OPTJOB (maximum length 255 chars)

OBJMOD: [optional] The RSM method to be used to approximate the value of objective function. The available methods are:

1.0 for a Shepard response surface model should

2.1 for linear Radial Basis Function

2.2 for thin plate Radial Basis Function

2.3 for cubic splines Radial Basis Function

2.4 for cubic splines Radial Basis Function with regression via reduced bases

3.1 for mean polynomial regression model

3.2 for first order polynomial regression model

3.3 for first order polynomial regression model plus squares

3.4 for first order polynomial regression model plus products (crossterms)

3.5 for second order polynomial regression model

3.6 for second order polynomial regression model plus cubes

4.1 for a Stochastic Process Model

4.2 for the root mean square error of the Stochastic Process Model

4.3 for the expected improvement of the Stochastic Process Model

4.31 for the expected improvement of the constrained Stochastic

Process Model [requires CONMOD=4.1]

4.32 for the feasibility of improvement of the constrained Stochastic

Process Model [requires CONMOD=4.1]

4.33 for the probability of improvement of the Stochastic Process Model

0.0 if the underlying user supplied function is to be called.

CONMOD: [optional] The RSM method to be used to approximate the values of the constraints. The available methods are:

1.0 for a Shepard response surface model should

2.1 for linear Radial Basis Function

2.2 for thin plate Radial Basis Function

2.3 for cubic splines Radial Basis Function

2.4 for cubic splines Radial Basis Function with regression via reduced bases

3.1 for mean polynomial regression model

3.2 for first order polynomial regression model

3.3 for first order polynomial regression model plus squares

3.4 for first order polynomial regression model plus products (crossterms)

3.5 for second order polynomial regression model

3.6 for second order polynomial regression model plus cubes

4.1 for a Stochastic Process Model

4.2 for the root mean square error of the Stochastic Process Model

4.3 for the expected improvement of the Stochastic Process Model

0.0 if the underlying user supplied function is to be called.

NUMUPDATE: [optional] is a scalar which determines the number of update points to be returned when a search routine is run over a RSM. Update points can be used to improve the accuracy of the dataset that was used to generate the RSM. The update points are return in a sub-structure DOE_TRACE in the output structure. If NUMUPDATE is not specified then update points are not returned by OptionsMatlab.

DOE_TRACE: [optional] is a structure containing the user-supplied DOE points to be used when the control parameter MC_TYPE equals 7. DOE_TRACE requires two mandatory fields:

DOE_TRACE.NCALLS: the number of user-supplied DOE points. Note that DOE_TRACE.NCALLS must equal NITERS-1 as the DOE will first evaluate the design variables VARS.

DOE_TRACE.VARS: the design points to be evaluated during the DOE (size NVARS by DOE_TRACE.NCALLS)

OBJHYPER: [optional] is a structure containing Stochastic Process Model hyper-parameters used to approximate the value of the objective function. OBJHYPER has three recognised fields:

OBJHYPER.OBJ_LAMBDA: the value of hyper-parameter LAMBDA

OBJHYPER.OBJ_THETA: the values of hyper-parameter THETA (length NVARS; see RSM_QCK_HP)

OBJHYPER.OBJ_EXP: the values of hyper-parameter EXP (length NVARS; see RSM_QCK_HP)

CONHYPER: [optional] is a structure containing Stochastic Process Model hyper-parameters used to approximate the value of the constraints. CONHYPER has three recognised fields:

CONHYPER.CST_LAMBDA: the value of hyper-parameter LAMBDA

CONHYPER.CST_THETA: the values of hyper-parameter THETA (length NVARS; see RSM_QCK_HP)

CONHYPER.CST_EXP: the values of hyper-parameter EXP (length NVARS; see RSM_QCK_HP)

RSM_QCK_HP: [optional] is a flag that indicates whether quick hyper-parameter tuning should be used when building and searching a Stochastic Process Model RSM. Quick tuning will be used when RSM_QCK_HP is true (e.g. 1). In this condition single values of the hyper-parameters THETA and EXP will be tuned across all design variables, rather than NVARS values of THETA and EXP corresponding to each design variable. This approach is faster but less accurate, and may be appropriate for some problems. If true the values of OBJ_EXP and OBJ_THETA, and of CST_EXP and CST_THETA (in the structures OBJHYPER and CONHYPER) will be scalar, rather than a vector of length NVARS. Quick hyper-parameter tuning is not available when manually tuning the hyper-parameters (i.e. when TUNEHYPER>0).

USERDATA: [optional] is an optional field which can contain any type of Matlab variable. This variable will be passed to the user-defined objective and constraint functions via the OPTJOB function.

TUNEHYPER: [optional] is a flag that indicates whether Stochastic Process Model hyper-parameters should be tuned over the search history contained in the second input argument. Hyper-parameters will be tuned if TUNEHYPER is true (e.g. 1). When TUNEHYPER is called the hyper-parameters are tuned using the search method specified by the input structure. Note that the user's problem is not searched, and the output structure will return the structures OBJHYPER (and CONHYPER where appropriate) in addition to the objective function OBJ_CLF (and CST_CLF).

It is possible to tune the values of specific hyper-parameters with following values of TUNEHYPER:

0 No tuning

1 Tune THETA, EXP and LAMBDA

2 Tune THETA and EXP

3 Tune THETA and LAMBDA

4 Tune THETA

If a value of TUNEHYPER greater than 1 is specified, and no user-defined hyper-parameters are supplied (via OBJHYPER or CSTHYPER), then initial values for all hyper-parameters will be generated but only the specified hyper-parameters will be tuned with the designated search method.

CHKPT_INTV: [optional] is an integer value that specifies the interval with which the search history is checkpointed to a MAT file. If parallel optimiser is used (OMETHD 2.8 or 4) CHKPT_INTV should be a multiple of MAXJOBS. If CHKPT_INTV equals 0 there will be no checkpointing (default). If OMETHD equals 4 CHKPT_INTV will contain the structure GA_VARS (once available) that will allow the genetic algorithm to be restarted.

CHKPT_FILE: [optional] specifies the file name that the checkpoint file is written (maximum length 20 characters). The default checkpoint file name is 'OptionsCHKPNT.mat'.

OPTUM1: [optional] A string describing the user-defined sequential optimisation routine to be called when OPTUM1 = 2.1 (maximum length 255 chars). The default value 'optum1' corresponds to the example implementation of a random optimiser (see help optum1 for more details).

Other valid STRUCTIN fields correspond to scalar Options control parameters documented in the Options manual (http://www.soton.ac.uk/~ajk/options.ps) sections 8.8 and 8.9. See also FAQ section 5.16. These control parameters include:

BC_NBIN, BC_NRANDM, BC_PENAL, CST_BAD_PT, DHC_INITSZ, DHC_NRANDM, DHC_PENAL, DHC_THRESH, DOE_NRANDM, EP_IMUTNT, EP_NBIN, EP_NPOP, EP_NRANDM, EP_PENAL, EP_TOURN, ES_DELSIG, ES_MDSCRT, ES_NCPOP, ES_NPPOP, ES_NRANDM, ES_PENAL, ES_UCHILD, ES_VDSCRT, FUSION_TYP, GA_ALPHA, GA_DMAX, GA_DMIN, GA_NBIN, GA_NBREED, GA_NCLUST, GA_NPOP, GA_NRANDM, GA_PBEST, GA_PCROSS, GA_PENAL, GA_PINVRT, GA_PMUTNT, GA_PRPTNL, GA_PSEED, MC_MAND, MC_P1, MC_P2, MC_PENAL, MC_TYPE, NAG_BIGBND, NAG_ETA, NAG_RHO, OBJ_BAD_PT, OPT_CTOL, OPT_STEP, OPT_TOL, OPT_TSIZE, OVR_CONV, OVR_MAND, OVR_NPTS, OVR_PENAL, OVR_SEED, OVR_SHRK, OVR_SIMP, OVR_STEP, OVR_STOP, PL_LRATE, PL_NBIN, PL_NPOP, PL_NRANDM, PL_PENAL, PL_PMUTNT, RSM_EIF_W, RSM_NCSKIP, RSM_NSKIP, RSM_NULL_T, SA_NBIN, SA_NRANDM, SA_PCOLD, SA_PENAL, SA_PMUTNT, SA_PTEMP, SA_PWIDTH, SA_SCHED, SC_BKORRL, SC_CONV, SC_DELI, SC_DELP, SC_DELS, SC_IELTER, SC_IREKOM, SC_KONVKR, SC_LR, SC_LS, SC_NACHKO, SC_NITERS, SC_NRANDM, SC_NS, SC_PENAL, SC_SN, SC_TYPE

Output argument

The structure STRUCTOUT contains the following fields:

VARS: The optimum design variables

OBJFUN: The objective function value at VARS

CONS: The constraint values at VARS

Following a direct search over the user's code the objective function and constraint search histories are returned to the user in to sub-structures, OBJTRC and CONSTRC (respectively). Following evaluation of a RSM search histories are returned in the field RSMTRC.

OBJTRC: The history of evaluations of the objective function

OBJTRC.NCALLS: The number of objective function evaluations

OBJTRC.OBJFUN: The values of the objective function (a vector of length OBJTRC.NCALLS)

OBJTRC.VARS: The variables at which the objective function was evaluated (size NVARS by OBJTRC.NCALLS)

CONSTRC: The history of evaluations of the constraints

CONSTRC.NCALLS: The number of constraint evaluations

CONSTRC.CONS: The values of the constraints (size NCONS by CONSTRC.NCALLS)

CONSTRC.VARS: The variables at which the constraints were evaluated (size NVARS by CONSTRC.NCALLS)

CONSTRC.UCONS: The upper limits to the constraints at each evaluation (size NCONS by CONSTRC.NCALLS)

CONSTRC.LCONS: The lower limits to the constraints at each evaluation (size NCONS by CONSTRC.NCALLS)

If the field NUMUPDATE is specified in the input structure for a search over a RSM a sub-structure DOE_TRACE is returned containing suggested points that would improve the initial dataset.

DOE_TRACE: Suggested points that would improve the dataset

DOE_TRACE.NCALLS: The number of suggested update points

DOE_TRACE.VARS: The design variables

Following an optimisation over a RSM OptionsMatlab will return the search history in the following field of the output structure (OptionsMatlab 0.9.0+):

RSMTRC: Search history of points evaluated over a RSM

RSMTRC.NCALLS: The number of user specified points used

RSMTRC.VARS: The user-specified design points used

RSMTRC.OBJFUN: The value of the objective function RSM at the user-specified design points.

RSMTRC.CONS: The value of the problem constraint RSM at the user-specified design points.

RSMTRC.UCONS: The upper limits of the problem constraint at the user-specified design points.

RSMTRC.LCONS: The upper limits of the problem constraint at the user-specified design points.

If a genetic algorithm (OMETHD=4) is used OptionsMatlab will return the values of the GA variables that may be used to restart the genetic algorithm. This information is contained in the following field of the output structure:

GA_VARS: The GA restart variables

GA_VARS.GA_POP: The GA population design variable and fitness values

GA_VARS.GA_CODE: The final GA code string values

GA_VARS.GA_NRANDM: The random number sequence used by the genetic algorithm.

Following an optimisation over approximate values of the objective and constraint functions using a Stochastic Process Model (OBJMOD and CONMOD respectively) the values and limits of the hyper-parameters will be returned. The hyper-parameters used to approximate values of the objective function will be returned in the structure OBJHYPER, and the constraint hyper-parameters will be returning in the structure CONHYPER. The structures OBJHYPER and CONHYPER are identical to the optional fields of the input structure described above.

Notes

OptionsMatlab requires a valid Options licence file.