Declaring Continuous Variables

Calling add_input and add_output

Every component in an OpenMDAO model is an instance of ExplicitComponent, ImplicitComponent, or a subclass of one of these classes. Regardless of the type, each component has input variables and output variables that it must declare.

In explicit and implicit components, the user must call add_input and add_output to declare variables in the setup method. An example is given below.

import openmdao.api as om


class TestExplCompSimple(om.ExplicitComponent):

    def setup(self):
        self.add_input('length', val=1., desc='length of rectangle')
        self.add_input('width', val=1., desc='width of rectangle')
        self.add_output('area', val=1., desc='area of rectangle')

    def setup_partials(self):
        self.declare_partials('*', '*')

    def compute(self, inputs, outputs):
        outputs['area'] = inputs['length'] * inputs['width']

Note

Variable names have few restrictions, but the following characters are not allowed in a variable name: ‘.’, ‘*’, ‘?’, ‘!’, ‘[‘, ‘]’.

Method Signatures

Component.add_input(name, val=1.0, shape=None, src_indices=None, flat_src_indices=None, units=None, desc='', tags=None, shape_by_conn=False, copy_shape=None, distributed=None)[source]

Add an input variable to the component.

Parameters
namestr

Name of the variable in this component’s namespace.

valfloat or list or tuple or ndarray or Iterable

The initial value of the variable being added in user-defined units. Default is 1.0.

shapeint or tuple or list or None

Shape of this variable, only required if src_indices not provided and val is not an array. Default is None.

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

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

flat_src_indicesbool

If True and the source is non-flat, each entry of src_indices is assumed to be an index into the flattened source. Ignored if the source is flat.

unitsstr or None

Units in which this input variable will be provided to the component during execution. Default is None, which means it is unitless.

descstr

Description of the variable.

tagsstr or list of strs

User defined tags that can be used to filter what gets listed when calling list_inputs and list_outputs.

shape_by_connbool

If True, shape this input to match its connected output.

copy_shapestr or None

If a str, that str is the name of a variable. Shape this input to match that of the named variable.

distributedbool

If True, this variable is a distributed variable, so it can have different sizes/values across MPI processes.

Returns
dict

Metadata for added variable.

Component.add_output(name, val=1.0, shape=None, units=None, res_units=None, desc='', lower=None, upper=None, ref=1.0, ref0=0.0, res_ref=None, tags=None, shape_by_conn=False, copy_shape=None, distributed=None)[source]

Add an output variable to the component.

Parameters
namestr

Name of the variable in this component’s namespace.

valfloat or list or tuple or ndarray

The initial value of the variable being added in user-defined units. Default is 1.0.

shapeint or tuple or list or None

Shape of this variable, only required if val is not an array. Default is None.

unitsstr or None

Units in which the output variables will be provided to the component during execution. Default is None, which means it has no units.

res_unitsstr or None

Units in which the residuals of this output will be given to the user when requested. Default is None, which means it has no units.

descstr

Description of the variable.

lowerfloat or list or tuple or ndarray or Iterable or None

Lower bound(s) in user-defined units. It can be (1) a float, (2) an array_like consistent with the shape arg (if given), or (3) an array_like matching the shape of val, if val is array_like. A value of None means this output has no lower bound. Default is None.

upperfloat or list or tuple or ndarray or or Iterable None

Upper bound(s) in user-defined units. It can be (1) a float, (2) an array_like consistent with the shape arg (if given), or (3) an array_like matching the shape of val, if val is array_like. A value of None means this output has no upper bound. Default is None.

reffloat or ndarray

Scaling parameter. The value in the user-defined units of this output variable when the scaled value is 1. Default is 1.

ref0float or ndarray

Scaling parameter. The value in the user-defined units of this output variable when the scaled value is 0. Default is 0.

res_reffloat or ndarray

Scaling parameter. The value in the user-defined res_units of this output’s residual when the scaled value is 1. Default is 1.

tagsstr or list of strs or set of strs

User defined tags that can be used to filter what gets listed when calling list_inputs and list_outputs.

shape_by_connbool

If True, shape this output to match its connected input(s).

copy_shapestr or None

If a str, that str is the name of a variable. Shape this output to match that of the named variable.

distributedbool

If True, this variable is a distributed variable, so it can have different sizes/values across MPI processes.

Returns
dict

Metadata for added variable.

Usage

1. Declaring with only the default value.

import numpy as np

class CompAddWithDefault(om.ExplicitComponent):
    """Component for tests for declaring only default value."""

    def setup(self):
        self.add_input('x_a')
        self.add_input('x_b', val=3.)
        self.add_input('x_c', val=(3., 3.))
        self.add_input('x_d', val=[3., 3.])
        self.add_input('x_e', val=3. * np.ones((2, 2)))

        self.add_output('y_a')
        self.add_output('y_b', val=6.)
        self.add_output('y_c', val=(6., 6., 6.))
        self.add_output('y_d', val=[6., 6., 6.])
        self.add_output('y_e', val=6. * np.ones((3, 2)))
"""Test declaring only default value."""
p = om.Problem(model=CompAddWithDefault())
p.setup()

print(p.get_val('x_a'))
[1.]
/usr/share/miniconda/envs/test/lib/python3.10/site-packages/openmdao/core/problem.py:1095: OMDeprecationWarning:The model for this Problem is of type 'CompAddWithDefault'. A future release will require that the model be a Group or a sub-class of Group.
print(p.get_val('x_b'))
[3.]
print(p.get_val('x_c'))
[3. 3.]
print(p.get_val('x_d'))
[3. 3.]
print(p.get_val('x_e'))
[[3. 3.]
 [3. 3.]]
print(p.get_val('y_a'))
[1.]
print(p.get_val('y_b'))
[6.]
print(p.get_val('y_c'))
[6. 6. 6.]
print(p.get_val('y_d'))
[6. 6. 6.]
print(p.get_val('y_e'))
[[6. 6.]
 [6. 6.]
 [6. 6.]]

2. Declaring with only the shape argument.

class CompAddWithShape(om.ExplicitComponent):
    """Component for tests for declaring only shape."""

    def setup(self):
        self.add_input('x_a', shape=2)
        self.add_input('x_b', shape=(2, 2))
        self.add_input('x_c', shape=[2, 2])

        self.add_output('y_a', shape=3)
        self.add_output('y_b', shape=(3, 3))
        self.add_output('y_c', shape=[3, 3])
"""Test declaring only shape."""
p = om.Problem(model=CompAddWithShape())
p.setup()

print(p.get_val('x_a'))
[1. 1.]
/usr/share/miniconda/envs/test/lib/python3.10/site-packages/openmdao/core/problem.py:1095: OMDeprecationWarning:The model for this Problem is of type 'CompAddWithShape'. A future release will require that the model be a Group or a sub-class of Group.
print(p.get_val('x_b'))
[[1. 1.]
 [1. 1.]]
print(p.get_val('x_c'))
[[1. 1.]
 [1. 1.]]
print(p.get_val('y_a'))
[1. 1. 1.]
print(p.get_val('y_b'))
[[1. 1. 1.]
 [1. 1. 1.]
 [1. 1. 1.]]
print(p.get_val('y_c'))
[[1. 1. 1.]
 [1. 1. 1.]
 [1. 1. 1.]]

4. Declaring an array variable with a scalar default value.

class CompAddArrayWithScalar(om.ExplicitComponent):
    """Component for tests for declaring a scalar val with an array variable."""

    def setup(self):
        self.add_input('x_a', val=2.0, shape=(6))
        self.add_input('x_b', val=2.0, shape=(3, 2))
        self.add_output('y_a', val=3.0, shape=(6))
        self.add_output('y_b', val=3.0, shape=(3, 2))
"""Test declaring a scalar val with an array variable."""
p = om.Problem(model=CompAddArrayWithScalar())
p.setup()
/usr/share/miniconda/envs/test/lib/python3.10/site-packages/openmdao/core/problem.py:1095: OMDeprecationWarning:The model for this Problem is of type 'CompAddArrayWithScalar'. A future release will require that the model be a Group or a sub-class of Group.
<openmdao.core.problem.Problem at 0x7f4921b6ec20>
print(p.get_val('x_a'))
[2. 2. 2. 2. 2. 2.]
print(p.get_val('x_b'))
[[2. 2.]
 [2. 2.]
 [2. 2.]]
print(p.get_val('y_a'))
[3. 3. 3. 3. 3. 3.]
print(p.get_val('y_b'))
[[3. 3.]
 [3. 3.]
 [3. 3.]]

6. Declaring an output with bounds, using upper and/or lower arguments.

class CompAddWithBounds(om.ExplicitComponent):
    """Component for tests for declaring bounds."""

    def setup(self):
        self.add_input('x')

        self.add_output('y_a', val=2.0, lower=0.)
        self.add_output('y_b', val=2.0, lower=0., upper=10.)
        self.add_output('y_c', val=2.0 * np.ones(6),  lower=np.zeros(6), upper=10.)
        self.add_output('y_d', val=2.0 * np.ones(6), lower=0., upper=[12, 10, 10, 10, 10, 12])
        self.add_output('y_e', val=2.0 * np.ones((3, 2)), lower=np.zeros((3, 2)))
"""Test declaring bounds."""
p = om.Problem(model=CompAddWithBounds())
p.setup()

print(p.get_val('y_a'))
[2.]
/usr/share/miniconda/envs/test/lib/python3.10/site-packages/openmdao/core/problem.py:1095: OMDeprecationWarning:The model for this Problem is of type 'CompAddWithBounds'. A future release will require that the model be a Group or a sub-class of Group.
print(p.get_val('y_b'))
[2.]
print(p.get_val('y_c'))
[2. 2. 2. 2. 2. 2.]
print(p.get_val('y_d'))
[2. 2. 2. 2. 2. 2.]

print(p.get_val('y_e'))
[[2. 2.]
 [2. 2.]
 [2. 2.]]

7. Adding tags to input and output variables. These tags can then be used to filter what gets returned from the System.get_io_metadata method and displayed/returned from the System.list_inputs and System.list_outputs methods.

class RectangleCompWithTags(om.ExplicitComponent):
    """
    A simple Explicit Component that also has input and output with tags.
    """

    def setup(self):
        self.add_input('length', val=1., tags=["tag1", "tag2"])
        self.add_input('width', val=1., tags=["tag2"])
        self.add_output('area', val=1., tags="tag1")

    def setup_partials(self):
        self.declare_partials('*', '*')

    def compute(self, inputs, outputs):
        outputs['area'] = inputs['length'] * inputs['width']

prob = om.Problem(RectangleCompWithTags())
prob.setup(check=False)
prob.run_model()

# Inputs no tags
inputs = prob.model.list_inputs(val=False, out_stream=None)
print(sorted(inputs))
[('length', {}), ('width', {})]
/usr/share/miniconda/envs/test/lib/python3.10/site-packages/openmdao/core/problem.py:1095: OMDeprecationWarning:The model for this Problem is of type 'RectangleCompWithTags'. A future release will require that the model be a Group or a sub-class of Group.
# Inputs with tags
inputs = prob.model.list_inputs(val=False, out_stream=None, tags="tag1")
print(sorted(inputs))
[('length', {})]
# Inputs with multiple tags
inputs = prob.model.list_inputs(val=False, out_stream=None, tags=["tag1", "tag2"])
print(sorted(inputs))
[('length', {}), ('width', {})]
# Inputs with tag that does not match
inputs = prob.model.list_inputs(val=False, out_stream=None, tags="tag3")
print(sorted(inputs))
[]
# Outputs no tags
outputs = prob.model.list_outputs(val=False, out_stream=None)
print(sorted(outputs))
[('area', {})]
# Outputs with tags
outputs = prob.model.list_outputs(val=False, out_stream=None, tags="tag1")
print(sorted(outputs))
[('area', {})]
# Outputs with multiple tags
outputs = prob.model.list_outputs(val=False, out_stream=None, tags=["tag1", "tag3"])
print(sorted(outputs))
[('area', {})]
# Outputs with tag that does not match
outputs = prob.model.list_outputs(val=False, out_stream=None, tags="tag3")
print(sorted(outputs))
[]

Calling add_residual

By default, residuals and outputs have the same names, but there are times when writing an ImplicitComponent that this might be confusing. OpenMDAO POEM 69 has specific examples that demonstrate the confusion.

To address this, the add_residual method was added to ImplicitComponent.

ImplicitComponent.add_residual(name, shape=(), units=None, desc='', ref=None)[source]

Add an residual variable to the component.

Note that the total size of the residual vector must match the total size of the outputs vector for this component.

Parameters
namestr

Name of the residual in this component’s namespace.

shapeint or tuple

Shape of this residual.

unitsstr or None

Units in which this residual will be given to the user when requested. Default is None, which means it has no units.

descstr

Description of the residual.

reffloat or ndarray or None

Scaling parameter. The value in the user-defined units of this residual when the scaled value is 1. Default is 1.

Returns
dict

Metadata for the added residual.

Note that if you make any calls to add_residual, you must use it to add all of the residuals, so that the size of the residuals vector is the same size as the outputs vector for that component.

Also note that this residual renaming is only active inside of the component, and the rest of the framework will still deal with residuals as if they map 1-to-1 with outputs.