gemseo / core

chain module¶

Chains of disciplines.

Can be both sequential or parallel execution processes.

class gemseo.core.chain.MDOAdditiveChain(disciplines, outputs_to_sum, name=None, grammar_type=GrammarType.JSON, use_threading=True, n_processes=None)[source]

Bases: MDOParallelChain

Execute disciplines in parallel and sum specified outputs across disciplines.

Initialize self. See help(type(self)) for accurate signature.

Parameters:

disciplines (Sequence[MDODiscipline]) – The disciplines.
outputs_to_sum (Iterable[str]) – The names of the outputs to sum.
name (str | None) – The name of the discipline. If None, use the class name.
grammar_type (MDODiscipline.GrammarType) –
The type of the input and output grammars.

By default it is set to “JSONGrammar”.
use_threading (bool) –
Whether to use threads instead of processes to parallelize the execution; multiprocessing will copy (serialize) all the disciplines, while threading will share all the memory. This is important to note if you want to execute the same discipline multiple times, you shall use multiprocessing.

By default it is set to True.
n_processes (int | None) – The maximum simultaneous number of threads, if use_threading is True, or processes otherwise, used to parallelize the execution. If None, uses the number of disciplines.

Notes

The actual number of processes could be lower than n_processes if there are less than n_processes disciplines. n_processes can be lower than the total number of CPUs on the machine. Each discipline may itself run on several CPUs.

cache: AbstractCache | None: The cache containing one or several executions of the discipline according to the cache policy.

data_processor: DataProcessor: A tool to pre- and post-process discipline data.

exec_for_lin: bool: Whether the last execution was due to a linearization.

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.

class gemseo.core.chain.MDOChain(disciplines, name=None, grammar_type=GrammarType.JSON)[source]

Bases: MDODiscipline

Chain of disciplines that is based on a predefined order of execution.

Initialize self. See help(type(self)) for accurate signature.

Parameters:

disciplines (Sequence[MDODiscipline]) – The disciplines.
name (str | None) – The name of the discipline. If None, use the class name.
grammar_type (MDODiscipline.GrammarType) –
The type of the input and output grammars.

By default it is set to “JSONGrammar”.

class LinearizationMode(value)

Bases: StrEnum

An enumeration.

AUTO = 'auto'

CENTERED_DIFFERENCES = 'centered_differences'

COMPLEX_STEP = 'complex_step'

FINITE_DIFFERENCES = 'finite_differences'

REVERSE = 'reverse'

static copy_jacs(jacobian)[source]

Deepcopy a Jacobian dictionary.

Parameters:: jacobian (dict[str, dict[str, ndarray]]) – The Jacobian dictionary, which is a nested dictionary as {'out': {'in': derivatives}}.
Returns:: The deepcopy of the Jacobian dictionary.
Return type:: dict[str, dict[str, ndarray]]

get_disciplines_in_dataflow_chain()[source]

Return the disciplines that must be shown as blocks in the XDSM.

By default, only the discipline itself is shown. This function can be differently implemented for any type of inherited discipline.

Returns:: The disciplines shown in the XDSM chain.
Return type:: list[MDODiscipline]

get_expected_dataflow()[source]

Return the expected data exchange sequence.

This method is used for the XDSM representation.

The default expected data exchange sequence is an empty list.

See also

MDOFormulation.get_expected_dataflow

Returns:: The data exchange arcs.
Return type:: None

get_expected_workflow()[source]

Return the expected execution sequence.

This method is used for the XDSM representation.

The default expected execution sequence is the execution of the discipline itself.

See also

MDOFormulation.get_expected_workflow

Returns:: The expected execution sequence.
Return type:: None

initialize_grammars()[source]

Define the input and output grammars from the disciplines’ ones.

Return type:: None

reset_statuses_for_run()[source]

Set all the statuses to MDODiscipline.ExecutionStatus.PENDING.

Raises:: ValueError – When the discipline cannot be run because of its status.
Return type:: None

reverse_chain_rule(chain_outputs, discipline)[source]

Chain the derivatives with a new discipline in the chain in reverse mode.

Perform chain ruling: (notation: D is total derivative, d is partial derivative)

D out d out dinpt_1 d output dinpt_2 —– = ——– . ——- + ——– . ——– D new_in d inpt_1 d new_in d inpt_2 d new_in

D out d out d out dinpt_2 —– = ——– + ——– . ——– D z d z d inpt_2 d z

D out d out [dinpt_1 d out d inpt_1 dinpt_2 ] —– = ——– . [——- + ——– . ——– . ——–] D z d inpt_1 [d z d inpt_1 d inpt_2 d z ]

Parameters:

discipline (MDODiscipline) – The new discipline to compose in the chain.
chain_outputs (Iterable[str]) – The outputs to lineariza.

Return type:

None

set_disciplines_statuses(status)[source]

Set the sub-disciplines statuses.

Parameters:: status (str) – The status to be set.
Return type:: None

cache: AbstractCache | None: The cache containing one or several executions of the discipline according to the cache policy.

data_processor: DataProcessor: A tool to pre- and post-process discipline data.

exec_for_lin: bool: Whether the last execution was due to a linearization.

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.

class gemseo.core.chain.MDOParallelChain(disciplines, name=None, grammar_type=GrammarType.JSON, use_threading=True, n_processes=None, use_deep_copy=False)[source]

Bases: MDODiscipline

Chain of processes that executes disciplines in parallel.

Initialize self. See help(type(self)) for accurate signature.

Parameters:

disciplines (Sequence[MDODiscipline]) – The disciplines.
name (str | None) – The name of the discipline. If None, use the class name.
grammar_type (MDODiscipline.GrammarType) –
The type of the input and output grammars.

By default it is set to “JSONGrammar”.
use_threading (bool) –
Whether to use threads instead of processes to parallelize the execution; multiprocessing will copy (serialize) all the disciplines, while threading will share all the memory. This is important to note if you want to execute the same discipline multiple times, you shall use multiprocessing.

By default it is set to True.
n_processes (int | None) – The maximum simultaneous number of threads, if use_threading is True, or processes otherwise, used to parallelize the execution. If None, uses the number of disciplines.
use_deep_copy (bool) –
Whether to deepcopy the discipline input data.

By default it is set to False.

Notes

add_differentiated_inputs(inputs=None)[source]

Add the inputs for differentiation.

The inputs that do not represent continuous numbers are filtered out.

Parameters:: inputs (Iterable[str] | None) – The input variables against which to differentiate the outputs. If None, all the inputs of the discipline are used.
Raises:: ValueError – When ``inputs `` are not in the input grammar.
Return type:: None

add_differentiated_outputs(outputs=None)[source]

Add the outputs for differentiation.

The outputs that do not represent continuous numbers are filtered out.

Parameters:: outputs (Iterable[str] | None) – The output variables to be differentiated. If None, all the outputs of the discipline are used.
Raises:: ValueError – When ``outputs `` are not in the output grammar.
Return type:: None

get_disciplines_in_dataflow_chain()[source]

Return the disciplines that must be shown as blocks in the XDSM.

By default, only the discipline itself is shown. This function can be differently implemented for any type of inherited discipline.

Returns:: The disciplines shown in the XDSM chain.
Return type:: list[MDODiscipline]

get_expected_dataflow()[source]

Return the expected data exchange sequence.

This method is used for the XDSM representation.

The default expected data exchange sequence is an empty list.

See also

MDOFormulation.get_expected_dataflow

Returns:: The data exchange arcs.
Return type:: list[tuple[MDODiscipline, MDODiscipline, list[str]]]

get_expected_workflow()[source]

Return the expected execution sequence.

This method is used for the XDSM representation.

The default expected execution sequence is the execution of the discipline itself.

See also

MDOFormulation.get_expected_workflow

Returns:: The expected execution sequence.
Return type:: SerialExecSequence

initialize_grammars()[source]

Define the input and output grammars from the disciplines’ ones.

Return type:: None

reset_statuses_for_run()[source]

Set all the statuses to MDODiscipline.ExecutionStatus.PENDING.

Raises:: ValueError – When the discipline cannot be run because of its status.
Return type:: None

cache: AbstractCache | None: The cache containing one or several executions of the discipline according to the cache policy.

data_processor: DataProcessor: A tool to pre- and post-process discipline data.

exec_for_lin: bool: Whether the last execution was due to a linearization.

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.

class gemseo.core.chain.MDOWarmStartedChain(disciplines, variable_names_to_warm_start, name=None, grammar_type=GrammarType.JSON)[source]

Bases: MDOChain

Chain capable of warm starting a given list of variables.

The values of the variables to warm start are stored after each run and used to initialize the next one.

This Chain cannot be linearized.

Initialize self. See help(type(self)) for accurate signature.

Parameters:

disciplines (Sequence[MDODiscipline]) – The disciplines.
variable_names_to_warm_start (Sequence[str]) – The names of the variables to be warm started. These names must be outputs of the disciplines in the chain. If the list is empty, no variables are warm started.
name (str | None) – The name of the discipline. If None, use the class name.
grammar_type (MDODiscipline.GrammarType) –
The type of the input and output grammars.

By default it is set to “JSONGrammar”.

Raises:

ValueError – If the variable names to warm start are not outputs of the chain.

cache: AbstractCache | None: The cache containing one or several executions of the discipline according to the cache policy.

data_processor: DataProcessor: A tool to pre- and post-process discipline data.

exec_for_lin: bool: Whether the last execution was due to a linearization.

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.