/*!

\page performance Performance plot tools

<hr> 

This document describes how you can plot the performance of an IDEA agent using it's
log file.

One needs to have <A HREF="http://www.gnuplot.info">gnuplot</A> installed to use the scripts.

\section scripts Reporting scripts 

\subsection runplot_all runplot_all

Will run \ref plot_all on each log file in the directory passed in as the first argument and parse the results
into the directory passed in as the second argument.

Usage: 
   ./runplot_all <searchdir> <outputdir>

\li <searchdir> directory the script should look for log files. The script looks for files with the following signature '*e.log.[0-9]*[0-9][0-9]'
\li <outputdir> directory the script will parse the results in

\verbatim
Example:
 ./runplot_all /home/user/me/dir_with_log_files /home/user/me/dir_for_output
\endverbatim

\subsection plot_all plot_all

Takes a log file and will create a report containing some plots, all warnings and errors and events. An event is defined by the script 'build-summary-from-log' in the IDEA-DEV/Tools/Test directory

Usage: ./plot_all <log-file-name> <output-dir> {noplot}

\li <log-file-name>, mandatory, the log file to be used
\li <output-dir>, mandatory, the output log files will be placed here.
\li {noplot} optional option tells the scripts to plot to a png file as opposed to the screen. (e.i. no plot to screen)

\verbatim
Example:
./plot_all log PlotLogs
\endverbatim

\subsection plot plot

Takes a log file and generates a plot of all the reactive planner cycles divided in the following segments:

\li waiting for lock, when the reactive planner can start the first thing it does is acquiring a lock, this segment shows how long it takes to get the lock.
\li pre processing
\li planning
\li post processing
\li printing of the state when the reactive planner is done
\li creating and sending out the messages

Usage: plot <log-file-name> <plot/noplot> {noplot}
  
\li <log-file-name>, mandatory, the log file to be used
\li <plot/noplot>, will assume plot unless noplot is specified
\li {noplot} optional option tells the scripts to plot to a png file as opposed to the screen. (e.i. no plot to screen)

\warning This script only works if agent-name and thread-names contain no white-spaces!

\verbatim
Example:
./plot log
./plot log noplot
\endverbatim

<img src="../Images/plot.png">

\subsection  plot_init

Usage: plot <log-file-name> <plot/noplot> {noplot}

\li <log-file-name>, mandatory, the log file to be used
\li <plot/noplot>, will assume plot unless noplot is specified
\li {noplot} optional option tells the scripts to plot to a png file as opposed to the screen. (e.i. no plot to screen)

\warning This script only works if agent-name and thread-names contain no white-spaces!

\verbatim
Example:
./plot_init log
./plot_init log noplot
\endverbatim 

\image png ../Images/init.png
<img src="../Images/init.png">

\subsection plot_efficiency plot_efficiency

Takes a log file and generates an efficiency plot of reactive planning cycles. Efficiency is definded as E=1-((Step-Depth)/Step)
and should be a metric for the efficiency of the search, the more beacktrack the lower the effciency
(100% efficiency indicates that there was no backtracking).

Usage: plot_efficiency <log-file-name> <parse/noparse> [start-tick] [end-tick] [title/plotting options]
  
\li <log-file-name>, mandatory, the log file to be used
\li [start-tick], optional, start point for the graph
\li [end-tick], optional, end point for the graph
\li [title/plotting options] name of title on graph or give: efficiency

Ths keyword lets you filter data by efficiency (not yet) .  The default
filter is by ticks. The filters should only be used with the noparse option
The default for this program will provide unspecified range by ticks.

\warning This script only works if agent-name and thread-names contain no white-spaces!

\verbatim 
 Example usage:
 ./plot_efficiency log parse
 ./plot_efficiency log noparse
 ./plot_efficiency log noparse 100 200 new_title
\endverbatim
 
The first time it is used, the log file will be parsed and plotted.

Thereafter, the original log file does not have to be parsed thus you may use the
log-plot.data file with the noparse option to disable the parsing of the original file.

When no parse is selected, it only needs to parse the much smaller -plot.data file
thus it is quicker.
 
<img src="../Images/efficiency.png">

\subsection plot_efficiencyC plot_efficiencyC 

Like plot_efficiency but the x-axis of the graph is compressed.

Usage: plot_efficiency <log-file-name> <parse/noparse> [start-tick] [end-tick] [title/plotting options]
  
\li <log-file-name>, mandatory, the log file to be used
\li [start-tick], optional, start point for the graph
\li [end-tick], optional, end point for the graph
\li [title/plotting options] name of title on graph or give: efficiency

Ths keyword lets you filter data by efficiency (not yet) .  The default
filter is by ticks. The filters should only be used with the noparse option
The default for this program will provide unspecified range by ticks.

\warning This script only works if agent-name and thread-names contain no white-spaces!

The first time it is used, the log file will be parsed and plotted.

Thereafter, the original log file does not have to be parsed thus you may use the
log-plot.data file with the noparse option to disable the parsing of the original file.

When no parse is selected, it only needs to parse the much smaller -plot.data file
thus it is quicker.
 
<img src="../Images/efficiency_compact.png">

*/
