com.mathworks.engine.MatlabEngine
Java class using MATLAB as a computational engine
Description
The com.mathworks.engine.MatlabEngine class uses a MATLAB® process as a computational engine for Java®. This class provides an interface between the Java language and MATLAB, enabling you to evaluate MATLAB functions and statements from Java.
Creation
The MatlabEngine class provides static methods to start MATLAB and to connect to a shared MATLAB session synchronously or asynchronously. Only these static methods can
instantiate this class:
startMatlab—Start MATLAB synchronously.
connectMatlab—Connect to shared MATLAB session synchronously.
startMatlabAsync—Start MATLAB asynchronously.
connectMatlabAsync—Connect to shared MATLAB session asynchronously.
Unsupported Startup Options
The engine does not support these MATLAB startup options:
-h-help-?-n-e-softwareopengl-logfile
For information on MATLAB startup options, see Commonly Used Startup Options.
Method Summary
Static Methods
Start MATLAB synchronously. | |
Start MATLAB asynchronously. | |
Find all shared MATLAB sessions on the local machine synchronously. | |
Find all shared MATLAB sessions on the local machine asynchronously. | |
Connect to a shared MATLAB session on the local machine synchronously. | |
Connect to a shared MATLAB session on the local machine asynchronously. | |
Connect to the current MATLAB session when called from the MATLAB environment. |
Member Variable
NULL_WRITER | Use a writer that ignores the contents from the MATLAB Command Window. |
Member Functions
Evaluate MATLAB functions with input arguments synchronously. | |
Evaluate MATLAB functions with input arguments asynchronously. | |
Evaluate a MATLAB statement as a string synchronously. | |
Evaluate a MATLAB statement as a string asynchronously. | |
Get a variable from the MATLAB base workspace synchronously. | |
Get a variable from the MATLAB base workspace asynchronously. | |
Put a variable into the MATLAB base workspace synchronously. | |
Put a variable into the MATLAB base workspace asynchronously. | |
Disconnect from the current MATLAB session synchronously. | |
Disconnect from the current MATLAB session asynchronously. | |
Force the shutdown of the current MATLAB session synchronously. | |
Force the shutdown of the current MATLAB session asynchronously without waiting for termination. | |
Disconnect or terminate the current MATLAB session. |
Method Details
startMatlab
static MatlabEngine startMatlab(String[] options)
static MatlabEngine startMatlab()
Start MATLAB synchronously.
| Startup options used to start the MATLAB engine. You can specify multiple startup options. The engine
supports all MATLAB startup options, except for the options listed in Unsupported Startup Options. For a list of options, see the
platform-specific command |
Instance of MatlabEngine
| MATLAB fails to start. |
String[] options = {"-noFigureWindows", "-r", "cd H:"};
MatlabEngine eng = MatlabEngine.startMatlab(options);
startMatlabAsync
static Future<MatlabEngine> startMatlabAsync(String[]
options)
static Future<MatlabEngine> startMatlabAsync()
Start MATLAB asynchronously. Once MATLAB has started, then you cannot cancel the method.
| Startup options used to start the MATLAB engine. You can specify multiple startup options. The engine
supports all MATLAB startup options, except for the options listed in Unsupported Startup Options. For a list of options, see the
platform-specific command |
Instance of Future<MatlabEngine>
Future<MatlabEngine> future = MatlabEngine.startMatlabAsync();findMatlab
static String[] findMatlab()
Find all shared MATLAB sessions on the local machine synchronously.
An array of the names of all shared MATLAB sessions on the local machine, or an empty vector if there are no shared MATLAB sessions available on the local machine.
| There is a failure during the search for MATLAB sessions. |
String[] engines = MatlabEngine.findMatlab();findMatlabAsync
static Future<String[]> findMatlabAsync()
Find all shared MATLAB sessions on the local machine asynchronously.
An instance of Future<String[]>
Future<String[]> future = MatlabEngine.findMatlabAsync();connectMatlab
static MatlabEngine connectMatlab(String name)
static MatlabEngine connectMatlab()
Connect to a shared MATLAB session on the local machine synchronously.
If you specify the name of a shared MATLAB session, but the engine cannot find a session with that name, the engine throws an exception.
If you do not specify a name and there are no shared MATLAB sessions available, the engine starts a new shared MATLAB session with default options.
If you do not specify a name and there are shared MATLAB sessions available, the engine connects to the first available session.
To connect to the current MATLAB session when called from the MATLAB environment, use getCurrentMatlab instead.
| Name of the shared MATLAB session. Use findMatlab to get the names of shared MATLAB sessions. |
An instance of MatlabEngine
| MATLAB fails to start or connect. |
MatlabEngine engine = MatlabEngine.connectMatlab();connectMatlabAsync
static Future<MatlabEngine> connectMatlabAsync(String
name)
static Future<MatlabEngine> connectMatlabAsync
Connect to a shared MATLAB session on the local machine asynchronously. The behavior is the same as
that of connectMatlab except the mechanism is asynchronous. Once a
connection has been made to MATLAB, you cannot cancel the method.
| Name of the shared MATLAB session. |
An instance of Future<MatlabEngine>
Future<MatlabEngine> future = MatlabEngine.connectMatlabAsync();getCurrentMatlab
static MatlabEngine getCurrentMatlab()
Starting in R2021b, connect to the current MATLAB session when called from the MATLAB environment.
To connect to a MATLAB session when called from engine applications, use connectMatlab.
An instance of MatlabEngine
| Calling from user thread is not supported. |
MatlabEngine engine = MatlabEngine.getCurrentMatlab();feval
<T> T feval(int nlhs, String func, Writer output, Writer error, Object…
args)
<T> T feval(int nlhs, String func, Object… args)
<T> T feval(String func, Writer output, Writer error, Object…
args)
<T> T feval(String func, Object… args)
Evaluate MATLAB functions with input arguments synchronously.
| Name of the MATLAB function or script to evaluate. |
| Number of expected outputs. Default is 1. If
If If |
| Stream used to store the standard output from the MATLAB function. If you do not specify a writer, the output is written to
the command window or terminal. Use |
| Stream used to store the standard error from the MATLAB function. If you do not specify a writer, the error message is
written to the command window or terminal. Use |
| Arguments to pass to the MATLAB function. |
Result of executing the MATLAB function
| Evaluation of a MATLAB function was canceled. |
| Evaluation of a MATLAB function was interrupted. |
| The MATLAB session is not available. |
| There is a MATLAB runtime error in the function. |
| There is an unsupported data type. |
| There is a syntax error in the MATLAB function. |
double result = engine.feval("sqrt", 4);fevalAsync
<T> Future<T> fevalAsync(int nlhs, String func, Writer output,
Writer error, Object… args)
<T> Future<T> fevalAsync(int nlhs, String func, Object…
args)
<T> Future<T> fevalAsync(String func, Writer output, Writer error,
Object… args)
<T> Future<T> fevalAsync(String func, Object…
args)
Evaluate MATLAB functions with input arguments asynchronously.
| Name of the MATLAB function or script to evaluate. |
| Number of expected outputs. Default is
If If If |
| Stream used to store the standard output from the MATLAB function. If you do not specify a writer, the output is written to
the command window or terminal. Use |
| Stream used to store the standard error from the MATLAB function. If you do not specify a writer, the error message is
written to the command window or terminal. Use |
| Arguments to pass to the MATLAB function. |
An instance of Future<T>
| The MATLAB session is not available. |
Future<Double> future = engine.fevalAsync("sqrt", 4);eval
void eval(String command, Writer output, Writer error)
void eval(String command)
Evaluate a MATLAB statement as a string synchronously.
| MATLAB statement to evaluate. |
| Stream used to store the standard output from the MATLAB statement. If you do not specify a writer, the output is written
to the command window or terminal. Use |
| Stream used to store the standard error from the MATLAB statement. If you do not specify a writer, the error message is
written to the command window or terminal. Use |
| Evaluation of a MATLAB function was canceled. |
| Evaluation of a MATLAB function was interrupted. |
| The MATLAB session is not available. |
| There is an error in the MATLAB statement during runtime. |
| There is a syntax error in the MATLAB statement. |
engine.eval("result = sqrt(4)");evalAsync
Future<Void> evalAsync(String command, Writer output, Writer
error)
Future<Void> evalAsync(String command)
Evaluate a MATLAB statement as a string asynchronously.
| MATLAB statement to evaluate. |
| Stream used to store the standard output from the MATLAB statement. If you do not specify a writer, the output is written
to the command window or terminal. Use |
| Stream used to store the standard error from the MATLAB statement. If you do not specify a writer, the error message is
written to the command window or terminal. Use |
An instance of Future<Void>
| The MATLAB session is not available. |
Future<Void> future = engine.evalAsync("sqrt(4)");getVariable
<T> T getVariable(String varName)
Get a variable from the MATLAB base workspace synchronously.
| Name of a variable in the MATLAB base workspace. |
Variable passed from the MATLAB base workspace
| Evaluation of this function is canceled. |
| Evaluation of this function is interrupted. |
| The MATLAB session is not available. |
double myVar = engine.getVariable("myVar");getVariableAsync
<T> Future<T> getVariableAsync(String varName)
Get a variable from the MATLAB base workspace asynchronously.
| Name of a variable in the MATLAB base workspace. |
An instance of Future<T>
| The MATLAB session is not available. |
Future<Double> future = engine.getVariableAsync("myVar");putVariable
void putVariable(String varName, T varData)
Put a variable into the MATLAB base workspace synchronously.
| Name of a variable to create in the MATLAB base workspace. |
| Value of the variable to create in the MATLAB base workspace. |
| Evaluation of this function is canceled. |
| Evaluation of this function is interrupted. |
| The MATLAB session is not available. |
engine.putVariable("myVar", 100);putVariableAsync
Future<Void> putVariableAsync(String varName, T varData)
Put a variable into the MATLAB base workspace asynchronously.
| Name of a variable to create in the MATLAB base workspace. |
| Value of the variable to create in the MATLAB base workspace. |
An instance of Future<Void>
| The MATLAB session is not available. |
Future<Void> future = engine.putVariableAsync("myVar", 100);disconnect
void disconnect()
Disconnect from the current MATLAB session synchronously.
| The current MATLAB session cannot be disconnected. |
engine.disconnect();disconnectAsync
Future<Void> disconnectAsync()
Disconnect from the current MATLAB session asynchronously.
Future<Void> future = engine.disconnectAsync();quit
void quit()
Force the shutdown of the current MATLAB session synchronously.
| The current MATLAB session cannot be shut down. |
engine.quit();quitAsync
Future<Void> quitAsync()
Force the shutdown of the current MATLAB session asynchronously without waiting for termination.
An instance of Future<Void>
Future<Void> future = engine.quitAsync();close
void close()
MatlabEngine provides the close() method to
implement the java.lang.AutoCloseable interface for
MatlabEngine objects. This close() method enables
you to use a try-with-resources statement to automatically disconnect
or terminate the MATLAB session at the end of the statement.
The MatlabEngine
close() method disconnects or terminates the current MATLAB session, depending on the context.
If a Java process starts the MATLAB session as a default non-shared session,
close()terminates MATLAB.If the MATLAB session is a shared session,
close()disconnects MATLAB from this Java process. MATLAB terminates when there are no other connections.
To force the shutdown or disconnection of the current MATLAB session, explicitly call MatlabEngine.quit(),
MatlabEngine.disconnect(), or their asynchronous counterparts.
engine.close();Version History
Introduced in R2016b
You can also select a web site from the following list
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)
Asia Pacific
- Australia (English)
- India (English)
- New Zealand (English)
- 中国
- 日本Japanese (日本語)
- 한국Korean (한국어)