[Index]

The Matlab Engine NMI Component (libmtng)

This document describes the Matlab Engine NMI Component (libmtng). Libmtng uses the matlab engine to allow a run-time specified body of matlab code to be run as an NMI component. Libmtng is derived from and conforms to the Network Model Interface. This edition documents version 1.0.

1. Notices

2. Introduction

3. Installation

4. Overview

5. The Mtngnmi Class

6. Examples

7. Testing

-- The Detailed Node Listing ---

Introduction

2.1 Companion Software

2.2 Obtaining

2.3 Other Documentation

Installation

3.1 Dependencies

3.2 Platforms

3.3 Required Build Tools

3.4 Building

3.5 Environment

Overview

4.1 Standards for Matlab Code

4.2 Constructing the System

4.3 Resetting the System

The Mtngnmi Class

5.1 Mtngnmi Configuration

5.2 Mtngnmi Commands

5.3 Mtngnmi Input Channels

5.4 Mtngnmi Output Channels

[Index]

1. Notices

The Matlab Engine NMI Component (libmtng)

Copyright (C) 1999 - 2003 Mike Arnold, Altjira Software.

Matlab is a trademark of The Mathworks Inc.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

This software and documentation is provided "as is" without express or implied warranty. All questions should be addressed to mikea@altjira.com.

[Index]

2. Introduction

2.1 Companion Software

2.2 Obtaining

2.3 Other Documentation

Libmtng uses the matlab engine to allow a run-time specified body of matlab code to be run as an NMI component. It is derived from and conforms to the Network Model Interface.

The matlab code must conform to the requirements as laid out in this documentation whereby the code is packaged up within a number of predefined functions and modules whose names have an 'nmi' prefix.

[Index]

2.1 Companion Software

For simulation frameworks that support NMI components refer to the libnmi documentation. Further information about the interoperability of NMI components can be found in the NMI Simulation Resources documentation.

The mtngpkg support package is available to facilitate the application of libmtng components within the available simulation frameworks.

[Index]

2.2 Obtaining

libmtng may be downloaded from http://www.altjira.com/distrib/libmtng. See also 3.1 Dependencies, and 2.1 Companion Software, for other software that may need to be downloaded and installed.

The latest version of this documentation may be found at http://www.altjira.com/support/libmtng/libmtng.html.

[Index]

2.3 Other Documentation

The mtngpkg support package includes documentation and examples on how to apply libmtng components within the available simulation frameworks. Other relevant support packages may be listed in the NMI Simulation Resources documentation.

Documentation on the implementation of libmtng is included within the source code, in particular the primary source files for each NMI component. Further information on how to write an NMI component is included in the libnmi documentation.

See also 2.1 Companion Software for further information on using libmtng.

This documentation is also installed to ${prefix}/doc/libmtng, where `${prefix}' is the installation directory specified during the build configuration.

[Index]

3. Installation

3.1 Dependencies

3.2 Platforms

3.3 Required Build Tools

3.4 Building

3.5 Environment

[Index]

3.1 Dependencies

libmtng requires the Network Model Interface library libnmi. It also requires matlab including the Matlab C libraries.

[Index]

3.2 Platforms

libmtng has been successfully tested on the following systems:

i686-linux-gnu (Mandrake 8.2) with Matlab 6.5 R13
freebsd release 4.6 with Matlab 6.5 R13

[Index]

3.3 Required Build Tools

The following software is suggested. Other versions may work but have not been tested.

Package maintenance requires:

[Index]

3.4 Building

Refer to the README and INSTALL files in the distribution.

[Index]

3.5 Environment

To use the matlab engine one may need to set the environment variable LD_LIBRARY_PATH in the user's shell, for example:

LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:/usr/local/matlab/extern/lib/glnx86:/usr/local/matlab/sys/os/glnx86

Check the matlab documentation.

[Index]

4. Overview

Libmtng contains the NMI-derived component Mtngnmi that calls the matlab engine to run some body of matlab code. Libmtng does not include the matlab code to be run, as it is specified at run-time not at compile-time. The matlab code is specified using the matlab path, as defined by the matlab installation, the user's matlab profile and the optional Mtngnmi <path> configuration. Note that <path> may only contain a single path, not a list of paths.

4.1 Standards for Matlab Code

4.2 Constructing the System

4.3 Resetting the System

[Index]

4.1 Standards for Matlab Code

The matlab code must be packaged up within a number of predefined functions and `.m' files. The names of these functions and files have a 'nmi' prefix and correspond to methods within the Nmi class. Note that not all of the methods in the Nmi class have corresponding `.m' files.

The following functions and `.m' files are required. Unless otherwise specified, the functions take no arguments and return no arguments.

nmiConstruct.m is a body of code that is called whenever the engine is started to create a default set of structures.
nmiBuild.m is a body of code that is called by build() to create ancillary data structures including the tag information for all channels.
nmiCalculate.m is a matlab function that is called by calculate() to move the matlab code forward in time. The function is defined as:
finish = nmiCalculate(start,finish)
nmiReset.m is a matlab function that is called by reset() to reset the matlab code.
nmiDump.m is a matlab function that is called by dump() to dump the state of the matlab code to an unspecified location.
nmiRestore.m is a matlab function that is called by restore() to restore the state of the matlab code from an unspecified location.
nmiCheck.m is a matlab function that is called by check() to check the integrity of the matlab code.
nmiDescribe.m is a matlab function that is called by describe() to describe the state of the matlab code.
nmiClassDesc.m is a matlab function that describes the functionality of the matlab code. It is not called by classDesc() but can be called from a Libmtng object using the run-code command.

The matlab code must also define a number of global variables whose names have a 'vNmi' prefix.

vNmiInputTags is a structure array that defines what input channels exist within the matlab code. The first field tag contains a string being the channel name, the second field alias contains a string being the alias for the channel name, and the third field size contains a double being the size of the channel which libmtng interprets as an unsigned integer. Libmtng does not expect it to be defined until after nmiBuild.m has been run.
vNmiOutputTags is a structure array that defines what output channels exist within the matlab code. The first field tag contains a string being the channel name, the second field alias contains a string being the alias for the channel name, and the third field size contains a double being the size of the channel which libmtng interprets as an unsigned integer. Libmtng does not expect it to be defined until after nmiBuild.m has been run.

Libmtng expects two other variables to be defined for each input or output channel. For each channel, the names of these related variables depend on the name of the channel as defined by the field tag in the vNmiInputTags and vNmiOutputTags structures. One variable, defined using the name of the channel, is used to hold the data for the channel and must be an array of double (of length size). The other variable, defined using the name of the channel with Change as a suffix, is used to indicate whether the state of the channel has changed, and must be an array of logical of length 1. Change of channel state variables for input channels are for the benefit of the matlab code and are set by libmtng to indicate that input has been received. Change of channel state variables for output channels are for the benefit of libmtng and should be set by the matlab function nmiCalculate() to indicate that the output has changed and needs to be propagated.

[Index]

4.2 Constructing the System

Each Mtngnmi object has its own matlab engine. The matlab engine is started automatically, but not at first when the Mtngnmi object is instantiated, but later when the first access to the engine is required. The command to start the matlab engine is defined using the configurable <start> (see 5.1 Mtngnmi Configuration).

Upon starting the engine the following occur:

if the configurable <path> has been defined then it is prepended to the matlab path so that the Mtngnmi object will locate the correct body of matlab code.
the matlab file nmiConstruct.m is called.
an optional second body of matlab code can be called using the configurable <construct>.

Configuring <start> or <path> causes the engine to be stopped and then re-started. Configuring <construct> does not cause the engine to be re-started, but does cause the specified body of matlab code to be immediately applied. The engine can also be stopped and started using the related Mtngnmi commands (see 5.2 Mtngnmi Commands).

[Index]

4.3 Resetting the System

When reset() is called, libmtng will first call the matlab function nmiReset(). An optional second body of matlab code can be called using the configurable <reset> (see 5.1 Mtngnmi Configuration).

[Index]

5. The Mtngnmi Class

reset=<string> additional reset command (none)

5.1 Mtngnmi Configuration

5.2 Mtngnmi Commands

5.3 Mtngnmi Input Channels

5.4 Mtngnmi Output Channels

[Index]

5.1 Mtngnmi Configuration

The following can be configured using the configure() routine. Note that the classDesc() routine in the source code is the authorative documentation.

start=<string> command to start the matlab engine (matlab -nodesktop -nosplash) path=<string> path to add to the matlab engine (none) construct=<string> additional construct command (none) reset=<string> additional reset command (none)

[Index]

5.2 Mtngnmi Commands

The following commands can be run using the call() routine. Note that the classDesc() routine in the source code is the authorative documentation.

start-engine [command=<string>] start the matlab engine command=<string> command to start engine stop-engine stop the matlab engine run-code code=<string> run some matlab code=<string> the code to run

[Index]

5.3 Mtngnmi Input Channels

The Mtngnmi class defines an input channel for each input channel within the matlab code as defined using the vNmiInputTags structure. Input for a channel causes the associated Change logical variable to be set to true (see 4.1 Standards for Matlab Code).

[Index]

5.4 Mtngnmi Output Channels

The Mtngnmi class defines an input channel for each input channel within the matlab code as defined using the vNmiOutputTags structure. Output is only placed on a channel if the associated Change logical variable is true (see 4.1 Standards for Matlab Code).

[Index]

6. Examples

Refer to the tutorial in the accompanying mtngpkg support package.

An example body of matlab code that works with the mtngtest executable is installed to ${prefix}/share/libmtng, where `${prefix}' is the installation directory specified during the build configuration.

[ > ]

[ >> ]

[Index]

7. Testing

To verify that libmtng is working properly and as an initial test for any body of matlab code, use the mtngtest executable, the source for which is in the `test' sub-directory in the source tree. mtngtest takes one optional argument which specifies the configurable <path>. Using the matlab code example provided in ${prefix}/share/libmtng, where `${prefix}' is the installation directory specified during the build configuration:

mtngtest ${prefix}/share/libmtng

[Index]

Table of Contents

2. Introduction

2.1 Companion Software

2.3 Other Documentation

3. Installation

3.1 Dependencies

3.3 Required Build Tools

3.5 Environment

4.1 Standards for Matlab Code

4.2 Constructing the System

4.3 Resetting the System

5. The Mtngnmi Class

5.1 Mtngnmi Configuration

5.2 Mtngnmi Commands

5.3 Mtngnmi Input Channels

5.4 Mtngnmi Output Channels

[Index]

Short Table of Contents

1. Notices
2. Introduction
3. Installation
4. Overview
5. The Mtngnmi Class
6. Examples
7. Testing

[Index]

About this document

This document was generated by Mike Arnold on June, 19 2003 using texi2html

The buttons in the navigation panels have the following meaning:

Button	Name	Go to	From 1.2.3 go to
[ < ]	Back	previous section in reading order	1.2.2
[ > ]	Forward	next section in reading order	1.2.4
[ << ]	FastBack	previous or up-and-previous section	1.1
[ Up ]	Up	up section	1.2
[ >> ]	FastForward	next or up-and-next section	1.3
[Top]	Top	cover (top) of document
[Contents]	Contents	table of contents
[Index]	Index	concept index
[ ? ]	About	this page

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

1. Section One

1.1 Subsection One-One

...

1.2 Subsection One-Two

1.2.1 Subsubsection One-Two-One
1.2.2 Subsubsection One-Two-Two
1.2.3 Subsubsection One-Two-Three <== Current Position
1.2.4 Subsubsection One-Two-Four

1.3 Subsection One-Three

...

1.4 Subsection One-Four

This document was generated by Mike Arnold on June, 19 2003 using texi2html