<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">%=====================================================================
\section{The ZAIC Tools for Building One-Variable IvP Functions}
%=====================================================================
\wikisec{grp=extend,file=ZAICTools,short=ZAIC Tools}
\label{sec_bldu_zaics}
\index{ZAIC Tools}
\index{ZAIC Tools!General Properties}

The \var{ZAIC} tools are part of the IvP Build Toolbox for
facilitating the building of IvP functions over a single domain
variable. There are three tools - \zpeak, {\zheq}, {\zleq}, and
{\zvec}. To use the tools, in short, one creates a instance of the
corresponding class, sets some parameters, and then extracts an IvP
function. The tools described in Section \ref{sec_bldu_reflector} for
n-variable functions can also be used for building one-variable
functions but are perhaps overkill for certain classes of common
one-variable functions that motivated the \var{ZAIC} tools. The term
\var{ZAIC} is not an acronym, but merely a play on the word mosaic.

%=====================================================================
\subsection{The {\zpeak} Tool}
\index{ZAIC\_PEAK Tool}

%---------------------------------------------------------------------
\subsubsection{Brief Overview}
\label{sec_zaic_peak}

The {\zpeak} tool is designed with the objective function shown in
Figure \ref{zaic-peak-fig} in mind. There is a identifiable preferred
single decision choice (the \summit) with maximum utility, and then a
gradual drop in utility as the variable value varies from the
preferred choice.

\vspace{0.15in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.96\textwidth]{figs_ivpbuild/zaic_peak_a_labels.png}
  \caption{{\bf The {\zpeak} tool}: defines an IvP function over one
    variable defined by the six parameters shown here. In the case
    rendered here, the tool would create an IvP function with six
    pieces. The function rendered was created with \vvar{summit=180},
    \vvar{peakwidth=85}, \vvar{basewidth=70}, \vvar{maxutil=150},
    \vvar{minutil=25}, \vvar{summitdelta=40}.}
\label{zaic-peak-fig}
\end{figure}
\vspace{0.1in}

The form in which the utility drops is dependent on the settings of
the six parameters shown in the figure. The \summit, \pwid, and
{\bwid} values are given in units native to the decision variable,
while the \sdelta, \minu, and {\maxu} values are given in terms of
units of utility. 

%---------------------------------------------------------------------
\subsubsection{The {\zpeak} Parameters and Function Form}
\index{ZAIC\_PEAK Tool!Interface}

\noindent
The \var{ZAIC\_PEAK} tool accepts six parameters in defining
$f(x)$. The \var{summit} parameter is the point of maximum
utility. The \var{minutil} parameter is the minimum value of $f(x)$,
with a default value of zero. The \var{maxutil} is the maximum value
of $f(x)$, with a default value of 100. The utility of the function
drops off linearly in two stages. In the first stage the utility drops
linearly off from the \var{maxutil} to \var{maxutil-summitdelta}, and
in the second stage it drops off linearly from
\var{maxutil-summitdelta} to \var{minutil}. The function has the form:

\small
%\wikihint{width=550}
\begin{align*}
  f(x) &amp;= \begin{cases}
    f_1(x)        &amp; ({\tt summit} - {\tt peakwidth}) \leq x \leq {\tt summit},  \\
    f_2(x)        &amp; ({\tt summit} - {\tt peakwidth} - {\tt basewidth}) \leq x &lt; 
                    ({\tt summit} - {\tt peakwidth} ),  \\
    f_3(x)        &amp; {\tt summit} &lt; x \leq ({\tt summit} + {\tt peakwidth}),  \\
    f_4(x)        &amp; ({\tt summit} + {\tt peakwidth}) &lt; x \leq 
                    ({\tt summit} + {\tt peakwidth} + {\tt basewidth}),  \\
    {\tt minutil} &amp; \text{otherwise}.
  \end{cases} \\
\end{align*}
\normalsize

\noindent
where

\footnotesize
\wikihint{width=640}
\begin{align*}
f_1(x) &amp; = ({\tt maxutil}-{\tt summitdelta}) + ({\tt summitdelta} * ((x-({\tt summit}-{\tt peakwidth})) / {\tt peakwidth})) \\
f_2(x) &amp; = {\tt minutil} + (({\tt maxutil}-{\tt minutil}-{\tt summitdelta}) * 
         ((x-({\tt summit}-{\tt peakwidth}-{\tt basewidth}))/{\tt basewidth})) \\
f_3(x) &amp; = ({\tt maxutil}-{\tt summitdelta}) + ({\tt summitdelta} * ((({\tt summit}+{\tt peakwidth})-x) / {\tt peakwidth})) \\
f_4(x) &amp; = {\tt minutil} + (({\tt maxutil}-{\tt minutil}-{\tt summitdelta}) * 
         ((({\tt summit}+{\tt peakwidth}+{\tt basewidth})-x)/{\tt basewidth})) \\
\end{align*}
\normalsize


%case 0:   x = summit
%case 1: summit &lt; x \leq (summit+peakwidth)
%Case 2: (summit+peakwidth) &lt; x \leq (summit+peakwidth+basewidth)
%Case 3: (summit-peakwidth) \leq x &lt; summit
%case 4: (summit-peakwidth-basewidth) \leq x &lt; (summit-peakwidth)
%case 5: otherwise

%case 0: f(x) = maxutil
%case 1: f(x) = (max-SD) + (SD * (((SV+PW)-x) / PW))
%Case 2: f(x) = min + ((max-min-SD) * (((SV+PW+BW)-x)/BW))
%Case 3: f(x) = (max-SD) + (SD * ((x-(SV-PW)) / PW))
%case 4: f(x) = min + ((max-min-SD) * ((x-(SV-PW-BW))/BW))


\noindent
To correlate the above five cases above with the six pieces in Figure
\ref{zaic-peak-fig}, $f_1(x)$ is piece \var{\#3}, $f_2(x)$ is piece
\var{\#2}, $f_3(x)$ is piece \var{\#4}, $f_4(x)$ is piece \var{\#5},
\var{minutil} for pieces \var{\#1} and \var{\#6}. The two stage linear
drop-off in utility is there to allow the shape of the function to
approximate convex or concave functions as shown in Figure
\ref{pzaic-one}.

\vspace{0.1in}

\noindent
\begin{figure}[H]
  \centering 
  \includegraphics[width=1.0\textwidth]{figs_ivpbuild/zaic_peak_concave_convex.png}
  \caption{{\bf The \vvar{ZAIC\_PEAK} tool:} A convex uni-modal
    function (left) and a non-convex uni-modal function (right).}
  \label{pzaic-one}
\end{figure}

%---------------------------------------------------------------------
\subsubsection{The {\zpeak} Interface Implementation}
\label{zaic_peak_interface}
\index{ZAIC\_PEAK Tool!Interface}

The following functions define the interface to the {\zpeak} tool. In
constructing and setting parameters, the instance maintains a Boolean
flag indicating if any fatal configuration errors were detected. In
such cases, a warning string is generated for optional retrieval, and
the error renders the instance effectively useless, never yielding an
IvP function when requested. 

Many of the below functions take an optional \var{index} parameter.
This is used for creating functions with multiple modes or peaks as
described in Section \ref{sec_zpeak_multi}. The default value is zero,
or the zeroth index, when only one mode or peak is being implemented.
If the given index references a non-existing component, this is
considered a fatal configuration error. Example usage is provided in
Listing \ref{lst_zaic_peak}.

\index{ZAIC\_PEAK Tool!\var{summit} parameter}

\begin{packed_itemize}[2]
\item \func{bool setSummit(double val, int index=0)}: Sets the
  {\summit} value of the component at the given index. If no index
  parameter is provided, the index is zero. If the summit value is
  outside the range of the domain, it is clipped to the appropriated
  end. For example if the domain were [0,359] as the example in
  Figure \ref{zaic-peak-fig}, and the requested summit value were
  550, the summit parameter would be set to 359. This is therefore
  not regarded as a fatal configuration error, but a warning would be
  generated anyway. This returns false only if index referencing
  a non-existent component is provided.

\index{ZAIC\_PEAK Tool!\var{peakwidth} parameter}
\item \func{bool setPeakWidth(double val, int index=0)}: Sets the
  peakwidth value of the component at the given index. If no index
  parameter is provided, the index is zero.

\index{ZAIC\_PEAK Tool!\var{basewidth} parameter}
\item \func{bool setBaseWidth(double val, int index=0)}: Sets the
  basewidth value of the component at the given index. If no index
  parameter is provided, the index is zero.

\index{ZAIC\_PEAK Tool!\var{summitdelta} parameter}
\item \func{bool setSummitDelta(double val, int index=0)}: Sets the
  {\sdelta} value of the component at the given index. If no index
  parameter is provided, the index is zero. A fatal error is declared
  and false is returned if the index is out of range, or if the
  value is less than zero. Otherwise true is returned. If the
  sumitdelta value is greater than the range determined by
  \var{maxutil} - \var{minutil}, this is not interpreted as a fatal
  error, but the {\sdelta} is clipped to the range.

\index{ZAIC\_PEAK Tool!\var{maxutil} parameter}
\index{ZAIC\_PEAK Tool!\var{minutil} parameter}
\item \func{bool setMinMaxUtil(double min, double, max, int index=0)}:
  Sets the minutil and maxutil values of the component at the given
  index. If no index parameter is provided, the index is zero. A fatal
  error is declared and false is returned if the index is out of
  range, or if the min value is greater than or equal to the max
  value. Otherwise true is returned. If the existing {\sdelta}
  value is greater than the range determined by \var{maxutil} -
  \var{minutil}, this is not interpreted as a fatal error, but the
      {\sdelta} is clipped to the range.

\item \func{bool setParams(double summit, double peakwidth, double
  basewidth, double summitdelta, \\ double minutil, double maxutil,
  int index=0}:: Sets the six configuration parameters \summit, \pwid,
  \bwid, \sdelta, {\minu} and {\maxu} all at once.  If the
  \var{summitdelta} value is greater than the range determined by
      {\maxu} - {\minu}, this is not interpreted as a fatal error, but
      the {\sdelta} is clipped to the range.

\index{ZAIC\_PEAK Tool!\var{summitinsist} parameter}
\item \func{void setSummitInsist(bool val)}: 
  Sets the {\sumi} flag to the given value. The default is true.
  See Section \ref{sec_wrap_insist} for more on this parameter.

\index{ZAIC\_PEAK Tool!\var{valuewrap} parameter}
\label{lab_valuewrap}
\item \func{void setValueWrap(bool val)}: 
  Sets the {\vwrap} flag to the given value. The default is
  false.  See Section \ref{sec_wrap_insist} for more on this
  parameter.


\item \func{int addComponent()}: Allocates a new component and returns
  the index of the new component.  Since the first component exists
  upon \var{ZAIC} creation, the first call to this function will
  return 1, and will result in the {\zpeak} instance having
  two components at index 0 and 1.  The default values for the new
  component are {\summit}=0, {\pwid}=0, {\bwid}=0, {\sdelta}=50,
  {\minu}=0, {\maxu}=100.

\index{ZAIC\_PEAK Tool!Extracting an \var{IvPFunction}}
\item \func{IvPFunction* extractIvPFunction(bool maxval=true)}: This
  function generates a new IvP function based on the prevailing
  parameter settings at the time of invocation. If a fatal error was
  detected in prior parameter setting attempts, this function will
  simply return the NULL pointer. When the IvP function is extracted
  from the ZAIC, an \var{IvPFunction} instance is created from the
  heap that needs to be later deleted. The ZAIC tool does not delete
  this. It is the responsibility of the caller. Typically this tool is
  used within a behavior, and the behavior passes the IvP function to
  the helm and the helm deletes all IvP functions.

\item \func{string getWarnings()}: When or if fatal (or non-fatal)
  problems are encountered in setting the parameters, the tool appends
  a message to a local warning string. This string can be retrieved by
  this function. A non-empty string does not necessarily mean a fatal
  configuration error was encountered. Instead, the \var{stateOK()}
  function below should be consulted.

\item \func{bool stateOK()}: This function returns true if no
  fatal errors were encountered during configuration attempts,
  otherwise it returns false. If an error has been encountered,
  this state cannot be reversed. The instance has been rendered
  effectively useless. To gain insight into the nature of the error,
  the \var{getWarnings()} function above can be consulted.

\end{packed_itemize}

%--------------------------------------------------------------------
\subsubsection{The Value-Wrap and Summit-Insist Parameters}
\label{sec_wrap_insist}
\index{ZAIC\_PEAK Tool!\var{valuewrap} parameter}
\index{ZAIC\_PEAK Tool!\var{summitinsist} parameter}

Two additional Boolean parameters may be set for an instance of
{\zpeak}.  They are the {\vwrap} and {\sumi} parameters set with the
following functions with the defaults shown:

\small
\begin{verbatim}
    zaic.setValueWrap(false);     // Default value is false
    zaic.setSummitInsist(true);   // Default value is true
\end{verbatim}
\normalsize

\noindent
When the \var{valuewrap} parameter is true, the utility associated
with the domain variable value "wraps" around. For example, if the
domain variable is the vehicle {\em heading}, which may have the
domain [0, 359], a value of 10 degrees is evaluated as being only 20
degrees different from 350, rather than being different by 330
degrees. The two functions depicted in Figure \ref{pzaic-two} differ
only in the setting of the \var{valuewrap} parameter.

\begin{figure}[H]
  \centering 
  \includegraphics[width=1.0\textwidth]{figs_ivpbuild/zaic_peak_wrap_wrapno.png}
  \caption{{\bf The \vvar{valuewrap} parameter in the
      \vvar{ZAIC\_PEAK} tool:} A function generated with
    \var{valuewrap=false} on the left, and function generated with
    \vvar{valuewrap=true} and otherwise identical parameters on the
    right.}
\label{pzaic-two}
\end{figure}

\vspace{0.15in}
The value of the \var{summitinsist} parameter can affect the generated
objective function in the following two scenarios. In the first case,
consider the domain to be the possible headings with 360 discrete
choices [0, 359], and the {\pwid} and {\bwid} are both zero. If the
{\summit} were then set to 90.25, one way to interpret this is that
all 360 discrete heading choices have a utility of zero, since none
are equal exactly to 90.25. This is the interpretation when {\sumi}
is false. When set to true, the same set of parameters would
generate an objective function that ranked the heading of 90 degrees
with maximum utility and all other heading choices with the minimum
utility (an IvP function with 3 pieces, i.e., intervals). In the
second case, consider the domain to be possible speeds with 31
discrete choices [0, 3.0], with the {\summit} set to 4.0 with a
peakwidth and basewidth of 0.25.  The \var{ZAIC\_PEAK} tool would
generate an objective function ranking all speeds equally with the
minimum utility when {\sumi} is set to false. When set to
true, the \var{ZAIC\_PEAK} tool would generate an objective
function ranking the highest speed in the domain (3.0) with maximum
utility (\var{maxutil}), and all other speeds with minimum utility
(\var{minutil}). The default setting is \var{summitinsist=true} since
this seems the more reasonable thing to do in most such cases.
\index{ZAIC\_PEAK Tool!\var{summitinsist} parameter}

%---------------------------------------------------------------------
\subsubsection{Using the {\zpeak} Tool}
\label{sec_zpeak_usage}
\index{ZAIC\_PEAK Tool!Example Usage}

\noindent
Usage of the \var{ZAIC\_PEAK} tool boils down to the following four
steps.

\begin{packed_itemize}[2]
\item Step 1: Create the IvP domain, or retrieve it if otherwise
  already created.
\item Step 2: Create the {\zpeak} instance with a domain and
  domain variable.
\item Step 3: Set the {\zpeak} parameters. 
\item Step 4: Extract the IvP function.
\end{packed_itemize}

\vspace{0.1in}
\noindent
A code example of the four steps is provided in Listing
\ref{lst_zaic_peak} below. This code example describes a function that
builds and returns an IvP function using the {\zleq} tool. It is not
too different from the activity inside a typical implementation of
\var{onRunState} in an IvP behavior.

\vspace{0.25in}
\begin{listing}{Example usage of the \var{ZAIC\_Peak} tool corresponding to Figure \ref{zaic-peak-fig}}
\label{lst_zaic_peak}
\scriptsize
\begin{verbatim}
  1  IvPFunction *buildIvPFunction()
  2  {
  3    // Step 1 - Create the IvPDomain, the function's domain
  4    IvPDomain domain;
  5    domain.addVar("depth", 0, 600, 601);
  6  
  7    // Step 2 - Create the ZAIC_PEAK with the domain and variable name
  8    ZAIC_PEAK  zaic_peak(domain, "depth");
  9  
 10    // Step 3 - Configure the ZAIC_LEQ parameters
 11    zaic_peak.setSummit(150);
 12    zaic_peak.setMinMaxUtil(20, 120);
 13    zaic_peak.setBaseWidth(60);
 14  
 15    // Step 4 - Extract the IvP function
 16    IvPFunction *ivp_function = 0;
 17    if(zaic_leq.stateOK())
 18      ivp_function = zaic_peak.extractIvPFunction();
 19    else
 20      cout &lt;&lt; zaic_peak.getWarnings();
 21    return(ivp_function)     
\end{verbatim}
\end{listing}
\normalsize
\vspace{0.1in}

\noindent
The lines comprising step 4 (lines 15-20) are conservative in that
they first check to see if no fatal configuration errors were
encountered, and writes the warnings to the terminal if found. It
does not even attempt to extract an IvP function if an error was
encountered. These five lines could have been replaced by one line:

\vspace{0.1in}
\small
\begin{verbatim}
   return(zaic_peak.extractIvPFunction());
\end{verbatim}
\normalsize
\vspace{0.1in}

\noindent
This is simpler, but the warning information is potentially
useful. When the \var{ZAIC\_PEAK} tool is used within an IvP behavior,
the warnings can be posted to the MOOSDB in the variable
\var{BHV\_WARNING} which is monitored by other tools.

%---------------------------------------------------------------------
\subsubsection{Support for Multi-Modal Functions with the {\zpeak} Tool}
\label{sec_zpeak_multi}
\index{ZAIC\_PEAK Tool!Multi-Modal Functions}

The {\zpeak} tool will allow additional components to be added to
provide a multi-modal effect. A {\em component} refers to the set of
six parameters \summit, \pwid, \bwid, \sdelta, \minu, \maxu. Adding a
second component creates a multi-modal function as shown in Figure
\ref{mmode-double}.

\vspace{0.15in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.8\textwidth]{figs_ivpbuild/mmode-double.png}
  \caption{{\bf Multiple modes with the {\zpeak} tool}: additional
    components can be added to create a multi-modal objective
    function. Each component is comprised of the six parameters
    \summit, \pwid, \bwid, \sdelta, \minu, and \maxu.}
\label{mmode-double}
\end{figure}
\vspace{0.1in}

\noindent
Listing \ref{lst_zaic_mpeaks} shows how this is done. In lines 2-3,
the {\zpeak} instance is created and the parameters are set for the
first component. A second component is allocated in line 5 with the
call to \func{addComponent()} which returns the index of the newly
created component. This index is passed as the last argument to the
function call on line 6 to clarify that the parameters are to be
applied to the second component (at index 1).

\vspace{0.2in}
\begin{listing}{Using the {\zpeak} tool to build and return a multi-mode IvP Function}
\label{lst_zaic_mpeaks}
\scriptsize
\begin{verbatim}
  1  IvPFunction *buildIvPFunction(IvPDomain domain, string varname)
  2  {
  3    ZAIC_PEAK zaic(domain, varname);
  4    zaic.setParams(300, 80, 100, 15, 0, 100);  // No index given - assumed to be zero.
  5    
  6    int index = zaic.addComponent();
  7    zaic.setParams(600, 130, 35, 30, 0, 147, index); // Last param is component index
  8
  9    zaic.setValueWrap(false);     // Not component specific - no index given
 10    zaic.setSummitInsist(true);   // Not component specific - no index given
 11    bool take_the_max = true
 12    IvPFunction *ipf = zaic.extractIvPFunction(take_the_max);
 13    return(ipf);
 14  }
\end{verbatim}
\end{listing}
\normalsize
\vspace{0.12in}

When the IvP function is extracted from the {\zpeak}, in line 9, the
composition of the multiple components can be interpreted in one of
two ways - by taking the {\em maximum} or the {\em sum} of the two
components. In the former, the combined utility is the maximum of the
values given by the individual components. In the latter the combined
utility is the sum of the individual components. The
\var{extractIvPFunction(bool)} function on line 11 will return a
composition based on taking the max if passed true, and will
take the sum otherwise. The default (if no value is passed) is
true. The difference between the two extractions is shown in
Figure \ref{mmode-combine} for the two components shown in Figure
\ref{mmode-double}.


\vspace{0.2in}
\begin{figure}[H]
  \includegraphics[width=1.0\textwidth]{figs_ivpbuild/mmode-combine.png}
  \caption{{\bf Options for combining components}: On the left is the
    result of combining the two components in Figure
    \ref{mmode-double} by using the max value from the two
    components. On the right is the result of combining the two
    components by using the sum of the values from the two
    components.}
  \label{mmode-combine}
\end{figure}
\vspace{0.15in}

All component parameter-setting functions defined for the {\zpeak}
class take an optional final argument indicating the intended
component index. If the argument is not provided, it is assumed to be
zero, the index of the one component created automatically when the
{\zpeak} instance is created. The default values of a newly added
component are are {\summit}=0, {\pwid}=0, {\bwid}=0, {\sdelta}=50,
{\minu}=0, {\maxu}=100. The {\vwrap} and {\sumi} parameters are not
component-specific parameters, and therefore are only called once on a
particular {\zpeak} instance, and do not have an optional index
parameter.


%\subsection{Detection of ZAIC Tool Usage Errors}%

%There are a few ways the {\zpeak} tool can be erroneously
%configured. In some cases, the erroneous configuration is handled by
%adjusting the user-provided parameters to something reasonable, and in
%other cases the attempted setting results in a error after which the
%tool will not generate an objective function.

%\newpage
\subsection{The {\zleq} and {\zheq} Tools}
\index{ZAIC\_LEQ Tool}
\index{ZAIC\_HEQ Tool}

%---------------------------------------------------------------------
\subsubsection{Brief Overview}
The \var{ZAIC\_LEQ} tool is used for generating IvP functions where
there is a constant, maximum utility associated with a decision
variable whose value is kept {\em less than or equal} to (LEQ) a given
value. For example if a UUV component is known to work reliably up to
a certain depth, or if a vehicle's speed is to be kept below a certain
value to prevent interference with another sensor or communications
equipment.  The \var{ZAIC\_LEQ} tool allows for expressing a linear
drop-off in utility between two values. For example, if the fictional
UUV component is rated to a depth of 200 meters, the utility function
may have a maximum utility for depths up to 150 meters and minimum
utility at 210 meters as in the example in Figure \ref{zaic-leq-fig}.

\vspace{0.18in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.9\textwidth]{figs_ivpbuild/zaic_leq_a_labels.png}
  \caption{{\bf The \vvar{ZAIC\_LEQ} tool}: facilitates building
    simple 2-3 piece piecewise defined utility functions over a single
    decision variable whose value is to be kept less than or equal to
    a given value. It accepts four parameters, the \vvar{summit},
    \vvar{minutil}, \vvar{maxutil}, \vvar{basewidth}. In the figure
    \vvar{summit}=150, \vvar{minutil}=20, \vvar{maxutil}=120,
    \vvar{basewidth}=60.}
\label{zaic-leq-fig}
\end{figure}
\vspace{0.15in}

Likewise, the {\zheq} tool is used for generating objective functions
where there is a constant, maximum utility associated with a decision
variable whose value is kept {\em greater than or equal} to (HEQ) a
given value. These two tools have a similar interface.  Most of what
is described below for one tool applies to the other. The differences
are distinguished in Section \ref{sec_zheq}. The IvP functions
generated by these ZAIC tools have a small footprint, having either
two or three pieces.

%---------------------------------------------------------------------
\subsubsection{The {\zleq} Parameters and Function Form}
\label{sec_zleq_params}

\index{ZAIC\_LEQ Tool!Interface}
\noindent
The \var{ZAIC\_LEQ} tool accepts four parameters in defining
$f(x)$. The \var{summit} parameter is the point where maximum utility
begins to drop off. The \var{minutil} parameter is the minimum value
of $f(x)$, with a default value of zero. The \var{maxutil} is the
maximum value of $f(x)$, with a default value of 100. The function has
the form:

\small
%\wikihint{width=450}
\begin{align*}
f(x) &amp;= \begin{cases}
    \text{\var{maxutil}} &amp; x \leq \text{\var{summit}}, \\
    \text{\var{minutil}} &amp; \text{otherwise}.
  \end{cases}\\
\end{align*}
\normalsize

\noindent
The \var{basewidth} parameter can be used to soften the drop in
utility as shown in Figure \ref{zaic-leq-fig}. When \var{basewidth}
has the default value of zero, the general form is as above. When
\var{basewidth} is configured with a positive value, the general form
is:

\vspace{0.1in}
\footnotesize
\wikihint{width=630}
\begin{align*}
  f(x) &amp;= \begin{cases}
    \text{\var{maxutil}} &amp; x \leq \text{\var{summit}}, \\
    \text{\var{minutil} + ((\var{maxutil} - \var{minutil}) * ((x - \var{summit}) / \var{basewidth}))} &amp; 
    \text{\var{summit}} &lt; x \leq \text{\var{summit} + \var{basewidth}}, \\
    \text{\var{minutil}} &amp; \text{otherwise}.
  \end{cases}\\
\end{align*}
\normalsize
\vspace{0.1in}

\noindent
For the example in Figure \ref{zaic-leq-fig}, the function is given below. 

\vspace{0.1in}
\small
%\wikihint{width=550}
\begin{align*}
f(x) &amp;= \begin{cases}
    120 &amp; x \leq 150, \\
    20 + ((120-20) * ((210 - x) / (210-150))) &amp; 150 &lt; x \leq 210, \\
    20 &amp; \text{otherwise}.
  \end{cases}\\
\end{align*}
\normalsize
\vspace{0.1in}

\noindent 
The three above cases corresponds to the three pieces generated for the 
IvP function shown in Figure \ref{zaic-leq-fig}.

%---------------------------------------------------------------------
\subsubsection{The {\zleq} Interface Implementation}
\label{sec_zleq_imp}

The following functions define the interface to the {\zleq} tool. In
constructing and setting parameters, the instance maintains a Boolean
flag indicating if any fatal configuration errors were detected. In
such cases, a warning string is generated for optional retrieval, and
the error renders the instance effectively useless, never yielding an
IvP function when requested. Example usage is provided in Listing
\ref{lst_zaic_leq}.

\begin{packed_itemize}[2]

\item \func{ZAIC\_LEQ(IvPDomain domain, string varname)}: The
  constructor takes two arguments, an IvP domain and a variable name
  contained in the domain. The named variable needs to be just {\em
    one} of the variables used in the IvP domain; not necessarily the
  only one. If the named variable is not part of the IvP domain, this
  is regarded as a fatal error.

\item \func{bool setSummit(double summit)}: Sets the {\summit}
  value. If the summit value is outside the range of the domain, it is
  clipped to the appropriated end. For example if the domain were
  [0,600] as the example in Figure \ref{zaic-leq-fig}, and the
  requested summit value were 650, the summit parameter would be set
  to 600. This is therefore not regarded as a fatal configuration
  error, but a warning would be generated anyway. This function always
  returns true.

\item \func{bool setMinMaxUtil(double min, double max)}: Sets the
  values for {\minu} and {\maxu}. If the {\minu} is greater or equal
  to {\maxu}, this is regarded as a fatal configuration error, a
  warning is generated, and the function returns false.

\item \func{bool setBaseWidth(double basewidth)}: Sets the
  \var{basewidth} parameter value. The given value must be greater
  than or equal to zero. Otherwise this is regarded as a fatal
  configuration error, a warning is generated, and the function
  returns false.

\item \func{IvPFunction *extractIvPFunction()}: This function
  generates a new IvP function based on the prevailing parameter
  settings at the time of invocation. If a fatal error was detected in
  prior parameter setting attempts, this function will simply return
  the NULL pointer. When the IvP function is extracted from the ZAIC,
  an IvPFunction instance is created from the heap that needs to
  be later deleted. The ZAIC tool does not delete this. It is the
  responsibility of the caller. Typically this tool is used within a
  behavior, and the behavior passes the IvP function to the helm and
  the helm deletes all IvP functions.

\item \func{string getWarnings()}: When or if fatal (or non-fatal)
  problems are encountered in setting the parameters, the tool appends
  a message to a local warning string. This string can be retrieved by
  this function. A non-empty string does not necessarily mean a fatal
  configuration error was encountered. Instead, the \var{stateOK()}
  function below should be consulted.

\item \func{bool stateOK()}: This function returns true if no
  fatal errors were encountered during configuration attempts,
  otherwise it returns false. If an error has been encountered,
  this state cannot be reversed. The instance has been rendered
  effectively useless. To gain insight into the nature of the error,
  the \var{getWarnings()} function above can be consulted.

\end{packed_itemize}

%--------------------------------------------------------------------
\subsubsection{Using the {\zleq} Tool}
\label{sec_zleq_usage}
\index{ZAIC\_LEQ Tool!Example Usage}

\noindent
Usage of the \var{ZAIC\_LEQ} tool boils down to the following four steps. 

\begin{packed_itemize}[2]
\item Step 1: Create the IvP domain, or retrieve it if otherwise
  already created. 
\item Step 2: Create the \var{ZAIC\_LEQ} instance with a domain and
  domain variable. 
\item Step 3: Set the \var{ZAIC\_LEQ} parameters. 
\item Step 4: Extract the IvP function.
\end{packed_itemize}

\vspace{0.1in}
\noindent
A code example of the four steps is provided in Listing
\ref{lst_zaic_leq} below. This code example describes a function that
builds and returns an IvP function using the {\zleq} tool. It is not
too different from the activity inside a typical implementation of
\var{onRunState} in an IvP behavior.

\vspace{0.25in}
\vspace{0.1in}
\begin{listing}{Example usage of the \var{ZAIC\_LEQ tool} corresponding to Figure \ref{zaic-leq-fig}}
\label{lst_zaic_leq}
\scriptsize
\begin{verbatim}
  1  IvPFunction *buildIvPFunction()
  2  {
  3    // Step 1 - Create the IvPDomain, the function's domain
  4    IvPDomain domain;
  5    domain.addVar("depth", 0, 600, 601);
  6  
  7    // Step 2 - Create the ZAIC_LEQ with the domain and variable name
  8    ZAIC_LEQ  zaic_leq(domain, "depth");
  9  
 10    // Step 3 - Configure the ZAIC_LEQ parameters
 11    zaic_leq.setSummit(150);
 12    zaic_leq.setMinMaxUtil(20, 120);
 13    zaic_leq.setBaseWidth(60);
 14  
 15    // Step 4 - Extract the IvP function
 16    IvPFunction *ivp_function = 0;
 17    if(zaic_leq.stateOK())
 18      ivp_function = zaic_leq.extractIvPFunction();
 19    else
 20      cout &lt;&lt; zaic_leq.getWarnings();
 21    return(ivp_function)     
\end{verbatim}
\end{listing}
\normalsize
\vspace{0.1in}

\noindent
The lines comprising step 4 (lines 15-20) are conservative in that
they first check to see if no fatal configuration errors were
encountered, and writes the warnings to the terminal if found. It
does not even attempt to extract an IvP function if an error was
encountered. These five lines could have been replaced by one line:

\vspace{0.1in}
\small
\begin{verbatim}
   return(zaic_leq.extractIvPFunction());
\end{verbatim}
\normalsize
\vspace{0.1in}

\noindent
This is simpler, but the warning information is potentially
useful. When the {\zleq} tool is used within an IvP behavior, the
warnings can be posted to the \app{MOOSDB} in the variable
\mvar{BHV\_WARNING} which is monitored by other tools.

%---------------------------------------------------------------------
\subsubsection{The {\zheq} Tool}
\index{ZAIC\_HEQ Tool}
\label{sec_zheq}

Like the {\zleq} tool, the {\zheq} too is used for generating
objective functions where there is a constant, maximum utility
associated with a decision variable whose value is kept {\em greater
  than or equal} to a given value. The parameters described in Section
\ref{sec_zleq_params} and interface implementation described in Section
\ref{sec_zleq_imp} for the {\zleq} tool are identical for the {\zheq}
tool. The parameters are interpreted differently however. The same
parameters used in Figure \ref{zaic-leq-fig} are used in the {\zheq}
tool to give the function shown in Figure \ref{zaic-heq-fig}.

\vspace{0.18in}

\begin{figure}[H]
  \centering
  \includegraphics[width=0.85\textwidth]{figs_ivpbuild/zaic_heq_a_labels.png}
  \caption{{\bf The \vvar{ZAIC\_HEQ} tool}: facilitates building
    simple 2-3 piece piecewise defined utility functions over a single
    decision variable whose value is to be kept greater than or equal
    to a given value. It accepts four parameters, the \vvar{summit},
    \vvar{minutil}, \vvar{maxutil}, \vvar{basewidth}. In the figure
    \vvar{summit}=150, \vvar{minutil}=20, \vvar{maxutil}=120,
    \vvar{basewidth}=60.}
\label{zaic-heq-fig}
\end{figure}
\vspace{0.15in}


%---------------------------------------------------------------------
\subsubsection{A Warning about the Maximum Utility Plateau}
\label{sec_maxplat}
\index{ZAIC Tools!Maximum Utility Plateau}

It is worth noting a potential pitfall regarding the maximum utility
plateau generated by both the {\zleq} and {\zheq} tools. By having
equal utility for all domain values in the plateau range, no one
domain value is preferred. If this is the only IvP objective function
involved in the decision process {\em for the particular domain
  variable}, it is not clear what value will be chosen by the IvP
solver. Even more troublesome is that the chosen value may change
between iterations giving the appearance that the decision engine is
thrashing. In this case the solver is simply faithfully and strictly
interpreting the problem it was given. In short, these objective
functions are designed to work in conjunction with others that express
preferences in a non-plateau manner.

%\newpage
\subsection{The  {\zvec} Tool}
\index{ZAIC\_Vector Tool}

%---------------------------------------------------------------------
\subsubsection{Brief Overview}
The \var{ZAIC\_Vector} tool is used for generating IvP functions over
one variable, given some number of explicit domain-range
mappings. These mappings are passed to the {\zvec} tool as two equally
sized vectors; a vector of domain values and a vector of range values.
An IvP function is created that typically has a piece per given
domain-range pair, where the slope of each piece simply approximates
the domain-range characteristics for domain-range pairs not explicitly
given.

\vspace{0.15in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.9\textwidth]{figs_ivpbuild/zaic_vector.png}
  \caption{{\bf The {\zvec} tool}: defines an IvP function over one
    variable defined by a set of explicit domain-range mappings.}
\label{zaic-vec-fig}
\end{figure}
\vspace{0.1in}


%---------------------------------------------------------------------
\subsubsection{Using the {\zvec} Tool}
\label{sec_zvec_usage}
\index{ZAIC\_Vector Tool!Example Usage}

\noindent
Usage of the {\zvec} tool boils down to the following four steps. 

\begin{packed_itemize}[2]
\item Step 1: Create the IvP domain, or retrieve it if otherwise
  already created. 
\item Step 2: Create the {\zvec} instance with a domain and
  domain variable. 
\item Step 3: Set the {\zvec} parameters. 
\item Step 4: Extract the IvP function.
\end{packed_itemize}

\vspace{0.1in}
\noindent
A code example of the four steps is provided in Listing
\ref{lst_zaic_vector} below. This code example describes a function
that builds and returns an IvP function using the {\zvec} tool. It is
not too different from the activity inside a typical implementation of
\func{onRunState} in an IvP behavior.

\vspace{0.25in}
\vspace{0.1in}
\begin{listing}{Example usage of the {\zvec} tool corresponding to Figure \ref{zaic-vec-fig}}
\label{lst_zaic_vector}
\scriptsize
\begin{verbatim}
  1  IvPFunction *buildIvPFunction()
  2  {
  3    // Step 1 - Create the IvPDomain, the function's domain
  4    IvPDomain domain;
  5    domain.addVar("depth", 0, 600, 601);
  6  
  7    // Step 2 - Create the ZAIC_Vector with the domain and variable name
  8    ZAIC_Vector  zaic_vector(domain, "depth");
  9  
 10    // Step 3 - Configure the ZAIC_Vector parameters
 11    vector&lt;double&gt; domain_vals;
 12    vector&lt;double&gt; range_vals;
 13    domain_vals.push_back(100); range_vals.push_back(80);
 14    domain_vals.push_back(150); range_vals.push_back(15);
 15    domain_vals.push_back(180); range_vals.push_back(35);
 16    domain_vals.push_back(220); range_vals.push_back(40);
 17    domain_vals.push_back(360); range_vals.push_back(55);
 18    domain_vals.push_back(419); range_vals.push_back(95);
 19    domain_vals.push_back(480); range_vals.push_back(75);
 20    domain_vals.push_back(520); range_vals.push_back(65);
 21    domain_vals.push_back(560); range_vals.push_back(85);
 22    domain_vals.push_back(999); range_vals.push_back(34);
 23    zaic_vecctor.setDomainVals(domain_vals);
 24    zaic_vecctor.setRangeVals(range_vals);
 25  
 26    // Step 4 - Extract the IvP function
 27    IvPFunction *ivp_function = 0;
 28    if(zaic_vector.stateOK())
 29      ivp_function = zaic_vector.extractIvPFunction();
 30    else
 31      cout &lt;&lt; zaic_vector.getWarnings();
 32    return(ivp_function)     
\end{verbatim}
\end{listing}
\normalsize
\vspace{0.1in}

\noindent
The lines comprising step 4 (lines 26-31) are conservative in that
they first check to see if no fatal configuration errors were
encountered, and writes the warnings to the terminal if found. It
does not even attempt to extract an IvP function if an error was
encountered. These five lines could have been replaced by one line:

\vspace{0.1in}
\small
\begin{verbatim}
   return(zaic_vector.extractIvPFunction());
\end{verbatim}
\normalsize
\vspace{0.1in}

\noindent
This is simpler, but the warning information is potentially
useful. When the {\zleq} tool is used within an IvP behavior, the
warnings can be posted to the MOOSDB in the variable
\mvar{BHV\_WARNING} which is monitored by other tools.

</pre></body></html>