Commit c9dfa7d2 authored by thomas.forbriger's avatar thomas.forbriger Committed by thomas.forbriger
Browse files

reorganizing documentation, started to add proper doxygen groups

This is a legacy commit from before 2015-03-01.
It may be incomplete as well as inconsistent.
See COPYING.legacy and README.history for details.


SVN Path:     http://gpitrsvn.gpi.uni-karlsruhe.de/repos/TFSoftware/branches/libfourier
SVN Revision: 3943
SVN UUID:     67feda4a-a26e-11df-9d6e-31afc202ad0c
parent 026ce2c1
......@@ -105,7 +105,7 @@ SRC=lib/error.cc dump.cc lib/strided.cc lib/stridedstepper.cc \
# test programs are placed in a subdirectory
TESTS=$(wildcard tests/*.cc)
# whereever we find a README, we will use it
README=$(shell find . -name README) README.changelog
README=$(shell find . -name README) README.changelog README.groups
# place where we will copy header files
INCINSTALLPATH=$(LOCINCLUDEDIR)/aff
......
......@@ -52,6 +52,9 @@
* removed from the library (\ref sec_design_binary)
* - 14/05/2011 V1.7 (thof)
* - add info on raw-major and column-major order
* - 15/05/2011 V1.8 (thof)
* - reordered documentation, movde modules to
* README.groups
*
* ============================================================================
*/
......@@ -79,21 +82,19 @@ $Id$
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_need
- \ref sec_main_peculiar
- \ref sec_main_modules
Additional information:
- \ref page_changelog
- \ref page_project_status
- \ref page_using
- \ref page_array_layout
- \ref page_design
- \ref page_using
- \ref page_notes
- \ref page_naming
- \ref page_representation
- \ref page_fortran
- \ref page_changelog
- \ref page_project_status
\section sec_main_aims Aims of the library
......@@ -106,93 +107,54 @@ $Id$
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
The object code is placed in libaff.a.
Contents of this page:
\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 (see example tests/arraytest.cc).
-# aff::Strided is the shape of a strided Fortran array and defines the
memory layout of aff::Array objects (see example
tests/shapetest.cc).
-# 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 and example tests/reprtest.cc).
-# aff::SimpleRigidArray is a linear array with size fixed at compile-time.
There are several inline functions defined for operations with
this array class (see example tests/simplearraytest.cc).
-# 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 pass Fortran layouts
to array constructors (see example tests/shapetest.cc).
-# aff::Series presented in aff/series.h which is used to interface linear
sequences of data (like time series or Fourier coefficients).
-# aff::Iterator presented in aff/iterator.h which is an iterator interface
to containers like aff::Array or aff::Series (see example
tests/helpertest.cc).
-# aff::subarray presented in aff/subarray.h to conveniently create
subarrays from aff::Array objects (see example
tests/helpertest.cc).
-# aff::slice presented in aff/slice.h to conveniently create
slices from aff::Array objects (see example
tests/helpertest.cc).
-# aff::FortranArray and its associate aff::util::FortranShape are presented
in aff/fortranshape.h. They calculate a Fortran 77 array
layout (leading dimensions) from a given AFF array (see
example tests/f77test.cc).
-# 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.
\sa \ref sec_design_namespaces
\sa \ref sec_naming_files
\section sec_main_peculiar Peculiarities
\section sec_main_peculiar Peculiarities of AFF
\par Containers use counted references
All containers (e.g. aff::Array, aff::Series) use counted references to access
global memory. Assigning one container object to another just assigns the
reference. Both will use the same data in memory afterwards.
See also \ref page_representation.
\sa \ref page_representation.
\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.
\sa \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.
\sa \ref sec_design_multidimensional.
\section sec_main_need Why do we need this 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.
\sa http://www.sophya.org/, http://www.boost.org
\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
The object code is placed in libaff.a.
\sa \ref group_array, \ref group_array_extensions
*/
/*======================================================================*/
......@@ -862,30 +824,6 @@ 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
......
/*! \file libaff/README.groups
* \brief groups in libaff
*
* ----------------------------------------------------------------------------
*
* $Id$
*
* Copyright (c) 2011 by Thomas Forbriger (BFO)
*
* groups in code for C++ containers for numbers (libaff)
*
* REVISIONS and CHANGES
* - 15/05/2011 V1.0 Thomas Forbriger
*
\todo
Define more groups to cover the complete code
* ============================================================================
*/
/*======================================================================*/
/*! \brief Basic array module
\defgroup group_array Basic array module
By including aff/array.h you will get access to the following modules:
-# aff::Array is the main array interface (see example tests/arraytest.cc).
-# aff::Strided is the shape of a strided Fortran array and defines the
memory layout of aff::Array objects (see example
tests/shapetest.cc).
-# 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 and example tests/reprtest.cc).
-# aff::SimpleRigidArray is a linear array with size fixed at compile-time.
There are several inline functions defined for operations with
this array class (see example tests/simplearraytest.cc).
-# 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).
Helpers are available in \ref group_array_extensions.
\todo
Place ingroup definitions in source code
\todo
Provide additional groups for Series and SimpleRigidArray
*/
/*----------------------------------------------------------------------*/
/*! \brief Extensions for array module
\defgroup group_array_extensions Extensions for array module
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 pass Fortran layouts
to array constructors (see example tests/shapetest.cc).
-# aff::Series presented in aff/series.h which is used to interface linear
sequences of data (like time series or Fourier coefficients).
-# aff::Iterator presented in aff/iterator.h which is an iterator interface
to containers like aff::Array or aff::Series (see example
tests/helpertest.cc).
-# aff::subarray presented in aff/subarray.h to conveniently create
subarrays from aff::Array objects (see example
tests/helpertest.cc).
-# aff::slice presented in aff/slice.h to conveniently create
slices from aff::Array objects (see example
tests/helpertest.cc).
-# aff::FortranArray and its associate aff::util::FortranShape are presented
in aff/fortranshape.h. They calculate a Fortran 77 array
layout (leading dimensions) from a given AFF array (see
example tests/f77test.cc).
-# 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.
\sa \ref sec_design_namespaces
\sa \ref sec_naming_files
\todo
Place ingroup definitions in source code
*/
/*======================================================================*/
// ----- END OF README.groups -----
......@@ -153,6 +153,7 @@ namespace aff {
template<class T> class Array;
/*! \brief Array base class
* \ingroup group_array
*
* This is a multidimensional (array) container that uses a strided memory
* layout (Fortran shape) and counted references to data in global memory.
......@@ -338,6 +339,7 @@ namespace aff {
/*======================================================================*/
/*! \brief Full multi-dimensional array functionality.
* \ingroup group_array
*
* This is the full array class template. It adds no additional
* functionality to its base class aff::ConstArray. But it provied acess to
......
......@@ -60,8 +60,8 @@ INLINE_INFO = YES
SORT_MEMBER_DOCS = YES
SORT_BRIEF_DOCS = NO
SORT_MEMBERS_CTORS_1ST = NO
SORT_GROUP_NAMES = NO
SORT_BY_SCOPE_NAME = NO
SORT_GROUP_NAMES = YES
SORT_BY_SCOPE_NAME = YES
GENERATE_TODOLIST = YES
GENERATE_TESTLIST = YES
GENERATE_BUGLIST = YES
......@@ -91,6 +91,7 @@ INPUT = ./
INPUT_ENCODING = UTF-8
FILE_PATTERNS = README \
README.changelog \
README.groups \
*.h \
*.cc
RECURSIVE = YES
......@@ -218,14 +219,14 @@ PERLMOD_MAKEVAR_PREFIX =
# Configuration options related to the preprocessor
#---------------------------------------------------------------------------
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = NO
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = NO
SEARCH_INCLUDES = YES
INCLUDE_PATH =
INCLUDE_PATH =
INCLUDE_FILE_PATTERNS =
PREDEFINED = DOXYGEN_MUST_SKIP_THIS
EXPAND_AS_DEFINED =
SKIP_FUNCTION_MACROS = YES
EXPAND_AS_DEFINED =
SKIP_FUNCTION_MACROS = NO
#---------------------------------------------------------------------------
# Configuration::additions related to external references
#---------------------------------------------------------------------------
......
......@@ -31,6 +31,7 @@
* - 10/02/2004 V1.0 Thomas Forbriger
* - 05/07/2005 V1.1 support modification of data in containers that are
* declared const
* - 15/05/2011 V1.2 added group name (thof)
*
* ============================================================================
*/
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment