Introduction to MATLAB Cosimulation

The MATLAB® models provide an interface between ADS Ptolemy and MATLAB, a numeric computation and visualization environment from The MathWorks, Inc. All ADS Ptolemy MATLAB Cosimulation models can be found in the Numeric Matlab palette and library on the DSP Schematic.

ADS provides the Import MATLAB Function Tool, an easy-to-use wizard interface enabling a user to create custom MATLAB models. These models can be for a MATLAB script, .m file function, or built-in MATLAB function. The wizard generates models that are essentially subnetworks containing one of the core infrastructure models listed in the following table. To learn more about the Import MATLAB Function Tool see Importing MATLAB Functions. For details about the MATLAB models, see MATLAB Blocks.

ADS Ptolemy handles the conversion of data to and from MATLAB. Since MATLAB Cosimulation involves multiple environments and associated inter-process communication, the installation and pre-simulation configuration must be precise and correct for the infrastructure to work as expected. To ensure proper operation, the instructions provided in Setting Up MATLAB Cosimulation must be followed as described whether or not the model is built into ADS Ptolemy or is user-defined.

MATLAB Models Built into ADS Ptolemy
Type of MATLAB Model Description Model Name
Models that interpret a MATLAB script The script can contain a function, command, statement or several statements. MatlabCx_M
MatlabFCx_M
MatlabF_M
MatlabSink
MatlabSinkF
Matlab_M
Models that can compile and import a MATLAB function as a shared library The function can be implemented in a .m file or a pre-compiled shared library. MatlabLibLink
MatlabLibLinkCx
Models that call specific MATLAB built-in functions These models are available in the DSP schematic's Numeric Matlab palette and library. AwgnCx
EigCx_M
Erf
Erfc
Norm_M
RandDeintrlv
RandIntrlv
SVD_Cx_M

Supported MATLAB Versions

ADS Ptolemy MATLAB Cosimulation requires MATLAB and supports these MATLAB versions:

Note
MATLAB Cosimulation is supported only on native 32-bit platforms or through 32-bit compatibility mode on 64-bit platforms.

Setting Up MATLAB Cosimulation

MATLAB must be configured correctly before using cosimulation. If a MATLAB model is run and MATLAB is not configured correctly, ADS Ptolemy will report an error. See On Windows or On UNIX for platform-specific configuration information.

On Windows

For most Windows users, ADS Ptolemy MATLAB Cosimulation will work as expected when MATLAB and ADS are installed. Only the PATH environment variable must be set after installing ADS and MATLAB. This will support script-mode, library-importing mode, and MATLAB compiler use. The PATH environment variable should include the bin directory under the MATLAB root directory. This example shows how PATH can be set:

set PATH=<matlabroot>\bin\win32;%PATH%

Typically, PATH is set by the MATLAB installer which also registers the COM components in the Windows registry.

To manually register COM components run

matlab /regserver

This may be necessary if you have multiple versions of MATLAB on your system and ADS Ptolemy MATLAB Cosimulation fails with an error Matlab could not be invoked.

Using MATLAB Cosimulation library-importing mode which requires precompilation requires additional configuration; for details, see Finishing the MATLAB Compiler Configuration.

On UNIX

The configuration process uses the configuration file hpads.cfg. For more details on the hpads.cfg file, see Customizing the ADS Environment.

Set the MATLAB configuration variable to point to the root of your MATLAB installation. An example of this setting is:

MATLAB=/usr/local/matlab

If the command to invoke MATLAB is not matlab , set the MATLABCMD configuration variable to the correct command. For example, you might set it to

MATLABCMD="matlab -c /path/to/license/file"

so that matlab correctly finds its license file. Typically, you will not need to set the MATLABCMD variable.

Alternatively, you can configure all the variables required for MATLAB cosimulation without using the hpads.cfg file. In this case, you must configure the following environment variables. The example commands below assume you are using a C-shell or equivalent; modify this command as needed for other shells.

Finishing the MATLAB Compiler Configuration

To complete the MATLAB compiler configuration on all supported platforms, one additional step is required. The MATLAB compiler must know which native C++ compiler to use to compile the C++ wrapper files it generates. This can be selected by running the following script on all platforms:

mbuild -setup

This is a one-time step per user and need not be repeated.

To verify that the MATLAB compiler has been configured correctly, run the command:

mcc

from the command line. Usage of mcc and command line options will be displayed if mcc has been configured correctly.

Simulating with MATLAB (Script-Interpreting)

MATLAB distinguishes between complex matrices and floating-point (real) matrices. ADS Ptolemy distinguishes between models that produce data and models that do not. The following table lists six script-interpreting MATLAB models available in ADS Ptolemy; two produce floating-point (real) matrices, two produce complex-valued matrices, and two are sinks that do not produce data. All models can accept any number of inputs provided that the inputs have the same data type, either floating-point (real) or complex.

Script-Interpreting ADS Ptolemy Models
Model Description
Matlab_M Evaluates a MATLAB expression and outputs results as floating-point (real) matrices.
MathlabF_M Evaluates a MATLAB script file and outputs results as floating-point (real) matrices.
MatlabCx_M Evaluates a MATLAB expression and outputs results as complex-valued matrices.
MathlabFCx_M Evaluates a MATLAB script file and outputs results as complex-valued matrices.
MatlabSink Evaluates a MATLAB expression a fixed number of times.
MatlabSinkF Evaluates a MATLAB script file a fixed number of times.

These models use a common MATLAB engine interface that is managed by a base MATLAB model. The base model does not have any inputs or outputs. It provides methods for starting and killing a MATLAB process, evaluating MATLAB commands, managing MATLAB figures, changing directories in MATLAB, and passing ADS Ptolemy matrices into and out of MATLAB. Currently, the base model supports 2-D real and complex-valued matrices only.

The MATLAB interpreter's working directory is set to the ScriptDirectory parameter, if it is given. Any custom MATLAB models will be searched from there, and any output files will be written there.

Figures generated by a MATLAB model are managed according to the value of the DeleteOldFigures parameter. If this parameter is set to Yes, the MATLAB model will close any MATLAB plots or graphics when it is destroyed. If set to No, the figures must be closed manually.

Writing Functions for MATLAB Models (Script-Interpreting)

There are several ways in which MATLAB commands can be specified in the MATLAB models in the MatlabFunction parameter.

If only a MATLAB function name is given for this parameter, the function is applied to the inputs in order. The function's outputs are sent to the model's outputs.

For example, specifying eig means to perform the eigendecomposition of the input. The function will be called to produce one or two outputs, according to how many output ports there are. If there is a mismatch in the number of inputs and outputs between the ADS Ptolemy model and the MATLAB function, then an error will be reported by MATLAB.

You may also explicitly specify how the inputs are to be passed to a MATLAB function and how the outputs are taken from the MATLAB function. For example, consider a two-input, two-output MATLAB model to perform a generalized eigendecomposition. The command

[output#2, output#1] = eig( input#2, input#1 )

says to perform the generalized eigendecomposition on the two-input matrices, place the generalized eigenvectors on output#2, and the eigenvalues (as a diagonal matrix) on output#1. Before this command is sent to MATLAB, all "#" characters are replaced with the underscore character "_" because "#" is illegal in a MATLAB variable name.

The MATLAB models also allow a sequence of commands to be evaluated. Continuing with the previous example, we can plot the eigenvalues on a graph after taking the generalized eigendecomposition:

[output#2, output#1] = eig( input#2, input#1 ); plot( output#1 )

When entering such a collection of commands in ADS Ptolemy, both commands appear on the same line without a new line after the semicolon. In this way, very complicated MATLAB commands can be built up. We can make the plot of eigenvalues always appear in the same plot without interfering with other plots generated by other MATLAB models with this function (new lines are inserted after the semicolons to improve readability):

[output#2, output#1] = eig( input#2, input#1 );
if ( exist(`myEigFig') == 0 ) myEigFig = figure; end;
figure(myEigFig);
plot( output#1);

The MatlabSetup and MatlabWrapUp parameters are called during the model's begin and wrap-up procedures. When used in Matlab_M or MatlabF_M components, these parameters can refer to a *. m file. During each of these procedures, data is not passed into or out of the model.

Because the same MATLAB interpreter is used for the entire simulation, variables are preserved from iteration to iteration. For example, the output of a Matlab_M model with settings:

MatlabSetUp = "x=ones(2;1)"
MatlabFunction = "output#1=x(2)/x(1); x=[x(2),sum(x)];"

will converge on the golden mean. It is impossible, however, to share variables between different MATLAB components. Such a simulation would be non-deterministic.

Simulating with MATLAB (Library-Importing)

Two models allow cosimulation between MATLAB and ADS through a native shared library. In MATLAB Version 6.5 (Release 13), shared library mode provides substantial speed improvement over script-interpreting mode. However, in MATLAB Versions 7.1 and 7.3 (Releases 14 and 2006b), the MATLAB Compiler does not generate native C/C++ code, but rather an intermediate bytecode format that is interpreted at run time by the MATLAB Compiler Runtime (MCR). According to MathWorks, this effectively makes the performance of the shared library mode to be on par with script-interpreting mode. If simulation performance is important for your needs, you may continue to use the older supported version of MATLAB.

Note
Library-importing mode is not supported on Linux platforms for any MATLAB versions, and on other UNIX platforms it is supported only for MATLAB Version 6.5. Use script-interpreting mode when library-importing mode is not supported.

The library-importing models use MATLAB Compiler to convert . m script files to shared libraries. This allows the sharing of libraries without exposing source files. You should be able to import a MATLAB .m script file directly without any code change.

The models are:

The models accept the .m script file for matrices evaluation and an optional .m script file for passing setup parameters to the MATLAB environment. You can switch between scripting and shared library modes by changing the Mode parameter. Due to the limitation of the MATLAB Compiler, no figures are supported in the shared library mode.

The shared libraries are compiled in the project/data directory. By default, libraries are also imported from the project/data directory. Make sure that the current directory ".", is in the library search path (i.e., LD_LIBRARY_PATH on Sun, SHLIB_PATH on HP-UX, and PATH on Windows). You can also set the library search path to a specified directory where pre-compiled libraries are located.

Users can manually generate shared libraries with the Matlab Compiler. The exact mcc commands used by ADS are:

MATLAB Version 6.5

mcc -t -W lib:<libname> -T link:lib -h <function name1> <function name2> <...> libmmfile.mlib libmwsglm.mlib

For example, to compile a gain.m file into a library called libmygain, the mcc command to generate a shared library for use with ADS is:

mcc -t -W lib:libmygain -T link:lib -h gain libmmfile.mlib libmwsglm.mlib

MATLAB Versions 7.1 and 7.3

mcc -W lib:<libname> -T link:lib <function name1> <function name2> <...>

For example, to compile a gain.m file into a library called libmygain, the mcc command to generate a shared library for use with ADS is:

mcc -W lib:libmygain -T link:lib gain.m

Examples

ADS Ptolemy provides example projects containing designs demonstrating MATLAB cosimulation. These projects are available from the ADS Main window.

For a project with a design demonstrating how to use MATLAB models, select
File > Example Project > DSP > dsp_demos_prj.
SOMBRERO.dsn is a simple example that plots a SINC function demonstrating how to use several MATLAB models effectively.

For a project with designs demonstrating how to call a MATLAB.m file, select
File > Example Project > DSP > MATLABlink_prj.

 

Privacy Statement  | Terms of Use  | Legal | Contact Us  | © Agilent 2000-2008 

Contents
Additional Resources