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)[source]
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)[source]
Bases:
StrEnum
Types of Matlab parallel execution.
- CLOUD = 'MATLAB Parallel Cloud'
- LOCAL = 'local'
- add_path(path, add_subfolder=False)[source]
Add a path to the matlab engine search directories.
- Parameters:
- Raises:
ValueError – If the given path cannot be added to Matlab.
- Return type:
None
- add_toolbox(toolbox_name)[source]
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()[source]
Close the matlab session.
- Return type:
None
- end_parallel_computing()[source]
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)[source]
Executes a Matlab function called “func_name”.
- Parameters:
- Raises:
matlab.engine.MatlabExecutionError – If the matlab function execution fails.
- Return type:
Any
- execute_script(script_name)[source]
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)[source]
Check if the given matlab file exists.
- get_toolboxes()[source]
Return all toolboxes to be checked before launching this engine.
- get_variable(item)[source]
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:
- remove_toolbox(toolbox_name)[source]
Remove a toolbox from the engine.
- Parameters:
toolbox_name (str) – The name of the toolbox to be checked.
- Return type:
None
- start_engine()[source]
Start the matlab engine.
- Return type:
None
- start_parallel_computing(n_parallel_workers, parallel_type=ParallelType.LOCAL)[source]
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.
- gemseo_matlab.engine.get_matlab_engine(workspace_name='matlab')[source]
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 sameworkspace_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:
Examples
>>> eng1 = get_matlab_engine() >>> eng2 = get_matlab_engine() >>> # make sure that engines are the same >>> eng1 is eng2