@comment %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@comment  Version control history
@comment %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@comment  $Id$
@comment  $Log$
@comment  Revision 1.3  2001/07/13 03:02:38  geraint
@comment  Added notes on #ICD, gnuplot.txt and odes.sg rep.
@comment
@comment  Revision 1.2  2001/07/03 22:59:10  gawthrop
@comment  Fixed problems with argument passing for CRs
@comment
@comment  Revision 1.1  2001/06/04 08:18:52  gawthrop
@comment  Putting documentation under CVS
@comment
@comment  Revision 1.66  2000/12/05 14:20:55  peterg

Simulation

* Steady-state solutions::      
* Simulation parameters::       
* Simulation input::            
* Simulation logic::            
* Simulation initial state::    
* Simulation code::             
* Simulation output::           

Steady-state solutions 

* Steady-state solutions - numerical(odess)::  
* Steady-state solutions - symbolic (ss)::  

Simulation parameters

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

Simulation output

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

Representations

* Octave setup::                
* Paths::                       
* File structure::              

Octave setup

* .octaverc::                   
* .oct file dependencies::      

Paths

* $MTTPATH::                    
* $MTT_COMPONENTS::             
* $MTT_CRS::                    
* $MTT_EXAMPLES::               

The available options are:
@vtable @code
@item -q
        quiet mode -- suppress MTT banner
@item -A 
        solve algebraic equations symbolically
@item -ae 
        <hybrd> solve algebraic equations numerically
 (this option requires -cc or -oct)
@item -D 
        debug -- leave log files etc
@item -I 
        prints more information
@item -abg 
       start at abg.m representation
@item -c 
        c-code generation
@item -cc
       C++ code generation
@item -d 
        <dir>  use directory <dir>
@item -dc 
       Maximise derivative (not integral) causality
@item -dc 
       Maximise derivative (not integral) causality
@item -i 
       <implicit|euler|rk4>   Use implicit, euler or Runge Kutta IVintegration
@item -o 
       ode is same as dae
@item -oct 
       use oct files in place of m files where appropriate
@item -opt 
       optimise code generation
@item -p 

@item -sub 
       <subsystem> operate on this subsystem
@item -t 
        tidy mode (default)
@item -u 
        untidy mode (leaves files in current dir)
@item -v 
        verbose mode (multiple uses increase the verbosity)
@item -viewlevel 
       <N> View N levels of hierachy
@item --version 
       print version and exit
@item --versions 
       print version of mtt and components and exit
@end vtable

representations for the purposes of numerical simulation:
@ftable @code
@item m
        @code{octave} a high-level interactive language for numerical
        computation.
@item c
        @code{gcc} a c compiler.
@item cc
        @code{g++} a C++ front-end to gcc.
@end ftable

There are a number solution algorithms available:
@itemize @bullet
@item
explicit solution via the matrix exponential
@item
backward Euler integration (explicit)
@item
forward Euler integration (implicit)
@item
Runge Kutta IV integration (explicit, fixed step)
@item
Hybrd algebraic solver (MINPACK, Octave fsolve)
@c  @item
@c  LSODE (Hindmarsh's ODE solver as implemented in Octave)
@c  @item
@c  DASSL (Petzold's DAE solver as implemented in Octave) (Unavailable just now)
@end itemize

 However, all combinations of representation, language and solution

``simulated''(@pxref{Steady-state solutions}).
@menu
* Steady-state solutions::      
* Simulation parameters::       
* Simulation input::            
* Simulation logic::            
* Simulation initial state::    
* Simulation code::             
* Simulation output::           
@end menu

@node Steady-state solutions, Simulation parameters, Simulation, Simulation
@comment  node-name,  next,  previous,  up
@section Steady-state solutions 
@cindex Steady-state solutions

        Maximum frequency = 10^WMAX
@item WSTEPS
        Number of Frequency steps.
@item INPUT
        The input index for frequency response
@end itemize

There are a number of solution algorithms
@itemize @bullet
@item Euler
        basic Euler integration (@pxref{Euler integration}). This method
is simple, but not recommended for stiff systems.
@item Implicit
        semi-implicit integration  (@pxref{Implicit integration}) - uses the smx representation to give
        stability.
@item Runge Kutta IV
        fixed step Runge Kutta fourth order integration (@pxref{Runge Kutta IV integration}).
@item Hybrd
        numerical algebraic equation solver
        

@c @item ImplicitS
@c         Sparse semi-implicit integration  (@pxref{Sparse implicit integration})
@c -- takes advantage of the sparsity of the A matrix.
@c @item LSODE
@c         the variable step-size method that comes with Octave (@pxref{Octave}).
@end itemize

@menu
* Euler integration::           
* Implicit integration::        
* Runge Kutta IV integration::  
* Hybrd algebraic solver::      
@end menu

@node Euler integration, Implicit integration, Simulation parameters, Simulation parameters
@comment  node-name,  next,  previous,  up
@subsection Euler integration
@cindex Euler integration
Euler integration approximates the solution of the Ordinary Differential Equation 

where A is the nxn matrix appearing in
@example
f(x,u) = Ax + Bu
@end example
If the system is non linear, the linearised system matrix A should act
as a guide to the choice of STEPFACTOR.

@node Implicit integration, Runge Kutta IV integration, Euler integration, Simulation parameters
@comment  node-name,  next,  previous,  up
@subsection Implicit integration
@cindex Implicit integration
Implicit integration approximates the solution of the Ordinary Differential Equation 
@example
dx/dt = f(x,u)
@end example

given by:
@example
(E(x)-A*DT)x := (E(x)-A*DT)x + f(x,u)DT
@end example
which reduces to the ordinary differential equation case when E(x)=I.

The _smx representation includes the E matrix.

@node Runge Kutta IV integration, Hybrd algebraic solver, Implicit integration, Simulation parameters
@comment  node-name,  next,  previous,  up
@subsection Runge Kutta IV integration
Runge Kutta IV approximates the solution of the Ordinary Differential Equation

@example
dx/dt = f(x,t)
@end example

by

@example
x := x + (DT/6)*(k1 + 2*k2 + 2*k3 + k4)
@end example

where

@example
k1 := f(x,t)
k2 := f(x+(1/2)*k1,t+(1/2)*DT)
k3 := f(x+(1/2)*k2,t+(1/2)*DT)
k4 := f(x+k3,t+DT)
@end example

The @strong{MTT} implementation of Runge-Kutta integration
is a fourth order, fixed-step, explicit integration method.

For some systems of equations, the increased accuracy of using a fourth order
method can allow larger step-lengths to be used than would allowed by the
 lower order Euler integration method.

It should be noted that during the interemediate calculations (k1...k4),
 the input vector @code{u} is not advanced w.r.t. time; the system inputs are
assumed to be constant over the period of the integration step-length.

@node Hybrd algebraic solver,  , Runge Kutta IV integration, Simulation parameters
@comment  node-name,  next,  previous,  up
@subsection Hybrd algebraic solver

The hybrd algebraic solver of @uref{http://www.netlib.org/minpack/hybrd.f,MINPACK},
which is used by Octave in the @code{fsolve} routine, may be used in conjunction
with one of the other integration methods to solve semi-explicit, index 1, differential
algebraic equations; these may be generated in @strong{MTT} models by use of 
@code{unknown} SS Components @pxref{SS component labels}.

This method requires that compiled simulation code is used; either -cc or -oct.
To perform a simulation based on a model @code{sys},

@example
mtt -cc -ae hybrd -i euler sys odeso view
@c XXX: should be daeso view?
@end example

@strong{MTT} will attempt to minimise the residual error at each integration time-step
using the hybrd routine.

This method of simulation is particularly well suited to stiff systems where very fast
dynamics are of little interest. Care must be taken to ensure that an acceptable level
of convergence is achieved by the solver for the system under investigation.
@c XXX: tolerance option

@c @node Sparse implicit integration,  , Implicit integration, Simulation parameters
@c @comment  node-name,  next,  previous,  up
@c @subsection Sparse implicit integration
@c @cindex Sparse implicit integration
@c This is an experimental approach for large (N>50) systems.

(defined by t) and parameters

For example:
@example
bounce_ground_1_mtt_switch_logic	= bounce_intf_1_mtt3<0;
@end example

@node Simulation initial state, Simulation code, Simulation logic, Simulation
@comment  node-name,  next,  previous,  up
@section Simulation initial state
@cindex Simulation initial state
This is defined in the system_state.txt file. A default file is created
automatically by @strong{MTT}. This is done explicitly by
@example
mtt system state txt

@c  @item
@c  The -ss switch is not present: the states default to zero
@c  @item
@c  The -ss switch is present: the states default to those set in the
@c  sspar.r file.
@c  @end itemize

@node Simulation code, Simulation output, Simulation initial state, Simulation
@comment  node-name,  next,  previous,  up
@section Simulation code
simulation code can be generated by @strong{MTT} in the form
of the @code{ode2odes} transformation. This can be produced in a number
of languages, including .m, .oct, C and C++ @pxref{Languages}.

To generate simulation code in C:
@example
mtt -c [options] sys ode2odes c
@end example

Similarly, to generate C++ code:
@example
mtt -cc [options] sys ode2odes cc
@end example

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

@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.

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

# %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
# %% Version control history
# %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
# %% $Id$
# %% $Log$
# %% Revision 1.3  2001/07/13 03:02:38  geraint
# %% Added notes on #ICD, gnuplot.txt and odes.sg rep.
# %%
# %% Revision 1.2  2001/07/03 22:59:10  gawthrop
# %% Fixed problems with argument passing for CRs
# %%
# %% Revision 1.1  2001/06/04 08:18:52  gawthrop
# %% Putting documentation under CVS
# %%
# %% Revision 1.66  2000/12/05 14:20:55  peterg

@node Octave setup, Paths, REDUCE setup, Administration
@comment  node-name,  next,  previous,  up
@section Octave setup
@cindex  Octave setup

Octave is available at various web sites including:

@uref{http://www.octave.org}


@menu
* .octaverc::                   
* .oct file dependencies::      
@end menu

@node .octaverc, .oct file dependencies, Octave setup, Octave setup
@comment  node-name,  next,  previous,  up
@subsection .octaverc
@vindex  .octaverc


The @file{.octaverc} file should contain the following lines:
@example
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Startup file for Octave for use with MTT
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

implicit_str_to_num_ok = 1;
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 library @code{liboctave}
and the Octave modified version of @code{libkpathsea} 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}.

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
@comment  node-name,  next,  previous,  up
@section Paths
@cindex paths
@cindex mttrc