.. _section-6.4:

Guide to User Application
-------------------------

This section provides some guidelines that should help tie together the
model equations and solution techniques just described and the card
input description given in :numref:`section-A6.1`. In this section signal
definition rules that must be observed are stated, model capabilities
are highlighted, and rules of thumb for choosing the values of solution
control parameters are given.

.. _section-6.4.1:

Signal Definition Rules
~~~~~~~~~~~~~~~~~~~~~~~

Signals are defined through the input deck and the definitions must
conform to certain rules. Any of the four signal kinds can appear
anywhere in the signal card region of the input deck, subject to the
following rules.

#. A block signal that is output from other than an integrator, lag compensator or lead-lag compensator must have been previously defined in the input stream before it can be used as an input to another block. This rule is intended to avoid circular references and to maintain proper sequencing of signals during numerical integration.
#. A demand signal or measured signal must pass through at least one block before it can be used as a control signal.
#. Each signal must be assigned a unique signal number between 1 and 998.

The card format for defining a signal is given in :numref:`section-A6.1`.

.. _section-6.4.2:

Units
~~~~~

Generally all measured signals are in MKS units while all control
signals should be calculated in these same units. The exceptions are
those signals that are normalized to a steady state value; these are
appropriately noted in :numref:`table-A6.1-3`.

The convention for demand signals is that demand tables are always
entered by the user, normalized to a time zero value of unity. The
actual value for a demand signal is calculated in the code by
multiplying the current time entry in the demand table by the initial
condition value. The next subsection describes how the initial condition
value is obtained.

The units of a block output signal are determined solely by the units of
the input signals and any conversion factors that are entered by the
user as constants on the block definition card.

.. _section-6.4.3:

Initial Conditions
~~~~~~~~~~~~~~~~~~

In order to begin a transient calculation, initial condition values are
required for demand signals and for the integrator, lag compensator and
lead-lag compensator blocks. There are basically three options available
for setting these values. In the first option, all values are supplied
by the user through input cards: in this case the steady state solution
finder is bypassed. If the user is seeking the steady state solution,
then a null transient may have to be run. In the second option, the
steady state solution finder is used to solve for the steady state
values. In the final option, a mixed set of initial conditions are used
with some values read directly from the signal cards while the remaining
values are solved for such that :eq:`6.2-4` is satisfied. The card input
data required for each of these options is described below.

If the initial condition values are to be read from the input cards then
the steady state solution finder should be bypassed by setting the J1SIG
field on the 999 card to '0'. Then the value for a demand signal and for
the block signal of each integrator, lag compensator and lead-lag
compensator is taken from the F4SIG field on the associated signal
definition card.

If the initial condition values are to be calculated by the steady state
solution finder then the J1SIG field on the 999 card is set to '1'. An
initial guess for each demand signal and integrator initial condition
variable must be supplied on the F4SIG field of the signal definition
card. In addition the F3SIG field must be set to '0'. As a rule of
thumb, the initial guess should be within 15% of the actual steady state
value to ensure convergence. The lag compensator and lead-lag
compensator are special cases and do not require initial condition
information from the user.

Finally, if a mixed set of initial conditions is to be used, the card
data is identical to the case directly above, except for those demand
and integrator signals whose initial conditions are to be read from
cards. For these signals the F3SIG field is set to '1.0' and the F4SIG
field is set to the initial condition value desired.

.. _section-6.4.4:

Solution Accuracy
~~~~~~~~~~~~~~~~~

The control system modeling capability attempts to limit the solution
error that is introduced during the numerical integration of the control
equations over a subinterval. Recall the error is controlled by
repeatedly bisecting the subinterval time step into substeps until
integrating across the subinterval gives a relative error between
successive iterations that is less than the user-supplied value for
EPSCS. [The method was described in :numref:`section-6.3`]. The value of EPSCS is
input on a table card and occupies location 8001. A value of 0.01 is
suggested for most applications.

.. _section-6.4.5:

Solution Stability
~~~~~~~~~~~~~~~~~~

The modeling capability also attempts to maintain a stable solution to
the coupled control system and plant equations. The basic idea is that
stability is enhanced if the relative change in a control signal across
a subinterval is maintained less than the user supplied value for
EPSCPL. [The method was described in :numref:`section-6.3`]. The value of EPSCPL
is input on a table card and occupies location 8002. A value of 0.1 is
suggested for most applications.

.. _section-6.4.6:

Zero Crossing Parameter
~~~~~~~~~~~~~~~~~~~~~~~

The zero crossing parameter in :eq:`6.3-2` is intended to prevent
unnecessarily small time step size when a signal passes close to zero.
The situation we seek to avoid occurs when the zero crossing parameter
F5SIG is zero. Then the denominator in :eq:`6.3-2` is very small so that
the relative error is very large. Time step size is severely reduced
even though the absolute error in the signal may well be acceptably
small. The solution is to control absolute error at the zero crossing
and we do it through the relative error control mechanisms associated
with :eq:`6.3-2` by proper choice of a value for F5SIG.

The appropriate value of F5SIG is problem dependent and is selected by
the user for input to the code. The goal is to select a value that gives
a desired level of absolute error near the zero crossing yet does not
significantly impact the calculation of relative error away from the
zero crossing. To do so we note that the code controls integration error
using :eq:`6.3-2` so that on convergence the solution satisfies

.. math::
    :label: 6.4-1

	\left| S_{\text{m}}^{j + 1} - S_{\text{m,e}}^{j + 1} \right| = \text{EPSCS} \left( \left| S_{\text{m}}^{j} \right| + \text{F5SIG}\left( m \right) \right)

where the value of :math:`m` is restricted to those signals that are output by
dynamic blocks. Near the zero crossing :math:`S_{\text{m}}^{j}` will be
insignificant so that :eq:`6.4-1` is equivalently

.. math::
    :label: 6.4-2

	\text{F5SIG}\left( m \right) = \frac{\left| S_{\text{m}}^{j + 1} - S_{\text{m,e}}^{j + 1} \right|}{\text{EPSCS}} ~.

Note that the numerator is the absolute error in the solution at
convergence. We can arrange for the numerator to take on a specific
value by appropriately choosing the value of :math:`\text{F5SIG} \left( m \right)` once the value of
EPSCS has been selected. For example, suppose we want the absolute error
on convergence near the zero crossing to be :math:`S_{\text{m}}^{o} \times 10^{-4}`
where :math:`S_{\text{m}}^{o}` is the maximum magnitude signal :math:`m` is to take
on over all time. If, the sake of illustration, a value of :math:`10^{-2}`
was input for EPSCS, then we can achieve our absolute error objective by
calculating the value of :math:`\text{F5SIG} \left( m \right)` from :eq:`6.4-2`,

.. math::

	\text{F5SIG} \left( m \right) = \frac{S_{\text{m}}^{o} 10^{-4}}{10^{- 2}} = S_{\text{m}}^{o} 10^{-2}

Away from the zero crossing, the impact of :math:`\text{F5SIG} \left( m \right)` is insignificant.

Similarly, the value of :math:`\text{F5SIG} \left( m \right)` associated with a control signal should
be selected as follows. The time step is adjusted down if necessary so
that the largest relative change in a control signal is limited by
:eq:`6.3-3` to

.. math::
    :label: 6.4-3

	\left| S_{\text{m}}^{j + 1} - S_{\text{m,e}}^{j} \right| = \text{EPSCPL} \left( \left| S_{\text{m}}^{j} \right| + \text{F5SIG}\left( m \right) \right)

where the value of m is restricted to those signals that are control
signals. Near the zero crossing :math:`S_{m}^{j}`\ will be insignificant
so that :eq:`6.4-3` is equivalently

.. math::
    :label: 6.4-4

	\text{F5SIG} \left( m \right) = \frac{\left| S_{\text{m}}^{j + 1} - S_{\text{m}}^{j} \right|}{\text{EPSCPL}} ~.

Note that the numerator is the absolute change in the solution across
the time step. We can arrange for the numerator to take on a specific
value by appropriately choosing the value of :math:`\text{F5SIG} \left( m \right)` once the value of
EPSCPL has been selected. For example, suppose we want the absolute
change in the control signal near the zero crossing to be as large as
:math:`S_{\text{m}}^{o} \times 10^{- 3}` before time step size is reduced. If, for
the sake of illustration, a value of :math:`10^{-1}` was input for EPSCPL,
then the absolute change objective will be met if :math:`\text{F5SIG} \left( m \right)` is calculated
from :eq:`6.4-4`,

.. math::

	\text{F5SIG}\left( m \right) = \frac{S_{\text{m}}^{o} 10^{- 3}}{10^{- 1}} = S_{\text{m}}^{o} 10^{- 2}

Away from the zero crossing, the impact of :math:`\text{F5SIG} \left( m \right)` on the control of
fractional change is insignificant.