| 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
|---|
| 2 | <html><head><meta http-equiv="Content-Type" content="text/html;charset=UTF-8"> |
|---|
| 3 | <title>mixpp: User Infos and their use</title> |
|---|
| 4 | <link href="tabs.css" rel="stylesheet" type="text/css"> |
|---|
| 5 | <link href="doxygen.css" rel="stylesheet" type="text/css"> |
|---|
| 6 | </head><body> |
|---|
| 7 | <!-- Generated by Doxygen 1.5.9 --> |
|---|
| 8 | <script type="text/javascript"> |
|---|
| 9 | <!-- |
|---|
| 10 | function changeDisplayState (e){ |
|---|
| 11 | var num=this.id.replace(/[^[0-9]/g,''); |
|---|
| 12 | var button=this.firstChild; |
|---|
| 13 | var sectionDiv=document.getElementById('dynsection'+num); |
|---|
| 14 | if (sectionDiv.style.display=='none'||sectionDiv.style.display==''){ |
|---|
| 15 | sectionDiv.style.display='block'; |
|---|
| 16 | button.src='open.gif'; |
|---|
| 17 | }else{ |
|---|
| 18 | sectionDiv.style.display='none'; |
|---|
| 19 | button.src='closed.gif'; |
|---|
| 20 | } |
|---|
| 21 | } |
|---|
| 22 | function initDynSections(){ |
|---|
| 23 | var divs=document.getElementsByTagName('div'); |
|---|
| 24 | var sectionCounter=1; |
|---|
| 25 | for(var i=0;i<divs.length-1;i++){ |
|---|
| 26 | if(divs[i].className=='dynheader'&&divs[i+1].className=='dynsection'){ |
|---|
| 27 | var header=divs[i]; |
|---|
| 28 | var section=divs[i+1]; |
|---|
| 29 | var button=header.firstChild; |
|---|
| 30 | if (button!='IMG'){ |
|---|
| 31 | divs[i].insertBefore(document.createTextNode(' '),divs[i].firstChild); |
|---|
| 32 | button=document.createElement('img'); |
|---|
| 33 | divs[i].insertBefore(button,divs[i].firstChild); |
|---|
| 34 | } |
|---|
| 35 | header.style.cursor='pointer'; |
|---|
| 36 | header.onclick=changeDisplayState; |
|---|
| 37 | header.id='dynheader'+sectionCounter; |
|---|
| 38 | button.src='closed.gif'; |
|---|
| 39 | section.id='dynsection'+sectionCounter; |
|---|
| 40 | section.style.display='none'; |
|---|
| 41 | section.style.marginLeft='14px'; |
|---|
| 42 | sectionCounter++; |
|---|
| 43 | } |
|---|
| 44 | } |
|---|
| 45 | } |
|---|
| 46 | window.onload = initDynSections; |
|---|
| 47 | --> |
|---|
| 48 | </script> |
|---|
| 49 | <div class="navigation" id="top"> |
|---|
| 50 | <div class="tabs"> |
|---|
| 51 | <ul> |
|---|
| 52 | <li><a href="main.html"><span>Main Page</span></a></li> |
|---|
| 53 | <li class="current"><a href="pages.html"><span>Related Pages</span></a></li> |
|---|
| 54 | <li><a href="annotated.html"><span>Classes</span></a></li> |
|---|
| 55 | <li><a href="files.html"><span>Files</span></a></li> |
|---|
| 56 | </ul> |
|---|
| 57 | </div> |
|---|
| 58 | <div class="navpath"><a class="el" href="dev_guide.html">BDM Use - in C++</a> |
|---|
| 59 | </div> |
|---|
| 60 | </div> |
|---|
| 61 | <div class="contents"> |
|---|
| 62 | <h1><a class="anchor" name="ui_page">User Infos and their use </a></h1><dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="classbdm_1_1UI.html" title="UI is an abstract class which collects all the auxiliary functions useful to prepare...">bdm::UI</a><p> |
|---|
| 63 | <a class="el" href="user__info_8h.html#4f9de2f17e844047726487b99def99c6" title="Macro for registration of class into map of user-infos, registered class is scriptable...">UIREGISTER</a><p> |
|---|
| 64 | <a class="el" href="classbdm_1_1UIFile.html" title="This class serves to load and/or save user-infos into/from configuration files stored...">bdm::UIFile</a><p> |
|---|
| 65 | <a href="http://www.hyperrealm.com/libconfig/">The web page of the libconfig library.</a></dd></dl> |
|---|
| 66 | <h2><a class="anchor" name="ui_intro"> |
|---|
| 67 | Introduction</a></h2> |
|---|
| 68 | For easier interaction with users, experiments can be configured via structures called <b>User Info</b>. These structures contain information about details of the experiment that is to be performed. Since experiments involve the use of basic BDM classes and their compositions, the experiment description is also hierarchical with specific user info for each object or class.<p> |
|---|
| 69 | The User Infos are designed using customized version of the libconfig library (www.hyperrealm.com/libconfig). It is specialized for BDM so as to recognize basic mathematical objects, such as vectors and matrices, see details below.<p> |
|---|
| 70 | Technically it can be made compatible with matlab structures. <dl class="todo" compact><dt><b><a class="el" href="todo.html#_todo000008">Todo:</a></b></dt><dd>it will be good to create a more detailed paragraph about the intraction with Matlab</dd></dl> |
|---|
| 71 | <h2><a class="anchor" name="ui_example"> |
|---|
| 72 | Example</a></h2> |
|---|
| 73 | For example, a simple experiment can be configures in the following way: <div class="fragment"><pre class="fragment">ndat = 100; <span class="comment">//number of data points</span> |
|---|
| 74 | prior = { <span class="keyword">class</span>=<span class="stringliteral">"enorm"</span>; |
|---|
| 75 | mu = [1, 2, 3]; |
|---|
| 76 | R = [1, 0, 0, |
|---|
| 77 | 0, 1, 0, |
|---|
| 78 | 0, 0, 1]; |
|---|
| 79 | }; |
|---|
| 80 | </pre></div> The exact meaning of the root fields in this structure (i.e. <code>ndat</code> and <code>prior</code>) is defined by the application (or mex file) that is using this configuration file. It will look for expected fields and it will ignore any other structures. When it does not find what it is looking for, it terminates with an appropriate error message.<p> |
|---|
| 81 | A structure with field <code>class="identifier"</code> is special. Such a structure will be parsed by an appropriate <a class="el" href="classbdm_1_1UI.html#1f3d45184f803e1256cfc896b43ed2f8">bdm::UI::build</a> method which will construct the desired object, in this instance of an object of the class <a class="el" href="classbdm_1_1enorm.html" title="Gaussian density with positive definite (decomposed) covariance matrix.">bdm::enorm</a>.<p> |
|---|
| 82 | For a detailed example how this mechanism works in practice see <a class="el" href="arx_ui.html">Running experiment <code>estimator</code> with ARX data fields</a>. To learn about the possinility of making <b> internal or external links</b> in configuration files, see the documentation of <a class="el" href="classbdm_1_1SettingResolver.html" title="This class serves to expand links used within configuration files.">bdm::SettingResolver</a>.<h2><a class="anchor" name="ui_implementation"> |
|---|
| 83 | Implementation of user info in a custom class</a></h2> |
|---|
| 84 | In accordance with the previous example of the configuration file, consider the class defined as follows:<p> |
|---|
| 85 | <div class="fragment"><pre class="fragment"><span class="keyword">class </span>newbee : <span class="keyword">public</span> bdm::root { |
|---|
| 86 | ... |
|---|
| 87 | |
|---|
| 88 | <a class="code" href="classbdm_1_1enorm.html" title="Gaussian density with positive definite (decomposed) covariance matrix.">bdm::enorm</a> prior; |
|---|
| 89 | <span class="keywordtype">int</span> ndat; |
|---|
| 90 | |
|---|
| 91 | ... |
|---|
| 92 | } |
|---|
| 93 | </pre></div><p> |
|---|
| 94 | There are few obligatory steps to implement user info mechanism in this class. At first, the class has to be <b>inherited</b> (directly or indirectly) from <a class="el" href="classbdm_1_1root.html" title="Root class of BDM objects.">bdm::root</a>, as you can see in our example. What is hidden behind the scene is the use of a <b>parameterless constructor.</b> Each class using User infos has to have one.<p> |
|---|
| 95 | Next, <b>two virtual methods</b> <a class="el" href="classbdm_1_1root.html#0551e3121091c5199bf4413b50522176" title="This method arrange instance properties according the data stored in the Setting...">bdm::root::from_setting</a> and <a class="el" href="classbdm_1_1root.html#67d954d255ede776eade7334d4895790" title="This method save all the instance properties into the Setting structure.">bdm::root::to_setting</a> defined in the <a class="el" href="classbdm_1_1root.html" title="Root class of BDM objects.">bdm::root</a> class <b>should be overriden </b> in accordance with the content of the current class. In fact, you can override just method <a class="el" href="classbdm_1_1root.html#0551e3121091c5199bf4413b50522176" title="This method arrange instance properties according the data stored in the Setting...">bdm::root::from_setting</a> in the case you are interested only in loading from configuration files, which is quite common. It is valid also in the other way round, i.e., in the case you are interested just in saving, override only <a class="el" href="classbdm_1_1root.html#67d954d255ede776eade7334d4895790" title="This method save all the instance properties into the Setting structure.">bdm::root::to_setting</a>.<p> |
|---|
| 96 | How should look the bodies of these methods? It is important not to forget to call their <b>implementation in the base class</b> (in our case, it is the <a class="el" href="classbdm_1_1root.html" title="Root class of BDM objects.">bdm::root</a> class). Then, they should contain loading of all the necessary class attributes in the case of <a class="el" href="classbdm_1_1root.html#0551e3121091c5199bf4413b50522176" title="This method arrange instance properties according the data stored in the Setting...">bdm::root::from_setting</a> method and saving of them in the other case. To implement these operation, you are encouraged to use static methods of <a class="el" href="classbdm_1_1UI.html" title="UI is an abstract class which collects all the auxiliary functions useful to prepare...">bdm::UI</a> class, namely <a class="el" href="classbdm_1_1UI.html#cd1667e6fec99ec64dabcb3ca2ff922d">bdm::UI::get</a>, <a class="el" href="classbdm_1_1UI.html#1f3d45184f803e1256cfc896b43ed2f8">bdm::UI::build</a> and <a class="el" href="classbdm_1_1UI.html#c83987949e6a9e79d6e093797ab7d917" title="A root descendant instance is stored in the new child Setting appended to the passed...">bdm::UI::save</a>.<p> |
|---|
| 97 | It can look like this:<p> |
|---|
| 98 | <div class="fragment"><pre class="fragment"><span class="keyword">class </span>newbee : <span class="keyword">public</span> bdm::root { |
|---|
| 99 | ... |
|---|
| 100 | |
|---|
| 101 | <a class="code" href="classbdm_1_1enorm.html" title="Gaussian density with positive definite (decomposed) covariance matrix.">bdm::enorm</a> prior; |
|---|
| 102 | <span class="keywordtype">int</span> ndat; |
|---|
| 103 | |
|---|
| 104 | ... |
|---|
| 105 | |
|---|
| 106 | <span class="keyword">virtual</span> <span class="keywordtype">void</span> from_setting(<span class="keyword">const</span> Setting &<span class="keyword">set</span>) { |
|---|
| 107 | root::from_setting(<span class="keyword">set</span>); |
|---|
| 108 | <span class="keywordflow">if</span>( !UI::get( ndat, <span class="keyword">set</span>, <span class="stringliteral">"ndat"</span> ) ) |
|---|
| 109 | ndat = 1; |
|---|
| 110 | prior = UI::build<enorm>( <span class="keyword">set</span>, <span class="stringliteral">"prior"</span>, compulsory ); |
|---|
| 111 | } |
|---|
| 112 | |
|---|
| 113 | <span class="keyword">virtual</span> <span class="keywordtype">void</span> to_setting(Setting &<span class="keyword">set</span>)<span class="keyword"> const </span>{ |
|---|
| 114 | root::to_setting(<span class="keyword">set</span>); |
|---|
| 115 | UI::save(ndat, <span class="keyword">set</span>, <span class="stringliteral">"ndat"</span>); |
|---|
| 116 | UI::save(prior, <span class="keyword">set</span>, <span class="stringliteral">"prior"</span>); |
|---|
| 117 | } |
|---|
| 118 | |
|---|
| 119 | ... |
|---|
| 120 | } |
|---|
| 121 | </pre></div><p> |
|---|
| 122 | As you can see, the presence of a concrete Setting in the configuration file can be tested by the return value of these methods and the code initializing the default values can follow immediately. Imagine, for example, that the first attribute <code>ndat</code> is optional. Thereore, the default value is filled in the case that there is not any other in the configuration file (and so <a class="el" href="classbdm_1_1UI.html#cd1667e6fec99ec64dabcb3ca2ff922d">bdm::UI::get</a> method returs <code>false</code>). The second atribute, <code>prior</code>, is intended to be compulsory. This fact is specified by the last parameter of the templated <a class="el" href="classbdm_1_1UI.html#1f3d45184f803e1256cfc896b43ed2f8">bdm::UI::build</a> method. In this case, the method throws an exception if there is not proper data in the configuration file.<p> |
|---|
| 123 | The only difference between <a class="el" href="classbdm_1_1UI.html#1f3d45184f803e1256cfc896b43ed2f8">bdm::UI::build</a> and <a class="el" href="classbdm_1_1UI.html#cd1667e6fec99ec64dabcb3ca2ff922d">bdm::UI::get</a> method is in the types of variables they are prepared to. The <a class="el" href="classbdm_1_1UI.html#1f3d45184f803e1256cfc896b43ed2f8">bdm::UI::build<T></a> method is used to initialize instances of classes derived from <a class="el" href="classbdm_1_1root.html" title="Root class of BDM objects.">bdm::root</a>. It allocates them dynamically and return just an pointer to the new instance. This way it is possible even to load instances of inherited classes without aneven knowing about it. Oppositely, all scalar values of types int, double, string, vec, ivec or mat are loaded by the <a class="el" href="classbdm_1_1UI.html#cd1667e6fec99ec64dabcb3ca2ff922d">bdm::UI::get</a> method with a static memory management. It is also capable to load arrays of templated type itpp::Array<T>.<p> |
|---|
| 124 | Saving is much more easier. For all the variable types, use the <a class="el" href="classbdm_1_1UI.html#c83987949e6a9e79d6e093797ab7d917" title="A root descendant instance is stored in the new child Setting appended to the passed...">bdm::UI::save</a> method. </div> |
|---|
| 125 | <hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 7 17:34:45 2009 for mixpp by |
|---|
| 126 | <a href="http://www.doxygen.org/index.html"> |
|---|
| 127 | <img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.9 </small></address> |
|---|
| 128 | </body> |
|---|
| 129 | </html> |
|---|
