matlab::engine::MATLABEngine - Evaluate MATLAB functions from C++ program - MATLAB (original) (raw)

Evaluate MATLAB functions from C++ program

Description

The matlab::engine::MATLABEngine class uses a MATLAB® process as a computational engine for C++. This class provides an interface between the C++ language and MATLAB, enabling you to evaluate MATLAB functions and expressions from C++ programs.

Class Details

Member Functions

• feval
• fevalAsync
• eval
• evalAsync
• getVariable
• getVariableAsync
• setVariable
• setVariableAsync
• getProperty
• getPropertyAsync
• setProperty
• setPropertyAsync

feval

std::vector<matlab::data::Array> feval(const matlab::engine::String &function,
   const size_t numReturned,
   const std::vector<matlab::data::Array> &args,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output = std::shared_ptr<matlab::engine::StreamBuffer>(),
   const std::shared_ptr<matlab::engine::StreamBuffer> &error = std::shared_ptr<matlab::engine::StreamBuffer>())

matlab::data::Array feval(const matlab::engine::String &function, 
   const std::vector<matlab::data::Array> &args, 
   const std::shared_ptr<matlab::engine::StreamBuffer> &output = std::shared_ptr<matlab::engine::StreamBuffer>(),
   const std::shared_ptr<matlab::engine::StreamBuffer> &error = std::shared_ptr<matlab::engine::StreamBuffer>())

matlab::data::Array feval(const matlab::engine::String &function,
   const matlab::data::Array &arg,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output = std::shared_ptr<matlab::engine::StreamBuffer>(),
   const std::shared_ptr<matlab::engine::StreamBuffer> &error = std::shared_ptr<matlab::engine::StreamBuffer>())

ResultType feval(const matlab::engine::String &function,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output,
   const std::shared_ptr<matlab::engine::StreamBuffer> &error,
   RhsArgs&&... rhsArgs )

ResultType feval(const matlab::engine::String &function,
   RhsArgs&&... rhsArgs)

Description

Evaluate MATLAB functions with input arguments synchronously. Usefeval to pass arguments from C++ to MATLAB and to return a result from MATLAB to C++.

Inputs and outputs can be types defined by the MATLAB Data API or can be native C++ types.

Parameters

Return Value

Exceptions

Examples

This example passes an array of numeric values to a MATLAB function. The code performs these steps:

• Creates a matlab::data::Array with the dimensions 2-by-3 from a vector of numeric values of type double.
• Starts a shared MATLAB session.
• Passes the data array to the MATLABsqrt function and returns the result to C++.

#include "MatlabDataArray.hpp"
#include "MatlabEngine.hpp"
using namespace matlab::engine;

    std::vector<double> cppData{ 4, 8, 12, 16, 20, 24 };

    // Create a 2-by-3 matlab data array 
    matlab::data::ArrayFactory factory;
    auto inputArray = factory.createArray({ 2, 3 }, cppData.cbegin(), cppData.cend());

    // Start MATLAB engine
    std::unique_ptr<MATLABEngine> matlabPtr = startMATLAB();

    // Pass data array to MATLAB sqrt function 
    // And return results.
    auto result = matlabPtr->feval(u"sqrt", inputArray);

When calling feval using native C++ types, the input arguments are restricted to scalar values. For example, this code returns the square root of a scalar value.

#include "MatlabEngine.hpp"
using namespace matlab::engine;

    // Start MATLAB engine synchronously
    std::unique_ptr<MATLABEngine> matlabPtr = startMATLAB();
    
    // Call sqrt function
    double result = matlabPtr->feval<double>(u"sqrt", double(27));

For functions that return multiple output arguments, you can use the MATLAB data API or, if using C++ types, an std::tuple. For an example, see Call Function with Native C++ Types.

For more examples, see Call MATLAB Functions from C++.

fevalAsync

FutureResult<std::vector<matlab::data::Array>> fevalAsync(const matlab::engine::String &function,
   const size_t numReturned,
   const std::vector<matlab::data::Array> &args,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output = std::shared_ptr<matlab::engine::StreamBuffer>(),
   const std::shared_ptr<matlab::engine::StreamBuffer> &error = std::shared_ptr<matlab::engine::StreamBuffer>())

FutureResult<matlab::data::Array> fevalAsync(const matlab::engine::String &function,
   const std::vector<matlab::data::Array> &args,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output = std::shared_ptr<matlab::engine::StreamBuffer>(),
   const std::shared_ptr<matlab::engine::StreamBuffer> &error = std::shared_ptr<matlab::engine::StreamBuffer>())

FutureResult<matlab::data::Array> fevalAsync(const matlab::engine::String &function,
   const matlab::data::Array &arg,
   const std::shared_ptr<matlab::engine::StreamBuffer> & output = std::shared_ptr<matlab::engine::StreamBuffer>(),
   const std::shared_ptr<matlab::engine::StreamBuffer> & error = std::shared_ptr<matlab::engine::StreamBuffer>())

FutureResult<ResultType> fevalAsync(const matlab::engine::String &function,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output,
   const std::shared_ptr<matlab::engine::StreamBuffer> &error,
   RhsArgs&&... rhsArgs)

FutureResult<ResultType> fevalAsync(const matlab::engine::String &function,
   RhsArgs&&... rhsArgs)

Description

Evaluate MATLAB functions with input arguments and returned values asynchronously.

Parameters

Return Value

Examples

This example passes the scalar double 12.7 to the MATLABsqrt function asynchronously. TheFutureResult is then used to get the result.

#include "MatlabDataArray.hpp"
#include "MatlabEngine.hpp"
using namespace matlab::engine;

std::unique_ptr<MATLABEngine> matlabPtr = startMATLAB();
    matlab::data::ArrayFactory factory;
    matlab::data::Array argument = factory.createScalar<double>(12.7);
    FutureResult<matlab::data::Array> future = matlabPtr->fevalAsync(u"sqrt", std::move(argument));
       ...
    matlab::data::TypedArray<double> result = future.get();

eval

void eval(const matlab::engine::String &statement,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output = std::shared_ptr<matlab::engine::StreamBuffer> (),
   const std::shared_ptr<matlab::engine::StreamBuffer> &error = std::shared_ptr<matlab::engine::StreamBuffer> ())

Description

Evaluate a MATLAB statement as a string synchronously.

Parameters

Exceptions

Examples

This example evaluates the following MATLAB statement.

The statement creates the variable a in the MATLAB base workspace.

#include "MatlabEngine.hpp"
using namespace matlab::engine;

std::unique_ptr<MATLABEngine> matlabPtr = startMATLAB();
matlabPtr->eval(u"a = sqrt(12.7);");

evalAsync

FutureResult<void> evalAsync(const matlab::engine::String &str,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output = std::shared_ptr<matlab::engine::StreamBuffer> (),
   const std::shared_ptr<matlab::engine::StreamBuffer> &error = std::shared_ptr<matlab::engine::StreamBuffer> ())

Description

Evaluate a MATLAB statement as a string asynchronously.

Parameters

Return Value

Examples

This example evaluates the following MATLAB statement asynchronously.

The statement creates the variable a in the MATLAB base workspace.

#include "MatlabEngine.hpp"
using namespace matlab::engine;

std::unique_ptr<MATLABEngine> matlabPtr = startMATLAB();
FutureResult<void> future = matlabPtr->evalAsync(u"a = sqrt(12.7);");

getVariable

matlab::data::Array getVariable(const matlab::engine::String &varName,
    matlab::engine::WorkspaceType workspaceType = matlab::engine::WorkspaceType::BASE)

Description

Get a variable from the MATLAB base or global workspace.

Parameters

Return Value

Exceptions

Examples

This example gets a variable named varName from the MATLAB base workspace.

#include "MatlabEngine.hpp"
using namespace matlab::engine;

std::unique_ptr<MATLABEngine> matlabPtr = startMATLAB();
matlab::data::Array varName = matlabPtr->getVariable(u"varName");

getVariableAsync

FutureResult<matlab::data::Array> getVariableAsync(const matlab::engine::String &varName,
    matlab::engine::WorkspaceType workspaceType = matlab::engine::WorkspaceType::BASE)

Description

Get a variable from the MATLAB base or global workspace asynchronously.

Parameters

Return Value

Examples

This example gets a variable named varName from the MATLAB base workspace asynchronously.

#include "MatlabEngine.hpp"
using namespace matlab::engine;

std::unique_ptr<MATLABEngine> matlabPtr = startMATLAB();
FutureResult<matlab::data::Array> future = matlabPtr->getVariableAsync(u"varName");
...
matlab::data::Array varName = future.get();

setVariable

void setVariable(const matlab::engine::String &varName,
   const matlab::data::Array &var,
   matlab::engine::WorkspaceType workspaceType = matlab::engine::WorkspaceType::BASE)

Description

Put a variable into the MATLAB base or global workspace. If a variable with the same name exists in the MATLAB workspace, setVariable overwrites it.

Parameters

Exceptions

Examples

This example puts the variable named data in the MATLAB base workspace.

#include "MatlabEngine.hpp"
using namespace matlab::engine;

std::unique_ptr<MATLABEngine> matlabPtr = startMATLAB();
matlab::data::Array data = factory.createArray<double>({ 1, 3 }, { 4, 8, 6 });
matlabPtr->setVariable(u"data", data);

setVariableAsync

FutureResult<void> setVariableAsync(const matlab::engine::String &varName,
   const matlab::data::Array var,
   matlab::engine::WorkspaceType workspaceType = matlab::engine::WorkspaceType::BASE)

Description

Put a variable into the MATLAB base or global workspace asynchronously. If a variable with the same name exists in the MATLAB base workspace, setVariableAsync overwrites it.

Parameters

Example

This example puts the variable named data in the MATLAB base workspace.

#include "MatlabEngine.hpp"
using namespace matlab::engine;

std::unique_ptr<MATLABEngine> matlabPtr = startMATLAB();
matlab::data::Array data = factory.createArray<double>({ 1, 3 }, { 4., 8., 6. });
FutureResult<void> future = matlabPtr->setVariableAsync(u"data", data);

getProperty

matlab::data::Array getProperty(const matlab::data::Array &objectArray,
    size_t index,
    const matlab::engine::String &propertyName)

matlab::data::Array getProperty(const matlab::data::Array &object,
   const matlab::engine::String &propertyName)

Description

Get the value of an object property. If the object input argument is an array of objects, specify the index of the array element that corresponds to the object whose property value you want to get.

Parameters

Return Value

Exceptions

Examples

This example evaluates a MATLAB statement in a try/catch block usingMATLABEngine::eval. TheMATLABEngine::getVariable member function returns the exception object. MATLABEngine::getProperty returns the exceptionmessage property value as amatlab::data::CharArray.

#include "MatlabEngine.hpp"
using namespace matlab::engine;

std::unique_ptr<MATLABEngine> matlabPtr = startMATLAB();
matlabPtr->eval(u"try; surf(4); catch me; end");
matlab::data::Array mException = matlabPtr->getVariable(u"me");
matlab::data::CharArray message = matlabPtr->getProperty(mException, u"message");
std::cout << "messages is: " << message.toAscii() << std::endl;

getPropertyAsync

FutureResult<matlab::data::Array> getPropertyAsync(const matlab::data::Array &objectArray,
    size_t index,
    const matlab::engine::String &propertyName)

FutureResult<matlab::data::Array> getPropertyAsync(const matlab::data::Array &object,
   const matlab::engine::String &propertyName)

Description

Get the value of an object property asynchronously. If the object input argument is an array of objects, specify the index of the array element that corresponds to the object whose property value you want to get.

Parameters

Return Value

Examples

This example evaluates a MATLAB statement in a try/catch block usingMATLABEngine::eval. TheMATLABEngine::getVariable member function returns the exception object. MATLABEngine::getPropertyAsync returns aFutureResult that you use to get the exceptionmessage property value as amatlab::data::CharArray.

#include "MatlabEngine.hpp"
using namespace matlab::engine;

std::unique_ptr<MATLABEngine> matlabPtr = startMATLAB();
matlabPtr->eval(u"try;surf(4);catch me;end");
matlab::data::Array mException = matlabPtr->getVariable(u"me");
FutureResult<matlab::data::Array> future = matlabPtr->getPropertyAsync(mException, u"message");
matlab::data::CharArray message = future.get();
std::cout << "messages is: " << message.toAscii() << std::endl;

setProperty

void setProperty(matlab::data::Array &objectArray,   
    size_t index,
    const matlab::engine::String &propertyName,
    const matlab::data::Array &propertyValue)

void setProperty(matlab::data::Array &object, 
    const matlab::engine::String &propertyName,
    const matlab::data::Array &propertyValue)

Description

Set the value of an object property. If the object input argument is an array of objects, specify the index of the array element that corresponds to the object whose property value you want to set.

Parameters

Exceptions

Examples

This example shows how to set a MATLAB object property. It creates a MATLAB graph and returns the line handle object. Setting the value of the lineLineStyle property to the character : changes the property value of the line object in MATLAB and updates the line style of the graph.

#include "MatlabEngine.hpp"
using namespace matlab::engine;

std::unique_ptr<MATLABEngine> matlabPtr = startMATLAB();
matlab::data::ArrayFactory factory;
matlab::data::Array yData = factory.createArray<double>({ 1, 5 }, { 4.0, 11.0, 4.7, 36.2, 72.3 });
matlab::data::Array lineHandle = matlabPtr->feval(u"plot", yData);
matlab::data::CharArray lineStyle = factory.createCharArray(":");
matlabPtr->setProperty(lineHandle, u"LineStyle", lineStyle);

setPropertyAsync

FutureResult<void> setPropertyAsync(matlab::data::Array &objectArray,   
    size_t index,
    const matlab::engine::String &propertyName,
    const matlab::data::Array &propertyValue)

FutureResult<void> setPropertyAsync(matlab::data::Array &object,
 const matlab::engine::String &propertyName,
 const matlab::data::Array &propertyValue)

Description

Set the value of an object property asynchronously. If the object input argument is an array of objects, specify the index of the array element that corresponds to the object whose property value you want to set.

Parameters

Examples

This example shows how to set a MATLAB object property asynchronously. It creates a MATLAB graph and returns the line handle object. Setting the lineLineStyle property to the character : changes the property value of the object in MATLAB and updates the line style of the graph.

#include "MatlabEngine.hpp"
using namespace matlab::engine;

std::unique_ptr<MATLABEngine> matlabPtr = startMATLAB();
matlab::data::ArrayFactory factory;
matlab::data::Array yData = factory.createArray<double>({ 1, 5 }, { 4.0, 11.0, 4.7, 36.2, 72.3 });
matlab::data::Array lineHandle = matlabPtr->feval(u"plot", yData);
matlab::data::CharArray lineStyle = factory.createCharArray(":");    
FutureResult<void> future = matlabPtr->setPropertyAsync(lineHandle, u"LineStyle", lineStyle);

Version History

Introduced in R2017b

expand all

Member functions feval and fevalAsync support native C++ string, std::vector, andstd::complex data types. For more information, see theRhsArgs&&... rhsArgs entry in thefeval and fevalAsync Parameters tables.