<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">%=================================================================
\section{The alogeval Tool}
%=================================================================
\label{sec_alogeval}
%\index{alogeval!Overview}

The \cmd{alogeval} tool will scan a given alog file and apply test
criteria found in a separate input file. The test criteria should be
similar to that used by \app{pMissionEval}, specifying criteria for
{\em when} the test should be applied, and then the criteria for
passing or failing the test. The advantage of \cmd{alogeval} over
\app{pMissionEval} is that the user can repeatedly adjust the evaluation
criteria and re-run the evaluations. With \app{pMissionEval}, the test
criteria loaded at run-time will produce mission evaluations that are
based on the run-time criteria only.

\vspace{0.1in}
\noindent
A concise form of this documentation is available on the command line:

\vspace{0.1in}
\begin{consoleverb}
$ alogeval --help    (or -h)
\end{consoleverb}
\vspace{0.1in}

\noindent
The web version of this content can be quickly summoned from the command
line with:

\vspace{0.1in}
\begin{consoleverb}
$ alogeval --web    (or -w)
\end{consoleverb}

%=================================================================
\subsection{Test Criteria Input File}

The test criteria is provided in a separate input file. If the file
has the suffix \var{.txt}, it can simply be provided, otherwise use
the \var{--testfile=filename} argument. The following two are
equivalent:

\vspace{0.1in}
\begin{consoleverb}
$ alogeval mission.alog criteria.txt
$ alogeval mission.alog --testfile=criteria.txt
\end{consoleverb}
\vspace{0.1in}


%=================================================================
\subsection{Test Criteria Logic Test Sequence}

The primary configuration structure is a {\em logic test sequence},
comprised of one or more {\em logic tests}. The sequence of tests
may be ordered by time, but may also be time invariant. The overall
test evaluation is completed when either (a) all logic tests in the
sequence have been evaluated and passed, or (b) when any one of the
logic tests in the sequence has failed.

\vspace{0.1in}
\noindent
A logic single test is comprised of:

\begin{packed_itemize}
\item lead conditions
\item pass conditions
\item fail conditions
\end{packed_itemize}

\noindent
One or more lead conditions may be provided. As soon as all lead
conditions have been satisfied, the pass/fail conditions are
evaluated. If one or more pass conditions have been provided, then
{\em all} must satisfied or else the test fails. If one or more fail
conditions are provided, then if {\em any} fail condition is satisfied,
the test fails.

\vspace{0.1in}
\noindent
A test sequence is comprised one or more tests. Each test has its own
conditions. In this case {\em the order of lines in the configuration
  file is important} as it determines the grouping. For example, in
the Alpha End Flag mission, the sole test is whether the end flag has
been set after the fifth waypoint has been hit. This does not test
for the possible error case where the endflag is posted after the third
or fourth waypoint has been hit. The single logic test could be replace
with the following test sequence:

\vspace{0.1in}
\begin{fileverb}
  lead_condition = WC_FLAG = 3
  pass_condition = EFLAG = 0

  lead_condition = WC_FLAG = 4
  pass_condition = EFLAG = 0
\end{fileverb}
\vspace{0.1in}

\noindent
Note in this case there are three tests, all tests need to pass if the
\pvar{pass\_flag} is to be posted. Note also that the test \mvar{EFLAG=0}
will not pass unless it is explicitly published with this value. And
the condition \mvar{EFLAG!=1} will also not pass unless \mvar{EFLAG} has
been published. In this example, in the Alpha End Flag mission, the helm
initializes the \mvar{EFLAG} variable to 0 upon helm launch.

\vspace{0.1in}
\noindent
The order of the tasks in the configuration does matter. The app at
any given moment will address the next element in the sequence. Only
when the last element has been addressed will the result, pass, and fail
flags be published. Consider what would happen if the first two of the
above tests were reversed? In this case the mission would never finish
evaluation. Why?

%=================================================================
\subsection{Test Output and Return Values}

If \cmd{alogeval} succeeds, with valid alog file, valid criteria file, and
passing all logic tests, it returns with a value of 0. Other possible
values:

\begin{packed_itemize}
\item 0: Success
\item 1: All valid files, but test criteria failed
\item 2: Unhandled command line argument
\item 3: Missing alog file or could not be opened
\item 4: Missing criteria file or could not be opened
\item 5: ALog or criteria file could not be parsed
\end{packed_itemize}

\vspace{0.1in}
\noindent
The above return values are returned to the shell on the command line.
By default, \cmd{alogeval} produces no output to the terminal. Output
can be enabled with the \var{--verbose} flag, for example:

\vspace{0.1in}
\begin{consoleverb}
$ alogeval file.alog criteria.txt --verbose
BEGIN ALogEvaluator: Handling ALog File:
    14.72909      EFLAG  0   [false,false] (0)
   121.82700    WC_FLAG  1   [false,false] (0)
   162.14515    WC_FLAG  2   [false,false] (0)
   192.43813    WC_FLAG  3   [false,false] (1)
   215.20145    WC_FLAG  4   [true,true]   (2)
EVALUATION COMPLETE
END  ALogEvaluator: Handling ALog File
Result: pass=true
$ echo $?
0
\end{consoleverb}
\vspace{0.1in}

\noindent
In the above output, several lines with timestamps are
shown. Variables involved in the criteria logic conditions are noted
by \cmd{alogeval}. Each time a log entry is encountered with one of
these variables, the test criteria is applied, and a line of output
is produced. The second column is the MOOS variable name. The third
column is the posted value of the MOOS variable. The fourth column
contains two Booleans. The first is whether the entire test sequence
has been evaluated, and the second Boolean is whether the evaluation
passed. If the first is false, the second will false. The fifth
column is index of the current logic test. Since there are only
two logic tests in this example, with the index is 2, then the
evaluations should be complete. 

\vspace{0.1in}
\noindent
In the line with timestamp at \var{192} seconds, the \var{WC\_FLAG}
posting is 3, which is the first \var{lead\_condition}. Since
\var{EFLAG=0} is the pass condition, this first logic test passes
and the logic test index increments from 0 to 1. In the line with
timestamp at \var{215} seconds, the \var{WC\_FLAG}
posting is 4, which is the second \var{lead\_condition}. Since
\var{EFLAG=0} is the pass condition, this second logic test passes
and the logic test index increments from 0 to 2. Since all logic
tests have been evaluated, and all passed, the fourth column on
this final line reads \var{[true,true]}, and the evaluation is
complete.

%=================================================================
\subsection{Examining the Test Sequence Structure}

The normal verbose output can be augmented with the \var{--show\_seq} or
\var{-ss} flag. This will show the structure of test criteria before the
evaluation, and again after the evaluations. For example:

\vspace{0.1in}
\begin{consoleverb}
$ alogeval file.alog criteria.txt --verbose -ss
BEGIN ALogEvaluator LogicTestSequence ========= 
LogicTestSequence: Total Aspects:2
Enabled:   true
Evaluated: false
Satisfied: false
Status:    pending
++++++++++ aspect[0] +++++++++++++
Lead Conditions: (1)  WC_FLAG = 3
Pass Conditions: (1)  EFLAG = 0
Fail Conditions: (none)
Enabled(true), Evaluated(false), Satisfied(false), Status(pending)
++++++++++ aspect[1] +++++++++++++
Lead Conditions: (1)  WC_FLAG = 4
Pass Conditions: (1)  EFLAG = 0
Fail Conditions: (none)
Enabled(true), Evaluated(false), Satisfied(false), Status(pending)
END   ALogEvaluator LogicTestSequence ========= 

BEGIN ALogEvaluator: Handling ALog File:
    14.72909      EFLAG  0   [false,false] (0)
   121.82700    WC_FLAG  1   [false,false] (0)
   162.14515    WC_FLAG  2   [false,false] (0)
   192.43813    WC_FLAG  3   [false,false] (1)
   215.20145    WC_FLAG  4   [true,true]   (2)
EVALUATION COMPLETE
END  ALogEvaluator: Handling ALog File

BEGIN ALogEvaluator LogicTestSequence ========= 
LogicTestSequence: Total Aspects:2
Enabled:   true
Evaluated: true
Satisfied: true
Status:    pass
++++++++++ aspect[0] +++++++++++++
Lead Conditions: (1)  WC_FLAG = 3
Pass Conditions: (1)  EFLAG = 0
Fail Conditions: (none)
Enabled(true), Evaluated(true), Satisfied(true), Status(pass)
++++++++++ aspect[1] +++++++++++++
Lead Conditions: (1)  WC_FLAG = 4
Pass Conditions: (1)  EFLAG = 0
Fail Conditions: (none)
Enabled(true), Evaluated(true), Satisfied(true), Status(pass)
END   ALogEvaluator LogicTestSequence ========= 
Result: pass=true
\end{consoleverb}
\vspace{0.1in}
</pre></body></html>