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)[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.
- Return type
None
- 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 check.
- 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
float | ndarray
- 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
- 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 check.
- 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 (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
- class gemseo.wrappers.matlab.engine.ParallelType(value)[source]¶
Bases:
enum.Enum
Types of Matlab parallel execution.
- CLOUD = 'MATLAB Parallel Cloud'¶
- LOCAL = 'local'¶
- gemseo.wrappers.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