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. IfNone
, uses the number of disciplines.
Notes
The actual number of processes could be lower than
n_processes
if there are less thann_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.
- 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:
- 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. IfNone
, uses the number of disciplines.use_deep_copy (bool) –
Whether to deepcopy the discipline input data.
By default it is set to False.
Notes
The actual number of processes could be lower than
n_processes
if there are less thann_processes
disciplines.n_processes
can be lower than the total number of CPUs on the machine. Each discipline may itself run on several CPUs.- 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:
- 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:
- 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:
- 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.