gemseo package#

GEMSEO main package.

This module contains the high-level functions to easily use GEMSEO without requiring a deep knowledge of this software.

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

The high-level functions also facilitate the interfacing of GEMSEO with a platform or other software.

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

See also Extend GEMSEO features.

compute_doe(variables_space, unit_sampling=False, settings_model=None, **settings)[source]#

Compute a design of experiments (DOE) in a variables space.

Parameters:

variables_space (DesignSpace | int) -- Either the variables space to be sampled or its dimension.
unit_sampling (bool) --
Whether to sample in the unit hypercube. If the value provided in variables_space is the dimension, the samples will be generated in the unit hypercube whatever the value of unit_sampling.

By default it is set to False.
settings_model (BaseDOESettings | None) -- The DOE settings as a Pydantic model. If None, use **settings.
**settings (DriverSettingType) -- The DOE settings, including the algorithm name (use the keyword "algo_name"). These arguments are ignored when settings_model is not None.

Returns:

The design of experiments whose rows are the samples and columns the variables.

Return type:

ndarray

Examples

>>> from gemseo import compute_doe, create_design_space
>>> variables_space = create_design_space()
>>> variables_space.add_variable("x", 2, lower_bound=-1.0, upper_bound=1.0)
>>> doe = compute_doe(variables_space, algo_name="lhs", n_samples=5)

configure(enable_discipline_statistics=True, enable_function_statistics=True, enable_progress_bar=True, enable_discipline_cache=True, validate_input_data=True, validate_output_data=True, check_desvars_bounds=True)[source]#

Update the configuration of GEMSEO if needed.

This could be useful to speed up calculations in presence of cheap disciplines such as analytic formula and surrogate models.

Warning

This function should be called before calling anything from GEMSEO.

Parameters:

enable_discipline_statistics (bool) --
Whether to record execution statistics of the disciplines such as the execution time, the number of executions and the number of linearizations.

By default it is set to True.
enable_function_statistics (bool) --
Whether to record the statistics attached to the functions, in charge of counting their number of evaluations.

By default it is set to True.
enable_progress_bar (bool) --
Whether to enable the progress bar attached to the drivers, in charge to log the execution of the process: iteration, execution time and objective value.

By default it is set to True.
enable_discipline_cache (bool) --
Whether to enable the discipline cache.

By default it is set to True.
validate_input_data (bool) --
Whether to validate the input data of a discipline before execution.

By default it is set to True.
validate_output_data (bool) --
Whether to validate the output data of a discipline after execution.

By default it is set to True.
check_desvars_bounds (bool) --
Whether to check the membership of design variables in the bounds when evaluating the functions in OptimizationProblem.

By default it is set to True.

Return type:

None

configure_logger(logger_name='', level=20, date_format='%H:%M:%S', message_format='%(levelname)8s - %(asctime)s: %(message)s', filename='', filemode='a')[source]#

Configure GEMSEO logging.

Parameters:

logger_name (str) --
The name of the logger to configure. If empty, configure the root logger.

By default it is set to "".
level (str | int) --
The numerical value or name of the logging level, as defined in logging. Values can either be logging.NOTSET ("NOTSET"), logging.DEBUG ("DEBUG"), logging.INFO ("INFO"), logging.WARNING ("WARNING" or "WARN"), logging.ERROR ("ERROR"), or logging.CRITICAL ("FATAL" or "CRITICAL").

By default it is set to 20.
date_format (str) --
The logging date format.

By default it is set to "%H:%M:%S".
message_format (str) --
The logging message format.

By default it is set to "%(levelname)8s - %(asctime)s: %(message)s".
filename (str | Path) --
The path to the log file, if outputs must be written in a file.

By default it is set to "".
filemode (str) --
The logging output file mode, either 'w' (overwrite) or 'a' (append).

By default it is set to "a".

Returns:

The configured logger.

Return type:

Logger

Examples

>>> import logging
>>> configure_logger(level=logging.WARNING)

create_benchmark_dataset(dataset_type, **options)[source]#

Instantiate a dataset.

Typically, benchmark datasets can be found in gemseo.datasets.dataset.

Parameters:

dataset_type (DatasetType) -- The type of the dataset.
**options (Any) -- The options for creating the dataset.

Returns:

The dataset.

Return type:

Dataset

create_cache(cache_type, name='', **options)[source]#

Return a cache.

Parameters:

cache_type (str) -- The type of the cache.
name (str) --
The name to be given to the cache. If empty, use cache_type.

By default it is set to "".
**options (Any) -- The options of the cache.

Returns:

The cache.

Return type:

BaseCache

Examples

>>> from gemseo import create_cache
>>> cache = create_cache("MemoryFullCache")
>>> print(cache)
+--------------------------------+
|        MemoryFullCache         |
+--------------+-----------------+
|   Property   |      Value      |
+--------------+-----------------+
|     Type     | MemoryFullCache |
|  Tolerance   |       0.0       |
| Input names  |       None      |
| Output names |       None      |
|    Length    |        0        |
+--------------+-----------------+

create_dataset(name='', data='', variable_names=(), variable_names_to_n_components=mappingproxy({}), variable_names_to_group_names=mappingproxy({}), delimiter=',', header=True, class_name=DatasetClassName.Dataset)[source]#

Create a dataset from a NumPy array or a data file.

Parameters:

name (str) --
The name to be given to the dataset.

By default it is set to "".
data (ndarray | str | Path) --
The data to be stored in the dataset, either a NumPy array or a file path. If empty, return an empty dataset.

By default it is set to "".
variable_names (str | Iterable[str]) --
The names of the variables. If empty, use default names.

By default it is set to ().
variable_names_to_n_components (dict[str, int]) --
The number of components of the variables. If empty, assume that all the variables have a single component.

By default it is set to {}.
variable_names_to_group_names (dict[str, str]) --
The groups of the variables. If empty, use Dataset.DEFAULT_GROUP for all the variables.

By default it is set to {}.
delimiter (str) --
The field delimiter.

By default it is set to ",".
header (bool) --
If True and data is a string, read the variables names on the first line of the file.

By default it is set to True.
class_name (DatasetClassName) --
The name of the dataset class.

By default it is set to "Dataset".

Returns:

The dataset generated from the NumPy array or data file.

Raises:

ValueError -- If data is neither a file nor an array.

Return type:

Dataset

create_design_space()[source]#

Create an empty design space.

Returns:: An empty design space.
Return type:: DesignSpace

Examples

>>> from gemseo import create_design_space
>>> design_space = create_design_space()
>>> design_space.add_variable("x", lower_bound=-1, upper_bound=1, value=0.0)
>>> print(design_space)
Design Space:
+------+-------------+-------+-------------+-------+
| name | lower_bound | value | upper_bound | type  |
+------+-------------+-------+-------------+-------+
| x    |      -1     |   0   |      1      | float |
+------+-------------+-------+-------------+-------+

create_discipline(discipline_name, **options)[source]#

Instantiate one or more disciplines.

Parameters:

discipline_name (str | Iterable[str]) -- Either the name of a discipline or the names of several disciplines.
**options (Any) -- The options to be passed to the disciplines constructors.

Returns:

The disciplines.

Return type:

Discipline | list[Discipline]

Examples

>>> from gemseo import create_discipline
>>> discipline = create_discipline("Sellar1")
>>> discipline.execute()
{'x_local': array([0.+0.j]),
 'x_shared': array([1.+0.j, 0.+0.j]),
 'y_0': array([0.89442719+0.j]),
 'y_1': array([1.+0.j])}

create_mda(mda_name, disciplines, **mda_settings)[source]#

Create a multidisciplinary analysis (MDA).

Parameters:

mda_name (str) -- The name of the MDA.
disciplines (Sequence[Discipline]) -- The disciplines.
**mda_settings (Any) -- The settings of the MDA.

Returns:

The MDA.

Return type:

BaseMDA

Examples

>>> from gemseo import create_discipline, create_mda
>>> disciplines = create_discipline(["Sellar1", "Sellar2"])
>>> mda = create_mda("MDAGaussSeidel", disciplines)
>>> mda.execute()
{'x_local': array([0.+0.j]),
 'x_shared': array([1.+0.j, 0.+0.j]),
 'y_0': array([0.79999995+0.j]),
 'y_1': array([1.79999995+0.j])}

create_parameter_space()[source]#

Create an empty parameter space.

Returns:: An empty parameter space.
Return type:: ParameterSpace

create_scalable(name, data, sizes=mappingproxy({}), **parameters)[source]#

Create a scalable discipline from a dataset.

Parameters:

name (str) -- The name of the class of the scalable model.
data (Dataset) -- The learning dataset.
sizes (Mapping[str, int]) --
The sizes of the input and output variables.

By default it is set to {}.
**parameters (Any) -- The parameters of the scalable model.

Returns:

The scalable discipline.

Return type:

ScalableDiscipline

create_scenario(disciplines, objective_name, design_space, name='', scenario_type='MDO', maximize_objective=False, formulation_settings_model=None, **formulation_settings)[source]#

Initialize a scenario.

Parameters:

disciplines (Sequence[Discipline] | Discipline) -- The disciplines used to compute the objective, constraints and observables from the design variables.
objective_name (str) -- The name(s) of the discipline output(s) used as objective. If multiple names are passed, the objective will be a vector.
design_space (DesignSpace | str | Path) -- The search space including at least the design variables (some formulations requires additional variables, e.g. IDF with the coupling variables).
name (str) --
The name to be given to this scenario. If empty, use the name of the class.

By default it is set to "".
scenario_type (str) --
The type of the scenario, e.g. "MDO" or "DOE".

By default it is set to "MDO".
maximize_objective (bool) --
Whether to maximize the objective.

By default it is set to False.
formulation_settings_model (BaseFormulationSettings | None) -- The formulation settings as a Pydantic model, including the formulation name (use the keyword "formulation"). If None, use **settings.
**formulation_settings (Any) -- The formulation settings. These arguments are ignored when settings_model is not None.

Return type:

BaseScenario

Examples

>>> from gemseo import create_discipline, create_scenario
>>> from gemseo.problems.mdo.sellar.sellar_design_space import (
...     SellarDesignSpace,
... )
>>> disciplines = create_discipline(["Sellar1", "Sellar2", "SellarSystem"])
>>> design_space = SellarDesignSpace()
>>> scenario = create_scenario(
>>>     disciplines, "obj", design_space, formulation_name="MDF"
>>> )

create_scenario_result(scenario, name='', **options)[source]#

Create the result of a scenario execution.

Parameters:

scenario (BaseScenario | str | Path) -- The scenario to post-process or its path to its HDF5 file.
name (str) --
The class name of the ScenarioResult. If empty, use the DEFAULT_SCENARIO_RESULT_CLASS_NAME of the BaseMDOFormulation attached to the Scenario.

By default it is set to "".
**options (Any) -- The options of the ScenarioResult.

Returns:

The result of a scenario execution or None if not yet executed`.

Return type:

ScenarioResult | None

create_surrogate(surrogate, data=None, transformer=mappingproxy({'inputs': <gemseo.mlearning.transformers.scaler.min_max_scaler.MinMaxScaler object>, 'outputs': <gemseo.mlearning.transformers.scaler.min_max_scaler.MinMaxScaler object>}), disc_name='', default_input_data=mappingproxy({}), input_names=(), output_names=(), **parameters)[source]#

Create a surrogate discipline, either from a dataset or a regression model.

Parameters:

surrogate (str | BaseRegressor) -- Either the name of a subclass of BaseRegressor or an instance of this subclass.
data (IODataset | None) -- The learning dataset to train the regression model. If None, the regression model is supposed to be trained.
transformer (TransformerType) --
The strategies to transform the variables. This argument is ignored when surrogate is a BaseRegressor; in this case, these strategies are defined with the transformer argument of this BaseRegressor, whose default value is BaseMLAlgo.IDENTITY, which means no transformation. In the other cases, the values of the dictionary are instances of BaseTransformer while the keys can be variable names, the group name "inputs" or the group name "outputs". If a group name is specified, the BaseTransformer will be applied to all the variables of this group. If BaseMLAlgo.IDENTITY, do not transform the variables. The BaseRegressor.DEFAULT_TRANSFORMER uses the MinMaxScaler strategy for both input and output variables.

By default it is set to {'inputs': <gemseo.mlearning.transformers.scaler.min_max_scaler.MinMaxScaler object at 0x7f25175ed280>, 'outputs': <gemseo.mlearning.transformers.scaler.min_max_scaler.MinMaxScaler object at 0x7f25175ed490>}.
disc_name (str) --
The name to be given to the surrogate discipline. If empty, the name will be f"{surrogate.SHORT_ALGO_NAME}_{data.name}.

By default it is set to "".
default_input_data (dict[str, ndarray]) --
The default values of the input variables. If empty, use the center of the learning input space.

By default it is set to {}.
input_names (Iterable[str]) --
The names of the input variables. If empty, consider all input variables mentioned in the learning dataset.

By default it is set to ().
output_names (Iterable[str]) --
The names of the output variables. If empty, consider all input variables mentioned in the learning dataset.

By default it is set to ().
**parameters (Any) -- The parameters of the machine learning algorithm.

Return type:

SurrogateDiscipline

execute_algo(opt_problem, algo_type='opt', settings_model=None, **settings)[source]#

Solve an optimization problem.

Parameters:

opt_problem (OptimizationProblem) -- The optimization problem to be solved.
algo_type (str) --
The type of algorithm, either "opt" for optimization or "doe" for design of experiments.

By default it is set to "opt".
settings_model (BaseAlgorithmSettings | None) -- The algorithm settings as a Pydantic model. If None, use **settings.
**settings (Any) -- The algorithm settings, including the algorithm name (use the keyword "algo_name"). These arguments are ignored when settings_model is not None.

Return type:

OptimizationResult

Examples

>>> from gemseo import execute_algo
>>> from gemseo.problems.optimization.rosenbrock import Rosenbrock
>>> opt_problem = Rosenbrock()
>>> opt_result = execute_algo(opt_problem, algo_name="SLSQP")
>>> opt_result
Optimization result:
|_ Design variables: [0.99999787 0.99999581]
|_ Objective function: 5.054173713127532e-12
|_ Feasible solution: True

execute_post(to_post_proc, settings_model=None, **settings)[source]#

Post-process a result.

Parameters:

to_post_proc (BaseScenario | OptimizationProblem | str | Path) -- The result to be post-processed, either a DOE scenario, an MDO scenario, an optimization problem or a path to an HDF file containing a saved optimization problem.
settings_model (BasePostSettings | None) -- The post-processor settings as a Pydantic model. If None, use **settings.
**settings (Any) -- The post-processor settings, including the algorithm name (use the keyword "post_name"). These arguments are ignored when settings_model is not None.

Returns:

The post-processor.

Return type:

BasePost

Examples

>>> from gemseo import create_discipline, create_scenario, execute_post
>>> from gemseo.problems.mdo.sellar.sellar_design_space import (
...     SellarDesignSpace,
... )
>>> disciplines = create_discipline(["Sellar1", "Sellar2", "SellarSystem"])
>>> design_space = SellarDesignSpace()
>>> scenario = create_scenario(
...     disciplines,
...     "obj",
...     design_space,
...     formulation_name="MDF",
...     name="SellarMDFScenario",
... )
>>> scenario.execute(algo_name="NLOPT_SLSQP", max_iter=100)
>>> execute_post(scenario, post_name="OptHistoryView", show=False, save=True)

generate_coupling_graph(disciplines, file_path='coupling_graph.pdf', full=True)[source]#

Generate a graph of the couplings between disciplines.

Parameters:

disciplines (Sequence[Discipline]) -- The disciplines from which the graph is generated.
file_path (str | Path) --
The path of the file to save the figure. If empty, the figure is not saved.

By default it is set to "coupling_graph.pdf".
full (bool) --
Whether to generate the full coupling graph. Otherwise, the condensed coupling graph is generated.

By default it is set to True.

Returns:

Either the graph of the couplings between disciplines or None when graphviz is not installed.

Return type:

GraphView | None

Examples

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

generate_n2_plot(disciplines, file_path='n2.pdf', show_data_names=True, save=True, show=False, fig_size=(15.0, 10.0), show_html=False)[source]#

Generate a N2 plot from disciplines.

It can be static (e.g. PDF, PNG, ...), dynamic (HTML) or both.

The disciplines are located on the diagonal of the N2 plot while the coupling variables are situated on the other blocks of the matrix view. A coupling variable is outputted by a discipline horizontally and enters another vertically. On the static plot, a blue diagonal block represents a self-coupled discipline, i.e. a discipline having some of its outputs as inputs.

Parameters:

disciplines (Sequence[Discipline]) -- 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 variables between two disciplines; 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 (FigSizeType) --
The width and height of the static N2 chart.

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

By default it is set to False.

Return type:

None

Examples

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

generate_xdsm(discipline, directory_path='.', file_name='xdsm', show_html=False, save_html=True, save_json=False, save_pdf=False, pdf_build=True, pdf_cleanup=True, pdf_batchmode=True)[source]#

Create the XDSM diagram of a discipline.

Parameters:

directory_path (str | Path) --
The path of the directory to save the files.

By default it is set to ".".
file_name (str) --
The file name without the file extension.

By default it is set to "xdsm".
show_html (bool) --
Whether to open the web browser and display the XDSM.

By default it is set to False.
save_html (bool) --
Whether to save the XDSM as a HTML file.

By default it is set to True.
save_json (bool) --
Whether to save the XDSM as a JSON file.

By default it is set to False.
save_pdf (bool) --
Whether to save the XDSM as a PDF file; use save_pdf=True and pdf_build=False to generate the file_name.tex and file_name.tikz files without building the PDF file.

By default it is set to False.
pdf_build (bool) --
Whether to generate the PDF file when save_pdf is True.

By default it is set to True.
pdf_cleanup (bool) --
Whether to clean up the intermediate files (file_name.tex, file_name.tikz and built files) used to build the PDF file.

By default it is set to True.
pdf_batchmode (bool) --
Whether pdflatex is run in batchmode.

By default it is set to True.
discipline (Discipline)

Returns:

The XDSM diagram of the discipline.

Return type:

XDSM

get_algorithm_options_schema(algorithm_name, output_json=False, pretty_print=False)[source]#

Return the schema of the options of an algorithm.

Parameters:

algorithm_name (str) -- The name of the algorithm.
output_json (bool) --
Whether to apply the JSON format to the schema.

By default it is set to False.
pretty_print (bool) --
Whether to print the schema in a tabular way.

By default it is set to False.

Returns:

The schema of the options of the algorithm.

Raises:

ValueError -- When the algorithm is not available.

Return type:

str | dict[str, Any]

Examples

>>> from gemseo import get_algorithm_options_schema
>>> schema = get_algorithm_options_schema("NLOPT_SLSQP", pretty_print=True)

get_available_caches()[source]#

Return the names of the available caches.

Returns:: The names of the available caches.
Return type:: list[str]

Examples

>>> from gemseo import get_available_caches
>>> get_available_caches()
['BaseFullCache', 'HDF5Cache', 'MemoryFullCache', 'SimpleCache']

get_available_disciplines()[source]#

Return the names of the available disciplines.

Returns:: The names of the available disciplines.
Return type:: list[str]

Examples

>>> from gemseo import get_available_disciplines
>>> print(get_available_disciplines())
['RosenMF', 'SobieskiAerodynamics', 'ScalableKriging', 'DOEScenario',
'MDOScenario', 'SobieskiMission', 'SobieskiDiscipline', 'Sellar1',
'Sellar2', 'MDOChain', 'SobieskiStructure', 'AutoPyDiscipline',
'Structure', 'SobieskiPropulsion', 'Scenario', 'AnalyticDiscipline',
'MDOScenarioAdapter', 'ScalableDiscipline', 'SellarSystem', 'Aerodynamics',
'Mission', 'PropaneComb1', 'PropaneComb2', 'PropaneComb3',
'PropaneReaction', 'MDOParallelChain']

get_available_doe_algorithms()[source]#

Return the names of the available design of experiments (DOEs) algorithms.

Returns:: The names of the available DOE algorithms.
Return type:: list[str]

Examples;

>>> from gemseo import get_available_doe_algorithms
>>> get_available_doe_algorithms()

get_available_formulations()[source]#

Return the names of the available formulations.

Returns:: The names of the available MDO formulations.
Return type:: list[str]

Examples

>>> from gemseo import get_available_formulations
>>> get_available_formulations()

get_available_mdas()[source]#

Return the names of the available multidisciplinary analyses (MDAs).

Returns:: The names of the available MDAs.
Return type:: list[str]

Examples

>>> from gemseo import get_available_mdas
>>> get_available_mdas()

get_available_opt_algorithms()[source]#

Return the names of the available optimization algorithms.

Returns:: The names of the available optimization algorithms.
Return type:: list[str]

Examples

>>> from gemseo import get_available_opt_algorithms
>>> get_available_opt_algorithms()

get_available_post_processings()[source]#

Return the names of the available optimization post-processings.

Returns:: The names of the available post-processings.
Return type:: list[str]

Examples

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

get_available_scenario_types()[source]#

Return the names of the available scenario types.

Returns:: The names of the available scenario types.
Return type:: list[str]

Examples

>>> from gemseo import get_available_scenario_types
>>> get_available_scenario_types()

get_available_surrogates()[source]#

Return the names of the available surrogate disciplines.

Returns:: The names of the available surrogate disciplines.
Return type:: list[str]

Examples

>>> from gemseo import get_available_surrogates
>>> print(get_available_surrogates())
['RBFRegressor', 'GaussianProcessRegressor', 'LinearRegressor', 'PCERegressor']

get_discipline_inputs_schema(discipline, output_json=False, pretty_print=False)[source]#

Return the schema of the inputs of a discipline.

Parameters:

discipline (Discipline) -- The discipline.
output_json (bool) --
Whether to apply the JSON format to the schema.

By default it is set to False.
pretty_print (bool) --
Whether to print the schema in a tabular way.

By default it is set to False.

Returns:

The schema of the inputs of the discipline.

Return type:

str | dict[str, Any]

Examples

>>> from gemseo import create_discipline, get_discipline_inputs_schema
>>> discipline = create_discipline("Sellar1")
>>> schema = get_discipline_inputs_schema(discipline, pretty_print=True)

get_discipline_options_defaults(discipline_name)[source]#

Return the default values of the options of a discipline.

Parameters:: discipline_name (str) -- The name of the discipline.
Returns:: The default values of the options of the discipline.
Return type:: dict[str, Any]

Examples

>>> from gemseo import get_discipline_options_defaults
>>> get_discipline_options_defaults("Sellar1")

get_discipline_options_schema(discipline_name, output_json=False, pretty_print=False)[source]#

Return the schema of a discipline.

Parameters:

discipline_name (str) -- The name of the formulation.
output_json (bool) --
Whether to apply the JSON format to the schema.

By default it is set to False.
pretty_print (bool) --
Whether to print the schema in a tabular way.

By default it is set to False.

Returns:

The schema of the discipline.

Return type:

str | dict[str, Any]

Examples

>>> from gemseo import get_discipline_options_schema
>>> schema = get_discipline_options_schema("Sellar1", pretty_print=True)

get_discipline_outputs_schema(discipline, output_json=False, pretty_print=False)[source]#

Return the schema of the outputs of a discipline.

Parameters:

discipline (Discipline) -- The discipline.
output_json (bool) --
Whether to apply the JSON format to the schema.

By default it is set to False.
pretty_print (bool) --
Whether to print the schema in a tabular way.

By default it is set to False.

Returns:

The schema of the outputs of the discipline.

Return type:

str | dict[str, Any]

Examples

>>> from gemseo import get_discipline_outputs_schema, create_discipline
>>> discipline = create_discipline("Sellar1")
>>> get_discipline_outputs_schema(discipline, pretty_print=True)

get_formulation_options_schema(formulation_name, output_json=False, pretty_print=False)[source]#

Return the schema of the options of a formulation.

Parameters:

formulation_name (str) -- The name of the formulation.
output_json (bool) --
Whether to apply the JSON format to the schema.

By default it is set to False.
pretty_print (bool) --
Whether to print the schema in a tabular way.

By default it is set to False.

Returns:

The schema of the options of the formulation.

Return type:

str | dict[str, Any]

Examples

>>> from gemseo import get_formulation_options_schema
>>> schema = get_formulation_options_schema("MDF", pretty_print=True)

get_formulation_sub_options_schema(formulation_name, output_json=False, pretty_print=False, **formulation_settings)[source]#

Return the schema of the sub-options of a formulation.

Parameters:

formulation_name (str) -- The name of the formulation.
output_json (bool) --
Whether to apply the JSON format to the schema.

By default it is set to False.
pretty_print (bool) --
Whether to print the schema in a tabular way.

By default it is set to False.
**formulation_settings (Any) -- The settings of the formulation required for its instantiation.

Returns:

The schema of the sub-options of the formulation, if any.

Return type:

str | dict[str, Any]

Examples

>>> from gemseo import get_formulation_sub_options_schema
>>> schema = get_formulation_sub_options_schema('MDF',
>>>                                             main_mda_name='MDAJacobi',
>>>                                             pretty_print=True)

get_formulations_options_defaults(formulation_name)[source]#

Return the default values of the options of a formulation.

Parameters:: formulation_name (str) -- The name of the formulation.
Returns:: The default values of the options of the formulation.
Return type:: dict[str, Any]

Examples

>>> from gemseo import get_formulations_options_defaults
>>> get_formulations_options_defaults("MDF")
{'main_mda_name': 'MDAChain',
 'maximize_objective': False,
 'inner_mda_name': 'MDAJacobi'}

get_formulations_sub_options_defaults(formulation_name, **formulation_settings)[source]#

Return the default values of the sub-options of a formulation.

Parameters:

formulation_name (str) -- The name of the formulation.
**formulation_settings (Any) -- The settings of the formulation required for its instantiation.

Returns:

The default values of the sub-options of the formulation.

Return type:

dict[str, Any]

Examples

>>> from gemseo import get_formulations_sub_options_defaults
>>> get_formulations_sub_options_defaults('MDF',
>>>                                       main_mda_name='MDAJacobi')

get_mda_options_schema(mda_name, output_json=False, pretty_print=False)[source]#

Return the schema of the options of a multidisciplinary analysis (MDA).

Parameters:

mda_name (str) -- The name of the MDA.
output_json (bool) --
Whether to apply the JSON format to the schema.

By default it is set to False.
pretty_print (bool) --
Whether to print the schema in a tabular way.

By default it is set to False.

Returns:

The schema of the options of the MDA.

Return type:

str | dict[str, Any]

Examples

>>> from gemseo import get_mda_options_schema
>>> get_mda_options_schema("MDAJacobi")

get_post_processing_options_schema(post_proc_name, output_json=False, pretty_print=False)[source]#

Return the schema of the options of a post-processing.

Parameters:

post_proc_name (str) -- The name of the post-processing.
output_json (bool) --
Whether to apply the JSON format to the schema.

By default it is set to False.
pretty_print (bool) --
Whether to print the schema in a tabular way.

By default it is set to False.

Returns:

The schema of the options of the post-processing.

Return type:

str | dict[str, Any]

Examples

>>> from gemseo import get_post_processing_options_schema
>>> schema = get_post_processing_options_schema('OptHistoryView',
>>>                                             pretty_print=True)

get_scenario_differentiation_modes()[source]#

Return the names of the available differentiation modes of a scenario.

Returns:: The names of the available differentiation modes of a scenario.
Return type:: tuple[OptimizationProblem.DifferentiationMethod]

Examples

>>> from gemseo import get_scenario_differentiation_modes
>>> get_scenario_differentiation_modes()

get_scenario_inputs_schema(scenario, output_json=False, pretty_print=False)[source]#

Return the schema of the inputs of a scenario.

Parameters:

scenario (BaseScenario) -- The scenario.
output_json (bool) --
Whether to apply the JSON format to the schema.

By default it is set to False.
pretty_print (bool) --
Whether to print the schema in a tabular way.

By default it is set to False.

Returns:

The schema of the inputs of the scenario.

Return type:

str | dict[str, Any]

Examples

>>> from gemseo import create_discipline, create_scenario,
get_scenario_inputs_schema
>>> from gemseo.problems.mdo.sellar.sellar_design_space import (
...     SellarDesignSpace,
... )
>>> design_space = SellarDesignSpace()
>>> disciplines = create_discipline(["Sellar1", "Sellar2", "SellarSystem"])
>>> scenario = create_scenario(
...     disciplines,
...     "obj",
...     design_space,
...     formulation_name="MDF",
...     scenario_type="MDO",
... )
>>> get_scenario_inputs_schema(scenario)

get_scenario_options_schema(scenario_type, output_json=False, pretty_print=False)[source]#

Return the schema of the options of a scenario.

Parameters:

scenario_type (str) -- The type of the scenario.
output_json (bool) --
Whether to apply the JSON format to the schema.

By default it is set to False.
pretty_print (bool) --
Whether to print the schema in a tabular way.

By default it is set to False.

Returns:

The schema of the options of the scenario.

Return type:

str | dict[str, Any]

Examples

>>> from gemseo import get_scenario_options_schema
>>> get_scenario_options_schema("MDO")

get_surrogate_options_schema(surrogate_name, output_json=False, pretty_print=False)[source]#

Return the available options for a surrogate discipline.

Parameters:

surrogate_name (str) -- The name of the surrogate discipline.
output_json (bool) --
Whether to apply the JSON format to the schema.

By default it is set to False.
pretty_print (bool) --
Whether to print the schema in a tabular way.

By default it is set to False.

Returns:

The schema of the options of the surrogate discipline.

Return type:

str | dict[str, Any]

Examples

>>> from gemseo import get_surrogate_options_schema
>>> tmp = get_surrogate_options_schema('LinRegSurrogateDiscipline',
>>>                                    pretty_print=True)

import_database(file_path, hdf_node_path='')[source]#

Load a database from an HDF file path.

This file could be generated using Database.to_hdf(), OptimizationProblem.to_hdf() or Scenario.save_optimization_history().

Parameters:

file_path (str | Path) -- The path of the HDF file.
hdf_node_path (str) --
The path of the HDF node from which the database should be exported. If empty, the root node is considered.

By default it is set to "".

Returns:

The database.

Return type:

Database

import_discipline(file_path, cls=None)[source]#

Import a discipline from a pickle file.

Parameters:

file_path (str | Path) -- The path to the file containing the discipline saved with the method Discipline.to_pickle().
cls (type[Discipline] | None) -- A class of discipline. If None, use Discipline.

Returns:

The discipline.

Return type:

Discipline

monitor_scenario(scenario, observer)[source]#

Add an observer to a scenario.

The observer must have an update method that handles the execution status change of an atom. update(atom) is called everytime an atom execution changes.

Parameters:

scenario (BaseScenario) -- The scenario to monitor.
observer -- The observer that handles an update of status.

Return type:

None

print_configuration()[source]#

Print the current configuration.

The log message contains the successfully loaded modules and failed imports with the reason.

Examples

>>> from gemseo import print_configuration
>>> print_configuration()

Return type:: None

read_design_space(file_path, header=())[source]#

Read a design space from a CSV or HDF file.

In the case of a CSV file, the following columns must be in the file: "name", "lower_bound" and "upper_bound". This file shall contain space-separated values (the number of spaces is not important) with a row for each variable and at least the bounds of the variable.

Parameters:

file_path (str | Path) -- The path to the file.
header (Iterable[str]) --
The names of the fields saved in the CSV file. If empty, read them in the first row of the CSV file.

By default it is set to ().

Returns:

The design space.

Return type:

DesignSpace

Examples

>>> from gemseo import (create_design_space, write_design_space,
>>>     read_design_space)
>>> original_design_space = create_design_space()
>>> original_design_space.add_variable(
...     "x", lower_bound=-1, value=0.0, upper_bound=1.0
... )
>>> write_design_space(original_design_space, "file.csv")
>>> design_space = read_design_space("file.csv")
>>> print(design_space)
Design Space:
+------+-------------+-------+-------------+-------+
| name | lower_bound | value | upper_bound | type  |
+------+-------------+-------+-------------+-------+
| x    |      -1     |   0   |      1      | float |
+------+-------------+-------+-------------+-------+

sample_disciplines(disciplines, input_space, output_names, formulation_name='MDF', formulation_settings=mappingproxy({}), name='Sampling', backup_settings=None, algo_settings_model=None, **algo_settings)[source]#

Sample a set of disciplines associated with an MDO formulation.

Parameters:

disciplines (Sequence[Discipline]) -- The disciplines to be sampled.
input_space (DesignSpace) -- The input space on which to sample the discipline.
output_names (str | Iterable[str]) -- The names of the outputs of interest.
n_samples -- The number of samples.
formulation_name (str) --
The name of the MDO formulation.

By default it is set to "MDF".
formulation_settings (StrKeyMapping) --
The settings of the MDO formulation. If empty, use the default ones.

By default it is set to {}.
name (str) --
The name of the returned dataset. If empty, use the name of the discipline.

By default it is set to "Sampling".
backup_settings (BackupSettings | None) -- The settings of the backup file to store the evaluations if any.
algo_settings_model (BaseDOESettings | None) -- The DOE settings as a Pydantic model. If None, use **settings.
**algo_settings (Any) -- The DOE settings. These arguments are ignored when settings_model is not None.

Returns:

The input-output samples of the disciplines.

Return type:

IODataset

wrap_discipline_in_job_scheduler(discipline, scheduler_name, workdir_path, **options)[source]#

Wrap the discipline within another one to delegate its execution to a job scheduler.

The discipline is serialized to the disk, its input too, then a job file is created from a template to execute it with the provided options. The submission command is launched, it will setup the environment, deserialize the discipline and its inputs, execute it and serialize the outputs. Finally, the deserialized outputs are returned by the wrapper.

All process classes MDOScenario, or BaseMDA, inherit from Discipline so can be sent to HPCs in this way.

The job scheduler template script can be provided directly or the predefined templates file names in gemseo.wrappers.job_schedulers.template can be used. SLURM and LSF templates are provided, but one can use other job schedulers or to customize the scheduler commands according to the user needs and infrastructure requirements.

The command to submit the job can also be overloaded.

Parameters:

discipline (Discipline) -- The discipline to wrap in the job scheduler.
scheduler_name (str) -- The name of the job scheduler (for instance LSF, SLURM, PBS).
workdir_path (Path) -- The path to the workdir
**options (Any) -- The submission options.

Raises:

OSError -- if the job template does not exist.

Return type:

JobSchedulerDisciplineWrapper

Warning

This method serializes the passed discipline so it has to be serializable. All disciplines provided in GEMSEO are serializable but it is possible that custom ones are not and this will make the submission proess fail.

Examples

This example execute a DOE of 100 points on an MDA, each MDA is executed on 24 CPUS using the SLURM wrapper, on a HPC, and at most 10 points run in parallel, everytime a point of the DOE is computed, another one is submitted to the queue.

>>> from gemseo.disciplines.wrappers.job_schedulers.factory import (
...     JobSchedulerDisciplineWrapperFactory,
... )
>>> from gemseo import create_discipline, create_scenario, create_mda
>>> from gemseo.problems.mdo.sellar.sellar_design_space import (
...     SellarDesignSpace,
... )
>>> disciplines = create_discipline(["Sellar1", "Sellar2", "SellarSystem"])
>>> mda = create_mda(disciplines)
>>> wrapped_mda= wrap_discipline_in_job_scheduler(mda, scheduler_name="SLURM",
>>>                                               workdir_path="workdir",
>>>                                               cpus_per_task=24)
>>> scn=create_scenario(
>>> ... mda, "obj", SellarDesignSpace(), formulation_name="DisciplinaryOpt", scenario_type="DOE"
>>> )
>>> scn.execute(algo_name="lhs", n_samples=100, n_processes=10)

In this variant, each discipline is wrapped independently in the job scheduler, which allows to parallelize more the process because each discipline will run on indpendent nodes, whithout being parallelized using MPI. The drawback is that each discipline execution will be queued on the HPC. A HDF5 cache is attached to the MDA, so all executions will be recorded. Each wrapped discipline can also be cached using a HDF cache.

>>> from gemseo.core.discipline import Discipline
>>> disciplines = create_discipline(["Sellar1", "Sellar2", "SellarSystem"])
>>> wrapped_discs=[wrap_discipline_in_job_scheduler(disc,
>>>                                                 workdir_path="workdir",
>>>                                                 cpus_per_task=24,
>>>                                                 scheduler_name="SLURM"),
>>>                for disc in disciplines]
>>> scn=create_scenario(
>>>     wrapped_discs, "obj", SellarDesignSpace(), formulation_name="MDF", scenario_type="DOE"
>>> )
>>> scn.formulation.mda.set_cache(
...     Discipline.HDF5_CACHE, hdf_file_path="mda_cache.h5"
... )
>>> scn.execute(algo_name="lhs", n_samples=100, n_processes=10)

write_design_space(design_space, output_file, fields=(), header_char='', **table_options)[source]#

Save a design space to a CSV or HDF file.

Parameters:

design_space (DesignSpace) -- The design space to be saved.
output_file (str | Path) -- The path to the file.
fields (Sequence[str]) --
The fields to be exported. If empty, export all fields.

By default it is set to ().
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 import create_design_space, write_design_space
>>> design_space = create_design_space()
>>> design_space.add_variable("x", lower_bound=-1, upper_bound=1, value=0.0)
>>> write_design_space(design_space, "file.csv")

Subpackages#

Submodules#

gemseo.typing module