NMI Matlab Wrapper (matnmi)

This document describes the Matlab Wrapper (matnmi) for the Network Model Interface (NMI or libnmi). matnmi allows objects of any nmi::Nmi derived class to be accessed from within Matlab. This edition documents version 1.0.

1. Notices
2. Introduction
3. Installation
4. Using the nmi() Function
5. Examples
6. Adding Nmi Classes
7. Troubleshooting
Concept Index

 -- 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

1. Notices

The NMI Matlab Wrapper (matnmi)

Copyright (C) 2002 - 2003 Mike Arnold, The Salk Institute for Biological Studies

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 was developed with the support of NASA Grant Number: NCC 2-1253.

Matlab is a trademark of The Mathworks Inc.

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

2. Introduction

matnmi allows objects of any class derived from the nmi::Nmi class to be accessed from within Matlab. It it is comprised of a single C-MEX function called nmi(). As a C-MEX function, nmi() is available within the Matlab environment.

nmi() takes at least one input array, being a string defining the functionality required, either the creation or deletion of an object of specified nmi::Nmi derived type, or the calling of the specified nmi::Nmi method for the specified object. Instantiated objects are stored within a static container within nmi(). The instantiation of an object returns an object id to the Matlab environment in the return array. This object id is used to specify all futher operations on the object, such as the calling of methods or its deletion.

nmi() can instantiate objects only of nmi::Nmi derived types, and only of types that have been explicitly compiled in to the C-MEX function.

The wrapper is implemented as a single C-MEX function instead of as a suite of C-MEX functions due to the problems of sharing static data between C-MEX functions.

2.1 Companion Software
2.2 Obtaining
2.3 Other Documentation

2.1 Companion Software

For the nmi::Nmi derived objects currently supported by matnmi refer to the libnmi website.

2.2 Obtaining

matnmi may be downloaded from http://www.cnl.salk.edu/~mikea/distrib/matnmi. 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.cnl.salk.edu/~mikea/doc/matnmi/matnmi.html.

2.3 Other Documentation

Further information regarding the interoperability of NMI components and supporting frameworks, their development and use, and all associated support and post-processing packages, is available in the NMI Simulation Resources documentation.

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

3. Installation

3.1 Dependencies
3.2 Platforms
3.3 Required Build Tools
3.4 Building
3.5 Environment

3.1 Dependencies

matnmi requires both the Network Model Interface library libnmi and the xutil library libxutil, as well as the packages containing desired the nmi::Nmi derived classes that are to be made available within Matlab. It also requires matlab including the Matlab mex compiler.

3.2 Platforms

matnmi 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

3.3 Required Build Tools

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

• gcc 3.2
• texi2html 1.64

Package maintenance requires:

• autoconf 2.54
• automake 1.7

3.4 Building

Refer to the README and INSTALL files in the distribution.

3.5 Environment

nmi() is installed to `$prefix/libexec/matnmi' where `$prefix' is the installation prefix given to the configure script during building. This directory should be included in the Matlab path, for example by modifying the user's Matlab startup file, which is usually `/home/user/matlab/startup.m'. For example, for the default prefix `/usr/local', the following line would be added:

addpath('/usr/local/libexec/matnmi')

4. Using the nmi() Function

nmi() takes at least one input array, being a string defining the functionality required, either the creation or deletion of an object of specified nmi::Nmi derived type, or the calling of the specified nmi::Nmi method for the specified object. Instantiated objects are stored within a static structure hidden from the Matlab environment. The instantiation of an object returns an object id to the Matlab environment in the return array. This object id is used to specify all futher operations on the object, such as the calling of methods or its deletion.

nmi() can be called in the following ways:

• <object_id> = nmi('create',<type>)

  instantiates a new object of specified type and returns the new object id.

• nmi('delete',<object_id>)

  deletes the object with the specified object.

• nmi('reset',<object_id>)

  calls Nmi::reset().

• nmi('restore',<object_id>,<stream_definition>)

  calls Nmi::restore(input) where <stream_definition> defines the input source.

• nmi('dump',<object_id>,<stream_definition>)

  calls Nmi::dump(output) where <stream_definition> defines the output.

• nmi('describe',<object_id>,<stream_definition>)

  calls Nmi::describe(output) where <stream_definition> defines the output.

• nmi('class-desc',<object_id>,<stream_definition>)

  calls Nmi::classDesc(output) where <stream_definition> defines the output.

• nmi('configure',<object_id>,<token>,<value>)

  calls Nmi::configure(<token>,<value>).

• nmi('call',<object_id>,<command>,<arguments>,<stream_definition>)

  calls Nmi::call(<command>,<arguments>,input,output) where <stream_definition> defines the input source and the output.

• nmi('check',<object_id>)

  calls Nmi::check().

• nmi('parse',<object_id>,<stream_definition>)

  calls Nmi::parse(input) where <stream_definition> defines the input source.

• nmi('build',<object_id>,<stream_definition>)

  calls Nmi::build(output) where <stream_definition> defines the output.

• <tag,size> = nmi('get-input-tags',<object_id>)

  calls Nmi::getInputTags() and returns an array of structures with one structure for each tag.

• <tag,size> = nmi('get-output-tags',<object_id>)

  calls Nmi::getOutputTags() and returns an array of structures with one structure for each tag.

• nmi('pass-input',<object_id>,<channel>,<time>,<data>)

  calls Nmi::passInput(<channel>,packet) where the packet is constructed from <time> and every element of <data>.

• <time> = nmi('request-output',<object_id>,<channel>,<data>)

  calls Nmi::requestOutput(<channel>,packet) and uses the returned packet to update <data>. If the packet is not empty, then the time of the updated data is returned.

• nmi('calculate',<object_id>,<start_time>,<finish_time>)

  calls Nmi::calculate(<start_time>,<finish_time>).

• nmi('configure-list',<object_id>,<token=value token=value ...>)

  calls Nmi::configure(<token>,<value>) for each token=value pair.

Stream definition arguments are strings of the form <input>:[+]<output>, where the optional + indicates append. If the string is empty, or if either <input> or <output> are empty then the input and/or output streams are set to point to /dev/null.

5. Examples

Refer to the libblock example.

6. Adding Nmi Classes

New nmi::Nmi derived classes must be added within `matnmi.cc'. A string must be chosen to identify the new class. Refer to the `matnmi.cc' for details and examples.

In addition, the configure script can be altered to reflect the availability of the new package, and allow it to be selected during the build configuration. Refer to the `configure.ac' for details and examples.

7. Troubleshooting

If the function does not compile or does not load refer to the Matlab documentation for debugging C-MEX files. The Matlab mex compiler may be incorrectly configured for the user's environment. First verify that the mex compiler is working for both C files and C++ files. Note that C++ files are not officially supported by Matlab, though example and test files do exist within most distributions. Refer to the Matlab documents regarding the use of C++ files with the mex compiler.

Concept Index

Table of Contents

1. Notices
2. Introduction

2.1 Companion Software
2.2 Obtaining
2.3 Other Documentation

3. Installation

3.1 Dependencies
3.2 Platforms
3.3 Required Build Tools
3.4 Building
3.5 Environment

4. Using the nmi() Function
5. Examples
6. Adding Nmi Classes
7. Troubleshooting
Concept Index

Short Table of Contents

1. Notices
2. Introduction
3. Installation
4. Using the nmi() Function
5. Examples
6. Adding Nmi Classes
7. Troubleshooting
Concept Index

About this document

• 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