• Quick-Overview
• History of DIRECTGO Versions
• Documentation
  • Algorithms within DIRECTGO
  • DIRECTGO Quick Start Guide
    • Example of box constrained global optimization algorithm usage
    • Example of constrained global optimization algorithm usage
    • Parallel algorithm usage
  • GENDIRECT Framework
  • GENDIRECT Quick Start Guide
• Replicating Findings from Our Research
• Citing DIRECTGO
• Feedback and Contributions
• References

DIRECTGO: A new DIRECT-type MATLAB toolbox for derivative-free Global Optimization¹. This toolbox provides a comprehensive suite of deterministic, derivative-free optimization algorithms tailored for various single-objective optimization problem types, containing box, linear, nonlinear, or hidden constraints.

The majority of the algorithms in this toolbox are implemented sequentially, utilizing either static² or dynamic³ data structures. Additionally, the repository includes parallel implementations⁴ for certain specific algorithms. The toolbox is organized into two main components:

• DIRECTGO.mltbx - MATLAB toolbox package containing implementations of DIRECT-type algorithms, including an extensive DIRECTGOLib⁵ library (maintained separately) of the box, generally constrained, and practical engineering global optimization problems, often used for benchmarking DIRECT-type algorithms.
• DIRECTGO.mlappinstall - A single MATLAB app installer file containing everything necessary to install and run the DIRECTGO toolbox, including a graphical user interface (GUI).

Additionally, we provide source files of all implemented algorithms in the Algorithms/ folder.

• DIRECTGO v2.0.0 (pre-release) incorporates the GENDIRECT a generalized framework⁶ that unifies most of the DIRECT-type algorithms for box-constrained global optimization under a single approach.
• DIRECTGO v1.2.0 incorporates thirteen new algorithms introduced in⁷ and⁸. With these additions, the total number of algorithms in DIRECTGO reaches 61.
• DIRECTGO v1.1.0 now comprises twelve additional algorithms introduced in⁹. With these new additions, the total number of algorithms in DIRECTGO amounts to 48.
• DIRECTGO v1.0.0 version, as described in¹, includes the implementation of 36 distinct DIRECT-type algorithms.

Categorization of 61 implemented DIRECT-type algorithms present in various versions of DIRECTGO:

After installation of the MATLAB toolbox (using DIRECTGO.mltbx), all implemented DIRECT-type algorithms and test problems can be freely accessed in the command window of MATLAB. Unlike GUI, algorithms from the command line require more programming knowledge, and configurations must be done manually. All algorithms can be run using the same style and syntax:

1. f_min = algorithm(P);
2. f_min = algorithm(P, OPTS);
3. f_min = algorithm(P, OPTS, D);
4. [f_min, x_min] = algorithm(P, OPTS, D);
5. [f_min, x_min, history] = algorithm(P, OPTS, D);

The left side of the equations specifies the output parameters. After the termination, the algorithm returns the best objective value f_min, solution point x_min, and the history of the algorithmic performance during all iterations history. The information presented here is the iteration number, the total number of objective function evaluations, the current minimum value, and the total execution time.

On the right side, the algorithm name algorithm and at least one input parameter are needed to specify. The first one is the problem structure P consisting of an objective function:

>> P.f = 'objfun';

If the problem involves additional constraints, they also must be specified:

>> P.constraint = 'confun';

The second parameter is an optional variable, OPTS to customize the default settings. The last parameter is the bound constraints for each dimension/variable:

D (i,1) ≤ x_i ≤ D (i,2), i = 1...n;

The parameter D is necessary for the algorithm but can be passed to it in other ways.

Any DIRECT-type algorithm in the DIRECTGO toolbox can be called in MATLAB using the same sequences discussed earlier. Let’s consider the example using the PLOR algorithm, solving the Bukin6.m test function. Figure 1. (left side) shows the Bukin6.m test function plot over its domain. The function should be defined as:

function y = Bukin6(x)                 % Extract info from the function
    if nargin == 0
        y.nx = 2;                      % Dimension of the problem
        xl = [-15; -3];
        y.xl = @(i) xl(i);             % Lower bounds for each variable
        xu = [5; 3];
        y.xu = @(i) xu(i);     	       % Upper bounds for each variable
	      y.fmin = @(nx) get_fmin(nx);   % Known solution value
        y.xmin = @(nx) get_xmin(nx);   % Known solution point
        return
    end
    if size(x, 2) > size(x, 1)         % If x is a row transpose to column 
        x = x'; 
    end
    term1 = 100*sqrt(abs(x(2) - 0.01*x(1)^2));
    term2 = 0.01*abs(x(1) + 10);
    y = term1 + term2;                 % Return function value at x
end

function fmin = get_fmin(~)
    fmin = 0;
end

function xmin = get_xmin(~)
    xmin = [-10; 1];
end

Each test problem in the DIRECTGOLib stores information about the problem structure together with the objective function. In this case, in the Bukin6.m file, the following information is stored: i) the dimensionality of the problem; ii) the lower and upper bounds for each variable; iii) the objective function value of the available solution; iv) the solution point. The optimization problem is passed to the algorithm as part of a P structure. For a simple, box-constrained problem like this, only one field of the P structure is needed: For some problems, the optimum might depend on the number of variables. Therefore, the solution values and points are returned as functions for all test problems in DIRECTGOLib.

» P.f = 'Bukin6';

When a user wants to perform calculations using different from the default settings, the OPTS structure should be used:

>> opts.maxevals = 50;       % Maximal number of function evaluations
>> opts.maxits = 100;        % Maximal number of iterations
>> opts.testflag = 1;        % 1 if global minima is known, 0 otherwise
>> opts.tol = 0.01;          % Tolerance for termination if testflag = 1

Now we are ready to call the dynamic data structure based PLOR implementation dPlor.m to solve this problem:

>> [f_min, x_min, history] = dPlor(P, OPTS);

The iterative output stored in the history parameter contains the following information:

>> history
        history =
            1.0000        5.0000       16.7833       0.0023
            2.0000        7.0000       16.7833       0.0030
            3.0000       13.0000        5.6500       0.0039
            4.0000       19.0000        5.6500       0.0046
            5.0000       27.0000        1.9537       0.0053
            6.0000       33.0000        1.9537       0.0060
            7.0000       41.0000        0.7167       0.0070
            8.0000       47.0000        0.7167       0.0077
            9.0000       55.0000        0.3060       0.0086

Here, the first column shows the iteration number, while the second is the total number of function evaluations. The third column shows how the best objective function value improves at each iteration, while the last column shows the execution time in seconds. The PLOR algorithm was terminated when the maximum number of function evaluations (opts.maxevals = 50) exceeded. The convergence plot is shown on the right side of Fig. 1, while the left side illustrates the Bukin6.m test function over its domain.

Any DIRECT-type algorithmic implementation for constrained global optimization problems can be used, following the same principle presented earlier. For constrained problems, implemented algorithms extract additional information from the functions, such as the number of inequality constraints, equality constraints, and constraint functions. Let us take the G06.m problem as an example, which is defined in the following way:

function y = G06(x)                           
    if nargin == 0			                  % Extract info from the function
        y.nx = 2;                             % Dimension of the problem
        y.ng = 2;                             % Number of g(x) constraints
        y.nh = 0;                             % Number of h(x) constraints
        xl = [13, 0];
        y.xl = @(i) xl(i);                    % Lower bounds for each variable
        y.xu = @(i) 100;		              % Upper bounds for each variable
        y.fmin = @(nx) get_fmin(nx);          % Known solution value
        y.xmin = @(nx) get_xmin(nx);          % Known solution point
        y.confun = @(i) G06c(i);              % Constraint functions
        return
    end
    if size(x, 2) > size(x, 1)                % If x is a row transpose to column 
        x = x'; 
    end
    y = (x(1) - 10)^3 + (x(2) - 20)^3;        % Return function value at x
end

function [c, ceq] = G06c( x )
    c(1) = -(x(1) - 5)^2 - (x(2) - 5)^2 + 100;
    c(2) = (x(1) - 6)^2 + (x(2) - 5)^2 - 82.81;
    ceq = [];
end

function fmin = get_fmin(~)
    fmin = -6961.8138751273809248;
end

function xmin = get_xmin(~)
    xmin = [14.0950000002011322; 0.8429607896175201];
end

As in the previous example, the optimization problem is passed to the algorithm as part of a P structure. Once again, only one field of the P structure is needed:

>> P.f = 'G06';

Next, assume that the user wants to stop the search as soon as the known solution is found to be within 0.01% error. The structure of OPTS in the MATLAB command window should be given as follows:

>> opts.maxevals = 10000;  % Maximal number of function evaluations
>> opts.maxits = 1000;     % Maximal number of iterations
>> opts.testflag = 1;      % 1 if global minima is known, 0 otherwise
>> opts.tol = 0.01;        % Tolerance for termination if testflag = 1
>> opts.showits = 1;       % Print iteration status

The desired algorithm can then be run using the following sequence:

>> [f_min, x_min, history] = dDirect_GLc(P, OPTS);

Since opts.showits has been set to 1 in the OPTS structure, the status of each iteration will be printed in the MATLAB command window. The DIRECT-GLc.m algorithm used in this example works in two phases. Since the initial sampling points of the G06.m problem do not satisfy the constraints using DIRECT-GLc, the algorithm switches to the second phase, which is indicated by the first printed line. In the latter stage, the algorithm searches for at least one point where the constraints are satisfied. When the algorithm finds such a point, it switches to phase one and tries to find a better solution using the auxiliary function-based approach. The last line prints the reason for stopping the algorithm. Since the solution was found with a 0.01% error, the algorithm stopped at iteration 14 after finding the solution 𝑓min with the value −6901.5099081387.

Phase_II - searching feasible points:
con viol: 2404.4400000000 fn evals: 5
con viol: 515.5511111111  fn evals: 7
...
con viol: 0.1374240038    fn evals: 123
con viol: 0.0000000000    fn evals: 159  f_min: -5612.1483164940
Phase_I - Improve feasible solution:
Iter: 1     f_min: -5886.5625227848     time(s): 0.05935     fn evals: 197
Iter: 2     f_min: -5931.8554991123     time(s): 0.06473     fn evals: 241
...
Iter: 13    f_min: -6873.0583159376     time(s): 0.13197     fn evals: 947
Iter: 14    f_min: -6901.5099081387     time(s): 0.13869     fn evals: 1027
Minima was found with Tolerance: 1

Let us consider a different way a user can use DIRECT-type algorithms. If the user wants to solve new problems not available in DIRECTGOLib without defining the functions described earlier, this can be done in other ways. Let us take the same G06.m problem as an example. To the structure P.f, the name of an m-file, which should compute the value of the G06.m objective function, must be given.

function y = G06(x)
    y = (x(1) - 10)^3 + (x(2) - 20)^3;
end

To the structure, P.constraint, the name of an m-file which should compute the vector of the G06.m constrain functions must be given.

function [c, ceq] = G06c(x)
    c(1) = -(x(1) - 5)^2 - (x(2) - 5)^2 + 100;
    c(2) = (x(1) - 6)^2 + (x(2) - 5)^2 - 82.81;
    ceq = [];
end

After the objective and constraint functions are passed to the structure P:

>> P.f = 'G06';
>> P.constraint = 'G06c';

The next necessary parameter to be passed is the optimization domain D. G06.m is a second dimension test problem, and domain D should look like a 2x2 matrix:

>> D = [13, 100; 0, 100];

The first column should indicate the lower bounds for x, and the second column the upper bounds. Next, assume that we will use the same OPTS structure we already defined earlier. However, for the algorithm to find a solution with the desired 0.01% error, it needs to specify the solution of the G06.m problem in the OPTS structure.

>> opts.globalmin = -6961.81387512; % Known global solution value

Then, the desired algorithm can be used with the following sequence:

>> [f_min, x_min, history] = dDirect_GLc(P, OPTS, D);

This results in the same iterative sequence of the algorithm as in the previous example in this section. The DIRECT-GLc.m algorithm will terminate after 14 iterations and 1027 objective function evaluations.

This section briefly explains how to use parallel versions of the algorithms. Assume a user wishes to use parallel code for the PLOR algorithm. First, a parallel implementation of the PLOR algorithm parallel_dPlor.m should be chosen. Next, users should specify the number of workers (computational threads). For parallel PLOR, it is reasonable to select 2, as only two potential optimal hyper-rectangles are selected per iteration. In this case, MATLAB parallel pool size should be specified using the parpool command, after which the parallel algorithm should be executed:

>> parpool(2);
>> [f_min, x_min, history] = parallel_dPlor(P, OPTS);

The parpool command default starts the MATLAB pool on the local machine with one worker per physical CPU core. Using parpool(2), we limit the number of workers to 2. After this, the parallel code is executed using both workers. However, it should be considered that creating a parallel parpool takes some time. Therefore, using the parallel PLOR algorithm is inefficient in solving simple problems. Using parallel codes should address higher-dimensionality and more expensive optimization problems. When all necessary calculations in parallel mode are finished, the following command:

>> delete(gcp);

shuts down the parallel pool.

GENDIRECT is a unified framework⁶ that offers a flexible alternative to creating new optimization algorithms. It allows the efficient generation of known and novel DIRECT-type algorithms by assembling different components, surpassing the flexibility of existing toolboxes and individual algorithms. GENDIRECT enables the creation of numerous combinations for customization and further advancements. The following table shows the available parameters in GENDIRECT for constructing DIRECT-type algorithms, with default values shown underlined.

After installing the MATLAB toolbox (using DIRECTGO.mltbx), GENDIRECT can be accessed in the MATLAB command window. Use the following syntax to initiate and run the algorithm:

• Create the GENDIRECT algorithm structure:

>> alg = GENDIRECT();

• The created algorithm alg needs a structured input covering the optimization problem, dimensions, lower and upper bounds, and a target value where relevant. Below is a code snippet showing the configuration of these parameters:

>> alg.Problem.f = 'objfun';      % Objective function 
>> alg.Problem.n = n;             % Dimension
>> alg.Problem.x_L = zeros(n, 1); % Lower bounds 
>> alg.Problem.x_U = ones(n, 1);  % Upper bounds 
>> alg.Problem.fgoal = 0.01;      % Optimal value set as target 
>> alg.Problem.info = false;      % Extract info from problem 

When the alg.Problem.info parameter is set to true, the algorithm gathers comprehensive information about the objective function directly from the objfun problem. This is compatible only with DIRECTGOLib⁵.

• Specify run-time parameters for created algorithm alg, such as maximum number of function evaluations, iterations and enable display of algorithm performance after each iteration:

>> alg.optParam.maxevals = 1000; % Maximal number of evaluations 
>> alg.optParam.maxits = 100;    % Maximal number of iterations
>> alg.optParam.showits = true;  % Show iteration status

• Specify sampling and partitioning strategy

% Method used in original DIRECT algorithm
>> alg.Partitioning.Strategy = 'DTC';
>> alg.Partitioning.SubSides = 'All';

• Design the selection of potentially optimal candidates scheme:

% Method used in original DIRECT algorithm
>> alg.Selection.AggrFuncVal = 'Midpoint'; 
>> alg.Selection.CandMeasure = 'Diagonal'; 
>> alg.Selection.Strategy = 'Original'; 
>> alg.Selection.EqualCand = 'All'; 
>> alg.Selection.SolRefin = 'Min'; 
>> alg.Selection.Ep = 0.0001; 
>> alg.Selection.ControlEp = 'Off'; 
>> alg.Selection.GloballyBased = 'Off'; 
>> alg.Selection.TwoPhase = 'Off';

• Design hybridization scheme:

% Method used in BIRMIN algorithm
>> alg.Hybridization.Strategy = 'Single'; 
>> alg.Hybridization.LocalSearch = 'interior-point';

• Solve the problem and retrieve optimization results:

>> Results = alg.solve;

Results structure contains the optimization outcomes, which include:

1. Results.Fmin - the best-founded objective value;

2. Results.Xmin - solution point;

3. Results.History - history of algorithmic performance during all iterations.

Four scripts in the folder Scripts/TOMS can be used to reproduce results presented in the manuscript: DIRECTGO: A new DIRECT-type MATLAB toolbox for derivative-free global optimization, and given in Results/TOMS folder. The scripts automatically download the required version of DIRECTGOLib for experiments.

• SolveBoxProblems.m - can be used to repeat experiments for box-constrained problems presented in TABLES 3 and 4;
• SolveGeneralProblems.m - can be used to repeat experiments for box-constrained problems presented in TABLE 5;
• SolveGeneralPracticalProblems.m - can be used to repeat experiments for box-constrained problems presented in TABLES 6-10;
• SolveBoxPracticalProblems.m - can be used to repeat experiments for box-constrained problems presented in TABLES 11 and 12.

The script in the folder Scripts/JOGO can be used to reproduce the results presented in the manuscript: An empirical study of various candidate selection and partitioning techniques in the DIRECT framework and given in Results/JOGO folder. The scripts automatically download the required version of DIRECTGOLib for experiments.

• SolveDIRECTGOlib.m - can be used to repeat experiments presented in TABLE 2.

The script in the folder Scripts/JOGO2 can be used to reproduce results presented in the manuscript: Lipschitz-inspired HALRECT algorithm for derivative-free global optimization and given in Results/JOGO2 folder. The scripts automatically download the required version of DIRECTGOLib for experiments.

• SolveHALRECT.m - can be used to repeat experiments presented in TABLES 3 and 4, and FIGURES 8 and 9.

The script in the folder Scripts/MDPI can be used to reproduce results presented in the manuscript: Novel Algorithm for Linearly Constrained Derivative Free Global Optimization of Lipschitz Functions and given in Results/MDPI folder. The scripts automatically download the required version of DIRECTGOLib for experiments.

• SolveDIRECTGOlib.m - can be used to repeat experiments presented in TABLE 1, and FIGURE 6.

The script in the folder Scripts/GEND can be used to reproduce results presented in the manuscript: GENDIRECT: a GENeralized DIRECT-type algorithmic framework for derivative-free global optimization. The scripts automatically download the required version of DIRECTGOLib for experiments.

• ScriptToRun.m - can be used to repeat experiments presented in TABLES 4-7, and FIGURES 4-9.

Please use the following BibTeX entries if you consider citing the DIRECTGO toolbox:

@article{Stripinis2022,
   author    = {Linas Stripinis and Remigijus Paulavi{\v c}ius},
   city      = {New York, NY, USA},
   doi       = {10.1145/3559755},
   issn      = {0098-3500},
   issue     = {4},
   journal   = {ACM Transactions on Mathematical Software},
   month     = {12},
   publisher = {Association for Computing Machinery},
   title     = {DIRECTGO: A New DIRECT-Type MATLAB Toolbox for Derivative-Free Global Optimization},
   volume    = {48},
   url       = {https://doi.org/10.1145/3559755},
   year      = {2022},
}

@misc{Stripinis2022:DirectGOv2.0.0,
    title        = {DIRECTGO: A new DIRECT-type MATLAB toolbox for derivative-free global optimization}, 
    author       = {Linas Stripinis and Remigijus Paulavi{\v c}ius},
    year         = {2022},
    publisher    = {GitHub},
    version      = {v2.0.0},
    howpublished = {\url{https://github.com/blockchain-group/DIRECTGO}},
    note         = {Pre-release v2.0.0}
}

We welcome contributions and corrections to this resource either way:

• By email - send us new problems, corrections, or suggestions by email: linas.stripinis@mif.vu.lt or remigijus.paulavicius@mif.vu.lt.
• GitHub way - fork the GitHub repository, add new algorithms or correct existing ones, then create a pull request, and we gratefully incorporate your contribution!