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