\section{Updating}\label{sec:Update}

The following subsections contain details on how to test
and/or benchmark an implementation of the \nrm routines that
is not available in the \filename{OtherVersions} directory
of the accompanying software package. Different approaches
are required depending upon whether the new implementation
is available as source code or in some non-source form, for
example, a pre-compiled library or \filename{.o} files.

Details of how to add a new test case to the existing test suite
are covered in Section~\ref{subsec:newtest}.

\subsection{Testing a New Implementation}\label{subsec:testnewimp}
To test a new implementation of the \nrm routines it is
necessary to link the new code with the test suite software. To
facilitate the testing of the algorithms and their variants
provided in the current package, the test suite software has
been constructed to expect the \nrm routines to be available as
a module. The test driver (\filename{sdTest.f90}) \fvarn{USE}s
the module \fvarn{testSubs} to import the four functions
\fvarn{dnrm2}, \fvarn{dznrm2}, \fvarn{scnrm2} and \fvarn{snrm2}
along with a descriptive title to allow easy identification
of the implementation under test (the title will appear as a
header in the generated results file).

For the majority of the implementations in the current package
the module containing the source files is \fvarn{nrm2\_Other}
and the names of the routines are those given above. Listing~\ref{list:one}
shows the required form of the module \fvarn{testSubs} in
this case.

\lstset{numbers=left, numberstyle=\tiny}
\lstinputlisting[language={Fortran},label={list:one}, 
 caption=Version used for modules in \filename{OtherVersions}, 
 basicstyle=\footnotesize]{../Testing/testSubsGen.f90}

Listing~\ref{list:two} gives the version of \fvarn{MODULE
testSubs} used to test the proposed hybrid routines. Note
that here the required routine names are imported from the
module \fvarn{nrm2HybridMod} and the variable containing the
descriptive title is defined explicitly in \fvarn{testSubs}.

\lstinputlisting[language={Fortran},label={list:two}, 
 caption=Version used for the new hybrid versions, 
 basicstyle=\footnotesize]{../Testing/testSubsHybrid.f90}

Finally, Listing~\ref{list:three} shows how the Kahan routines
used in the hybrid module may be tested by using local names. As
with Listing~\ref{list:two}, the \fvarn{descript} variable is
set explicitly in the \fvarn{testSubs} module.

\lstinputlisting[language={Fortran},label={list:three}, 
 caption=Version used for the Kahan versions used by the new hybrid codes, 
 basicstyle=\footnotesize]{../Testing/testSubsKahan.f90}
\lstset{numbers=none, frame=single}

If the new routines are already packaged as a module, then
the approach used in Listing~\ref{list:two} may be used to
interface this module with the test suite. The only changes
necessary should be to use the name of the new module in
place of \fvarn{nrm2HybridMod} in the \fvarn{USE} statement
at line 9 and change the string assignment to the variable,
\fvarn{descript}, to something appropriate. The associated
\filename{Makefile} should then be edited to add the new module
using the executable \filename{sdTestOnePassKahan} as a template.

If the routines to be tested are available as source
code but are not packaged as a module, then the simplest
approach is to wrap them as a module, \fvarn{nrm2\_Other},
and use Listing~\ref{list:one} directly. The associated
\filename{Makefile} should then be edited using the executable
\filename{sdTestOrigBLAS} as a template.

If the new implementation is not available as source code then
the templates provided in the makefile in the \filename{Testing}
directory should be used to build the executables. The
template \fvarn{sdTestBLASLib} provides details for linking
against a pre-compiled library and \filename{sdTestBLASSubs}
for routines only available as \filename{.o} files or as source
code not packaged in a module.

\subsection{Running the Benchmark Code against New Sources}

If the comparison implementation is in the form of a
pre-compiled library (i.e., no source code is available)
or is presented as a set of source routines not contained
in a module (either in \texttt{.f/.f90/.f95} or \texttt{.o}
format), then the benchmark source file
\filename{sdBenchmark.f90} needs to be changed. (An alternative
for a set of routines in source format would be to wrap them
in a module as described in Section~\ref{subsec:testnewimp} above.) The
\filename{makefile} will also need to be changed in order to
build the required executable.

The following steps are required:

\begin{enumerate}
\item Follow the instructions in the comments at the start
of the program file \filename{sdBenchmark.f90}. The code
has been set up to import the required routines, \nrm, from
the module, \fvarn{nrm2\_other}. Thus, if this is not
the case, the routines need to be declared \fvarn{EXTERNAL}
and the type of each function declared explicitly.

\item To build the executables (\filename{sdBenchBLASLib} and
\filename{sdBenchBLASSubs}) follow the comments in the file
\filename{Makefile} in the \filename{Benchmarks} directory for
these names.

\noindent
Note: the use of \filename{sdBenchmark.f90} rather than
\filename{sdBenchmark.o}; this forces the compiler to overwrite
any existing \filename{.o} and \filename{.mod} (or equivalent)
files under all circumstances.

\item For the case where the comparison implementation is in
the form of a set of routines different build definitions
may be necessary depending on the `form' of the routines:

\begin{description}
\item [\filename{.o} files:] just link
\item [source files:] if we have fixed format then it will
probably be necessary to use a different set of compiler flags
to take account of it.

If the source code is not Fortran, then an appropriate compile
line will be needed as well as possible changes to the link
line to accommodate the mixed language nature of the build.

\end{description}
\end{enumerate}
