gemseo_matlab

Show inherited members

matlab_discipline module

Definition of the Matlab discipline.

Overview

This module contains the MatlabDiscipline which enables to automatically create a wrapper of any Matlab function. This class can be used in order to interface any Matlab code and to use it inside a MDO process.

class gemseo_matlab.matlab_discipline.MatlabDiscipline(matlab_fct, input_names=None, output_names=None, add_subfold_path=False, search_file=None, matlab_engine_name='matlab', matlab_data_file=None, name=None, clean_cache_each_n=None, input_grammar_file=None, output_grammar_file=None, auto_detect_grammar_files=False, check_opt_data=True, cache_type=CacheType.SIMPLE, grammar_type=GrammarType.JSON, cache_file_path=None, is_jac_returned_by_func=False)[source]

Bases: MDODiscipline

Base wrapper for matlab discipline.

Generates a discipline of given matlab function and wrap it to be executed with GEMSEO. Can be used on encrypted, MATLAB build-in and user made function.

Examples

>>> # build the discipline from the MATLAB function "function.m"
>>> disc = MatlabDiscipline("function.m")
>>> # Execute the discipline
>>> disc.execute({"x": array([2.0]), "y": array([1.0])})
>>>
>>> # build discipline with initial data from MATLAB file
>>> disc = MatlabDiscipline("function.m", matlab_data_file="data.mat")
>>> # execute discipline from default values
>>> disc.execute()
>>>
>>> # build discipline from MATLAB file located in matlab_files directory
>>> disc = MatlabDiscipline("function.m", search_file="matlab_files")
>>>
>>> # build discipline with jacobian returned by the matlab function
>>> disc = MatlabDiscipline("function.m", is_jac_returned_by_func=True)
>>> disc.execute({"x": array([2.0]), "y": array([1.0])})
>>> # print jacboian values
>>> print(disc.jac)
Note:

If is_jac_returned_by_func is True, jacobian matrices must be returned by the matlab function itself. In such case, function outputs must contain standard output as well as new outputs for jacobian terms. These new outputs must follow naming convention described in function MatlabDiscipline._get_jac_name(). They can be returned in any order.

Initialize self. See help(type(self)) for accurate signature.

Parameters:

  • matlab_fct (str | Path) – The path of the Matlab file or Name of the function.

  • input_names (Sequence[str] | None) – The input variables.

  • output_names (Sequence[str] | None) – The output variables.

  • add_subfold_path (bool) –

    Whether to add all sub-folder to matlab engine path.

    By default it is set to False.

  • search_file (str | None) – The root directory to launch the research of matlab file.

  • matlab_engine_name (str) –

    The name of the singleton used for this discipline.

    By default it is set to “matlab”.

  • matlab_data_file (str | Path | None) – The .mat file or path containing default values of data.

  • name (str | None) – The name of discipline.

  • clean_cache_each_n (int | None) – Iteration interval at which matlab workspace is cleaned.

  • input_grammar_file (str | None) – The file for input grammar description, if None, name + “_input.json” is used.

  • output_grammar_file (str | None) – The file for output grammar description.

  • auto_detect_grammar_files (bool) –

    If no input and output grammar files are provided, auto_detect_grammar_files uses a naming convention to associate a grammar file to a discipline: searches in the “comp_dir” directory containing the discipline source file for files basenames self.name _input.json and self.name _output.json.

    By default it is set to False.

  • check_opt_data (bool) –

    Whether to check input and output data of discipline.

    By default it is set to True.

  • cache_type (MDODiscipline.CacheType) –

    The type of cache.

    By default it is set to “SimpleCache”.

  • grammar_type (MDODiscipline.GrammarType) –

    The type of the input and output grammars.

    By default it is set to “JSONGrammar”.

  • cache_file_path (str | None) – The file to store the data, mandatory when HDF caching is used.

  • is_jac_returned_by_func (bool) –

    If True, the jacobian matrices should be returned of matlab function with standard outputs. Default is False. If True, the conventional name ‘jac_dout_din’ is used as jacobian term of any output ‘out’ with respect to input ‘in’.

    By default it is set to False.

check_input_data(input_data, raise_exception=True)[source]

Check the input data validity.

Parameters:

  • input_data (Mapping[str, np.ndarray]) – The input data needed to execute the discipline according to the discipline input grammar.

  • raise_exception (bool) –

    Whether to raise on error.

    By default it is set to True.

Return type:

None

check_output_data(raise_exception=True)[source]

Check the output data validity.

Parameters:

raise_exception (bool) –

Whether to raise an exception when the data is invalid.

By default it is set to True.

Return type:

None

save_data_to_matlab(file_path)[source]

Save local data to matlab .mat format.

Parameters:

file_path (str | Path) – The path where to save the file.

Return type:

None

static search_file(file_name, root_dir, extension='.m')[source]

Locate recursively a file in the given root directory.

Parameters:

  • file_name (str) – The name of the file to be located.

  • root_dir (str) – The root directory to launch the research.

  • extension (str) –

    The extension of the file in case not given by user.

    By default it is set to “.m”.

Returns:

The path of the given file.

Raises:

IOError –

  • If two files are found in same directory; * If no file is found.

Return type:

str

JAC_PREFIX: ClassVar[str] = 'jac_'
cache: AbstractCache | None

The cache containing one or several executions of the discipline according to the cache policy.

property cleaning_interval: int

Get and/or set the flushing interval for matlab disciplines.

data_processor: DataProcessor

A tool to pre- and post-process discipline data.

property engine: MatlabEngine

The matlab engine of the discipline.

The engine is associated to the matlab_engine_name provided at the instance construction.

exec_for_lin: bool

Whether the last execution was due to a linearization.

property function_name: str

Return the name of the function.

input_grammar: BaseGrammar

The input grammar.

jac: MutableMapping[str, MutableMapping[str, ndarray | csr_array | JacobianOperator]]

The Jacobians of the outputs wrt inputs.

The structure is {output: {input: matrix}}.

name: str

The name of the discipline.

output_grammar: BaseGrammar

The output grammar.

re_exec_policy: ReExecutionPolicy

The policy to re-execute the same discipline.

residual_variables: dict[str, str]

The output variables mapping to their inputs, to be considered as residuals; they shall be equal to zero.

run_solves_residuals: bool

Whether the run method shall solve the residuals.