tempus mex-system User's Guide

tempus mex-system User's Guide

Contents

Introduction
How mex-systems work
Overview of basic mex-systems procedures
Compiling mex-systems
Matlab handle-based logic
Initializing mex-systems
Setting parameter values in mex-systems
Executing mex-systems
Accessing tempus system outputs in mex-systems
Setting system inputs in mex-systems
Recording data to trf files in mex-systems
Deleting mex-systems
Using multiple mex-systems within a single Matlab session
Using the trm with mex-systems
Debugging mex-systems
Sending mex-systems to other Matlab users
t-functions: Using mex-systems to create Simulink s-functions

Related Documents

tempus mex-system mfiles Documentation Index
tempus Matlab mfiles Documentation Index
tempus m-system User's Guide
tempus tve User's Guide
tempus Runset Monitor (trm) User's Guide

Introduction

tempus runsets are saved with auto-generated code which allows tempus systems to be executed from the Matlab command line as Matlab mex-functions. We call such tempus systems mex-systems. The mex-system interface allows users to create the systems, view and modify the default parameters, turn on and off recording of outputs to trf files, incrementally execute the systems for specified periods of virtual time, and access system outputs which have been computed. These capabilities allow mex-systems to be seamlessly incorporated into Matlab processing and facilitates very efficient interactive investigations and visualization of tempus system results.

In the syntax descriptions below, items in bold type are to be entered verbatim, items in italics are substituted with more specific information, items preceding ellipses (...) can be repeated, items contained in quotation marks (" ") must go together and the quotation marks are not to be specified, single-ticks (' ') are used as string delimiters and must be specified, and items in braces ({ }) are optional. Many of the syntax descriptions include underlined type indicative of hyperlinks.

How mex-systems work

The tve runset editor is used to define the top-level input parameters of the tempus system that is to be executed. Through the use of run variables and system parameter settings the user configures complex sets of inputs to be provided to the tempus system. Loop variables can be used to set up a parameter space over which multiple executions of the same tempus system can be made. Finally, the runset editor generates the C++ source code which results in initialization of inputs and execution of the tempus system. When the tve runset editor saves a runset, the following C++ source code files are generated:

systemRunrunset.cpp: the standalone version which, when compile and invoked, causes execution of the runs described by the runset. The resulting program runs as an independent process and is usually initiated from the tve runset editor.
mexsystemRunrunset.cpp: the mex-file version which can be manipulated and executed via a variety of Matlab procedures.

where system is the name of the top-level tempus system and runset is the name of the runset as specified to the runset editor.

tempus runsets can be valid as both a standalone and a mex-system runset. However, the resulting functionality is somewhat different. For example, in standalone runsets, complex systems of loop variables are often created to allow a parametric set of runs to be executed in a single runset. Whereas in the mex-system, the parameterization of the system is intended to be carried out at the Matlab command line level. Therefore, the run variables and loop variables are treated somewhat differently but consistently. In particular, the runset editor generates mex-system code which does not loop over loop variables. Instead the loop and run variables are interpreted in such a way as to allow their use in the parameter setting syntax but not as a mechanism to execute multiple runs. This approach makes it feasible for the user to maintain a runset which is both a valid standalone system as well as a mex-system without having to make adjustments to the parameter setting expressions.

The user is provided with a toolbox of Matlab routines which compile, configure, execute, and interrogate the mex-system. The remainder of this guide describes the process of using mex-systems within Matlab.

Overview of basic mex-systems procedures

mex-systems can be used in very complex and sophisticated ways. However, their basic use is simple. Suppose that we have saved a runset called d1 for a tempus system called Demo. This results in the creation of a source code file named mexDemoRund1.cpp. After starting Matlab and changing the current directory to the directory in which the source file resides, the user can begin the process of running the mex-system.

A toolbox of Matlab functions are provided to facilitate mex-system execution. Of course, the directory containing the routines must be placed in the Matlab path. Then the mex-system must be compiled to create a .dll file necessary for execution. To do this we use the following command in Matlab:

� tmxmkdll('DemoRund1') % Compile mexDemoRund1.cpp to create mexDemoRund1.dll.

Assuming that the default runset and parameter setting are sufficient, the user can create a handle to an executable mex-system with the following function:

� tmxh = tmxcreate('DemoRund1') % Create an initialized instance of the mex-system and assign a handle to tmxh.

Provided the user is satisfied with the default recording configuration, he can execute the system with:

� tmxh = tmxrun(tmxh, 0.001) % Execute the mex-system until simulation virtual time 0.001 seconds and store the resulting handle back in tmxh.

The user can now obtain the current values of any of the mex-system outputs for which there is a defined conversion from the tempus object type to the Matlab types (see the section "m-system interface tempus object types" in the tempus m-system User's Guide for a list of the types). The following command gets the value of an output named camera.fpaImage and displays it in an image plot:

� d1 = tmxload(tmxh, 'camera.fpaImage') % Obtain the value of specified output and store it in d1.
� imagesc(d1.x, d1.y, d1.g) % Display the image.

The user can now continue the execution of the system with:

� tmxh = tmxrun(tmxh, 0.002) % Execute the mex-system from 0.001 until simulation virtual time 0.002 seconds.

The outputs can be again evaluated and manipulated:

� d2 = tmxload(tmxh, 'camera.fpaImage') % Obtain the value of specified output and store it in d2.
� imagesc(d2.x, d2.y, d2.g-d1.g) % Display the difference between the output at 0.001 and 0.002 seconds.

When the user is all done with the mex-system, he should delete it in order to properly close the resulting trf file and avoid memory leaks within the Matlab session with the following command:

� tmxh = tmxdel(tmxh) % Delete the mex-system and store a null handle in tmxh.

There are a number of other operations that the user can perform on the mex-system such as setting and evaluating parameter values, change recording options, and querying other information about the underlying tempus system. These operations are described in the following sections.

Compiling mex-systems

mex-systems must be compiled from their generated C++ source code (.cpp file) to relocatable object code (.dll file). To accomplish this, the following commands are used:

� cd dir % Change the working directory to dir, the directory where the mex source code resides.
� tmxmkdll('sysRunrunset') % Compile the file mexsysRunrunset.cpp to create mexsysRunrunset.dll.

If the file mexsysRunrunset.cpp does not exist or has errors, a series of error messages will be printed and the .dll file will not be created. Upon successful compilation the file mexsysRunrunset.dll is available for use as a mex-system.

As long as the underlying tempus system and runset is not meant to be changed, mex-systems only need to compiled once. In fact, the mex-system is a standalone Matlab mex-function which can be given to users who do not have the entire tempus/WaveTrain installation. See the section "Sending mex-systems to other Matlab users" for more information.

Matlab handle-based logic

mex-systems are implemented using handle-based logic inside Matlab. Essentially this means that the user is provided a data variable, a tmx_handle, which represents the current state of a mex-system. All operations which modify the mex-system return a modified handle and the original handle is assumed to be invalidated. Therefore, the user is encouraged to assign a particular name to a mex-system handle and to continue using that same name as it is modified. The following group of commented commands should clarify the issue:

� t1 = tmxcreate('Demo1Runt1'); % Create the mex-system handle and store it in t1.
� t2 = tmxrun(t1, 0.001);    % Bad idea. The mex-system is properly run but the invalid handle t1 is left lying around and might accidentally be used resulting in problems.
� clear t1;    % That's better. At least we got rid of t1 and we cannot accidentally use it.
� t2 = tmxrun(t2, 0.002);    % Now we run the mex-system and we assign the resulting handle to a variable of the same name.
� tmxdel(t2, 0.002);    % Again a bad idea. Here t2 is still lying around pointing to a deleted mex-system. This could cause real problems.
� clear t2;    % At least we got rid of t2.
� t1 = tmxcreate('Demo1Runt1'); % Now we'll start over and do it right.
� t1 = tmxrun(t1, 0.001);    % We store the new handle in the variable of the same name.
� d = tmxload(t1, 'camera.fpaImage');    % This does not modify the handle so no issue here.
� t1 = tmxdel(t1);    % And when we delete t1 is set to the null array so it cannot be accidentally used.

The user should not abort a tmx command using Crtl-C at the Matlab command level. Doing so will cause unpredictable results. See the section "Using the trm with mex-systems" on information about interrupting mex-system execution.

Initializing mex-systems

mex-systems must be initialized before they can be executed. For this, the user employs the tmxcreate command to obtain a handle to a mex-system:

tmxh = tmxcreate('sysRunrunset') % Create a mex-system handle using the mexsysRunrunset.dll. The resulting mex-system is initialized using the default setting expressions for all run variables and parameters.

The resulting variable, tmxh, is a tmx_handle structure containing information specific to the mex-system. The user may interrogate the values of the fields in this structure, but he must not modify them in any way. The structure is meant to be modified by tmx routines only. Doing otherwise will cause unpredictable results, including Matlab system crashes and incorrect mex-system behavior.

As described in following section, an optional argument to tmxcreate can specify non-default run variable and parameter values.

Setting parameter values in mex-systems

mex-systems provide a convenient mechanism for setting their parameters prior to system execution. Suppose that for the DemoRund1 mex-system described previously, we wish to execute a number of cases where one of the parameters changes. To obtain a structure specifying the parameters that can be changed and their default values, we execute the following command prior to creating the system:

� params = tmxparams('DemoRund1') % Get a list of parameters and default values for the specified mex-system.

The resulting params structure fields have the names of all the run variables and parameters of the top-level system (see the description of the tmx_param structure). The values of those parameters are strings showing the tempus object type, name, and default value of each variable. If the user changes the value of a fields, that value will be used rather than the default setting expression. But values which are not changed, will be set using the default setting expression which can involve computations. Because run variable and parameter values are allowed to be set according to fairly arbitrary expressions which can be dependent on the values of other run variables and parameters, it is not sufficient to simply keep track of the value the parameters in the structure.

Some of the fields in the params structure have names encompassed in braces ({ }). These run variables and parameters are of tempus object types which have no predefined conversion to Matlab types and therefore cannot be set using this mechanism. However, these parameters can still be affected by parameter value changes in Matlab because their default values can be expressions dependent on the value of other parameters which can be modified.

The following commands can be used to change a parameter named range and execute the mex-system:

� params.range = 10000.0    % Set a parameter to a value other than its default.
� tmxh = tmxcreate('DemoRund1', params)    % Create an instance of a mex-system using the parameters defined by params rather than the defaults.
� tmxh = tmxrun(tmxh, 0.001)    % Run the system.

We can get even fancier. The following commands run a loop which varies the parameter over a range of interest:

� params = tmxparams('DemoRund1')    % Get a list of parameters and default values for the specified mex-system.
� for ii=1:10,...
�    params.range = ii*5000.0;...    % Increase the range in increments of 5000.
�    tmxh = tmxcreatee('DemoRund1', params);...    % Create an instance of a mex-system.
�    tmxh = tmxrun(tmxh, 0.001) ;...   % Run the system.
�    res{ii} = tmxload(tmxh, 'camera.fpaImage');...    % Get an output from the run.
�    tmxh = tmxdel(tmxh);...    % Delete the mex-system.
� end;

Now the cell array res can be used to show the mex-system's dependence on the parameter range.

The values of the fields in the structure returned by tmxparams contain text strings which indicate the tempus object types, names, and default values. The mex-system uses these values as a key to indicate whether or not the default computation ought to be used in calculating the parameter. Unfortunately, this approach results in the user not being able discern the precise values of the parameters from the tmxparams result. To compensate for this the tmxcompparams function provides the user the values of those parameters which can be represented in Matlab. The following command computes the default parameters and places them in a structure with the same fields as those defined in the previous params structure:

� cparams = tmxcompparams('DemoRund1') % Compute the default values of the mex-system parameters.

Because parameters calculated using their default setting expressions can be affect by the non-default values of other parameters, the user can also give tmxcompparams a structure containing a mix of default and non-default values as in the following commands:

� params = tmxparams('DemoRund1');    % Get a list of parameters and default values for the specified mex-system.
� params.range = 5000.0;    % Set range to a non-default value.
� cparams = tmxcompparams('DemoRund1', params);    % Evaluate all parameters given some that are not set to their default values.

The structure returned by tmxcompparams can also be provided to tmxcreate to specify parameter values, but this must be done with a complete understanding of the dependencies between parameters. For example, in the following series of commands:

� params = tmxparams('DemoRund1');
� cparams = tmxcompparams('DemoRund1', params);
� params.range = 5000.0;
� cparams.range = 5000.0;
� tmxh1 = tmxcreate('DemoRund1', params);
� tmxh2 = tmxcreate('DemoRund1', cparams);

the systems created by the two calls two tmxcreate may not be the same. This is because in the params case, parameters dependent on range will be calculated differently than in the case of the cparams because default setting expressions for params were evaluated after params.range was set.

Setting parameter values within Matlab must be done carefully. Nothing in tempus enforces setting parameters to valid values. Where mex-systems may be expecting a 2-element vector, the user could instead pass a text string. In such cases, the mex-system will almost certainly not execute properly and may even crash the Matlab session. Users experimenting with mex-systems are advised to do so carefully and to save Matlab session variables often when an accidental crash would be major inconvenience.

Executing mex-systems

Once created, a mex-system can be executed and re-executed using the tmxrun command. The initial virtual time of a tempus system is assumed to be zero. The following series of commands demonstrate the use of tmxrun:

� tmxh = tmxrun(tmxh, 0.001);    % Execute the from the current time to 0.001 seconds.
� tmxh = tmxrun(tmxh, 0.001);    % This has no effect because we are already at 0.001 seconds.
� tmxh = tmxrun(tmxh, 0.004);    % Now we go to 0.004 seconds.

Choosing the length of time for the simulation to proceed is purely up to what the user. However, attempting to interrupt the execution of the mex-system with Ctrl-C will cause unpredictable results. You can, however, interrupt the execution using the trm. See the section "Using the trm with mex-systems" for more information.

Combined with other calls, the tmxrun command can be used to track the status of variables as a function of simulation virtual time:

� tmxh = tmxcreate('DemoRund1', params);...    % Create an instance of a mex-system.
� for ii=1:10,...
�    tmxh = tmxrun(tmxh, ii*0.001) ;...   % Run the system for a millisecond.
�    res{ii} = tmxload(tmxh, 'camera.fpaImage');...    % Get an output at the current simulation time.
� end;
� tmxh = tmxdel(tmxh);    % Delete the mex-system.

Now the cell array res can be used to show the mex-system's dependence on time.

Accessing tempus system outputs in mex-systems

Within a mex-system every tempus subsystem output for which there is a conversion from tempus object type to Matlab data type can be can be accessed from the Matlab command line using the tmxload command. A list of the outputs that can be loaded is obtained using the tmxoutls command:

� tmxoutls(tmxh); % List all outputs which can be accessed via the tmxload command.

To obtain the current value of an output use the tmxload command:

� d = tmxload(tmxh, 'simplefieldsensor.field'); % Load the specified output.

The structure and content of the result is dependent on the tempus object type and size of the output which is being accessed.

It is possible for a request to evaluate an output to result in a mex-system crash which will in turn cause a crash of the Matlab system. This can occur if the user requests an output which has not yet been computed because the computation is dependent on other computations which have not yet been executed. This situation cannot be detected with 100% accuracy in tempus, so to avoid this situation, the user cannot execute the tmxload command until the tmxrun command has been executed on the mex-system at least once.

Setting tempus system inputs in mex-systems

In order to allow dynamic interactions between Matlab code (including Simulink block diagrams) and mex-systems, users are provided a mechanism to change the values of inputs to mex-systems. To do this, the top-level tempus system must have external inputs. For example, in the following top-level block diagram, the inputs beam and tilts may be modified by the user:

The inputs which can be set must be from the set of types for which there is a defined conversion from the tempus object type to the Matlab types (see the section "m-system interface tempus object types" in the tempus m-system User's Guide for a list of the types).

To change the value of an input, the user employs the tmxsetinp command as in the following command series:

� tmxmkdll('PSTrackRuna'); % Compile the mex-system.
� tmxh = tmxcreate('PSTrackRuna'); % Create the mex-system handle and store it in tmxh.
� tmxh = tmxrun(tmxh, 0.001); % Run the system out to 0.001 seconds. The default inputs are used.
� fpa1 = tmxload(tmxh, 'camera.fpaImage'); % Get the FPA image.
� tmxh = tmxsetinp(tmxh, 'tilts', [1.0e-06, -4.0e-06]); % Set the value of the tilts input.
� tmxh = tmxrun(tmxh, 0.002); % Run the system out to 0.002 seconds. The new tilts are used.
� fpa2 = tmxload(tmxh, 'camera.fpaImage'); % Get the FPA image with the new tilts.
� tmxh = tmxdel(tmxh); % Delete the handle.
� figure; imagesc(fpa1.g); figure; imagesc(fpa2.g); % Plot and compare the images.

Just to be safe, mex-system creators should always set up the top-level system inputs with valid default values. This will help to avoid crashes in the case that a user forgets (or does not wish to) set an input. In this example, the tilts are set to zeros and the default beam is a top-hat.

tempus systems are necessarily time-dependent. If there are delays in the data flow of a mex-system, it can be easy for a user to be confused when his input setting does not seem to be reflected in the system outputs. Hence, the user must be cognizant of any delays and appropriately advance the system time sufficiently (through a call to tmxrun) to allow inputs to take effect.

Setting inputs from within Matlab must be done carefully. Nothing in tempus enforces setting inputs to valid values. Where mex-systems may be expecting a 2-element vector, the user could instead pass a text string. In such cases, the mex-system will almost certainly not execute properly and may even crash the Matlab session. Users experimenting with mex-systems are advised to do so carefully and to save Matlab session variables often when an accidental crash would be major inconvenience.

Presently there is no mechanism for listing the inputs which can be changed from within Matlab. For now the user is expected to inspect the block diagram to determine which inputs can be changed. In later versions of the software, we will add tmxinp and tmxinpls commands for listing modifiable inputs.

Recording data to trf files in mex-systems

Like standalone tempus runsets, mex-systems record user-selected outputs to trf files. The user is provided with mechanisms to adjust recording operations within a mex-system. In fact, because mex-systems can be executed incrementally and recording can be changed mid-run, the recording capabilities within a mex-system are somewhat more flexible than that within a standalone runset.

By default a mex-system will record outputs as configured within the tve runset editor. The user can determine which outputs are to be recorded using the following command:

� recdef = tmxout(tmxh, 'def'); % Get a list of the outputs to be recorded by default.

recdef is now set to a structure containing the name and recording parameters of those outputs set to be recorded in the tve runset editor. See the section on tmx_recout for detailed information about this structure.

The user can change which outputs are to be recorded by specifying the names of the outputs to be recorded. For example, the following command will cause the system to record an output named simplefieldsensor.fld:

� tmxh = tmxrecon(tmxh, 'simplefieldsensor.field'); % Turn on recording for the specified output on a "when changed" basis.

Specifying only the name of the output causes it to be recorded whenever its value has been changed. To record once every 0.001 seconds, we have to create a structure which specifies all of the recording parameters:

� r.name='simplefieldsensor.field'    % Specify the name in the structure.
� r.whenchanged=false;    % We are not recording when changed, but at a fixed rate.
� r.atleastrate=0;    % We aren't using atleastrate, but it must be in the structure.
� r.exactlyrate=0.001;    % Now we specify the rate at which recording is to occur.
� tmxh = tmxrecon(tmxh, r);    % We turn on the recording using the structure r.

When the recording parameters are changed, the user can determine for which outputs recording is turned on:

� recon = tmxout(tmxh, 'on'); % Get a list of the outputs currently set to be recorded.

recon is now set to a structure containing the name and recording parameters of those outputs presently set to be recorded.

A structure containing those parameters which are not to be recorded can be obtained:

� recoff = tmxout(tmxh, 'off'); % Get a list of the outputs which are not currently set to be recorded.

recoff is now set to a structure containing the name and recording parameters of those outputs which are not presently set to be recorded.

The user can get a list of all outputs regardless of whether they are set to be recorded:

� recall = tmxout(tmxh, 'all'); % Get a list of all outputs.

The user can turn off the recording of outputs previously set for recording:

� tmxh = tmxrecon(tmxh, 'simplefieldsensor.field'); % Turn off recording for the specified output.

All of these commands can be interleaved with calls to tmxrun. So if these are specific periods of interest concerning certain outputs, the user can be selective about recording. The following code segment shows how this can be used.

� tmxh = tmxcreate('DemoRund1');    % Create the system.
� tmxh = tmxrecoff(tmxh);    % Turn off all recording. Specifying no outputs turns them all off.
� tmxh = tmxrun(tmxh, 0.005);    % Run for 0.005 seconds.
� tmxh = tmxrecon(tmxh,tmxrecs(tmxh,'def'));    % Turn on all default recording as set in the tve runset editor.
� tmxh = tmxrun(tmxh, 0.006);    % Run for another 0.001 seconds.
� trfname = tmxh.trfname; % Remember the name of the trf file.
� tmxh = tmxdel(tmxh);    % Delete the system and close its trf file.
� trfh = trfopen(trfname);    % Open the resulting .trf file.
� d = trfload(trfh);    % Load the .trf data.

The user can view a text list of the output names using the following commands:

� tmxoutls(tmxh,'all');    % List all outputs which could be recorded.
� tmxoutls(tmxh);    % List all outputs which could be recorded (same as above).
� tmxoutls(tmxh,'def');    % List all outputs recorded by default.
� tmxoutls(tmxh,'on');    % List all outputs which will be recorded.
� tmxoutls(tmxh,'off');    % List all outputs which will not be recorded.
� tmxoutls(reclist);    % List all outputs in the specified tmx_recout structure.

Deleting mex-systems

When the user is all done with the mex-system, he should delete it in order to properly close the resulting trf file and avoid memory leaks within the Matlab session with the following command:

� tmxh = tmxdel(tmxh) % Delete the mex-system and store a null handle in tmxh.

Using multiple mex-systems within a single Matlab session

There are a few rules about using multiple mex-systems within a single Matlab session. In particular:

Results will be unpredictable and a crash may result if the user creates a mex-system of the same runset as one that is already open. The first mex-system must be deleted before another can be created. If it is really necessary to have two such systems simultaneously, the user can have the tve store an identical copy of the runset using a different name, compile it, and use the resulting mex-system simultaneously with the other. Operating on two copies of the same mex-systems at one time may cause Matlab to crash and/or incorrect results.
The user may simultaneously operate on any number of mex-systems as long as none of them are the same mex-system.

Using the trm with mex-systems

The tempus runset monitor (trm) can be used to monitor execution of the mex-system. Once the mex-system is created using tmxcreate, the user may use trmrun instead of tmxrun to coordinate execution with the trm. The difference between trmrun and tmxrun is that trmrun will start the trm if it has not been previously started for the same mex-system handle.

Once a mex-system handle has been created, use the command trmrun to run the mex-system in concert with the trm:

� tmxh = trmrun(tmxh, 0.1);

This will start the trm in its default Matlab layout and connect it to the running mex-system:

The pause button can be used suspend execution. Once suspended, the trm will look like this:

While the mex-system is paused, the Matlab command window is also suspended and cannot be accessed for command input. In fact, Matlab will not update any window, including graphics, while in this suspended state. The user can push the run button to continue execution.

While running, the user can push the stop button to cause the mex-system to stop execution and return control to Matlab. Stopping execution this way does not have an adverse effect on the mex-system. Execution of the mex-system can be resumed with another call to tmxrun or trmrun.

The user can terminate the trm (without any effect on the mex-system) using the close button . The trm User's Guide provides detailed information on using the trm. The Matlab commands trm and trmcreate can also be used to coordinated mex-system execution with the trm.

Debugging mex-systems

Users that have access to the tempus and WaveTrain source code can debug mex-systems using the Microsoft Visual Studio debugger. To debug mex-systems, take the following steps:

Make sure that the source code for tempus and WaveTrain is installed on the machine. Debugging without the source is not very useful. However, if the user has written his own tempus systems, it is possible to set breakpoints in these tempus systems without accessing the main tempus and WaveTrain source code.
Start a normal Matlab session.
When compiling the mex-system with tmxmkdll, specify the debug option. That is, specify the command:

tmxmkdll('sysRunrunset','debug').

Find the process id for Matlab with the following command at the Matlab command prompt:

!tasklist|find /i "Matlab"

The process id is the number in the second column:

MATLAB.exe 5028 Console

Start a Microsoft Visual Studio session from the Matlab command line in the directory containing the mex-system files using the following command:

!vsJITDebugger.exe -p PID

where PID is the Matlab process id number, e.g., 5028.

Load the cpp file and .h file for the mex system into the Visual C++ Editor. The names will be mexsysRunrunset.cpp and sys.h, e.g. “mexDemoRunat1.cpp” and “Demo.h”. You can optionally load any other source files that belong to your system.
In Visual Studio the user can now use the debugging commands to set breakpoints, for instance in the mexsystemRunrunset.cpp and system.h files, to cause execution to halt. Then in the Matlab command line window, the user can use tmx commands to create and run an instance of the mex-system. The user can then use standard debugger traversal techniques to monitor code execution.

Sending mex-systems to other Matlab users

mex-systems can be executed by Matlab users who do not have tempus installed on their computers. To do this, copy the following files from a machine with a tempus installation to the non-tempus machine:

%TEMPUS_DIR%\msvc6\bin\*.dll
%TEMPUS_DIR%\msvc6\bin\trm.exe (only necessary if the trm will be used).
%TEMPUS_DIR%\mfiles\trf.tbx\*.m
%TEMPUS_DIR%\mfiles\tbx.tbx\*.m
mexsystemRunrunset.dll as generated by tmxmkdll.

The general tempus and WaveTrain licenses allow users to distribute these files to non-licensed users. The .dll files must be placed in a directory which appears in the execution PATH and the .m files must be placed in a directory which appears in the MATLAB_PATH. The user may then execute all tmx commands except for tmxmkdll which must be executed on a machine on which tempus is installed.

A good way to send a mex-system to a user is to use a tool like WinZip to put all of the above specified files into a single .zip file and e-mail the file. The recipient can then unzip the file into a directory, place the directory in both the system PATH and MATLAB_PATH and then execute. Of course, if the user already has copies of the fixed files (1 through 4) one only needs to send the new mex-system mexsystemRunrunset.dll (5).

t-functions: Using mex-systems to create Simulink s-functions

tempus mex-systems can be used to construct s-functions for Simulink execution. Borrowing an unused letter, such tempus s-functions are called t-functions. There is nothing fundamentally special about the t-function interface. In fact, t-functions are written by wrapping a standard m-file s-function around the mex-function.

Using a combination of tmx routines, m-file s-function can be written to interface with mex-systems. Such t-functions have the following properties:

mex-system parameters may be set and manipulated using standard Simulink mechanisms.
All mex-system external inputs can be mapped to s-function inputs or discrete states.
All convertible mex-system subsystem outputs can be mapped to either discrete states or system outputs.
Where the mapping between mex-system and Simulink is not straight-forward, the m-file implementation allows the user to write simple interface code which takes care of such issues.

Because of the significant generality of the s-function interface and because the mapping of mex-system inputs and outputs to Simulink inputs and outputs must be handled on a case-by-case basis, there is no "standard" t-function interface. Instead, an m-file template (tfuntmpl.m) is provided to demonstrate how mex-systems can be interfaced with Simulink. To use this template the user takes the following steps:

Using the tempus tve, create a mex-system with parameters, inputs, and outputs which are to be mapped to t-function parameters, inputs, and outputs.
Compile the mex-system using tmxmkdll.
Edit the tfuntmpl.m file (in the same directory as the tmx routines), following the instructions marked by the text "T-FUNCTION".
Save the edited file using a unique t-function name and filename in a directory which will be in the Matlab path.
Insert an s-function block into a Simulink block diagram, specifying the appropriate parameters and connecting the inputs and outputs as planned.
Execute the resulting Simulink system.

It is generally necessary that in order to write a t-function, the user understand how to write an s-function. So the t-function documentation must be taken in the context of the s-function documentation provided by Matlab.

It is not possible to use two instances of a mex-system simultaneously. To use multiple instances of mex-systems and related t-functions, the user must artificially create separate .dll and .m files for each and insert them in the Simulink block diagram as if they were distinct systems.