thomas.forbriger committed Dec 06, 2002 1 /*! \file README  thomas.forbriger committed Dec 06, 2002 2  * \brief C++ containers for numbers (libaff)  thomas.forbriger committed Dec 06, 2002 3 4 5  * * ---------------------------------------------------------------------------- *  thomas.forbriger committed Dec 08, 2002 6  * $Id: README,v 1.3 2002-12-08 22:28:05 forbrig Exp$  thomas.forbriger committed Dec 06, 2002 7 8 9  * * Copyright (c) 2002 by Thomas Forbriger (IMG Frankfurt) *  thomas.forbriger committed Dec 06, 2002 10  * C++ containers for numbers (libaff)  thomas.forbriger committed Dec 06, 2002 11 12  * * This file contains:  thomas.forbriger committed Dec 06, 2002 13  * - documentation of namespace aff  thomas.forbriger committed Dec 06, 2002 14 15  * - mainpage text * - documentation for pages:  thomas.forbriger committed Dec 08, 2002 16  * - \ref page_design  thomas.forbriger committed Dec 06, 2002 17 18  * - \ref page_using * - \ref page_notes  thomas.forbriger committed Dec 08, 2002 19 20 21 22  * - \ref page_naming * * \todo * Rework this README  thomas.forbriger committed Dec 06, 2002 23 24  * * REVISIONS and CHANGES  thomas.forbriger committed Dec 06, 2002 25  * - 06/12/2002 V1.0 Thomas Forbriger (copied from libcontxx)  thomas.forbriger committed Dec 06, 2002 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).  thomas.forbriger committed Dec 08, 2002 34  While aff::Array is the only compound in this namespace, all others are  thomas.forbriger committed Dec 06, 2002 35 36  placed in sub namespaces. When working with the binary version of the library, you have to use  thomas.forbriger committed Dec 08, 2002 37  aff::prebuilt in place of contxx (see \ref sec_main_binary).  thomas.forbriger committed Dec 06, 2002 38  */  thomas.forbriger committed Dec 08, 2002 39 40 namespace aff { } // namespace aff  thomas.forbriger committed Dec 06, 2002 41 42 43 44 45 46  /*======================================================================*/ /*! \mainpage \author Thomas Forbriger  thomas.forbriger committed Dec 06, 2002 47 48 49 \author Wolfgang Friederich \since December 2002 \date December 2002  thomas.forbriger committed Dec 06, 2002 50 \version V1.0  thomas.forbriger committed Dec 08, 2002 51 $Id: README,v 1.3 2002-12-08 22:28:05 forbrig Exp$  thomas.forbriger committed Dec 06, 2002 52 53  Contents of this page:  thomas.forbriger committed Dec 08, 2002 54  - \ref sec_main_aims  thomas.forbriger committed Dec 06, 2002 55  - \ref sec_main_modules  thomas.forbriger committed Dec 08, 2002 56 57 58 59  - \ref sec_main_interface - \ref sec_main_namespace_aff - \ref sec_main_headers - \ref sec_main_constness  thomas.forbriger committed Dec 06, 2002 60 61  Additional information:  thomas.forbriger committed Dec 08, 2002 62 63 64 65  - \ref page_design - \ref page_using - \ref page_notes - \ref page_naming  thomas.forbriger committed Dec 06, 2002 66  - \ref page_representation  thomas.forbriger committed Dec 08, 2002 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81  \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 /*----------------------------------------------------------------------*/  thomas.forbriger committed Dec 06, 2002 82 83 84  \section sec_main_modules Modules of the library  thomas.forbriger committed Dec 08, 2002 85 86 87 88 89 90 91 92  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.  thomas.forbriger committed Dec 06, 2002 93 94  \todo  thomas.forbriger committed Dec 08, 2002 95 96 97  Other essential modules: - A projection and slicing module. - Basic whole-array operator functions for +,-.* etc.  thomas.forbriger committed Dec 06, 2002 98 99  \todo  thomas.forbriger committed Dec 08, 2002 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115  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  thomas.forbriger committed Dec 06, 2002 116  \code  thomas.forbriger committed Dec 08, 2002 117  using namespace aff;  thomas.forbriger committed Dec 06, 2002 118  \endcode  thomas.forbriger committed Dec 08, 2002 119 120 121 122 123  or \code using aff::Array; \endcode for convenient access.  thomas.forbriger committed Dec 06, 2002 124   thomas.forbriger committed Dec 08, 2002 125  \sa \ref sec_design_namespaces  thomas.forbriger committed Dec 06, 2002 126   thomas.forbriger committed Dec 08, 2002 127 /*----------------------------------------------------------------------*/  thomas.forbriger committed Dec 06, 2002 128   thomas.forbriger committed Dec 08, 2002 129 \subsection sec_main_headers Header files  thomas.forbriger committed Dec 06, 2002 130   thomas.forbriger committed Dec 08, 2002 131 132 133 134 135 136 137 138 139  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  thomas.forbriger committed Dec 06, 2002 140 141 142  /*----------------------------------------------------------------------*/  thomas.forbriger committed Dec 08, 2002 143 \section sec_main_constness Constness of arrays  thomas.forbriger committed Dec 06, 2002 144   thomas.forbriger committed Dec 08, 2002 145 146 147 148 149 150 151 152  We distinguish between the constness of the array and the constness of the elements. A definition \code const aff:Array 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.  thomas.forbriger committed Dec 06, 2002 153   thomas.forbriger committed Dec 08, 2002 154 155 156 157 158 159 160  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 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.  thomas.forbriger committed Dec 06, 2002 161   thomas.forbriger committed Dec 08, 2002 162  \sa \ref sec_design_const  thomas.forbriger committed Dec 06, 2002 163   thomas.forbriger committed Dec 08, 2002 164 */  thomas.forbriger committed Dec 06, 2002 165   thomas.forbriger committed Dec 08, 2002 166 /*======================================================================*/  thomas.forbriger committed Dec 06, 2002 167   thomas.forbriger committed Dec 08, 2002 168 /*! \page page_design Design decisions  thomas.forbriger committed Dec 06, 2002 169   thomas.forbriger committed Dec 08, 2002 170 171 172 173 174 175  Contents of this page: - \ref sec_design_copy - \ref sec_design_namespaces - \ref sec_design_binary - \ref sec_design_multidimensional - \ref sec_design_const  thomas.forbriger committed Dec 06, 2002 176   thomas.forbriger committed Dec 08, 2002 177 178 179 180 181 182 183 184 185 186 187 188 \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  thomas.forbriger committed Dec 06, 2002 189  \code  thomas.forbriger committed Dec 08, 2002 190  A=B;  thomas.forbriger committed Dec 06, 2002 191  \endcode  thomas.forbriger committed Dec 08, 2002 192 193 194 195  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.  thomas.forbriger committed Dec 06, 2002 196   thomas.forbriger committed Dec 08, 2002 197 198  However, in many cases (most cases?) we will use the copy operator in the senso of a mathematical equation. This may read like  thomas.forbriger committed Dec 06, 2002 199  \code  thomas.forbriger committed Dec 08, 2002 200  A=B+C;  thomas.forbriger committed Dec 06, 2002 201  \endcode  thomas.forbriger committed Dec 08, 2002 202 203 204 205 206  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.  thomas.forbriger committed Dec 06, 2002 207   thomas.forbriger committed Dec 08, 2002 208 209 210  \todo An answer how the semantics of the copy operator should be chosen is not yet found. Find it!  thomas.forbriger committed Dec 06, 2002 211 212 213  /*----------------------------------------------------------------------*/  thomas.forbriger committed Dec 08, 2002 214 \section sec_design_namespaces Namespaces  thomas.forbriger committed Dec 06, 2002 215   thomas.forbriger committed Dec 08, 2002 216 217 218  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.  thomas.forbriger committed Dec 06, 2002 219 220 221  /*----------------------------------------------------------------------*/  thomas.forbriger committed Dec 08, 2002 222 \section sec_design_binary Binary library  thomas.forbriger committed Dec 06, 2002 223 224 225  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  thomas.forbriger committed Dec 08, 2002 226  libaff.a should reduce compilation times in comparison to complete  thomas.forbriger committed Dec 06, 2002 227 228 229 230 231 232 233  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  thomas.forbriger committed Dec 08, 2002 234  You will find all modules in aff::prebuilt that are in contxx in the  thomas.forbriger committed Dec 06, 2002 235 236 237 238  full-template version. \sa tests/binarraytest.cc \sa binarray.h  thomas.forbriger committed Dec 08, 2002 239  \sa \ref sec_using_include  thomas.forbriger committed Dec 06, 2002 240   thomas.forbriger committed Dec 08, 2002 241 242 243 244 245  The inclusion of header files is controlled by a set of preprocessor macros. \sa AFF_PREBUILT \sa AFF_NO_DEFINITIONS \sa AFF_COMPILING_LIBRARY \sa DOXYGEN_MUST_SKIP_THIS  thomas.forbriger committed Dec 06, 2002 246   thomas.forbriger committed Dec 08, 2002 247 248  \todo Document the different precocessor macros we use.  thomas.forbriger committed Dec 06, 2002 249   thomas.forbriger committed Dec 08, 2002 250 251 252 253  \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!  thomas.forbriger committed Dec 06, 2002 254   thomas.forbriger committed Dec 08, 2002 255 /*----------------------------------------------------------------------*/  thomas.forbriger committed Dec 06, 2002 256   thomas.forbriger committed Dec 08, 2002 257 \section sec_design_multidimensional Multidimensional arrays  thomas.forbriger committed Dec 06, 2002 258   thomas.forbriger committed Dec 08, 2002 259 260  \todo Explain Wolfgangs idea of multidimensional arrays.  thomas.forbriger committed Dec 06, 2002 261   thomas.forbriger committed Dec 08, 2002 262 /*----------------------------------------------------------------------*/  thomas.forbriger committed Dec 06, 2002 263   thomas.forbriger committed Dec 08, 2002 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 \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  thomas.forbriger committed Dec 06, 2002 317 318 319 320 321  */ /*======================================================================*/  thomas.forbriger committed Dec 08, 2002 322 /*! \page page_using HOWTO use this library  thomas.forbriger committed Dec 06, 2002 323   thomas.forbriger committed Dec 08, 2002 324 325 326  Contents of this page: - \ref sec_using_constructor - \ref sec_using_include  thomas.forbriger committed Dec 06, 2002 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343  \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 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  thomas.forbriger committed Dec 08, 2002 344 345 346  \todo rework this section  thomas.forbriger committed Dec 06, 2002 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 \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.  thomas.forbriger committed Dec 08, 2002 371 372 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  \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.  thomas.forbriger committed Dec 06, 2002 401 402 403 404 */ /*======================================================================*/  thomas.forbriger committed Dec 08, 2002 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 436 437 438 439 440 441 442 443 444 445 446 /*! \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_". \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.  thomas.forbriger committed Dec 06, 2002 447 448 449 */ // ----- END OF README -----