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.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 @@ -436,10 +439,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:: @@ -663,10 +670,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:: @@ -2318,10 +2328,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 @@ -3551,11 +3595,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, @@ -4530,10 +4574,13 @@ # %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% # %% Version control history # %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% # %% $Id$ # %% $Log$ +# %% 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 @@ -5807,13 +5854,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 @@ -5847,11 +5897,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 @@ -5977,17 +6159,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}.