\documentclass[acmtoms]{acmtrans2m}

\usepackage{psfig}
\usepackage{amssymb} % used for R in Real numbers

% \acmVolume{}
% \acmNumber{}
% \acmYear{}
% \acmMonth{}

\renewcommand{\thefootnote}{\fnsymbol{footnote}}
\renewcommand{\footnoterule}{\hrule}
\renewcommand{\firstfoot}{}
\renewcommand{\runningfoot}{\em}

\begin{document}

\markboth{M.~Gaviano, D.~E.~Kvasov, D.~Lera, and
Ya.~D.~Sergeyev}{GKLS-Generator of Classes of Test Functions: {\it
User Manual}}

\title{GKLS-Generator of Classes of Test Functions\\
with Known Local and Global Minima\\for Global Optimization:\\
USER MANUAL}

\author{MARCO GAVIANO \\ Universit\`{a} di Cagliari, Italy
 \\ DMITRI E. KVASOV \\ Universit\`{a} di Roma ``La Sapienza'',
 Italy, and University of Nizhni Novgorod, Russia
 \\ DANIELA LERA \\ Universit\`{a} di Cagliari, Italy
 \and YAROSLAV D. SERGEYEV\footnote{Corresponding author, e-mail:
 yaro@si.deis.unical.it \newline
 Authors' addresses: M.~Gaviano and D.~Lera, Dipartimento
 di Matematica, Universit\`{a} di Cagliari, Via Ospedale, 72, 09100
 Cagliari -- Italy; D.E.~Kvasov and Ya.D.~Sergeyev, DEIS,
 Universit\`a della Calabria, Via P.Bucci, Cubo 41C, 87036 Rende
 (CS) -- Italy. \newline
 This work has been partially supported by the following projects:
 FIRB RBAU01JYPN, FIRB RBNE01WBBB, and RFBR 01-01-00587.}
 \\ Universit\`{a} della Calabria, Italy,
and University of Nizhni Novgorod, Russia}

\maketitle

\setcounter{page}{0}

\vspace{4mm} \tableofcontents
\newpage

\section{Introduction} \label{sectionIntro}

This {\it User Manual} describes an implementation of the
GKLS-generator. First, the general structure of the package is
presented, then instructions for using the test classes generator
are described. The {\it User Manual} is strongly connected to the
paper~\citeN{Gaviano:et:al.(2003)} (called hereafter {\it paper}).
Particularly, any formulae referenced in the {\it User Manual} are
to be found in the {\it paper}. In the {\it paper}, the user can
find an example of a generated test function also.


\section{Structure of the package} \label{sectionStructure}

The GKLS-generator package has been written in ANSI Standard C and
successfully tested on Windows and UNIX platforms. Our
implementation follows the procedure described in Section~3 of the
{\it paper}.

The package implementing the generator includes the following
files:
 \begin{itemize}
  \item[\bf gkls.c] -- the main file;
  \item[\bf gkls.h] -- the header file that users should include in
  their application projects in order to call subroutines from
  the file {\bf gkls.c};
  \item[\bf rnd\_gen.c] -- the file containing the uniform random number
  generator proposed in Knuth~[\citeyearNP{Knuth(1997)};
  \citeyearNP{Knuth:HomePage}];
  \item[\bf rnd\_gen.h] -- the header file for linkage to the file {\bf
  rnd\_gen.c};
  \item[\bf example.c] -- an example of the GKLS-generator usage;
  \item[\bf Makefile] -- an example of a UNIX makefile provided to
  UNIX users for a simple compilation and linkage of separate files
  of the application project.
 \end{itemize}

For implementation details the user can consult the C codes. Note
that the random number generator in {\bf rnd\_gen.c} uses the
logical-and operation `\&' for efficiency, so it is not strictly
portable unless the computer uses two's complement representation
for integer. It does not limit portability of the package because
almost all modern computers are based on two's complement
arithmetic.

\section{Calling sequence for generation and usage of the tests
classes} \label{sectionInstructions}

Here we describe how to generate and use classes of
non-differentiable (ND-type), differentiable (D-type), and twice
continuously differentiable (D2-type) test functions. Again, we
concentrate on the D-type functions. The operations for the
remaining two types are analogous.

To utilize the GKLS-generator the user must perform the following
steps:
\begin{itemize}
 \item[\bf Step 1.] Input of the parameters defining a specific test class.
 \item[\bf Step 2.] Generating a specific test function of the defined test
 class.
 \item[\bf Step 3.] Evaluation of the generated test function and, if
 necessary, its partial derivatives.
 \item[\bf Step 4.] Memory deallocating.
\end{itemize}
Let us consider these steps in turn.

\subsection{Input of the parameters defining a specific test class}
\label{sectionInput}

This step is subdivided into: (1)~defining the parameters of the
test class, (2)~defining the admissible region $\Omega$, and
(3)~checking (if necessary).

\subsubsection{Defining the parameters of the test class}
The parameters to be defined by the user determine a specific
class (of the ND-, D- or D2-type) of 100 test functions (a
specific function is retrieved by its number). There are the
following parameters:
 \begin{itemize}
  \item[{\it GKLS\_dim}] -- ({\bf unsigned int}) dimension $N$
  (from~(1)) of test functions; $N \geq 2$ (since
  multidimensional problems are considered in~(1)) and
  $N<$ NUM\_RND in {\bf rnd\_gen.h}; this value is limited by the
  power of \mbox{{\bf unsigned int}}-representation; default
  $N=2$;
  \item[{\it GKLS\_num\_minima}] -- ({\bf unsigned int}) number $m$
  (from~(4)) of local minima including the paraboloid $Z$
  minimum (from~(3)) and the global minimum; $m \geq 2$; the
  upper bound of this parameter is limited by the power of
  \mbox{{\bf unsigned int}}-representation;
  default $m=10$;
  \item[{\it GKLS\_global\_value}] -- ({\bf double}) global minimum value $f^*$ of
  $f(x)$; condition~(16) must be satisfied; the default
  value is $-1.0$ (defined in the file {\bf gkls.h} as a constant~GKLS\_GLOBAL\_MIN\_VALUE);

  \item[{\it GKLS\_global\_dist}] -- ({\bf double}) distance $r^*$ from the paraboloid
  vertex $T$ in~(3) to the global minimizer $x^* \in \Omega$
  of $f(x)$; condition~(17) must be
  satisfied; the default value is
  $$
    {\rm GKLS\_global\_dist}\ \stackrel{\rm def}{=} \ \min_{1 \leq j
    \leq N} |  b(j) - a(j) |  /\, 3,
  $$
  where the vectors $a$ and $b$ determine the admissible region
  $\Omega$ in~(2);
  \item[{\it GKLS\_global\_radius}] -- ({\bf double}) radius $\rho ^*$ of the attraction
  region of the global
  minimizer $x^*\in \Omega$ of $f(x)$; condition~(18) must be
  satisfied; the default value is
  $$
    {\rm GKLS\_global\_radius}\ \stackrel{\rm def}{=} \ \min_{1 \leq
    j \leq N} |  b(j) - a(j) |  /\, 6.
  $$
 \end{itemize}
The user may call subroutine \mbox{{\it GKLS\_set\_default}()} to
set the default values of these five variables.

\subsubsection{Defining the admissible region} \label{sectionOmega}
With $N$ determined, the user must allocate dynamic arrays {\it
GKLS\_domain\_left} and {\it GKLS\_domain\_right} to define the
boundary of the hyperrectangle $\Omega$. This is done by calling
subroutine

{\bf int} {\it GKLS\_domain\_alloc} ();\\
which has no parameters and returns the following error codes
defined in~{\bf gkls.h}:
\begin{itemize}
 \item[\bf GKLS\_OK] -- no errors;
 \item[\bf GKLS\_DIM\_ERROR] -- the problem dimension is out of range;
 it must be greater than or equal to 2 and less than NUM\_RND defined
 in {\bf rnd\_gen.h};
 \item[\bf GKLS\_MEMORY\_ERROR] -- there is not enough memory to
 allocate.
\end{itemize}

The same subroutine defines the admissible region $\Omega$. The
default value $\Omega =[-1,1]^N$ is set by \mbox{{\it
GKLS\_set\_default}()}.

\subsubsection{Checking} \label{sectionChecking}
The following subroutine allows the user to check validity of the
input parameters:

{\bf int} {\it GKLS\_parameters\_check} ().\\
It has no parameters and returns the following error codes (see
{\bf gkls.h}):
 \begin{itemize}
  \item[\bf GKLS\_OK] -- no errors;
  \item[\bf GKLS\_DIM\_ERROR] -- problem dimension error;
  \item[\bf GKLS\_NUM\_MINIMA\_ERROR] -- number of local minima error;
  \item[\bf GKLS\_BOUNDARY\_ERROR] -- the admissible region boundary
  vectors are ill-defined;
  \item[\bf GKLS\_GLOBAL\_MIN\_VALUE\_ERROR] -- the global minimum
  value is not less than the paraboloid~(3) minimum value $t$
  defined in {\bf gkls.h} as a constant GKLS\_PARABOLOID\_MIN;
  \item[\bf GKLS\_GLOBAL\_DIST\_ERROR] -- the parameter $r^*$ does not
  satisfy~(17);
  \item[\bf GKLS\_GLOBAL\_RADIUS\_ERROR] -- the parameter $\rho^*$ does not
  satisfy~(18).
 \end{itemize}

\subsection{Generating a specific test function of the defined
test class} \label{sectionGenerating}

After a specific test class has been chosen (i.e., the input
parameters have been determined) the user can generate a specific
function that belongs to the chosen class of 100 test functions.
This is done by calling subroutine

{\bf int} {\it GKLS\_arg\_generate} ({\bf unsigned int} {\it nf}); \\
where
\begin{itemize}
 \item[\it nf] -- the number
 of a function from the test class (from~1~to~100).
\end{itemize}
This subroutine initializes the random number generator, checks
the input parameters, allocates dynamic arrays, and generates a
test function following the procedure of Section~3 of the {\it
paper}. It returns an error code that can be the same as for
subroutines {\it GKLS\_parameters\_check}() and {\it
GKLS\_domain\_alloc}(), or additionally:
\begin{itemize}
 \item[\bf GKLS\_FUNC\_NUMBER\_ERROR] -- the number of a test function to
 generate exceeds 100 or it is less than 1.
\end{itemize}

{\it GKLS\_arg\_generate}() generates the list of all local minima
and the list of the global minima as parts of the structures {\it
GKLS\_minima} and {\it GKLS\_glob}, respectively. The first
structure gathers the following information about all local minima
(including the paraboloid minimum and the global one): coordinates
of local minimizers, local minima values, and attraction regions
radii. The second structure contains information about the number
of global minimizers and their indices in the set of local
minimizers. It has the following fields:
 \begin{itemize}
  \item[\it num\_global\_minima] -- ({\bf unsigned int}) total number of
  global minima;
  \item[\it gm\_index] -- ({\bf unsigned int *}) list of indices of generated
  minimizers, which are the global ones (elements 0 to ($\mbox{\it
  num\_global\_minima} - 1$) of the list) and the local ones
  (the remaining elements of the list).
 \end{itemize}
The elements of the list {\it GKLS\_glob}.{\it gm\_index} are
indices to a specific minimizer in the first structure {\it
GKLS\_minima} characterized by the following fields:
 \begin{itemize}
  \item[\it local\_min] -- ({\bf double **}) list of local minimizers
  coordinates;
  \item[\it f] -- ({\bf double *}) list of local minima values;
  \item[\it rho] -- ({\bf double *}) list of attraction regions radii;
  \item[\it peak] -- ({\bf double *}) list of parameters $\gamma_i$ values
  from~(10);
  \item[\it w\_rho] -- ({\bf double *}) list of parameters $w_i$ values
  from~(23).
 \end{itemize}
The fields of these structures can be useful if one needs to study
properties of a specific generated test function more deeply.

\subsection{Evaluation of a generated test function or its
partial derivatives} \label{sectionEvaluation}

While there exists a structure {\it GKLS\_minima} of local minima,
the user can evaluate a test function (or partial derivatives of
D- and D2-type functions) that is determined by its number (a
parameter to the subroutine {\it GKLS\_arg\_generate}()) within
the chosen test class. If the user wishes to evaluate another
function within the same class he should deallocate dynamic arrays
(see the next subsection) and recall the generator {\it
GKLS\_arg\_generate}() (passing it the corresponding function
number) without resetting the input class parameters (see
subsection~\ref{sectionInput}). If the user wishes to change the
test class properties he should reset also the input class
parameters.

Evaluation of an ND-type function is done by calling subroutine

{\bf double} {\it GKLS\_ND\_func} ({\it x}).\\
Evaluation of a D-type function is done by calling subroutine

{\bf double} {\it GKLS\_D\_func} ({\it x}).\\
Evaluation of a D2-type function is done by calling subroutine

{\bf double} {\it GKLS\_D2\_func} ({\it x}).\\
All these subroutines have only one input parameter
\begin{itemize}
 \item[\it x] -- ({\bf double *}) a point $x \in \mathbb{R} ^N$
 where the function must be evaluated.
\end{itemize}
All the subroutines return a test function value corresponding to
the point $x$. They return the value GKLS\_MAX\_VALUE (defined in
{\bf gkls.h}) in two cases: (a) vector~$x$ does not belong to the
admissible region $\Omega$ and (b) the user tries to call the
subroutines without generating a test function.

The following subroutines are provided for calculating the partial
derivatives of the test functions (see Appendix in the {\it
paper}).

Evaluation of the first order partial derivative of the D-type
test functions with respect to the variable $x_j$
(see~(A.1)--(A.2) in Appendix) is done by calling subroutine

{\bf double} {\it GKLS\_D\_deriv} ({\it j}, {\it x}). \\
Evaluation of the first order partial derivative of the D2-type
test functions with respect to the variable $x_j$
(see~(A.3)--(A.4) in Appendix) is done by calling subroutine

{\bf double} {\it GKLS\_D2\_deriv1} ({\it j}, {\it x}). \\
Evaluation of the second order partial derivative of the D2-type
test functions with respect to the variables $x_j$ and $x_k$ (see
in Appendix the formulae~(A.5)--(A.6) for the case $j \neq k$
and~(A.7)--(A.8) for the case $j = k$) is done by calling
subroutine

{\bf double} {\it GKLS\_D2\_deriv2} ({\it j}, {\it k}, {\it x}). \\
Input parameters for these three subroutines are:
\begin{itemize}
 \item[\it j, k] -- ({\bf unsigned int}) indices of the variables
 (that must be in the range from 1 to {\it GKLS\_dim}) with respect to
 which the partial derivative is evaluated;
 \item[\it x] -- ({\bf double *}) a point $x \in \mathbb{R} ^N$ where
 the derivative must be evaluated.
\end{itemize}
All subroutines return the value of a specific partial derivative
corresponding to the point $x$ and to the given direction. They
return the value GKLS\_MAX\_VALUE (defined in {\bf gkls.h}) in
three cases: (a) index ($j$ or $k$) of a variable is out of the
range [1,{\it GKLS\_dim}]; (b) vector $x$ does not belong to the
admissible region~$\Omega$; (c) the user tries to call the
subroutines without generating a test function.

Subroutines for calculating the gradients of the D- and D2-type
test functions and for calculating the Hessian matrix of the
D2-type test functions at a given feasible point are also
provided. These are

{\bf int} {\it GKLS\_D\_gradient} ({\it x}, {\it g}), \\

{\bf int} {\it GKLS\_D2\_gradient} ({\it x}, {\it g}), \\

{\bf int} {\it GKLS\_D2\_hessian} ({\it x}, {\it h}). \\
Here
\begin{itemize}
 \item[\it x] -- ({\bf double *}) a point $x \in \mathbb{R} ^N$
 where the gradient or Hessian matrix must be evaluated;
 \item[\it g] -- ({\bf double *}) a pointer to the gradient vector
 calculated at {\it x};
 \item[\it h] -- ({\bf double **}) a pointer to the Hessian matrix
 calculated at {\it x}.
\end{itemize}
Note that before calling these subroutines the user must allocate
dynamic memory for the gradient vector {\it g} or the Hessian
matrix {\it h} and pass the pointers {\it g} or {\it h} as
parameters of the subroutines.

These subroutines call the subroutines described above for
calculating the partial derivatives and return an error code ({\bf
GKLS\_DERIV\_EVAL\_ERROR} in the case of an error during
evaluation of a particular component of the gradient or the
Hessian matrix, or {\bf GKLS\_OK} if there are no errors).

\subsection{Memory deallocating} \label{sectionMemory}

When the user concludes his work with a test function he should
deallocate dynamic arrays allocated by the generator. This is done
by calling subroutine

{\bf void} {\it GKLS\_free} ({\bf void});\\
with no parameters.

When the user abandons the test class he should deallocate dynamic
boundaries vectors {\it GKLS\_domain\_left} and {\it
GKLS\_domain\_right} by calling subroutine

{\bf void} {\it GKLS\_domain\_free} ({\bf void});\\
again with no parameters.

It should be finally highlighted that if the user, after
deallocating memory, wishes to return to the same class,
generation of the class with the same parameters produces the same
100 test functions.

An example of the generation and use of some of the test classes
can be found in the file {\bf example.c}.

\bibliographystyle{acmtrans}
\bibliography{UserManual}

\label{@lastpg}

\end{document}