gemseo / wrappers / matlab

engine module

Definition of the matlab engine singleton for workspace handling.

Overview

This module contains the MatlabEngine class which enables to build the Matlab workspace. The Matlab workspace must be seen as the Matlab “area” where Matlab functions are executed as well as Matlab variables live. The engine is basically used when creating a MatlabDiscipline instance and therefore is not directly handled by the user. However, a MatlabEngine instance can be used outside a MatlabDiscipline in order to directly call Matlab functions and/or accessing to some variables into the Matlab workspace.

Since MatlabEngine is private, it cannot be used directly from the module. It is rather used through the function get_matlab_engine() which enables to create only one instance with respect to the workspace_name (i.e. the instance is unique if the workspace name is the same when calling several times the function). Following this, MatlabEngine acts like a singleton.

class gemseo.wrappers.matlab.engine.MatlabEngine(engine_name)

Bases: object

Wrapper around the matlab execution engine.

Since this class is private, an instance should be built through get_matlab_engine() function. Using that latter function acts like a singleton, i.e. the returned instance is unique if the workspace name is the same.

Examples

>>> eng1 = get_matlab_engine()
>>> # add new searching directory to workspace with sub-dir
>>> eng1.add_path("dir_to_files", add_subfolder=True)
>>>
>>> # check if a function exists in workspace and returns the type
>>> exist, type_func = eng1.exist("cos")
>>> # execute the function
>>> eng1.execute_function("cos", 0, nargout=1)
>>>
>>> # quit engine
>>> eng1.close_session()
>>> print(eng1.is_closed)

Parameters

engine_name (str) – The name identifying the engine.

Return type

None

add_path(path, add_subfolder=False)

Add a path to the matlab engine search directories.

Parameters

• path (str | Path) – The path to the directory or file to be added to path.

• add_subfolder (bool) –

  If True, add path sub-folders.

  By default it is set to False.

Raises

ValueError – If the given path cannot be added to Matlab.

Return type

None

add_toolbox(toolbox_name)

Add a toolbox to the engine.

The toolbox added would be needed for the functions used in the current session. It should be checked that the license is compatible. The name given here can be found using “license(‘inuse’)” in MATLAB.

Parameters

toolbox_name (str) – The name of the toolbox to be check.

Return type

None

close_session()

Close the matlab session.

Return type

None

end_parallel_computing()

End the parallel computing.

Raises

matlab.engine.MatlabExecutionError – If the parallel option is not correctly deactivated.

Return type

None

execute_function(func_name, *args, **kwargs)

Executes a Matlab function called “func_name”.

Parameters

• func_name (str) – The function name to call.

• *args (float) – Any arguments that must be passed to the function.

• **kwargs (float) – Any arguments that must be passed to the function.

Raises

matlab.engine.MatlabExecutionError – If the matlab function execution fails.

Return type

float | ndarray

execute_script(script_name)

Execute a script in the current workspace.

After executing the script, the workspace point to the path where the script is located.

Parameters

script_name (str) – The script name.

Return type

None

exist(name)

Check if the given matlab object exists.

Parameters

name (str | Path) – The name to be checked if present in MATLAB path.

Returns

A boolean that tells if name exist. A string that indicates the type of file where function_name is found.

Return type

tuple[bool, str | None]

get_toolboxes()

Return all toolboxes to be checked before launching this engine.

Returns

All toolboxes.

Return type

list[str]

get_variable(item)

Get any variable in the workspace.

Parameters

item (str) – The variable name.

Returns

The value of the variable.

Raises

ValueError – If the item is unknown inside the workspace.

Return type

numpy.ndarray

remove_toolbox(toolbox_name)

Remove a toolbox from the engine.

Parameters

toolbox_name (str) – The name of the toolbox to be check.

Return type

None

start_engine()

Start the matlab engine.

Return type

None

start_parallel_computing(n_parallel_workers, parallel_type=ParallelType.LOCAL)

Start the parallel pool of matlab for parallel computing.

This feature only works if parallel toolbox is available.

Parameters

• n_parallel_workers (int) – The number of “workers” to the parallel pool.

• parallel_type (gemseo.wrappers.matlab.engine.ParallelType) –

  The type of parallel execution.

  By default it is set to ParallelType.LOCAL.

Raises

NameError – If parallel_type is not valid.

Return type

None

property is_closed: bool

Return True if the matlab engine is closed.

property is_parallel: bool

Return True if parallel is active.

property paths: list[str]

Return the paths.

class gemseo.wrappers.matlab.engine.ParallelType(value)

Bases: enum.Enum

Types of Matlab parallel execution.

CLOUD = 'MATLAB Parallel Cloud'

LOCAL = 'local'

gemseo.wrappers.matlab.engine.get_matlab_engine(workspace_name='matlab')

Return a new matlab engine.

LRU cache decorator enables to cache the instance if prescribed workspace_name is the same. Therefore, it acts like a singleton. This means that calling this function with the same workspace_name returns the same instance.

Parameters

workspace_name (str) –

The name of matlab workspace.

By default it is set to matlab.

Returns

A Matlab engine instance.

Return type

gemseo.wrappers.matlab.engine.MatlabEngine

Examples

>>> eng1 = get_matlab_engine()
>>> eng2 = get_matlab_engine()
>>> # make sure that engines are the same
>>> eng1 is eng2