root/applications/bdmtoolbox/doc/local/02userguide_sim.dox @ 1436

Revision 1054, 12.6 kB (checked in by smidl, 14 years ago)

doc

Line 
1/*!
2\page userguide_sim BDM Use - System, Data, Simulation
3
4This section serves as introduction to the scenario of data simulation. Since it is the simplest of all scenarios 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\ref ug_sim_config
10\ref ug_sim
11\ref ug_memds
12\ref ug_rvs
13\ref ug_rv_connect
14\ref ug_pdfds
15\ref ug_arx_sim
16\ref ug_ini
17\ref ug_store
18
19
20\section ug_sim_config Configuration of an experiment
21
22Configuration 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.
23
24Specific 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).
25
26Advanced users can find more information in (\ref ui).
27
28\subsection ug_first First experiment
29
30The first experiment that can be performed is:
31\code
32DS.class='MemDS';
33DS.Data =[1 2 3 4 5 6];
34\endcode
35which can be found in file bdmtoolbox/tutorials/userguide/memds_example.m.
36
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.
39
40The expected result for Matlab is:
41\code
42>> M=simulator(DS)
43
44M =
45
46    ch0: [6x1 double]
47\endcode
48
49All that the simulator did was actually copying \c DS.Data to \c M.ch0. Explanation of the experiment and the logic used there follows.
50
51\section ug_sim Systems and DataSources
52
53In standard system theory, the system is typically illustrated graphically as:
54\dot
55digraph sys{
56        node [shape=box];
57        {"System"}
58        node [shape=plaintext]
59        {rank="same"; "u"; "System"; "y"}
60        "u" -> "System" -> "y" [nodesep=2];
61}
62\enddot
63Where \c u typically denotes input and \c y denotes output of the system. A causal dependence between input and output is typically presumed.
64
65We are predominantly concerned with discrete-time systems, hence, we will add indices \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$.
66
67One 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.
68
69DataSource is an object that is essentially able to:
70 -# return data observed at time \f$ t \f$,
71 -# perform one a time step.
72 -# describe what these data are, via class RV, introduced in ref \ref ug_pdf_marg,
73 -# store log of its activity into dedicated logger.
74
75No further specification, e.g. if the data are pre-recorded or computed on-the-fly, are given.
76For a list of available DataSources, see <a href="annotated_bdm_DS.html"> list </a>.
77
78
79\section ug_memds DataSource of pre-recorded data -- MemDS
80
81The first experiment run in \ref ug_first was actually an instance of DataSource of pre-recorded data that were stored in memory, i.e. the bdm::MemDS class.
82
83Operation of such object is trivial, the data are stored as a matrix and the general operations defined above are specialized as follows:
84 -# data observed at time \f$ t \f$  are columns of the matrix, getdata() returns current column,
85 -# time step itself is performed by increasing the column index,
86 -# each row is named as "ch0","ch1",...
87
88This is the default behavior. It can be customized using the UI mechanism. Full list of options is:
89\code
90DS.class = 'MemDS';
91DS.Data = (...);            // Data matrix or data vector
92        --- optional ---
93DS.drv = RV({"ch0",...} ); // Identification how rows of the matrix Data will be known to others
94DS.time = 0;               // Index of the first column to user_info,
95\endcode
96The compulsory fields are listed at the beginning; the optional fields are separated by string "--- optional ---".
97
98Fields \c time denotes the first record to start counting from. Field \c drv is a the one that specifies identification of the data elements, (point 3. of the general requirements of a DataSource).
99
100All optionals fields will be filled by default values, it this case:
101\code
102DS.drv  = RV({'ch0'},1,0);
103DS.time = 0;
104\endcode
105Where the first line specifies a universal identification structure: random variable (bdm::RV).
106
107\section ug_rvs What is RV and how to use it
108
109RV stands for \c random \c variable which is a description of random variable or its realization. However, this object serves as general descriptor of fields in vectors of data.
110
111It is used for:
112 - description of RV in pdfs, ways how to define marginalization and conditioning,
113 - connection between source of data and computational objects that use them,
114 - connection <b>time</b>, more exactly time shift from \f$ t \f$, defaults to 0.
115
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:
117\code
118DS.class='MemDS';
119DS.Data =[1 2 3 4 5 6];
120DS.drv = RV('y');
121\endcode
122Data from this data source will be available when estimators ask for rv 'y'.
123
124\subsection ug_rv_connect Storing results
125
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.
128The \c mexlog is the default option in bdmtoolbox.
129
130Connection between computational blocks and loggers is controlled by structure called \c log_level which governs the level of details to be logged.
131A standard Data source has two levels, \c logdt and \c logut which means "log all outputs, dt" and "log all inputs, ut".
132Readers 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.
133
134List is available <a href="annotated_bdm_logger.html"> loggers </a>.
135
136\section ug_pdfds How to create a simulator from pdfs
137For example, we would like to simulate a random Uniform distributed noise on interval <-1,1>.
138This is achieved by plugging an object representing uniform pdf into general simulator of independent random samples, pdfDS. Uniform density is implemented as class bdm::euni, which is created from the following structure:
139\code
140U.class='euni';
141U.rv   = RV({'a'});
142U.high = 1.0;
143U.low  = -1.0;
144\endcode
145which encodes information:\f[
146f(a) = \mathcal{U}(-1,1)
147\f]
148 
149The datasource itself, i.e. the instance of \c EpdfDS can be then configured via:
150\code
151DS.class = 'pdfDS';
152DS.pdf  = U;
153\endcode
154where \c U is the structure defined above.
155
156Contrary 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:
157\code
158experiment.ndat = 10;
159M=simulator(DS,experiment);
160\endcode
161
162The result is as expected in field \c M.DS_dt_a the name of which corresponds to results form "datasouce" / "output_dt" / "name given in U.rv".
163
164If the task was only to generate random realizations, this would indeed be a very clumsy way of doing it.
165However, the power of the proposed approach will be revealed in more demanding examples, one of which follows next.
166
167By 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'.
168
169\section ug_arx_sim Simulating autoregressive model
170
171Consider the following autoregressive model:
172\f[
173f(y_t|y_{t-3},u_{t-1}) = \mathcal{N}( a y_{t-3} + b u_{t-1}, r)
174\f]
175where \f$ a,b \f$ are known constants, and \f$ r \f$ is known variance.
176
177We need to handle two issues:
178 -# extra unsimulated variable \f$ u \f$,
179 -# time delays of the values.
180
181The 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.
182However, 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[
183f(u_t) = \mathcal{N}(0, r_u)
184\f]
185where \f$ r_u \f$ is another known constant.
186Thus, the joint density is now:\f[
187f(y_{t},u_{t}|y_{t-3},u_{t-1}) = f(y_{t}|y_{t-3},u_{t-1})f(u_{t})
188\f]
189and we have no need for input since the datasource have all necessary information inside. All that is required is to store them and copy their values to appropriate places.
190
191That is done in automatic way (via bdm::datalink_buffered). The only issue a user may need to take care about is the missing initial conditions for simulation.
192By default these are set to zeros. Using the default values, the full configuration of this system is:
193\code
194y = RV({'y'});
195u = RV({'u'});
196
197fy.class = 'mlnorm\<ldmat\>';
198fy.rv    = y;
199fy.rvc   = RV({'y','u'}, [1 1], [-3, -1]);
200fy.A     = [0.5, -0.9];
201fy.const = 0;
202fy.R     = 0.1;
203
204
205fu.class = 'enorm\<ldmat\>';
206fu.rv    = u;
207fu.mu    = 0;
208fu.R     = 0.2;
209
210DS.class = 'pdfDS';
211DS.pdf.class  = 'mprod';
212DS.pdf.pdfs  = {fy, fu};
213\endcode
214
215Explanation of this example will require few remarks:
216 - 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.
217 - 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.
218 - 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.
219 - class 'mprod' represents the chain rule of probability, see \ref ug_pdf_cond.
220 
221The code above can be immediately run, using the same execution sequence of \c estimator as above.
222
223\subsection ug_ini Initializing simulation
224
225When zeros are not appropriate initial conditions, the correct conditions can be set using additional commands:
226\code
227DS.init_rv = RV({'y','y','y'}, [1,1,1], [-1,-2,-3]);
228DS.init_values = [0.1, 0.2, 0.3];
229\endcode
230
231The values of \c init_values will be copied to places in history identified by corresponding values of \c init_rv.
232Initial 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.
233
234\section ug_store Storing results of simulation
235
236If the simulated data are to be analyzed off-line it may be advantageous to store them and use later on.
237This operation is straightforward if the class of logger used in the \c simulator is compatible with some datasource class.
238
239For 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.
240
241In Matlab, the output of mexlog is a structure of vectors or matrices. The results can be saved in a Matlab file using:
242\code
243Data=[M.y; M.u];
244drv = RVjoin({y,u});
245save pdfds_results Data drv
246\endcode
247Such data can be later provided e.g. by MemDS
248\code
249mxDS.class   = 'MemDS';
250mxDS.Data    = 'Data';
251mxDS.drv     = drv;
252\endcode
253
254List of all <a href="annotated_bdm_DS.html"> DataSources </a> and <a href="annotated_bdm_logger.html">loggers </a>.
255*/
Note: See TracBrowser for help on using the browser.