Index: mttroot/mtt/doc/mtt.texi ================================================================== --- mttroot/mtt/doc/mtt.texi +++ mttroot/mtt/doc/mtt.texi @@ -14,10 +14,19 @@ @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). @@ -433,10 +442,14 @@ * 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:: @@ -660,10 +673,13 @@ * 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:: @@ -2315,10 +2331,44 @@ 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 @@ -2359,42 +2409,29 @@ @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 results may be viewed in -@uref{http://www.gnuplot.org,gnuplot} with the command +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 -The plot format is controlled by the file @emph{sys_gnuplot.txt}. A default version -of this file, which will cause gnuplot to plot the time-history of each state -and each output individually, may be created with the command - -@example -mtt rc gnuplot txt -@end example - -resulting in - -@example -wait=-1 -set data style lines -set xlabel "time" -set grid -set term X11 - -plot "rc_odes.dat2" using 1:4 axes x1y1 title "rc_c_c; -pause(wait); -plot "rc_odes.dat2" using 1:2 axes x1y1 title "rc_e2_e2 -; pause(wait); -@end example - -The file is used as an input to the gnuplot program and may therefore be -edited to contain any valid gnuplot commands. +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 @@ -3561,11 +3598,11 @@ %% 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) +@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, @@ -4540,10 +4577,19 @@ # %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% # %% 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). @@ -5814,13 +5860,16 @@ @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), , Octave, Octave +@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 @@ -5854,11 +5903,143 @@ @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 @@ -5984,17 +6165,41 @@ @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. +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}.