\subsection{The \texttt{GRAD:} module}

The {\tt GRAD:} module is designed to perform the following tasks:
\begin{itemize}
\item compute the gradients of the {\sl system characteristics} using solutions of direct or adjoint
fixed source eigenvalue problems. Here, we assume an optimization problem with \dusa{nvar} control variables and
with \dusa{ncst} constraints. The total number of system characteristics is therefore equal to \dusa{ncst}$+1$.

\item define options and parameters for the different method to solve the optimization problem. The non-linear
optimization problem can be solved as a converging sequence of linear optimization problems with a quadratic constraint
of the form
$$
\sum_{i=1}^{\sl nvar} \omega_i \left( \Delta x_i^{(n)}\right)^2 \le \left( S^{(n)}\right)^2
$$
\noindent where $\omega_i$ is a weight defined after keyword \moc{CST-WEIGHT} and $\Delta x_i^{(n)}$ is a displacement for
$i$--th control variable at iteration $(n)$. The initial value of radius $S^{(1)}$ is defined after keyword \moc{OUT-STEP-LIM}.

\item reduces the radius $S^{(n)}$ of the quadratic constraint.
\end{itemize}

\vskip 0.08cm

The calling specifications are:

\begin{DataStructure}{Structure \moc{GRAD:}}
\dusa{OPTIM} \moc{:=} \moc{GRAD:} $[$ \dusa{OPTIM} $]$ \dusa{DFLUX} \dusa{GPT} \moc{::} \dstr{grad\_data}
\end{DataStructure}

\noindent where

\begin{ListeDeDescription}{mmmmmmmm}

\item[\dusa{OPTIM}] \texttt{character*12} name of the \dds{optimize} object ({\tt L\_OPTIMIZE} signature) containing the
optimization informations. Object \dusa{OPTIM} must appear on the RHS to be able to updated the previous values.

\item[\dusa{DFLUX}] \texttt{character*12} name of the \dds{flux} object ({\tt L\_FLUX} signature) containing a set of
solutions of fixed-source eigenvalue problems.

\item[\dusa{GPT}] \texttt{character*12} name of the \dds{gpt} object ({\tt L\_GPT} signature) containing a set of
direct or adjoint sources.

\item[\dstr{grad\_data}] structure containing the data to the module \texttt{GRAD:} (see Sect.~\ref{sect:grad_data}).

\end{ListeDeDescription}
\vskip 0.2cm

\subsubsection{Data input for module \texttt{GRAD:}}\label{sect:grad_data}

\begin{DataStructure}{Structure \moc{grad\_data}}
$[$ \moc{EDIT} \dusa{iprint} $]$ \\
$[$ \moc{METHOD} \{ \moc{SIMPLEX} $|$ \moc{LEMKE} $|$ \moc{MAP} $|$ \moc{AUG-LAGRANG} $|$ \moc{PENAL-METH} \} $]$ \\
$[$ \moc{OUT-STEP-LIM} \dusa{sr} $]$ \\
$[$ \moc{OUT-STEP-EPS} \dusa{$\epsilon_{ext}$} $]~[$ \moc{INN-STEP-EPS} \dusa{$\epsilon_{inn}$} $]$ \\
$[$ \moc{CST-QUAD-EPS} \dusa{$\epsilon_{quad}$} $]$ \\
$[~\{$ \moc{MAXIMIZE} $|$ \moc{MINIMIZE} $\}~]$ \\
$[$ \moc{STEP-REDUCT} $\{$ \moc{HALF} $|$ \moc{PARABOLIC} $\}~]$ \\
$[$ \moc{VAR-VALUE} ( \dusa{control}(i), i=1,\dusa{nvar} ) $]~[$ \moc{VAR-WEIGHT} ( \dusa{weight}(i), i=1,\dusa{nvar} ) $]$ \\
$[$ \moc{VAR-VAL-MIN} $\{$ ( \dusa{vecmin}(i), i=1,\dusa{nvar} ) $|$ \moc{ALL} \dusa{varmin} $]$ \\
$[$ \moc{VAR-VAL-MAX} $\{$ ( \dusa{vecmax}(i), i=1,\dusa{nvar} ) $|$ \moc{ALL} \dusa{varmax} $]$ \\
$[$ \moc{FOBJ-CST-VAL} ( \dusa{funct}(i), i=1,\dusa{ncst}$+1$ ) $]$ \\
$[$ \moc{CST-TYPE} ( \dusa{type}(i), i=1,\dusa{ncst} ) $]~[$ \moc{CST-OBJ} ( \dusa{cstval}(i), i=1,\dusa{ncst} ) $]$ \\
$[$ \moc{CST-WEIGHT} ( \dusa{cstw}(i), i=1,\dusa{ncst} ) $]$ \\
;
\end{DataStructure}

\noindent where
\begin{ListeDeDescription}{mmmmmmmm}

\item[\moc{EDIT}] keyword used to set \dusa{iprint}.

\item[\dusa{iprint}] index used to control the printing in module.

\item[\moc{METHOD}] keyword used to define the quasi-linear programming method. {\bf Note:} If the general Lemke method is
used, the quadratic constraint must be active. The strategy consists to proceed in two steps:
\begin{itemize}
\item At first step, the linear programming problem
(i. e., without the quadratic contraint) is solved and the control-variable displacement is computed. If this displacement is less
than the radius of the quadratic constraint, the step one solution is accepted and step two is not performed. If this displacement is greater
than the radius of the quadratic constraint, the step one solution is rejected and step two is performed. Step one can be
solved with the SIMPLEX method or with the linear LEMKE method.
\item At step two, the general LEMKE method is used to find the correct solution. The general Lemke method is based on a parametric linear
complementarity principle, as explained in Ref.~\citen{ferland}.
\end{itemize}

\item[\moc{SIMPLEX}] keyword used to specify that the SIMPLEX method will be used at step one and the general LEMKE method at step two.

\item[\moc{LEMKE}] keyword used to specify that the linear LEMKE method will be used at step one and the general LEMKE method at step two.

\item[\moc{MAP}] keyword used to specify that the MAP method will be used. The quadratic constraint is linearized and a converging sequence
of SIMPLEX calculations is performed.

\item[\moc{AUG-LAGRANG}] keyword used to specify that the augmented Lagrangian method will be used.

\item[\moc{PENAL-METH}] keyword used to specify that the penalty method will be used.

\item[\moc{OUT-STEP-LIM}] keyword used to set the initial radius of the quadratic constraint (default value is \dusa{sr} $=1.0$).

\item[\dusa{sr}] initial radius of the quadratic constraint (real).

\item[\moc{OUT-STEP-EPS}] keyword used to set the tolerance of outer iteration convergence inside module {\tt PLQ:}.

\item[\dusa{$\epsilon_{ext}$}] tolerance value (real).

\item[\moc{INN-STEP-EPS}] keyword used to set the tolerance used within the SIMPLEX or LEMKE method.

\item[\dusa{$\epsilon_{inn}$}] tolerance value (real).

\item[\moc{CST-QUAD-EPS}] keyword to set the convergence parameter \dusa{epsilon4} for the radius of the quadratic constraint inside module {\tt GRAD:}.

\item[\dusa{$\epsilon_{quad}$}] tolerance for convergence of the radius of the quadratic constraint (real).

\item[\moc{MAXIMIZE}] keyword used to specify that the optimization problem will be a maximization.

\item[\moc{MINIMIZE}] keyword used to specify that the optimization problem will be a minimization (default).

\item[\moc{STEP-REDUCT}] keyword used to define the method of the reduction of the outer step.

\item[\moc{HALF}] keyword used to specify that the step will be reduced by a factor of 2.

\item[\moc{PARABOLIC}] keyword used to specify that the step will be reduced with the parabolic method.

\item[\moc{VAR-VALUE}] keyword to specify the values of the control variables. These values can also be set in a previous call
to module {\tt GRAD:} or set in another module.

\item[\dusa{control}] array containing \dusa{nvar} real values.

\item[\moc{VAR-WEIGHT}] keyword to specify the values of the control variable weights in the quadratic constraint. All weights
are set to 1.0 by default.

\item[\dusa{weight}] array containing \dusa{nvar} real values.

\item[\moc{VAR-VAL-MIN}] keyword to specify the minimum values of the control variables. These values can also be set in a previous call
to module {\tt GRAD:}.

\item[\dusa{vecmin}] array containing \dusa{nvar} real values.

\item[\dusa{varmin}] single real value used for all control variables.

\item[\moc{VAR-VAL-MAX}] keyword to specify the maximum values of the control variables. These values can also be set in a previous call
to module {\tt GRAD:}.

\item[\dusa{vecmax}] array containing \dusa{nvar} real values.

\item[\dusa{varmax}] single real value used for all control variables.

\item[\moc{FOBJ-CST-VAL}] keyword to specify the value of the objective function followed by the actual values of the constraints. These values can also be set in a previous call
to module {\tt GRAD:} or set in another module.

\item[\dusa{funct}] array containing \dusa{ncst}$+1$ real values.

\item[\moc{CST-TYPE}] keyword to specify the relation types of the constraints. These values can also be set in a previous call
to module {\tt GRAD:}.

\item[\dusa{type}] array containing \dusa{ncst} integer values. These values are: $=-1$ for $\ge$, $=0$ for equalily and $=1$
for $\le$.

\item[\moc{CST-OBJ}] keyword to specify the RHS values of the constraints. These values can also be set in a previous call
to module {\tt GRAD:}.

\item[\dusa{cstval}] array containing \dusa{ncst} real values.

\item[\moc{CST-WEIGHT}] keyword to specify the weights (or penalties) of the constraints. These weights are not used with
Lemke or MAP methods. These values can also be set in a previous call to module {\tt GRAD:}.

\item[\dusa{cstw}] array containing \dusa{ncst} real values.

\end{ListeDeDescription}
\clearpage
