group.py

Define the Group class.

class openmdao.core.group.Group(**kwargs)

Bases: System

Class used to group systems together; instantiate or inherit.

Parameters:

**kwargsdict

Dict of arguments available here and in all descendants of this Group.

Attributes:

_mpi_proc_allocatorProcAllocator

Object used to allocate MPI processes to subsystems.

_proc_infodict of subsys_name: (min_procs, max_procs, weight, proc_group)

Information used to determine MPI process allocation to subsystems.

_subgroups_myproclist

List of local subgroups, (sorted by name if Problem option allow_post_setup_reorder is True).

_manual_connectionsdict

Dictionary of input_name: (output_name, src_indices) connections.

_group_inputsdict

Mapping of promoted names to certain metadata (src_indices, units).

_static_group_inputsdict

Group inputs added outside of setup/configure.

_pre_config_group_inputsdict

Group inputs added inside of setup but before configure.

_static_manual_connectionsdict

Dictionary that stores all explicit connections added outside of setup.

_conn_graphAllConnGraph

Connection graph instance used to store the connection graph.

_conn_abs_in2out{‘abs_in’: ‘abs_out’}

Dictionary containing all explicit & implicit continuous var connections owned by this system only. The data is the same across all processors.

_conn_discrete_in2out{‘abs_in’: ‘abs_out’}

Dictionary containing all explicit & implicit discrete var connections owned by this system only. The data is the same across all processors.

_transfersdict of dict of Transfers

First key is mode, second is subname where mode is ‘fwd’ or ‘rev’ and subname is the subsystem name or subname can be None for the full, simultaneous transfer.

_discrete_transfersdict of discrete transfer metadata

Key is system pathname or None for the full, simultaneous transfer.

_setup_procs_finishedbool

Flag to check if setup_procs is complete

_contains_parallel_groupbool

If True, this Group contains a ParallelGroup. Only used to determine if a parallel group or distributed component is below a DirectSolver so that we can raise an exception.

_order_setbool

Flag to check if set_order has been called.

_shapes_graphnx.Graph

Dynamic shape dependency graph, or None.

_pre_componentsset of str or None

Set of pathnames of components that are executed prior to the optimization loop. Empty unless the ‘group_by_pre_opt_post’ option is True in the Problem.

_post_componentsset of str or None

Set of pathnames of components that are executed after the optimization loop. Empty unless the ‘group_by_pre_opt_post’ option is True in the Problem.

_iterated_componentsset of str or ContainsAll

Set of pathnames of components that are executed in the optimization loop if ‘group_by_pre_opt_post’ is True in the Problem.

_fd_rev_xfer_correction_distdict

If this group is using finite difference to compute derivatives, this is the set of inputs that are upstream of a distributed response within this group, keyed by active response. These determine if contributions from all ranks will be added together to get the correct input values when derivatives in the larger model are being solved using reverse mode.

_auto_ivc_recorderslist

List of recorders that were added to _auto_ivc before it existed so they can be added after _auto_ivc is created.

_is_explicitbool or None

True if neither this Group nor any of its descendants contains implicit systems or cycles.

_sys_graph_cachedict

Cache for the system graph.

_key_ownerdict

The owning rank keyed by absolute jacobian key.

Methods

abs_meta_iter(iotype[, local, cont, discrete])	Iterate over absolute variable names and their metadata for this System.
add_constraint(name[, lower, upper, equals, ...])	Add a constraint variable to this system.
add_design_var(name[, lower, upper, ref, ...])	Add a design variable to this system.
add_objective(name[, ref, ref0, index, ...])	Add a response variable to this system.
add_recorder(recorder[, recurse])	Add a recorder to the system.
add_response(name, type_[, lower, upper, ...])	Add a response variable to this system.
add_subsystem(name, subsys[, promotes, ...])	Add a subsystem.
approx_totals([method, step, form, step_calc])	Approximate derivatives for a Group using the specified approximation method.
best_partial_deriv_direction()	Return the best direction for partial deriv calculations based on input and output sizes.
check_config(logger)	Perform optional error checks.
cleanup()	Clean up resources prior to exit.
comm_info_iter()	Yield comm size for this system and all subsystems.
compute_sparsity([direction, num_iters, ...])	Compute the sparsity of the partial jacobian.
compute_sys_graph([comps_only, add_edge_info])	Compute a dependency graph for subsystems in this group.
configure()	Configure this group to assign children settings.
connect(src_name, tgt_name[, src_indices, ...])	Connect source src_name to target tgt_name in this namespace.
convert2units(name, val, units)	Convert the given value to the specified units.
convert_from_units(name, val, units)	Convert the given value from the specified units to those of the named variable.
convert_units(name, val, units_from, units_to)	Wrap the utility convert_units and give a good error message.
declare_coloring([wrt, method, form, step, ...])	Set options for deriv coloring of a set of wrt vars matching the given pattern(s).
dist_size_iter(io, top_comm)	Yield names and distributed ranges of all local and remote variables in this system.
get_coloring_fname(mode)	Return the full pathname to a coloring file.
get_conn_graph()	Return the model connection graph.
get_constraints([recurse, get_sizes, ...])	Get the Constraint settings from this system.
get_design_vars([recurse, get_sizes, ...])	Get the DesignVariable settings from this system.
get_indep_vars(local[, include_discrete])	Return a dict of independant variables contained in this group or any of its subgroups.
get_io_metadata([iotypes, metadata_keys, ...])	Retrieve metadata for a filtered list of variables.
get_linear_vectors()	Return the linear inputs, outputs, and residuals vectors.
get_nonlinear_vectors()	Return the inputs, outputs, and residuals vectors.
get_objectives([recurse, get_sizes, ...])	Get the Objective settings from this system.
get_outputs_dir(*subdirs[, mkdir])	Get the path under which all output files of this system are to be placed.
get_promotions([inprom, outprom])	Return all promotions for the given promoted variable(s).
get_reports_dir()	Get the path to the directory where the report files should go.
get_responses([recurse, get_sizes, use_prom_ivc])	Get the response variable settings from this system.
get_self_statics()	Override this in derived classes if compute_primal references static values.
get_source(name)	Return the source variable connected to the given named variable.
get_val(name[, units, indices, get_remote, ...])	Get an output/input/residual variable.
get_var_dup_info(name, io)	Return information about how the given variable is duplicated across MPI processes.
get_var_sizes(name, io)	Return the sizes of the given variable on all procs.
guess_nonlinear(inputs, outputs, residuals)	Provide initial guess for states.
has_vectors()	Check if the system vectors have been initialized.
initialize()	Perform any one-time initialization run at instantiation.
is_explicit([is_comp])	Return True if this Group contains only explicit systems and has no cycles.
list_inputs([val, prom_name, units, shape, ...])	Write a list of input names and other optional information to a specified stream.
list_options([include_default, ...])	Write a list of output names and other optional information to a specified stream.
list_outputs([explicit, implicit, val, ...])	Write a list of output names and other optional information to a specified stream.
list_vars([val, prom_name, residuals, ...])	Write a list of inputs and outputs sorted by component in execution order.
load_case(case)	Pull all input and output variables from a Case into this System.
load_model_options()	Load the relevant model options from Problem._metadata['model_options'].
promotes(subsys_name[, any, inputs, ...])	Promote a variable in the model tree.
record_iteration()	Record an iteration of the current System.
run_apply_linear(mode[, scope_out, scope_in])	Compute jac-vec product.
run_apply_nonlinear()	Compute residuals.
run_linearize([sub_do_ln, driver])	Compute jacobian / factorization.
run_solve_linear(mode)	Apply inverse jac product.
run_solve_nonlinear()	Compute outputs.
run_validation()	Run validate method on all systems below this system.
set_constraint_options(name[, ref, ref0, ...])	Set options for constraints in the model.
set_design_var_options(name[, lower, upper, ...])	Set options for design vars in the model.
set_initial_values()	Set all input and output variables to their declared initial values.
set_input_defaults(name[, val, units, src_shape])	Specify metadata to be assumed when multiple inputs are promoted to the same name.
set_objective_options(name[, ref, ref0, ...])	Set options for objectives in the model.
set_order(new_order)	Specify a new execution order for subsystems in this group.
set_output_solver_options(name[, lower, ...])	Set solver output options.
set_solver_print([level, depth, type_, ...])	Control printing for solvers and subsolvers in the model.
set_val(name, val[, units, indices])	Set an input or output variable.
setup()	Build this group.
sparsity_matches_fd([direction, outstream])	Compare the sparsity computed by this system vs.
subjac_sparsity_iter(sparsity[, wrt_matches])	Iterate over sparsity for each subjac in the jacobian.
system_iter([include_self, recurse, typ, ...])	Yield a generator of local subsystems of this system.
total_local_size(io)	Return the total local size of the given variable.
use_fixed_coloring([coloring, recurse])	Use a precomputed coloring for this System.
uses_approx()	Return True if the system uses approximations to compute derivatives.
validate(inputs, outputs[, discrete_inputs, ...])	Check any final input / output values after a run.

display_conn_graph
display_dataflow_graph

__init__(**kwargs)

Set the solvers to nonlinear and linear block Gauss–Seidel by default.

add_recorder(recorder, recurse=False)

Add a recorder to the system.

Parameters:

recorder<CaseRecorder>

A recorder instance.

recursebool

Flag indicating if the recorder should be added to all the subsystems.

add_subsystem(name, subsys, promotes=None, promotes_inputs=None, promotes_outputs=None, min_procs=1, max_procs=None, proc_weight=1.0, proc_group=None)

Add a subsystem.

Parameters:

namestr

Name of the subsystem being added.

subsys<System>

An instantiated, but not-yet-set up system object.

promotesiter of (str or tuple), optional

A list of variable names specifying which subsystem variables to ‘promote’ up to this group. If an entry is a tuple of the form (old_name, new_name), this will rename the variable in the parent group.

promotes_inputsiter of (str or tuple), optional

A list of input variable names specifying which subsystem input variables to ‘promote’ up to this group. If an entry is a tuple of the form (old_name, new_name), this will rename the variable in the parent group.

promotes_outputsiter of (str or tuple), optional

A list of output variable names specifying which subsystem output variables to ‘promote’ up to this group. If an entry is a tuple of the form (old_name, new_name), this will rename the variable in the parent group.

min_procsint

Minimum number of MPI processes usable by the subsystem. Defaults to 1.

max_procsint or None

Maximum number of MPI processes usable by the subsystem. A value of None (the default) indicates there is no maximum limit.

proc_weightfloat

Weight given to the subsystem when allocating available MPI processes to all subsystems. Default is 1.0.

proc_groupstr or None

Name of a processor group such that any system with that processor group name within the same parent group will be allocated on the same mpi process(es). If this is not None, then any other systems sharing the same proc_group must have identical values of min_procs, max_procs, and proc_weight or an exception will be raised.

Returns:

<System>

The subsystem that was passed in. This is returned to enable users to instantiate and add a subsystem at the same time, and get the reference back.

approx_totals(method='fd', step=None, form=None, step_calc=None)

Approximate derivatives for a Group using the specified approximation method.

Parameters:

methodstr

The type of approximation that should be used. Valid options include: ‘fd’: Finite Difference, ‘cs’: Complex Step.

stepfloat

Step size for approximation. Defaults to None, in which case, the approximation method provides its default value.

formstr

Form for finite difference, can be ‘forward’, ‘backward’, or ‘central’. Defaults to None, in which case, the approximation method provides its default value.

step_calcstr

Step type for computing the size of the finite difference step. It can be ‘abs’ for absolute, ‘rel_avg’ for a size relative to the absolute value of the vector input, or ‘rel_element’ for a size relative to each value in the vector input. In addition, it can be ‘rel_legacy’ for a size relative to the norm of the vector. For backwards compatibilty, it can be ‘rel’, which is now equivalent to ‘rel_avg’. Defaults to None, in which case the approximation method provides its default value.

compute_sys_graph(comps_only=False, add_edge_info=True)

Compute a dependency graph for subsystems in this group.

Variable connection information is stored in each edge of the system graph if comps_only is True and add_edge_info is True.

Parameters:

comps_onlybool (False)

If True, return a graph of all components within this group or any of its descendants. No sub-groups will be included. Otherwise, a graph containing only direct children (both Components and Groups) of this group will be returned.

add_edge_infobool (True)

If True and comps_only is also True, store variable connection information in each edge of the system graph.

Returns:

DiGraph

A directed graph containing names of subsystems and their connections.

configure()

Configure this group to assign children settings.

This method may optionally be overidden by your Group’s method.

You may only use this method to change settings on your children subsystems. This includes setting solvers in cases where you want to override the defaults.

You can assume that the full hierarchy below your level has been instantiated and has already called its own configure methods.

Available attributes:

name pathname comm options system hieararchy with attribute access

connect(src_name, tgt_name, src_indices=None, flat_src_indices=None)

Connect source src_name to target tgt_name in this namespace.

Parameters:

src_namestr

Name of the source variable to connect.

tgt_namestr or [str, … ] or (str, …)

Name of the target variable(s) to connect.

src_indicesint or list of ints or tuple of ints or int ndarray or Iterable or None

The global indices of the source variable to transfer data from. The shapes of the target and src_indices must match, and form of the entries within is determined by the value of ‘flat_src_indices’.

flat_src_indicesbool

If True, each entry of src_indices is assumed to be an index into the flattened source. Otherwise it must be a tuple or list of size equal to the number of dimensions of the source.

display_conn_graph(varname=None, outfile=None)

display_dataflow_graph(recurse=True, show_vars=True, show_boundary=False, exclude=(), outfile=None)

get_design_vars(recurse=True, get_sizes=True, use_prom_ivc=True)

Get the DesignVariable settings from this system.

Retrieve all design variable settings from the system and, if recurse is True, all of its subsystems.

Parameters:

recursebool

If True, recurse through the subsystems and return the path of all design vars relative to the this Group.

get_sizesbool, optional

If True, compute the size of each design variable.

use_prom_ivcbool

Use promoted names for inputs, else convert to absolute source names.

Returns:

dict

The design variables defined in the current system and, if recurse=True, its subsystems.

get_indep_vars(local, include_discrete=False)

Return a dict of independant variables contained in this group or any of its subgroups.

Parameters:

localbool

If True, return only the variables local to the current process.

include_discretebool

If True, include discrete variables in the returned dict.

Returns:

dict

Dict of all independant variables in this group and their corresponding metadata.

get_responses(recurse=True, get_sizes=True, use_prom_ivc=False)

Get the response variable settings from this system.

Retrieve all response variable settings from the system as a dict, keyed by either absolute variable name, promoted name, or alias name, depending on the value of use_prom_ivc and whether the original key was a promoted output, promoted input, or an alias.

Parameters:

recursebool, optional

If True, recurse through the subsystems and return the path of all responses relative to the this system.

get_sizesbool, optional

If True, compute the size of each response.

use_prom_ivcbool

Translate ivc names to their promoted input names.

Returns:

dict

The responses defined in the current system and, if recurse=True, its subsystems.

guess_nonlinear(inputs, outputs, residuals, discrete_inputs=None, discrete_outputs=None)

Provide initial guess for states.

Override this method to set the initial guess for states.

Parameters:

inputsVector

Unscaled, dimensional input variables read via inputs[key].

outputsVector

Unscaled, dimensional output variables read via outputs[key].

residualsVector

Unscaled, dimensional residuals written to via residuals[key].

discrete_inputsdict or None

If not None, dict containing discrete input values.

discrete_outputsdict or None

If not None, dict containing discrete output values.

is_explicit(is_comp=True)

Return True if this Group contains only explicit systems and has no cycles.

Parameters:

is_compbool

If True, return True if this is an explicit component. If False, return True if this is an explicit component or group.

Returns:

bool

True if this is an explicit component.

property model_options

Get the model options from self._problem_meta.

The user may change the contents of model_options to impact values sent to subsystems of this Group.

Returns:

dict

The model options metadata provided by the associated Problem object.

promotes(subsys_name, any=None, inputs=None, outputs=None, src_indices=None, flat_src_indices=None, src_shape=None)

Promote a variable in the model tree.

Parameters:

subsys_namestr

The name of the child subsystem whose inputs/outputs are being promoted.

anySequence of str or tuple

A Sequence of variable names (or tuples) to be promoted, regardless of if they are inputs or outputs. This is equivalent to the items passed via the promotes= argument to add_subsystem. If given as a tuple, we use the “promote as” standard of “(‘real name’, ‘promoted name’)*[]:”.

inputsSequence of str or tuple

A Sequence of input names (or tuples) to be promoted. Tuples are used for the “promote as” capability.

outputsSequence of str or tuple

A Sequence of output names (or tuples) to be promoted. Tuples are used for the “promote as” capability.

src_indicesint or list of ints or tuple of ints or int ndarray or Iterable or None

This argument applies only to promoted inputs. The global indices of the source variable to transfer data from. A value of None implies this input depends on all entries of source. Default is None. The shapes of the target and src_indices must match, and form of the entries within is determined by the value of ‘flat_src_indices’.

flat_src_indicesbool

This argument applies only to promoted inputs. If True, each entry of src_indices is assumed to be an index into the flattened source. Otherwise each entry must be a tuple or list of size equal to the number of dimensions of the source.

src_shapeint or tuple

Assumed shape of any connected source or higher level promoted input.

run_linearize(sub_do_ln=True, driver=None)

Compute jacobian / factorization.

This calls _linearize, but with the model assumed to be in an unscaled state.

Parameters:

sub_do_lnbool

Flag indicating if the children should call linearize on their linear solvers.

driverDriver or None

If this system is the top level system and approx derivatives have not been initialized, the driver for this model must be supplied in order to properly initialize the approximations.

set_initial_values()

Set all input and output variables to their declared initial values.

This should only be called on the top level group.

set_input_defaults(name, val=UNDEFINED, units=None, src_shape=None)

Specify metadata to be assumed when multiple inputs are promoted to the same name.

Parameters:

namestr

Promoted input name.

valobject

Value to assume for the promoted input.

unitsstr or None

Units to assume for the promoted input.

src_shapeint or tuple

Assumed shape of any connected source or higher level promoted input.

set_order(new_order)

Specify a new execution order for subsystems in this group.

Parameters:

new_orderlist of str

List of system names in desired new execution order.

setup()

Build this group.

This method should be overidden by your Group’s method. The reason for using this method to add subsystem is to save memory and setup time when using your Group while running under MPI. This avoids the creation of systems that will not be used in the current process.

You may call ‘add_subsystem’ to add systems to this group. You may also issue connections, and set the linear and nonlinear solvers for this group level. You cannot safely change anything on children systems; use the ‘configure’ method instead.

Available attributes:

name pathname comm options

openmdao.core.group.iter_solver_info(system)

Return solver information for this System.

Parameters:

systemSystem

Return solver information for this System.

Returns:

str

System pathname.

str

Class name.

list of sets of str

Strongly connected components in this Group’s subsystem graph. If not a Group, this will be an empty list.

str

Linear solver class name.

str

Nonlinear solver class name.

int

Linear solver max iterations.

int

Nonlinear solver max iterations.

int

Number of subsystems that are not part of any strongly connected component. If this number is greater than 0 and strongly connected components exist in this group, it indicates that this group contains subcycles and that it may be more efficient to separate those subcyles into their own groups and apply iterative solvers to them.

bool

True if this is a Group, False if it is an ImplicitComponent.

bool

True if the linear solver found for this System can solve a cycle or implicit component.

bool

True if the nonlinear solver found for this System can solve a cycle or implicit component.