VXL To Do List
--------------

This file lists ideas for enhancements that would be helpful to VXL
and is essentially a simple bug and feature request tracker.

Maintainers should feel free to add new items and to add comments or
suggestions to any of these items.  Make sure you keep the file well
organized.

When someone works on or completes one of these tasks, make a note of
that in this file.  If that marks a significant improvement, make an
entry in the CHANGES.txt file as well.

############################################################################

* Add exception support to VXL.

This would have to be done so that all exception code can be switched off,
since VXL does not require exception support. Converting many of the
calls to vcl_abort, into exceptions would be useful for programmers of
GUIs, giving the program a change to save state and possibly give a
useful bug report before exiting. Lots of VXL is probably not exception
safe, and needs to be fixed.

############################################################################

* Ensure that VXL APIs are re-entrant.

VXL is not thread-safe, but should be. Some of this is due to the
limitations of f2c in v3p/netlib. It produces static variables, where
automatic ones would do. This may be fixed with the latest version of
f2c and or lapack3e.

In other places, such as the vil image loader, and the vsl binary
loader, there are singleton classes. This code is inherently
non-thread safe. Such code can be clearly documented to indicate how
to avoid thread problems, e.g. by initialising such loaders in a single
thread.

############################################################################

* upgrade netlib to use LAPACK instead of LINPACK

vnl_algo uses the netlib library to provide good numerical algorithms.
During VNL's design, it was thought that the much newer LAPACK was better
than the LINPACK library. However, it was faster to get something working
with LINPACK, since it had less dependencies than LAPACK. Now, LAPACK's
superiority is undisputed. LAPACK is faster, and more accurate. It is
designed for efficient parallel processing including on SMP machines
so it should be thread safe. We do not know if f2c'ed LAPACK is
automally thread safe, but it should be possible to hand edit it
to deal with f2c's deficiencies. LAPACK3E has been specifically updated
to avoid SAVE statements and so is definitely thread safe. It is written
in Fortran 90 whilst f2c can still only read Fortran77. There is a
developmental version of gcc supporting Fortran95, so maybe gcc users
could optionally use the native LAPACK library.

netlib.org has a library called CLAPACK where someone else has done the
f2c and tidyup already. I don't know if it is thread-safe. It might not
be too much work to strip out any remaining static values.

It should be possible to start using LAPACK incrementally. LAPACK
names do not appear to clash with LINPACK, and since they both need
BLAS, adding the LAPACK code to v3p/netlib would be sensible.
I suggest starting with SVD of double matrices. This will require
also converting some helper functions. After that it should be
relatively straight forward to start importing individual LAPACK
routines, and moving vnl_algo classes over one at a time.

Note that vnl does not use BLAS, but does its own vector and matrix
multiplications. The speed of the MKL (An Intel supplied/optimised copy
of BLAS) was compared with gcc's compilation of VNL, and gcc/VNL won.
gcc/VNL was marginally faster on the matrix-vector operations, although
the difference was more marked on the vector-vector operations.
However, LAPACK and LINPACK both need a BLAS, and the MKL 
was definitely faster than the gcc-compiled version of the default BLAS
currently in netlib. So it would be worth providing an option to use an
external BLAS for vnl_algo/netlib. It might also be worth testing the
matrix-matrix operations - where MKL's knowledge of cache behaviour
may help more than vnl's knowledge of the matrix data organisation.
See https://sourceforge.net/mailarchive/message.php?msg_id=3628964 for
more details.

Some compiler optimsers (gcc's notably) appear to break bits of netlib.
Different versions of gcc (or even the same version of gcc on different
computers) break different bits of netlib, so turning optimisation off
for all of netlib has too high a price. It would be worth testing the
builds of various bits of netlib in the configuration and adjusting
optimiser values until tests are passed. It is certainly not worth
doing any of this before moving from linpack to lapack.

Ian Scott.

############################################################################

* Borland compiler

VXL has been ported to the Borland 5.5 compiler, but only for the core
libraries, not the contrib libraries.  Brad King did the port for the
core libraries and may have some advice on getting contrib ported.

############################################################################

* vnl specializations for char

From Brad King: There no specializations for char types in vnl.

############################################################################

* vnl, mix of static methods and static constants for constants

From Brad King: In vnl Some of the constants are static methods and
some are static constants.  I do not see any reason for the
inconsistency.

############################################################################

* vnl min/max values for long types are hardcoded to assume 32-bits

From Brad King: In vnl, min/max values for long types are hardcoded to
assume 32-bits.  It should be possible to construct almost all the
values with try-run programs during the configuration process, but
that may be overkill for now.

############################################################################

* vnl, test_math and test_numeric_limits access the NaN values

From Brad King: In vnl, another problem is that test_math and
test_numeric_limits access the NaN values.  There is nothing wrong
with this, but Borland throws floating-point exceptions by default.
I've fixed my local copy to use the _control87 function to disable
exceptions for those tests on that compiler, but I haven't committed
it yet.  Is this something we want to abstract and add to testlib?

From Peter Vanroose: A similar problem on Alpha (OSF).  I've commented
out the affected tests, but that's not really the best way to proceed.
So it's not just Borland C++, and it would indeed be nice to have an
elegant solution for this.

From Brad King: We could just put the floating point exception disable
code in the top of testlib_main just like the crtdbg stuff for getting
rid of the MSVC popup dialogs.  Once we get it working everywhere with
a bunch of #ifdef lines then we could consider making it a function
somewhere useful outside testing.

############################################################################

* vcl and CMake try-compile

Bill Hoffman has suggested that a lot of the compiler version based
#ifdefs in vcl could be replaced by the CMake try-compile mechanism.

############################################################################

* CVS server file execute permissions wrong

At the CVS server, remove execute permission from files that should
not have it.  There is not way to do this with CVS commands, except
possibly a remove and add, which we should avoid.  This could be done
at the same time as any other direct repository modification.

############################################################################

* vnl_math.cxx and vnl_math_is* functions

Brad King: There are several ways that compilers provide isnan, isinf,
and isfinite tests.  The C99 standard defines "isnan", "isinf", and
"isfinite" as macros that work with float, double, and long double.

BSD 4.3 (and many conforming platforms) define
  int isinf(double value);
  int isnan(double value);
  int finite(double value);
in math.h.  Many platforms also provide
  int isinff(float value);
  int isnanf(float value);
  int finitef(float value);
and
  int isinfl(long double value);
  int isnanl(long double value);
  int finitel(long double value);

However, no set of these works everywhere, and some implementations
have bugs.  Alternatively one can implement these functions by hand.
Currently there is a hand-written implementation that works in most
cases, but not all.  As hardware improves and long double gets bigger,
the implementation is working on fewer and fewer platforms.

For long double, the sign bit is not always the most significant bit
due to aligned sizes (see below).  It is possible to detect the
location of the sign exponent bits by bitwise XORing the
representation of '1.0' and '-1.0'.  The lowest order bit of the
exponent portion can be detected by bitwise XORing the representation
of '1.0' and '0.5'.  Unfortunately the assumption of IEEE conformance
for long double cannot be made.  The representation on Intel
platforms, for example, has the following problems:

  sizeof(long double) == 10  when compiling with Borland
  sizeof(long double) == 12  when compiling with GCC

The 12-byte version is the aligned size, but the number is really only
10 bytes long.  It is a direct copy of the 80-bit floating point
representation from the Intel FPU's registers.  The implicit '1' bit
is represented explicitly as the MSB of the fraction component, and
thus is not IEEE conforming.

############################################################################
