Index: mttroot/mtt/doc/mtt.texi ================================================================== --- mttroot/mtt/doc/mtt.texi +++ mttroot/mtt/doc/mtt.texi @@ -14,10 +14,13 @@ @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 @@ -406,10 +409,11 @@ * Steady-state solutions:: * Simulation parameters:: * Simulation input:: * Simulation logic:: * Simulation initial state:: +* Simulation code:: * Simulation output:: Steady-state solutions * Steady-state solutions - numerical(odess):: @@ -417,10 +421,12 @@ Simulation parameters * Euler integration:: * Implicit integration:: +* Runge Kutta IV integration:: +* Hybrd algebraic solver:: Simulation output * Viewing results with gnuplot:: * Exporting results to SciGraphica:: @@ -656,10 +662,11 @@ * File structure:: Octave setup * .octaverc:: +* .oct file dependencies:: Paths * $MTTPATH:: * $MTT_COMPONENTS:: @@ -1161,26 +1168,31 @@ @vtable @code @item -q quiet mode -- suppress MTT banner @item -A solve algebraic equations symbolically +@item -ae + 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 use directory @item -dc Maximise derivative (not integral) causality @item -dc Maximise derivative (not integral) causality @item -i - Use implicit or euler integration + 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 @@ -1202,11 +1214,11 @@ @item -t tidy mode (default) @item -u untidy mode (leaves files in current dir) @item -v - verbose mode + verbose mode (multiple uses increase the verbosity) @item -viewlevel View N levels of hierachy @item --version print version and exit @item --versions @@ -1856,10 +1868,12 @@ @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 @@ -1866,10 +1880,14 @@ 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 @@ -1905,10 +1923,11 @@ * 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 @@ -1987,18 +2006,24 @@ Number of Frequency steps. @item INPUT The input index for frequency response @end itemize -There are two integration algorithms +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}). @@ -2005,10 +2030,12 @@ @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 @@ -2035,11 +2062,11 @@ 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, , Euler integration, Simulation parameters +@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 @@ -2072,10 +2099,71 @@ (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 @@ -2158,11 +2246,11 @@ For example: @example bounce_ground_1_mtt_switch_logic = bounce_intf_1_mtt3<0; @end example -@node Simulation initial state, Simulation output, Simulation logic, Simulation +@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 @@ -2195,11 +2283,33 @@ @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 output, , Simulation initial state, Simulation +@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 @@ -4353,10 +4463,13 @@ # %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% # %% 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 @@ -5741,19 +5854,18 @@ @comment node-name, next, previous, up @section Octave setup @cindex Octave setup Octave is available at various web sites including: -@quotation - -@end quotation +@uref{http://www.octave.org} @menu * .octaverc:: +* .oct file dependencies:: @end menu -@node .octaverc, , Octave setup, Octave setup +@node .octaverc, .oct file dependencies, Octave setup, Octave setup @comment node-name, next, previous, up @subsection .octaverc @vindex .octaverc @@ -5765,10 +5877,26 @@ 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