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 functionMatlabDiscipline._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.
- 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:
- Returns:
The path of the given file.
- Raises:
IOError –
If two files are found in same directory; * If no file is found.
- Return type:
- 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.