# system.py

# system.py¶

Define the base System class.

class`openmdao.core.system.`

`System`

(num_par_fd=1,**kwargs)[source]Bases:

`object`

Base class for all systems in OpenMDAO.

Never instantiated; subclassed by <Group> or <Component>. All subclasses have their attributes defined here.

- In attribute names:
abs / abs_name: absolute, unpromoted variable name, seen from root (unique). rel / rel_name: relative, unpromoted variable name, seen from current system (unique). prom / prom_name: relative, promoted variable name, seen from current system (non-unique). idx: global variable index among variables on all procs (I/O indices separate). my_idx: index among variables in this system, on this processor (I/O indices separate). io: indicates explicitly that input and output variables are combined in the same dict.

- Parameters

num_par_fdintIf FD is active, number of concurrent FD solves.

**kwargsdict of keyword argumentsKeyword arguments that will be mapped into the System options.

- Attributes

namestrName of the system, must be different from siblings.

pathnamestrGlobal name of the system, including the path.

commMPI.Comm or <FakeComm>MPI communicator object.

optionsOptionsDictionaryoptions dictionary

recording_optionsOptionsDictionaryRecording options dictionary

_problem_metadictProblem level metadata.

under_complex_stepboolWhen True, this system is undergoing complex step.

under_finite_differenceboolWhen True, this system is undergoing finite differencing.

under_approxboolWhen True, this system is undergoing approximation.

iter_countintCounts the number of times this system has called _solve_nonlinear. This also corresponds to the number of times that the system’s outputs are recorded if a recorder is present.

iter_count_applyintCounts the number of times the system has called _apply_nonlinear. For ExplicitComponent, calls to apply_nonlinear also call compute, so number of executions can be found by adding this and iter_count together. Recorders do no record calls to apply_nonlinear.

iter_count_without_approxintCounts the number of times the system has iterated but excludes any that occur during approximation of derivatives.

citestrListing of relevant citations that should be referenced when publishing work that uses this class.

_full_commMPI.Comm or NoneMPI communicator object used when System’s comm is split for parallel FD.

_solver_print_cachelistAllows solver iprints to be set to requested values after setup calls.

_subsystems_allprocsOrderedDictDict mapping subsystem name to SysInfo(system, index) for children of this system.

_subsystems_myproc[<System>, …]List of local subsystems that exist on this proc.

_var_promotes{ ‘any’: [], ‘input’: [], ‘output’: [] }Dictionary of lists of variable names/wildcards specifying promotion (used to calculate promoted names)

_var_prom2indsdictMaps promoted name to src_indices in scope of system.

_var_allprocs_prom2abs_list{‘input’: dict, ‘output’: dict}Dictionary mapping promoted names to list of all absolute names. For outputs, the list will have length one since promoted output names are unique.

_var_abs2prom{‘input’: dict, ‘output’: dict}Dictionary mapping absolute names to promoted names, on current proc.

_var_allprocs_abs2prom{‘input’: dict, ‘output’: dict}Dictionary mapping absolute names to promoted names, on all procs.

_var_allprocs_abs2metadictDictionary mapping absolute names to metadata dictionaries for allprocs variables. The keys are (‘units’, ‘shape’, ‘size’) for inputs and (‘units’, ‘shape’, ‘size’, ‘ref’, ‘ref0’, ‘res_ref’, ‘distributed’) for outputs.

_var_abs2metadictDictionary mapping absolute names to metadata dictionaries for myproc variables.

_var_discretedictDictionary of discrete var metadata and values local to this process.

_var_allprocs_discretedictDictionary of discrete var metadata and values for all processes.

_discrete_inputsdict-like or NoneStorage for discrete input values.

_discrete_outputsdict-like or NoneStorage for discrete output values.

_var_allprocs_abs2idxdictDictionary mapping absolute names to their indices among this system’s allprocs variables. Therefore, the indices range from 0 to the total number of this system’s variables.

_var_sizes{‘input’: ndarray, ‘output’: ndarray}Array of local sizes of this system’s allprocs variables. The array has size nproc x num_var where nproc is the number of processors owned by this system and num_var is the number of allprocs variables.

_owned_sizesndarrayArray of local sizes for ‘owned’ or distributed vars only.

_var_offsets{<vecname>: {‘input’: dict of ndarray, ‘output’: dict of ndarray}, …} or NoneDict of distributed offsets, keyed by var name. Offsets are stored in an array of size nproc x num_var where nproc is the number of processors in this System’s communicator and num_var is the number of allprocs variables in the given system. This is only defined in a Group that owns one or more interprocess connections or a top level Group or System that is used to compute total derivatives across multiple processes.

_vars_to_gatherdictContains names of non-distributed variables that are remote on at least one proc in the comm

_conn_global_abs_in2out{‘abs_in’: ‘abs_out’}Dictionary containing all explicit & implicit connections (continuous and discrete) owned by this system or any descendant system. The data is the same across all processors.

_vectors{‘input’: dict, ‘output’: dict, ‘residual’: dict}Dictionaries of vectors keyed by vec_name.

_inputs<Vector>The inputs vector; points to _vectors[‘input’][‘nonlinear’].

_outputs<Vector>The outputs vector; points to _vectors[‘output’][‘nonlinear’].

_residuals<Vector>The residuals vector; points to _vectors[‘residual’][‘nonlinear’].

_nonlinear_solver<NonlinearSolver>Nonlinear solver to be used for solve_nonlinear.

_linear_solver<LinearSolver>Linear solver to be used for solve_linear; not the Newton system.

_approx_schemesOrderedDictA mapping of approximation types to the associated ApproximationScheme.

_jacobian<Jacobian><Jacobian> object to be used in apply_linear.

_owns_approx_jacboolIf True, this system approximated its Jacobian

_owns_approx_jac_metadictStores approximation metadata (e.g., step_size) from calls to approx_totals

_owns_approx_oflist or NoneOverrides aproximation outputs. This is set when calculating system derivatives, and serves as a way to communicate the driver’s output quantities to the approximation objects so that we only take derivatives of variables that the driver needs.

_owns_approx_of_idxdictIndex for override ‘of’ approximations if declared. When the user calls add_objective or add_constraint, they may optionally specify an “indices” argument. This argument must also be communicated to the approximations when they are set up so that 1) the Jacobian is the correct size, and 2) we don’t perform any extra unnecessary calculations.

_owns_approx_wrtlist or NoneOverrides aproximation inputs. This is set when calculating system derivatives, and serves as a way to communicate the driver’s input quantities to the approximation objects so that we only take derivatives with respect to variables that the driver needs.

_owns_approx_wrt_idxdictIndex for override ‘wrt’ approximations if declared. When the user calls add_designvar they may optionally specify an “indices” argument. This argument must also be communicated to the approximations when they are set up so that 1) the Jacobian is the correct size, and 2) we don’t perform any extra unnecessary calculations.

_subjacs_infodict of dictSub-jacobian metadata for each (output, input) pair added using declare_partials. Members of each pair may be glob patterns.

_approx_subjac_keyslistList of subjacobian keys used for approximated derivatives.

_design_varsdict of dictdict of all driver design vars added to the system.

_responsesdict of dictdict of all driver responses added to the system.

_rec_mgr<RecordingManager>object that manages all recorders added to this system.

_static_subsystems_allprocsOrderedDictDict of SysInfo(subsys, index) that stores all subsystems added outside of setup.

_static_design_varsdict of dictDriver design variables added outside of setup.

_static_responsesdict of dictDriver responses added outside of setup.

matrix_freeboolThis is set to True if the component overrides the appropriate function with a user-defined matrix vector product with the Jacobian or any of its subsystems do.

_relevantdictMapping of a VOI to a tuple containing dependent inputs, dependent outputs, and dependent systems.

_voisdictEither design vars or responses metadata, depending on the direction of derivatives.

_modestrIndicates derivative direction for the model, either ‘fwd’ or ‘rev’.

_scope_cachedictCache for variables in the scope of various mat-vec products.

_has_guessboolTrue if this system has or contains a system with a guess_nonlinear method defined.

_has_output_scalingboolTrue if this system has output scaling.

_has_output_adderboolTrue if this system has scaling that includes an adder term.

_has_resid_scalingboolTrue if this system has resid scaling.

_has_input_scalingboolTrue if this system has input scaling.

_has_input_adderboolTrue if this system has scaling that includes an adder term.

_has_boundsboolTrue if this system has upper or lower bounds on outputs.

_has_distrib_varsboolIf True, this System contains at least one distributed variable. Used to determine if a parallel group or distributed component is below a DirectSolver so that we can raise an exception.

_owning_rankdictDict mapping var name to the lowest rank where that variable is local.

_filtered_vars_to_recordDictDict of list of var names to record

_vector_classclassClass to use for data vectors. After setup will contain the value of either _problem_meta[‘distributed_vector_class’] or _problem_meta[‘local_vector_class’].

_assembled_jacAssembledJacobian or NoneIf not None, this is the AssembledJacobian owned by this system’s linear_solver.

_num_par_fdintIf FD is active, and the value is > 1, turns on parallel FD and specifies the number of concurrent FD solves.

_par_fd_idintID used to determine which columns in the jacobian will be computed when using parallel FD.

_has_approxboolIf True, this system or its descendent has declared approximated partial or semi-total derivatives.

_coloring_infotupleMetadata that defines how to perform coloring of this System’s approx jacobian. Not used if this System does no partial or semi-total coloring.

_first_call_to_linearizeboolIf True, this is the first call to _linearize.

_is_localboolIf True, this system is local to this mpi process.

_tot_jac__TotalJacInfo or NoneIf a total jacobian is being computed and this is the top level System, this will be a reference to the _TotalJacInfo object.

`__init__`

(num_par_fd=1,**kwargs)[source]Initialize all attributes.

`abs_name_iter`

(iotype,local=True,cont=True,discrete=False)[source]Iterate over absolute variable names for this System.

By setting appropriate values for ‘cont’ and ‘discrete’, yielded variable names can be continuous only, discrete only, or both.

- Parameters

iotypestrEither ‘input’ or ‘output’.

localboolIf True, include only names of local variables. Default is True.

contboolIf True, include names of continuous variables. Default is True.

discreteboolIf True, include names of discrete variables. Default is False.

- Yields

- str

`add_constraint`

(name,lower=None,upper=None,equals=None,ref=None,ref0=None,adder=None,scaler=None,units=None,indices=None,linear=False,parallel_deriv_color=None,cache_linear_solution=False,flat_indices=False)[source]Add a constraint variable to this system.

- Parameters

namestrName of the response variable in the system.

lowerfloat or ndarray, optionalLower boundary for the variable.

upperfloat or ndarray, optionalUpper boundary for the variable.

equalsfloat or ndarray, optionalEquality constraint value for the variable.

reffloat or ndarray, optionalValue of response variable that scales to 1.0 in the driver.

ref0float or ndarray, optionalValue of response variable that scales to 0.0 in the driver.

adderfloat or ndarray, optionalValue to add to the model value to get the scaled value for the driver. adder is first in precedence. adder and scaler are an alterantive to using ref and ref0.

scalerfloat or ndarray, optionalValue to multiply the model value to get the scaled value for the driver. scaler is second in precedence. adder and scaler are an alterantive to using ref and ref0.

unitsstr, optionalUnits to convert to before applying scaling.

indicessequence of int, optionalIf variable is an array, these indicate which entries are of interest for this particular response. These may be positive or negative integers.

linearboolSet to True if constraint is linear. Default is False.

parallel_deriv_colorstrIf specified, this design var will be grouped for parallel derivative calculations with other variables sharing the same parallel_deriv_color.

cache_linear_solutionboolIf True, store the linear solution vectors for this variable so they can be used to start the next linear solution with an initial guess equal to the solution from the previous linear solve.

flat_indicesboolIf True, interpret specified indices as being indices into a flat source array.

Notes

The response can be scaled using ref and ref0. The argument

`ref0`

represents the physical value when the scaled value is 0. The argument`ref`

represents the physical value when the scaled value is 1. The arguments (`lower`

,`upper`

,`equals`

) can not be strings or variable names.

`add_design_var`

(name,lower=None,upper=None,ref=None,ref0=None,indices=None,adder=None,scaler=None,units=None,parallel_deriv_color=None,cache_linear_solution=False,flat_indices=False)[source]Add a design variable to this system.

- Parameters

namestrName of the design variable in the system.

lowerfloat or ndarray, optionalLower boundary for the input.

upperupper or ndarray, optionalUpper boundary for the input.

reffloat or ndarray, optionalValue of design var that scales to 1.0 in the driver.

ref0float or ndarray, optionalValue of design var that scales to 0.0 in the driver.

indicesiter of int, optionalIf an input is an array, these indicate which entries are of interest for this particular design variable. These may be positive or negative integers.

adderfloat or ndarray, optionalValue to add to the model value to get the scaled value for the driver. adder is first in precedence. adder and scaler are an alterantive to using ref and ref0.

scalerfloat or ndarray, optionalValue to multiply the model value to get the scaled value for the driver. scaler is second in precedence. adder and scaler are an alterantive to using ref and ref0.

unitsstr, optionalUnits to convert to before applying scaling.

parallel_deriv_colorstrIf specified, this design var will be grouped for parallel derivative calculations with other variables sharing the same parallel_deriv_color.

cache_linear_solutionboolIf True, store the linear solution vectors for this variable so they can be used to start the next linear solution with an initial guess equal to the solution from the previous linear solve.

flat_indicesboolIf True, interpret specified indices as being indices into a flat source array.

Notes

The response can be scaled using ref and ref0. The argument

`ref0`

represents the physical value when the scaled value is 0. The argument`ref`

represents the physical value when the scaled value is 1.

`add_objective`

(name,ref=None,ref0=None,index=None,units=None,adder=None,scaler=None,parallel_deriv_color=None,cache_linear_solution=False,flat_indices=False)[source]Add a response variable to this system.

- Parameters

namestrName of the response variable in the system.

reffloat or ndarray, optionalValue of response variable that scales to 1.0 in the driver.

ref0float or ndarray, optionalValue of response variable that scales to 0.0 in the driver.

indexint, optionalIf variable is an array, this indicates which entry is of interest for this particular response. This may be a positive or negative integer.

unitsstr, optionalUnits to convert to before applying scaling.

adderfloat or ndarray, optionalValue to add to the model value to get the scaled value for the driver. adder is first in precedence. adder and scaler are an alterantive to using ref and ref0.

scalerfloat or ndarray, optionalValue to multiply the model value to get the scaled value for the driver. scaler is second in precedence. adder and scaler are an alterantive to using ref and ref0.

parallel_deriv_colorstrIf specified, this design var will be grouped for parallel derivative calculations with other variables sharing the same parallel_deriv_color.

cache_linear_solutionboolIf True, store the linear solution vectors for this variable so they can be used to start the next linear solution with an initial guess equal to the solution from the previous linear solve.

flat_indicesboolIf True, interpret specified indices as being indices into a flat source array.

Notes

The objective can be scaled using scaler and adder, where

\[x_{scaled} = scaler(x + adder)\]or through the use of ref/ref0, which map to scaler and adder through the equations:

\[ \begin{align}\begin{aligned}0 = scaler(ref_0 + adder)\\1 = scaler(ref + adder)\end{aligned}\end{align} \]which results in:

\[ \begin{align}\begin{aligned}adder = -ref_0\\scaler = \frac{1}{ref + adder}\end{aligned}\end{align} \]

`add_recorder`

(recorder,recurse=False)[source]Add a recorder to the system.

- Parameters

recorder<CaseRecorder>A recorder instance.

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

`add_response`

(name,type_,lower=None,upper=None,equals=None,ref=None,ref0=None,indices=None,index=None,units=None,adder=None,scaler=None,linear=False,parallel_deriv_color=None,cache_linear_solution=False,flat_indices=None)[source]Add a response variable to this system.

The response can be scaled using ref and ref0. The argument

`ref0`

represents the physical value when the scaled value is 0. The argument`ref`

represents the physical value when the scaled value is 1.

- Parameters

namestrName of the response variable in the system.

type_strThe type of response. Supported values are ‘con’ and ‘obj’.

lowerfloat or ndarray, optionalLower boundary for the variable.

upperupper or ndarray, optionalUpper boundary for the variable.

equalsequals or ndarray, optionalEquality constraint value for the variable.

reffloat or ndarray, optionalValue of response variable that scales to 1.0 in the driver.

ref0upper or ndarray, optionalValue of response variable that scales to 0.0 in the driver.

indicessequence of int, optionalIf variable is an array, these indicate which entries are of interest for this particular response.

indexint, optionalIf variable is an array, this indicates which entry is of interest for this particular response.

unitsstr, optionalUnits to convert to before applying scaling.

adderfloat or ndarray, optionalscalerfloat or ndarray, optionallinearboolSet to True if constraint is linear. Default is False.

parallel_deriv_colorstrcache_linear_solutionboolflat_indicesboolIf True, interpret specified indices as being indices into a flat source array.

`all_connected_nodes`

(graph,start,local=False)[source]Yield all downstream nodes starting at the given node.

- Parameters

graphnetwork.DiGraphGraph being traversed.

starthashable objectIdentifier of the starting node.

localboolIf True and a non-local node is encountered in the traversal, the traversal ends on that branch.

- Yields

- str
Each node found when traversal starts at start.

`check_config`

(logger)[source]Perform optional error checks.

- Parameters

loggerobjectThe object that manages logging output.

`cleanup`

()[source]Clean up resources prior to exit.

`convert2units`

(name,val,units)[source]Convert the given value to the specified units.

- Parameters

namestrName of the variable.

valfloat or ndarray of floatThe value of the variable.

unitsstrThe units to convert to.

- Returns

- float or ndarray of float
The value converted to the specified units.

`convert_from_units`

(name,val,units)[source]Convert the given value from the specified units to those of the named variable.

- Parameters

namestrName of the variable.

valfloat or ndarray of floatThe value of the variable.

unitsstrThe units to convert to.

- Returns

- float or ndarray of float
The value converted to the specified units.

`convert_units`

(name,val,units_from,units_to)[source]Wrap the utility convert_units and give a good error message.

- Parameters

namestrName of the variable.

valfloat or ndarray of floatThe value of the variable.

units_fromstrThe units to convert from.

units_tostrThe units to convert to.

- Returns

- float or ndarray of float
The value converted to the specified units.

`declare_coloring`

(wrt=('*'),method='fd',form=None,step=None,per_instance=True,num_full_jacs=3,tol=1e-25,orders=None,perturb_size=1e-09,min_improve_pct=5.0,show_summary=True,show_sparsity=False)[source]Set options for deriv coloring of a set of wrt vars matching the given pattern(s).

- Parameters

wrtstr or list of strThe name or names of the variables that derivatives are taken with respect to. This can contain input names, output names, or glob patterns.

methodstrMethod used to compute derivative: “fd” for finite difference, “cs” for complex step.

formstrFinite difference form, can be “forward”, “central”, or “backward”. Leave undeclared to keep unchanged from previous or default value.

stepfloatStep size for finite difference. Leave undeclared to keep unchanged from previous or default value.

per_instanceboolIf True, a separate coloring will be generated for each instance of a given class. Otherwise, only one coloring for a given class will be generated and all instances of that class will use it.

num_full_jacsintNumber of times to repeat partial jacobian computation when computing sparsity.

tolfloatTolerance used to determine if an array entry is nonzero during sparsity determination.

ordersintNumber of orders above and below the tolerance to check during the tolerance sweep.

perturb_sizefloatSize of input/output perturbation during generation of sparsity.

min_improve_pctfloatIf coloring does not improve (decrease) the number of solves more than the given percentage, coloring will not be used.

show_summaryboolIf True, display summary information after generating coloring.

show_sparsityboolIf True, display sparsity with coloring info after generating coloring.

`get_coloring_fname`

()[source]Return the full pathname to a coloring file.

- Returns

- str
Full pathname of the coloring file.

`get_constraints`

(recurse=True)[source]Get the Constraint settings from this system.

Retrieve the constraint settings for the current system as a dict, keyed by variable name.

- Parameters

recursebool, optionalIf True, recurse through the subsystems and return the path of all constraints relative to the this system.

- Returns

- dict
The constraints defined in the current system.

`get_design_vars`

(recurse=True,get_sizes=True,use_prom_ivc=True)[source]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

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

get_sizesbool, optionalIf True, compute the size of each design variable.

use_prom_ivcboolTranslate auto_ivc_names to their promoted input names.

- Returns

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

`get_io_metadata`

(iotypes=('input', 'output'),metadata_keys=None,includes=None,excludes=None,tags=(),get_remote=False,rank=None,return_rel_names=True)[source]Retrieve metdata for a filtered list of variables.

- Parameters

iotypesstr or iter of strWill contain either ‘input’, ‘output’, or both. Defaults to both.

metadata_keysiter of str or NoneNames of metadata entries to be retrieved or None, meaning retrieve all available ‘allprocs’ metadata. If ‘val’ or ‘src_indices’ are required, their keys must be provided explicitly since they are not found in the ‘allprocs’ metadata and must be retrieved from local metadata located in each process.

includesstr, iter of str or NoneCollection of glob patterns for pathnames of variables to include. Default is None, which includes all variables.

excludesstr, iter of str or NoneCollection of glob patterns for pathnames of variables to exclude. Default is None.

tagsstr or iter of strsUser defined tags that can be used to filter what gets listed. Only inputs with the given tags will be listed. Default is None, which means there will be no filtering based on tags.

get_remoteboolIf True, retrieve variables from other MPI processes as well.

rankint or NoneIf None, and get_remote is True, retrieve values from all MPI process to all other MPI processes. Otherwise, if get_remote is True, retrieve values from all MPI processes only to the specified rank.

return_rel_namesboolIf True, the names returned will be relative to the scope of this System. Otherwise they will be absolute names.

- Returns

- dict
A dict of metadata keyed on name, where name is either absolute or relative based on the value of the return_rel_names arg, and metadata is a dict containing entries based on the value of the metadata_keys arg. Every metadata dict will always contain two entries, ‘promoted_name’ and ‘discrete’, to indicate a given variable’s promoted name and whether or not it is discrete.

`get_linear_vectors`

()[source]Return the linear inputs, outputs, and residuals vectors.

- Returns

- (inputs, outputs, residuals): tuple of <Vector> instances
Yields the linear inputs, outputs, and residuals vectors.

`get_nonlinear_vectors`

()[source]Return the inputs, outputs, and residuals vectors.

- Returns

- (inputs, outputs, residuals)
Yields the inputs, outputs, and residuals nonlinear vectors.

`get_objectives`

(recurse=True)[source]Get the Objective settings from this system.

Retrieve all objectives settings from the system as a dict, keyed by variable name.

- Parameters

recursebool, optionalIf True, recurse through the subsystems and return the path of all objective relative to the this system.

- Returns

- dict
The objectives defined in the current system.

`get_relevant_vars`

(desvars,responses,mode)[source]Find all relevant vars between desvars and responses.

Both vars are assumed to be outputs (either design vars or responses).

- Parameters

desvarsdictDictionary of design variable metadata.

responsesdictDictionary of response variable metadata.

modestrDirection of derivatives, either ‘fwd’ or ‘rev’.

- Returns

- dict
Dict of ({‘outputs’: dep_outputs, ‘inputs’: dep_inputs}, dep_systems) keyed by design vars and responses.

`get_responses`

(recurse=True,get_sizes=True,use_prom_ivc=False)[source]Get the response variable settings from this system.

Retrieve all response variable settings from the system as a dict, keyed by variable name.

- Parameters

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

get_sizesbool, optionalIf True, compute the size of each response.

use_prom_ivcboolTranslate auto_ivc_names to their promoted input names.

- Returns

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

`get_source`

(name)[source]Return the source variable connected to the given named variable.

The name can be a promoted name or an absolute name. If the given variable is an input, the absolute name of the connected source will be returned. If the given variable itself is a source, its own absolute name will be returned.

- Parameters

namestrAbsolute or promoted name of the variable.

- Returns

- str
The absolute name of the source variable.

`get_val`

(name,units=None,indices=None,get_remote=False,rank=None,vec_name='nonlinear',kind=None,flat=False,from_src=True)[source]Get an output/input/residual variable.

Function is used if you want to specify display units.

- Parameters

namestrPromoted or relative variable name in the root system’s namespace.

unitsstr, optionalUnits to convert to before return.

indicesint or list of ints or tuple of ints or int ndarray or Iterable or None, optionalIndices or slice to return.

get_remotebool or NoneIf True, retrieve the value even if it is on a remote process. Note that if the variable is remote on ANY process, this function must be called on EVERY process in the Problem’s MPI communicator. If False, only retrieve the value if it is on the current process, or only the part of the value that’s on the current process for a distributed variable. If None and the variable is remote or distributed, a RuntimeError will be raised.

rankint or NoneIf not None, only gather the value to this rank.

vec_namestrName of the vector to use. Defaults to ‘nonlinear’.

kindstr or NoneKind of variable (‘input’, ‘output’, or ‘residual’). If None, returned value will be either an input or output.

flatboolIf True, return the flattened version of the value.

from_srcboolIf True, retrieve value of an input variable from its connected source.

- Returns

- object
The value of the requested output/input variable.

`initialize`

()[source]Perform any one-time initialization run at instantiation.

`is_active`

()[source]Determine if the system is active on this rank.

- Returns

- bool
If running under MPI, returns True if this System has a valid communicator. Always returns True if not running under MPI.

property`linear_solver`

Get the linear solver for this system.

`list_inputs`

(val=True,prom_name=False,units=False,shape=False,global_shape=False,desc=False,hierarchical=True,print_arrays=False,tags=None,includes=None,excludes=None,all_procs=False,out_stream=DEFAULT_OUT_STREAM,values=None,print_min=False,print_max=False)[source]Write a list of input names and other optional information to a specified stream.

- Parameters

valbool, optionalWhen True, display/return input values. Default is True.

prom_namebool, optionalWhen True, display/return the promoted name of the variable. Default is False.

unitsbool, optionalWhen True, display/return units. Default is False.

shapebool, optionalWhen True, display/return the shape of the value. Default is False.

global_shapebool, optionalWhen True, display/return the global shape of the value. Default is False.

descbool, optionalWhen True, display/return description. Default is False.

hierarchicalbool, optionalWhen True, human readable output shows variables in hierarchical format.

print_arraysbool, optionalWhen False, in the columnar display, just display norm of any ndarrays with size > 1. The norm is surrounded by vertical bars to indicate that it is a norm. When True, also display full values of the ndarray below the row. Format is affected by the values set with numpy.set_printoptions Default is False.

tagsstr or list of strsUser defined tags that can be used to filter what gets listed. Only inputs with the given tags will be listed. Default is None, which means there will be no filtering based on tags.

includesNone, str, or iter of strCollection of glob patterns for pathnames of variables to include. Default is None, which includes all input variables.

excludesNone, str, or iter of strCollection of glob patterns for pathnames of variables to exclude. Default is None.

all_procsbool, optionalWhen True, display output on all ranks. Default is False, which will display output only from rank 0.

out_streamfile-like objectWhere to send human readable output. Default is sys.stdout. Set to None to suppress.

valuesbool, optionalThis argument has been deprecated and will be removed in 4.0.

print_minboolWhen true, if the input value is an array, print its smallest value.

print_maxboolWhen true, if the input value is an array, print its largest value.

- Returns

- list of (name, metadata)
List of input names and other optional information about those inputs.

`list_outputs`

(explicit=True,implicit=True,val=True,prom_name=False,residuals=False,residuals_tol=None,units=False,shape=False,global_shape=False,bounds=False,scaling=False,desc=False,hierarchical=True,print_arrays=False,tags=None,includes=None,excludes=None,all_procs=False,list_autoivcs=False,out_stream=DEFAULT_OUT_STREAM,values=None,print_min=False,print_max=False)[source]Write a list of output names and other optional information to a specified stream.

- Parameters

explicitbool, optionalInclude outputs from explicit components. Default is True.

implicitbool, optionalInclude outputs from implicit components. Default is True.

valbool, optionalWhen True, display output values. Default is True.

prom_namebool, optionalWhen True, display the promoted name of the variable. Default is False.

residualsbool, optionalWhen True, display residual values. Default is False.

residuals_tolfloat, optionalIf set, limits the output of list_outputs to only variables where the norm of the resids array is greater than the given ‘residuals_tol’. Default is None.

unitsbool, optionalWhen True, display units. Default is False.

shapebool, optionalWhen True, display/return the shape of the value. Default is False.

global_shapebool, optionalWhen True, display/return the global shape of the value. Default is False.

boundsbool, optionalWhen True, display/return bounds (lower and upper). Default is False.

scalingbool, optionalWhen True, display/return scaling (ref, ref0, and res_ref). Default is False.

descbool, optionalWhen True, display/return description. Default is False.

hierarchicalbool, optionalWhen True, human readable output shows variables in hierarchical format.

print_arraysbool, optionalWhen False, in the columnar display, just display norm of any ndarrays with size > 1. The norm is surrounded by vertical bars to indicate that it is a norm. When True, also display full values of the ndarray below the row. Format is affected by the values set with numpy.set_printoptions Default is False.

tagsstr or list of strsUser defined tags that can be used to filter what gets listed. Only outputs with the given tags will be listed. Default is None, which means there will be no filtering based on tags.

includesNone, str, or iter of strCollection of glob patterns for pathnames of variables to include. Default is None, which includes all output variables.

excludesNone, str, or iter of strCollection of glob patterns for pathnames of variables to exclude. Default is None.

all_procsbool, optionalWhen True, display output on all processors. Default is False.

list_autoivcsboolIf True, include auto_ivc outputs in the listing. Defaults to False.

out_streamfile-likeWhere to send human readable output. Default is sys.stdout. Set to None to suppress.

valuesbool, optionalThis argument has been deprecated and will be removed in 4.0.

print_minboolWhen true, if the output value is an array, print its smallest value.

print_maxboolWhen true, if the output value is an array, print its largest value.

- Returns

- list of (name, metadata)
List of output names and other optional information about those outputs.

property`msginfo`

Our instance pathname, if available, or our class name. For use in error messages.

- Returns

- str
Either our instance pathname or class name.

property`nonlinear_solver`

Get the nonlinear solver for this system.

`record_iteration`

()[source]Record an iteration of the current System.

`run_apply_linear`

(mode,scope_out=None,scope_in=None)[source]Compute jac-vec product.

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

- Parameters

modestr‘fwd’ or ‘rev’.

scope_outset or NoneSet of absolute output names in the scope of this mat-vec product. If None, all are in the scope.

scope_inset or NoneSet of absolute input names in the scope of this mat-vec product. If None, all are in the scope.

`run_apply_nonlinear`

()[source]Compute residuals.

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

`run_linearize`

(sub_do_ln=True)[source]Compute jacobian / factorization.

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

- Parameters

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

`run_solve_linear`

(mode)[source]Apply inverse jac product.

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

- Parameters

modestr‘fwd’ or ‘rev’.

`run_solve_nonlinear`

()[source]Compute outputs.

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

`set_initial_values`

()[source]Set all input and output variables to their declared initial values.

`set_solver_print`

(level=2,depth=1e+99,type_='all')[source]Control printing for solvers and subsolvers in the model.

- Parameters

levelintIprint level. Set to 2 to print residuals each iteration; set to 1 to print just the iteration totals; set to 0 to disable all printing except for failures, and set to -1 to disable all printing including failures.

depthintHow deep to recurse. For example, you can set this to 0 if you only want to print the top level linear and nonlinear solver messages. Default prints everything.

type_strType of solver to set: ‘LN’ for linear, ‘NL’ for nonlinear, or ‘all’ for all.

`system_iter`

(include_self=False,recurse=True,typ=None)[source]Yield a generator of local subsystems of this system.

- Parameters

include_selfboolIf True, include this system in the iteration.

recurseboolIf True, iterate over the whole tree under this system.

typtypeIf not None, only yield Systems that match that are instances of the given type.

- Yields

- type or None

`use_fixed_coloring`

(coloring=<object object>,recurse=True)[source]Use a precomputed coloring for this System.

- Parameters

coloringstrA coloring filename. If no arg is passed, filename will be determined automatically.

recurseboolIf True, set fixed coloring in all subsystems that declare a coloring. Ignored if a specific coloring is passed in.