@comment %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@comment  Version control history
@comment %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@comment  $Id$
@comment  $Log$
@comment  Revision 1.11  2002/08/20 15:51:17  gawthrop
@comment  Update to work with ident DIY rep
@comment
@comment  Revision 1.10  2002/07/22 10:45:22  geraint
@comment  Fixed gnuplot rep so that it correctly re-runs the simulation if input files have changed.
@comment
@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

* Introduction::                
* User interface::              
* Creating Models::             
* Simulation::                  
* Sensitivity models::          
* Representations::             
* Extending MTT::               
* Documentation::               
* Languages::                   
* Language tools::              
* Administration::              
* Glossary::                    
* Index::                       

@detailmenu

* Representation summary::      
* Defining representations::    
* Verbal description (desc)::   
* Acausal bond graph (abg)::    
* Stripped acausal bond graph (sabg)::  
* Labels (lbl)::                

* Structure (struc)::           
* Constitutive Relationship (cr)::  
* Parameters::                  
* Causal bond graph (cbg)::     
* Elementary system equations::  
* Differential-Algebraic Equations::  
* Constrained-state Equations::  

* Language fig (sabg.fig)::     
* Stripped acausal bond graph (view)::  

Labels (lbl)

* SS component labels ::        
* Other component labels::      
* Component names::             
* Component constitutive relationship::  
* Component arguments::         
* Parameter declarations::      
* Units declarations::          
* Interface Control Definition::  
* Aliases::                     
* Parameter passing::           
* Old-style labels (lbl)::      
* Language tex (desc.tex)::     

Other component labels 

* Component names::             
* Component constitutive relationship::  
* Component arguments::         
* Aliases::                     

Old-style labels (lbl)

* SS component labels (old-style)::  
* Other component labels (old-style)::  
* Parameter passing (old-style)::  

Parameter passing (old-style)

* Language tex (desc.tex)::     

Structure (struc)

* Language txt (struc.txt)::    
* Language tex (struc.tex)::    

* Report (text)::               
* Report (view)::               

Extending MTT

* Makefiles::                   
* New (DIY) representations::   
* Component library ::          

New (DIY) representations

* Makefile (DIY representations)::  
* Shell-script (DIY representations)::  
* Documentation (DIY representations)::  

Documentation

* Manual (Documentation)::      
* On-line documentation::       

On-line documentation

* Brief::                       
* Detailed::                    

Languages

* Fig::                         r
* m::                           
* Reduce::                      
* c::                           

@menu
* Representation summary::      
* Defining representations::    
* Verbal description (desc)::   
* Acausal bond graph (abg)::    
* Stripped acausal bond graph (sabg)::  
* Labels (lbl)::                

* Structure (struc)::           
* Constitutive Relationship (cr)::  
* Parameters::                  
* Causal bond graph (cbg)::     
* Elementary system equations::  
* Differential-Algebraic Equations::  
* Constrained-state Equations::  

(@pxref{Language tools}).
@vtable @code
@item system_abg.fig
        the acausal bond graph (@pxref{Acausal bond graph (abg)})
@item system_lbl.txt
        the label file (@pxref{Labels (lbl)})
@item system_desc.tex
        the description file (@pxref{Detailed})
@item system_simp.r
        algebraic simplifications to make output more readable
        (@pxref{Symbolic parameters for simplification (simp.r)})
@item system_subs.r
        algebraic substitutions to resolve, eq trig. identities
        (@pxref{Symbolic parameters (subs.r)})
@item system_simpar.txt

@comment  node-name,  next,  previous,  up
@subsection Language tex (abg.tex)
@cindex Language tex (abg.tex)

For the purpose of producing a report (@pxref{Report}), @strong{MTT}
generates a LaTeX (@pxref{LaTeX}) file describing the bond graph and its
subsystems. Additional information may be supplied using the description
representation (@pxref{Detailed}).

@c      node   next  prev  up
@node   Stripped acausal bond graph (sabg), Labels (lbl), Acausal bond graph (abg), Representations
@section Stripped acausal bond graph (sabg)
@cindex Stripped acausal bond graph (sabg)
@pindex Stripped acausal bond graph (sabg)
The stripped acausal bond graph is the acausal bond graph representation

@subsection Stripped acausal bond graph (view)
@cindex Language m (view)
@cindex view  Constrained-state Equations
This representation has the standard text view
(@pxref{Views}).


@node Labels (lbl), Structure (struc), Stripped acausal bond graph (sabg), Representations
@comment  node-name,  next,  previous,  up
@section Labels (lbl)
@cindex Labels
@cindex lbl
Bond graph components have optional labels. These provide pointers to
further information relating to the component; this avoids clutter on
the bond graph.

The label file contains the following non-blank lines (blank lines are ignored)
@itemize @bullet
@item Summary - lines beginning with #SUMMARY
@item Description - lines beginning with #DESCRIPTION
@item Alias - lines beginning with #ALIAS
@item Comments - lines beginning with # 
@item Labels - other non-blank lines
@end itemize

Note, for compatability with old versions, % may be used in place of
#; but the use of % is deprecated.
Each lable contains three fields (in the following order) separated by
white space and on one line:
@enumerate
@item The component name @pxref{Component names}. This must be a valid
name  (@pxref{Valid names}.
@item The component constitutive relationship @pxref{Component constitutive relationship}
@item The component arguments @pxref{Component arguments}

The old-style lbl files (@pxref{Old-style labels (lbl)}) are NO LONGER
supported -- you are encouraged to convert them ASAP.

@menu
* SS component labels ::        
* Other component labels::      
* Component names::             
* Component constitutive relationship::  
* Component arguments::         
* Parameter declarations::      
* Units declarations::          
* Interface Control Definition::  
* Aliases::                     
* Parameter passing::           
* Old-style labels (lbl)::      
* Language tex (desc.tex)::     
@end menu

@node SS component labels , Other component labels, Labels (lbl), Labels (lbl)
@comment  node-name,  next,  previous,  up
@subsection SS component labels 
@cindex SS component labels 
In addition to the label there are two information fields, @pxref{Labels
(lbl)}. The first must be `SS', the second contains two information
fields of the form info_field_1,info_field_2.

* Component constitutive relationship::  
* Component arguments::         
* Aliases::                     
* Parameter passing::           
* Old-style labels (lbl)::      
@end menu

@node Component names, Component constitutive relationship, Other component labels, Labels (lbl)
@comment  node-name,  next,  previous,  up
@subsection Component names
@cindex  Component names
The component name field must contain a valid name  (@pxref{Valid names} corresponding to the
name (the bit after the :) of each named component (@pxref{components})
on  the bond graph (@pxref{Acausal bond graph (abg)}).

whereas in component `turb' the first three parameters are the same but
@itemize @bullet
@item @code{$4} is replaced by effort,k_t
@end itemize



@node Old-style labels (lbl), Language tex (desc.tex), Parameter passing, Labels (lbl)
@comment  node-name,  next,  previous,  up
@subsection Old-style labels (lbl)
@cindex Old-style labels
@cindex lbl

Old syle labels (mtt version 2.x) are supported by mtt version
3.x. However, you are advised to use the new form (@pxref{Labels

%SUMMARY Pendulum example from Section 10.3 of "Metamodelling"

%Rod parameters
rod     none    l;l;j;m

@end example













@menu
* Language tex (desc.tex)::     
@end menu

@node Language tex (desc.tex),  , Old-style labels (lbl), Labels (lbl)
@comment  node-name,  next,  previous,  up
@subsection Language tex (desc.tex)
@cindex Language tex (desc.tex)
This file may contain any LaTeX compatible commands. Any mathematics
should conform to the AMSmath package.

@node Structure (struc), Constitutive Relationship (cr), Labels (lbl), Representations
@comment  node-name,  next,  previous,  up
@section Structure (struc)
@cindex Structure
@cindex struc

The causal bond graph implies a set of equations describing the
system. The Structure (struc) representation describes the structure of

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

# %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
# %% Version control history
# %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
# %% $Id$
# %% $Log$
# %% Revision 1.11  2002/08/20 15:51:17  gawthrop
# %% Update to work with ident DIY rep
# %%
# %% Revision 1.10  2002/07/22 10:45:22  geraint
# %% Fixed gnuplot rep so that it correctly re-runs the simulation if input files have changed.
# %%
# %% 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

mtt rc tf tex
mtt rc lmfr ps
@end example

The acausal bond graph (abg) (@pxref{Acausal bond graph (abg)}) with the
tex language is handled in a special way: the acausal Bond Graph  in
fig format (@pxref{Language fig (abg.fig)}), the label file (@pxref{Labels (lbl)})
the description file (@pxref{Detailed}), together with
corresponding subsystems are included in the report. It is recommended
that the first (non-comment line) in the file should be:
@example
mtt <system> abg tex
@end example
where @code{<system>} is the name of the (top-level) system.

@node Report (view),  , Report (text), Report
@subsection Language view
@cindex Report (view)
@cindex view Report
This representation has the standard text view
(@pxref{Views}).

@node Extending MTT, Documentation, Representations, Top
@comment  node-name,  next,  previous,  up
@chapter Extending MTT
@cindex Extending MTT
@cindex Make

@strong{MTT} has a number of built-in mechanisms for the user to extend
its capabilities. As @strong{MTT} is based on `Make' it is unsurprising
that some of these  involve the creation of `make files'. 

@menu
* Makefiles::                   
* New (DIY) representations::   
* Component library ::          
@end menu

@node Makefiles, New (DIY) representations, Extending MTT, Extending MTT
@comment  node-name,  next,  previous,  up
@section Makefiles
@cindex Makefiles

If a file called `Makefile' exists in the current directory,
@strong{MTT} executes it using make before doing anything else. This is
useful if one of the .txt files contains a reference to, for example, an

TwoLinkGMV_numpar.m: TwoLinkGMV_numpar.txt
        mtt -q TwoLinkGMV numpar m
@end example
All of the files in the line stating `all:' are created when
@strong{MTT} is executed (if they don't already exist).

@node New (DIY) representations, Component library , Makefiles, Extending MTT
@comment  node-name,  next,  previous,  up
@section New (DIY) representations
@cindex New representations
@cindex DIY representations

It may be convenient to create new representations for @strong{MTT}; in
particular, it is nice to be able to include the result of some
numerical or symbolic computations within an @strong{MTT} report
(@pxref{Report}). Therefore @strong{MTT} provides a mechanism for doing
this.

Future extensions of @strong{MTT} will use such representations stored
in $MTT_REP.

There are three parts to creating a DIY representation called myrep
@enumerate
@item Creating a make file in Make format called myrep_rep.make
@item Optionally creating a shell script called myrep_rep.sh
@item Optionally creating a documentation file in LaTeX format called myrep_rep.tex
@end enumerate

@menu
* Makefile (DIY representations)::  
* Shell-script (DIY representations)::  
* Documentation (DIY representations)::  
@end menu

@node Makefile (DIY representations), Shell-script (DIY representations), New (DIY) representations, New (DIY) representations
@comment  node-name,  next,  previous,  up
@subsection Makefile
@cindex New representations
@cindex DIY representations
@cindex Makefile

To create a new representation `myrep' in a language `mylang', create a
file with the name
@example
myrep_rep.make
@end example
This file must contain text in `make' syntax. It is executed by
@strong{MTT} and the two arguments `SYS' (the system name) and `LANG'
(the language) are passed to it by @strong{MTT}. Note that @strong{MTT}
cannot know of any prerequisites, but these can be explicitly included in
the makefile (which may include execution of @strong{MTT} itself.

The following example declares the new representation `ident' which is
created in conjunction with the shell-script ident_rep.sh (@pxref{Shell-script (DIY
representations)}).

@verbatim
# -*-makefile-*-

#SUMMARY 	Identification
#DESCRIPTION 	Partially know system identification using
#DESCRIPTION    using bond graphs

# Makefile for representation ident
# File ident_rep.make

#Copyright (C) 2000,2001,2002 by Peter J. Gawthrop

## Model targets
model_reps =  ${SYS}_sympar.m ${SYS}_simpar.m ${SYS}_state.m 
model_reps += ${SYS}_numpar.m ${SYS}_input.m ${SYS}_ode2odes.m  
model_reps += ${SYS}_def.m 

## Prepend s to get the sensitivity targets
sensitivity_reps = ${model_reps:%=s%}

## Model prerequisites
model_pre =  ${SYS}_abg.fig ${SYS}_lbl.txt 
model_pre += ${SYS}_rdae.r ${SYS}_numpar.txt

## Prepend s to get the sensitivity targets
sensitivity_pre = ${model_pre:%=s%}


## Simulation targets
sims = ${SYS}_sim.m s${SYS}_ssim.m

## m-files needed for ident
ident_m = ${SYS}_ident.m ${SYS}_ident_numpar.m 

## Targets for the ident simulation
ident_reps = ${ident_m} ${sims} ${model_reps} ${sensitivity_reps}

## ps output files etc
psfiles = ${SYS}_ident.ps ${SYS}_ident.comparison.ps
figfiles = ${psfiles:%.ps=%.fig}
gdatfiles = ${psfiles:%.ps=%.gdat}
datfiles = ${psfiles:%.ps=%.dat2}

## LaTeX files etc
latexfiles = ${SYS}_ident_par.tex

all: ${SYS}_ident.${LANG}

echo:
	echo "sims: ${sims}"
	echo "model_reps: ${model_reps}"
	echo "sensitivity_reps: ${sensitivity_reps}"
	echo "ident_reps: ${ident_reps}"

${SYS}_ident.view: ${psfiles}
	ident_rep.sh ${SYS} view

${psfiles}: ${figfiles}
	ident_rep.sh ${SYS} ps

${figfiles}: ${gdatfiles}
	ident_rep.sh ${SYS} fig

${gdatfiles}: ${datfiles}
	ident_rep.sh ${SYS} gdat

${datfiles} ${latexfiles}: ${ident_reps}
	ident_rep.sh ${SYS} dat2

${SYS}_ident.m: 
	ident_rep.sh ${SYS} m

${SYS}_ident_numpar.m:
	ident_rep.sh ${SYS} numpar.m

## System model reps
## Generic txt files 
${SYS}_%.txt:
	mtt ${OPTS} -q -stdin ${SYS} $* txt

## Specific m files
${SYS}_ode2odes.m: ${model_pre}
	mtt -q -stdin ${OPTS} ${SYS} ode2odes m

${SYS}_sim.m: ${SYS}_ode2odes.m
	mtt ${OPTS} -q -stdin ${SYS} sim m

## Numpar files
${SYS}_numpar.m:
	mtt ${SYS} numpar m

## Sympar files
${SYS}_sympar.m:
	mtt ${SYS} sympar m

## Generic txt to m
${SYS}_%.m: ${SYS}_%.txt
	mtt ${OPTS} -q -stdin ${SYS} $* m

## r files
${SYS}_def.r: ${SYS}_abg.fig
	mtt ${OPTS} -q -stdin ${SYS} def r

${SYS}_rdae.r: 
	mtt ${OPTS} -q -stdin ${SYS} rdae r

## Sensitivity model reps
## Generic txt files 
s${SYS}_%.txt:
	mtt ${OPTS} -q -stdin -s s${SYS} $* txt

## Specific m files
## Numpar files
s${SYS}_numpar.m:
	mtt -s s${SYS} numpar m

## Sympar files
s${SYS}_sympar.m:
	mtt -s s${SYS} sympar m

s${SYS}_ode2odes.m: ${sensitivity_pre}
	mtt -q -stdin ${OPTS} -s s${SYS} ode2odes m

s${SYS}_ssim.m:
	mtt -q -stdin ${OPTS} -s s${SYS} ssim m

s${SYS}_def.m:
	mtt -q -stdin ${OPTS} -s s${SYS} def m


## Generic txt to m
s${SYS}_%.m: s${SYS}_%.txt
	mtt ${OPTS} -q -stdin s${SYS} $* m

## r files
s${SYS}_rdae.r: 
	mtt ${OPTS} -q -stdin -s s${SYS} rdae r

@end verbatim

@node Shell-script (DIY representations), Documentation (DIY representations), Makefile (DIY representations), New (DIY) representations
@comment  node-name,  next,  previous,  up
@subsection Shell-script
@cindex New representations
@cindex DIY representations
@cindex Shell-script

For more complex DIY representations, it is convenient to define new
commands to be used by the Makefile (@pxref{Makefile (DIY
representations)}).

The following example shows this in the context of the DIY
representation `ident' used as an example in the previous section
(@pxref{Makefile (DIY representations)}).


@node Documentation (DIY representations),  , Shell-script (DIY representations), New (DIY) representations
@comment  node-name,  next,  previous,  up
@subsection Documentation
@cindex New representations
@cindex DIY representations
@cindex Documentation


@node Component library ,  , New (DIY) representations, Extending MTT
@comment  node-name,  next,  previous,  up
@section Component library
@cindex Component library
@cindex component
@cindex Component library

If @strong{MTT} does not recognise a component (eg named MyComponent) as
a simple component (@pxref{Simple components}) or as already existing,
it searches the library search path $MTT_COMPONENTS
(@pxref{$MTT_COMPONENTS}) for a directory called MyComponent containing
MyComponent_lbl.txt. It then copies the @emph{entire} directory into the
current working directory. Thus, for example, the directory could
contain MyComponent_desc.tex MyComponent_abg.fig MyComponent_lbl.txt and MyComponent_cr.r in
addition to MyComponent_lbl.txt.

@c      node   next  prev  up
@node   Documentation, Languages, Extending MTT, Top
@chapter Documentation
@cindex Documentation

@menu
* Manual (Documentation)::      
* On-line documentation::       
@end menu

@node   Manual (Documentation), On-line documentation, Documentation, Documentation
@section Manual
@cindex Manual

MTT is documented in this manual. The manual can be invoked in various
ways:

@vtable @code
@item mtt manual
      Brings up a pdf version of the manual
@item mtt info
      Brings up an xterm containing an info version of the manual
@item mtt hinfo
      Brings up an html browser containing the manual
@item emacs
      type ^h^i followed by mmtt in the command window
@item browser
      point browser to mtt.sf.netb
@end vtable

@node On-line documentation,  , Manual (Documentation), Documentation
@section On-line documentation
@cindex Components 
@cindex Examples
@cindex Documentation
@cindex On-line documentation

@strong{MTT} components, constitutive relations, examples and representations in libraries
(@pxref{Component library}) are documented in two ways:

@enumerate 
@item brief 
@item verbose
@end enumerate

@menu
* Brief::                       
* Detailed::                    
@end menu

@node Brief, Detailed, On-line documentation, On-line documentation
@subsection Brief on-line documentation
@cindex Brief documentation

Documentation of DIY components, examples, constitutive relationships
and representations is provides by the programmer by inserting code of
the form

@example
#SUMMARY     One line summary
#DESCRIPTION Multi-line
#DESCRIPTION More detailed description
@end example

within the appropriate file (usually at or near the top):
@vtable @code
@item components
      _lbl.txt (@pxref{Labels (lbl)})
@item examples
      _lbl.txt (@pxref{Labels (lbl)})
@item constitutive relations
      _cr.r (@pxref{DIY constitutive relationships})
@item representations
      _rep.make (@pxref{Makefile (DIY representations)})
@end vtable

This documentation is accessed by the user in various ways
@vtable @code
@item mtt help name
      prints basic information on the screen
@item mtt system lbl view
      gives formatted information about the component or example
@item Including mtt system abg tex in the _rep.txt file
      gives formatted information about the component or example
      within the report
@end vtable

@node Detailed,  , Brief, On-line documentation
@subsection Detailed on-line documentation
@cindex Detailed documentation
@cindex Description
@cindex desc

DIY components, examples, constitutive relationships can be described
textually in LaTeX (.tex) description file; this is the only language
for this representation. This representation is used by the LaTeX
language version (@pxref{Language tex (abg.tex)}) of the acausal bond
graph representation (@pxref{Acausal bond graph (abg)}).

The file may contain any  LaTeX commands
valis for the ``article'' document type but must @strong{not} contain:
@itemize @bullet
@item documentclass commands
@item document environments
@end itemize

@c      node   next  prev  up
@node   Languages, Language tools, Documentation, Top
@chapter Languages
@cindex Languages
@pindex Languages


@c      node   next  prev  up
@menu