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.
Note
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: dict[str, dict[str, ndarray]]
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: Mapping[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'
- 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, numpy.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, numpy.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:
- 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.
- 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: dict[str, dict[str, ndarray]]
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: Mapping[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.
Note
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 against which to differentiate the outputs.
If the discipline grammar type is
MDODiscipline.GrammarType.JSON
and an input is either a non-numeric array or not an array, it will be ignored. If an input is declared as an array but the type of its items is not defined, it is assumed as a numeric array.If the discipline grammar type is
MDODiscipline.GrammarType.SIMPLE
and an input is not an array, it will be ignored. Keep in mind that in this case the array subtype is not checked.- 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 the inputs wrt which differentiate the discipline are not inputs of the latter.
- Return type:
None
- add_differentiated_outputs(outputs=None)[source]
Add the outputs to be differentiated.
If the discipline grammar type is
MDODiscipline.GrammarType.JSON
and an output is either a non-numeric array or not an array, it will be ignored. If an output is declared as an array but the type of its items is not defined, it is assumed as a numeric array.If the discipline grammar type is
MDODiscipline.GrammarType.SIMPLE
and an output is not an array, it will be ignored. Keep in mind that in this case the array subtype is not checked.- Parameters:
outputs (Iterable[str] | None) – The output variables to be differentiated. If None, all the outputs of the discipline are used.
- Raises:
ValueError – When the outputs to differentiate are not discipline outputs.
- 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:
list[tuple[gemseo.core.discipline.MDODiscipline, gemseo.core.discipline.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:
- 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: dict[str, dict[str, ndarray]]
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: Mapping[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: dict[str, dict[str, ndarray]]
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: Mapping[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.