Implicit Relationships with Subsystems
======================================

Residual variables may depend on the result of a subsystem.
For example, the solution to a quadratic equation depends on the
coefficients, but one of those coefficients may not be constant, and may
depend on a subsystem.

In this example, we solve :math:`ax^2+bx+c=0`, but :math:`a` is a fixed
point of :math:`(3 + a - 2a^2)^\frac{1}{4}`.

In order to compute :math:`a`, ``omtools`` creates a new
``openmdao.Problem`` instance within an ``ImplicitComponent``.
The ``Problem`` instance contains a model, which is an instance of
``ot.Group``.
The ``ImplicitComponent`` class provides acces to this ``ot.Group``
object with ``self.group``.
Residuals that depend on subsystems may be defined with
calls to ``self.group.add_subsystem``.

**Subsystems added by calling ``self.group.add_subsystem`` are
part of the residual(s), not the ``ImplicitComponent``.**

**All inputs to the ``ImplicitComponent`` must be declared using calls
to ``self.group.declare_input`` at the beginning of ``self.setup``,
before any calls to ``self.group.add_subsystem``.**

In this example, the only input is ``c``.
Both ``a`` and ``b`` are outputs of subsystems used to define the
residual.

.. jupyter-execute::
  ../../../../omtools/examples/valid/ex_implicit_with_subsystems.py


Note that calls to ``ImplicitComponent.add_subsystem`` result in adding
a subsystem to the internal ``Problem`` instance (not shown), and not
the ``ImplicitComponent`` itself.

.. embed-n2::
  ../omtools/examples/valid/ex_implicit_with_subsystems.py

Here is the n2 diagram generated by passing ``n2=True`` to the
constructor for ``ImplicitOutput`` to verify that the model
structure for the residual is correct.

.. embed-n2::
  ../omtools/examples/valid/ex_implicit_with_subsystems_internal_n2.py

Just as with residuals that do not require subsystems to converge,
bracketing solutions is an option as well.

.. jupyter-execute::
  ../../../../omtools/examples/valid/ex_implicit_with_subsystems_bracketed_scalar.py

Brackets may also be specified for multidimensional array values.

.. jupyter-execute::
  ../../../../omtools/examples/valid/ex_implicit_with_subsystems_bracketed_array.py