README

/*! \file libaff/README
 * \brief C++ containers for numbers (libaff)
 *
 * ----------------------------------------------------------------------------
 *
 * $Id: README,v 1.11 2002-12-20 18:23:46 forbrig Exp $
 * 
 * Copyright (c) 2002 by Thomas Forbriger (IMG Frankfurt) 
 * 
 * C++ containers for numbers (libaff)
 *
 * This file contains:
 *  - documentation of namespace aff
 *  - mainpage text
 *  - documentation for pages:
 *    - \ref page_design
 *    - \ref page_using
 *    - \ref page_notes
 *    - \ref page_naming
 * 
 * REVISIONS and CHANGES 
 *  - 06/12/2002   V1.0   Thomas Forbriger (copied from libcontxx)
 *  - 20/12/2002   V1.1   (thof)
 *                        - complete revision of this file
 *                        - there are major gaps in
 *                          -# \ref sec_design_multidimensional
 *                          -# \ref page_using
 * 
 * ============================================================================
 */

/*! \brief Root namespace of library
  
  This namespace contains all modules of the library
  (see \ref sec_main_modules). 
  Here you should find all components, the user needs to work with this
  library.
  When working with the binary version of the library, you have to use
  aff::prebuilt in place of aff (see \ref sec_design_binary).
 */
namespace aff {
} // namespace aff

/*======================================================================*/

/*! \mainpage

\author Thomas Forbriger
\author Wolfgang Friederich
\since December 2002
\date December 2002
\version V1.0
$Id: README,v 1.11 2002-12-20 18:23:46 forbrig Exp $

  Contents of this page:
  - \ref sec_main_aims
  - \ref sec_main_modules
    - \ref sec_main_modules_basic
    - \ref sec_main_modules_extended
  - \ref sec_main_peculiar

  Additional information:
  - \ref page_design
  - \ref page_using
  - \ref page_notes
  - \ref page_naming
  - \ref page_representation
  - \ref page_changelog
  - \ref page_project_status

\section sec_main_aims Aims of the library
  
  The AFF (Array of Friederich and Forbriger) is a lightweight class library.
  It offers a simple and easy to use container for numbers as is necessary in
  numerical code. The offered array always has a rectangular strided layout,
  reference semantics (through counted references) and a Fortran layout in
  memory. The interface is intentionally kept sparse to keep compilation times
  small. The array itself is meant to be used to pass numbers from one program
  module to the other. If you want to exploit the power of expression
  templates, pass the array contents to something like Blitz++.

  \sa \ref sec_notes_need

/*----------------------------------------------------------------------*/

\section sec_main_modules Modules of the library

  The main module is the array class aff::Array. It provides basic
  functionality through its interface. See the explanation there.
  It is presented in aff/array.h and aff/binarray.h (see also 
  \ref sec_design_binary).
  The object code is places in libaff.a.

\subsection sec_main_modules_basic Basic array modules

  By including aff/array.h you will get access to the following modules:

  -# aff::Array is the main array interface.
  -# aff::Strided is the shape of a strided Fortran array and defines the
                memory layout of aff::Array objects.
  -# aff::SharedHeap is the representation used by aff::Array. It holds the
                data in memory and provides an interface to it. This interface
                may be passed separately from the array object (see also
                \ref page_representation).
  -# aff::SimpleRigidArray is a linear array with size fixed at compile-time.
                There are several inline functions defined for operations with
                this array class.
  -# aff::Exception is the exception base class used in the library .
  -# aff::AllocException is the exception that indicated a failed memory
                allocation(see also "\ref group_error").

  It additionally offers the following type definitions:

  -# aff::Tsubscript is the type of subscripts to arrays (positive and
                     negative).
  -# aff::Tsize      is the type of size values (non-negative).
  -# aff::Tdim       is the type of the dimension index (small, non-negative).

\subsection sec_main_modules_extended Extensions
  
  The library provides some additional modules. You need only include the
  header file of those modules that you really want to use in addition to the
  basic aff::Array functionality.
  These additional modules are:

  -# aff::Shaper presented in aff/shaper.h and used to passed Fortran layouts
                 to array constructors.
  -# aff::Series presented in aff/series.h which is used to interface linear
                 sequences of data (like time series or Fourier spectra).
  -# aff::Iterator presented in aff/iterator.h which is an iterator interface
                 to containers like aff::Array or aff::Series.
  -# aff::Range presented in aff/lib/range.h which is usefull where ever you
                 need to deal with numerical ranges (calculate with them, find 
                 the smallest in a set, etc.).
  -# aff::Subarray presented in aff/subarray.h to conveniently create
                 subarrays from aff::Array objects.
  -# aff::Slice presented in aff/slice.h to conveniently create
                 slices from aff::Array objects.
  -# aff::dump and its associates, presented in aff/dump.h. They are used to 
                 dump shape or contents of containers and are thus useful when
                 debugging your code. See also "\ref group_helpers".


  In the \ref sec_design_binary "binary version" some of the modules
  (aff::Array and aff::SharedHeap) are presented in namespace aff::prebuilt.

  \sa \ref sec_design_namespaces
  \sa \ref sec_nameing_files

/*----------------------------------------------------------------------*/

\section sec_main_peculiar Peculiarities

\par Const-correctness for array elements
In this library we follow provide functionality to write const-correct code
with regard to the array container and with regard to its element values.
See also "\ref sec_design_const".

\par Multidimensional arrays
Every aff::Array of this class has aff::Strided::Mmax_dimen dimensions.
Construction and access for lower dimensionality is provided. In the case of
using less dimensions, the size of the unused dimensions is 1 by default and
its index is inherently set to the first index.
See also "\ref sec_design_multidimensional".

*/

/*======================================================================*/

/*! \page page_design Design decisions

  Contents of this page:
  - \ref sec_design_copy
  - \ref sec_design_namespaces
  - \ref sec_design_binary
  - \ref sec_design_multidimensional
  - \ref sec_design_const

\section sec_design_copy Copy constructor and copy operator
  
  Usually we would expect the copy operator and the copy constructor to have
  the same semantics. Here the copy constructor of aff::Array must have
  reference semantics (it does a shallow copy). This is necessary to allow
  arrays as return values from functions. In this case the copy constructor is
  automatically invoked. Reference semantics ensure a minimal overhead. in
  terms of memory usage and execution time.

  In the case of the copy (assignment) operator things are less clear: 
  If we define the
  copy operator to have reference semantics, it has the same behaviour as the
  copy constructor. That is what we usually would expect. An expression like
  \code
  A=B;
  \endcode
  means that array \c A drops its reference to the memory location it was
  pointing to and forgets its previous shape. Following this statement array
  \c A will refer to the same memory location as array \c B and will have the
  same shape. Both are indistinguishable.

  However, in many cases (most cases?) we will use the copy (assignment)
  operator in the
  sense of a mathematical equation. This may read like
  \code
  A=B+C;
  \endcode
  although expressions like this are not yet supported by the library
  features. In this case we do not mean that \c A should drop it reference. 
  \c A may refer to an array in memory which is also referred by other array
  instances. And we want these values to be set to the result of the operation
  \c B + \c C. In that case the copy operator should have deep copy semantics.

  \par Design decision
  The classes aff::Array and aff::Series provide copy (assignment) operators
  with shallow copy semantics. 
  This is sensible, because we are not offering mathematical array operations.
  This operations may be delegated to a wrapper class in the future, which
  then also may provide expression templates and an appropriate assignment
  operator.

/*----------------------------------------------------------------------*/

\section sec_design_namespaces Namespaces

  We group all code in two namespaces. Major modules which will be accessed by
  the user are placed in namepsace aff. Modules meant to be used internally are
  placed in aff::util.
  Use directives like
  \code
  using namespace aff;
  \endcode
  or
  \code
  using aff::Array;
  \endcode
  for convenient access.

/*----------------------------------------------------------------------*/

\section sec_design_binary Binary library

  We provide a binary version of the library. It contains a set of prebuilt
  class objects. Using this version and linking against the binary library
  libaff.a should reduce compilation times in comparison to complete
  template evaluation.
  This will become more significant the more code is factored out to separate
  definition headers.
  This approach offers no improvement with inlined code (which we use
  extensively in array access functions).

  To use the binary version you should include binarry.h in place of array.h
  You will find modules aff::Array and aff::SharedHeap
  in aff::prebuilt that are in aff in the full-template version.

  \sa tests/binarraytest.cc
  \sa binarray.h

  The inclusion of header files is controlled by a set of preprocessor macros.
  \sa AFF_PREBUILT
  \sa AFF_INDEXCHECK
  \sa AFF_NO_DEFINITIONS
  \sa AFF_COMPILING_LIBRARY
  \sa DOXYGEN_MUST_SKIP_THIS

\note
Since we reduced to number of template parameters significantly in this
approach, many parts of code have already been factored out to separate files
that are compiled into the binary libaff.a. The approach of explicitly
instantiated class templates is not supported so far. It is, however, prepared
in the structure of header files and may be activated in the future.
\date 20/12/2002

/*----------------------------------------------------------------------*/

\section sec_design_multidimensional Multidimensional arrays

  \todo
  Explain Wolfgangs idea of multidimensional arrays.

/*----------------------------------------------------------------------*/

\section sec_design_const Notes on the const-correctness of arrays

\subsection sec_design_const_approach Approach used in this library

  We distinguish between the constness of the array and the constness of the
  elements. A definition
  \code
  aff::Array<int> A(12,12);
  const aff::Array<int> B(A);
  \endcode
  means that array \c B is a constant array initialized to array \c A. This
  means, that the container is constant. Its shape and reference may not be
  changed.

  If you want to define constness of the contained values (e.g. when passing
  an array to a function), you have to use
  \code
  aff::Array<const int> C(A);
  \endcode
  which defines that the contents of \c C may not be changed (i.e. they are of
  type \c const \c int. 
  They are still refering to the same data in memory. 
  If you modify data elements through \c A, this will be visible through \c C.

  An array for elements of type \c T is derived from an array for elements of
  type \c const \c T. 
  Functions that only need read access to arrays should be declared like
  \code
  void func(const aff::Array<const int>& array);
  \endcode
  and may be called like
  \code
  aff::Array<int> A(12,12);
  func(A);
  \endcode
  The type conversion from \c aff::Array<int> to 
  \c const \c aff::Array<const \c int>& is trivial and has no runtime
  overhead.

  A container (aff::Array, etc.) with \c const qualifier offers no access
  operators, that allow modification of the data. 
  Although the constness of the container object generally does not imply
  constness of the contained data, we think that every user will expect the
  classes to behave like this.
  To ensure true constness of the data, you have to assign to a container for
  element type \c const \c T. Remember that a \c const \c aff::Array always
  may be assigned to a mutable aff::Array, which in turn allows modification
  of the data!

  \sa aff::SharedHeap< const T >
  \sa aff::Array< const T >
  \sa aff::Series< const T >

\subsection sec_design_const_general General considerations

  Arrays using the shared heap representation have reference semantics.
  Different instances will access the same data in memory. Copying an array
  instance just copies a reference to the data. This mechanism is not obvious
  to the compiler. The array instances are values in the sense of C++ types
  and not references. Passing an \c const \c aff::Array to a function does
  not prohibit the function from assigning this instance to a non-const
  \c aff::Array, which then references the same memory area and allows the
  modification of the values contained in the array.

  Generally it has to be defined, what is meant by declaring an array instance
  to be \c const. In the first place this means constness of the container to
  the compiler. The compiler will ensure, that the container (array class) is
  not changed, thus no data member of the array is changed. This means that
  the array will keep the reference to the same data and that the
  index-mapping defined by the array shape may not be changed. However, the
  compiler will not prevent to change any data, the array refers to. 

  We may define access operators that have a non-const version that returns a
  reference to the data, allowing to change the data values together with a
  const version that returns a value of const reference, thus preventing the
  data from being changed through an instance that is declared const. However,
  the compiler will always allow to create a non-const copy of a const array
  instance. In the sense of const-ness of C++ data, this does not violate the
  const-ness of the source of the copy. The shape of the original array may
  not be changed. Only the shape of the copy may be changed. But the data of
  the original array may now be changed through the copied instance, since our
  array classes implicitly have reference semantic. Thus we have to
  distinguish between const-ness of the container (array class instance) and
  the contained data (values in memory the arrays refers to).

  In this library we will not provide a const and a non-const version of the
  array classes. With templated code it is more convenient to use an array
  with element type \c const \c T as the const version of an array with
  element type \c T. To allow conversion of an instance with element type \c T
  to an instance of type \c const \c T, we use the version for elements of
  type \c const \c T as a base classe.

   -  The need of const-correctness is discussed in "Chapter 1 Introduction,
      C++ Conventions, Implementation of Vector and Matrix Classes" of
      "Numerical Recipes in C++". A link to a PDF file of this chapter is
      provided at "http://www.nr.com/cpp-blurb.html".
   - The "C++ FAQ Lite" discusses many aspects of const-correctness in Chapter
     18, which you find at
     "http://www.inf.uni-konstanz.de/~kuehl/cpp/cppfaq.htm/const-correctness.html".
   -  You may find my thoughts about const-correctness with containers that
      have reference semantics at
      "http://www.geophysik.uni-frankfurt.de/~forbrig/txt/cxx/tutorial/consthandle.doc/doc/html/index.html".

*/

/*======================================================================*/

/*! \page page_using HOWTO use this library

  Contents of this page:
  - \ref sec_using_constructor
  - \ref sec_using_examples

\section sec_using_constructor Constructing arrays
  Arrays are most easy constructed by means of the aff::Shaper.
  If you want e.g. define an array \c A of element type int with Fortran
  layout, three dimensions and the index ranges [-2:2], [1:4], and [6:10] you
  have to code
  \code
  using namespace aff;
  Array<int> A(Shaper(-2,2)(4)(6,10));
  \endcode
  The shaper is presented in aff/shaper.h.

\section sec_using_examples Example code
  The test programs may serve as examples for using this library:
  - tests/arraytest.cc
  - tests/shapetest.cc
  - tests/reprtest.cc
  - tests/simplearraytest.cc

\todo
We need more text and examples.

*/


/*======================================================================*/

/*! \page page_notes General notes

  Contents of this page:
  - \ref sec_notes_need

\section sec_notes_need The need of an array library
  
  One major reason for replacing Fortran77 by C++ in numerical code is the
  convenience in expressing logistics. Data of different type and size may be
  packed into classes and encapsulated from the outside world. Most numerical
  results are to be stored in arrays, multi-dimensional arrays in particular.
  This library provides the basic functionality for storing many data of the
  same type in memory, passing them around between subroutines in an efficient
  way and accessing them through convenient interfaces. The main purpose of
  this library is not calculation but managing (passing between program
  modules, selection of subsets of the data) large amounts of numbers. In the
  future it might provide interfaces to libraries like blitz++ for finite
  difference calculations, MTL for linear algebra calculations, and POOMA for
  parallel computations.

*/

/*======================================================================*/

/*! \page page_naming Naming conventions

  Contents of this page:
  - \ref sec_nameing_identifiers
  - \ref sec_nameing_macros
  - \ref sec_nameing_files

\section sec_nameing_identifiers Classes, Typedefs, etc.

  During coding it is sometimes helpfull to recognize the meaning of an
  identifier due to some signals in irs name. Therefor the following
  guidelines are used. The nameing of template parameters is left free for
  convenience.

  \par Classes
   
  Class names always start with a capital letter.

  \par Typedefs

  Typedefs always start with a capital \c T.

  \par Member data

  Member data identifiers always start with a capital \c M.

\section sec_nameing_macros Preprocessor macros

  Preprocessor macros like include-guards should have the prefix "AFF_".
  The macros in the \ref group_helpers are an exception to this rule.

\section sec_nameing_files Filenames

  Files with the extension \c .cc contain only non-template definitions. Files
  with the extension \c .h may contain prototypes, class declarations or
  template code. Files ending on \c def.h contain template code definitions
  that is factored out to be compilable into a binary library for explicit
  instantiation.

  The main directory %aff contains headers that are usually included by the
  user. A subdirectory %aff/lib contains additional headers that are mostly
  used internally.

*/

// ----- END OF README -----