gemseo_matlab

Hide inherited members

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_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.

class ParallelType(value)

Bases: StrEnum

Types of Matlab parallel execution.

CLOUD = 'MATLAB Parallel Cloud'

LOCAL = 'local'

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) –

  Whether to add the sub-folders recursively.

  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 checked.

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 | str) – 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:

Any

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 file 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]

get_toolboxes()

Return all toolboxes to be checked before launching this engine.

Returns:

All toolboxes.

Return type:

set[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:

ndarray

remove_toolbox(toolbox_name)

Remove a toolbox from the engine.

Parameters:

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

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 (ParallelType) –

  The type of parallel execution.

  By default it is set to “local”.

Return type:

None

property engine_name: str

The engine name.

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.

gemseo_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:

MatlabEngine

Examples

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