@comment %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@comment  Version control history
@comment %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@comment  $Id$
@comment  $Log$
@comment  Revision 1.9  2002/07/05 13:29:34  geraint
@comment  Added notes about generating dynamically linked functions for Octave and Matlab.
@comment
@comment  Revision 1.8  2002/07/04 21:34:12  geraint
@comment  Updated gnuplot view description to describe Tcl/Tk interface instead of obsolete txt method.
@comment
@comment  Revision 1.7  2002/04/23 09:51:54  gawthrop
@comment  Changed incorrect statement about searching for components.
@comment
@comment  Revision 1.6  2001/10/15 14:29:50  gawthrop
@comment  Added documentaton on  [1:N] style port labels
@comment
@comment  Revision 1.5  2001/07/23 03:35:29  geraint
@comment  Updated file structure (mtt/bin).
@comment
@comment  Revision 1.4  2001/07/23 03:25:02  geraint

Simulation parameters

* Euler integration::           
* Implicit integration::        
* Runge Kutta IV integration::  
* Hybrd algebraic solver::      

Simulation code

* Dynamically linked functions::  

Simulation output

* Viewing results with gnuplot::  
* Exporting results to SciGraphica::  

Representations

* Text editors::                
* Octave::                      
* LaTeX::                       

Octave

* Octave control system toolbox (OCST)::  
* Creating GNU Octave .oct files::  
* Creating Matlab .mex files::  
* Embedding MTT models in Simulink::  

Administration

* Software components::         
* REDUCE setup::                
* Octave setup::                
* Paths::                       

@end example

To generate an executable based on the C++ representation:
@example
mtt -cc [options] sys ode2odes exe
@end example

@menu
* Dynamically linked functions::  
@end menu

@node Dynamically linked functions,  , Simulation code, Simulation code
@comment  node-name,  next,  previous,  up
@subsection Dynamically linked functions

Some model representations can be compiled into dynamically loaded
code (shared objects) which are compiled prior to use in other
modelling and simulation environments; in particular, .oct files can
be generated for use in GNU Octave (@pxref{Creating GNU Octave .oct
files}) and .mex files can be generated for use in Matlab
(@pxref{Creating Matlab .mex files}) or Simulink (@pxref{Embedding MTT
models in Simulink}).  The use of compiled (and possibly
compiler-optimised) code can offer significant processing speed
advantages over equivalent interpreted functions (e.g. .m files) for
computationally intensive procedures.

The C++ code generated by @strong{MTT} allows the same code to be
generated as standalone code, Octave .oct files or Matlab .mexglx
files. Although @strong{MTT} usually takes care of the compilation
options, if it is necessary to compile the code on a machine on which
@strong{MTT} is not installed, the appropriate flag should be passed
to the compiler pre-processor:
@itemize @bullet
@item
@code{-DCODEGENTARGET=STANDALONE}
@item
@code{-DCODEGENTARGET=OCTAVEDLD}
@item
@code{-DCODEGENTARGET=MATLABMEX}
@end itemize

@node Simulation output,  , Simulation code, Simulation
@comment  node-name,  next,  previous,  up
@section Simulation output
@cindex Simulation output
The view (@pxref{Views}) representation provides a graphical
representation of the results of a simulation; the postscript language
provides the same thing in a form that can be included in a document.

@end menu

@node Viewing results with gnuplot, Exporting results to SciGraphica, Simulation output, Simulation output
@comment  node-name,  next,  previous,  up@subsection
@subsection Viewing results with gnuplot
@cindex gnuplot

Simulation plots may be conveniently selected, viewed with
@uref{http://www.gnuplot.org,gnuplot} 
and saved to file (in PostScript format) using the command

@example
mtt [options] rc gnuplot view
@end example


This will cause a menu to be displayed, from which states and outputs may be selected for viewing. Clicking on a @emph{parameter name} will cause a new window to be opened displaying the time history of the selected parameter. Selecting the @emph{print} option in the main window provides the option of saving to file a plot of the last selected parameter. Clicking on the @emph{title bar} of the main window (``Outputs'' or ``States'') will alter the order in which the parameter names are displayed.





It should be noted that unlike other representations, if a simulation has been previously run in a directory, this command will @emph{not} cause @strong{MTT} to re-run a simulation, even if any of the input files have been changed.


If it is desired to re-run a simulation, it is advisable to run the command 

@example





mtt [options] rc odeso view ; mtt [options] rc gnuplot view




@end example



As with @strong{xMTT} (@pxref{Menu-driven interface}), the Wish Tcl/Tk interpreter must be installed to make use of this feature.

@node Exporting results to SciGraphica,  , Viewing results with gnuplot, Simulation output
@comment  node-name,  next,  previous,  up
@subsection Exporting results to SciGraphica
@cindex SciGraphica

Simulation results can be converted into an XML-format

%% ss1 is both a source and sensor
ss1     SS              external,external
%% ss1 acts as a flow sensor - it imposes zero effort.
ss2     SS              0,external
@end example


@node Other component labels, Component names, SS component labels , Labels (lbl)
@comment  node-name,  next,  previous,  up
@subsection Other component labels 
@cindex Other component labels 

In addition to the label there are two information fields,
@pxref{Labels (lbl)}.
They correspond to the constitutive relationship 

# Generated by MTT at Mon Jun 16 15:10:17 BST 1997

# %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
# %% Version control history
# %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
# %% $Id$
# %% $Log$
# %% Revision 1.9  2002/07/05 13:29:34  geraint
# %% Added notes about generating dynamically linked functions for Octave and Matlab.
# %%
# %% Revision 1.8  2002/07/04 21:34:12  geraint
# %% Updated gnuplot view description to describe Tcl/Tk interface instead of obsolete txt method.
# %%
# %% Revision 1.7  2002/04/23 09:51:54  gawthrop
# %% Changed incorrect statement about searching for components.
# %%
# %% Revision 1.6  2001/10/15 14:29:50  gawthrop
# %% Added documentaton on  [1:N] style port labels
# %%
# %% Revision 1.5  2001/07/23 03:35:29  geraint
# %% Updated file structure (mtt/bin).
# %%
# %% Revision 1.4  2001/07/23 03:25:02  geraint

step(rc);
bode(rc);
@end example


@menu
* Octave control system toolbox (OCST)::  
* Creating GNU Octave .oct files::  
* Creating Matlab .mex files::  
* Embedding MTT models in Simulink::  
@end menu

@node Octave control system toolbox (OCST), Creating GNU Octave .oct files, Octave, Octave
@comment  node-name,  next,  previous,  up
@subsection Octave control system toolbox (OCST)
@cindex Octave
@cindex toolbox
@cindex OCST
@cindex control systems
@cindex mtt2sys

The following octave commands then generate the step reponse and bode
diagram respectively:
@example
step(rc);
bode(rc);
@end example

@node Creating GNU Octave .oct files, Creating Matlab .mex files, Octave control system toolbox (OCST), Octave
@comment  node-name,  next,  previous,  up
@subsection Creating GNU Octave .oct files
@cindex Creating GNU Octave .oct files

GNU Octave dynamically loaded functions (.oct files) can be created by
instructing @strong{MTT} to create the ``oct'' representation:

@example
  mtt [options] sys ode oct
@end example

This will cause @strong{MTT} to create the C++ representation of the system
(sys_ode.cc) and to then compile it as a shared object suitable for
use within Octave. The resultant file may be used in an identical
manner to the equivalent, but generally slower, interpreted .m file.

Usage information for the function may be obtained within Octave in the usual manner:

@example
  octave:1> help rc_ode

  rc_ode is the dynamically-linked function from the file
  /home/mttuser/rc/rc_ode.oct

  Usage: [mttdx] = rc_ode(mttx,mttu,mttt,mttpar)
  Octave ode representation of system rc
  Generated by MTT on Fri Jul  5 11:23:08 BST 2002
@end example

Note that the first line of output from Octave identifies whether the
compiled or interpreted function is being used.

Alternatively, standard representations may be generated using the
Octave DLDs by use of the ``-oct'' switch:

@example
  mtt -oct rc odeso view
@end example

In order to successfully generate .oct files, Octave must be correctly
configured prior to compilation and certain headers and libraries must
be correctly installed on the system (@pxref{.oct file dependencies}).

@node  Creating Matlab .mex files, Embedding MTT models in Simulink, Creating GNU Octave .oct files, Octave
@comment  node-name,  next,  previous,  up
@subsection Creating Matlab .mex files
@cindex Creating Matlab .mex files

On GNU/Linux systems, Matlab dynamically linked executables (.mexglx
files) can created by instructing @strong{MTT} to create the
``mexglx'' representation:

@example
  mtt [options] sys ode mexglx
@end example

This will cause @strong{MTT} to create the C++ representation of the
system (sys_ode.cc) and to then compile it as a shared object suitable
for use within Matlab.

If it is necessary to compile mex files for another platform, then the
usual C++ representation (generated with the -cc flag) can be created
and the resultant file compiled with the -DCODEGENTARGET=MATLABMEX
flag on the target platform.

@example
  mtt_machine:
  mtt -cc rc ode cc

  matlab_machine:
  matlab> mex -DCODEGENTARGET=MATLABMEX rc_ode.cc
@end example

@node  Embedding MTT models in Simulink,  , Creating Matlab .mex files, Octave
@comment  node-name,  next,  previous,  up
@subsection Embedding MTT models in Simulink
@cindex Embedding MTT models in Simulink

It is possible to embed @strong{MTT} functions or entire @strong{MTT}
models within Simulink simulations as Sfun blocks. If the zip package
is installed on the system, the command

@example
  mtt sys sfun zip
@end example

will create a compressed archive containing sys.mdl, which may be
embedded into a larger Simulink model. Also contained within the
archive will be four sys_sfun*.c files,

@itemize @bullet
@item
sys_sfun.c
model state and output equations
@item
sys_sfun_ae.c
model algebraic equations
@item
sys_sfun_input.c
model inputs
@item
sys_sfun_interface.c
interface between MTT model and Simulink
@end itemize

The last of these files must be edited to correctly map the inputs and
outputs between the @strong{MTT} and Simulink models. The two sections
to edit are clearly marked with

@example
  @code{/* Start EDIT */}
  @code{....}
  @code{/* End EDIT */}
@end example

These four files should then be compiled with the Matlab ``mex''
compiler as described in the @emph{README} file in the archive.

If it is desired to compile the .mex files directly from within
@strong{MTT} on a machine which has the Matlab header files installed,
this may be done with the command

@example
  mtt sys sfun mexglx 
@end example

which will generated the four .mex files and the .mdl file. In this
case, the user must ensure that @emph{sys_sfun_interface.c} has been
correctly edited prior to compilation.

Note that solution of algebraic equations within Simulink is not
possible unless the @emph{Matlab Optimisation Toolbox} is installed.

@node LaTeX,  , Octave, Language tools
@comment  node-name,  next,  previous,  up
@section LaTeX
@cindex LaTeX

LaTeX is a powerful text processor which @strong{MTT} uses to provide

empty_list_elements_ok = 1;

@end example

@node .oct file dependencies,  , .octaverc, Octave setup
@comment  node-name,  next,  previous,  up Additionally, it is necessary to
@subsection .oct file dependencies
Successful compilation of .oct code requires that Octave has been
configured to use dynamically linked libraries and that the Octave
libraries @code{liboctave}, @code{libcruft} and @code{liboctinterp}
are available on the system.

This can be acheived by compiling Octave from the source code, configured
with the options @code{--enable-shared} and @code{--enable-dl}.

A number of additional libraries and headers are also required to be
installed on a system. These include,
@itemize @bullet
@item
@emph{ncurses} and @emph{readline}
               terminal control routines
@item
@emph{blas} or @emph{altas}
            basic linear algebra subprograms, usually optimised for the specific processor
@item
@emph{fftw}
        fast Fourier transform routines
@item
@emph{g2c}
        GNU Fortran to C conversion routines
@item
@emph{kpathsea}
        TeX path search routines
@end itemize

Note that on many GNU/Linux distributions, the necessary headers are
contained in development packages which must be installed in addition
to the standard library package.

Further information on configuring and installing Octave to handle dynamic
libraries (DLDs) can be found in the
@uref{http://www.octave.org/docs.html,Octave documentation}.


@node Paths, File structure, Octave setup, Administration