gemseo / core

coupling_structure module

Graph-based analysis of the weak and strong couplings between several disciplines.

class gemseo.core.coupling_structure.MDOCouplingStructure(disciplines)[source]

Bases: object

Structure of the couplings between several disciplines.

The methods of this class include the computation of weak, strong or all couplings.

Parameters:

disciplines (Sequence[MDODiscipline]) – The disciplines that possibly exchange coupling variables.

find_discipline(output)[source]

Find which discipline produces a given output.

Parameters:

output (str) – The name of an output.

Returns:

The discipline producing this output, if it exists.

Raises:
  • TypeError – If the name of the output is not a string.

  • ValueError – If the output is not an output of the discipline.

Return type:

MDODiscipline

get_input_couplings(discipline, strong=True)[source]

Compute all the input coupling variables of a discipline.

Parameters:
  • discipline (MDODiscipline) – The discipline.

  • strong (bool) –

    If True, consider the strong couplings. Otherwise, the weak ones.

    By default it is set to True.

Returns:

The names of the input coupling variables.

Return type:

list[str]

get_output_couplings(discipline, strong=True)[source]

Compute the output coupling variables of a discipline, either strong or weak.

Parameters:
  • discipline (MDODiscipline) – The discipline.

  • strong (bool) –

    If True, consider the strong couplings. Otherwise, the weak ones.

    By default it is set to True.

Returns:

The names of the output coupling variables.

Return type:

list[str]

get_strongly_coupled_disciplines(add_self_coupled=True, by_group=False)[source]

Determines the strongly coupled disciplines, that is the disciplines that occur in (possibly different) MDAs.

Parameters:
  • add_self_coupled (bool) –

    if True, adds the disciplines that are self-coupled to the list of strongly coupled disciplines

    By default it is set to True.

  • by_group (bool) –

    if True, returns a list of list of strongly coupled disciplines where the sublist contains the groups of disciplines that are strongly coupled together. if False, returns a single list

    By default it is set to False.

Returns:

The coupled disciplines list or list of list

Return type:

list[MDODiscipline] | list[list[MDODiscipline]]

static is_self_coupled(discipline)[source]

Test if the discipline is self-coupled.

Self-coupling means that one of its outputs is also an input.

Parameters:

discipline (MDODiscipline) – The discipline.

Returns:

Whether the discipline is self-coupled.

Return type:

bool

plot_n2_chart(file_path='n2.pdf', show_data_names=True, save=True, show=False, fig_size=(15.0, 10.0), open_browser=False)[source]

Generate a dynamic N2 chart for the disciplines, and possibly a static one.

A static N2 chart is a figure generated with the matplotlib library that can be saved to file_path, displayed on screen or both; the extension of file_path must be recognized by matplotlib.

A dynamic N2 chart is an HTML file with interactive features such as reordering the disciplines, expanding or collapsing the groups of strongly coupled disciplines and displaying information on disciplines or couplings.

The disciplines are located on the diagonal of the chart 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 chart, a blue diagonal block represent a self-coupled discipline, i.e. a discipline having some of its outputs as inputs.

Parameters:
  • 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 display the static N2 chart on screen.

    By default it is set to False.

  • fig_size (tuple[float, float]) –

    The width and height of the static N2 chart in inches.

    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.

Raises:

ValueError – When there is less than two disciplines.

Return type:

None

property all_couplings: list[str]

The inputs of disciplines that are also ouputs of other disciplines.

disciplines: Sequence[MDODiscipline]

The disciplines.

graph: DependencyGraph

The directed graph of the disciplines.

sequence: list[list[tuple[gemseo.core.discipline.MDODiscipline]]]

The sequence of execution of the disciplines.

property strong_couplings: list[str]

The outputs of the strongly coupled disciplines that are also inputs of a strongly coupled discipline.

property strongly_coupled_disciplines: list[gemseo.core.discipline.MDODiscipline]

The disciplines that are strongly coupled, ie that lie in cycles in the coupling graphs.

property weak_couplings: list[str]

The outputs of the weakly coupled disciplines.

property weakly_coupled_disciplines: list[gemseo.core.discipline.MDODiscipline]

The disciplines that do not appear in cycles in the coupling graph.