Changeset 617 for library/doc/tutorial

Timestamp:

09/15/09 23:47:47 (15 years ago)

Author:

smidl

Message:

simulator + doc

Files:

• library/doc/tutorial/01userguide.dox (modified) (8 diffs)

library/doc/tutorial/01userguide.dox

@@ -1 +1 @@
 /*!
-\page user_guide Howto Use BDM - Introduction
-\addindex Howto Use BDM - Introduction
-
-BDM is a library of basic components for Bayesian decision making, hence its direct use is not possible. In order to use BDM the components must be pulled together in order to achieve desired functionality. We expect two kinds of users:
-
- - <b> Basic users </b> who run prepared scripts with different parameterizations and analyze their results,
- - <b> Advanced users </b> who are able to understand the logic of BDM and extend its functionality to new applications.
-
-The primary design aim of BDM was to ease development of complex algorithms, hence the target user is the advanced one. 
-However, running experiments is the first task to learn for both types of users.
-
-\section param Experiment is fully parameterized before execution
-
-Experiments in BDM can be performed using either standalone applications or function bindings in high-level environment. A typical example of the latter being mex file in Matlab environment.
-
-The main logic behind the experiment is that all necessary information about it are gathered in advance in a configuration file (for standalone applications) or in configuration structure (Matlab).
-This approach was designed especially for time consuming  experiments and Monte-Carlo studies for which it suits the most. 
-
-For smaller decision making tasks, interactive use of the experiment can be achieved by showing the full configuration structure (or its selected parts), running the experiment on demand and showing the results.
-
-Semi-interactive experiments can be designed by sequential run of different algorithms. This topic will be covered in advanced documentation.
+\page user_guide Howto Use BDM - System, Data, Simulation
+
+This section serves as introdustion to the scenario of data simulation. Since it is the simpliest of all scenarios defined in \ref user_guide0 it also serves as introduction to configuration of an experiment (see \ref ui) and basic decision making objects (bdm::RV and bdm::DS).
+
+All experiments are demonstarted on scenario simulator which can be either standalone application of mex file (simulator.mex**).
+
 
 \section config Configuration of an experiment
 
-Configuration file (or config structure) is organized as a tree of information. High levels represent bigger structures, leafs of the structures are basic data elements such as strings, numbers or vectors.
+Configuration file (or config structure) is organized as a tree of information. High levels represent complex structures, leafs of the tree are basic data elements such as strings, numbers or vectors.
 
 Specific treatment was developed for objects. Since BDM is designed as object oriented library, the configuration was designed to honor the rule of inheritance. That is, offspring of a class can be used in place of its predecessor. Hence, objects (instances of classes) are configured by a structure  with compulsory field \c class. This is a string variable corresponding to the name of the class to be used.
 
-Consider the following example:
-\code
-DS = {class="MemDS";
-   data = [1, 2, 3, 4, 5, 6, 7];
-}
-\endcode
-or written equivalently in Matlab as
+The configuration has two possible options:
+ - configuration file using syntax of libconfig (see \ref ui),
+ - matlab structure.
+For the purpose of tutorial, we will use the matlab notation. 
+These two options can be mutually converted from one to another using prepared mex files: config2mxstruct.mex and mxstruct2config.mex. Naturally, these scripts require matlab to run. If it is not available, manual conversion is relatively trivial, the major difference is in using different types of brackets (\ref ui)
+
+\subsection first First experiment
+
+The first experiment that can be performed is:
 \code
 DS.class='MemDS';
 DS.Data =[1 2 3 4 5 6];
 \endcode
-
-The code above is the minimum necessary information to run a pre-made algorithm implemented as executable \c estimator or Matlab mex file \c estimator. The expected result for Matlab is:
-\code
->> M=estimator(DS,{})
+which can be found in file bdmtoolbox/tutorials/userguide/memds_example.m.
+
+The code above is the minimum necessary information to run scenario \c simulator in matlab. 
+To actually do so, make sure that matlab can find the simulator.mex file, e.g. by running:
+\code 
+>> addpath _path_to_/bmtoolbox/mex/
+\endcode
+
+The expected result for Matlab is:
+\code
+>> M=simulator(DS)
 
 M = 
@@ -49 +43 @@
 \endcode
 
-The structure \c M has one field called \c ch0 to which the data from \c DS.Data were copied. This was configured to be the default behavior which can be easily changed by adding more information to the configuration structure.
-
-First, we will have a look at all options of MemDS.
-
-\section memds How to understand configuration of classes
-
-As a first step, the estimator algorithm has created an object of class MemDS and called its method  bdm::MemDS::from_setting().
-This is a universal method called when creating an instance of class from configuration. Object that does not implement this method can not be created automatically from configuration.
-
-The documentation contains the full structure which can be loaded. e.g.:
-\code
-{ class = 'MemDS';
-        Data = (...);            // Data matrix or data vector
+If you see this result, you have configured BDM correctly and you have sucessfully run you first experiment. In other cases, please check your installation, \ref installation. 
+All that the simulator did was actually copying \c DS.Data to \c M.ch0. Explanation of the experiment and the logic used there follows.
+
+\section sim Systems and DataSources
+
+In standard system theory, the system is typically illustrated graphically as:
+\dot 
+digraph sys{
+        node [shape=box];
+        {"System"}
+        node [shape=plaintext]
+        {rank="same"; "u"; "System"; "y"}
+        "u" -> "System" -> "y" [nodesep=2];
+}
+\enddot
+Where \c u typically denotes input and \c y denotes output of the system. A causal dependence between input and output is typically presumed.
+
+We are predominantly concerned with discrete-time systems, hence, we will add indeces \f$ _t \f$ to both input and output, \f$ u_t \f$ and \f$ y_t \f$. We presume that the causal dependence is \f$ u_t \f$ comes before \f$ y_t \f$.
+
+One of the definition of a system is that system is a "set of variables observed on a part of the world". Under this definition system is understood as generator of data. This definition may be a considered too simplistic, but it serves well as a description of what software object \c DataSource is.
+
+DataSource is an object that is essentially:
+ -# able to return data observed at time \f$ t \f$, (bdm::DS::getdata()),
+ -# able to perform one a time step, (bdm::DS::step()).
+ -# able to describe what these data are, (bdm::DS::_drv()),
+
+No fruther specification, e.g. if the data are pre-recorded or computed on-the-fly, are given.
+Specific behaviour of various DataSources is implemented as specialization of the root class bdm::DS.
+
+
+\section memds DataSource of pre-recorded data -- MemDS
+
+The first experiment run in \ref first was actually an instance of DataSource of pre-recorded data that were stored in memory, i.e. the bdm::MemDS class.
+
+Operation of such object is trivial, the data are stored as a matrix and the general operations defined above are specialized as follows:
+ -# data observed at time \f$ t \f$  are columns of the matrix, getdata() ruturns current column,
+ -# time step itself is performed by increasing the column index,
+ -# each row is named as "ch0","ch1",...
+
+This is the default bahavior. It can be customized using the UI mechanism.
+When the object of class MemDS is created it calls method  bdm::MemDS::from_setting() and the input structure is parsed for settings. All available settings are documented in the method, see bdm::MemDS::from_setting(). The options are:
+\code
+DS.class = 'MemDS';
+DS.Data = (...);            // Data matrix or data vector
         --- optional ---
-        drv = {class='RV'; ...} // Identification how rows of the matrix Data will be known to others
-        time = 0;               // Index of the first column to user_info,
-        rowid = [1,2,3...];     // ids of rows to be used
-}
-\endcode
-for MemDS. The compulsory fields are listed at the beginning; the optional fields are separated by string "--- optional ---".
-
-For the example given above, the missing fields were filled as follows:
-\code
-  drv  = {class="RV"; names="{ch0 }"; sizes=[1];};
-  time = 0;
-  rowid = [1];
-\endcode
-Meaning that the data will be read from the first column (time=0), all rows of data are to be read (rowid=[1]), and this row will be called "ch0". 
-
-\note <b>Mixtools reference</b> This object replaces global variables DATA and TIME. In BDM, data can be read and written to a range of \c datasources, objects derived from bdm::DS.
+DS.drv = RV({"ch0",...} ); // Identification how rows of the matrix Data will be known to others
+DS.time = 0;               // Index of the first column to user_info,
+DS.rowid = [1,2,3...];     // ids of rows to be used
+\endcode
+The compulsory fields are listed at the beginning; the optional fields are separated by string "--- optional ---".
+
+Fields \c time and \c rowid are self-explanatory. Field \c drv is a the one that specifies identification of the data elements, (point 3. of the general requirements of a DataSource). 
+
+All optionals fields will be filled by default values, it this case:
+\code
+DS.drv  = RV({'ch0'},1,0);
+DS.time = 0;
+DS.rowid = [1];
+\endcode
+Where the first line specifies a universal identification structure: random variable (bdm::RV).
 
 \section rvs What is RV and how to use it
@@ -84 +108 @@
 RV stands for \c random \c variable which is a description of random variable or its realization. This object playes role of identifier of elements of vectors of data (in datasources), expected inputs to functions (in pdfs), or required results (operations conditioning). 
 
-\note <b>Mixtools reference </b> RV is generalization of "structures" \c str in Mixtools. It replaces channel numbers by string names, and adds extra field size for each record.
-
-Mathematical interpretation of RV is straightforward. Consider pdf \f$ f(a)\f$, then \f$ a \f$ is the part represented by RV. Explicit naming of random variables may seem unnecessary for many operations with pdf, e.g. for generation of a uniform sample from <0,1> it is not necessary to specify any random variable. For this reason, RV are often optional information to specify. However, the considered algorithm \c estimator is build in a way that requires RV to be given.
-
-The \c estimator use-case expects to join the data source with an array of estimators, each of which declaring its input vector of data. The connection will be made automatically using the mechanism of datalinks (bdm::datalink).
-Readers familiar with Simulink environment may look at the RV as being unique identifiers of inputs and outputs of simulation blocks. The inputs are connected automatically with the outputs with matching RV. This view is however, very incomplete, RV are much more powerful than this. 
+Mathematical interpretation of RV is straightforward. Consider pdf \f$ f(a)\f$, then \f$ a \f$ is the part represented by RV. Explicit naming of random variables may seem unnecessary for many operations with pdf, e.g. for generation of a uniform sample from <0,1> it is not necessary to specify any random variable. For this reason, RV are often optional information to specify. However, the considered scenanrio \c simulator is build in a way that requires RV to be given.
+
+The \c simulator scenario connects the DataSource to second basic class of BDM, bdm:logger. The logger is a class that take care of storing results -- in this case, results of simulation.
+The connection between these blocks is done automatically. The logger stores results of simulations under the names specified in drv.  
+Readers familiar with Simulink environment may look at the RV as being unique identifiers of inputs and outputs of simulation blocks. The inputs are connected automatically with the outputs with matching RV. This view is however, very incomplete, RV have more roles than this.
+
+\section loggers Loggers for flexible handling of results
+Loggers are universal objects for storing and manipulating the results of an experiment. Similar to DataSource, every logger has to provide basic functionality:
+ -# initialize its storage (bdm::logger.init()),
+ -# assign a connection point to each interested object (bdm::logger.logadd()),
+ -# accept data to be logged to given connection (bdm::logger.logit()),
+ -# finalize the storage when experiment is finished.
+
+These abstarct operations can be specialized in many ways. For example, storing all results in memory and writing them to disc when finished (bdm::memlog), storing data in a matlab structure (bdm::mexlog), writing them out in ascii (bdm::stdlog) or more sophisticated buffered output to harddrive (bdm::dirfilelog).
+
+Since all experiments are performed in matlab, the default mexlog class will be used. However, the way how the results are to be stored can be configured using configuration structure filled by fields from \c from_setting of the chosen logger, and passing it as third argument to \c simulator.
 
 \section datasource Class inheritance and DataSources
 
-As mentioned above, the algorithm \c estimator is written to accept any datasource (i.e. any offspring of bdm::DS). For full list of offsprings, click Classes > Class Hierarchy.
+As mentioned above, the scenario \c simulator is written to accept any datasource (i.e. any offspring of bdm::DS). For full list of offsprings, click see Classes > Class Hierarchy.
 
 At the time of writing this tutorial, available datasources are
@@ -111 +145 @@
 Brief decription of the class states that EpdfDS "Simulate data from a static pdf (epdf)". The static pdf means unconditional pdf in the sense that the random variable is conditioned by numerical values only. In mathematical notation it could be both \f$ f(a) \f$ and \f$ f(x_t |d_1 \ldots d_t)\f$. The latter case is true only when all \f$ d \f$ denotes observed values.
 
-For example, we wish to simulate realizations of a Uniform density on interval <-1,1>. Uniform density is represented by class bdm::euni.
-From bdm::euni.from_setting() we can find that the code is:
-\code 
-U={class="euni"; high=1.0; low = -1.0;}
-\endcode
-for configuration file, and 
+For example, we wish to simulate realizations of a Uniform pdf on interval <-1,1>. 
+This is achieved by plugging an object representing uniform pdf into general simulator of independent random samples, EpdfDS. Uniform density is implemented as class bdm::euni.
+An instance of \c euni can be again created method \c from_setting, in this case bdm::euni.from_setting(). Using documentation we define it with the following code:
 \code
 U.class='euni';
+U.rv   = RV({'a'});
 U.high = 1.0;
 U.low  = -1.0;
-U.rv.class = 'RV';
-U.rv.names = {'a'};
-\endcode
-for Matlab.
+\endcode
+which encodes information:\f[
+f(a) = \mathcal{U}(-1,1)
+\f]
   
-The datasource itself, can be then configured via
-\code
-DS = {class='EpdfDS'; epdf=@U;};
-\endcode
-in config file, or 
+The datasource itself, i.e. the instanc of \c EpdfDS can be then configured via:
 \code
 DS.class = 'EpdfDS';
 DS.epdf  = U;
 \endcode
-in Matlab.
-
-Contrary to the previous example, we need to tell to algorithm \c estimator how many samples from the data source we need. This is configured by variable \c experiment.ndat. The configuration has to be finalized by:
+where \c U is the structure defined above.
+
+Contrary to the previous example, we need to tell to algorithm \c simulator how many samples from the data source we need. This is configured by variable \c experiment.ndat. The configuration has to be finalized by:
 \code 
 experiment.ndat = 10;
-M=estimator(DS,{},experiment);
+M=simulator(DS,experiment);
 \endcode
 
@@ -151 +179 @@
 Consider the following autoregressive model: 
 \f[
-y_t \sim \mathcal{N}( a y_{t-3} + b u_{t-1}, r)
+f(y_t|y_{t-3},u_{t-1}) = \mathcal{N}( a y_{t-3} + b u_{t-1}, r)
 \f]
 where \f$ a,b \f$ are known constants, and \f$ r \f$ is known variance.
@@ -160 +188 @@
  -# time delayes of the values.
 
-The first issue can be handled in two ways. First, \f$ u \f$ can be considered as input and as such it could be externally given to the datasource. This solution is used in algorithm use-case \c closedloop.
-However, for the \c estimator scenario we will apply the second option, that is we complement \f$ f(y_{t}|y_{t-3},u_{t-1})\f$ by extra pdf:\f[
-u_t \sim \mathcal{N}(0, r_u)
-\f]
+The first issue can be handled in two ways. First, \f$ u \f$ can be considered as input and as such it could be externally given to the datasource. This solution is used in scenario \c closedloop.
+However, for the \c simulator scenario we will apply the second option, that is we complement \f$ f(y_{t}|y_{t-3},u_{t-1})\f$ by extra pdf:\f[
+f(u_t) = \mathcal{N}(0, r_u)
+\f]
+where \f$ r_u \f$ is another known constant.
 Thus, the joint density is now:\f[
 f(y_{t},u_{t}|y_{t-3},u_{t-1}) = f(y_{t}|y_{t-3},u_{t-1})f(u_{t})
@@ -205 +234 @@
 \subsection ini Initializing simulation
 
-When zeros are not appropriate initial conditions, the correct conditions can be set using additional commands:
+When zeros are not appropriate initial conditions, the correct conditions can be set using additional commands (see bdm::MpdfDS.from_setting() ):
 \code
 DS.init_rv = RV({'y','y','y'}, [1,1,1], [-1,-2,-3]);
@@ -214 +243 @@
 Initial data is not checked for completeness, i.e. values of random variables missing from \c init_rv (in this case all occurences of \f$ u \f$) are still initialized to 0.
 
-\section conc What was demonstrated in this tutorial
-The purpose of this page was to introduce software image of basic elements of decision making as implemented in BDM.
-
- - random values as identification mechanism (bdm::RV)
- - unconditional pdfs (bdm::epdf),
- - conditional pdfs (bdm::mpdf),
- 
-And the use of these in simulation of data and function of datasources. In the next tutorial, Bayesian models (bdm::BM) and loggers (bdm::logger) will be introduced.
-
-
-
 
 */