MTT: Model Transformation Tools

It implements two features not discussed in that book:

• bicausal bond graphs and
• hierarchical bond graphs.

1. Introduction

MTT is a set of Model Transformation Tools based on bond graphs. MTT implements the theory to be found in the book "Metamodelling: Bond Graphs and Dynamic Systems" by Peter Gawthrop and Lorcan Smith published by Prentice Hall in 1996 (ISBN 0-13-489824-9).

It implements two features not discussed in that book:

• bicausal bond graphs and
• hierarchical bond graphs.

In the context of software, it has been said that one good tool is worth many packages. UNIX is a good example of this philosophy: the user can put together applications from a range of ready made tools. This manual describes the application of this philosophy to dynamic system modeling embodied in MTT - a set of Model Transformation Tools each of which implements a single transformation between system representations.

System representations have two attributes.

• A Form: e.g. acausal bond graph, differential algebraic, linear state-space etc.
• A Language: e.g. Fig, Matlab, LaTeX, Reduce, postscript etc.

Transformations in MTT are accomplished using appropriate software (e.g. Octave/Matlab, Reduce) encapsulated in UNIX Bourne shell scripts. The relationships between the tools are encoded in a Make File; thus the user can specify a final representation and all the necessary intermediate transformations are automatically generated.

1.1 What is a representation?

Physical systems have many representations. These include

• a schematic diagram,
• a block diagram,
• a bunch of equations,
• a single differential(-algebraic) equation,
• simulation code,
• linearised state-space (or descriptor) equations,
• transfer function (of the linearised system),
• frequency response (of the linearised system),
• etc...

Each of these representations is related to other representations by an appropriate transformation (see section 1.2 What is a transformation?. In many cases, a modeler is presented with a physical system and needs to make a model. In particular, a model, in this context, is a representation of the system appropriate to a particular use, for example:

• simulation,
• control system design,
• optimisation
• etc.

Indeed, for a given physical system, the modeler would need to derive a number of models. This process can be viewed as a series of steps; each involving a transformation between representations (see section 1.2 What is a transformation?.

In this context, the following considerations are relevant.

• There is a unique `core' representation of any system. There are many routes from this core representation, each leading to an appropriate model. There are many possible routes to this core representation from the physical system: the route chosen is a matter of convenience.
• Because the core representation is unique, it is easy to expand the tool-box to include additional transformations from the physical system to the core representation and additional transformations from the core representation to the mode.
• Transformation_1 probably cannot, and certainly should not, be completely automated. Engineering insight, knowledge and experience is essential to capture the essence (with respect to the particular use) of the physical system whilst discarding irrelevant form.
• Representation_1 should be `close' in some sense to the Physical system.
• The core representation, and hence the representations leading to it, must contain enough information to generate all of the required models.
• Representations must be easily extensible: it must be possible to add extra components or attributes without restructuring the representation.

I happen to believe that Bond graphs (see section 1.3 What is a bond graph?) provide the most convenient and powerful basis for the core representation.

1.2 What is a transformation?

Each system representation (see section 1.1 What is a representation? is related to other representations by an appropriate transformation as follows:

• Physical system
• Transformation_1 ---> Representation_1
• Transformation_2 ---> Representation_2
• ...
• Transformation_N ---> Core representation
• Transformation_N+1 ---> Representation_N+1
• Transformation_N+2 ---> Representation_N+2
• ...
• Transformation_N+M ---> Model

1.3 What is a bond graph?

Bond graphs provide a graphical high-level language for describing dynamic systems in a precise and unambiguous fashion. They make a clear distinction between structure (how components are connected together), and behavior (the particular constitutive relationships, or physical laws, describing each component.

They can describe a range of physical systems including:

• Electrical systems
• Mechanical systems
• Hydraulic systems
• Chemical process systems

More importantly, they can describe systems which contain subsystems drawn from all of these domains in a uniform manner.

Bond graphs are made up of components (see section 1.6 Components) connected by bonds (see section 1.5 Bonds) which define the relationship between variables (see section 1.4 Variables).

1.4 Variables

• effort variables
• flow variables
• integrated effort variables
• integrated flow variables

Examples of effort variables are

• voltage
• pressure
• force
• torque
• temperature

Examples of flow variables are

• current
• volumetric flow rate
• velocity
• angular velocity
• heat flow

Examples of integrated flow variables are

• charge
• volume
• momentum
• angular momentum
• heat

1.5 Bonds

• an effort (see section 1.4 Variables) variable and
• a flow (see section 1.4 Variables) variable.

• a half-arrow,
• a causal stroke and
• a causal half-stroke.

The half-arrow indicates two things:

• the direction of power (or pseudo power) flow and
• the side of the bond associated with the flow variable.

The causal stroke indicates two things:

• the effort variable is imposed at the same end as the stroke and
• the flow variable is imposed at the opposite end to the stroke.

The causal half-stoke indicates one thing:

• if it is on the effort side of the bond, the effort variable is imposed at the same end as the stroke or
• if it is on the flow side of the bond, the flow variable is imposed at the opposite end to the stroke.

1.6 Components

Components provide the building blocks of a dynamic system when connected by bonds (see section 6.4.1.2 Bonds). Components have the following attributes:

ports

provide the connections to other components (see section 1.6.1 Ports)

constitutive relationships

define how the port-variables are related (see section 1.6.2 Constitutive relationship)

1.6.1 Ports

Ports are implemented in MTT using named SS components. (see section 6.4.1.9 Named SS components).

The direction of the named SS components. (see section 6.4.1.9 Named SS components) is coerced (see section 6.4.1.10 Coerced bond direction) to have the same direction as the bons connected to the corresponding port. Thus the direction of the direction of the named SS components has no significance unless the component is at the top level.

1.6.2 Constitutive relationship

The constitutive relationship of a component defines how the port variables are related. This relationship may be linear or non-linear. This typically contains symbolic parameters (see section 1.6.3 Symbolic parameters) which may be replaced, for the purposes of numerical analysis by numeric parameters (see section 1.6.4 Numeric parameters).

1.6.3 Symbolic parameters

However, MTT allows replacement of symbolic parameters by numeric parameters (see section 1.6.4 Numeric parameters) when appropriate.

1.6.4 Numeric parameters

1.7 Algebraic loops

In particular if zero junction is undercausal an SS:loop component (with effort output indicated by a causal stroke) with the following label file entry:

  loop SS unknown,zero

For more information, refer to: "Metamodelling: Bond Graphs and Dynamic Systems" by Peter Gawthrop and Lorcan Smith published by Prentice Hall in 1996 (ISBN 0-13-489824-9).

1.8 Switched systems

Some systems contain switch-like components. For example an electrical system may contain on-off switches and diodes and a hydraulic system may shut-off valves and non-return valves.

Such systems are sometimes called hybrid systems. The modelling an simulation of such systems is the subject of current research. MTT implements a simple pragmatic approach to the modelling and simulation of such systems via two new Bond Graph components:

ISW

a switched I component

CSW

a switched C component

These switches are user controlled through the logic representation (see section 4.4 Simulation logic).

2. User interface

2.1 Menu-driven interface

xmtt

2.2 Command line interface

mtt [options] <system_name> <representation> <language>

[options]

the (optional) option switches (see section 2.3 Options)

<system_name>

the name of the system being transformed

<representation>

the mnemonic for the system representation (see section 6.1 Representation summary)

<language>

the mnemonic for language for the representation (see section 9. Languages)

mtt rc rep view

mtt rc sm m

2.3 Options

MTT has a number of optional switches to control its operation. These are invoked immediately after `mtt' on the command line; for example:

mtt -o -ss -cc syst cbg view

If you wish to use an option all the time, use the alias function appropriate to the shell you are using. For example, using bash:

alias mtt='mtt -o -ss -cc'

mtt syst cbg view

The available options are:

-q

quiet mode -- suppress MTT banner

-A

solve algebraic equations symbolically

-ae

<hybrd> solve algebraic equations numerically (this option requires -cc or -oct)

-D

debug -- leave log files etc

-I

prints more information

-abg

start at abg.m representation

-c

c-code generation

-cc

C++ code generation

-d

<dir> use directory <dir>

-dc

Maximise derivative (not integral) causality

-dc

Maximise derivative (not integral) causality

-i

<implicit|euler|rk4> Use implicit, euler or Runge Kutta IVintegration

-o

ode is same as dae

-oct

use oct files in place of m files where appropriate

-opt

optimise code generation

-p

print environment variables

-partition

partition hierachical system

-r

reset time stamp on representation

-s

try to generate sensitivity BG (experimental)

-ss

use steady-state info to initialise simulations

-stdin

read input data from standard input for simulations

-sub

<subsystem> operate on this subsystem

-t

tidy mode (default)

-u

untidy mode (leaves files in current dir)

-v

verbose mode (multiple uses increase the verbosity)

-viewlevel

<N> View N levels of hierachy

--version

print version and exit

--versions

print version of mtt and components and exit

2.4 Utilities

mtt help

Lists the help/browser commands

mtt copy <system>

Copies the system (ie directory and enclosed files) to the current working directory.

mtt rename <old_name> <new_name>

Renames all of the defining representations (see section 6.2 Defining representations) and textually changes each file appropriately.

mtt <system> clean

Remove all files generated by MTT associated with system `system'.

mtt clean

Remove all files generated by MTT associated with all systems within the current directory.

mtt system representation vc

Apply version control to representation `representation' of system `system'.

mtt system vc

Apply version control to all representations (under version control) system `system'.

2.4.1 Help

       mtt help representations
       mtt help components
       mtt help examples
       mtt help crs
       mtt help representations <match_string>
       mtt help components <match_string>
       mtt help examples  <match_string>
       mtt help crs <match_string>
       mtt help <component_or_example_or_CR_name>

2.4.1.1 help representations

The command

mtt help representations

The command

mtt help representations <match_string>

mtt help representations descriptor

2.4.1.2 help components

The command

mtt help components

The command

mtt help components <match_string>

mtt help components source

2.4.1.3 help examples

This command provides a good way to get started in MTT. having found an interesting example, copy it to your working directory using

mtt copy <example_name>

mtt help examples

The command

mtt help examples <match_string>

mtt help examples pharmokinetic

2.4.1.4 help crs

The command

mtt help crs

The command

mtt help crs <match_string>

mtt help crs sin

2.4.1.5 help <name>

The command

mtt help <name>

2.4.2 Copy

MTT provides a way of copying examples to your working directory:

mtt copy <example_name>

Use the command

mtt help examples

Note that components and constitutive relationships are automatically copied when required.

2.4.3 Clean

1. mtt system clean
2. mtt clean

The files which remain after such a clean are the Defining representations (see section 6.2 Defining representations).

2.4.4 Version control

When you are working on a modeling project, it is easy to forget what changes you made to a system and why you made them. Sometimes, you may regret some changes and wish to revert to an earlier version: even if you use .old files this may be difficult to achieve safely.

These are very similar problems to those faced by software developers and can be solved in the same way: using version control.MTT provides version control using the standard GNU Revision Control System (RCS). This is hidden from the user, but is fully complementary to direct use of RCS (e.g. via emacs vc commands) to the more experienced user who wishes to do so.

The only files that you should ever change (i.e. the ones never overwritten by MTT) are the Defining representations (see section 6.2 Defining representations).

All of the files, with the exception of system_abg.fig, are initially created by MTT and contain the RCS header for version control.

The MTT version control will automatically expand this part of the text to include all change comments that you give it -- so will direct use of RCS (e.g. via emacs vc commands)

The MTT version commands are as follows:

mtt system representation vc

Apply version control to representation `representation' of system `system'.

mtt system vc

Apply version control to all representations (under version control) system `system'.

The first is appropriate after you have made a revision to a single file. It will prompt you for a change comment; this will be automatically included in the file header. In addition, enough information will be saved to enable any version to be retrieved via RCS.

The second is appropriate to record the state of the entire model. This assumes that all relevant files have been recorded by the first version of the command. Once again, old versions of the entire model can be retrieved using the relevant RCS commands.

A subdirectory `RCS' is created to hold this information. You need not bother about the contents, except that you must not delete any files within `RCS'.

3. Creating Models

MTT helps you to analyse and transform system models -- ultimately the process of capturing the real world in a model is up to you. This chapter discusses the MTT aspects of creating a model. For convenience, this is divided into creating simple models and creating complex models.

3.1 Quick start

It is probably worth a quick skim though MTT to get a flavour of what it can do before plunging into the detail of the rest of this document. Here is a series of commands to do this.

Copy an initial set of files describing the bond graph.

mtt copy rc

cd rc

mtt rc abg view

mtt rc cbg view

mtt rc ode view

mtt rc sro view

An alternative (but more general) way of achieving the same result is

mtt -c rc odeso view

View the system transfer function

mtt rc tf view

mtt rc lmfr view

View the log modulus frequency response of the system for 100 logarithmically spaced frequencies in the range 0.1 to 10 radians per second.

mtt rc lmfr view 'W=logspace(-1,1,100);'

MTT has a report generation ((see section 6.16 Report (rep)) facility which can generate a hypertext description of the system.

mtt rc rep hview

The report contents are specified by the rep representation (see section 6.16 Report (rep)), in this case the corresponding file is:

% %% Outline report file for system rc (rc_rep.txt)

mtt rc abg tex
mtt rc struc tex
mtt rc cbg ps
mtt rc ode tex
mtt rc ode dvi
mtt rc sm tex
mtt rc tf tex
mtt rc tf dvi
mtt rc sro ps
mtt rc lmfr ps
mtt rc odes h
mtt rc numpar txt
mtt rc input txt
mtt -c rc odeso ps
mtt rc rep txt

mtt rc rep view

Now have a go at modifying the bond graph.

mtt rc abg fig

More examples can be found using

mtt help examples

mtt help <example_name>

mtt copy <example_name>

Lots of examples are available.

mtt help examples

mtt copy <name>

A number of examples are to be found <A HREF="http://www.mech.gla.ac.uk/~peterg/software/MTT/examples/Examples/Examples.html"> here</A>.

3.2 Creating simple models

For then purposes of this section, simple models are those which are built up from bond graphs involving predefined components. In contrast, more complex systems (see section 3.3 Creating complex models) need to be built up hierarchically.

The recommended sequence of steps to create a simple model is:

1. Decide on a name for the system; let us call it `syst' for the purposes of this discussion.
2. Invoke the Bond Graph editor to draw the acausal Bond Graph.

   mtt syst abg fig

3. Draw the Bond Graph (see section 6.4.1 Language fig (abg.fig)), including the bonds (see section 1.5 Bonds), the components (see section 1.6 Components) and any artwork (see section 6.4.1.15 Artwork) to make the Bond Graph more readable. The graphical editor xfig is (see section 10.2 Xfig) is self-explanatory. The icon library is helpful here (see see section 6.4.1.1 Icon library).
4. Add causal strokes (see section 6.4.1.3 Strokes) where needed to define causality. As a general rule, use the minimum number of strokes needed to define the problem; this will often be only on the SS components. (see section 6.4.1.6 SS components). Save the bond graph.
5. View the corresponding causal bond graph.

   mtt syst cbg view

   1. At this stage, MTT will warn you that the labeled components do not appear in the label file - this can safely be ignored.
   2. MTT will indicate the percentage of components which are causally complete -- ideally this will be 100\%. Components which are not causally complete will be listed.
   3. A view of the causal bond graph will be created. The added causal strokes are indicated in blue, undercausal components in green and overcausal components in red.
   4. If the bond graph is causally complete, proceed to the next step, otherwise think hard and return to the first step.
6. At this stage, no constitutive relationships have been defined. Nevertheless, MTT will proceed in a semi-qualitative fashion by assuming that all constitutive relationships are unity (and therefore linear). It may be useful at this stage to view various derived representations to check the overall model properties before proceeding further. For example:
   1. View the system Differential-algebraic equations

      mtt syst dae view

   2. View the system state matrices

      mtt syst sm view

   3. View the system transfer function

      mtt syst tf view

   4. View the system step response

      mtt syst sro view

7. As well as creating the causal bond graph, MTT has also generated templates for other text files (see section 6.2 Defining representations) used to further specify the system. These can now be edited using your favorite text editor (see section 10.3 Text editors).
8. MTT will now generate the representations (see section 6.1 Representation summary)that you desire. For example the system can be simulated by

   mtt syst odeso view

   MTT will complain if a component is named in the bond graph but not in the label file and vice versa. This mainly to catch typing errors.

3.3 Creating complex models

Complex models -- in distinction to simple models (see section 3.2 Creating simple models) -- have a hierarchical structure. In particular, bond graph components can be created by specifying their bond graph. Typically, such components will have more than one port (see section 1.6.1 Ports); within each component, ports are represented by named SS components (see section 6.4.1.9 Named SS components); outwith each component, ports are unambiguously identified by labels (see section 6.4.1.11 Port labels) and vector labels (see section 6.4.1.12 Vector port labels).

Complex models are thus created by conceptually decomposing the system into simple subsystems, and then creating the corresponding bond graphs. The procedure for simple systems (see section 3.2 Creating simple models) is then followed using the top level system (see section 3.3.1 Top level); MTT then recursively operates on the lower level systems.

The report representation (see section 6.16 Report (rep)) provides a convenient way of viewing a complex system.

An example of such a system can be created as follows:

mtt copy twolink
mtt twolink rep hview

The result is <A HREF="./examples/twolink/twolink_rep/twolink_rep.html"> here</A>.

3.3.1 Top level

• its name is used in the mtt command as the system name.
• all named SS componenents (see section 6.4.1.9 Named SS components) are treated as ordinary SS components (see section 6.4.1.6 SS components).

4. Simulation

Simulation is typically performed using an appropriate simulation language (which is often inappropriately conflated with modelling tools). MTT provides a number of alternative routes to simulation based on the following representations (see section 6. Representations):

cse

constrained-state differential equation form

ode

ordinary differential (or state-space) equations

Special cases of numerical simulation, appropriate to linear systems, are:

ir

impulse response - state

iro

impulse response - output

sr

impulse response - state

sro

impulse response - output

There are a number of languages (see section 9. Languages) which can be used to describe these representations for the purposes of numerical simulation:

m

octave a high-level interactive language for numerical computation.

c

gcc a c compiler.

cc

g++ a C++ front-end to gcc.

There are a number solution algorithms available:

• explicit solution via the matrix exponential
• backward Euler integration (explicit)
• forward Euler integration (implicit)
• Runge Kutta IV integration (explicit, fixed step)
• Hybrd algebraic solver (MINPACK, Octave fsolve)

However, all combinations of representation, language and solution method are not supported by MTT at the moment. Given a system `system', some recommended commands are:

mtt system iro view

creates the impulse response of a linear system via the system_sm.m representation using explicit solution via the matrix exponential.

mtt system sro view

creates the step response of a linear system via the system_sm.m representation using explicit solution via the matrix exponential.

mtt -c system odeso view

creates the response of a nonlinear system via the system_ode.c representation using implicit integration.

mtt -c -i euler system odeso view

creates the response of a nonlinear system via the system_ode.c representation using euler integration.

Simulation parameters are described in the system_simpar.txt file (see section 4.2 Simulation parameters).

The steady-state solution of a system can also be "simulated"(see section 4.1 Steady-state solutions).

4.1 Steady-state solutions

4.1.1 Steady-state solutions (odess)

MTT can compute the steady-state solutions of an ordinary differential equation; this used the octave function `fsolve'. The solution is computed as a function of time using the input specified in the input file. The simulation parameter file (see section 4.2 Simulation parameters) is used to provide the time scales.

For example

mtt copy rc
cd rc
mtt rc odess view

4.1.2 Steady-state solutions (ss)

mtt system ss view

For example

mtt copy rc
cd rc
mtt rc sspar view
mtt rc ss view

4.2 Simulation parameters

Simulation parameters are set in the system_simpar.txt file. At the moment this sets the following variables:

• LAST the last simulation time
• DT the incremental time (for plotting)
• STEPFACTOR the number of integration steps per DT -- thus the integration interval is DT/STEPFACTOR
• WMIN Minimum frequency = 10^WMIN
• WMAX Maximum frequency = 10^WMAX
• WSTEPS Number of Frequency steps.
• INPUT The input index for frequency response

There are a number of solution algorithms

• Euler basic Euler integration (see section 4.2.1 Euler integration). This method is simple, but not recommended for stiff systems.
• Implicit semi-implicit integration (see section 4.2.2 Implicit integration) - uses the smx representation to give stability.
• Runge Kutta IV fixed step Runge Kutta fourth order integration (see section 4.2.3 Runge Kutta IV integration).
• Hybrd numerical algebraic equation solver

4.2.1 Euler integration

dx/dt = f(x,u)

x := x + f(x,u)*DDT

DDT = DT/STEPFACTOR

(maximum eigenvalue of -A)*DT/2

f(x,u) = Ax + Bu

4.2.2 Implicit integration

dx/dt = f(x,u)

(I-A*DT)x := (I-A*DT)x + f(x,u)DT

If the system is linear, stability is ensured unconditionaly. If the system is non-linear, then the method still works well.

This method is nice in that choice of DT trades of accuracy against computation time without compromising stability. In addition, the correct stready-state values are achieved.

This approach can also be used for constrained state equations of the form:

E(x) dx/dt = f(x,u)

(E(x)-A*DT)x := (E(x)-A*DT)x + f(x,u)DT

The _smx representation includes the E matrix.

4.2.3 Runge Kutta IV integration

dx/dt = f(x,t)

by

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

where

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)

The 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 u is not advanced w.r.t. time; the system inputs are assumed to be constant over the period of the integration step-length.

4.2.4 Hybrd algebraic solver

The hybrd algebraic solver of MINPACK, which is used by Octave in the 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 MTT models by use of unknown SS Components see section 6.6.1 SS component labels.

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

mtt -cc -ae hybrd -i euler sys odeso view

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.

4.3 Simulation input

mtt system input txt

Inputs are defined by the full system name appearing in the structure file (see section 6.7 Structure (struc)). They can depend on states (again defined by name), time (defined by t) and parameters

For example:

system_pump_l_1_u      = 4e5*atm;
system_pump_r_1_u       = 4e5*(t<10)*atm;
system_ss_i             = 0*kg;
system_ss_o             = 3e-3*kg;
system_v_1_u            = (t>10);
system_v_ll_1_u         = 1;
system_v_lr_1_u         = (t<10);
system_v_ul_1_u         = 0;
system_v_ur_1_u         = (t>10);

4.4 Simulation logic

mtt system logic txt

Logical inputs are defined by the full system name corresponding to MTT_switch components appearing in the structure file (see section 6.7 Structure (struc)) with `_logic' appended. They can depend on states (again defined by name), time (defined by t) and parameters

For example:

bounce_ground_1_mtt_switch_logic       = bounce_intf_1_mtt3<0;

4.5 Simulation initial state

mtt system state txt

States are defined by the full system name appearing in the structure file (see section 6.7 Structure (struc)). They can depend on parameters. For example

system_c_l     = (1e4/k_l)/kg;
system_c_ll     = (1e4/k_s)/kg;
system_c_lr     = (1e4/k_s)/kg;
system_c_u      = (1e4/k_l)/kg;

4.6 Simulation code

To generate simulation code in C:

mtt -c [options] sys ode2odes c

Similarly, to generate C++ code:

mtt -cc [options] sys ode2odes cc

To generate an executable based on the C++ representation:

mtt -cc [options] sys ode2odes exe

4.6.1 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 (see section 10.4.2 Creating GNU Octave .oct files) and .mex files can be generated for use in Matlab (see section 10.4.3 Creating Matlab .mex files) or Simulink (see section 10.4.4 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 MTT allows the same code to be generated as standalone code, Octave .oct files or Matlab .mexglx files. Although MTT usually takes care of the compilation options, if it is necessary to compile the code on a machine on which MTT is not installed, the appropriate flag should be passed to the compiler pre-processor:

• -DCODEGENTARGET=STANDALONE
• -DCODEGENTARGET=OCTAVEDLD
• -DCODEGENTARGET=MATLABMEX

4.7 Simulation output

These are two simulation output representations

odes

ordinary differential equation solution (states)

odeso

ordinary differential equation solution (output)

Particular output variables can be selected by adding a fourth argument in one of 2 forms

'name1;name2;..;namen'

plot the variables with names na1 .. namen against time

'name1:name2'

plot the variable with name2 against that with name 1

An example of plotting a single variable against time is:

mtt -o -c -ss OttoCycle odeso ps 'OttoCycle_cycle_V'

mtt -o -c -ss OttoCycle odeso ps 'OttoCycle_cycle_V:OttoCycle_cycle_P'

4.7.1 Viewing results with gnuplot

Simulation plots may be conveniently selected, viewed with gnuplot and saved to file (in PostScript format) using the command

mtt [options] rc gnuplot view

This will cause a menu to be displayed, from which states and outputs may be selected for viewing. Clicking on a parameter name will, by default, cause the time history of the selected parameter to be displayed.

As with xMTT (see section 2.1 Menu-driven interface), the Wish Tcl/Tk interpreter must be installed to make use of this feature.

4.7.2 Exporting results to SciGraphica

Simulation results can be converted into an XML-format SciGraphica (version 0.61) .sg file with the command

mtt [options] sys odes sg

The SciGraphica file will contain two worksheets, X_sys and Y_sys, containing the state and output time-histories from the simulation.

5. Sensitivity models

The sensitivity model of a system is a set of equations giving the sensitivity of the system outputs with respect to system parameters. MTT has built in methods for assisting with the development of such models.

This feature is experimental at the moment, but the following example gives an idea of what can be achieved.

mtt copy rc
cd rc
mtt -s src ode view
mtt -s src odeso view

An alternative route is to create the sensitivity functions by symbolic differentiation. The following sensitivity representations are available:

scse

sensitivity constrained-state equations

sm

sensitivity state matrices

scsm

sensitivity constrained-state matrices

6. Representations

As discussed in 1.1 What is a representation?, a system has many representations. The purpose of MTT is to provide an easy way to generate such representation by applying the appropriate sequence of transformations. The representations supported by MTT are summarised in 6.1 Representation summary.

There is a two-fold division of representations into those with which the user defines the system and its various attributes, and those which are derived from these. The defining representations are listed in 6.2 Defining representations.

Each representation is implemented in one or more languages depending on its use. These languages are discussed in 9. Languages and are associated with appropriate tools for modifying or viewing the representations.

6.1 Representation summary

Some of the the representations available in MTT are (in alphabetical order):

abg

acausal bond graph

cbg

causal bond graph

cr

constitutive relationship for each subsystem

cse

constrained-state equations

csm

constrained-state matrices

dae

differential-algebraic equations

daes

dae solution - state

daeso

dae solution - output

def

definitions - system orders etc.

desc

Verbal description of system

dm

descriptor matrices

ese

elementary system equations

fr

frequency response

input

numerical input declaration

ir

impulse response - state

iro

impulse response - output

lbl

label file

lmfr

loglog modulus frequency response

lpfr

semilog phase frequency response

nifr

Nichols style frequency response

numpar

numerical parameter declaration

nyfr

Nyquist style frequency response

obs

observer equations for CGPC

ode

ordinary differential equations

odes

ode solution - state

odes

ODE simulation header file

odeso

ode solution - output

odess

ode numerical steady-states - states

odesso

ode numerical steady-states - outputs

rbg

raw bond graph

rep

report

rfe

robot-form equations

sabg

stripped acausal bond graph

simp

simplification information

sm

state matrices

smx

state matrices containing explicit states and inputs

sms

ode

smss

SM simulation header file

sr

step response - state

sro

step response - output

ss

steady-state equations

sspar

steady-state definition

struc

structure - list of inputs, outputs and states

sub

Executable subsystem list

sub

LaTeX subsystem list

sympar

symbolic parameters

tf

transfer function

Many of these representations have more than one language (see section 6. Representations) associated with them.

Some of these representations define the system (see section 6.2 Defining representations).

6.2 Defining representations

The following representations define the system and therefore must, ultimately, be defined by the user. However, all of these are assigned default values by MTT and may then be subsequently edited (see section 10.3 Text editors) viewed or operated on by the appropriate tools (see section 10. Language tools).

system_abg.fig

the acausal bond graph (see section 6.4 Acausal bond graph (abg))

system_lbl.txt

the label file (see section 6.6 Labels (lbl))

system_desc.tex

the description file (see section 8.2.2 Detailed on-line documentation)

system_simp.r

algebraic simplifications to make output more readable (see section 6.9.2 Symbolic parameters for simplification (simp.r))

system_subs.r

algebraic substitutions to resolve, eq trig. identities (see section 6.9.1 Symbolic parameters (subs.r))

system_simpar.txt

simulation parameters (see section 4.2 Simulation parameters)

system_numpar.txt

numerical parameters (see section 6.9.3 Numeric parameters (numpar))

system_input.txt

the system input for simulations (see section 4.3 Simulation input)

system_logic.txt

the switching logic for simulations (see section 4.4 Simulation logic)

system_sspar.r

defines the system steady-state (see section 4.1.2 Steady-state solutions (ss))

6.3 Verbal description (desc)

Systems can be documented in LaTeX using the _desc.tex file. This file is included in the report (see section 6.16 Report (rep)) if the abg tex option is included in the rep.txt file. As usual, MTT provides a default text file to be edited by the user (see section 10.3 Text editors).

6.4 Acausal bond graph (abg)

The acausal bond graph is the main input to MTT. It is up to you, as a system modeler, to distill the essential aspects of the system that you wish to model and capture this information in the form of a bond graph.

The inexperienced modeler may wish to look in one of the standard textbooks and copy some bond graphs of systems to get going.

To create the acausal bond graph of system `sys' in language fig type:

mtt sys abg fig

mtt sys abg m

mtt sys abg view

6.4.1 Language fig (abg.fig)

A bond graph is made up of:

bonds

To connect components together.

strokes

To indicate causality.

components

Either simple or compound.

artwork

Irrelevant to the system but useful to the user.

An icon library of bonds, components and other symbols is available within xfig (see section 6.4.1.1 Icon library).

6.4.1.1 Icon library

Click onto the library icon
Click onto the library pull-down menu and select BondGraph
Select iconic symbols from the presented list

6.4.1.2 Bonds

Bonds are represented by polylines with two segments. They must be the default style (i.e. plain not dashed or dotted). The shortest segment is taken to be the half-arrow. its positioning is significant because:

• It points in the direction of power flow; thus a bond normally points towards C, I and R components.
• the corresponding side of the bond indicates flow causality; the other side represents effort causality. This is significant when using casual half-strokes (see section 6.4.1.3 Strokes). Please adopt the convention of having the half-arrows below horizontal bonds and to the right of vertical bonds.

6.4.1.3 Strokes

Causal strokes are represented by single-segment polylines. There are two sorts of strokes:

• Full strokes: these are the usual bond-graph strokes and determine both the effort and flow causality in the usual way. The centre of the stroke should be at about one end of the bond and be at right angles to it.
• Half strokes: these are an innovation in MTT and allow you to specify the effort and flow causality independently. The end of the stroke should be at about one end of the bond and be at right angles to it. If the causal half-stroke is on the same side as the half-arrow (see section 6.4.1.2 Bonds) then it determines flow causality; if, on the other hand, it is on the opposite side to the half-arrow (see section 6.4.1.2 Bonds) then it determines effort causality. Two half strokes on the same, but on opposite sides of the bond are equivalent to a a full stroke at the same end of the bond.

MTT is reasonably forgiving; but a neat diagram will be less ambiguous to you as well as to MTT.

Causality is indicated as follows:

• Effort is imposed at the same end as the stroke.
• Flow is imposed at the opposite end as the stroke.

6.4.1.4 Components

Components are represented by a text string in fig. The recommended style is: 20pt, Times-Roman and centre justified.

The component text string can be of the following forms:

type

Just the type of the component is indicated. Components may be either Simple components (see section 6.4.1.5 Simple components) or Compound components (see section 6.4.1.8 Compound components). For example:

R

type:label

Both the type and the label of the component are given. The type must be a valid name (see section 6.4.1.16 Valid Names.The name provides a link to more information to be found in See section 6.6 Labels (lbl). For example:

R:r

type:label:cr

Not only are the type and the label of the component given, but also the component cr argument. The type must be a valid name (see section 6.4.1.16 Valid Names.The name provides a link to more information to be found in See section 6.6 Labels (lbl). For example:

R:r:flow,r

type:label:expression

Expression is a mathematical expression relating the effort (called mtt_e) to the flow (called mtt_f). For example the following three forms are equivalent

R:r:mtt_e=r*mtt_f R:r:mtt_e-r*mtt_f=0 R:r:mtt_f=mtt_e/r

A non-linear example is:

R:r:mtt_e = sin(mtt_f)

type*n

The name, together with the number `n' of repetitions of the component, are given. This repetition only makes sense if the component has an even number of ports (see section 6.4.1.11 Port labels); n copies of the component are concatenated with odd Named ports (see section 6.4.1.11 Port labels) of the component being connected to the even Named ports of the previous component in the chain in numerical order. This feature is particularly useful if the component is compound and can be used for, example to give a lumped approximation of a distributed system. For example:

MySystem*25

type:label*n

This complete form and is a combination of the simpler forms. For example:

MySystem:MyLabel*25

6.4.1.5 Simple components

The following simple components are defined in MTT.

R

Standard one-port R

C

Standard one-port I

I

Standard one-port I

SS

Source-sensor

TF

Transformer

GY

Gyrator

AE

Effort amplifier

AF

Flow amplifier

CSW

Switched one-port I

ISW

Switched one-port I

6.4.1.6 SS components

SS components provide input and output variables for a system; Named SS components (see section 6.4.1.9 Named SS components) provide this for subsystems.

6.4.1.7 Simple components - implementation

Each simple component, with name NAME, is defined by two m files:

NAME_cause.m

defines the possible causal patterns for the component

NAME_eqn.m

defines the equations generated

6.4.1.8 Compound components

Like any other system, they are described by a graphical Bond Graph description (see section 6.4.1 Language fig (abg.fig)), and a label file (see section 6.6 Labels (lbl)).

By convention, all of the files describing a component live in a directory with the same name as the component.

6.4.1.9 Named SS components

Named SS components provide the link from the system which defines compound component to the system which uses a compound component see section 6.4.1.8 Compound components. A named SS components is of the form SS:[name];

Where `name' is a name consisting of alphanumeric characters and underscore; for example:

SS:[Mechanical_1]

If a named SS component exists at the top level (see section 3.3.1 Top level) and is treated as an ordinary SS component with the given direction and with the attributes specified in the label file (see section 6.6 Labels (lbl)).

6.4.1.10 Coerced bond direction

6.4.1.11 Port labels

A port label is indicated by a name within parentheses of the form [name], where `name' is a name consisting of alphanumeric characters and underscore; for example:

[Mechanical_1]

The following rules must be be obeyed:

• If a component has any port labels at all, there must be one for each port of the component.

Port labels may be grouped into vector port labels (see section 6.4.1.12 Vector port labels). Components with compatible (ie containing the same number of ports) vector ports may be connected by a single bond (see section 1.5 Bonds); such a bond implies the corresponding number of bonds (one for each element of the vector port label). All such bonds inherit the same direction and any explicit causal strokes (see section 6.4.1.3 Strokes)

6.4.1.12 Vector port labels

[Mechanical_1,Electrical,Hydraulic_5]

6.4.1.13 Port label defaults

1. A single unlabled inport defaults to [in]
2. A single unlabled outport defaults to [out]

These defaults may, in turn be aliases (see section 6.6.9 Aliases) for port labels (see section 6.4.1.11 Port labels) or vector port labels (see section 6.4.1.12 Vector port labels). Combining the default and alias mechanism is a powerful tool for creating uncluttered, yet complex, bond graph models.

6.4.1.14 Vector Components

In each case, the presence of a vector component is indicated by a single port label (see section 6.4.1.11 Port labels) of one of two forms:

1. containing numerals from 1 to the order of the vector. Thus a vector of 3 components is indicated by a port label of the form [1,2,3].
2. 1: followed by the order of the vector. Thus a vector of 3 components is indicated by a port label of the form [1:3].

Within the corresponding label file (see section 6.6 Labels (lbl)), the components of a vector port can be accessed using _i where i is the corresponding index. Thus a port SS:[Electrical] appearing near the port label [1,2,3] could contain the port alias (see section 6.6.9.1 Port aliases)

%ALIAS  in Electrical_1,Electrical_2,Electrical_3

6.4.1.15 Artwork

You may add any Fig (see section 9.1 Fig) object to the bond graph as long as it will not be interpreted as part of the bond graph. The reccommended way to acheive this is to put the Bond Graph at depth 0,10,20 etc (ie depth modulo 10 is zero) and artwork at any other depth.

For compatibility with earlier versions of MTT, the following objects are ignored even at level 0. However, their use is strongly discouraged.

• Adding text is OK as long as it cannot be confused with components (see section 6.4.1.4 Components). In particular, you can include invalid component characters such as white space, ", ', ! etc.
• Adding boxes, arcs etc is always OK.
• Adding dotted or dashes lines is always OK.

The stripped abg file (sabg) (see section 6.5 Stripped acausal bond graph (sabg)) shows only those parts of the diagram recognised by MTT and is therefore useful for distinguishing artwork.

6.4.1.16 Valid Names

The following names should be avoided

if endif

The following reserved words in reduce should also be avoided (with any case)

Commands ALGEBRAIC ANTISYMMETRIC ARRAY BYE CLEAR CLEARRULES COMMENT
CONT DECOMPOSE DEFINE DEPEND DISPLAY ED EDITDEF END EVEN FACTOR FOR
FORALL FOREACH GO GOTO IF IN INDEX INFIX INPUT INTEGER KORDER LET
LINEAR LISP LISTARGP LOAD LOAD PACKAGE MASS MATCH MATRIX MSHELL
NODEPEND NONCOM NONZERO NOSPUR ODD OFF ON OPERATOR ORDER OUT PAUSE
PRECEDENCE PRINT PRECISION PROCEDURE QUIT REAL REMFAC REMIND RETRY
RETURN SAVEAS SCALAR SETMOD SHARE SHOWTIME SHUT SPUR SYMBOLIC
SYMMETRIC VECDIM VECTOR WEIGHT WRITE WTLEVEL

Boolean Operators EVENP FIXP FREEOF NUMBERP ORDP PRIMEP

Infix Operators := = >= > <= < => + * / ^ ** . WHERE SETQ OR AND
MEMBER MEMQ EQUAL NEQ EQ GEQ GREATERP LEQ LESSP PLUS DIFFERENCE MINUS
TIMES QUOTIENT EXPT CONS Numerical Operators ABS ACOS ACOSH ACOT ACOTH
ACSC ACSCH ASEC ASECH ASIN ASINH ATAN ATANH ATAN2 COS COSH COT COTH
CSC CSCH EXP FACTORIAL FIX FLOOR HYPOT LN LOG LOGB LOG10 NEXTPRIME
ROUND SEC SECH SIN SINH SQRT TAN TANH

Prefix Operators APPEND ARGLENGTH CEILING COEFF COEFFN COFACTOR CONJ
DEG DEN DET DF DILOG EI EPS ERF FACTORIZE FIRST GCD G IMPART INT
INTERPOL LCM LCOF LENGTH LHS LINELENGTH LTERM MAINVAR MAT MATEIGEN MAX
MIN MKID NULLSPACE NUM PART PF PRECISION RANDOM RANDOM NEW SEED RANK
REDERR REDUCT REMAINDER REPART REST RESULTANT REVERSE RHS SECOND SET
SHOWRULES SIGN SOLVE STRUCTR SUB SUM THIRD TP TRACE VARNAME

Reserved Variables CARD NO E EVAL MODE FORT WIDTH HIGH POW I INFINITY
K!* LOW POW NIL PI ROOT MULTIPLICITY T

Switches ADJPREC ALGINT ALLBRANCH ALLFAC BFSPACE COMBINEEXPT
COMBINELOGS COMP COMPLEX CRAMER CREF DEFN DEMO DIV ECHO ERRCONT
EVALLHSEQP EXP EXPANDLOGS EZGCD FACTOR FORT FULLROOTS GCD IFACTOR INT
INTSTR LCM LIST LISTARGS MCD MODULAR MSG MULTIPLICITIES NAT NERO
NOSPLIT OUTPUT PERIOD PRECISE PRET PRI RAT RATARG RATIONAL RATIONALIZE
RATPRI REVPRI RLISP88 ROUNDALL ROUNDBF ROUNDED SAVESTRUCTR
SOLVESINGULAR TIME TRA TRFAC TRIGFORM TRINT

Other Reserved Ids BEGIN DO EXPR FEXPR INPUT LAMBDA LISP MACRO PRODUCT
REPEAT SMACRO SUM UNTIL WHEN WHILE WS

6.4.2 Language m (rbg.m)

function [rbonds, rstrokes,rcomponents,rports,n_ports] = sys_rbg

The five outputs of this function are:

• rbonds
• rstrokes
• rcomponents
• rports
• n_ports

rbonds is a matrix with

• one row for each bond (see section 6.4.1.2 Bonds)
• columns 1 and 2 containing the x,y coordinates for one end of the bond
• columns 3 and 4 containing the x,y coordinates for the corner of the bond
• columns 5 and 6 containing the x,y coordinates for the other end of the bond

rstrokes is a matrix with (see section 6.4.1.3 Strokes)

• one row for each stroke or half-stroke
• columns 1 and 2 containing the x,y coordinates for one end of the stroke
• columns 3 and 4 containing the x,y coordinates for the other end of the stroke

rcomponents is a matrix with (see section 6.4.1.4 Components)

• one row for each component
• columns 1 and 2 containing the x,y coordinates of the component
• the remaining columns containing fig file information

rports is a matrix with (see section 6.4.1.11 Port labels)

• one row for each component port that is explicitly labeled
• columns 1 and 2 containing the x,y coordinates of the port label
• column 3 contains the port number.

n_ports is the number of ports associated with the system -- i.e. the number of Named SS components (see section 6.4.1.9 Named SS components).

6.4.2.1 Transformation abg2rbg_fig2m

This transformation takes the acausal bond graph as a fig file (see section 6.4.1 Language fig (abg.fig)) and transforms it into a raw bond graph in m-file format (see section 6.4.2 Language m (rbg.m)).

This transformation is implemented in GNU awk (gawk). It scans both the fig file (see section 6.4.1 Language fig (abg.fig)) and the label file (see section 6.6 Labels (lbl)) and generates the rbg (see section 6.4.2 Language m (rbg.m)) with components sorted according to the label file. It also generates a file sys_fig.fig containing details of the bond graph with the components removed.

6.4.3 Language m (abg.m)

The acausal bond graph of system `sys' is represented as an m file with heading:

function [bonds,components,n_ports] = sys_abg

• bonds
• components
• n_ports

bonds is a matrix with

• one row for each bond
• the first column contains the arrow-orientated (see section 6.4.3.1 Arrow-orientated causality) causality of the effort variable.
• the second column contains the arrow-orientated (see section 6.4.3.1 Arrow-orientated causality) causality of the flow variable.

components is a matrix with

• one row for each component
• one column for each bond impinging on the component. The magnitude of each entry corresponds to the bond number (the appropriate row index of` bonds'); the sign is positive if the bond arrow points into the component and negative otherwise.

n_ports is the number of ports associated with the system -- i.e. the number of Named SS components (see section 6.4.1.9 Named SS components).

6.4.3.1 Arrow-orientated causality

The arrow-orientated causality convention assigns -1, 0 or 1 to both the effort and flow (see section 1.4 Variables) sides of a bond to represent the causal stroke (see section 6.4.1.3 Strokes) as follows:

0

if there is no causality set.

1

if the causal stroke is at the arrow end of the bond.

-1

if the causal stroke is at the other end of the bond.

6.4.3.2 Component-orientated causality

The component-orientated causality convention assigns -1, 0 or 1 to both the effort and flow (see section 1.4 Variables) sides of a bond to represent the causal stroke (see section 6.4.1.3 Strokes) as follows:

0

if there is no causality set.

1

if the causal stroke is at the component end of the bond.

-1

if the causal stroke is at the other end of the bond.

6.4.3.3 Transformation rbg2abg_m

6.4.4 Language tex (abg.tex)

For the purpose of producing a report (see section 6.16 Report (rep)), MTT generates a LaTeX (see section 10.5 LaTeX) file describing the bond graph and its subsystems. Additional information may be supplied using the description representation (see section 8.2.2 Detailed on-line documentation).

6.5 Stripped acausal bond graph (sabg)

6.5.1 Language fig (sabg.fig)

mtt syst sabg fig

6.5.2 Stripped acausal bond graph (view)

6.6 Labels (lbl)

The label file contains the following non-blank lines (blank lines are ignored)

• Summary - lines beginning with #SUMMARY
• Description - lines beginning with #DESCRIPTION
• Alias - lines beginning with #ALIAS
• Comments - lines beginning with #
• Labels - other non-blank lines

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:

1. The component name see section 6.6.3 Component names. This must be a valid name (see section 6.4.1.16 Valid Names.
2. The component constitutive relationship see section 6.6.4 Component constitutive relationship
3. The component arguments see section 6.6.5 Component arguments

Not each component see section 6.4.1.4 Components needs a label, only those which are explicitly labeled on the Bond Graph see section 6.4 Acausal bond graph (abg). MTT checks whether all components labelled on the bond graph have labels and vice versa.

If no lbl file exists, MTT will create a valid one for you; including a default set of arguments and crs for both simplae and compound components.

If wish to create one to edit yourself, type

mtt system_name lbl txt

%% Label file for system RC (RC_lbl.txt)
%SUMMARY RC
%DESCRIPTION <Detailed description here>
% Port aliases
%ALIAS  in      in
%ALIAS  out     out

% Argument aliases
%ALIAS  $1      c
%ALIAS  $2      r

%% Each line should be of one of the following forms:
%            a comment (ie starting with %)
%            component-name     cr_name arg1,arg2,..argn
%            blank

% ---- Component labels ----

% Component type C
        c               lin     effort,c

% Component type R
        r               lin     flow,r

% Component type SS
        [in]    SS              external,external
        [out]   SS              external,external

The old-style lbl files (see section 6.6.11 Old-style labels (lbl)) are NO LONGER supported -- you are encouraged to convert them ASAP.

6.6.1 SS component labels

These two information fields correspond to the effort and flow variables of the of the SS components as follows

info_field_1

effort

info_field_2

flow

external

indicates that the corresponding variable is a system input or output

internal

indicates that the variable does not appear as a system output; it is an error to label an input in this way.

a number

the value of the input; or the value of the (imposed) output

a symbol

the symbolic value of the input; or the value of the (imposed) output

unknown

used for the SS method of solving algebraic loops. This indicates that the corresponding system input (SS output) is to be chosen to set the corresponding system output (SS input) to zero.

zero

used for the SS method of solving algebraic loops. This indicates that the corresponding system output (SS input) is to be set to zero using the variable indicted by the corresponding `unknown' label.

Some examples are:

%% ss1 is both a source and sensor
ss1     SS              external,external
%% ss1 acts as a flow sensor - it imposes zero effort.
ss2     SS              0,external

6.6.2 Other component labels

In addition to the label there are two information fields, see section 6.6 Labels (lbl). They correspond to the constitutive relationship (see see section 1.6.2 Constitutive relationship and arguments of the component as follows

info_field_1

constitutive relationship

info_field_2

parameters

Some examples are:

%Armature resistance
r_a     lin     effort,r_a

%Gearbox ratio
n       lin     effort,n

MTT supports parameter-passing to (see section 6.6.10 Parameter passing) subsystems.

6.6.3 Component names

6.6.4 Component constitutive relationship

1. A generic constitutive relationship such as lin (the generic linear constitutive relationship.
2. A local constitutive relationship with the same name as the component type
3. The SS constitutive relationship reserved for SS components. All labels for SS components must contain SS in this field.

6.6.5 Component arguments

6.6.6 Parameter declarations

It is sometimes useful to use parameters (in addition to those implied by the Component arguments see section 6.6.5 Component arguments) to compute values in, for example the numpar file. These can be declared in the label file; for examples , the two parameters par1 and par 2 can be declared as:

#PAR par1
#PAR par2

On the other hand, some CR arguments (eg foo and bar) may not correspond to parameters. These can be excluded from the sympar list using the NOTPAR declaration

#NOTPAR foo
#NOTPAR bar

For comapability with old code, VAR may be used in place of PAR, but this usage is deprecated.

6.6.7 Units declarations

#UNITS Port_name domain effort_units flow_units

electrical

the electrical domain

translational

the translational mechanical domain

rotational

the rotational mechanical domain

fluid

the fluid domain

thermal

the thermal domain

Allowed units are those defined in the units package.

MTT checks that units are

• defined consistently with the domain
• the same for connected ports when both ports have defined units.

6.6.8 Interface Control Definition

#ICD    PressureSensor         PUMP1_PRESSURE_SENSOR,Pa;null,none
#ICD    Electrical              PUMP1_VOLTAGE,volt;PUMP1_CURRENT,amp

% Component type De
        PressureSensor  SS      external

% Component type SS
        Electrical      SS      external,external

The ICD directive consists of 3 whitespace delimited fields:

1. [%|#]ICD
2. component name
3. Four comma (,) or semi-colon (;) delimited fields:
   1. name of effort parameter
   2. unit of effort parameter
   3. name of flow parameter
   4. unit of flow parameter

If no parameter name is required, a value of "null" should be used. If the parameter does not have any units, a value of "none" should be used.

ICD parameters may be aliased see section 6.6.9 Aliases in the same way as normal parameters, thus it is possible to define some or all of the ICD in higher level components.

The command

mtt sys ICD txt

will generate a text file containing a list of mappings:

## Interface Control Definition for System sys
## sys_ICD.txt: Generated by MTT Thu Jul 12 21:21:21 CDT 2001

Input:  PUMP1_VOLTAGE           sys_P1_1_Electrical      Causality: Effort   Units: volt
Output: PUMP1_CURRENT           sys_P1_1_Electrical      Causality: Flow     Units: amp
Output: PUMP1_PRESSURE_SENSOR   sys_P1_1_PressureSensor  Causality: Effort   Units: Pa

A set of assignments can be generated with the command

mtt sys ICD m

resulting in:

# Interface Control Definition mappings for system sys
# sys_ICD.m: Generated by MTT Thu Jul 12 21:26:56 CDT 2001

# Inputs

        mttu(1) = PUMP1_VOLTAGE;

# Outputs

        PUMP1_CURRENT                  = mtty(1);
        PUMP1_PRESSURE_SENSOR          = mtty(2);

A similar file will be generated by the command

mtt sys ICD cc

6.6.9 Aliases

Aliases provide a convenient mechanism for relabelling words appearing in the label file (see section 6.6 Labels (lbl)). There are three contexts in which the alias mechanism is used:

1. renaming ports (see section 6.6.9.1 Port aliases),
2. renaming parameters (see section 6.6.9.2 Parameter aliases) and
3. renaming components (see section 6.6.9.4 Component aliases).

All three mechanisms use the same form of statement within the label file

%ALIAS short_label       real_label

MTT distinguishes between the three forms as follows:

• Parameter aliases: `short_label' starts with a `$'
• Component aliases: `real_label' contains the directory separator `/'
• Port aliases: neither of the above

6.6.9.1 Port aliases

%ALIAS short_label       real_label

When the component is used within another component, the short_lable may be used in place of the real_label. More than one alias per label can be used, for example

%ALIAS short_label_1       real_label
%ALIAS short_label_2       real_label
%ALIAS short_label_3       real_label

The port can then be refered to in four ways: as real_label, short_label_1, short_label_2 or short_label_3. An alternative notation for the ALIAS statement in this case is

%ALIAS short_label_1|short_label_2|short_label_3       real_label

The alias feature is particularly powerful in conjunction with vector port labels (see section 6.4.1.12 Vector port labels) and the port label default (see section 6.4.1.13 Port label defaults) mechanisms. For example, a component with 5 ports appearing in the lbl file as:

        [Hydraulic_in]  external        external
        [Hydraulic_out] external        external
        [Power_Shaft]           external        external
        [Thermal_in]    external        external
        [Thermal_out]   external        external

together with the following statements in the label file:

%ALIAS  in              Thermal_in,Hyydraulic_in
%ALIAS  out             Thermal_out,Hydraulic_out
%ALIAS  shaft|power     Power_Shaft

can appear in the bond graph containing that component with one bond labeled either [shaft] or [power] or [Power_Shaft], one unlabeled vector bond pointing in and one unlabeled vector bond pointing out.

6.6.9.2 Parameter aliases

Parameter aliases are of the form

%ALIAS $n       actual parameter

%ALIAS  $1              c_v
%ALIAS  $2              density,ideal_gas,r
%ALIAS  $3              alpha
%ALIAS  $4              flow,k_p

Assigns four symbolic parameters to the corresponding strings These four parameters ($1--$4) can then be used for parameter passing(see section 6.6.10 Parameter passing).

6.6.9.3 CR aliases

CR aliases are of the form

%ALIAS $an       actual parameter

%ALIAS  $a1  lin

6.6.9.4 Component aliases

Component aliases are of the form

%ALIAS Component_name   Component_location

An example appears in the following label file fragment

...
%ALIAS  wPipe   CompressibleFlow/wPipe
%ALIAS  Poly    CompressibleFlow/Poly
....

6.6.10 Parameter passing

In a subsystem $i, is replaced by the ith field of a colon ; separated field in the calling label file. This field may include commas , and the four arithmetic operators +, -, * and /.

For example, consider the following example label file fragment (associated with a component called Pump:

...

%ALIAS  $1              c_v
%ALIAS  $2              density,ideal_gas,r
%ALIAS  $3              alpha
%ALIAS  $4              flow,k_p

%ALIAS  wPipe   CompressibleFlow/wPipe
%ALIAS  Poly    CompressibleFlow/Poly

% Component type wPipe
        pipe    none                    c_v;density,ideal_gas,r

% Component type Poly
        poly            Poly            alpha

The 4 parameters $1, $2, $3, and $4 can be passed from a higher level component as in the following label file fragment:

% Component type Pump
        comp            none            c_v;rho,ideal_gas,r;alpha;effort,k_c
        turb            none            c_v;rho,ideal_gas,r;alpha;effort,k_t

Thus in component `comp':

• $1 is replaced by c_v
• $2 is replaced by rho,ideal_gas
• $3 is replaced by alpha
• $4 is replaced by effort,k_c

• $4 is replaced by effort,k_t

6.6.11 Old-style labels (lbl)

Old syle labels (mtt version 2.x) are supported by mtt version 3.x. However, you are advised to use the new form (see section 6.6 Labels (lbl)).

Each line of the _label.txt file is of one of three forms:

1. Contains three fields (separated by white space) of the form

   label field_1 field_2

2. Blank
3. Preceded by %

The role of the two information fields depends on the component with the corresponding label. In particular the classes of components are:

• SS components, see section 6.4.1.6 SS components.
• Other components, see section 6.4.1.4 Components.

6.6.11.1 SS component labels (old-style)

info_field_1

effort

info_field_2

flow

external indicates that the corresponding variable is a system input or output

internal

indicates that the variable does not appear as a system output; it is an error to label an input in this way.

a number

the value of the input; or the value of the (imposed) output

a symbol

the symbolic value of the input; or the value of the (imposed) output

unknown

used for the SS method of solving algebraic loops. This indicates that the corresponding system input (SS output) is to be chosen to set the corresponding system output (SS input) to zero.

zero

used for the SS method of solving algebraic loops. This indicates that the corresponding system output (SS input) is to be set to zero using the variable indicted by the corresponding `unknown' label.

Some examples are:

%Label  field1          field2
ss1     external        external
ss2     0               external

6.6.11.2 Other component labels (old-style)

In addition to the label there are two information fields, see section 6.6 Labels (lbl). They correspond to the constitutive relationship (see see section 1.6.2 Constitutive relationship and arguments of the component as follows

info_field_1

constitutive relationship

info_field_2

parameters

Some examples are:

%Armature resistance
r_a     lin     effort,r_a

%Gearbox ratio
n       lin     effort,n

MTT supports parameter-passing to (see section 6.6.11.3 Parameter passing (old-style)) subsystems.

6.6.11.3 Parameter passing (old-style)

In a subsystem $i, is replaced by the ith field of a colon ; separated field in the calling label file. This field may include commas ,.

For example subsystem ROD contains the following lines in the label file:

%DESCRIPTION    Parameter 1:    length from end 1 to mass centre
%DESCRIPTION    Parameter 2:    length from end 2 to mass centre
%DESCRIPTION    Parameter 3:    inertia about mass centre
%DESCRIPTION    Parameter 4:    mass
%DESCRIPTION    See Section 10.2 of "Metamodelling"


%Inertias
J       lin     flow,$3
m_x     lin     flow,$4
m_y     lin     flow,$4

%Integrate angular velocity to get angle
th

%Modulated transformers
s1      lsin    flow,$1
s2      lsin    flow,$2
c1      lcos    flow,$1
c2      lcos    flow,$2

This can be used in a higher-level lbl (see section 6.6 Labels (lbl)) file as:

%SUMMARY Pendulum example from Section 10.3 of "Metamodelling"

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

6.6.12 Language tex (desc.tex)

6.7 Structure (struc)

The causal bond graph implies a set of equations describing the system. The Structure (struc) representation describes the structure of these equations in terms of the input, outputs, states and non-states of the system.

6.7.1 Language txt (struc.txt)

type

input, output state or nonstate

index an integer corresponding to the array index

component name the name of the component corresponding to the variable

system name

the name of the system containing the component

repetition

an integer corresponding to the repetition of a repeated subsystem.

An example of such a file (corresponding to rc) (see section 3.1 Quick start) is:

input           1       e1      rc      1
output          1       e2      rc      1
state           1       c       rc      1

6.7.2 Language tex (struc.tex)

6.7.3 Language tex (view)

6.8 Constitutive relationship (cr)

The constitutive relationship (see section 1.6.2 Constitutive relationship) of a simple component (see section 6.4.1.5 Simple components is defined in the symbolic algebra language Reduce (see section 9.3 Reduce). The constitutive relationship of a compound components (see section 6.4.1.8 Compound components) is implied by the constitutive relationships of its constituent components.