README 16.5 KB
Newer Older
1
/*! \file README
thomas.forbriger's avatar
thomas.forbriger committed
2
 * \brief C++ containers for numbers (libaff)
3
4
5
 *
 * ----------------------------------------------------------------------------
 *
thomas.forbriger's avatar
thomas.forbriger committed
6
 * $Id: README,v 1.6 2002-12-19 18:30:01 forbrig Exp $
7
8
9
 * 
 * Copyright (c) 2002 by Thomas Forbriger (IMG Frankfurt) 
 * 
thomas.forbriger's avatar
thomas.forbriger committed
10
 * C++ containers for numbers (libaff)
11
12
 *
 * This file contains:
thomas.forbriger's avatar
thomas.forbriger committed
13
 *  - documentation of namespace aff
14
15
 *  - mainpage text
 *  - documentation for pages:
16
 *    - \ref page_design
17
18
 *    - \ref page_using
 *    - \ref page_notes
19
20
21
22
 *    - \ref page_naming
 *
 * \todo 
 * Rework this README
23
24
 * 
 * REVISIONS and CHANGES 
thomas.forbriger's avatar
thomas.forbriger committed
25
 *  - 06/12/2002   V1.0   Thomas Forbriger (copied from libcontxx)
26
27
28
29
30
31
32
33
 * 
 * ============================================================================
 */

/*! \brief Root namespace of library
  
  This namespace contains all modules of the library
  (see \ref sec_main_modules).
34
  While aff::Array is the only compound in this namespace, all others are
35
36
  placed in sub namespaces.
  When working with the binary version of the library, you have to use
37
  aff::prebuilt in place of contxx (see \ref sec_main_binary).
38
 */
39
40
namespace aff {
} // namespace aff
41
42
43
44
45
46

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

/*! \mainpage

\author Thomas Forbriger
thomas.forbriger's avatar
thomas.forbriger committed
47
48
49
\author Wolfgang Friederich
\since December 2002
\date December 2002
50
\version V1.0
thomas.forbriger's avatar
thomas.forbriger committed
51
$Id: README,v 1.6 2002-12-19 18:30:01 forbrig Exp $
52
53

  Contents of this page:
54
  - \ref sec_main_aims
55
  - \ref sec_main_modules
56
57
58
59
  - \ref sec_main_interface
    - \ref sec_main_namespace_aff
    - \ref sec_main_headers
  - \ref sec_main_constness
60
61

  Additional information:
62
63
64
65
  - \ref page_design
  - \ref page_using
  - \ref page_notes
  - \ref page_naming
66
  - \ref page_representation
thomas.forbriger's avatar
thomas.forbriger committed
67
  - \ref page_changelog
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82

\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 kept 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

/*----------------------------------------------------------------------*/
83
84
85

\section sec_main_modules Modules of the library

86
87
88
89
90
91
92
93
  The main module is the array class aff::Array. It provides basic
  functionality through its interface. See the explanation there.

  Utility modules are aff::Iterator for sequential access to the entire array
  (independent of dimensionality) and aff::Shaper for convenient construction
  of arrays of given shape. The aff::Array class is completely independent of
  them. You will have include their headers additionally if you want to use
  them.
94
95

  \todo
96
97
98
  Other essential modules: 
  - A projection and slicing module.
  - Basic whole-array operator functions for +,-.* etc.
99
100

  \todo
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
  Tell about the class aff::Range

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

\section sec_main_interface Interface to the library
\subsection sec_main_namespace_aff Namespace aff

  The main modules like 
  - aff::Array
  - aff::Iterator
  - aff::Shaper

  are presented in namespace aff. In the 
  \ref sec_design_binary "binary version" the same modules are
  presented in namespace aff::prebuilt.
  Use the directive
117
  \code
118
  using namespace aff;
119
  \endcode
120
121
122
123
124
  or
  \code
  using aff::Array;
  \endcode
  for convenient access.
125

126
  \sa \ref sec_design_namespaces
127

128
/*----------------------------------------------------------------------*/
129

130
\subsection sec_main_headers Header files
131

132
133
134
135
136
137
138
139
140
  The main modules are presented in
  - aff/array.h (the aff::Array class and its constituents)
  - aff/binarray.h (the same for its precompiled
    \ref sec_design_binary "binary version")
  - aff/iterator.h (the aff::Iterator class)
  - aff/shaper.h (the aff::Shaper class)

  \sa \ref sec_nameing_files
  \sa \ref sec_using_include
141
142
143

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

144
\section sec_main_constness Constness of arrays
145

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

155
156
157
158
159
160
161
  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. 
162

163
  \sa \ref sec_design_const
164

165
*/
166

167
/*======================================================================*/
168

169
/*! \page page_design Design decisions
170

171
172
173
174
175
176
  Contents of this page:
  - \ref sec_design_copy
  - \ref sec_design_namespaces
  - \ref sec_design_binary
  - \ref sec_design_multidimensional
  - \ref sec_design_const
177

178
179
180
181
182
183
184
185
186
187
188
189
\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 operator thnigs 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 explect. An expression like
190
  \code
191
  A=B;
192
  \endcode
193
194
195
196
  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.
197

198
199
  However, in many cases (most cases?) we will use the copy operator in the
  senso of a mathematical equation. This may read like
200
  \code
201
  A=B+C;
202
  \endcode
203
204
205
206
207
  although expressions like this are not yet supported by the library
  features. In this case we do not mean the \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.
208

209
210
211
  \todo 
  An answer how the semantics of the copy operator should be chosen is not yet
  found. Find it!
212
213
214

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

215
\section sec_design_namespaces Namespaces
216

217
218
219
  We group all code in two namespaces. Major modules which will be accessed by
  the user are place in namepsace aff. Modules meant to be used internally are
  place in aff::util.
220
221
222

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

223
\section sec_design_binary Binary library
224
225
226

  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
227
  libaff.a should reduce compilation times in comparison to complete
228
229
230
231
232
233
234
  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
235
  You will find all modules in aff::prebuilt that are in contxx in the
236
237
238
239
  full-template version.

  \sa tests/binarraytest.cc
  \sa binarray.h
240
  \sa \ref sec_using_include
241

242
243
  The inclusion of header files is controlled by a set of preprocessor macros.
  \sa AFF_PREBUILT
244
  \sa AFF_INDEXCHECK
245
246
247
  \sa AFF_NO_DEFINITIONS
  \sa AFF_COMPILING_LIBRARY
  \sa DOXYGEN_MUST_SKIP_THIS
248

249
250
  \todo
  Document the different precocessor macros we use.
251

252
253
254
255
  \todo
  Explain how to mix the template and the binary version in practice, when
  using additional headers like iterator.h. The include-guards will prevent
  them from being read twice - which is not what we want!
256

257
/*----------------------------------------------------------------------*/
258

259
\section sec_design_multidimensional Multidimensional arrays
260

261
262
  \todo
  Explain Wolfgangs idea of multidimensional arrays.
263

264
/*----------------------------------------------------------------------*/
265

266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
\section sec_design_const Notes on the const-correctness of arrays

  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 copying of an instance with element type \c T to
  an instance of type \c const \c T, we have to provide explicit conversion
  operators. A special class aff::util::Qualified allows automatic
  specialization of array classes and representations to use the correct
  element type conversion in the class conversion operators.

   -  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".

   \sa aff::SharedHeap
319
320
321
322
323

*/

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

324
/*! \page page_using HOWTO use this library
325

326
327
328
  Contents of this page:
  - \ref sec_using_constructor
  - \ref sec_using_include
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345

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

  \sa \ref Shaper
  \sa \ref sec_main_modules_shaper
  \sa contxx::shaper
  \sa contxx::shaper::Fortran
  \sa tests/arraytest.cc
  \sa \ref sec_general_dimension

346
347
348
  \todo
  rework this section

349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
\section sec_using_include Including header files
  The main set of \ref sec_main_modules "array modules" is included by
  contxx/array.h. This include the full templatized version of the library. We
  you want to take advantage of the 
  \ref sec_main_binary "precompiled binary library" you have to include
  contxx/binarray.h.
  This will set CONTXX_PREBUILT which places all definitions in
  contxx::prebuilt rather than just namespace contxx.
  Files like contxx/shaper/fortran.h or contxx/iterator.h are not included
  automatically by array.h or binarray.h.
  You have to include them separately.
  If you are using the precompiled library, you must include them \b after
  binarray.h so that they will place their declarations in contxx::prebuilt
  and take the declarations for other parts of the library from that namespace
  too.

  \par Mixing the pure template library and the binary version
  Mixing the pure template library and the binary version might not work with
  this version of the library. Once you included either array.h or binarray.h
  the include guards will prevent the precompiler from reading the files
  again. 
  This problem may be solved in a future version with a more elaborate include
  guard mechanism that takes account for CONTXX_PREBUILT.

373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
  \todo
  Rework this section

\todo
Tell about usefull header files.
*/


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

/*! \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.

403
404
405
406
*/

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

407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
/*! \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_".
thomas.forbriger's avatar
thomas.forbriger committed
436
  The macros in the \ref group_helpers are an exception to this rule.
437
438
439
440
441
442
443
444
445
446
447
448
449

\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.

450
451
452
*/

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