Index: library/doc/guides/install.dox
===================================================================
--- library/doc/guides/install.dox (revision 608)
+++  (revision )
@@ -1,90 +1,0 @@
-/*!
-\page install How to install BDM
-
-BDM is written as a multiplatform library, which was tested on Linux, Windows and Mac OSX.
-However, installation on each platform is specific.
-
-BDM comes in two basic versions:
-\li \b binary   with precompiled executables and matlab mex files that can be configured by external text files
-\li \b source \b code  that can be compiled into any required form. 
-Distribution of the binary form is not currently available. It is planned in latter stages of development.
-
-
-\section src Source code
-
-is available from svn repository:
-http://mys.utia.cas.cz:1800/svn/mixpp using guest/guest as login/password.
-
-For download use an appropriate SVN client http://subversion.tigris.org/links.html#clients
-
-Download the source files to any directory of your choise, this directoory will be refered to as \<bdm_dir\>.
-
-\subsection pre Prerequisities
-
-You need to have the following tools available on your system:
-\li working C++ compiler, e.g. gcc on Linux, or Visual Studio on windows
-\li CMake, a cross-platform build system, http://www.cmake.org
-\li ITPP library, http://itpp.sourceforge.net/ which is a part of all major linux distributions, for its installation on Windows, see Section Windows.
- 
-\section lin Linux
-
-All prerequisities are available as binary packages for most distribution. E.g. for debian-based distributions, use
-\code
-apt-get install g++ cmake libitpp-dev 
-\endcode
-
-\note If you want to use mex files, you need to build IT++ from sources using the classi configure;make;make install. 
-The necessary flags for configure for mex compilation are in file linux/configure_itpp.
-
-Compile the BDM library and its applications using 
-\code
-$ cd <bdm_dir>/library/
-$ cmake .
-$ make
-\endcode
-
-
-\section win Windows
-
-The following approach was tested on Visual Studio 9, so we recommend to download and install it. 
-http://www.microsoft.com/express/vc/
-
-Make sure you have cmake installed.
-
-Expert users are advised to download and compile their ITPP version following a guide on : 
-http://itpp.sourceforge.net/current/installation.html
-
-For convenience of the beginners, DLLS of the ACML and lib+include files for ITPP and ACML are
-provided at: http://staff.utia.cas.cz/smidl/Public/mixpp_win32lib.zip
-If you want to use them copy the content of the zip file to \<bdm_dir\>/library/system/win32/ directory and
-make sure to set your PATH environment variable:
-\code
- Path = %PATH%; <bdm_dir>\library\system\win32\dll
-\endcode
-Otherwise you will not be able to run any programs.
-
-
-Compilation of BDM:
-
- * When everything is set-up, make a copy of library\system\win32\run_cmake.bat, edit it 
-  to reflect your environment (i.e. change paths to cmake and your C++ target environment) 
-  and run it.
-
- * It should generate build files for your compiler in the main BDM 
-  directory
-
-\section mac Mac OS X
-
-All prerequisities for Mac OS X are avaliable except for ITPP, make sure you have them installed.
-
-However, its compilation is straightforward. 
-
- 1. Download the latest stable release from http://itpp.sourceforge.net
- 2. Compile it using script system/mac/itpp_compile.sh
-
-The default cmake configuration is looking for itpp in directory mac/itpp, make sure you have symlinks to this directory.
-
-If itpp compilation is successfull, you can run Cmake. Fill in the paths to your BDM directory, run Configure followed by Create.
-Configuration files for your favourite build environment should be created in the BDM directory.
-
-*/
Index: library/doc/guides/unit_testing.dox
===================================================================
--- library/doc/guides/unit_testing.dox (revision 608)
+++  (revision )
@@ -1,183 +1,0 @@
-/*!
-\page unit_testing Unit testing of BDM
-
-Unit tests are simple, fast and easy to run tests of small pieces of
-code (the "units") designed to reassure developers that individual
-parts of the developped functionality behave as they're meant to. BDM
-being an object-oriented library, the independent units are classes,
-tested by calling their individual methods and comparing actual to
-expected results.
-
-Unit tests are especially useful for C++, where the simplest change
-can introduce (or uncover) a difficult-to-find bug. They also
-facilitate changing the internal structure of classes without
-modifying their external behavior - unit tests can be run before and
-after such a change to make sure the behavior had indeed stayed the
-same. More ambitiously, tests can be written before implementing new
-functionality, serving as its machine-checkable specification. Some
-authorities go so far as to demand that "not a single line of code" be
-written before having a failing unit test for it first, but BDM unit
-testing isn't that demanding - it does facilitate the style for
-developers who prefer it, but most BDM code is tested retroactively,
-with new tests suggested by various considerations (see below).
-
-\section Setup
-
-Unit tests of BDM use a 3rd-party unit testing framework, UnitTest++
-(from http://unittest-cpp.sourceforge.net/ ), which is designed
-specifically for C++, reasonably popular and maintained (for a C++
-unit testing framework), works on Unix, Windows and Mac, allows simple
-test addition and proved to be readily extensible. Sources of
-UnitTest++ are included in directory library/tests/unittest-cpp, so
-that they can be built as part of the normal BDM build, without the
-need for explicit installation and setup, and are lightly modified for
-specific requirements of BDM.
-
-Existing unit tests are collected into a testsuite executable (so that
-they can all easily be run together), whose sources are in
-library/tests. Apart from the top-level testsuite.cpp, testsuite
-sources are generally named &lt;classname&gt;_test.cpp, where
-&lt;classname&gt; is the class tested by the file (or a base class of
-classes tested by the file, when these derived classes are similar
-enough to be tested in the same way). BDM doesn't test abstract
-classes using mock-ups (although it does test some template
-instantiations on test-only classes) - all its abstract classes
-already have concrete children and methods of the base class can be
-tested on them.
-
-When run, testsuite prints to standard output the names of performed
-tests and error messages when they fail, which means, among other
-things, that it should generally be run from the command line - even
-on Windows. Note that while UnitTest++ does have support for more
-elaborate GUIs, this support hasn't been extended for BDM-specific use
-cases. Testsuite can also be run under debugging tools - not only
-under a debugger, but also valgrind for checking memory management,
-coverage tools etc.
-
-Specific tests can be run individually, by passing their name (or
-names) as a command-line argument to testsuite. Note that a test which
-behaves differently depending on which tests run before it is a bug in
-testsuite (this can happen e.g. when using RVs, which are global -
-it's probably best to include the tested class name in their names,
-although not all existing tests do that yet). Tests of sampling and
-other functionality depending on random inputs can occasionally fail.
-Whether that's due to skewed inputs, BDM bugs or too tight error
-limits is not clear. Testsuite aims for every test passing with at
-least 95% probability, but the quantification of error limits isn't
-finished yet.
-
-Not all tests depending on UnitTest++ are in testsuite. Performance
-experiments have their own executables - currently just
-square_mat_stress, for testing BDM matrix wrappers. square_mat_stress
-is more configurable than testsuite: it doesn't generate its own
-random data, but reads them from a configuration file (named
-agenda.cfg by default) generated by another executable,
-square_mat_prep. This allows generation (and checking) of test inputs
-for various numerically demanding scenarios, which are encapsulated in
-square_mat_prep's generators - that is, classes implementing its
-generator interface. generators themselves are configurable using the
-same scripting framework as other BDM classes, and both
-square_mat_prep and square_mat_stress have command-line parameters -
-run them with '-?' to see the list. Analogical support can be created
-for other classes which would benefit from it. Focus of stress tests
-is rather different from unit tests as generally understood - that a
-class has stress tests doesn't mean it shouldn't be tested separately
-inside testsuite.
-
-\section new_unit_tests Adding new unit tests
-
-Adding new unit tests is encouraged - it's a good way to get
-acquainted with the library, and there's always space for more
-tests.
-
-Unit tests are implemented by adding a block of code (it actually
-isn't just a function body, but it looks like one) starting with the
-TEST macro, whose argument is the test name:
-
-\code
-TEST ( test_egiw ) {
-	epdf_harness::test_config ( "egiw.cfg" );
-}
-\endcode
-
-"UnitTest++.h" should be included in every test file to have the macro
-defined.
-
-Tests are usually named test_&lt;classname&gt;, or
-test_&lt;classname&gt;_postfix when a class has more than one test:
-
-\code
-TEST ( test_egiw_1_2 ) {
-\endcode
-
-This is useful when a class should be thoroughly tested from multiple
-aspects, e.g. for different dimensions. Exception-throwing execution
-paths are also generally run by extra tests, whose names end with
-_error. Note that each test in testsuite must have a unique name,
-which must be a legal C++ identifier.
-
-Testsuite has explicit support for testing classes derived from
-bdm::epdf and bdm::mpdf: bdm::epdf_harness and
-bdm::mpdf_harness. These classes run a list of tests on objects
-created from the specified configuration file (normally called
-&lt;classname&gt;.cfg) and check them against expected values also
-specified in that file, so that a test using harness is just a
-single-line call to its test_config method (as above).
-
-Unit tests can also be written explicitly. The test body is normal C++
-code, implementing the checks of actual against expected values using
-various CHECK_* macros defined by UnitTest++:
-
-\code
-	double summ = 0.0;
-	for ( int k = 0; k < n; k++ ) { // ALL b
-...
-	}
-
-	CHECK_CLOSE ( 1.0, summ, 0.1 );
-\endcode
-
-Note that when checking vectors or matrices, you should also include
-"mat_checks.h", which defines their comparison. Unit tests shouldn't
-require any user interaction and probably shouldn't output anything
-other than error reports via the UnitTest++ facilities - among other
-things, UnitTest++ uses C functions for its output, and therefore a
-test printing via std::cout and std::cerr may report in rather
-confusing mixed order.
-
-Developers wishing to add new tests can use various heuristics to come
-up with the specific functionality to test - a selection is described
-below, roughly in the order of usefulness.
-
-\subsection existing_bugs Eliciting existing bugs
-
-When the library has a bug, it may be useful to isolate the smallest
-possible code snippet which exhibits it - if not always, then at
-least as reliably as possible. Such a snippet is a good candidate for
-a unit test - it can be added either before the bug is fixed, or
-afterwards.
-
-\subsection tricky_parts Testing the code known to be tricky
-
-Every body of code has its dark corners - copy&pasted legacy code,
-highly optimized algorithms, complicated interactions. These should be
-tested first.
-
-\subsection unclear_behavior Documenting and stabilizing unclear behavior
-
-The library can behave in ways surprising its users without being
-necessarily "wrong". In such cases, it's most important that all
-maintainers agree on what the correct behavior should be (so that
-attempts to fix it don't run in circles). Unit tests constraining the
-contested functionality communicate very efficiently what their author
-thinks the behavior should (or shouldn't) be.
-
-\subsection coverage Increasing test coverage
-
-Ideally, unit tests should test every method of every class (there are
-higher ideals, but they're even less realistic). Failing that, at
-least some methods of every class should be tested. Coverage tools
-(e.g. gcov) can show which parts of the library are not exercised by
-testsuite.
-
-*/
Index: library/doc/guides/codingrules.dox
===================================================================
--- library/doc/guides/codingrules.dox (revision 608)
+++  (revision )
@@ -1,116 +1,0 @@
-/*!
-\page codingrules Coding Rules (Mostly inherited from IT++)
-
-In the following sections we describe the naming conventions which are
-used for files, classes, structures, local variables, and global variables.
-
-
-\section cr_variables Default Naming Rules for Variables
-
-Generally, variables are named using lower-case letters and words are separated using
-under-score. But there are many exceptions, for instance abbreviations or classical 
-matematical notations. Therefore, coding rules for variables are quite free. Examples:
-
-<ul>
-<li> \c `FFT_size' </li>
-<li> \c `initial_RV' </li>
-<li> \c `my_variable' </li>
-</ul>
-
-\section cr_files Default Naming Rules for Files
-
-Files are named using lower-case letters and words are separated using
-under-score. If an abbreviation is inevitable within file name, it is written with 
-lower-case letters. 
-
-Source files are named using <tt>`.cpp'</tt> suffix, whereas header
-files end with <tt>`.h'</tt> extension. Examples:
-
-<ul>
-<li> <tt>`my_file.h'</tt> </li>
-<li> <tt>`user_info.cpp'</tt> </li>
-</ul>
-
-\section cr_file_templates Form of the source files
-
-For all the library classes, both header file `[filename].h' and source file 
-`[filename].cpp' should be implemented. And the following few rules should be 
-respected   
-
-<ul>
-
-<li> if possible, each `\#include ... ' dircetive should be located within the `.h'
-file, one obvious exception is the case of `\#include "[filename].h"' written in 
-`[filename].cpp' </li>
-
-<li> firstly, system headers should be included (i.e. those with brackets 
-`\#include \<system_header_name\>'), other headers (like `\#include "my_header_name.h"') 
-should follow (this rule leads to the faster search of an error on some 
-compilators) </li>
-
-<li> source code itself should be placed in the `.cpp' file, `.h' should 
-contains only class declarations and documentation (this rule has a few exceptions like
- inline functions, templates and some extremely short function bodies)</li>
-
-</ul>
-
-Rules considering formatting of the source code itself are stored in the 
-file /system/astylerc, which is a configuration file for code formating 
-utility named ASTYLE. To apply them, download the proper version from 
-its web page http://astyle.sourceforge.net/     
-
-\section cr_functions Default Naming Rules for Functions
-
-Function names are named using lower-case letters and words are
-separated using under-score. Abbreviations, when used in function
-names, are also written with lower-case letters. This rule applies
-both to stand-alone functions as well as to member functions of
-classes. Example:
-
-<ul>
-<li> <tt>int my_function_name(int a, int b)</tt> </li>
-</ul>
-
-
-\section cr_specialfunctions Convention for sensitive functions
-
-For efficiency, some functions may return pointers to internal variables.
-Such functionality is indicated by underscore as the first letter in the
-the name.
-
-<ul>
-<li> <tt>mat* _internal_matrix()</tt> </li>
-</ul>
-
-
-\section cr_classes Default Naming Rules for Classes and Structures
-
-Each new word in a class or structure name should always start with a
-capital letter and the words should not be separated. Abbreviations are 
-written with capital letters. Examples:
-
-<ul>
-<li> \c `MyClassName' </li>
-<li> \c `MyStructName' </li>
-<li> \c `OFDM' </li>
-</ul>
-
-
-\section cr_classes_functionality Default Functionality of Classes
-
-All classes that are configured by input parameters should include:
-
-<ul>
-<li> default empty constructor </li>
-<li> one or more additional constructor(s) that takes input parameters
-and initializes the class instance </li>
-<li> setup function, preferably named \c `setup' or \c
-`set_parameters' </li>
-</ul>
-
-Explicit destructor functions are not required, unless they are
-needed. It shall not be possible to use any of the other member
-functions unless the class has been properly initiated with the input
-parameters.
-
-*/
Index: library/doc/guides/library_structure.dox
===================================================================
--- library/doc/guides/library_structure.dox (revision 608)
+++  (revision )
@@ -1,32 +1,0 @@
-/*!
-\page library_structure Library structure
-
-\todo it is necessary to fill in the missing descriptions of the directories below 
-
-Here you find infromation about the library structure. List of its 
-subdirectories with a basic description follows:
-<ul>
-<li> source:/bdm -- library source codes </li>
-<li> source:/bdm/base -- base classes of the library </li>
-<li> source:/bdm/design -- ... </li>
-<li> source:/bdm/estim -- ... </li>
-<li> source:/bdm/math -- ... </li>
-<li> source:/bdm/mex -- ... </li>
-<li> source:/bdm/stat -- ... </li>
-<li> source:/doc -- library documantation and with some of its sources </li>
-<li> source:/doc/dot -- ... </li>
-<li> source:/doc/html -- html documentation generated automatically by Doxygen </li>
-<li> source:/doc/images -- ... </li>
-<li> source:/doc/issues -- ... </li>
-<li> source:/doc/latex -- latex documentation generated automatically by Doxygen </li>
-<li> source:/doc/local -- documentation pages which are not related to any specific source file </li>
-<li> source:/doc/tutorial -- documentation pages related to the library tutorial</li>
-<li> source:/doc/xml -- ... </li>
-<li> source:/matlab -- matlab input/output utilities </li>
-<li> source:/system -- a system specific parts necessary to run CMake </li>
-<li> source:/tests -- unit tests </li>
-<li> source:/utia_legacy -- ... </li>
-</ul>
-
-
-*/
Index: library/doc/guides/memory_management.dox
===================================================================
--- library/doc/guides/memory_management.dox (revision 608)
+++  (revision )
@@ -1,140 +1,0 @@
-/*!
-\page memory_management Memory Management in BDM
-
-C++ memory management is notoriously flexible, allowing a wide range
-of efficient and dangerous techniques. BDM uses conventions which
-allow high implementation efficiency (not absolutely maximal, but
-within a measurement error of the most efficient way) while
-substantially reducing the danger of memory errors. These conventions
-are described below.
-
-\section Constructors
-
-\li Each configurable class must have public default constructor (that
-is, a constructor which takes no parameters). This is required by the
-configuration framework. Other constructors may also be defined when
-convenient.
-
-\li Each constructor must initialize all fields of the constructed
-object, to prevent unpredictable behavior.
-
-One consequence of the points above is the case when a default
-constructor doesn't have the data with which to initialize a new
-object - in that case it can simply call the default constructors of
-all its object fields (and base classes), but must explicitly
-initialize all numeric fields and raw pointers to 0. Such an object
-isn't valid as constructed and must have some additional
-initialization methods (typically from_settings, for reading its
-configured state), but it can at least be destroyed.
-
-\section Exceptions
-
-BDM uses exceptions to signal runtime and some logic errors. The
-library aims to provide the minimal exception safety (that is,
-throwing an exception doesn't crash and doesn't leak any resources)
-for all thrown exceptions \b except memory errors - when a program
-using BDM exhausts memory, it should be terminated as soon as possible
-(and in most cases it has probably already terminated by
-itself). Specific exceptions may provide stronger guarantees, as
-documented for specific cases. All exceptions thrown out of the
-library are descendants of std::exception. Since they're organized
-into a class hierarchy, they should be caught by reference:
-
-\code
-try {
-	mpdf* mtmp = UI::build<mpdf> (_Sources, i);
-	Sources (i) = mtmp;
-} catch (UIException &exc) {
-\endcode
-
-This saves one call to copy constructor and prevents slicing.
-
-\section Pointers
-
-Pointers are used extensively (for efficiency), but usage of raw
-pointers should be minimized.
-
-Objects allocated by operator new should be assigned to a smart
-pointer instance immediately upon their construction, so that they can
-be automatically deleted after use. BDM implements its own
-reference-counted smart pointer template, bdm::shared_ptr, whose
-interface and semantics are close to the proposed standard
-std::tr1:shared_ptr (which is planned to replace bdm::shared_ptr once
-it becomes widely available). Note that objects allocated on the stack
-\b must \b not have their addresses passed to shared_ptr - that is a
-bug leading to intermittent runtime errors.
-
-Non-null heap pointers may also be kept in instances of object_ptr,
-which is convertible to (and from) shared_ptr. The SHAREDPTR macro (or
-SHAREDPTR2, for templated types) defines standartized names for these
-instances, simplifying library usage:
-
-\code
-/*
- egamma_ptr is typedef for object_ptr<egamma>, whose default
- constructor calls new egamma()
-*/
-egamma_ptr eG; 
-eG->set_parameters ( a, b );
-
-epdf_array Coms ( 2 ); // epdf_array is typedef for Array<shared_ptr<epdf> >
-Coms ( 0 ) = eG; // object_ptr<T> is derived from shared_ptr<T>
-
-/*
- The egamma instance doesn't leak: if the shared_ptr instance which
- wraps it isn't assigned to anything else, the pointer is deleted by
- the destructor of either object_ptr, or Array, whichever runs last.
-*/
-\endcode
-
-Pointers kept in object fields should be wrapped in a shared_ptr
-instance, which will automatically keep them valid (at least) for the
-lifetime of the containing object. When that isn't possible, it should
-be documented why their containing class doesn't delete them and who
-does.
-
-Pointers passed as arguments into functions (and methods) are
-generally not expected to stay valid after the function returns - when
-that is required, the parameter's documentation should specify the
-required scope:
-
-\code
-/* the pointer must stay valid for the lifetime of the object */
-CurrentContext ( const char *name, int idx );
-\endcode
-
-A simpler alternative is just to pass a shared pointer:
-
-\code
-class mepdf : public mpdf
-{
-	shared_ptr<epdf> iepdf;
-public:
-	mepdf (shared_ptr<epdf> em) {
-		iepdf = em;
-\endcode
-
-In the case above, passing a (constant) reference to shared_ptr<epdf>
-might be more efficient, but no measurements have been performed.
-
-Functions returning raw pointers should document the scope of their
-validity:
-
-\code
-/*
- Returns the stored pointer (which remains owned by this
- instance).
-*/
-T *get();
-\endcode
-
-Functions generally shouldn't return raw pointers allocated by
-operator new - such pointers should be wrapped in an instance of
-shared_ptr, so that the pointer's unlimited life expectancy is encoded
-in the function signature:
-
-\code
-virtual shared_ptr<epdf> marginal (const RV &rv) const;
-\endcode
-
-*/
