Changeset 948 for library/doc/tutorial

Show
Ignore:
Timestamp:
05/18/10 16:54:25 (15 years ago)
Author:
smidl
Message:

doc

Location:
library/doc/tutorial
Files:
5 modified

Legend:

Unmodified
Added
Removed

  • library/doc/tutorial/000install.dox

    r944 r948  
    1515\li svn checkout http://mys.utia.cas.cz:1800/svn/mixpp/applications/bdmtoolbox/ into your local directory of your choice (this will be denoted \<toolbox_dir\>) 
    1616\li or download a prepared zip file from http://staff.utia.cas.cz/smidl/Public/bdmtoolbox_win32.zip and extract it to any directory (will be denoted \<toolbox_dir\>) 
    17 \li open matlab and type:  
     17\li open matlab and type: 
    1818\code  
    1919>> addpath <toolbox_dir>/mex;  
    … …  
    2121>> addpath <toolbox_dir>/mex_classes 
    2222\endcode 
     23for downloaded win32 version of the toolbox. When compiling from sources, the mex files may be located in Debug of Release directories. Check where  
     24        the latest compiled files are and add apropriate path. E.g. for Windown and Mac: 
     25\code  
     26>> addpath <toolbox_dir>/mex;  
     27>> addpath <toolbox_dir>/mex/Debug;  
     28>> addpath <toolbox_dir>/mex_classes 
     29\endcode 
     30For linux, the default build dir is \<toolbox_dir\>/mex, hence only me and mex_classes need to be in the path. 
    2331\li the toolbox is ready to be used, test it e.g. by:  
    2432\code >> cd tutorial/userguide;  

  • library/doc/tutorial/007userguide_pdf.dox

    r944 r948  
    55 
    66The tutorial is written for the BDM toolbox, if you are interested in use of C++ classes see class reference pages. 
     7 
     8Table of content: 
     9 - \ref ug_pdf_create  
     10 - \ref ug_pdf_marg  
     11 - \ref ug_pdf_cond  
     12 - \ref ug_pdf_fnc  
     13 - \ref ug_pdf_mex  
    714 
    815\section ug_pdf_create Using built-in pdfs 
    … …  
    2027\li mu denotes mean value 
    2128\li R denotes variance (written in full matrix regardles of the used decomposition), 
     29\li parameters mu and R are vector and matrix, respectively. They can be given directly (as in Nab.mu) or as a result of arbitrary matlab function, (as in Nab.R) 
    2230\li rv denotes names assigned to the variables. RV is more complicated structure, but here it is sufficient to use default values. 
    2331\li rv is an optional parameter, some operations do not need it, such as sampling or evaluation of moments 

  • library/doc/tutorial/01userguide_sim.dox

    r947 r948  
    22\page userguide_sim BDM Use - System, Data, Simulation 
    33 
    4 This section serves as introduction to the scenario of data simulation. Since it is the simpliest of all scenarios defined in \ref userguide0 it also serves as introduction to configuration of an experiment (see \ref ui) and basic decision making objects (bdm::RV and bdm::DS). 
    5  
    6 All experiments are demonstarted on mex file \c simulator, which is also available as a standalone application. 
     4This section serves as introduction to the scenario of data simulation. Since it is the simplest of all scenarios defined in \ref userguide0 it also serves as introduction to configuration of an experiment (see \ref ui) and basic decision making objects (bdm::RV and bdm::DS). 
     5 
     6All experiments are demonstrated on mex file \c simulator, which is also available as a standalone application. 
     7 
     8Table of contents: 
     9\section ug_sim_config  
     10\section ug_sim  
     11\section ug_memds  
     12\section ug_rvs  
     13\subsection ug_rv_connect  
     14\section ug_pdfds  
     15\section ug_arx_sim  
     16\subsection ug_ini  
     17\section ug_store  
    718 
    819 
    … …  
    1324Specific 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. This information is stored in Matlab structures (or objects, see section on Matlab extensions). 
    1425 
    15 Advacnded users can find more information in (\ref ui). 
     26Advanced users can find more information in (\ref ui). 
    1627 
    1728\subsection ug_first First experiment 
    … …  
    2435which can be found in file bdmtoolbox/tutorials/userguide/memds_example.m. 
    2536 
    26 The code above is the minimum necessary information to run scenario \c simulator in matlab.  
    27 To actually do so, make sure that matlab paths are correctly set, as described in \ref install. 
     37The code above is the minimum necessary information to run scenario \c simulator in Matlab.  
     38To actually do so, make sure that Matlab paths are correctly set, as described in \ref install. 
    2839 
    2940The expected result for Matlab is: 
    … …  
    6273 -# store log of its activity into dedicated logger. 
    6374 
    64 No fruther specification, e.g. if the data are pre-recorded or computed on-the-fly, are given. 
     75No further specification, e.g. if the data are pre-recorded or computed on-the-fly, are given. 
    6576For a list of available DataSources, see ... 
    6677 
    … …  
    7182 
    7283Operation of such object is trivial, the data are stored as a matrix and the general operations defined above are specialized as follows: 
    73  -# data observed at time \f$ t \f$  are columns of the matrix, getdata() ruturns current column, 
     84 -# data observed at time \f$ t \f$  are columns of the matrix, getdata() returns current column, 
    7485 -# time step itself is performed by increasing the column index, 
    7586 -# each row is named as "ch0","ch1",... 
    7687 
    77 This is the default bahavior. It can be customized using the UI mechanism. Full list of options is: 
     88This is the default behavior. It can be customized using the UI mechanism. Full list of options is: 
    7889\code 
    7990DS.class = 'MemDS'; 
    … …  
    99110 
    100111It is used for: 
    101  - desription of RV in pdfs, ways how to define marginalization and conditioning, 
     112 - description of RV in pdfs, ways how to define marginalization and conditioning, 
    102113 - connection between source of data and computational objects that use them, 
    103114 - connection <b>time</b>, more exactly time shift from \f$ t \f$, defaults to 0. 
    104115 
    105 For example, the estimators will request the data from the above mentioned data source by asking for rv 'ch0'. If a more meaninful names are available, the fields drv can be added to read: 
     116For example, the estimators will request the data from the above mentioned data source by asking for rv 'ch0'. If a more meaningful names are available, the fields drv can be added to read: 
    106117\code 
    107118DS.class='MemDS'; 
    … …  
    109120DS.drv = RV('y'); 
    110121\endcode 
    111 Data from thsi data source will be available when estimators ask for rv 'y'. 
     122Data from this data source will be available when estimators ask for rv 'y'. 
    112123 
    113124\subsection ug_rv_connect Storing results 
    114125 
    115 results of an experiment can be stored in many ways. This functionality was abstracted into a class called logger. Exact form of the stored resuls is chosen by choosing appropriate class. 
    116 For example, \c stdlog writes all output in the console, \c dirfilelog writes all data in the dirfilelog format for high-speed data processing, \c mexlog writes data into matlab structure.  
     126results of an experiment can be stored in many ways. This functionality was abstracted into a class called logger. Exact form of the stored results is chosen by choosing appropriate class. 
     127For example, \c stdlog writes all output in the console, \c dirfilelog writes all data in the dirfilelog format for high-speed data processing, \c mexlog writes data into Matlab structure.  
    117128The \c mexlog is the default option in bdmtoolbox. 
    118129 
    119 Connection between computational blocks and loggers is controlled by structure called \c log_level which governes the level of details to be logged. 
     130Connection between computational blocks and loggers is controlled by structure called \c log_level which governs the level of details to be logged. 
    120131A standard Data source has two levels, \c logdt and \c logut which means "log all outputs, dt" and "log all inputs, ut". 
    121132Readers 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. 
    … …  
    134145\f] 
    135146   
    136 The datasource itself, i.e. the instanc of \c EpdfDS can be then configured via: 
     147The datasource itself, i.e. the instance of \c EpdfDS can be then configured via: 
    137148\code 
    138149DS.class = 'pdfDS'; 
    … …  
    150161 
    151162If the task was only to generate random realizations, this would indeed be a very clumsy way of doing it.  
    152 However, the power of the proposed approach will be revelead in more demanding examples, one of which follows next. 
     163However, the power of the proposed approach will be revealed in more demanding examples, one of which follows next. 
    153164 
    154165By default, data from this datasouce will be named after the rvs in given by the pdfs. When pdf with no rv is used, drv of the data source is set again to 'ch0'. 
    … …  
    164175We need to handle two issues: 
    165176 -# extra unsimulated variable \f$ u \f$, 
    166  -# time delayes of the values. 
     177 -# time delays of the values. 
    167178 
    168179The 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. 
    … …  
    202213Explanation of this example will require few remarks: 
    203214 - class of the \c fy object is 'mlnorm\<ldmat\>' which is Normal pdf with mean value given by linear function, and covariance matrix stored in LD decomposition, see bdm::mlnorm for details. 
    204  - naming convention 'mlnorm\<ldmat\>' relates to the concept of templates in C++. For those unfamiliar with this concept, it is basicaly a way how to share code for different flavours of the same object. Note that mlnorm exist in three versions: mlnorm\<ldmat\>, mlnorm<chmat>, mlnorm<fsqmat>. Those classes act identically the only difference is that the internal data are stored either in LD decomposition, choleski decomposition or full matrices, respectively.  
     215 - naming convention 'mlnorm\<ldmat\>' relates to the concept of templates in C++. For those unfamiliar with this concept, it is basically a way how to share code for different flavors of the same object. Note that mlnorm exist in three versions: mlnorm\<ldmat\>, mlnorm<chmat>, mlnorm<fsqmat>. Those classes act identically the only difference is that the internal data are stored either in LD decomposition, choleski decomposition or full matrices, respectively.  
    205216 - the same concept is used for enorm, where enorm<chmat> and enorm<fsqmat> are also possible. In this particular use, these objects are equivalent. In specific situation, e.g. Kalman filter implemented on Choleski decomposition (bdm::KalmanCh), only enorm<chmat> is approprate. 
    206217 - class 'mprod' represents the chain rule of probability, see \ref ug_pdf_cond. 
    207218  
    208 The code above can be immediatelly run, usin the same execution sequence of \c estimator as above.  
     219The code above can be immediately run, using the same execution sequence of \c estimator as above.  
    209220 
    210221\subsection ug_ini Initializing simulation 
    … …  
    217228 
    218229The values of \c init_values will be copied to places in history identified by corresponding values of \c init_rv. 
    219 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. 
     230Initial data is not checked for completeness, i.e. values of random variables missing from \c init_rv (in this case all occurrences of \f$ u \f$) are still initialized to 0. 
    220231 
    221232\section ug_store Storing results of simulation 
    … …  
    226237For example, the output of \c MemDS can be stored as an .it file (filename is specified in configuration structure) which can be later read by bdm::ITppFileDS. 
    227238 
    228 In matlab, the output of mexlog is a structure of vectors or matrices. The results can be saved in a matlab file using: 
     239In Matlab, the output of mexlog is a structure of vectors or matrices. The results can be saved in a Matlab file using: 
    229240\code 
    230241Data=[M.y; M.u]; 

  • library/doc/tutorial/02userguide_estim.dox

    r944 r948  
    22\page userguide_estim BDM Use - Estimation and Bayes Rule 
    33 
    4 Baysian theory is predominantly used in system identification, or estimation problems.  
    5 This section is concerned with recursive estimation, as implemneted in prepared scenario \c estimator. 
     4Bayesian theory is predominantly used in system identification, or estimation problems.  
     5This section is concerned with recursive estimation, as implemented in prepared scenario \c estimator. 
     6 
     7Table of contents: 
     8\ref ug2_theory  
     9\ref ug2_arx_basic  
     10\ref ug2_model_sel  
     11\ref ug2_bm_composition  
     12\ref ug_est_ext  
    613 
    714The function of the \c estimator is graphically illustrated: 
    … …  
    3138 - <b> Bayes rule </b> as defined above, operation bdm::BM::bayes() which expects to get the current data record \c dt, \f$ d_t \f$ 
    3239 - <b> evidence </b> i.e. numerical value of \f$ f(d_t|d_1\ldots d_{t-1})\f$ as a typical side-product, since it is required in denominator of the above formula. 
    33    For some models, computation of this value may require extra effort, and can be swithed off. 
     40   For some models, computation of this value may require extra effort, and can be switched off. 
    3441 - <b> prediction </b> the object has enough information to create the one-step ahead predictor, i.e. \f[ f(d_{t+1}| d_1 \ldots d_{t}), \f]  
    3542         
    3643Implementation of these operations is heavily dependent on the specific class of prior pdf, or its approximations. We can identify only a few principal approaches to this problem. For example, analytical estimation which is possible within sufficient the Exponential Family, or estimation when both prior and posterior are approximated by empirical densities.  
    37 These approaches are first level of descendants of class \c BM, classes bdm::BMEF and bdm::PF, repectively. 
     44These approaches are first level of descendants of class \c BM, classes bdm::BMEF and bdm::PF, respectively. 
    3845 
    3946\section ug2_arx_basic Estimation of ARX models 
    … …  
    5158This is the minimal configuration of an ARX estimator.  
    5259 
    53 The first three fileds are self explanatory, they identify which data are predicted (field \c rv) and which are in regressor (field \c rgr). 
     60The first three fields are self explanatory, they identify which data are predicted (field \c rv) and which are in regresor (field \c rgr). 
    5461The field \c log_level is a string of options passed to the object. In particular, class \c BM understand only options related to storing results: 
    5562 - logbounds - store also lower and upper bounds on estimates (obtained by calling BM::posterior().qbounds()), 
    … …  
    6673In Bayesian framework, model selection is done via comparison of evidence (marginal likelihood) of the recorded data. See [some theory]. 
    6774 
    68 A trivial exammple how this can be done is presented in file bdmtoolbox/tutorial/userguide/arx_selection_example.m. The code extends the basic A1 object as follows: 
     75A trivial example how this can be done is presented in file bdmtoolbox/tutorial/userguide/arx_selection_example.m. The code extends the basic A1 object as follows: 
    6976\code 
    7077A2=A1; 
    … …  
    7885 - A3 which is the same as A2, but assumes time-variant parameters with forgetting factor 0.95. 
    7986  
    80 Since all estimator were configured to store values of marginal log-likelihood, we can easily compare them by computint total log-likelihood for each of them and converting them to probabilities. Typically, the results should look like: 
     87Since all estimator were configured to store values of marginal log-likelihood, we can easily compare them by computing total log-likelihood for each of them and converting them to probabilities. Typically, the results should look like: 
    8188\code 
    8289Model_probabilities = 
    … …  
    100107\section ug2_bm_composition Composition of estimators 
    101108 
    102 Similarly to pdfs which could be composed via \c mprod, the Bayesian models can be composed togetrer. However, justification of this step is less clear than in the case of epdfs. 
     109Similarly to pdfs which could be composed via \c mprod, the Bayesian models can be composed together. However, justification of this step is less clear than in the case of epdfs. 
    103110 
    104111One possible theoretical base of composition is the Marginalized particle filter, which splits the prior and the posterior in two parts: 
    … …  
    166173\image latex frg_example.png "Typical run of tutorial/userguide/frg_example.m" width=\linewidth 
    167174 
    168 Note: error bars in this case are not directly comparable with those of previous examples. The MPF class implements the qbounds function as minimum and maximum of bounds in the condidered set (even if its weight is extreemly small). Hence, the bounds of the MPF are probably larger than it should be. Nevertheless, they provide great help when designing and tuning algorithms. 
     175Note: error bars in this case are not directly comparable with those of previous examples. The MPF class implements the qbounds function as minimum and maximum of bounds in the considered set (even if its weight is extremely small). Hence, the bounds of the MPF are probably larger than it should be. Nevertheless, they provide great help when designing and tuning algorithms. 
    169176 
    170177\section ug_est_ext Matlab extensions of the Bayesian estimators 
    … …  
    178185In order to create a new extension of an estimator, copy file with class mexLaplaceBM.m and redefine the methods therein. If needed create new classes for pdfs by inheriting from mexEpdf, it the same way as in the mexLaplace.m example class. 
    179186 
    180 Foro list of all estimators, see \ref app_base. 
     187For list of all estimators, see \ref app_base. 
    181188*/ 

  • library/doc/tutorial/030userguide3.dox

    r704 r948  
    11/*! 
    2 \page userguide3 BDM Use - Control and Design of Decision Making Strategy 
     2\page userguide_ctrl BDM Use - Control and Design of Decision Making Strategy 
    33 
    44Bayesian estimation as introduced in Section \ref userguide2 is a special case of Decision Strategy, see. .... 
    55A more demanding scenario is to design a control strategy that will influence the system operating under uncertainty, this is implemented as scenario \c closedloop. 
     6 
     7Table of content: 
     8\ref ug3_theory  
     9\ref ug3_arx_basic  
     10\ref ug3_arx_distributed  
    611 
    712The function of the \c closedloop is graphically illustrated: