# GEMSEO Study Analysis¶

## Objective and scope¶

This section describes how to use StudyAnalysis. The idea is to help the users to define the right MDO problem to be solved, even before wrapping any software. The result of the study are a N2 (or DSM) and XDSM diagrams (see more explanations here XDSM), with a defined MDO problems including:

• The list of disciplines, with their inputs and outputs

• The design variables

• The constraints

• The objective function(s)

No executable code is produced, the idea is to assist the discussions with design and field experts, customers, to define the MDO problem, from the white sheet. This way, the study may be visualized before any process or tool being actually ready.

There is no need to write any line of code to use this tool. A command line executable is available.

Warning

GEMSEO study analysis only works under Python 3.7 and higher versions.

## Examples¶

The next figure illustrates how this tool can be used to create an MDO study analysis. This requires the creation of an excel workbook with one sheet per discipline. The name of the discipline is given by the name of the sheet. On each of these sheets, the inputs and outputs of the discipline must be given.

Scenarios are defined by sheet names starting with “Scenario”.

The N2 and XDSM diagrams can be generated from such as study file. The N2 diagrams are generated as pdf files. The XDSM diagrams are generated as standalone HTML files, by default, or as Latex and pdf files as an option (-l).

Multi level formulations can be also used. You need to define multiple scenarios, and add the name of the scenarios in the disciplines list. Use an MDO formulation that is distributed (BiLevel for instance).

## Class documentation¶

class gemseo.utils.study_analysis.StudyAnalysis(xls_study_path)[source]

A MDO study analysis from an Excel specification.

Generate a N2 (equivalent to the Design Structure Matrix) diagram, showing the couplings between the disciplines, and a XDSM (Extended Design Structure Matrix), showing the MDO process, from an Excel specification of the inputs, outputs, design variables, objectives and constraints.

The input Excel files contains one sheet per discipline. The name of the sheet shall have the discipline name. The sheet shall have at least two columns, one for inputs and one for outputs, with the following format:

Disc1

Inputs

Outputs

in1

out1

in2

out2

Empty lines are ignored.

The scenarios (at least one, or multiple for distributed formulations) must appear in a Excel sheet name starting by “Scenario”.

The sheet shall have the following columns, with some constraints :

• All of them are mandatory, even if empty for the constraints.

• The order does not matter.

• One and only one formulation must be declared.

• At least one objective must be provided, and one design variable.

Scenario1

Design variables

Objective function

Constraints

Disciplines

Formulation

Options

Options values

in1

out1

out2

Disc1

MDF

tolerance

0.1

Disc2

main_mda_name

MDAJacobi

All the objective functions and constraints must be outputs of a discipline, not necessarily the one of the current sheet. All the design variables must be inputs of a discipline, not necessarily the one of the current sheet.

The columns ‘Options’ and ‘Options values’ are used to pass the formulation options. Note that for string type ‘Option values’, the value can be written with or without the “” characters.

To use multi level MDO formulations, create multiple scenarios, and add the name of the sub scenarios in the list of disciplines of the main (system) scenario.

An arbitrary number of levels can be generated this way (three, four levels etc formulations).

Initialize the study from the Excel specification.

Parameters:

xls_study_path (str) – The path to the Excel file describing the study.

generate_n2(file_path='n2.pdf', show_data_names=True, save=True, show=False, fig_size=(15, 10))[source]

Generate a N2 plot for the disciplines list.

Parameters:
• file_path (str) –

The file path of the figure.

By default it is set to n2.pdf.

• show_data_names (bool) –

If true, the names of the coupling data is shown; otherwise, circles are drawn, which size depends on the number of coupling names.

By default it is set to True.

• save (bool) –

If True, save the figure to file_path.

By default it is set to True.

• show (bool) –

If True, show the plot.

By default it is set to False.

• fig_size (tuple[float, float]) –

The size of the figure.

By default it is set to (15, 10).

Return type:

None

generate_xdsm(output_dir, latex_output=False, open_browser=False)[source]

Create an xdsm.json file from the current scenario.

Parameters:
• output_dir (str) – The directory where the XDSM html files are generated.

• latex_output (bool) –

If True, build the .tex, .tikz and .pdf files.

By default it is set to False.

• open_browser (bool) –

If True, open in a web browser.

By default it is set to False.

Returns:

The MDOScenario that contains the DesignSpace, the formulation, but the disciplines have only correct input and output grammars but no _run methods so that can’t be executed

Return type:

gemseo.core.mdo_scenario.MDOScenario

disciplines: dict[str, MDODiscipline]

The disciplines.

disciplines_descr: dict[str, MDODiscipline]

The descriptions of the disciplines (including sub-scenario) parsed in the Excel file.

scenarios: dict[str, MDOScenario]

The scenarios.

scenarios_descr: dict[str, dict[str, str | list[str]]]

The descriptions of the scenarios parsed in the Excel file.

study: XLSStudyParser

The XLSStudyParser instance built from the Excel file.

xls_study_path: str

The path of the Excel file.

## Usage of the command line executable¶

GEMSEO installation provides the gemseo-study command line executable, its usage is:

gemseo-study [-h] [-o OUT_DIR] [-x] [-l] [-s FIG_SIZE] study_file

A tool to generate an N2 chart and an XDSM diagram from an Excel description file.

positional arguments:

study_file XLS file that describes the study

optional arguments:
-h, --help

show this help message and exit

-o OUT_DIR, --out_dir OUT_DIR

Output directory for the generated files

-x, --xdsm

If True, generates the XDSM file

-l, --latex_output

If True, generates the XDSM in PDF and Latex

-s FIG_SIZE, --fig_size FIG_SIZE

Size of the N2 figure, tuple (x,y)