In order to call compiled MATLAB® functions from within a Microsoft® Excel® spreadsheet, perform the following from the Development and Deployment machines, as specified.
In order for a function to be called using the Microsoft
Excel function syntax (
=myfunction(input)), the MATLAB function must return a single scalar output argument.
Perform the following steps on the Development machine:
Create the following MATLAB functions in three separate files named
function output = doubleit(input) output = input * 2;
function output = incrementit(input1, input2) output = input1 + input2;
function output = powerit(input1, input2) output = power(input1, input2);
Start the Library Compiler.
Use the following information as you work through this example using the instructions in Create Excel Add-In from MATLAB:
Perform the following steps on the Deployment machine:
Copy the contents of
for_redistribution_files_only to the
deployment machine(s). Copy the file to a standard place for use with Microsoft
Excel, such as
Office_Installation_folder is a folder such as
C:\Program Files\Microsoft Office\OFFICE11.
You need to re-register your DLL file if you move it following its creation. Unlike DLL files, Excel files can be moved anywhere at anytime.
Excel. The spreadsheet
Book1 should be open by
In Excel, select Tools > Visual Basic Editor. The Microsoft Visual Basic® Editor starts.
In the Microsoft Visual Basic Editor, select File > Import File.
myexcelfunctions.bas and click
Open. In the Project Explorer, Module1
appears under the Modules node beneath VBAProject
In the Microsoft
Visual Basic Editor, select View > Microsoft Excel. You
can now use the
powerit functions in your Book1
Test the functions, by doing the following:
=doubleit(2.5) in cell A1.
=incrementit(11,17) in cell A2.
=powerit(7,2) in cell A3.
You should see values 5, 28, and 49 in cells A1, A2, and A3 respectively.
To use the
incrementit functions in all your new Microsoft
Excel spreadsheets, do the following:
Select File > Save As.
Change the Save as type option to .xlt (Template).
Browse to the
Save the file as
Your Microsoft Excel Macro Security level must be set at Medium or Low to save this template.
For more information about accessing the example code from within the product ,see Example File Copying.
This feature provides a lightweight interface for easily accessing the MATLAB Runtime data. It allows data to be shared between the MATLAB Runtime instance, the MATLAB code running on that the MATLAB Runtime, and the wrapper code that created the MATLAB Runtime. Through calls to the MATLAB Runtime User Data interface API, you access the MATLAB Runtime data by creating a per MATLAB Runtime instance associative array of
mxArrays, consisting of a
mapping from string keys to
mxArray values. Reasons for doing this
include, but are not limited to:
You need to supply run-time profile information to a client running an application created with the Parallel Computing Toolbox™. Profile information may be supplied (and change) on a per-execution basis. For example, two instances of the same application may run simultaneously with different profiles.
You want to initialize the MATLAB Runtime with constant values that can be accessed by all your MATLAB applications.
You want to set up a global workspace — a global variable or variables that the MATLAB and your client can access.
You want to store the state of any variable or group of variables.
Compiler™ supports per the MATLAB Runtime instance state access through an object-oriented API. Unlike MATLAB
Compiler, access to per the MATLAB Runtime instance state is optional, rather than on by default. You can access this
state by adding
getmcruserdata.m to your deployment project or by specifying them on
the command line. Alternately, you use a helper function to call these methods, as shown
in Supply Run-Time Profile Information for Parallel Computing Toolbox Applications.
For more information, see the MATLAB Compiler User's Guide.
Following is a complete example of how you can use the MATLAB Runtime User Data Interface as a mechanism to specify a profile for Parallel Computing Toolbox applications.
Standalone executables and shared libraries generated from MATLAB Compiler or MATLAB Compiler SDK™ for parallel applications can now launch up to twelve local workers without MATLAB Parallel Server™.
Step 1: Write Your Parallel Computing Toolbox Code
sample_pct.m in MATLAB.
This example code uses the cluster defined in the default profile.
The output assumes that the default profile is
function speedup = sample_pct (n) warning off all; tic if(ischar(n)) n=str2double(n); end for ii = 1:n (cov(sin(magic(n)+rand(n,n)))); end time1 =toc; parpool; tic parfor ii = 1:n (cov(sin(magic(n)+rand(n,n)))); end time2 =toc; disp(['Normal loop times: ' num2str(time1) ... ',parallel loop time: ' num2str(time2) ]); disp(['parallel speedup: ' num2str(1/(time2/time1)) ... ' times faster than normal']); delete(gcp); disp('done'); speedup = (time1/time2);
Run the code as follows after changing the default
local, if needed.
a = sample_pct(200)
Verify that you get the following results:
Starting parallel pool (parpool) using the 'local' profile ... connected to 4 workers. Normal loop times: 0.7587,parallel loop time: 2.9988 parallel speedup: 0.253 times faster than normal Parallel pool using the 'local' profile is shutting down. done a = 0.2530
Step 2: Set the Parallel Computing Toolbox Profile. In order to compile MATLAB code to a COM component and utilize the Parallel Computing Toolbox, the
mcruserdata must be set directly from MATLAB. There is no API available to access the
there is for C and C++ applications built with MATLAB
To set the
mcruserdata from MATLAB, create an
init function in your COM class. This is a
separate MATLAB function that uses
setmcruserdata to set the
Parallel Computing Toolbox profile once. You then call your other functions to utilize the
Parallel Computing Toolbox functions.
Create the following
function init_sample_pct % Set the Parallel Profile: if(isdeployed) [profile] = uigetfile('*.settings'); % let the USER select file setmcruserdata('ParallelProfile',[profile]); end
Step 3: Compile Your Function with the Deploytool or the Command Line. You can compile your function from the command line by entering the following:
mcc -B 'cexcel:exPctComp,exPctClass,1.0' init_sample_pct.m sample_pct.m
Alternately, you can use the deploytool as follows:
Follow the steps in Create Excel Add-In from MATLAB to compile your application.
When the compilation finishes, a new folder (with the same name as the project) is created.
|File to compile|
If you are using the GPU feature of Parallel Computing Toolbox, you need to manually add the PTX and CU files.
If you are using the Library Compiler app, click Add files/directories on the Build tab.
If you are using the
To deploy the compiled application, copy the
for_redistribution_files_only folder, which contains the
following, to your end users.
VBA module (
MATLAB Runtime installer
The end-user's target machine must have access to the cluster.
Step 4: Modify the generated VBA Driver Application (the BAS File). After registering the COM DLL on the deployment machine and importing the BAS file into Excel, modify the generated BAS file code as needed.
Dim MCLUtil As Object Dim bModuleInitialized As Boolean Dim exPctClass As Object Private Sub InitModule() If Not bModuleInitialized Then On Error GoTo Handle_Error If MCLUtil Is Nothing Then Set MCLUtil = CreateObject("MWComUtil.MWUtil7.10") End If Call MCLUtil.MWInitApplication(Application) bModuleInitialized = True Exit Sub Handle_Error: bModuleInitialized = False End If End Sub Function init_sample_pct() As Variant On Error GoTo Handle_Error Call InitModule If exPctClass Is Nothing Then Set exPctClass = CreateObject("exPctComp.exPctClass.1_0") End If Call exPctClass.init_sample_pct init_sample_pct = Empty Exit Function Handle_Error: init_sample_pct = "Error in " & Err.Source & ": " & Err.Description End Function Function sample_pct(Optional pelle As Variant) As Variant Dim speedup As Variant On Error GoTo Handle_Error Call InitModule If exPctClass Is Nothing Then Set exPctClass = CreateObject("exPctComp.exPctClass.1_0") End If Call exPctClass.sample_pct(1, speedup, pelle) sample_pct = speedup Exit Function Handle_Error: sample_pct = "Error in " & Err.Source & ": " & Err.Description End Function
The output is as follows:
deployable archive data is automatically embedded directly in MATLAB Compiler components by default and extracted to a temporary folder.
Automatic embedding enables usage of MATLAB Runtime Component Cache features through environment variables.
These variables allow you to specify the following:
Define the default location where you want the deployable archive to be automatically extracted
Add diagnostic error printing options that can be used when automatically extracting the deployable, for troubleshooting purposes
Tuning the MATLAB Runtime component cache size for performance reasons.
Use the following environment variables to change these settings.
|MCR_CACHE_ROOT||When set to the location of where you want the deployable archive to be extracted, this
variable overrides the default per-user component cache location. This is true
for embedded ||On macOS, this variable is ignored in MATLAB R2020a and later. The app bundle contains the files necessary for runtime.|
|MCR_CACHE_SIZE||When set, this variable overrides the default component cache size.||The initial limit for this variable is 32M (megabytes). This
may, however, be changed after you have set the variable the first
time. Edit the file |
You can override this automatic embedding and extraction behavior by compiling
-C option. See Overriding Default Behavior for details.
If you run
mcc specifying conflicting wrapper and target types,
the deployable archive will not be embedded into the generated component. For example,
if you run:
mcc -W lib:myLib -T link:exe test.m test.c
test.exewill not have the deployable archive embedded in it, as if you had specified a
-Coption to the command line.
Do not extract the files within the
.ctf file and place them
individually under version control. Since the
.ctf file contains
interdependent MATLAB functions and data, the files within it must be accessed only by accessing
.ctf file. For best results, place the entire
.ctf file under version control.
To extract the deployable archive in a manner prior to R2008b, alongside the compiled
COM component, compile using the
You can also implement this override by adding the
-c flag in the
Settings section of the compiler app.
You might want to use this option to troubleshoot problems with the deployable archive, for example, as the log and diagnostic messages are much more visible.
For more information about the deployable archive, see Deployable Archive.
-logfile — Creates a named log file.
If You Compiled the Add-In in MATLAB or used mcc. If you are building your add-in using the MATLAB Library Compiler, select Create log file under Additional Runtime Settings.
If you are building your add-in using
mcc, simply specify
-logfile with the
If You Created a Function From Scratch Using the Function Wizard. If you created a function from scratch using the Function Wizard, and want to
specify MATLAB Runtime options, you have to manually modify the
You do this by invoking the following
MWUtil API calls, detailed
with examples in Class MWUtil: