\newpage \noindent {\bf \huge external}\\  \rule[3pt]{\textwidth}{1pt}\\
\begin{description}
 \item[Purpose]\ \newline \newline 
Constructor for the external class

\end{description}

\begin{description}
 \item[Synopsis]\ \newline \newline 
{\tt m=external}\\ 
{\tt m=external(m)}\\ 
{\tt m=external(name,n\_in,n\_out) }\\ 
\end{description}

\begin{description}
 \item[Description]\ \newline \newline 
{\tt m=external} 
creates a new general external skeleton.
\vspace{4mm}\\ 
\hspace{2mm}
{\tt m=external(m)} 
clone the external object {\tt m}. This can be
also used to transform a structure in a external object since the
common fields are used to inizialize the external object.
\vspace{4mm}\\ 
\hspace{2mm}
{\tt m=external(name,n\_in,n\_out) } 
creates a new general system with {\tt n\_in} inputs
and {\tt n\_out} outputs. The name {\tt name} is associated
to it.       
\end{description}

\begin{description}
 \item[Methods]\ \\ 
\begin{itemize}
\item {\tt add\_dynamics}   add the dynamical description of the model
\item {\tt build\_regressors}   build the regresors for a MIMO system
\item {\tt check}   checks the consistency of all the fields of a external object
\item {\tt display}   Display an object of class external

\item {\tt error}   computes the mean square error of the model
\item {\tt errordb}   Graphical User Interface for inspecting the errors of the mappings
\item {\tt get}   gets the value of the attribute of an object
\item {\tt identify}   Identify the system from data

\item {\tt regress}   extracts the regressors from the data
\item {\tt set}   Set object properties
\item {\tt simulate}   simulates the model
\item {\tt simulation\_error}   computes the mean square error of the simulated model
\end{itemize}
\end{description}
\newpage \noindent {\bf \huge add\_dynamics}\\  \rule[3pt]{\textwidth}{1pt}\\
\begin{description}
 \item[Purpose]\ \newline \newline 
add the dynamical description of the model
\end{description}

\begin{description}
 \item[Synopsis]\ \newline \newline 
{\tt m=add\_dynamics(m,dyn)}\\ 
{\tt m=add\_dynamics(m,ny,nu,nd)}\\ 
\end{description}

\begin{description}
 \item[Description]\ \newline \newline 
{\tt m=add\_dynamics(m,dyn)} 
attaches to the model {\tt m} the dynamic
description of the model 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.
\vspace{4mm}\\ 
\hspace{2mm}
{\tt m=add\_dynamics(m,ny,nu,nd)} 
attaches to the model {\tt m} the dynamic
description of the system as defined in the arrays {\tt ny},
{\tt nu}, and {\tt nd}.
\end{description}

\begin{description}
 \item[Remarks]\ \newline \newline 
This is 
done by inizializing the 'nu', 'ny' and 'nd' subfields of the 
'dynamics' field of the model. These  define the structure of the 
regressors and therefore the dynamical behaviour of the system. 'ny'
is a {\tt  num\_out * num\_out} square matrix which contains
the relationships of each output (each row) with all the other
outputs. Each entry {\tt ij} indicates the number of past
values associated to the output {\tt j} used in the
regressor of the output {\tt i}. 'nu' is a {\tt  num\_out *
num\_in} matrix defining the relationships between the
outputs and each input. Each entry {\tt ij} indicates the
number of past values associated to the input {\tt j} used
in the regressor of the output {\tt i}. Finally 'nd' is a
{\tt  num\_out * num\_in} matrix defining the delay of the
inputs respect to the outputs. Each entry {\tt ij}
indicates the delay of the input {\tt j} used in the
regressor of the output {\tt i}.

\end{description}

\begin{description}
 \item[See also]\ \newline \newline 
get

\end{description}
\newpage \noindent {\bf \huge build\_regressors}\\  \rule[3pt]{\textwidth}{1pt}\\
\begin{description}
 \item[Purpose]\ \newline \newline 
build the regresors for a MIMO system
\end{description}

\begin{description}
 \item[Synopsis]\ \newline \newline 
{\tt [in,out]=build\_regressors(m,z,subset);}\\ 
\end{description}

\begin{description}
 \item[Description]\ \newline \newline 
{\tt [in,out]=build\_regressors(m,z,subset);} 
given the inputs outputs {\tt z}=[outputs inputs],
computes {\tt subset} regressors.
\end{description}

\begin{description}
 \item[Remarks]\ \newline \newline 
For z=[y u];
in{o}(t)=[y{1}(t-1),y{1}(t-2),...,y{1}(t-ny(o,1)),y{2}(t-1),y{2}(t-2),...,y{2}(t-ny(o,2)), ...
u{1}(t-nd(O,1)),u{1}(t-1-nd(O,1)),...,u{1}(t-nu(o,1)-nd(O,1)), ...]
out{o}(t)=y{o}(t)
It works even if y{1} ... are all vectors (useful for the computation of the derivatives)

\end{description}
\newpage \noindent {\bf \huge check}\\  \rule[3pt]{\textwidth}{1pt}\\
\begin{description}
 \item[Purpose]\ \newline \newline 
checks the consistency of all the fields of a external object
\end{description}

\begin{description}
 \item[Synopsis]\ \newline \newline 
{\tt check(m)}\\ 
\end{description}

\begin{description}
 \item[Description]\ \newline \newline 
{\tt check(m)} 
check the consistency of a external object.
\end{description}

\begin{description}
 \item[Remarks]\ \newline \newline 
This function has been provided in order to make the external class
more rouboust since it checks a external object for consistency of
the data defined in its fields. If a inconsistency is found, an 
error message is displayed.

\end{description}
\newpage \noindent {\bf \huge display}\\  \rule[3pt]{\textwidth}{1pt}\\
\begin{description}
 \item[Purpose]\ \newline \newline 
Display an object of class external

\end{description}

\begin{description}
 \item[Synopsis]\ \newline \newline 
{\tt display(m)}\\ 
\end{description}

\begin{description}
 \item[Description]\ \newline \newline 
{\tt display(m)} 
Display the object m of class external
\end{description}
\newpage \noindent {\bf \huge error}\\  \rule[3pt]{\textwidth}{1pt}\\
\begin{description}
 \item[Purpose]\ \newline \newline 
computes the mean square error of the model
\end{description}

\begin{description}
 \item[Synopsis]\ \newline \newline 
{\tt err=error(m,j)}\\ 
{\tt err=error(m,data,j)}\\ 
\end{description}

\begin{description}
 \item[Description]\ \newline \newline 
{\tt err=error(m,j)} 
returns the mean square error of the model respect the output {\tt j}.
\vspace{4mm}\\ 
\hspace{2mm}
{\tt err=error(m,data,j)} 
get the error of the model respect the data {\tt data} 
and the output {\tt j}. {\tt data} must be an object of
the class dataset.
\end{description}

\begin{description}
 \item[Remarks]\ \newline \newline 
This function 
evaluates the mean square error of the model respect to the reference set of 
values given as output data. This is performed by the function by calling the
'eval' method, obtaining the extimated output of the model 
and comparing it with the reference one.  

\end{description}

\begin{description}
 \item[See also]\ \newline \newline 
simulation\_error

\end{description}
\newpage \noindent {\bf \huge errordb}\\  \rule[3pt]{\textwidth}{1pt}\\
\begin{description}
 \item[Purpose]\ \newline \newline 
Graphical User Interface for inspecting the errors of the mappings
\end{description}

\begin{description}
 \item[See also]\ \newline \newline 


\end{description}
\newpage \noindent {\bf \huge get}\\  \rule[3pt]{\textwidth}{1pt}\\
\begin{description}
 \item[Purpose]\ \newline \newline 
gets the value of the attribute of an object
\end{description}

\begin{description}
 \item[Synopsis]\ \newline \newline 
{\tt d = get(m,label,options)}\\ 
\end{description}

\begin{description}
 \item[Description]\ \newline \newline 
{\tt d = get(m,label,options)} 
gets the value of the attribute {\tt label}
associated to the object {\tt m} and return it inside {\tt d}.
The following codes are recognised:
\\  
\begin{tabular}{lp{12cm}}
{\tt name}: & returns the name of the object \\ 
{\tt n\_in}: & returns the number of inputs of the system \\ 
{\tt n\_out}: & returns the number of outputs of the system \\ 
{\tt data}: & returns the data set linked to the system \\ 
{\tt T}: & returns the sampling period of the discrete system, 0 if continuous \\ 
{\tt mapping}: & returns the array of mappings \\ 
{\tt links}: & returns the links array which defines which output is computed by which mapping \\ 
{\tt limits}: & returns the bounds of the inputs and outputs \\ 
{\tt userData}: & returns the 'userData' field \\ 
{\tt opt}: & returns the 'opt' field \\ 
{\tt date}: & returns the date of creation of the object \\ 
{\tt mapfield}: & let the user access directly property of the mappings. When used, opt
must contain a 2 elements cell array {{\tt n} 'property'}. {\tt n} is the index of the 
mapping and 'property' is the name of the property which has to be accessed. An even more convenient
way to access mappings' fields is a achieved through the syntax s{n}.property. \\ 
{\tt numparams}: & returns the number of parameters to be optimised \\ 
{\tt params}: & returns the parameters to be optimised \\ 
{\tt dynamics}: & returns the dynamical description of the regressors \\ 
{\tt horiz\_length}: & returns the width of the time window used to compute the outputs \\ 
\end{tabular} \\ 

\end{description}

\begin{description}
 \item[See also]\ \newline \newline 
set

\end{description}
\newpage \noindent {\bf \huge identify}\\  \rule[3pt]{\textwidth}{1pt}\\
\begin{description}
 \item[Purpose]\ \newline \newline 
Identify the system from data

\end{description}

\begin{description}
 \item[Synopsis]\ \newline \newline 
{\tt m = identify(m) }\\ 
{\tt m = identify(m,j,options)}\\ 
\end{description}

\begin{description}
 \item[Description]\ \newline \newline 
{\tt m = identify(m) } 
performs the identification of the model {\tt m}
using the data embedded inside the object for all the outputs of the
system, using the defautl values of the identification methods. 
\vspace{4mm}\\ 
\hspace{2mm}
{\tt m = identify(m,j,options)} 
performs the identification of the model {\tt m} using
the data embeded inside the object for the outputs listed in the
array {\tt j}. Use {\tt options} in order
to specify the identification method and options.
\end{description}

\begin{description}
 \item[See also]\ \newline \newline 
eval

\end{description}
\newpage \noindent {\bf \huge regress}\\  \rule[3pt]{\textwidth}{1pt}\\
\begin{description}
 \item[Purpose]\ \newline \newline 
extracts the regressors from the data
\end{description}

\begin{description}
 \item[Synopsis]\ \newline \newline 
{\tt [r\_in,r\_out]=get\_regressors(m)}\\ 
{\tt [r\_in,r\_out]=get\_regressors(m,j)}\\ 
\end{description}

\begin{description}
 \item[Description]\ \newline \newline 
{\tt [r\_in,r\_out]=get\_regressors(m)} 
extracts the regressors from the model {\tt m},
for all the outputs of the system.
\vspace{4mm}\\ 
\hspace{2mm}
{\tt [r\_in,r\_out]=get\_regressors(m,j)} 
extracts the regressors from the model {\tt m},
for all the outputs of the system defined in the array {\tt j}.
\end{description}

\begin{description}
 \item[Remarks]\ \newline \newline 
This function uses the
dynamical system representation stored in the 'dynamics' field to
extract the regressors form the input-output data stored in the '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 {\tt size\_regressor
* num\_exaples}, where {\tt size\_regressor} depends from the
structure of the regressor defined in the dynamical description of the
system, and {\tt num\_exaples} is the number of exaples given in
the input-output data set. {\tt r\_in} is a cell array returing
the corrispondent output of each regressor taken from the output data
set. Each entry in the cell array is a vector of size {\tt 1 *
num\_exaples}. 

\end{description}
\newpage \noindent {\bf \huge set}\\  \rule[3pt]{\textwidth}{1pt}\\
\begin{description}
 \item[Purpose]\ \newline \newline 
Set object properties
\end{description}

\begin{description}
 \item[Synopsis]\ \newline \newline 
{\tt set(m,'AttrName1',AttrValue1,'AttrName2',AttrValue2,...)}\\ 
{\tt m\_out = set(m,'AttrName1',AttrValue1,'AttrName2',AttrValue2,...)}\\ 
\end{description}

\begin{description}
 \item[Description]\ \newline \newline 
{\tt set(m,'AttrName1',AttrValue1,'AttrName2',AttrValue2,...)} 
sets the value of the attribute {\tt AttrName1},
{\tt AttrName2}, ... associated to the object {\tt m}.
\vspace{4mm}\\ 
\hspace{2mm}
{\tt m\_out = set(m,'AttrName1',AttrValue1,'AttrName2',AttrValue2,...)} 
sets the value of the attribute {\tt AttrName1},
{\tt AttrName2}, ... associated to the object {\tt m} and
return the modified model inside m\_out. The original model is not modified.
The following {\tt AttrName} are recognised:
\\  
\begin{tabular}{lp{12cm}}
{\tt name}: & sets the name of the system \\ 
{\tt n\_in}: & sets the number of inputs of the system \\ 
{\tt n\_out}: & sets the number of outputs of the system \\ 
{\tt data}: & sets the data set linked to the system \\ 
{\tt T}: & sets the sampling period of the discrete system, 0 if continuous \\ 
{\tt mapping}: & sets the array of mappings \\ 
{\tt links}: & sets the links array which defines which output is computed by which mapping \\ 
{\tt limits}: & sets the limits of the domain of definition
of the mapping. The value must be a {\tt 2*n\_in} matrix where
the upper and lever saturation level are \\ 
{\tt userData}: & sets the 'userData' field \\ 
{\tt opt}: & sets the 'opt' field \\ 
{\tt date}: & sets the date of creation of the object \\ 
{\tt mapfield}: & let the user access directly property of the mappings. When used, {\tt value}
must contain a 3 elements cell array {{\tt n} 'property' {\tt mapvalue}}. {\tt n} is the index of the 
mapping, 'property' is the name of the property which has to be changet and {\tt mapvalue} is the new value. An even more convenient
way to change mappings' fields is a achieved through the syntax s{n}.property = mapvalue. \\ 
{\tt params}: & sets the parameters to be optimised \\ 
{\tt dynamics}: & sets the dynamics of the system (please use add\_dynamics instead) \\ 
\end{tabular} \\ 

\end{description}

\begin{description}
 \item[See also]\ \newline \newline 
get

\end{description}
\newpage \noindent {\bf \huge simulate}\\  \rule[3pt]{\textwidth}{1pt}\\
\begin{description}
 \item[Purpose]\ \newline \newline 
simulates the model
\end{description}

\begin{description}
 \item[Synopsis]\ \newline \newline 
{\tt [res,m]=simulate(m)}\\ 
{\tt [res,m]=simulate(m,time)}\\ 
\end{description}

\begin{description}
 \item[Description]\ \newline \newline 
{\tt [res,m]=simulate(m)} 
simulate the model {\tt m} using the input data.
\vspace{4mm}\\ 
\hspace{2mm}
{\tt [res,m]=simulate(m,time)} 
simulate the model  {\tt m} for the time horizon {\tt time}
\end{description}

\begin{description}
 \item[Remarks]\ \newline \newline 
This function performs a simulation of the 
model {\tt m} using the input data and feeding back the results
of the simulation to calculate at each step the regressors. The result of 
the simulation {\tt res} is a {\tt simulation\_time * num\_outputs}
array. 

\end{description}
\newpage \noindent {\bf \huge simulation\_error}\\  \rule[3pt]{\textwidth}{1pt}\\
\begin{description}
 \item[Purpose]\ \newline \newline 
computes the mean square error of the simulated model
\end{description}

\begin{description}
 \item[Synopsis]\ \newline \newline 
{\tt m=simulation\_error(m,j,'plot')}\\ 
{\tt m=simulation\_error(m,data,j)}\\ 
\end{description}

\begin{description}
 \item[Description]\ \newline \newline 
{\tt m=simulation\_error(m,j,'plot')} 
get the simulation error of the model {\tt m} respect 
the output {\tt j}. If the instead of the number of the output
the label 'all' is given to the function the error respect all the outputs is
returned in an array. The optional label {\tt plot} may be
specified if a plot of the original data and the simulation is
desired.   
\vspace{4mm}\\ 
\hspace{2mm}
{\tt m=simulation\_error(m,data,j)} 
get the error of the simulated model {\tt m} respect  
the output {\tt j} and the data {\tt data} input-output set.
{\tt data} must be a structure defining the 'dat\_in' and 'dat\_out'  
fields which contain the input output data. If the instead of the
number of the output {\tt j}
the label 'all' is given to the function the error respect all the outputs is
returned in an array. The optional label <code>'plot'</code> may be
specified if a plot of the original data and the simulation is
desired.   
\end{description}

\begin{description}
 \item[Remarks]\ \newline \newline 
This function
performs a simulation of the model using the {\tt simulate} method and
then calculates the mean square error by comparing the simulated output
with the value of the output contained in the output data set. 

\end{description}

\begin{description}
 \item[See also]\ \newline \newline 
error

\end{description}
