def start_matlab(option="-nodesktop", **kwargs):
"""
Start the MATLAB Engine. This function creates an instance of the
MatlabEngine class. The local version of MATLAB will be launched
with the "-nodesktop" argument.
Please note the invocation of this function is synchronous, which
means it only returns after MATLAB launches.
Parameters
option - MATLAB startup option.
async, background: bool - start MATLAB asynchronously or not. This parameter
is optional and false by default. "async" is a synonym for "background"
that will be removed in a future release.
Returns
MatlabEngine - if aync or background is false. This object can be used to evaluate
MATLAB statements.
FutureResult - if async or background is true. This object can be used to obtain the
real MatlabEngine instance.
Raises
EngineError - if MATLAB can't be started.
"""
if not isinstance(option, str):
raise TypeError(pythonengine.getMessage('StartupOptionShouldBeStr'))
background = enginehelper._get_async_or_background_argument(kwargs)
future = FutureResult(option=option)
if not background:
#multi-threads cannot launch MATLAB simultaneously
eng = future.result()
return eng
else:
return future
def connect_matlab(name=None, **kwargs):
"""
Connect to a shared MATLAB session. This function creates an instance
of the MatlabEngine class and connects it to a MATLAB session. The MATLAB
session must be a shared session on the local machine.
If name is not specified and there is no shared MATLAB available, this
function launches a shared MATLAB session with default options. If name
is not specified and there are shared MATLAB sessions available, the first
shared MATLAB created is connected. If name is specified and there are no
shared MATLAB sessions with that name, an exception is raised.
Parameters
name: str - the name of the shared MATLAB session, which is optional.
By default it is None.
async, background: bool - connect to the shared MATLAB session asynchronously or
not. This is optional and false by default. "async" is a synonym for
"background" that will be removed in a future release.
Returns
MatlabEngine - if async or background is false. This object can be used to evaluate
MATLAB functions.
FutureResult - if async or background is true. This object can be used to obtain the
real MatlabEngine instance.
Raises
EngineError - if the MATLAB cannot be connected.
"""
#multi-threads cannot run this function simultaneously
background = enginehelper._get_async_or_background_argument(kwargs)
if name is None:
with _engine_lock:
#if there is no shareable or more than one shareable MATLAB
engines = find_matlab()
if len(engines) == 0:
future = FutureResult(option="-r matlab.engine.shareEngine")
else:
#if there are shareable MATLAB sessions available
future = FutureResult(name=engines[0], attach=True)
if not background:
eng = future.result()
return eng
else:
return future
else:
future = FutureResult(name=name, attach=True)
if not background:
eng = future.result()
return eng
else:
return future
is optional and false by default.
Returns
MatlabEngine - if aync is false. This object can be used to evaluate
MATLAB statements.
FutureResult - if async is true. This object can be used to obtain the
real MatlabEngine instance.
Raises
EngineError - if MATLAB can't be started.
"""
if not isinstance(option, str):
raise TypeError(pythonengine.getMessage('StartupOptionShouldBeStr'))
future = FutureResult(option=option)
if not async:
#multi-threads cannot launch MATLAB simultaneously
eng = future.result()
return eng
else:
return future
def find_matlab():
"""
Discover all shared MATLAB sessions on the local machine. This function
returns the names of all shared MATLAB sessions.
Returns
tuple - the names of all shared MATLAB sessions running locally.