1/4/2014

Call MATLAB Functions - MATLAB & Simulink

Call MATLAB Functions

The code generation softw are attempts to generate code for functions, even if they are not supported for C code generation. The softw are detects calls to many common visualization functions, such as p l o t ,d i s p , and f i g u r e . The softw are treats these functions like extrinsic functions but you do not have to declare them extrinsic using c o d e r . e x t r i n s i c . During simulation, the code generation softw are generates code for these functions, but does not generate their internal code. During standalone code generation, MATLAB attempts to determine w hether the visualization function affects the output of the function in w hich it is called. Provided that the output does not change, MATLAB proceeds w ith code generation, but excludes the visualization function from the generated code. Otherw ise, compilation errors occur. For example, you might w ant to call p l o tto visualize your results in the MATLAB environment. If you generate a MEX function from a function that calls p l o tand then run the generated MEX function, the code generation softw are dispatches calls to the p l o tfunction to MATLAB. If you generate a library or executable, the generated code does not contain calls to the p l o tfunction. The code generation report highlights calls from your MATLAB code to extrinsic functions so that it is easy to determine w hich functions are supported only in the MATLAB environment.

For unsupported functions other than common visualization functions, you must declare the functions (like p a u s e ) to be extrinsic (see Resolution of Function Calls for Code Generation). Extrinsic functions are not compiled, but instead executed in MATLAB during simulation (see How MATLAB Resolves Extrinsic Functions During Simulation). There are tw o w ays to declare a function to be extrinsic: Use the c o d e r . e x t r i n s i cconstruct in main functions or local functions (see Declaring MATLAB Functions as Extrinsic Functions). Call the function indirectly using f e v a l(see Calling MATLAB Functions Using feval).

Declaring MATLAB Functions as Extrinsic Functions

To declare a MATLAB function to be extrinsic, add the c o d e r . e x t r i n s i cconstruct at the top of the main function or a local function: c o d e r . e x t r i n s i c ( ' f u n c t i o n _ n a m e _ 1 ' ,. . .,' f u n c t i o n _ n a m e _ n ' ) ; Declaring Extrinsic Functions The follow ing code declares the MATLAB p a t c hfunction extrinsic in the local function c r e a t e _ p l o t : f u n c t i o nc=p y t h a g o r a s ( a , b , c o l o r )% # c o d e g e n %C a l c u l a t e st h eh y p o t e n u s eo far i g h tt r i a n g l e % a n dd i s p l a y st h et r i a n g l e . c=s q r t ( a ^ 2+b ^ 2 ) ; c r e a t e _ p l o t ( a ,b ,c o l o r ) ;

f u n c t i o nc r e a t e _ p l o t ( a ,b ,c o l o r ) % D e c l a r ep a t c ha n da x i sa se x t r i n s i c c o d e r . e x t r i n s i c ( ' p a t c h ' ) ; x=[ 0 ; a ; a ] ; y=[ 0 ; 0 ; b ] ; p a t c h ( x ,y ,c o l o r ) ;

http://www.mathworks.com/help/simulink/ug/calling-matlab-functions.html#bq1h2z9-47 1/5

1/4/2014

Call MATLAB Functions - MATLAB & Simulink

a x i s ( ' e q u a l ' ) ; The code generation softw are detects that a x i sis not supported for code generation and automatically treats it as an extrinsic function. The compiler does not generate code for p a t c hand a x i s , but instead dispatches them to MATLAB for execution. To test the function, follow these steps: 1. Convert p y t h a g o r a sto a MEX function by executing this command at the MATLAB prompt: c o d e g e nr e p o r tp y t h a g o r a sa r g s{ 1 ,1 ,[ . 3. 3. 3 ] } 2. Click the link to the code generation report and then, in the report, view the MATLAB code for c r e a t e _ p l o t . The report highlights the p a t c hand a x i sfunctions to indicate that they are supported only w ithin the MATLAB environment.

3. Run the MEX function by executing this command: p y t h a g o r a s _ m e x ( 3 ,4 ,[ 1 . 00 . 00 . 0 ] ) ; MATLAB displays a plot of the right triangle as a red patch object:

When to Use the coder.extrinsic Construct Use the c o d e r . e x t r i n s i cconstruct to: Call MATLAB functions that do not produce output such as p a u s e during simulation, w ithout generating unnecessary code (see How MATLAB Resolves Extrinsic Functions During Simulation). Make your code self-documenting and easier to debug. You can scan the source code for c o d e r . e x t r i n s i cstatements to isolate calls to MATLAB functions, w hich can potentially create and propagate m x A r r a y s(see Working w ith mxArrays).
http://www.mathworks.com/help/simulink/ug/calling-matlab-functions.html#bq1h2z9-47 2/5

1/4/2014

Call MATLAB Functions - MATLAB & Simulink

Save typing. With one c o d e r . e x t r i n s i cstatement, each subsequent function call is extrinsic, as long as the call and the statement are in the same scope (see Scope of Extrinsic Function Declarations). Declare the MATLAB function(s) extrinsic throughout the calling function scope (see Scope of Extrinsic Function Declarations). To narrow the scope, use f e v a l(see Calling MATLAB Functions Using feval). Rules for Extrinsic Function Declarations Observe the follow ing rules w hen declaring functions extrinsic for code generation: Declare the function extrinsic before you call it. Do not use the extrinsic declaration in conditional statements. Scope of Extrinsic Function Declarations The c o d e r . e x t r i n s i cconstruct has function scope. For example, consider the follow ing code: f u n c t i o ny=f o o% # c o d e g e n c o d e r . e x t r i n s i c ( ' r a t ' , ' m i n ' ) ; [ ND ]=r a t ( p i ) ; y=0 ; y=m i n ( N ,D ) ; In this example, r a tand m i nas treated as extrinsic every time they are called in the main function f o o . There are tw o w ays to narrow the scope of an extrinsic declaration inside the main function: Declare the MATLAB function extrinsic in a local function, as in this example: f u n c t i o ny=f o o% # c o d e g e n c o d e r . e x t r i n s i c ( ' r a t ' ) ; [ ND ]=r a t ( p i ) ; y=0 ; y=m y m i n ( N ,D ) ; f u n c t i o ny=m y m i n ( a , b ) c o d e r . e x t r i n s i c ( ' m i n ' ) ; y=m i n ( a , b ) ; Here, the function r a tis extrinsic every time it is called inside the main function f o o , but the function m i nis extrinsic only w hen called inside the local function m y m i n . Call the MATLAB function using f e v a l , as described in Calling MATLAB Functions Using feval.

Calling MATLAB Functions Using feval

The function f e v a lis automatically interpreted as an extrinsic function during code generation. Therefore, you can use f e v a lto conveniently call functions that you w ant to execute in the MATLAB environment, rather than compiled to generated code. Consider the follow ing example: f u n c t i o ny=f o o c o d e r . e x t r i n s i c ( ' r a t ' ) ; [ ND ]=r a t ( p i ) ; y=0 ; y=f e v a l ( ' m i n ' ,N ,D ) ; Because f e v a lis extrinsic, the statement f e v a l ( ' m i n ' ,N ,D )is evaluated by MATLAB not compiled w hich has the same result as declaring the function m i nextrinsic for just this one call. By contrast, the function r a tis extrinsic throughout the function f o o .

How MATLAB Resolves Extrinsic Functions During Simulation

MATLAB resolves calls to extrinsic functions functions that do not support code generation as follow s:

http://www.mathworks.com/help/simulink/ug/calling-matlab-functions.html#bq1h2z9-47

3/5

1/4/2014

Call MATLAB Functions - MATLAB & Simulink

During simulation, MATLAB generates code for the call to an extrinsic function, but does not generate the function's internal code. Therefore, you can run the simulation only on platforms w here you install MATLAB softw are. During code generation, MATLAB attempts to determine w hether the extrinsic function affects the output of the function in w hich it is called for example by returning m x A r r a y sto an output variable (see Working w ith mxArrays). Provided that the output does not change, MATLAB proceeds w ith code generation, but excludes the extrinsic function from the generated code. Otherw ise, MATLAB issues a compiler error.

Working with mxArrays

The output of an extrinsic function is an m x A r r a y also called a MATLAB array. The only valid operations for m x A r r a y sare: Storing m x A r r a y sin variables Passing m x A r r a y sto functions and returning them from functions Converting m x A r r a y sto know n types at run time To use m x A r r a y sreturned by extrinsic functions in other operations, you must first convert them to know n types, as described in Converting mxArrays to Know n Types. Converting m xArrays to Know n Types To convert an m x A r r a yto a know n type, assign the m x A r r a yto a variable w hose type is defined. At run time, the m x A r r a yis converted to the type of the variable assigned to it. How ever, if the data in the m x A r r a yis not consistent w ith the type of the variable, you get a run-time error. For example, consider this code: f u n c t i o ny=f o o% # c o d e g e n c o d e r . e x t r i n s i c ( ' r a t ' ) ; [ ND ]=r a t ( p i ) ; y=m i n ( N ,D ) ; Here, the top-level function f o ocalls the extrinsic MATLAB function r a t , w hich returns tw o m x A r r a y srepresenting the numerator Nand denominator Dof the rational fraction approximation of p i . Although you can pass these m x A r r a y sto another MATLAB function in this case, m i n you cannot assign the m x A r r a yreturned by m i nto the output y . If you run this function f o oin a MATLAB Function block in a Simulink model, the code generates the follow ing error during simulation:
http://www.mathworks.com/help/simulink/ug/calling-matlab-functions.html#bq1h2z9-47 4/5

1/4/2014

Call MATLAB Functions - MATLAB & Simulink

F u n c t i o no u t p u t' y 'c a n n o tb eo fM A T L A Bt y p e . To fix this problem, define yto be the type and size of the value that you expect m i nto return in this case, a scalar double as follow s: f u n c t i o ny=f o o% # c o d e g e n c o d e r . e x t r i n s i c ( ' r a t ' ) ; [ ND ]=r a t ( p i ) ; y=0 ;%D e f i n eya sas c a l a ro ft y p ed o u b l e y=m i n ( N , D ) ;

Restrictions on Extrinsic Functions for Code Generation

The full MATLAB run-time environment is not supported during code generation. Therefore, the follow ing restrictions apply w hen calling MATLAB functions extrinsically: MATLAB functions that inspect the caller, or read or w rite to the caller's w orkspace do not w ork during code generation. Such functions include: d b s t a c k e v a l i n a s s i g n i n s a v e The MATLAB debugger cannot inspect variables defined in extrinsic functions. Functions in generated code may produce unpredictable results if your extrinsic function performs the follow ing actions at run time: Change folders Change the MATLAB path Delete or add MATLAB files Change w arning states Change MATLAB preferences Change Simulink parameters

Limit on Function Arguments

You can call functions w ith up to 64 inputs and 64 outputs.

http://www.mathworks.com/help/simulink/ug/calling-matlab-functions.html#bq1h2z9-47

5/5