\chapter{Learning Guide}

The main scope behind NLMIMO is the integration of the software
produced by the partners taking part in the FAMIMO project (ESPRIT LTR
Project 21911) in a unique toolbox. In order to achieve this it has
been necessary to design an extremely flexible system that can
accommodate the needs of the different laboratories collaborating in the
project. For this reason the NLMIMO toolbox has been designed using an
object oriented approach, which allows modularity, flexibility and
ease of extension. This has been possible thanks to the new features
present in the Matlab\texttrademark 5.0 which allows the development of an object
oriented software.\\

The NLMIMO toolbox is built around three main classes. The {\tt
system} class, which defines all the attributes which characterize a
system, the {\tt dataset} class, which allows the storage and the
processing of all the data, and the {\tt mapping} class, which defines
the the modeling of the process. As depicted in figure
\ref{fig:top_classes} the {\tt system} class is the main one of the
toolbox, and the other ones are used to describe some of the features
of the system. In this way the data and the parameterization of the
model are separate from the description of the system, and therefore
can be easily modified or updated without the need of altering the
structure of the {\tt system} class.  Each class has methods for
accessing, setting and displaying its attributes, and checking their
integrity and consistency.


\section{Building things}

Once the general philosophy and the structure of the NLMIMO toolbox
has been understood, it is time to put your hands on the keyboard and
use this toolbox for the definition and the analysis of dynamic or
static systems.\\

The nlmimo toolbox supports two alternative system representations:
internal, and external representation. The Matlab\texttrademark object oriented
approach provides an ideal way to describe the rich set of information
which characterize these representations.


We will start with the description of the external representation.
There are several different alternatives constructors which can be
used to build an external object. The common one is to define the
a new object using the following syntax:
\begin{verbatim}
   m=external('external object',2,3)
\end{verbatim}
this creates a new object belonging to the class external whose name
is ``external object'', with 2 inputs and 3 outputs. Matlab\texttrademark displays
the following information on the screen:
\begin{verbatim}
   m = 
   A external system with the following attributes
 
           name: 'external object'
           n_in: 2
          n_out: 3
       dynamics: []
           data: []
              T: -1
        mapping: {}
          links: []
         limits: [2x5 double]
       userData: []
            opt: []
           date: [1999 7 26 8 53 44.8545]

\end{verbatim}

It is possible to access the fields of the object using two different
approaches; using the ``{\tt .}'' (dot) operator (object\_name.field),
or using the {\tt get} method:
\begin{verbatim}
   get(object_name,'field')
\end{verbatim} 
The first approach is useful when analyzing objects at the Matlab\texttrademark
prompt, but is discouraged in programs since it is against the object
oriented programming paradigm used in the toolbox. If not differently
specified all the
fields of and object can be set using the {\tt set} method, which
allows to set the values of multiple attributes. This can be done in
the following way:
\begin{verbatim}
   set(object_name,'field', value)
   set(object_name,'field_1', value_1,'field_2',value_2,...)
\end{verbatim}

The {\tt name} field of an external object contains its name, and {\tt
n\_in} and {\tt n\_out} store the its number of inputs and outputs.\\
  
The {\tt dynamics} field provides the dynamics description of the system.
It is a structure including three subfields, {\tt nu}, {\tt ny} and
{\tt nd}, which define the regressors and
therefore the dynamical behaviour of the system. {\tt ny} is a $
n\_out \star n\_out$ square matrix which contains the
relationships of each output (each row) with all the other
outputs. Each entry $ij$ indicates the number of past values
associated to the output $j$ used in the regressor of the output
$i$. {\tt nu} is a $ n\_out \star n\_in$ matrix defining the
relationships between the outputs and each input. Each entry $ij$
indicates the number of past values associated to the input $j$ used
in the regressor of the output $i$. Finally {\tt nd} is a $ n\_out
\star n\_in$ matrix defining the delay of the inputs respect to the
outputs. Each entry $ij$ indicates the delay of the input $j$ used in
the regressor of the output $i$. For example the following dynamical
description of a 2 inputs 3 outputs system:
\begin{eqnarray*}
y_1(t) &=& F( y_1(t-1), y_1(t-2), y_2(t-1), u_1(t), u_1(t-1), u_1(t-2),
u_2(t))\\
y_2(t) &=& F( y_1(t-1), y_2(t-1), y_3(t-1), u_1(t), u_1(t-1),
u_2(t-2))\\
y_3(t) &=& F( y_1(t-1), y_2(t-1), y_2(t-2), y_3(t-1), u_2(t-2), u_2(t-3)
\end{eqnarray*}
is translated in the following set of matrices:
\begin{displaymath}
{\tt ny}=\left( \begin{array} {ccc} 
2 & 1 & 0 \\ 1 & 1 & 1 \\ 1 & 2 & 1 \end{array} \right)
end\hspace{1cm}
{\tt nu}=\left( \begin{array} {ccc}
3 & 1 \\ 2 & 1 \\ 0 & 2 \end{array} \right)
\hspace{1cm}
{\tt nd}=\left( \begin{array} {ccc}
0 & 0 \\ 0 & 2 \\ 0 & 2 \end{array} \right)
\end{displaymath}
The method {\tt add\_dynamics} allows to add the dynamical description
to the object. It is possible to use one of the two following
syntaxes:
\begin{verbatim}
   m=add_dynamics(m,dyn)
\end{verbatim}
which attaches to the object {\tt m} the dynamic
description of the system present in the structure {\tt dyn} which
must include the fields 'nu', 'ny' and 'nd', defining the appropriate
matrixes of the inputs, outputs and delays of the system;
\begin{verbatim}
   m=add_dynamics(m,ny,nu,nd)
\end{verbatim}
which attaches to the  the object {\tt m}  the dynamic
description of the system as defined in the arrays {\tt ny},
{\tt nu}, and {\tt nd}.\\

The {\tt data} field stores an object of type ``dataset'',
which contains all the input-output data of the system. Once the data
has been stored in a ``dataset'' object and  all the data
preprocessing has been done it is  possible to associate it to the
external system using the following syntax:
\begin{verbatim}
   m=add_data(m,data,t)
\end{verbatim}
which associates the  {\tt data} object to the field 'data' of the
model {\tt m}. The optional variable {\tt t} specifies the sampling 
time of the model (default continuous = 0).\\

{\tt T} represents the sampling time of the system; -1 indicates that
this quantity is undefined, 0 that the system is a continuous one, a
number greater than zero indicates the sampling time of the discrete
time system. This field can be defined using the {\tt set} method.\\

The field {\tt mapping} is a cell array which contains the
input-output mappings of the system. Each of the elements present in
this class belongs from a subclass of the ``mapping'' class. New
mappings can be added to this list using the following syntax:
\begin{verbatim}
   m=add_mapping(m,mapp)
\end{verbatim}
which appends the mapping defined in {\tt mapp} to the list of the
mappings of the object. The clear the list it is possible to use the 
function:
\begin{verbatim}
   m=add_mapping(m)
\end{verbatim}

Once the list of the mappings have been defined it is necessary to
associate each output to a mapping. This relation is stored in the 
{\tt links} field, which is an array of size $n\_out \star 2$. The
first column defines the number of the mapping, and the second one the
number of the output to which the mapping is associated. Of course
there could be mapping which are not associated to any output. This is
especially the case during the modeling stage when different models
are tested, and only some of them are active at each moment.\\

The {\tt limits} field stores the superior and inferior limits of the
input and outputs of the system. It is a array of size $2 \star (n\_in
+ n\_out)$. The top row stores the inferior limit and bottom one the
superior limits of the inputs and the outputs of the system. The default
values are {\tt -Inf +Inf} for all the inputs and the outputs.\\

The {\tt date} field reports the creation date the the system. The
{\tt opt} and {\tt userData} fields are used to store optional
information or used defined data, and can be useful especially during
the development of user defined functions.\\


Once a new external object has been created it is possible to start
to fill the different fields using the methods described in the
previous section. Usually the first fields to be defined are the 
{\tt dynamics} and {\tt data} fields. Then as soon as the mappings are
defined it is possible to add them to the list of the mapping of the
system using the {\tt add\_mapping} method. The method get allows to
retrieve all the mapping field stored in an external object, however
the following syntaxes allow to see the contents of each mapping
directly. For example: 
\begin{verbatim}
   m.mapping{1}
\end{verbatim}
or even more shortly:
\begin{verbatim}
   m{1}
\end{verbatim}
allow to see the contents of the first mapping of the mapping list
associated to the object {\tt m}.\\
 
Before gpomg on it is essential to
define the {\tt links} field in order to associate each output to a
mapping.

There are a series of method which have been defined for the
processing of the external objects. First of all there is the {\tt identify}
method. It most general syntax follows:
\begin{verbatim}
   m=identify(m,j,options)
\end{verbatim} 
which performs an identification of the output {\tt j} of the system
passing to the identification procedure the parameters contained in
the structure {\tt options}. This method is a wrapper since it calls
the identification procedure associated with the mapping connected
with the output {\tt j} passing to this one the {\tt option} structure
and the data contained in the {\tt data} field to perform the
identification procedure. The contents of {\tt option} must be
consistent with the identification procedure associated with the
particular mapping.\\ 

The quality of the result of the identification procedure can be
assessed with methods for calculating the mean square error, {\tt
error}, and the simulation error {\tt simulation\_error} of the model 
respect the to the reference set of  values given as output data or a
validation set given as input of the method.\\

Another method defined by the class is {\tt regress} which 
extracts the regressors from the data whose sintax follows:
\begin{verbatim}
  [r_in,r_out]=regress(m,j)
\end{verbatim}
This function uses the
dynamical system representation stored in the {\tt dynamics} field to
extract the regressors form the input-output data stored in the {\tt data}
field.  The function returns the input regressors {\tt r\_in} in a
cell array.  Each element of the cell array is a regressor associated
with an output.  Each regressor is an array of size $ size\_regressor
\star num_exaples$, where $ size\_regressor$ depends from the
structure of the regressor defined in the dynamical description of the
system, and $ num\_exaples$ is the number of examples given in
the input-output data set. {\tt r\_in} is a cell array returning
the correspondent output of each regressor taken from the output data
set. Each entry in the cell array is a vector of size $ 1 \star
num\_examples$.\\

The method {\tt eval} calculates the output for the output {\tt j} 
of a system given the regressor using the syntax:
\begin{verbatim}
out=eval(m,regressor,j)
\end{verbatim}
Other two method are used to calculate the derivatives of the system
respect to the inputs ({\tt jacob\_inputs}) and the parameters ({\tt
jacob\_parameters}). All these methods are wrappers since they call
the equivalent methods defined in the single mappings defined inside
the object.\\ 

The method {\tt simulate} performs a simulation of the 
model using the input data and feeding back the results
of the simulation to calculate at each step the regressors.\\

The class defines other methods for normalize a mapping in order to make fit
its limits to the interval [0,1] (if the {\tt limits} are finite),
denormalise it, and to check the consistency of all the fields defined in
an external object.


The internal class is quite similar to the external one, but it
defines some other fields and methods. When a new internal object is
created with the command
\begin{verbatim}
  m=inetrnal('internal object',1,2,3)
\end{verbatim}
this creates a new object belonging to the class internal whose name
is ``internal object'', with 1 input, 2 outputs and 3 internal
states. Matlab\texttrademark displays the following on the screen:
\begin{verbatim}
  m=
  A internal system with the following attributes
 
            name: 'internal object'
            n_in: 1
           n_out: 2
         n_state: 3
           state: [0 0 0]
            data: []
               T: -1
         mapping: {1x1 cell  }
           links: [2x2 double]
          limits: [2x3 double]
        userData: []
    statemapping: {1x1 cell  }
      statelinks: [3x2 double]
     statelimits: [2x3 double]
             opt: []
            date: [1999 7 26 13 51 6.6021]
\end{verbatim}
As it is possible to see the main difference between an internal and
an external object is the absence of the {\tt dynamic} field and the
presence of all a series of field associated with the internal
representation of the state of the system. The object is already
initialized with linear mappings for describing the evolution of the
internal state and its outputs. The field {\tt n\_states} defines the
number of the internal states of the system, and the field {\tt state}
their initial values. The fields {\tt statemapping}, {\tt statelinks}
and {\tt statelimits} are similar to the {\tt mapping}, {\tt links}
and {\tt limits} fields but they refer to the internal state of the system.
it is possible to add new mappings for the state using the {\tt 
add\_statemapping} method in a way identical to the {\tt add\_mapping}
method. Almost all the methods defined in the external class are
defined in the internal one as well. In addition  the following
methods are defined: {\tt eval\_state} for calculating the internal 
state of the system given a regressor, {\tt jacob\_cloop} for calculating the 
jacobian with respect to the state for a closed loop.

\section{The {\tt mapping} class and its subclasses}

The mapping class and its subclasses allows great power and
flexibility to the nlmimo toolbox. These classes allow the to 
define the modeling of a process using the approach which best suits
the data and the the ability of the programmer. Different approaches
can be used and the results of each mapping can be evaluated and
compared to choose the best possible system description. Now in turn a
description of all the mappings which have been defined so far in the
toolbox will be given.\\

Besides providing a common framework for every linear and non linear mappings
supported inside the {\tt system} class and its subclasses. The mapping architecture
supply the user with a complete set of stand alone classes. A dynamical model should always
be defined using the {\tt internal} or {\tt external} to take profit of the dynamical
representation facilities provided by these classes. A static model can be defined using
the {\tt external} class if integration with simulink, models combination or data set embedding
are whished features.
It can also be defined using one of the {\tt mapping} subclasses when such features are not
necessary which allow user to choose a smaller data structure while still having access to
the core functions of the toolbox.\\

In the following pages, we present how to use the mapping class in stand alone mode. Their use
while embedded inside a {\tt system} object is obvious if one keeps into mind that many {\tt system}
methods like {\tt eval}, {\tt identify}, ... are nothing more than wrapper/dispatcher which pass
their arguments to the called {\tt mapping} subclasses methods.\\

\subsection{The linear class} 

The linear mapping provides a simple linear relationship between
inputs and outputs. To create a new linear object it is possible to
use the following instruction:
\begin{verbatim}
   l=linear('linear object',2,3)
\end{verbatim}
which creates a new linear object called ``linear object'' with 2
inputs and 3 outputs. Matlab\texttrademark displays the following information on 
the screen:
\begin{verbatim}
l =
 
A linear object with the following attributes
 
           name: 'linear object'
           n_in: 2
          n_out: 3
         limits: [2x5 double]
       userData: []
            opt: []
           date: [1999 7 26 14 51 31.6432]
    optimparams: []
        linears: [3x3 double]
\end{verbatim}
the {\tt name} field stores the name of the object, {\tt n\_in} and
{\tt n\_out} the number of input and output of the mapping. It is
possible to notice that there is no definition of time in all the
mapping objects. This is beacuse the mapping objects are better
understood as input-output functions which receive a certain number of
inputs and return a defined number of outputs. The {\tt limits} field 
stores the limits of the inputs and the outputs of the mapping. 
It is a array of size $2 \star (n\_in
+ n_out)$. The top row stores the inferior limit and bottom one the
superior of the inputs and the outputs of the system. The default
values are {\tt -Inf +Inf} for all the inputs and the outputs. The
most important field is the {\tt linears} one which stores the linear
relationships between the input and the outputs of the system. The
{\tt date} field stores the creation time of the object. The {\tt
userData} and {\tt opt} field could be used by the user during the
developemnt of programs for storing information. The {\tt optimparams}
field is used to specify which subset of the parameters has to be optimised
when the {\tt identify} method is called. Similarly to the case of the
subclasses of the {\tt system} class, all the fields can be set using
the {\tt set} method, and retrived using the 'dot' or the {\tt get}
method.\\

The {\tt linear} class defines a series of methods for performing the
several actions on its objects.\\

The method {\tt identify} whose syntax follows:
\begin{verbatim}
m = identify(m,in,out)
\end{verbatim}
perform a least mean square fit of the input-output data contained in the
{\tt in} and {\tt out} arrays. The first one must have a size of
$num\_examples \star n\_in$ while the second one must be equal to 
$num\_examples \star n\_out$. The results of the least mean square
fit are stored in the {\tt linears} field.\\

The class provides a method for evaluating the mapping given an input,
{\tt eval}, method for normalising and denormalising the mapping ( if
the {\tt limits} are finite). The methods {\tt jacob\_inputs} and {\tt
jacob\_params}  are used to calculate the derivatives of the mapping
respect to the inputs and the parameters. The method {\tt check} is
provided  to check the consistency of all the fields defined in
an external object.

\subsection{The lazy class} 


The class lazy allows to describe dynamical systems using a 'lazy'
representation, which is a kind of k-nearest neigbour. It works in a
simple way. The input-output data is stored in a database. When a
prediction of the putput is needed a local model is fitted through the
closest points of the query contained in the database. In order to
create a new lazy object it is possible to use the following
instruction:
\begin{verbatim}
   l=lazy('lazy object',2,3)
\end{verbatim}
which creates a new lazy object called ``lazy object'' with 2
inputs and 3 outputs. Matlab\texttrademark displays the following information on 
the screen:
\begin{verbatim}
A lazy object with the following attributes
 
           name: 'lazy object'
           n_in: 2
          n_out: 3
         limits: [2x5 double]
       userData: []
            opt: []
           date: [1999 7 27 8 7 13.6540]
    optimparams: []
         id_par: []
        cmb_par: 1
     examples_x: []
     examples_y: []
\end{verbatim}
the {\tt name} field stores the name of the object, {\tt n\_in} and
{\tt n\_out} the number of inputs and outputs of the mapping. This class
as well has the {\tt limits}, {\tt userData}, {\tt opt}, {\tt
optimparams}, and {\tt date} fields which have the same meaning of the
ones defined in the {\tt linear} class. The fileds {\tt examples\_x}
and {\tt examples\_y}, contain the full input-output database, which
is used by the algorithm to perform the local fitting when needed.
The elements which describe how the lazy model will be built  
are defined in the {\tt id\_par} and {\tt cmb\_par} fields.\\

When the {\tt identify} method is called:
\begin{verbatim}
m = identify(m,in_data,out_data,options)
\end{verbatim}
no real identification is performed, since the models are built on
query-by-query basis, but the {\tt examples\_x} field is inizialized
with the data contained in {\tt in\_data} and the {\tt examples\_y}
field with the one contained in the {\tt out\_data}. The dimension of
{\tt in\_data} must be $num\_examples \star n\_in$, the one of {\tt
out\_data} $num\_examples \star n\_out$. The {\tt options} argument is
a structure which may be used to specify the identification method and
options. It can define two fields; {\tt id\_par} for the
identification parameters and {\tt cmb\_par} for the model combination
parameters.The first one defines the range in which the number of
neighbors is searched.  The identification parameter can assume the
following forms:
%
\begin{enumerate}
%
\item   
  	  {\tt id\_par[3,3]}
  	\hfil
$
		{\tt id\_par} = 
  		\left|\begin{array}{ccc}
  			 {\tt idm0} 
  				&{\tt idM0} 
  					&{\tt valM0}\\
  			 {\tt idm1} 
  				&{\tt idM1} 
  					&{\tt valM1}\\
  			 {\tt idm2} 
  				&{\tt idM2} 
  					&{\tt valM2}
  		\end{array}\right|
$
  	\hfil \\[1ex]
%     
	where {\tt [idm$d$,idM$d$]} is the range $\mathcal{K}(d)$ in
	which the best number of neighbors is searched when identifying
	the local model of degree $d$. The scalar {\tt valM$d$} defines
	the maximum number of neighbors on which the local model of
	degree $d$ is validated:
%
	\begin{equation}
		\mathit{mse}_{d}^\mathit{cv}(k) 
           = \frac{1}{m_d(k)} \sum_{j=1}^{m_d(k)} 
		e_{d,j}^\mathit{cv}(k).
	\end{equation}
%
	where $m(k) = \min(k,{\tt valM}d)$.
%
%%
%
\item   
	  {\tt id\_par[3,2]}
	\hfil
$
		{\tt id\_par} = 
		\left|\begin{array}{cc}
			 {\tt idm0} 
				&{\tt idM0} \\
			 {\tt idm1} 
				&{\tt idM1} \\
			 {\tt idm2} 
				&{\tt idM2} \\
		\end{array}\right|
$
	\hfil \\[1ex] 
%
	where {\tt [idm$d$,idM$d$]} have the same meaning as in point 1,
	and {\tt valM$d$} assumes the default value of {\tt idM$d$} for
	all the values of $d$: for every local model considered, all the
	neighbors used in identification are used also in validation.
%
%%
%
\item   
	  {\tt id\_par[3,1]}
	\hfil
$
		{\tt id\_par} = 
		\left|\begin{array}{c}
			 {\tt c0} \\
			 {\tt c1} \\
			 {\tt c2} 
		\end{array}\right|
$
	\hfil \\[1ex]
%
        Here {\tt idm$d$} and {\tt idM$d$} are obtained according to the
	following formulas: 
%
	\begin{center}
%	
	    {\tt idm$d$ = floor(3 * p$d$ * c$d$)}\\
	    {\tt idM$d$ = ceil(5 * p$d$ * c$d$)}
	\end{center}
%
	where {\tt p$d$} is the number of parameter of the model of
	degree $d$. Recommended choice: {\tt c$d$} = 1. The validation
	parameters get the default value as in point 2.
%
%%
\end{enumerate}
%
{\tt cmb\_par} determines the behavior of the function for what
concerns the combination/selection of the local models.
%
If {\tt cmb\_par} is not given, the best model is selected among those
identified as specified by {\tt id\_par}. In this case, the model
combination reduces to a simple model selection.
%
The default value for {\tt cmb\_par} is 1 as it will be clear from what
follows.   
%
If given, {\tt cmb\_par} can assume the following to forms:
%
\begin{enumerate}
%
\item   
	  {\tt cmb\_par[3,1]}
	\hfil
$		{\tt cmb\_par} = 
		\left|\begin{array}{c}
			 {\tt cmb0} \\
			 {\tt cmb1} \\
			 {\tt cmb2} 
		\end{array}\right|
$
	\hfil \\[1ex]
%     
	where {\tt cmb$d$} is the number of models of degree $d$ that
  	will be included in the local combination.  Each local model
  	will be therefore a combination of the best {\tt cmb0} models of
  	degree 0, the best {\tt cmb1} models of degree 1, and the best
  	{\tt cmb2} models of degree 2, all identified as specified by
  	{\tt id\_par}.
%
%%
%
\item   
	  {\tt cmb\_par[1,1]}
	\hfil
$		{\tt cmb\_par} = 
		\left|\begin{array}{c}
			 {\tt cmb}
		\end{array}\right|
$
	\hfil \\[1ex]
%
  	where {\tt cmb} is the number of models that will be combined,
	disregarding any constraint on the degree of the models that
	will be considered.  Each local model will be therefore a
	combination of the best {\tt cmb} models, identified as
	specified by {\tt id\_par}.
%
%%
\end{enumerate}
It is important to notice that less computational expensive models are
the constant ones, followd by the linear ones. The quadratic models
are particularly heavy and should not be used for for a number of
inputs which is greater than 7-8. The combination of models improves
the performance of the lazy algorithm. For more details about the
features of the algorithm see ``The lazy learning toolbox''
\cite{lazy_toolbox}.\\ 
 
The {\tt eval} method calculates the output of the lazy system for a
given input. At each query point it builds a local model fitting the
data close to the query point using the database of the examples. This
function is quite computationally expensive in comparison with the
{\tt eval} methods defined in other classes such as linear and taksug,
since all the database of the examples must be completely scanned and
the model generated at each query.\\

The method {\tt jacob\_inputs} computes the jacobian of the outputs
respect to the inputs, while the method {\tt jacob\_params} is only
provided for consistency, buy returns an empty array, since it has no
meaning for the lazy mapping.\\

Methods for normalising and denormalising the mapping ( if
the {\tt limits} are finite) are provided. Finally the the 
method {\tt check} checks the consistency of all the fields defined in
a lazy object.

\subsection{The taksug class}
The {\tt taksug} class is used when an input-output relation inside the system
is to be represented with a Takagi Sugeno fuzzy system:
\begin{verbatim}
ts = taksug('Takagi Sugeno Mapping',2,3)
\end{verbatim}
produces a 2 inputs, 3 outputs TS fuzzy function.
The object returned is as follows:
\begin{verbatim}
A taksug object with the following attributes
 
           name: 'Takagi Sugeno Mapping'
           n_in: 2
          n_out: 3
         limits: [2x5  double]
       userData: []
            opt: []
           date: [1999 7 27 17 19 19.5549]
    optimparams: []
        n_rules: 0
     model_code: {}
              m: 2
        centers: []
     ivariances: []
            rls: []
            mfs: {1x2  cell  }
        linears: []
\end{verbatim}
Once again, the {\tt name} field stores the name of the object, {\tt n\_in} and
{\tt n\_out} the number of input and output of the mapping. This class
as well has the {\tt limits}, {\tt userData}, {\tt opt}, {\tt optimparams},
and {\tt date} fields which have the same meaning as in the
{\tt linear} class.
{\tt n\_rules} is the number of rules of the TS function. It should not be changed by hand,
{\tt add\_rules} and {\tt rem\_rules} take care of maintaining it coherent with the others
attributes of the object. The same remark is appliable for the dimensions of the other fields
specific to {\tt taksug}.\\

Let's add a few rules to the TS system:
\begin{verbatim}
ts = add_rules(ts,5)
 
ts =
 
A taksug object with the following attributes
 
           name: 'Takagi Sugeno Mapping'
           n_in: 2
          n_out: 3
         limits: [2x5   double]
       userData: []
            opt: []
           date: [1999 7 27 17 19 19.5549]
    optimparams: []
        n_rules: 5
     model_code: {1x3   cell  }
              m: 2
        centers: [2x5   double]
     ivariances: [2x2x5 double]
            rls: []
            mfs: {1x2   cell  }
        linears: [3x3x5 double]
\end{verbatim}
If we look inside {\tt ts.model\_code}, Matlab\texttrademark returns:

\begin{verbatim}
ans = 

    'productspace'    'inversedist'    'linear'
\end{verbatim}
which means that the TS rules are defined in the multidimensional space formed by the
product of the input spaces ({\tt productspace}), that the degrees of fullfilment of the
rules are computed on the basis of the inverse of the distance ({\tt inversedist}) and that
the consequents of the rules are linear functions ({\tt linear}).
We can either change this value by writing for example:
\begin{verbatim}
set(ts,'model_code',{'productspace' 'gaussian' 'linear'})
\end{verbatim}
or we could have called the {\tt add\_rules} with an extra parameter:
\begin{verbatim}
ts = add_rules(ts,5,{'productspace' 'gaussian' 'linear'})
\end{verbatim}
If we call add\_rules and the specified rule types don't match the previously added ones,
the following error message is issued:
\begin{verbatim}
??? Error using ==> taksug/add_rules
You cannot add rules of this type to the current model.
Remove first the previous ones
\end{verbatim}
In this case, {\tt rem\_rules} has to be used to empty the rules before
new types of rules can be added.\\

The fields {\tt centers} and {\tt ivariances} are used to describe rules defined in the
cross product space:\\
\begin{center}
${\cal R}^{(l)}:$ IF $x_1, x_2, ..., x_n$ IS $A^{(l)}$ THEN $y=h^{(l)}(x)$
\end{center}
while the fields {\tt rls} and {\tt mfs} are used for projected rules:
\begin{center}
${\cal R}^{(l)}:$ IF $x_1$ IS $A_1^{(l)}$ AND \dots AND  $x_n$ IS $A_n^{(l)}$
THEN $y=h^{(l)}(x)$.
\end{center}

{\tt centers} is a $n\_in \star (n\_rules)$ matrix containing for each rule, the center $c_l$
of the fuzzy set, antecedent of the rule $l$. {\tt ivariances} is a $n\_in \star n\_in \star (n\_rules)$
matrix $\Lambda_l$ containing for each rule, the quadratic matrix defining the metric of the antecedent of
the rule $l$. $linears$ contains the parameters of the linear consequent $L_l$ of the rule.
The output of the Takagi Sugeno system is therefore computed as this:
\begin{equation}
y = \sum_l^{l=n} e^{-(x - c_l)^T \Lambda_l (x - c_l)} * L_l * x
\end{equation}
for {\tt model\_code} equal to {\tt \{'productspace' 'gaussian' 'linear'\}} and
\begin{equation}
y = \sum_l^{l=n} \frac{1}{[1 + (x - c_l)^T \Lambda_l (x - c_l)]^{\frac{1}{m-1}}} * L_l * x
\end{equation}
for {\tt model\_code} equal to {\tt \{'productspace' 'inversedist' 'linear'\}}.\\

{\tt mfs} is cell array (one cell for each input) whose the cells contain the description
of the rukes along each input dimension. {\tt rls} defines the rule base. Its size is
$n\_rules \star (n\_in)$.\\

Let's take an example of a {\tt projected} Takagi Sugeno system. This is the Matlab\texttrademark session:

\begin{verbatim}
>>ts = taksug('Takagi Sugeno Mapping',2,3);
>>ts.limits(:,1:2) =[0 0;1 1];
>>ts = sets_grid(ts, 3, 5, 'trapezoidal');
>>ts = add_rules(ts, 15, {'projected' 'rulegrid' 'linear'})
 
ts =
 
A taksug object with the following attributes
 
           name: 'Takagi Sugeno Mapping'
           n_in: 2
          n_out: 3
         limits: [ 2x5    double]
       userData: []
            opt: []
           date: [1999 7 28 11 9 29.3285]
    optimparams: []
        n_rules: 15
     model_code: { 1x3    cell  }
              m: 2
        centers: []
     ivariances: []
            rls: [15x2    double]
            mfs: { 1x2    cell  }
        linears: [ 3x3x15 double]

\end{verbatim}

The {\tt taksug} object is created using the constructor {\tt taksug}, limits are specified for the
two inputs. On the basis of these limits, the toolbox is able to populate the inputs with
fuzzy sets using the {\tt sets\_grid} method. In this case, 3 sets are put on the first dimension
and 5 are put on the second one. The sets are {\tt trapezoidal}. The other possible set types are {\tt constant},
 {\tt gaussian} and {\tt s-shaped}. Rules are added by means of the {\tt add\_rules} method. Note the
 {\tt projected} option and the {\tt rulegrid} option which specifies that fuzzy sets previously created
have to be used in order to create evenly distributed rules.

Now let's look inside the structure of the object we have defined:
\begin{verbatim} 
>>ts.mfs{1}

ans =

    1.0000         0         0    0.1667    0.3333
    1.0000    0.1667    0.3333    0.6667    0.8333
    1.0000    0.6667    0.8333    1.0000    1.0000
\end{verbatim}
The first column of {\tt mfs} contain, for each set, the code representing the type
of the set (trapezoidal, gaussian, s-shaped). The next four are used to specify
the location and the extent of the rules.

{\tt rls} is a list of the fuzzy sets associated to each rule:
\begin{verbatim}
>>ts.rls

ans =

     1     1
     2     1
     3     1
     1     2
     2     2
     3     2
     ...
\end{verbatim}
which states for example that rule 6 has to be read as:
\begin{center}
${\cal R}^{(6)}:$ IF $x_1$ IS $A_1^3$ AND $x_2$ IS $A_2^2$ THEN $y=L_6 x$.
\end{center}

As we have seen, fuzzy sets can be added by hand and there position and size can be
changed using the {\tt set} function. The same holds for the linear consequents or the rules.
An alternate way of defining the rule base is to use the {\tt identify} method.
\begin{verbatim}
m = identify(m,in,out,options)
\end{verbatim}
optimise the TS function to fit the input-output data contained in the
{\tt in} and {\tt out} arrays. {\tt in} must have a size of
$num\_examples \star n\_in$ while {\tt out} must be equal to 
$num\_examples \star n\_out$.\\
{\tt option} is a struct whose fields {\tt method}, {\tt n\_rules}, {\tt fuzzyness}, ...
(see help of the taksug/identify method) let choose among different optimisation procedures
and tune these procedure.

The class provides a method for evaluating the mapping given an input,
{\tt eval}, method for normalising and denormalising the mapping ( if
the {\tt limits} are finite). The methods {\tt jacob\_inputs} and {\tt
jacob\_params}  are used to calculate the derivatives of the mapping
respect to the inputs and the parameters. The method {\tt check} is
provided  to check the consistency of all the fields defined in
the {\tt taksug} object.

\subsection{The mamdani class}
The {\tt mamdani} class used to represent Mamdani type of fuzzy systems is very similar
to the {\tt taksug} class. 

The same methods are available though the calling convention can differ slightly. The
following example should be compared to the one provided for the {\tt taksug} class:

\begin{verbatim}
>>m = mamdani('Mamdani Mapping',3,2);
>>m.limits = [0 0 0 0 0;1 1 1 1 1];
>>m = sets_grid(m,3,2,3,1,2);
>>m = add_rules(m,-1,{'product' 'meancentroid'},'rulegrid')
 
m =
 
A taksug object with the following attributes
 
           name: 'Mamdani Mapping'
           n_in: 3
          n_out: 2
         limits: [ 2x5 double]
       userData: []
            opt: []
           date: [1999 7 28 14 17 18.6538]
    optimparams: []
        n_rules: 18
     model_code: { 1x2 cell  }
            rls: [18x5 double]
            mfs: { 1x5 cell  }
\end{verbatim}

With respect to the {\tt taksug} class, it has to be highlighted that only the fields
used in the {\tt projected} rules are present in the {\tt mamdani} class. The {\tt linears}
attribute is not present and is replaced by extra fuzzy sets (one series for each output)
stored inside {\tt mfs}. The rules are of the form:

\begin{center}
${\cal R}^{(l)}:$ IF $x_1$ IS $A_1^{(l)}$ AND \dots AND  $x_n$ IS $A_n^{(l)}$
THEN $y_1$ IS $B_1^{(l)}$ \dots $y_m$ IS $B_m^{(l)}$.
\end{center}

and {\tt rls} contains for each rules the list of the fuzzy sets defining the antecedent
as well as the {\em fuzzy sets defining the consequent} of the rule.

The {\tt model\_code} attribute, determines the T-norm used for the AND operator and the
defuzzification method used during the fuzzy inference.

No identification method is defined yet.

\section{Handling data with the {\tt dataset} class}
Dataset is quite a complete package to handle data. It allows to perform normalisation,
statistical analysis, clustering, supervised classification of data. The description of
the use of dataset exceeds the scope of this tutorial. We encourage the reader to refer
to the dataset tutorial or the dataset documentation for extensive information.\\

In this tutorial, we will focus on the use of the {\tt dataset} constructor specifically
applied to build dataset used for regression puposes. The syntax of {\tt dataset} is the
following:

\begin{verbatim}
dataset(data)
\end{verbatim}

{\tt data} holds the raw data (one sample on each row, one column for each variable).

\section{NLMIMO identification in a nutshell}

The nlmimo toolbox allows a great flexibility for the identification of
static and dynamic systems. In any case the main steps which are
needed to build such a system follow (let's consider an external
system):
\begin{itemize}
\item build the system ({\tt external}) defining the appropriate
number of inputs and outputs;
\item put the data inside a {\tt dataset} object and attach it to the
external object with the appropriate sampling time;
\item define the dynamics of the system;
\item define the mappings which will be used by the system, and make
them consistent with the dynamics description of the system; 
\item attach the mapping to the external object and link them to the
outputs of the system;
\item perform the identification;
\item evaluate the identification results
\end{itemize}
if the results are not satisfactory (thing that usually happens at the
beginning), change the mappings or even the dynamics of the system and
try again. 




