API: high level functions to use GEMSEO¶

This section describes the Application Programming Interface of GEMSEO.

The basics of APIs¶

The aim of the API is to provide high level functions that are sufficient to use GEMSEO in most cases, without requiring a deep knowledge of GEMSEO.

Besides, these functions shall change much less often that the internal classes, which is key for backward compatibility, which means ensuring that your current scripts using on GEMSEO will be usable with the future versions of GEMSEO.

The API also eases the interface GEMSEO within a platform or other software.

See also

To interface a simulation software with GEMSEO, please refer to: Interfacing simulation software.

An API standardizes the programming interface of GEMSEO, and allows to separate inner GEMSEO code from what users see. A few methods are sufficient to create a scenario, execute it and post process it.

See Extend GEMSEO features to learn how to run GEMSEO with external python modules.

Logs¶

To configure the logs, and eventually set a logging file, use configure_logger().

GEMSEO configuration¶

The API function print_configuration() can print the configuration with successfully loaded modules and failed imports with the reason.

About discipline¶

Tip

In order to import easily and instantiate an MDODiscipline, GEMSEO provides a Factory mechanism to avoid manual imports.

Get available disciplines¶

The get_available_disciplines() API function can list the available disciplines:

>>> get_available_disciplines()
['RosenMF', 'Struct', 'SobieskiAerodynamics', 'DOEScenario', 'MDOScenario', 'SobieskiMission', 'SobieskiBaseWrapper', 'Sellar1', 'Sellar2', 'Aero', 'MDOChain', 'SobieskiStructure', 'Aerostruct', 'SobieskiPropulsion', 'Scenario', 'AnalyticDiscipline', 'MDOScenarioAdapter', 'SellarSystem', 'ScalableFittedDiscipline', 'PropaneReaction', 'PropaneComb1', 'PropaneComb2', 'PropaneComb3', 'MDOParallelChain']

Create a discipline¶

The create_discipline() API function can create an MDODiscipline or a list of MDODiscipline by using its name alone; specific **options can be provided in argument; e.g.:

>>> from gemseo.api import create_discipline
>>> disciplines = create_discipline(["SobieskiPropulsion", "SobieskiAerodynamics",
...                                  "SobieskiMission", "SobieskiStructure"])

Get discipline schemas for inputs, outputs and options¶

The API function get_discipline_inputs_schema() can get the JSON schema of the inputs of a discipline; if the argument output_json (default: False) is set to True, this method returns a JSON string, otherwise it returns a dictionary; e.g.:

>>> get_discipline_inputs_schema(disciplines[0])
{u'name': u'SobieskiPropulsion_input', 'required': [u'x_3', u'x_shared', u'y_23'], u'id': u'#SobieskiPropulsion_input', u'$schema': u'http://json-schema.org/draft-04/schema', 'type': u'object', 'properties': {u'x_shared': {'items': {'type': u'number'}, 'type': u'array'}, u'y_23': {'items': {'type': u'number'}, 'type': u'array'}, u'x_3': {'items': {'type': u'number'}, 'type': u'array'}}}

The API function get_discipline_outputs_schema() can get the JSON schema of the outputs of a discipline; if the argument output_json (default: False) is set to True, this method returns a JSON string, otherwise it returns a dictionary; e.g.:

>>> get_discipline_outputs_schema(disciplines[0])
{u'name': u'SobieskiPropulsion_output', 'required': [u'g_3', u'y_3', u'y_31', u'y_32', u'y_34'], u'id': u'#SobieskiPropulsion_output', u'$schema': u'http://json-schema.org/draft-04/schema', 'type': u'object', 'properties': {u'y_31': {'items': {'type': u'number'}, 'type': u'array'}, u'y_32': {'items': {'type': u'number'}, 'type': u'array'}, u'y_3': {'items': {'type': u'number'}, 'type': u'array'}, u'y_34': {'items': {'type': u'number'}, 'type': u'array'}, u'g_3': {'items': {'type': u'number'}, 'type': u'array'}}}

The API function get_discipline_options_schema() can get the JSON schema of the options of a discipline; if the argument output_json (default: False) is set to True, this method returns a JSON string, otherwise it returns a dictionary; e.g.:

>>> get_discipline_options_schema('SobieskiMission')
{u'$schema': u'http://json-schema.org/draft-04/schema', 'required': ['dtype'], 'type': u'object', u'name': u'MDODiscipline_options', 'properties': {u'linearization_mode': {u'enum': [u'auto', u'direct', u'reverse', u'adjoint'], 'type': u'string'}, u'cache_tolerance': {u'minimum': 0, 'type': u'number', 'description': u'Numerical tolerance on the relative norm of input vectors \n to consider that two sets of inputs are equal, and that the outputs may therefore be returned from the cache without calculations.'}, u'jac_approx_n_processes': {u'minimum': 1, 'type': u'integer', 'description': u'maximum number of processors or threads on \nwhich the jacobian approximation is performed\n by default, 1 means no parallel calculations'}, u'cache_type': {u'enum': [u'HDF5_cache', u'simple_cache'], 'type': u'string', 'description': u'Type of cache to be used.  \nBy default, simple cache stores the last execution inputs and outputs  \nin memory only to avoid computation of the outputs if the inputs are identical.\n To store more executions, use HDF5 caches, which stores data on the disk.\n There is a hashing mechanism which avoids reading on the disk for every calculation.'}, 'dtype': {'type': 'string'}, u'cache_hdf_file': {'type': u'string', 'description': u'Path to the HDF5 file to store the cache data.', u'format': u'uri'}, u'jac_approx_use_threading': {'type': u'boolean', 'description': u'if True, use Threads instead of processes\n to parallelize the execution. \nMultiprocessing will serialize all the disciplines, \nwhile multithreading will share all the memory.\n This is important to note if you want to execute the same\n  discipline multiple times, you shall use multiprocessing'}, u'cache_hdf_node_name': {'type': u'string', 'description': u'Name of the HDF dataset to store the discipline\n data. If None, the discipline name is used.'}, u'jac_approx_type': {u'enum': [u'finite_differences', u'complex_step'], 'type': u'string'}, u'jax_approx_step': {'type': u'number', u'minimum': 0, u'exclusiveMinimum': True, 'description': u'Step for finite differences or complex step for Jacobian approximation'}, u'jac_approx_wait_time': {u'minimum': 0, 'type': u'number', 'description': u'Time waited between two forks of the process or thread when using parallel jacobian approximations (parallel=True)'}}}

The API function get_discipline_options_defaults() can get the default values of the JSON schema of the options of a discipline discipline_name; e.g.:

Plot coupling structure¶

The generate_coupling_graph() API function plots the coupling graph of a set of MDODiscipline:

api.generate_coupling_graph(file_path='coupling_graph.pdf', full=True)

Generate a graph of the couplings between disciplines.

Parameters

disciplines (Sequence[MDODiscipline]) – The disciplines from which the graph is generated.
file_path (str | Path) –
The path of the file to save the figure.

By default it is set to coupling_graph.pdf.
full (bool) –
If True, generate the full coupling graph. Otherwise, generate the condensed one.

By default it is set to True.

Return type

None

Examples

>>> from gemseo.api import create_discipline, generate_coupling_graph
>>> disciplines = create_discipline(['Sellar1', 'Sellar2', 'SellarSystem'])
>>> generate_coupling_graph(disciplines)

See also

generate_n2_plot

The generate_n2_plot() API function plots the N2 diagram of a set of MDODiscipline:

api.generate_n2_plot(file_path='n2.pdf', show_data_names=True, save=True, show=False, fig_size=(15.0, 10.0), open_browser=False)

Generate a N2 plot from disciplines.

Parameters

disciplines (Sequence[MDODiscipline]) – The disciplines from which the N2 chart is generated.
file_path (str | Path) –
The file path to save the static N2 chart.

By default it is set to n2.pdf.
show_data_names (bool) –
Whether to show the names of the coupling data ; otherwise, circles are drawn, whose size depends on the number of coupling names.

By default it is set to True.
save (bool) –
Whether to save the static N2 chart.

By default it is set to True.
show (bool) –
Whether to show the static N2 chart.

By default it is set to False.
fig_size (tuple[float, float]) –
The width and height of the static N2 chart.

By default it is set to (15.0, 10.0).
open_browser (bool) –
Whether to display the interactive N2 chart in a browser.

By default it is set to False.

Return type

None

Examples

>>> from gemseo.api import create_discipline, generate_n2_plot
>>> disciplines = create_discipline(['Sellar1', 'Sellar2', 'SellarSystem'])
>>> generate_n2_plot(disciplines)

See also

generate_coupling_graph

About surrogate discipline¶

Similarly, a surrogate discipline can be created. Here are the API functions for that.

Get available surrogate disciplines¶

The API function get_available_surrogates() can list the available surrogate models:

>>> get_available_surrogates()
['LinRegSurrogateDiscipline', 'RBFSurrogateDiscipline', 'GPRSurrogateDiscipline']

Get the surrogate schema for options¶

The API function get_surrogate_options_schema() can get the JSON schema of a surrogate; if the argument output_json (default: False) is set to True, this method returns a JSON string, otherwise it returns a dictionary; e.g.:

>>> get_surrogate_options_schema('RBFSurrogateDiscipline', output_json=True)
'{"required": ["function"], "type": "object", "properties": {"function": {"type": "string", "description": "str or callable, optional\\nThe radial basis function, based on the radius, r, given by the\\n norm\\n:type function: str or callable\\n"}, "input_names": {"description": "list of input names among all inputs in the HDF\\nBy default, takes all inputs in the HDF\\n:type input_names: list(str)\\n"}, "disc_name": {"description": "discipline name\\n:type disc_name: str\\n"}, "train_set": {"description": "sample train set\\n:type train_set: list(int)\\n"}, "epsilon": {"description": "Adjustable constant for gaussian or\\nmultiquadrics functions\\n:type epsilone: float"}, "output_names": {"description": "list of output names among all inputs in the HDF\\nBy default, takes all outputs in the HDF\\n:type output_names: list(str)\\n"}}}'

Create surrogate disciplines¶

The API function create_surrogate() can create a surrogate discipline.
- The mandatory arguments are:
  - surrogate_name: name of the surrogate model (the class name)
  - hdf_file_path: path to the HDF file to be used to train the surrogate
  - hdf_node_path: node name in the HDF, by default the original discipline name
- The optional arguments are:
  - input_names: list of input names among all inputs in the HDF. By default, takes all inputs in the HDF (defaut: None)
  - output_names: list of output names among all outputs in the HDF. By default, takes all outputs in the HDF
  - disc_name: surrogate discipline name
  - **options: additional options to be passed to the surrogate for its construction

See also

See Surrogate models for more details about the API function create_surrogate().

About design space¶

Create a design space¶

To create a standard DesignSpace, the API function create_design_space() can be used.

This function does not take any argument.
This function returns an instance of DesignSpace.

Read a design space¶

In presence of a design space specified in a CSV file, the API function read_design_space() can be used.

Its first argument is the file path of the design space. Its second argument is the list of fields available in the file and is optional.
By default, the design space reads these information from the file.
This function returns an instance of DesignSpace.

See also

See DesignSpace creation and manipulation for more details about the API function create_design_space().

See DesignSpace import and export from disk for more details about the API function read_design_space().

Write a design space¶

To export an instance of DesignSpace into an hdf or txt file, the export_design_space() API function can be used:

api.export_design_space(output_file, export_hdf=False, fields=None, header_char='', **table_options)

Save a design space to a text or HDF file.

Parameters

design_space (DesignSpace) – The design space to be saved.
output_file (str | Path) – The path to the file.
export_hdf (bool) –
If True, save to an HDF file. Otherwise, save to a text file.

By default it is set to False.
fields (Sequence[str] | None) –
The fields to be exported. If None, export all fields.

By default it is set to None.
header_char (str) –
The header character.

By default it is set to .
**table_options (Any) – The names and values of additional attributes for the PrettyTable view generated by DesignSpace.get_pretty_table().

Return type

None

Examples

>>> from gemseo.api import create_design_space, export_design_space
>>> design_space = create_design_space()
>>> design_space.add_variable('x', l_b=-1, u_b=1, value=0.)
>>> export_design_space(design_space, 'file.txt')

About MDO formulations¶

Get available formulations¶

Many API functions allow to discover the MDO formulations and their options.

The API function get_available_formulations() returns the list of available MDO formulations.

>>> get_available_formulations()
['IDF', 'BiLevel', 'MDF', 'DisciplinaryOpt']

Get formulation schemas for (sub-)options¶

For a given MDO formulation named formulation_name, e.g. "MDF", we can:

get its list of option by means of the API function get_formulation_options_schema(); if the argument output_json (default: False) is set to True, this method returns a JSON string, otherwise it returns a dictionary; e.g.:

>>> get_formulation_options_schema("MDF")
{'$schema': 'http://json-schema.org/schema#', 'type': 'object', 'properties': {'maximize_objective': {'description': 'If True, the objective function is maximized.', 'type': 'boolean'}, 'grammar_type': {'description': 'The type of the input and output grammars, either :attr:`.MDODiscipline.JSON_GRAMMAR_TYPE` or :attr:`.MDODiscipline.SIMPLE_GRAMMAR_TYPE`.', 'type': 'string'}, 'main_mda_name': {'description': 'The name of the class used for the main MDA, typically the :class:`.MDAChain`, but one can force to use :class:`.MDAGaussSeidel` for instance.', 'type': 'string'}, 'inner_mda_name': {'description': 'The name of the class used for the inner-MDA of the main MDA, if any; typically when the main MDA is an :class:`.MDAChain`.', 'type': 'string'}}, 'required': ['grammar_type', 'inner_mda_name', 'main_mda_name', 'maximize_objective']}

get its list of sub-options by means of the API function get_formulation_sub_options_schema() when the **options of formulation_name are provided in argument; if the argument output_json (default: False) is set to True, this method returns a JSON string, otherwise it returns a dictionary.
get its list of default option values by means of get_formulations_options_defaults(); if the argument output_json (default: False) is set to True, this method returns a JSON string, otherwise it returns a dictionary.

>>> get_formulations_options_defaults("MDF")
{'maximize_objective': False, 'grammar_type': 'JSONGrammar', 'main_mda_name': 'MDAChain', 'inner_mda_name': 'MDAJacobi'}

get its list of default sub-option values by means of get_formulations_sub_options_defaults() when the **options of formulation_name are provided in argument; if the argument output_json (default: False) is set to True, this method returns a JSON string, otherwise it returns a dictionary.

About scenario¶

Get available scenario type¶

The API function get_available_scenario_types() can be used to get the available scenario types (MDOScenario and DOEScenario)

>>> get_available_scenario_types()
['MDO', 'DOE']

Get scenario schema for inputs and options¶

The API function get_scenario_options_schema() can be used to get the options of a given scenario: if the argument output_json (default: False) is set to True, this method returns a JSON string, otherwise it returns a dictionary; e.g.:

>>> print(get_scenario_options_schema("MDO"))
{u'$schema': u'http://json-schema.org/draft-04/schema', 'required': ['name'], 'type': u'object', u'name': u'MDODiscipline_options', 'properties': {u'linearization_mode': {u'enum': [u'auto', u'direct', u'reverse', u'adjoint'], 'type': u'string'}, u'cache_tolerance': {u'minimum': 0, 'type': u'number', 'description': u'Numerical tolerance on the relative norm of input vectors \n to consider that two sets of inputs are equal, and that the outputs may therefore be returned from the cache without calculations.'}, u'jac_approx_n_processes': {u'minimum': 1, 'type': u'integer', 'description': u'maximum number of processors or threads on \nwhich the jacobian approximation is performed\n by default, 1 means no parallel calculations'}, u'cache_type': {u'enum': [u'HDF5_cache', u'simple_cache'], 'type': u'string', 'description': u'Type of cache to be used.  \nBy default, simple cache stores the last execution inputs and outputs  \nin memory only to avoid computation of the outputs if the inputs are identical.\n To store more executions, use HDF5 caches, which stores data on the disk.\n There is a hashing mechanism which avoids reading on the disk for every calculation.'}, u'cache_hdf_file': {'type': u'string', 'description': u'Path to the HDF5 file to store the cache data.', u'format': u'uri'}, u'jac_approx_use_threading': {'type': u'boolean', 'description': u'if True, use Threads instead of processes\n to parallelize the execution. \nMultiprocessing will serialize all the disciplines, \nwhile multithreading will share all the memory.\n This is important to note if you want to execute the same\n  discipline multiple times, you shall use multiprocessing'}, u'cache_hdf_node_name': {'type': u'string', 'description': u'Name of the HDF dataset to store the discipline\n data. If None, the discipline name is used.'}, u'jac_approx_type': {u'enum': [u'finite_differences', u'complex_step'], 'type': u'string'}, u'jac_approx_wait_time': {u'minimum': 0, 'type': u'number', 'description': u'Time waited between two forks of the process or thread when using parallel jacobian approximations (parallel=True)'}, u'jax_approx_step': {'type': u'number', u'minimum': 0, u'exclusiveMinimum': True, 'description': u'Step for finite differences or complex step for Jacobian approximation'}, 'name': {'description': 'scenario name\n'}}}

The API function get_scenario_inputs_schema() can be used to get the JSONSchema of the inputs of a scenario; if the argument output_json (default: False) is set to True, this method returns a JSON string, otherwise it returns a dictionary.

Get scenario differentiation modes¶

The API function get_scenario_differentiation_modes() can be used to get the available differentiation modes of a scenario:

>>> get_scenario_differentiation_modes()
['user', 'complex_step', 'finite_differences', 'no_derivatives']

Create a scenario¶

The API function create_scenario() can be used to create a scenario:

The four first arguments are mandatory:
1. disciplines: either a list of MDODiscipline or a single MDODiscipline,
2. formulation: the formulation name (available formulations can be listed by using the API function gemseo.api.get_available_formulations()),
3. objective_name: the name of the objective function (one of the discipline outputs, which can be listed by using the function gemseo.disciplines.utils.get_all_outputs())
4. design_space: the DesignSpace or the file path of the design space the design variables are a subset of all the discipline inputs, which can be obtained by using get_all_inputs() .
The other arguments are optional:
- name: scenario name,
- scenario_type: type of scenario, either "MDO" (default) or "DOE",
- **options: options passed to the formulation,
This function returns an instance of MDOScenario or DOEScenario.

See also

See this part of the Sellar’s tutorial for more details about the API function create_scenario().

The API function monitor_scenario() can be used to add an observer to a scenario; the observer must have an “update(atom)” method that handles the execution status change of atom ; update(atom) is called everytime an atom execution changes; if the argument output_json (default: False) is set to True, this method returns a JSON string, otherwise it returns a dictionary.

Monitor a scenario¶

To monitor a scenario execution programmatically, ie get a notification when a discipline status is changed, use monitor_scenario(). The first argument is the scenario to monitor, and the second is an observer object, that is notified by its update(atom) method, which takes an AtomicExecSequence as argument. This method will be called every time a discipline status changes. The atom represents a discipline’s position in the process. One discipline can have multiple atoms, since one discipline can be used in multiple positions in the MDO formulation.

For more details on monitoring, see Monitoring the execution of a scenario.

About optimization and DOE algorithms¶

Get available algorithms and associated options¶

To execute a scenario, a driver must be selected. Here are the API functions for that.

The API function get_available_opt_algorithms() can list the available optimization algorithms:

>>> get_available_opt_algorithms()
['NLOPT_SLSQP', 'L-BFGS-B', 'SLSQP', 'NLOPT_COBYLA', 'NLOPT_BFGS', 'NLOPT_NEWUOA', 'TNC', 'P-L-BFGS-B', 'NLOPT_MMA', 'NLOPT_BOBYQA', 'ODD']

The API function get_available_doe_algorithms() can list the available DOE algorithms:

>>> get_available_doe_algorithms()
['ff2n', 'OT_FACTORIAL', 'OT_FAURE', 'OT_HASELGROVE', 'OT_REVERSE_HALTON', 'OT_HALTON', 'ccdesign', 'OT_SOBOL', 'fullfact', 'OT_FULLFACT', 'OT_AXIAL', 'lhs', 'OT_LHSC', 'OT_MONTE_CARLO', 'OT_RANDOM', 'OT_COMPOSITE', 'CustomDOE', 'pbdesign', 'OT_LHS', 'bbdesign']

The API function get_algorithm_options_schema() can list the available options of the algorithm algorithm_name; if the argument output_json (default: False) is set to True, this method returns a JSON string, otherwise it returns a dictionary; e.g.:

>>> get_algorithm_options_schema('OT_HALTON')
{u'$schema': u'http://json-schema.org/draft-04/schema', 'type': u'object', u'name': u'OPENTURNS_options', 'properties': {u'wait_time_between_samples': {u'minimum': 0, 'type': u'number'}, u'n_processes': {u'minimum': 1, 'type': u'integer'}, u'end': {'type': u'number'}, u'distribution_name': {u'enum': [u'Arcsine', u'Beta', u'Dirichlet', u'Normal', u'TruncatedNormal', u'Triangular', u'Trapezoidal', u'Uniform'], 'description': 'Default value = "Uniform")\n'}, u'eval_jac': {'type': u'boolean'}, u'mu': {'type': u'number'}, u'start': {'type': u'number'}, u'levels': {'items': {u'minItems': 1, 'type': u'number'}, 'type': u'array', 'description': 'Default value = None)\n'}, u'n_samples': {u'minimum': 1, 'type': u'integer'}, u'sigma': {'type': u'number'}, u'centers': {'items': {u'minItems': 1, 'type': u'number'}, 'type': u'array', 'description': 'Default value = None)\n'}}}

Execute an algorithm¶

We can apply a DOE or optimization algorithm to an OptimizationProblem by means of the execute_algo() algorithm:

>>> from gemseo.problems.analytical.rastrigin import Rastrigin
>>> from gemseo.api import execute_algo
>>>
>>> opt_problem = Rastrigin()
>>> execute_algo(opt_problem, 'SLSQP')
INFO - 12:59:49 : Optimization problem:
INFO - 12:59:49 :       Minimize: Rastrigin(x) = 20 + sum(x[i]**2 - 10*cos(2pi*x[i]))
INFO - 12:59:49 : With respect to:
INFO - 12:59:49 :     x
INFO - 12:59:49 : Design Space:
INFO - 12:59:49 : +------+-------------+-------+-------------+-------+
INFO - 12:59:49 : | name | lower_bound | value | upper_bound | type  |
INFO - 12:59:49 : +------+-------------+-------+-------------+-------+
INFO - 12:59:49 : | x    |     -0.1    |  0.01 |     0.1     | float |
INFO - 12:59:49 : | x    |     -0.1    |  0.01 |     0.1     | float |
INFO - 12:59:49 : +------+-------------+-------+-------------+-------+
INFO - 12:59:49 : Optimization: |          | 0/999   0% [elapsed: 00:00 left: ?, ? iters/sec]
INFO - 12:59:49 : Optimization: |          | 4/999   0% [elapsed: 00:00 left: 00:00, 1949.25 iters/sec obj:  0.00 ]
INFO - 12:59:49 : Optimization result:
INFO - 12:59:49 : Objective value = 1.37852396165e-10
INFO - 12:59:49 : The result is feasible.
INFO - 12:59:49 : Status: 0
INFO - 12:59:49 : Optimizer message: Optimization terminated successfully.
INFO - 12:59:49 : Number of calls to the objective function by the optimizer: 5
INFO - 12:59:49 : Constraints values:
INFO - 12:59:49 :
INFO - 12:59:49 : Design Space:
INFO - 12:59:49 : +------+-------------+-----------------------+-------------+-------+
INFO - 12:59:49 : | name | lower_bound |         value         | upper_bound | type  |
INFO - 12:59:49 : +------+-------------+-----------------------+-------------+-------+
INFO - 12:59:49 : | x    |     -0.1    | 5.894250055538119e-07 |     0.1     | float |
INFO - 12:59:49 : | x    |     -0.1    | 5.894250055538119e-07 |     0.1     | float |
INFO - 12:59:49 : +------+-------------+-----------------------+-------------+-------+

About MDA¶

Here are the API functions for MDA.

The API function get_available_mdas() can list the available MDAs:

>>> get_available_mdas()
['MDANewtonRaphson', 'MDAChain', 'MDARoot', 'MDAQuasiNewton', 'MDAGaussSeidel', 'GSNewtonMDA', 'MDASequential', 'MDAJacobi']

The API function get_mda_options_schema() can list the available options of an MDA; if the argument output_json (default: False) is set to True, this method returns a JSON string, otherwise it returns a dictionary; e.g.

>>> get_mda_options_schema('MDAGaussSeidel')
{'required': ['grammar_type', 'linear_solver_tolerance', 'max_mda_iter', 'tolerance', 'use_lu_fact', 'warm_start'], 'type': 'object', 'properties': {'warm_start': {'type': 'boolean', 'description': 'if True, the second iteration and ongoing\nstart from the previous coupling solution\n:type warm_start: bool\n'}, 'name': {'description': 'the name of the chain\n:type name: str\n'}, 'use_lu_fact': {'type': 'boolean', 'description': 'if True, when using adjoint/forward\ndifferenciation, store a LU factorization of the matrix\nto solve faster multiple RHS problem\n:type use_lu_fact: bool'}, 'grammar_type': {'type': 'string', 'description': 'the type of grammar to use for IO declaration\neither JSON_GRAMMAR_TYPE or SIMPLE_GRAMMAR_TYPE\n:type grammar_type: str\n'}, 'linear_solver_tolerance': {'type': 'number', 'description': 'Tolerance of the linear solver\nin the adjoint equation\n:type linear_solver_tolerance: float\n'}, 'max_mda_iter': {'type': 'integer', 'description': 'maximum number of iterations\n:type max_mda_iter: int\n'}, 'tolerance': {'type': 'number', 'description': 'tolerance of the iterative direct coupling solver,\nnorm of the current residuals divided by initial residuals norm\nshall be lower than the tolerance to stop iterating\n:type tolerance: float\n'}}}

The API function create_mda() can create a MDA called mda_name, from a list of disciplines and additional **options.

See also

See Multi Disciplinary Analyses for more details about the API function get_available_mdas()

About post processing¶

GEMSEO provides various methods to post process the results. Here are the API functions for that.

The API function get_available_post_processings() can list the available visualizations in the current GEMSEO setup (depending on plugins and availability of dependencies),

>>> get_available_post_processings()
['ScatterPlotMatrix', 'VariableInfluence', 'RadarChart', 'ConstraintsHistory', 'SOM', 'Correlations', 'Robustness', 'KMeans', 'ParallelCoordinates', 'GradientSensitivity', 'OptHistoryView', 'BasicHistory', 'ObjConstrHist', 'QuadApprox']

The API function get_post_processing_options_schema() can list the available options of the post processing post_proc_name; e.g.: if the argument output_json (default: False) is set to True, this method returns a JSON string, otherwise it returns a dictionary; e.g.:

>>> get_post_processing_options_schema('RadarChart')
{u'name': u'RadarChart_options', 'required': [u'constraint_names', u'save'], u'$schema': u'http://json-schema.org/draft-04/schema', 'type': u'object', 'properties': {u'save': {'type': u'boolean', 'description': 'if True, exports plot to pdf\n'}, u'iteration': {'type': u'integer', 'description': 'number of iteration to post process\n'}, u'file_path': {'type': u'string', 'description': 'the base paths of the files to export'}, u'contraint_names': {'items': {u'minItems': 1, 'type': u'string'}, 'type': u'array', 'description': 'list of constraints names\n'}, u'show': {'type': u'boolean', 'description': 'if True, display plot\n'}}}

The API function execute_post() can generate visualizations of the MDO results. For that, it consider the object to post process to_post_proc, the post processing post_name with its **options; e.g.:

api.execute_post(post_name, **options)

Post-process a result.

Parameters

to_post_proc (Scenario | OptimizationProblem | str | Path) – The result to be post-processed, either a DOE scenario, a MDO scenario, an optimization problem or a path to an HDF file containing a saved optimization problem.
post_name (str) – The name of the post-processing.
**options (Any) – The post-processing options.

Returns

The figures, to be customized if not closed.

Return type

dict[str, Figure]

Examples

>>> from gemseo.api import create_discipline, create_scenario, execute_post
>>> from gemseo.problems.sellar.sellar_design_space import SellarDesignSpace
>>> disciplines = create_discipline(['Sellar1', 'Sellar2', 'SellarSystem'])
>>> design_space = SellarDesignSpace()
>>> scenario = create_scenario(disciplines, 'MDF', 'obj', design_space,
>>>                            'SellarMDFScenario', 'MDO')
>>> scenario.execute({'algo': 'NLOPT_SLSQP', 'max_iter': 100})
>>> execute_post(scenario, 'OptHistoryView', show=False, save=True)