.. _conditions-kinematic:

*****************************
Kinematic Boundary Conditions
*****************************

The various kinematic boundary conditions available in Sierra/SM are described in this section. The kinematic boundary conditions are nested inside the region scope.

Kinematic constraints can potentially be in conflict with other constraints. Refer to :ref:`Appendix D <appendix-constraints>` for information on how conflicting constraints are handled.

Fixed Displacement
==================

.. code-block:: sierrainput

   BEGIN FIXED DISPLACEMENT
     #
     # node set commands
     NODE SET|NODESET = <string list>nodelist_names
     SURFACE|SIDESET|SIDE SET = <string list>surface_names
     BLOCK = <string list>block_names
     ASSEMBLY = <string list>assembly_names
     RIGID BODY = <string list>rigid_body_names
     INCLUDE ALL BLOCKS
     REMOVE NODE SET = <string list>nodelist_names
     REMOVE SURFACE = <string list>surface_names
     REMOVE BLOCK = <string list>block_names
     #
     # direction commands
     COMPONENT = <string>X|Y|Z | COMPONENTS = <string>X/Y/Z |
       DIRECTION = <string>dirName
     #
     # additional commands
     ACTIVE PERIODS = <string list>period_names
     INACTIVE PERIODS = <string list>period_names
   END [FIXED DISPLACEMENT]

The ``FIXED DISPLACEMENT`` command block fixes displacement components (X, Y, Z, or some combination thereof, or some other direction) for a set of nodes to be zero. This command block contains two groups of commands---node set and component. Each of these command groups is basically independent of the other. In addition to the command lines in the two command groups, there are two additional command lines: ``ACTIVE PERIODS`` and ``INACTIVE PERIODS``. These are used to activate or deactivate this kinematic boundary condition for certain time periods.

It's important to note that the displacement field refers to the difference between model coordinates (reference coordinates) and current coordinates.  Thus, a fixed displacement implies that the node never moves from the original position.  A fixed displacement boundary condition cannot be used to "freeze" a node in a particular position after it has already been displaced.  Any attempt to "freeze" a node (e.g. using ``ACTIVE PERIODS``, for example) would result in the node snapping back to its original position in a single time step.

For rigid bodies, any kinematic boundary condition is applied directly to the rigid body reference node. The kinematics for the nodes attached to the  rigid body are applied via the rigid body constraint conditions. Since rigid bodies are defined using element blocks, only the ``BLOCK`` or ``RIGID BODY`` commands may be used to specify fixed displacement conditions on rigid bodies.

.. warning::

   Note the fixed displacement command sets the displacement of a node to ZERO. To instead keep the current nodal displacement, a zero velocity boundary condition should be used.

Following are descriptions of the different command groups.

Node Set Commands
-----------------

The ``node set commands`` portion of the ``FIXED DISPLACEMENT`` command block specifies the nodes associated with the boundary condition. This portion of the command block can include some combination of the following command lines:

.. code-block:: sierrainput

   NODE SET|NODESET = <string list>nodelist_names
   SURFACE|SIDESET|SIDE SET = <string list>surface_names
   BLOCK = <string list>block_names
   ASSEMBLY = <string list>assembly_names
   RIGID BODY = <string list>rigid_body_names
   INCLUDE ALL BLOCKS
   REMOVE NODE SET = <string list>nodelist_names
   REMOVE SURFACE = <string list>surface_names
   REMOVE BLOCK = <string list>block_names

These command lines, taken collectively, constitute a set of Boolean operators for constructing a set of nodes. See :numref:`conditions-general-entity` for more information about the use of these command lines for creating a set of nodes used by the boundary condition. There must be at least one ``NODE SET|NODESET``, ``SURFACE``, ``BLOCK``, ``RIGID BODY``, or ``INCLUDE ALL BLOCKS`` command line in the command block. Assemblies may  contain blocks, surfaces, nodesets, or assemblies of these.

Specification Commands
----------------------

There are two component specification commands available in the ``FIXED DISPLACEMENT`` command block:

.. code-block:: sierrainput

   COMPONENT = X|Y|Z | COMPONENTS = X/Y/Z | 
      DIRECTION = <string>dirName

A single displacement component may be set with the ``COMPONENT`` command line. A single direction of constraint can be set with the ``DIRECTION`` command. Multiple components can be constrained simultaneously with the ``COMPONENTS``. One and only one ``COMPONENT``, ``DIRECTION``, or ``COMPONENTS`` command must be specified in the block. The ``COMPONENTS`` command can constraint multiple components simultaneously, for example

.. code-block:: sierrainput

   COMPONENTS = X Y 

Additional Commands
-------------------

The ``ACTIVE PERIODS`` and ``INACTIVE PERIODS`` command lines can optionally appear in the ``FIXED DISPLACEMENT`` command block:

.. code-block:: sierrainput

   ACTIVE PERIODS = <string list>period_names
   INACTIVE PERIODS = <string list>period_names

These command lines determine when the boundary condition is active. See :numref:`commands-functionality` for more information about these optional command lines.

.. warning::

   If ``FIXED DISPLACEMENT`` becomes active the displacement is returned to zero. If the intention is to maintain the current displacement when activated ``PRESCRIBED VELOCITY`` with a value of zero should be used.

.. _bou-pdis:

Prescribed Displacement
=======================

.. code-block:: sierrainput

     BEGIN PRESCRIBED DISPLACEMENT
       #
       # node set commands
       NODE SET|NODESET = <string list>nodelist_names
       SURFACE|SIDESET|SIDE SET = <string list>surface_names
       BLOCK = <string list>block_names
       ASSEMBLY = <string list>assembly_names
       RIGID BODY = <string list>rigid_body_names
       INCLUDE ALL BLOCKS
       REMOVE NODE SET = <string list>nodelist_names
       REMOVE SURFACE = <string list>surface_names
       REMOVE BLOCK = <string list>block_names
       #
       # specification commands
       DIRECTION = <string>defined_direction |
         COMPONENT = <string>X|Y|Z |  COMPONENTS = <string>X/Y/Z |
         CYLINDRICAL AXIS = <string>defined_axis |
         RADIAL AXIS = <string>defined_axis
       FUNCTION = <string>function_name
       #
       # user subroutine commands
       NODE SET SUBROUTINE = <string>subroutine_name
       SUBROUTINE DEBUGGING OFF | SUBROUTINE DEBUGGING ON
       SUBROUTINE REAL PARAMETER: <string>param_name
         = <real>param_value
       SUBROUTINE INTEGER PARAMETER: <string>param_name
         = <integer>param_value
       SUBROUTINE STRING PARAMETER: <string>param_name
         = <string>param_value     
       # 
       # external database commands
       READ VARIABLE = <string>var_name
       COPY VARIABLE = <string>var_name [FROM MODEL <string>model_name]
       TIME = <real>time|FIRST|LAST
       #
       # additional commands
       SCALE FACTOR = <real>scale_factor(1.0)
       ACTIVE PERIODS = <string list>period_names
       INACTIVE PERIODS = <string list>period_names
     END [PRESCRIBED DISPLACEMENT]

The ``PRESCRIBED DISPLACEMENT`` command block prescribes a displacement field for a given set of nodes. The displacement field associates a vector giving the magnitude and direction of the displacement with each node in the set of nodes.  It's important to note that the displacement field refers to the difference between model coordinates and current coordinates.  Thus, a prescribed displacement always refers to the total displacement from the undeformed configuration.  The displacement field may vary over time and space. If the displacement field has only a time-varying magnitude and uses one of four methods for setting direction, the specification commands in the above command block can be used to specify the displacement field. If the displacement field is more complex, a user subroutine specifies the displacement field. The displacement field can also be read from an external mesh database. In a given boundary condition command block, commands from only one of the command groups (specification commands, user subroutine commands, or external database commands) may be used.

For rigid bodies, any kinematic boundary condition is applied directly to the rigid body reference node. The kinematics for the mesh nodes attached to the  rigid body are applied via the rigid body constraint conditions. Since rigid bodies are defined using element blocks, only the ``BLOCK`` or  ``RIGID BODY`` command lines may be used to specify prescribed displacement conditions on rigid bodies.

The ``PRESCRIBED DISPLACEMENT`` command block contains four groups of commands---node set, function, user subroutine, and external database. Each of these command groups is basically independent of the others. In addition to the command lines in the four command groups, there are three additional command lines: ``SCALE FACTOR``, ``ACTIVE PERIODS``, and ``INACTIVE PERIODS``. The ``SCALE FACTOR`` command line can be used in conjunction with the specification commands, the user subroutine commands, or the external database command. The ``ACTIVE PERIODS`` and ``INACTIVE PERIODS`` command lines are used to activate or deactivate this kinematic boundary condition for certain time periods. Following are descriptions of the different command groups and the ``SCALE FACTOR`` and ``ACTIVE PERIODS`` command lines. 

Node Set Commands
-----------------

The ``node set commands`` portion of the ``PRESCRIBED DISPLACEMENT`` command  block defines a set of nodes associated with the prescribed displacement  field and can include some combination of the following command lines:

.. code-block:: sierrainput

   NODE SET|NODESET = <string list>nodelist_names
   SURFACE|SIDESET|SIDE SET = <string list>surface_names
   BLOCK = <string list>block_names
   ASSEMBLY = <string list>assembly_names
   RIGID BODY = <string list>rigid_body_names
   INCLUDE ALL BLOCKS
   REMOVE NODE SET = <string list>nodelist_names
   REMOVE SURFACE = <string list>surface_names
   REMOVE BLOCK = <string list>block_names

These command lines, taken collectively, constitute a set of Boolean  operators for constructing a set of nodes. See :numref:`conditions-general-entity` for more information  about the use of these command lines for creating a set of nodes used by the  boundary condition. There must be at least one ``NODE SET|NODESET``, ``SURFACE``, ``BLOCK``,  ``ASSEMBLY``, ``RIGID BODY``, or ``INCLUDE ALL BLOCKS`` command line in the command block. Assemblies may contain blocks, surfaces, nodesets, or assemblies of these.

.. _conditions-kinematic-prescribeddisplacement-specification:

Specification Commands
----------------------

If the specification commands are used, the displacement vector at any given time is  the same for all nodes in the node set associated with the particular  ``PRESCRIBED DISPLACEMENT`` command block.

Following are the command lines used to specify the prescribed displacement with a direction and a function:

.. code-block:: sierrainput

   DIRECTION = <string>defined_direction |
     COMPONENT = <string>X|Y|Z |
     CYLINDRICAL AXIS = <string>defined_axis |
     RADIAL AXIS = <string>defined_axis
   FUNCTION = <string>function_name

The displacement can be specified along an arbitrary user-defined direction, along a component direction (X, Y, or Z), along the azimuthal direction in a cylindrical coordinate system (defined in reference to an axis), or along a radial direction (defined in reference to an axis). Only one of these options is allowed per command block. The displacement is prescribed only in the specified direction. A prescribed displacement boundary condition does not influence the motion in directions orthogonal to the prescribed direction.

- The ``DIRECTION`` command line is used to prescribe displacement in an arbitrary user-defined direction. The name in the string ``defined_direction`` is a reference to a direction, which is defined using the ``DEFINE DIRECTION`` command block within the SIERRA scope.
- The ``COMPONENT`` command line specifies that the prescribed displacement vector lies along one of the component directions. The ``COMPONENT`` command line is a shortcut to an internally defined direction vector; for example, component ``x`` corresponds to using direction vector (1, 0, 0).
- The ``CYLINDRICAL AXIS`` command line specifies that the prescribed displacement is to be applied in the azimuthal direction of a cylindrical coordinate system. The string ``defined_axis`` refers to the name of the :math:`\tilde{Z}` axis of the cylindrical coordinate system, and which is defined via a ``DEFINE AXIS`` command block in the SIERRA scope. The displacement is prescribed as a rotation in radians about that axis. Nodes with this type of boundary condition are free to move in the radial and longitudinal directions of the cylindrical coordinate system. Restraints can be placed on the node set in those directions if desired by applying separate kinematic boundary conditions that contain ``RADIAL AXIS`` or ``DIRECTION`` commands that refer to the same axis. Note that this type of boundary condition only affects translational degrees of freedom; it does not apply a rotation to nodes that have rotational degrees of freedom.

  .. admonition:: Known Issue
   :class: admonition warning

   If a prescribed displacement with the ``CYLINDRICAL AXIS`` option is applied to nodes that fall on the axis, it will have no effect. Separate boundary conditions should be applied to those nodes to fix them in the plane normal to the axis.

- The ``RADIAL AXIS`` command line specifies that the prescribed displacement is to be applied in the radial direction of a cylindrical coordinate system. The string ``defined_axis`` refers to the name of the :math:`\tilde{Z}` axis of the cylindrical coordinate system, and which is defined via a ``DEFINE AXIS`` command block in the SIERRA scope. The prescribed displacement vector lies along the radial line drawn from that axis to the node.

The magnitude of the displacement is specified by the ``FUNCTION`` command line. This references a ``function_name`` (defined in the SIERRA scope using a ``FUNCTION`` command block) that specifies the magnitude of the displacement vector as a function of time. The magnitude can be scaled by use of the ``SCALE FACTOR`` command line described in :numref:`bou-pdisadd`.

User Subroutine Commands
------------------------

If the user subroutine option is used, the displacement vector may vary spatially at any given time for each of the nodes in the node set associated with the particular ``PRESCRIBED DISPLACEMENT`` command block. The user subroutine option allows for a more complex description of the displacement field than do the specification commands, but also requires writing a user subroutine to implement this capability. The user subroutine will be used to define a displacement direction and a magnitude for every node to which the boundary condition will be applied. The subroutine will be called by Sierra/SM at the appropriate time to generate the displacement field.

Following are the command lines related to the user subroutine option:

.. code-block:: sierrainput

   NODE SET SUBROUTINE = <string>subroutine_name
   SUBROUTINE DEBUGGING OFF | SUBROUTINE DEBUGGING ON
   SUBROUTINE REAL PARAMETER: <string>param_name
     = <real>param_value
   SUBROUTINE INTEGER PARAMETER: <string>param_name
     = <integer>param_value
   SUBROUTINE STRING PARAMETER: <string>param_name
     = <string>param_value   

The user subroutine option is invoked by using the ``NODE SET SUBROUTINE`` command line. The string ``subroutine_name`` is the name of a FORTRAN subroutine that is written by the user.

Following the ``NODE SET SUBROUTINE`` command line are other command lines that may be used to implement the user subroutine option. These command lines are described in  :numref:`use-comlines` and consist of ``SUBROUTINE DEBUGGING OFF``, ``SUBROUTINE DEBUGGING ON``,  ``SUBROUTINE REAL PARAMETER``, ``SUBROUTINE INTEGER PARAMETER``, and ``SUBROUTINE  STRING PARAMETER``. Examples of using these command lines are provided  throughout :numref:`subroutines`.

The magnitude set in the user subroutine can be scaled by use of the ``SCALE FACTOR`` command line, as described in :numref:`bou-pdisadd`.

See :numref:`conditions-kinematic-subroutine` and :numref:`subroutines` for more details on implementing the user subroutine option. 

External Mesh Database Commands
-------------------------------

If the external database option is used, the displacement vector (or specified components of the vector) is read from an external mesh database. The displacements are read from a finite element model defined via the ``FINITE ELEMENT MODEL`` command block described in :numref:`elements-fem`. The finite element model can either be the model used by the region for its mesh definition as specified with the ``USE FINITE ELEMENT MODEL`` command (see :numref:`commands-fem`), or it can be a different (but compatible) model. The following command lines control the use of an external mesh database to prescribe the displacement:

.. code-block:: sierrainput

   READ VARIABLE = <string>var_name
   COPY VARIABLE = <string>var_name [FROM MODEL <string>model_name]
     MAP_BY_PROXIMITY|MAP_BY_ID(MAP_BY_PROXIMITY)
   TIME = <real>time |FIRST|LAST

Specifying multiple components using external mesh database commands is not currently implemented. To read all components from an external mesh database, please specify three separate prescribed displacement blocks and specify the three different components

See :numref:`conditions-variable-extmesh` for more details.

.. _bou-pdisadd:

Additional Commands
-------------------

These command lines in the ``PRESCRIBED DISPLACEMENT`` command block provide  additional options for the boundary condition:

.. code-block:: sierrainput

   SCALE FACTOR = <real>scale_factor(1.0)
   ACTIVE PERIODS = <string list>period_names
   INACTIVE PERIODS = <string list>period_names

The ``SCALE FACTOR`` command line is used to apply an additional scaling factor, which is constant in both time and space, to all vector magnitude values of the field defined by the specification commands or the user subroutine. For example, if the magnitude of the displacement in a time history function is given as 1.5 from time 1.0 to time 2.0 and the scale factor is 0.5, then the magnitude of the displacement from time 1.0 to 2.0 is 0.75. The default value for the scale factor is 1.0.

The ``ACTIVE PERIODS`` and ``INACTIVE PERIODS`` command lines determine when the boundary condition is active. See :numref:`commands-functionality` for more information about these command lines.

.. _bou-pvel:

Prescribed Velocity
===================

.. code-block:: sierrainput

   BEGIN PRESCRIBED VELOCITY
     #
     # node set commands
     NODE SET|NODESET = <string list>nodelist_names
     SURFACE|SIDESET|SIDE SET = <string list>surface_names
     BLOCK = <string list>block_names
     ASSEMBLY = <string list>assembly_names
     RIGID BODY = <string list>rigid_body_names
     INCLUDE ALL BLOCKS
     REMOVE NODE SET = <string list>nodelist_names
     REMOVE SURFACE = <string list>surface_names
     REMOVE BLOCK = <string list>block_names
     #
     # specification commands
     DIRECTION = <string>defined_direction |
       COMPONENT = <string>X|Y|Z | COMPONENTS = <string>X/Y/Z |
       CYLINDRICAL AXIS = <string>defined_axis |
       RADIAL AXIS = <string>defined_axis
     FUNCTION = <string>function_name
     #
     # user subroutine commands
     NODE SET SUBROUTINE = <string>subroutine_name
     SUBROUTINE DEBUGGING OFF | SUBROUTINE DEBUGGING ON
     SUBROUTINE REAL PARAMETER: <string>param_name
       = <real>param_value
     SUBROUTINE INTEGER PARAMETER: <string>param_name
       = <integer>param_value
     SUBROUTINE STRING PARAMETER: <string>param_name
       = <string>param_value     
     #
     # external database commands
     READ VARIABLE = <string>var_name
     COPY VARIABLE = <string>var_name [FROM MODEL <string>model_name]
       MAP_BY_PROXIMITY|MAP_BY_ID(MAP_BY_PROXIMITY)
     TIME = <real>time|FIRST|LAST
     #
     # additional commands
     SCALE FACTOR = <real>scale_factor(1.0)
     ACTIVE PERIODS = <string list>period_names
     INACTIVE PERIODS = <string list>period_names
   END [PRESCRIBED VELOCITY]

The ``PRESCRIBED VELOCITY`` command block prescribes a velocity field for a given set of nodes. The velocity field associates a vector giving the magnitude and direction of the velocity with each node in the node set. The velocity field may vary over time and space. If the velocity field has only a time-varying magnitude and uses one of four methods for setting direction, the specification commands in the above command block can be used to specify the velocity field. If the velocity field is more complex, a user subroutine specifies the velocity field. The velocity field can also be read from an external mesh database. In a given boundary condition command block, commands from only one of the command groups (specification commands, user subroutine commands, or external database commands) may be used.

For rigid bodies, any kinematic boundary condition is applied directly to the rigid body reference node. The kinematics for the mesh nodes attached to the  rigid body are applied via the rigid body constraint conditions. Since rigid bodies are defined using element blocks, only the ``BLOCK`` and ``RIGID BODY`` command lines may be used to specify prescribed velocity conditions on rigid bodies.

The ``PRESCRIBED VELOCITY`` command block contains four groups of commands---node set, function, user subroutine, and external database. Each of these command groups is basically independent of the others. In addition to the command lines in the four command groups, there are three additional command lines: ``SCALE FACTOR``, ``ACTIVE PERIODS``, and ``INACTIVE PERIODS``. The ``SCALE FACTOR`` command line can be used in conjunction with either the specification commands or the user subroutine commands. The ``ACTIVE PERIODS`` and ``INACTIVE PERIODS`` command lines are used to activate or deactivate this kinematic boundary condition for certain time periods. Following are descriptions of the different command groups.

Node Set Commands
-----------------

The ``node set commands`` portion of the ``PRESCRIBED VELOCITY`` command  block defines a set of nodes associated with the prescribed velocity field  and can include some combination of the following command lines:

.. code-block:: sierrainput

   NODE SET|NODESET = <string list>nodelist_names
   SURFACE|SIDESET|SIDE SET = <string list>surface_names
   BLOCK = <string list>block_names
   ASSEMBLY = <string list>assembly_names
   RIGID BODY = <string list>rigid_body_names
   INCLUDE ALL BLOCKS
   REMOVE NODE SET = <string list>nodelist_names
   REMOVE SURFACE = <string list>surface_names
   REMOVE BLOCK = <string list>block_names

These command lines, taken collectively, constitute a set of Boolean  operators for constructing a set of nodes. See :numref:`conditions-general-entity` for more information  about the use of these command lines for creating a set of nodes used by the  boundary condition. There must be at least one ``NODE SET|NODESET``, ``SURFACE``, ``BLOCK``,  ``ASSEMBLY``, ``RIGID BODY``, or ``INCLUDE ALL BLOCKS`` command line in the command block. Assemblies may contain blocks, surfaces, nodesets, or assemblies of these.

.. _conditions-kinematic-prescribedvelocity-specification:

Specification Commands
----------------------

If the specification commands are used, the velocity vector at any given time is the  same for all nodes in the node set associated with the particular ``PRESCRIBED  VELOCITY`` command block.

Following are the command lines used to specify the prescribed velocity with a direction and a function:

.. code-block:: sierrainput

   DIRECTION = <string>defined_direction |
     COMPONENT = <string>X|Y|Z |
     CYLINDRICAL AXIS = <string>defined_axis |
     RADIAL AXIS = <string>defined_axis
   FUNCTION = <string>function_name

The velocity can be specified along an arbitrary user-defined direction, along a component direction (X, Y, or Z), along the azimuthal direction in a cylindrical coordinate system (defined in reference to an axis), or along a radial direction (defined in reference to an axis). Only one of these options is allowed per command block. The velocity is prescribed only in the specified direction. A prescribed velocity boundary condition does not influence the motion in directions orthogonal to the prescribed direction.

- The ``DIRECTION`` command line is used to prescribe velocity in an arbitrary user-defined direction. The name in the string ``defined_direction`` is a reference to a direction, which is defined using the ``DEFINE DIRECTION`` command block within the SIERRA scope.

- The ``COMPONENT`` command line specifies that the prescribed velocity vector lies along one of the component directions. The ``COMPONENT`` command line is a shortcut to an internally defined direction vector; for example, component ``x`` corresponds to using direction vector (1, 0, 0).

- The ``CYLINDRICAL AXIS`` command line specifies that the prescribed velocity is to be applied in the azimuthal direction of a cylindrical coordinate system. The string ``defined_axis`` refers to the name of the axis of the cylindrical coordinate system, and which is defined via a ``DEFINE AXIS`` command block in the SIERRA scope. The velocity is prescribed as a rotation in radians about the axis. Nodes with this type of boundary condition are free to move in the radial and height directions in the cylindrical coordinate system. Restraints can be placed on the node set in those directions if desired by applying separate kinematic boundary conditions that contain ``RADIAL AXIS`` or ``DIRECTION`` commands that refer to the same axis. Note that this type of boundary condition is not a rotational boundary condition; it only affects translational degrees of freedom.

  .. admonition:: Known Issue
   :class: admonition warning

   If a prescribed velocity with the ``CYLINDRICAL AXIS`` option is applied to nodes that fall on the axis, it will have no effect. Separate boundary conditions should be applied to those nodes to fix them in the plane normal to the axis.

- The ``RADIAL AXIS`` command line requires an axis definition that appears in the SIERRA scope. The string ``defined_axis`` uses an ``axis_name`` that is defined in the SIERRA scope (via a ``DEFINE   AXIS`` command line). For this option, a radial line is drawn from a node to the radial axis. The velocity vector lies along this radial line from the node to the radial axis.

The magnitude of the velocity is specified by the ``FUNCTION`` command line. This references a ``function_name`` (defined in the SIERRA scope using a ``FUNCTION`` command block) that specifies the magnitude of the velocity vector as a function of time. The magnitude can be scaled by use of the ``SCALE FACTOR`` command line described in :numref:`bou-pveladd`.

User Subroutine Commands
------------------------

If the user subroutine option is used, the velocity vector may vary spatially at any given time for each of the nodes in the node set associated with the particular ``PRESCRIBED VELOCITY`` command block. The user subroutine option allows for a more complex description of the velocity field than do the specification commands, but also requires writing a user subroutine to implement this capability. The user subroutine will be used to define a velocity direction and a magnitude for every node to which the boundary condition will be applied. The subroutine will be called by Sierra/SM at the appropriate time to generate the velocity field.

Following are the command lines related to the user subroutine option:

.. code-block:: sierrainput

   NODE SET SUBROUTINE = <string>subroutine_name
   SUBROUTINE DEBUGGING OFF | SUBROUTINE DEBUGGING ON
   SUBROUTINE REAL PARAMETER: <string>param_name
     = <real>param_value
   SUBROUTINE INTEGER PARAMETER: <string>param_name
     = <integer>param_value
   SUBROUTINE STRING PARAMETER: <string>param_name
     = <string>param_value   

The user subroutine option is invoked by using the ``NODE SET SUBROUTINE`` command line. The string ``subroutine_name`` is the name of a FORTRAN subroutine that is written by the user. 

Following the ``NODE SET SUBROUTINE`` command line are other command lines that may be used to implement the user subroutine option. These command lines are described in :numref:`use-comlines` and  consist of ``SUBROUTINE DEBUGGING OFF``, ``SUBROUTINE DEBUGGING ON``, ``SUBROUTINE REAL PARAMETER``, ``SUBROUTINE INTEGER PARAMETER``, and ``SUBROUTINE STRING PARAMETER``. Examples of using these command lines are provided throughout :numref:`subroutines`.

The magnitude set in the user subroutine can be scaled by use of the ``SCALE FACTOR`` command line, as described in :numref:`bou-pveladd`.

External Mesh Database Commands
-------------------------------

If the external database option is used, the velocity vector (or specified components of the vector) is read from an external mesh database. The velocities are read from a finite element model defined via the ``FINITE ELEMENT MODEL`` command block described in :numref:`elements-fem`. The finite element model can either be the model used by the region for its mesh definition as specified with the ``USE FINITE ELEMENT MODEL`` command (see :numref:`commands-fem`), or it can be a different (but compatible) model. The following command lines control the use of an external mesh database to prescribe the velocity:

.. code-block:: sierrainput

   READ VARIABLE = <string>var_name
   COPY VARIABLE = <string>var_name [FROM MODEL <string>model_name]
     MAP_BY_PROXIMITY|MAP_BY_ID(MAP_BY_PROXIMITY)
   TIME = <real>time|FIRST|LAST

See :numref:`conditions-variable-extmesh` for more details.

.. _bou-pveladd:

Additional Commands
-------------------

These command lines in the ``PRESCRIBED VELOCITY`` command block provide additional options for the boundary condition:

.. code-block:: sierrainput

   SCALE FACTOR = <real>scale_factor(1.0)
   ACTIVE PERIODS = <string list>period_names
   INACTIVE PERIODS = <string list>period_names

The ``SCALE FACTOR`` command line is used to apply an additional scaling factor, which is constant in both time and space, to all vector magnitude values of the field defined by the specification commands or the user subroutine. For example, if the magnitude of the velocity in a time history function is given as 1.5 from time 1.0 to time 2.0 and the scale factor is 0.5, then the magnitude of the velocity from time 1.0 to 2.0 is 0.75. The default value for the scale factor is 1.0.

The ``ACTIVE PERIODS`` and ``INACTIVE PERIODS`` command lines determine when the boundary condition is active. See :numref:`commands-functionality` for more information about these command lines.

Prescribed Acceleration
=======================

.. code-block:: sierrainput

   BEGIN PRESCRIBED ACCELERATION
     #
     # node set commands
     NODE SET|NODESET = <string list>nodelist_names
     SURFACE|SIDESET|SIDE SET = <string list>surface_names
     BLOCK = <string list>block_names
     ASSEMBLY = <string list>assembly_names
     RIGID BODY = <string list>rigid_body_names
     INCLUDE ALL BLOCKS
     REMOVE NODE SET = <string list>nodelist_names
     REMOVE SURFACE = <string list>surface_names
     REMOVE BLOCK = <string list>block_names
     #
     # specification commands
     DIRECTION = <string>defined_direction |
       COMPONENT = <string>X|Y|Z | COMPONENTS = <string>X/Y/Z |
     FUNCTION = <string>function_name
     #
     # user subroutine commands
     NODE SET SUBROUTINE = <string>subroutine_name
     SUBROUTINE DEBUGGING OFF | SUBROUTINE DEBUGGING ON
     SUBROUTINE REAL PARAMETER: <string>param_name
       = <real>param_value
     SUBROUTINE INTEGER PARAMETER: <string>param_name
       = <integer>param_value
     SUBROUTINE STRING PARAMETER: <string>param_name
       = <string>param_value
     #
     # external database commands
     READ VARIABLE = <string>var_name
     COPY VARIABLE = <string>var_name [FROM MODEL <string>model_name]
       MAP_BY_PROXIMITY|MAP_BY_ID(MAP_BY_PROXIMITY)
     TIME = <real>time|FIRST|LAST
     #
     # additional commands
     SCALE FACTOR = <real>scale_factor(1.0)
     ACTIVE PERIODS = <string list>period_names
     INACTIVE PERIODS = <string list>period_names
   END [PRESCRIBED ACCELERATION]

The ``PRESCRIBED ACCELERATION`` command block prescribes an acceleration field for a given set of nodes. The acceleration field associates a vector giving the magnitude and direction of the acceleration with each node in the node set. The acceleration field may vary over time and space. If the acceleration field has only a time-varying component, the specification commands in the above command block can be used to specify the acceleration field. If the acceleration field has both time-varying and spatially varying components, a user subroutine specifies the acceleration field. The acceleration field can also be read from an external mesh database. In a given boundary condition command block, commands from only one of the command groups (specification commands, user subroutine commands, or external database commands) may be used.

For rigid bodies, any kinematic boundary condition is applied directly to the rigid body reference node. The kinematics for the mesh nodes attached to the rigid body are applied via the rigid body constraint conditions. Since rigid bodies are defined using element blocks, only the ``BLOCK`` and ``RIGID BODY`` commands may be used to specify prescribed acceleration conditions on rigid bodies.

The ``PRESCRIBED ACCELERATION`` command block contains four groups of commands: node set, function, user subroutine, and external database. Each of these command groups is independent of the others. In addition to the command lines in the four command groups, there are three additional command lines: ``SCALE FACTOR``, ``ACTIVE PERIODS``, and ``INACTIVE PERIODS``. The ``SCALE FACTOR`` command line can be used in conjunction with either the specification commands or the user subroutine commands. The ``ACTIVE PERIODS`` and ``INACTIVE PERIODS`` command lines are used to activate or deactivate this kinematic boundary condition for certain time periods. Following are descriptions of the different command groups.

.. _bou-paccnode:

Node Set Commands
-----------------

The ``node set commands`` portion of the ``PRESCRIBED ACCELERATION`` command 
block defines a set of nodes associated with the prescribed acceleration 
field and can include some combination of the following command lines:

.. code-block:: sierrainput

   NODE SET|NODESET = <string list>nodelist_names
   SURFACE|SIDESET|SIDE SET = <string list>surface_names
   BLOCK = <string list>block_names
   ASSEMBLY = <string list>assembly_names
   RIGID BODY = <string list>rigid_body_names
   INCLUDE ALL BLOCKS
   REMOVE NODE SET = <string list>nodelist_names
   REMOVE SURFACE = <string list>surface_names
   REMOVE BLOCK = <string list>block_names

These command lines, taken collectively, constitute a set of Boolean operators for constructing a set of nodes. See :numref:`conditions-general-entity` for more information about the use of these command lines for creating a set of nodes used by the boundary condition. There must be at least one ``NODE SET|NODESET``, ``SURFACE``, ``BLOCK``, ``ASSEMBLY``, ``RIGID BODY``, or ``INCLUDE ALL BLOCKS`` command line in the command block. Assemblies may contain blocks, surfaces, nodesets, or assemblies  of these.

.. _bou-paccspec:

Specification Commands
----------------------

If the specification commands are used, the acceleration vector at any given time is  the same for all nodes in the node set associated with the particular  ``PRESCRIBED ACCELERATION`` command block. The direction of the acceleration  vector is constant for all time; the magnitude of the acceleration vector  may vary with time, however.

Following are the command lines used to specify the prescribed acceleration with a direction and a function:

.. code-block:: sierrainput

   DIRECTION = <string>defined_direction |
     COMPONENT = <string>X|Y|Z
   FUNCTION = <string>function_name

The acceleration can be specified along an arbitrary user-defined direction or along a component direction (X, Y, or Z). Only one of these options is allowed per command block. The acceleration is prescribed only in the specified direction. A prescribed acceleration boundary condition does not influence the motion in directions orthogonal to the prescribed direction.

- The ``DIRECTION`` command line is used to prescribe acceleration in an arbitrary user-defined direction. The name in the string ``defined_direction`` is a reference to a direction, which is defined using the ``DEFINE DIRECTION`` command block within the SIERRA scope.

- The ``COMPONENT`` command line specifies that the prescribed acceleration vector lies along one of the component directions. The ``COMPONENT`` command line is a shortcut to an internally defined direction vector; for example, component ``x`` corresponds to using direction vector (1, 0, 0).

The magnitude of the acceleration is specified by the ``FUNCTION`` command line. This references a ``function_name`` (defined in the SIERRA scope using a ``FUNCTION`` command block) that specifies the magnitude of the acceleration vector as a function of time. The magnitude can be scaled by use of the ``SCALE FACTOR`` command line described in :numref:`bou-paccadd`.

.. _bou-paccsub:

User Subroutine Commands
------------------------

If the user subroutine option is used, the acceleration vector may vary spatially at any given time for each of the nodes in the node set associated with the particular ``PRESCRIBED ACCELERATION`` command block. The user subroutine option allows for a more complex description of the acceleration field than do the specification commands, but also requires writing a user subroutine to implement this capability. The user subroutine will be used to define an acceleration direction and a magnitude for every node to which the boundary condition will be applied. The subroutine will be called by Sierra/SM at the appropriate time to generate the acceleration field.

Following are the command lines related to the user subroutine option:

.. code-block:: sierrainput

   NODE SET SUBROUTINE = <string>subroutine_name
   SUBROUTINE DEBUGGING OFF | SUBROUTINE DEBUGGING ON
   SUBROUTINE REAL PARAMETER: <string>param_name
     = <real>param_value
   SUBROUTINE INTEGER PARAMETER: <string>param_name
     = <integer>param_value
   SUBROUTINE STRING PARAMETER: <string>param_name
     = <string>param_value

The user subroutine option is invoked by using the ``NODE SET SUBROUTINE``  command line. The string ``subroutine_name`` is the name of a FORTRAN  subroutine that is written by the user. 

Following the ``NODE SET SUBROUTINE`` command line are other command lines that may be used to implement the user subroutine option. These command lines are described in  :numref:`use-comlines` and consist of ``SUBROUTINE DEBUGGING OFF``, ``SUBROUTINE DEBUGGING ON``, ``SUBROUTINE REAL PARAMETER``, ``SUBROUTINE INTEGER PARAMETER``, and ``SUBROUTINE STRING PARAMETER``. Examples of using these command lines are provided throughout :numref:`subroutines`.

The magnitude set in the user subroutine can be scaled by use of the ``SCALE FACTOR`` command line, as described in :numref:`bou-paccadd`.

See :numref:`conditions-kinematic-subroutine` and :numref:`subroutines` for more details on implementing the user subroutine option. 

.. _bou-paccdb:

External Mesh Database Commands
-------------------------------

If the external database option is used, the acceleration vector (or specified components of the vector) is read from an external mesh database. The accelerations are read from a finite element model defined via the ``FINITE ELEMENT MODEL`` command block described in :numref:`elements-fem`. The finite element model can either be the model used by the region for its mesh definition as specified with the ``USE FINITE ELEMENT MODEL`` command (see :numref:`commands-fem`), or it can be a different (but compatible) model. The following command lines control the use of an external mesh database to prescribe the acceleration:

.. code-block:: sierrainput

   READ VARIABLE = <string>var_name
   COPY VARIABLE = <string>var_name [FROM MODEL <string>model_name]
     MAP_BY_PROXIMITY|MAP_BY_ID(MAP_BY_PROXIMITY)
   TIME = <real>time|FIRST|LAST

See :numref:`conditions-variable-extmesh` for more details.

.. _bou-paccadd:

Additional Commands
-------------------

These command lines in the ``PRESCRIBED ACCELERATION`` command block provide  additional options for the boundary condition:

.. code-block:: sierrainput

   SCALE FACTOR = <real>scale_factor(1.0)
   ACTIVE PERIODS = <string list>period_names
   INACTIVE PERIODS = <string list>period_names

The ``SCALE FACTOR`` command line is used to apply an additional scaling factor,  which is constant in both time and space, to all vector magnitude values of  the field defined by the specification commands or the user subroutine. For  example, if the magnitude of the acceleration in a time history function is  given as 1.5 from time 1.0 to time 2.0 and the scale factor is 0.5, then the  magnitude of the acceleration from time 1.0 to 2.0 is 0.75. The default  value for the scale factor is 1.0.

The ``ACTIVE PERIODS`` and ``INACTIVE PERIODS`` command lines determine when the boundary condition is active. See :numref:`commands-functionality` for more information about these command lines.

Periodic Boundary Conditions
============================

.. code-block:: sierrainput

   BEGIN PERIODIC
     SIDE B  = <string>side_b_node_set
     SIDE A = <string>side_a_node_or_face_set
     COMPONENT = <string>X/Y/Z
     PRESCRIBED QUANTITY = DISPLACEMENT|FORCE|VELOCITY
     SEARCH TOLERANCE = <real>tol
     FUNCTION = <string>func_name
     SCALE FACTOR = <real>func_scale
     POINT ON AXIS = <string>point_name
     REFERENCE AXIS = <string>direction_name      
     THETA = <real>theta 
   END [PERIODIC]

The ``PERIODIC`` boundary condition command is used to define a set of periodic boundary constraints between two surfaces. 

The ``side_b_node_set`` is the name of the side B node set for the constraints. The ``side_a_node_or_face_set`` is the name of either the side A node set or side A surface for the constraint. If a side A node set is used the side A node set and side B node set must have the same number of nodes. Additionally the side A node set and side B node set must be related by a simple translation. When  two node sets are specified, a periodic constraint is defined between  each pair of coincident (after applying the translation) nodes in the two node sets.

When a node set and a surface are specified the constraints will be defined between the side B nodes and the faces of the side A surface. When using surfaces to specify periodic boundary conditions, the number of nodes must be the same on the side A and side B sides. The side B node set and side A face set  must still be related to one another by a simple translation.

``COMPONENT`` specifies which directional component should enforce the  prescribed quantity. This quantity can be ``DISPLACEMENT``,  ``VELOCITY``, or ``FORCE`` as defined by the ``PRESCRIBED QUANTITY`` command. Note, all degrees of freedom on the node are considered periodic. Only the ``COMPONENT`` will have the ``PRESCRIBED QUANTITY`` enforced, the other degrees of freedom will be  effectively linked with zero offset unless overridden by another periodic boundary condition.

.. warning::

   At this time the ``COPY VARIABLE`` command can only be used with nodal variables. Neither the ``COPY VARIABLE`` command nor the  ``READ VARIABLE`` command is compatible with global variables.

.. warning::

   Multi-component periodic BCs are not currently supported with FETI/Full Tangent Preconditioner. Please break-up each component of your periodic BCs into separate periodic BC command blocks.

Note that neither of the ``COMPONENT`` or ``PRESCRIBED QUANTITY`` command are needed  when dealing with rotational symmetry. 

The ``FUNCTION`` and ``SCALE FACTOR`` commands are used to define a relative difference in the prescribed quantity on the side B and side A sets. This function can be used to define an isotropic expansion or contraction of a periodic boundary. For the common default use case the function is set to zero zero meaning the prescribed quantities on the two sets are the same.

The ``SEARCH TOLERANCE`` command specifies a search tolerance used for matching up nodes and faces between the side A and side B sets. The search tolerance is necessary to account for slightly varying mesh topologies between the side A and side B sets. The search tolerance  should be something small, generally some small fraction of the  characteristic face length of facets on the surfaces.

|implicit| The commands ``POINT ON AXIS``, ``REFERENCE AXIS``, and ``THETA`` are used to define axisymmetric periodic wedge conditions. ``point_name`` gives the name of a point defined by a domain level ``DEFINE POINT`` command. ``direction_name`` gives the name of a point defined by a domain level ``DEFINE DIRECTION`` command. Taken together these two commands define the axis of rotation for the wedge body. ``THETA`` defines the angle, in degrees, covered by the wedge. By way of the thumb rule, ``THETA`` should always be positive when sweeping from side A to side B, in a positive rotation.

.. warning::

   The axisymmetric periodic boundary condition capability is still in development and has only been evaluated for implicit, serial analysis.

Examples:

.. code-block:: sierrainput

   SIDE B              = nodeset_11
   SIDE A              = nodeset_12
   COMPONENT           = xz
   PRESCRIBED QUANTITY = displacement
   SEARCH TOLERANCE    = 0.001
   FUNCTION            = function_1
   SCALE FACTOR        = 0.0

The above commands will create a periodic boundary condition between ``nodeset_11`` and ``nodeset_12``. The translational offset between ``nodeset_11`` and ``nodeset_12`` will be automatically determined. After the translation is applied, the coincident nodes in these node sets will match. For each node pair a constraint will be created to ensure the :math:`x`- and :math:`z`-displacements of the two nodes in the pair are equal.

.. warning::

   Periodic boundary conditions should generally not be combined with other kinematic boundary conditions (such as fixed displacement). The periodic boundary conditions define a full set of kinematic constraints and additional constraints may conflict with the periodic constraints in unexpected ways.

.. _bou-frot:

Fixed Rotation
==============

.. code-block:: sierrainput

   BEGIN FIXED ROTATION
     #
     # node set commands
     NODE SET|NODESET = <string list>nodelist_names
     SURFACE|SIDESET|SIDE SET = <string list>surface_names
     BLOCK = <string list>block_names
     ASSEMBLY = <string list>assembly_names
     RIGID BODY = <string list>rigid_body_names
     INCLUDE ALL BLOCKS
     REMOVE NODE SET = <string list>nodelist_names
     REMOVE SURFACE = <string list>surface_names
     REMOVE BLOCK = <string list>block_names
     #
     # specification commands
     COMPONENT = <string>X/Y/Z | COMPONENTS = <string>X/Y/Z | 
       DIRECTION = <string>dir_name
     #
     # additional commands
     ACTIVE PERIODS = <string list>periods_names
     INACTIVE PERIODS = <string list>periods_names
   END [FIXED ROTATION]

The ``FIXED ROTATION`` command is only applied to nodes that have rotational degrees of freedom such as shell element nodes and rigid body reference nodes. In the case of rigid bodies, the boundary condition must be specified on the block that defines the rigid body using the ``BLOCK`` or ``RIGID BODY`` line command.

The ``FIXED ROTATION`` command block fixes rotation about direction components (X, Y, Z, or some combination thereof) for a set of nodes to zero. This command block contains two groups of commands---node set and component. Each of these command groups is basically independent of the other. In addition to the command lines in the two command groups, there are additional command lines: ``ACTIVE PERIODS`` and ``INACTIVE PERIODS``. These command lines are used to activate or deactivate this kinematic boundary condition for certain time periods. 

.. warning::

   Note the fixed rotation command sets the rotation of a node to ZERO. To instead keep the current nodal displacement, a zero rotational velocity boundary condition should be used.

Following are descriptions of the different command groups.

.. _bou-frotnode:

Node Set Commands
-----------------

The ``node set commands`` portion of the command block specifies the  nodes associated with the boundary condition. This portion of the command  block can include some combination of the following command lines:

.. code-block:: sierrainput

   NODE SET|NODESET = <string list>nodelist_names
   SURFACE|SIDESET|SIDE SET = <string list>surface_names
   BLOCK = <string list>block_names
   ASSEMBLY = <string list>assembly_names
   RIGID BODY = <string list>rigid_body_names
   INCLUDE ALL BLOCKS
   REMOVE NODE SET = <string list>nodelist_names
   REMOVE SURFACE = <string list>surface_names
   REMOVE BLOCK = <string list>block_names

These command lines, taken collectively, constitute a set of Boolean  operators for constructing a set of nodes. See :numref:`conditions-general-entity` for more information  about the use of these command lines for creating a set of nodes used by the  boundary condition. There must be at least one ``NODE SET|NODESET``, ``SURFACE``, ``BLOCK``,  ``ASSEMBLY``, ``RIGID BODY``, or ``INCLUDE ALL BLOCKS`` command line in the command block. Assemblies may contain blocks, surfaces, nodesets, or assemblies of these.

.. _bou-frotspec:

Specification Commands
----------------------

There are two component specification commands available in the ``FIXED ROTATION`` command block:

.. code-block:: sierrainput

   COMPONENT = X|Y|Z | COMPONENTS = X/Y/Z | 
      DIRECTION = <string>dirName

A single rotation component may be set with the ``COMPONENT`` command line. A single direction of constraint can be set with the ``DIRECTION`` command. Multiple components can be constrained simultaneously with the ``COMPONENTS``. One and only one ``COMPONENT``, ``DIRECTION``, or ``COMPONENTS`` command must be specified in  the block. The ``COMPONENTS`` command can constraint multiple components simultaneously, for example

.. code-block:: sierrainput

   COMPONENTS = X Y 

.. _bou-frotadd:

Additional Commands
-------------------

The ``ACTIVE PERIODS`` and ``INACTIVE PERIODS`` command lines can optionally appear in the ``FIXED ROTATION`` command block:

.. code-block:: sierrainput

   ACTIVE PERIODS = <string list>period_names
   INACTIVE PERIODS = <string list>period_names

This command line determines when the boundary condition is active. See :numref:`commands-functionality` for more information about this optional command line.

.. _bou-prot:

Prescribed Rotation
===================

.. code-block:: sierrainput

   BEGIN PRESCRIBED ROTATION
     #
     # node set commands
     NODE SET|NODESET = <string list>nodelist_names
     SURFACE|SIDESET|SIDE SET = <string list>surface_names
     BLOCK = <string list>block_names
     ASSEMBLY = <string list>assembly_names
     RIGID BODY = <string list>rigid_body_names
     INCLUDE ALL BLOCKS
     REMOVE NODE SET = <string list>nodelist_names
     REMOVE SURFACE = <string list>surface_names
     REMOVE BLOCK = <string list>block_names
     #
     # specification commands
     DIRECTION = <string>defined_direction
     COMPONENT = X|Y|Z
     FUNCTION = <string>function_name
     #
     # user subroutine commands
     NODE SET SUBROUTINE = <string>subroutine_name
     SUBROUTINE DEBUGGING OFF | SUBROUTINE DEBUGGING ON
     SUBROUTINE REAL PARAMETER: <string>param_name
       = <real>param_value
     SUBROUTINE INTEGER PARAMETER: <string>param_name
       = <integer>param_value
     SUBROUTINE STRING PARAMETER: <string>param_name
       = <string>param_value
     #
     # external database commands
     READ VARIABLE = <string>var_name
     COPY VARIABLE = <string>var_name [FROM MODEL <string>model_name]
       MAP_BY_PROXIMITY|MAP_BY_ID(MAP_BY_PROXIMITY)
     TIME = <real>time|FIRST|LAST
     #
     # additional commands
     SCALE FACTOR = <real>scale_factor(1.0)
     ACTIVE PERIODS = <string list>period_names
     INACTIVE PERIODS = <string list>period_names
   END [PRESCRIBED ROTATION]

.. warning::

   The ``BEGIN PRESCRIBED ROTATION`` command is only applied to nodes that have rotational degrees of freedom such as shell element nodes and rigid body reference nodes. Displacements consistent with rotation about a fixed axis for nodes that do not have rotational degrees of freedom, are imposed using the ``CYLINDRICAL AXIS`` command line in the ``PRESCRIBED DISPLACEMENT``  command block described in :numref:`bou-pdis`.

.. TODOEXPLICIT

.. warning::

   The behavior of the ``BEGIN PRESCRIBED ROTATION`` command differs for implicit and explicit analyses. For implicit analyses, the ``BEGIN PRESCRIBED ROTATION`` command fully prescribes all rotational degrees of freedom. Consequently, a prescribed rotation in a given direction restricts rotation in the remaining two orthogonal directions. If multiple prescribed rotation boundary conditions are applied to a node, only the last one specified in the input is enforced. In explicit analyses, the ``BEGIN PRESCRIBED ROTATION`` command block prescribes rotational degree of freedom in only the specified direction. The node is free to rotate in the directions orthogonal to that direction. Multiple prescribed rotation boundary conditions can be applied to constrain rotations in those other directions if desired.

For nodal rotational degrees of freedom, the rotations applied using the ``BEGIN PRESCRIBED ROTATION`` command are the three components of the rotational degree of freedom itself. For rigid bodies, the rotations must be the nonlinear components that result in the desired quaternion on the rigid body reference node. For rigid bodies, the boundary condition is applied to the reference node and therefore must be specified on the block that defines the rigid body using the ``BLOCK`` or ``RIGID BODY`` line command. 

The ``PRESCRIBED ROTATION`` command block prescribes the rotation about an axis  for a given set of nodes. The rotation field associates a vector giving the  magnitude and direction of the rotation with each node in the node set. The  rotation field may vary over time and space. If the rotation field has only  a time-varying component, the specification commands in the above command block can  be used to specify the rotation field. If the rotation field has both  time-varying and spatially varying components, a user subroutine is  used to specify the rotation field. The rotation field can also be read from an external mesh database. In a given boundary condition command block, commands from only one of the command groups (specification commands, user subroutine commands, or external database commands) may be used.

The ``PRESCRIBED ROTATION`` command block contains four groups of commands---node set, function, user subroutine, and external database. Each of these command groups is basically independent of the others. In addition to the command lines in the four command groups, there are three additional command lines: ``SCALE FACTOR``, ``ACTIVE PERIODS``, and ``INACTIVE PERIODS``. The ``SCALE FACTOR`` command line can be used in conjunction with either the specification commands or the user subroutine commands. The ``ACTIVE PERIODS`` and ``INACTIVE PERIODS`` command lines are used to activate or deactivate this kinematic boundary condition for certain time periods. Following are descriptions of the different command groups.

.. _bou-protnode:

Node Set Commands
-----------------

The ``node set commands`` portion of the ``PRESCRIBED ROTATION`` command block defines a set of nodes associated with the prescribed rotation field and can include some combination of the following command lines:

.. code-block:: sierrainput

   NODE SET|NODESET = <string list>nodelist_names
   SURFACE|SIDESET|SIDE SET = <string list>surface_names
   BLOCK = <string list>block_names
   ASSEMBLY = <string list>assembly_names
   RIGID BODY = <string list>rigid_body_names
   INCLUDE ALL BLOCKS
   REMOVE NODE SET = <string list>nodelist_names
   REMOVE SURFACE = <string list>surface_names
   REMOVE BLOCK = <string list>block_names

These command lines, taken collectively, constitute a set of Boolean  operators for constructing a set of nodes. See :numref:`conditions-general-entity` for more information  about the use of these command lines for creating a set of nodes used by the  boundary condition. There must be at least one ``NODE SET|NODESET``, ``SURFACE``, ``BLOCK``,  ``ASSEMBLY``, ``RIGID BODY``, or ``INCLUDE ALL BLOCKS`` command line in the command block. Assemblies may contain blocks, surfaces, nodesets, or assemblies of these.

.. _bou-protspec:

Specification Commands
----------------------

If the specification commands are used, the rotation vector at any given time is the  same for all nodes in the node set associated with the particular ``PRESCRIBED  ROTATION`` command block. The direction of the rotation vector is constant for  all time; the magnitude of the rotation vector may vary with time, however.

Following are the command lines used to specify the prescribed rotation with a direction and a function:

.. code-block:: sierrainput

   DIRECTION = <string>defined_direction
   COMPONENT = X|Y|Z
   FUNCTION = <string>function_name

The ``DIRECTION`` or ``COMPONENT`` command line are used to prescribe the direction of rotation. The name in the string ``defined_direction`` is a reference to a direction, which is defined using the ``DEFINE DIRECTION`` command block within the SIERRA scope. The rotation is prescribed only in the specified direction. A prescribed rotation boundary condition does not influence the rotation in directions orthogonal to the prescribed direction. 

The magnitude of the rotation is specified by the ``FUNCTION`` command line. This references a ``function_name`` (defined in the SIERRA scope in a  ``FUNCTION`` command block) that specifies the magnitude of the  rotation vector as a function of time. The magnitude can be scaled by use of  the ``SCALE FACTOR`` command line described in :numref:`bou-protadd`.

The magnitude of the rotation, as specified by the product of the function and the scale factor, has units of radians per second.

.. _bou-protsub:

User Subroutine Commands
------------------------

If the user subroutine option is used, the rotation vector may vary spatially at any given time for each of the nodes in the node set associated with the particular ``PRESCRIBED ROTATION`` command block. The user subroutine option allows for a more complex description of the rotation field than do the specification commands, but also requires writing a user subroutine to implement this capability. The user subroutine will be used to define a rotation direction and a magnitude for every node to which the boundary condition will be applied. The subroutine will be called by Sierra/SM at the appropriate time to generate the rotation field.

Following are the command lines related to the user subroutine option:

.. code-block:: sierrainput

   NODE SET SUBROUTINE = <string>subroutine_name
   SUBROUTINE DEBUGGING OFF | SUBROUTINE DEBUGGING ON
   SUBROUTINE REAL PARAMETER: <string>param_name
     = <real>param_value
   SUBROUTINE INTEGER PARAMETER: <string>param_name
     = <integer>param_value
   SUBROUTINE STRING PARAMETER: <string>param_name
     = <string>param_value

The user subroutine option is invoked by using the ``NODE SET SUBROUTINE`` command line. The string ``subroutine_name`` is the name of a FORTRAN subroutine that is written by the user. 

Following the ``NODE SET SUBROUTINE`` command line are other command lines that may be used to implement the user subroutine option. These command lines are described in :numref:`use-comlines` and consist of ``SUBROUTINE DEBUGGING OFF``, ``SUBROUTINE DEBUGGING ON``, ``SUBROUTINE REAL PARAMETER``, ``SUBROUTINE INTEGER PARAMETER``, and ``SUBROUTINE STRING PARAMETER``. Examples of using these command lines are provided throughout :numref:`subroutines`.

The magnitude set in the user subroutine can be scaled by use of the ``SCALE FACTOR`` command line, as described in :numref:`bou-protadd`.

See :numref:`conditions-kinematic-subroutine` and :numref:`subroutines` for more details on implementing the user subroutine option. 

.. _bou-protdb:

External Mesh Database Commands
-------------------------------

If the external database option is used, the rotation vector (or specified components of the vector) is read from an external mesh database. The rotations are read from a finite element model defined via the ``FINITE ELEMENT MODEL`` command block described in :numref:`elements-fem`. The finite element model can either be the model used by the region for its mesh definition as specified with the ``USE FINITE ELEMENT MODEL`` command (see :numref:`commands-fem`), or it can be a different (but compatible) model. The following command lines control the use of an external mesh database to prescribe the rotation:

.. code-block:: sierrainput

   READ VARIABLE = <string>var_name
   COPY VARIABLE = <string>var_name [FROM MODEL <string>model_name]
     MAP_BY_PROXIMITY|MAP_BY_ID(MAP_BY_PROXIMITY)
   TIME = <real>time|FIRST|LAST

See :numref:`conditions-variable-extmesh` for more details.

.. _bou-protadd:

Additional Commands
-------------------

These command lines in the ``PRESCRIBED ROTATION`` command block provide additional options for the boundary condition:

.. code-block:: sierrainput

   SCALE FACTOR = <real>scale_factor(1.0)
   ACTIVE PERIODS = <string list>period_names
   INACTIVE PERIODS = <string list>period_names

The ``SCALE FACTOR`` command line is used to apply an additional scaling factor,  which is constant in both time and space, to all vector magnitude values of  the field defined by the specification commands or the user subroutine. For  example, if the magnitude of the rotation in a time history function is  given as 1.5 from time 1.0 to time 2.0 and the scale factor is 0.5, then the  magnitude of the rotation from time 1.0 to 2.0 is 0.75. The default value  for the scale factor is 1.0.

The ``ACTIVE PERIODS`` and ``INACTIVE PERIODS`` command lines determine when the boundary condition is active. See :numref:`commands-functionality` for more information about these command lines.

.. _bou-protvel:

Prescribed Rotational Velocity
==============================

.. code-block:: sierrainput

   BEGIN PRESCRIBED ROTATIONAL VELOCITY
     #
     # node set commands
     NODE SET|NODESET = <string list>nodelist_names
     SURFACE|SIDESET|SIDE SET = <string list>surface_names
     BLOCK = <string list>block_names
     ASSEMBLY = <string list>assembly_names
     RIGID BODY = <string list>rigid_body_names
     INCLUDE ALL BLOCKS
     REMOVE NODE SET = <string list>nodelist_names
     REMOVE SURFACE = <string list>surface_names
     REMOVE BLOCK = <string list>block_names
     #
     # specification commands
     DIRECTION = <string>defined_direction |
      COMPONENT = <string>X|Y|Z
     FUNCTION = <string>function_name
     #
     # user subroutine commands
     NODE SET SUBROUTINE = <string>subroutine_name
     SUBROUTINE DEBUGGING OFF | SUBROUTINE DEBUGGING ON
     SUBROUTINE REAL PARAMETER: <string>param_name
       = <real>param_value
     SUBROUTINE INTEGER PARAMETER: <string>param_name
       = <integer>param_value
     SUBROUTINE STRING PARAMETER: <string>param_name
       = <string>param_value
     #
     # external database commands
     READ VARIABLE = <string>variable_name
     COPY VARIABLE = <string>variable_name [FROM MODEL 
       <string>model_name]
     TIME = <real>time|FIRST|LAST
     #
     # additional commands
     SCALE FACTOR = <real>scale_factor(1.0)
     ACTIVE PERIODS = <string list>period_names
     INACTIVE PERIODS = <string list>period_names
   END [PRESCRIBED ROTATIONAL VELOCITY]

.. warning::

   The ``PRESCRIBED ROTATIONAL VELOCITY`` command is only applied to nodes that have rotational degrees of freedom such as shell element nodes and rigid body reference nodes. Velocities consistent with rotation about a fixed axis for nodes that do not have rotational degrees of freedom, are imposed with the ``CYLINDRICAL AXIS`` command line in the ``PRESCRIBED VELOCITY``  command block described in :numref:`bou-pvel`.

.. TODOEXPLICIT

.. warning::

   The behavior of the ``BEGIN PRESCRIBED ROTATIONAL VELOCITY`` command differs for implicit and explicit analyses. For implicit analyses, the ``BEGIN PRESCRIBED ROTATIONAL VELOCITY`` command fully prescribes all rotational degrees of freedom. Consequently, a prescribed rotational velocity in a given direction restricts rotation in the remaining two orthogonal directions. If multiple prescribed rotational velocity boundary conditions are applied to a node, only the last one specified in the input is enforced. In explicit analyses, the ``BEGIN PRESCRIBED ROTATIONAL VELOCITY`` command block prescribes rotational degree of freedom in only the specified direction. The node is free to rotate in the directions orthogonal to that direction. Multiple prescribed rotational velocity boundary conditions can be applied to constrain rotations in those other directions if desired.

The ``PRESCRIBED ROTATIONAL VELOCITY`` command block prescribes the rotational velocity about an axis  for a given set of nodes. The rotational velocity field associates a vector giving the  magnitude and direction of the rotational velocity with each node in the node set. The  rotational velocity field may vary over time and space. If the rotational velocity field has only  a time-varying component, the specification commands in the above command block can  be used to specify the rotational velocity field. If the rotational velocity field has both  time-varying and spatially varying components, a user subroutine is  used to specify the rotational velocity field. The rotational velocity field can also be read from an external mesh database. In a given boundary condition command block, commands from only one of the command groups (specification commands, user subroutine commands, or external database commands) may be used.

For rigid bodies, the user must specify the rotational velocity components such that they define the desired quaternion on the rigid body reference node. For rigid bodies, the boundary condition is applied to the reference node and therefore must be specified on the block that defines the rigid body using the ``BLOCK`` or ``RIGID BODY`` line command. 

The ``PRESCRIBED ROTATIONAL VELOCITY`` command block contains four groups of commands---node set, function, user subroutine, and external database. Each of these command groups is basically independent of the others. In addition to the command lines in the four command groups, there are three additional command lines: ``SCALE FACTOR``, ``ACTIVE PERIODS``, and ``INACTIVE PERIODS``. The ``SCALE FACTOR`` command line can be used in conjunction with either the specification commands or the user subroutine commands. The ``ACTIVE PERIODS`` and ``INACTIVE PERIODS`` command lines are used to activate or deactivate this kinematic boundary condition for certain time periods. Following are descriptions of the different command groups.

.. _bou-protvelnode:

Node Set Commands
-----------------

The ``node set commands`` portion of the ``PRESCRIBED ROTATIONAL VELOCITY`` command block defines a set of nodes associated with the prescribed rotational velocity field and can include some combination of the following command lines:

.. code-block:: sierrainput

   NODE SET|NODESET = <string list>nodelist_names
   SURFACE|SIDESET|SIDE SET = <string list>surface_names
   BLOCK = <string list>block_names
   ASSEMBLY = <string list>assembly_names
   RIGID BODY = <string list>rigid_body_names
   INCLUDE ALL BLOCKS
   REMOVE NODE SET = <string list>nodelist_names
   REMOVE SURFACE = <string list>surface_names
   REMOVE BLOCK = <string list>block_names

These command lines, taken collectively, constitute a set of Boolean operators for constructing a set of nodes. See :numref:`conditions-general-entity` for more information about the use of these command lines for creating a set of nodes used by the boundary condition. There must be at least one ``NODE SET|NODESET``, ``SURFACE``, ``BLOCK``, ``ASSEMBLY``, ``RIGID BODY``, or ``INCLUDE ALL BLOCKS`` command line in the command block. Assemblies may contain blocks, surfaces, nodesets, or assemblies of these.

.. _bou-protvelspec:

Specification Commands
----------------------

If the specification commands are used, the rotational velocity vector at any given time is the same for all nodes in the node set associated with the particular ``PRESCRIBED ROTATIONAL VELOCITY`` command block. The direction of the rotational velocity vector is constant for all time; the magnitude of the rotational velocity vector may vary with time, however.

Following are the command lines used to specify the prescribed rotational velocity with a direction and a function:

.. code-block:: sierrainput

   DIRECTION = <string>defined_direction |
     COMPONENT = <string>X|Y|Z
   FUNCTION = <string>function_name

The rotational velocity can be specified either along an arbitrary user-defined direction or along a component direction (X, Y, or Z), but not both. The rotational velocity is prescribed only in the specified direction. A prescribed rotational velocity boundary condition does not influence the rotational velocity in directions orthogonal to the prescribed direction. 

- The ``DIRECTION`` command line is used to prescribe rotational velocity in an arbitrary user-defined direction. The name in the string ``defined_direction`` is a reference to a direction, which is defined using the ``DEFINE DIRECTION`` command block within the SIERRA scope. 

- The ``COMPONENT`` command line specifies that the prescribed rotational velocity vector lies along one of the component directions. The ``COMPONENT`` command line is a shortcut to an internally defined direction vector; for example, component ``x`` corresponds to using direction vector (1, 0, 0). 

The magnitude of the rotational velocity is specified by the ``FUNCTION`` command line. This references a ``function_name`` (defined in the SIERRA scope in a ``FUNCTION`` command block) that specifies the magnitude of the rotational velocity vector as a function of time. The magnitude can be scaled by use of the ``SCALE FACTOR`` command line described in :numref:`bou-protveladd`.

The magnitude of the rotational velocity, as specified by the product of the function  and the scale factor, has units of radians per second.

.. _bou-protvelsub:

User Subroutine Commands
------------------------

If the user subroutine option is used, the rotational velocity vector may vary spatially at any given time for each of the nodes in the node set associated with the particular ``PRESCRIBED ROTATIONAL VELOCITY`` command block. The user subroutine option allows for a more complex description of the rotational velocity field than do the specification commands, but also requires writing a user subroutine to implement this capability. The user subroutine will be used to define a rotational velocity direction and a magnitude for every node to which the boundary condition will be applied. The subroutine will be called by Sierra/SM at the appropriate time to generate the rotational velocity field.

Following are the command lines related to the user subroutine option:

.. code-block:: sierrainput

   NODE SET SUBROUTINE = <string>subroutine_name
   SUBROUTINE DEBUGGING OFF | SUBROUTINE DEBUGGING ON
   SUBROUTINE REAL PARAMETER: <string>param_name
     = <real>param_value
   SUBROUTINE INTEGER PARAMETER: <string>param_name
     = <integer>param_value
   SUBROUTINE STRING PARAMETER: <string>param_name
     = <string>param_value

The user subroutine option is invoked by using the ``NODE SET SUBROUTINE`` command line. The string ``subroutine_name`` is the name of a FORTRAN subroutine that is written by the user. 

Following the ``NODE SET SUBROUTINE`` command line are other command lines that may be used to implement the user subroutine option. These command lines are described in :numref:`use-comlines` and consist of ``SUBROUTINE DEBUGGING OFF``, ``SUBROUTINE DEBUGGING ON``, ``SUBROUTINE REAL PARAMETER``, ``SUBROUTINE INTEGER PARAMETER``, and ``SUBROUTINE STRING PARAMETER``. Examples of using these command lines are provided throughout :numref:`subroutines`.

The magnitude set in the user subroutine can be scaled by use of the ``SCALE FACTOR`` command line, as described in :numref:`bou-protveladd`.

See :numref:`conditions-kinematic-subroutine` and :numref:`subroutines` for more details on implementing the user subroutine option. 

.. _bou-protveldb:

External Mesh Database Commands
-------------------------------

If the external database option is used, the rotational velocity vector (or specified components of the vector) is read from an external mesh database. The rotational velocities are read from a finite element model defined via the ``FINITE ELEMENT MODEL`` command block described in :numref:`elements-fem`. The finite element model can either be the model used by the region for its mesh definition as specified with the ``USE FINITE ELEMENT MODEL`` command (see :numref:`commands-fem`), or it can be a different (but compatible) model. The following command lines control the use of an external mesh database to prescribe the rotational velocity:

.. code-block:: sierrainput

   READ VARIABLE = <string>var_name
   COPY VARIABLE = <string>var_name [FROM MODEL <string>model_name]
     MAP_BY_PROXIMITY|MAP_BY_ID(MAP_BY_PROXIMITY)
   TIME = <real>time|FIRST|LAST

See :numref:`conditions-variable-extmesh` for more details.

.. _bou-protveladd:

Additional Commands
-------------------

These command lines in the ``PRESCRIBED ROTATIONAL VELOCITY`` command block provide additional options for the boundary condition:

.. code-block:: sierrainput

   SCALE FACTOR = <real>scale_factor(1.0)
   ACTIVE PERIODS = <string list>period_names
   INACTIVE PERIODS = <string list>period_names

The ``SCALE FACTOR`` command line is used to apply an additional scaling factor, which is constant in both time and space, to all vector magnitude values of the field defined by the specification commands or the user subroutine. For example, if the magnitude of the rotational velocity in a time history function is given as 1.5 from time 1.0 to time 2.0 and the scale factor is 0.5, then the magnitude of the rotational velocity from time 1.0 to 2.0 is 0.75. The default value for the scale factor is 1.0.

The ``ACTIVE PERIODS`` and ``INACTIVE PERIODS`` command lines determine when the boundary condition is active. See :numref:`commands-functionality` for more information about these command lines.

.. _bou-rarot:

Reference Axis Rotation
=======================

.. code-block:: sierrainput

   BEGIN REFERENCE AXIS ROTATION
     #
     # block commands
     BLOCK = <string list>block_names
     ASSEMBLY = <string list>assembly_names
     RIGID BODY = <string list>rigid_body_names
     #
     # specification commands
     REFERENCE AXIS X FUNCTION = <string>function_name
     REFERENCE AXIS Y FUNCTION = <string>function_name
     REFERENCE AXIS Z FUNCTION = <string>function_name
     #
     # rotation commands
     ROTATION = <string>function_name
     ROTATIONAL VELOCITY = <string>function_name
     #
     # torque command
     TORQUE = <string>function_name
     #
     # additional commands
     SCALE FACTOR = <real>scale_factor(1.0)
     ACTIVE PERIODS = <string list>period_names
     INACTIVE PERIODS = <string list>period_names
   END [REFERENCE AXIS ROTATION]

The ``REFERENCE AXIS ROTATION`` command block is intended to control the rotation of a rigid body. The three ``REFERENCE AXIS`` line commands are required and together define a time-varying reference axis or vector. The rigid body will rotate to follow the vector. Depending on other line commands in the block, the rigid body will have either zero or one free rotational degree of freedom. If one degree of freedom is present, it is the rotation about the time-varying reference vector.

The rotation of the rigid body described by the axis functions over any time step is  determined using the reference axis position at the beginning and the end of the time step. If a reference axis is desired to represent movement of a principal axis of the rigid body, its  position at the start of rotation must coincide with the position of that principal axis. A constant function can only be used to represent a spin around a principal axis if the principal axis and the reference axis are the same. To represent spin about a principal axis that is moving or is stationary but in a different position than the principal axis, the time history for the axis functions must define the reference axis in the same position as the principal axis at the beginning of the rotation.

At most, one of the ``ROTATION``, ``ROTATIONAL VELOCITY``, or ``TORQUE`` line commands may be present. If the ``ROTATION`` or ``ROTATIONAL VELOCITY`` command line is present, the rigid body will be fully prescribed for rotation. The ``ACTIVE PERIODS`` and ``INACTIVE PERIODS`` command lines are used to activate or deactivate this kinematic boundary condition for certain time periods.

Use of the ``REFERENCE AXIS ROTATION`` command block will cause extra global variables to be written to the results file. These variables describe the reaction force, rotational reaction moment, rotational displacement, and rotational velocity associated with the boundary condition and in the local coordinate system described by the boundary condition. The names of the variables are:

.. code-block:: sierrainput

   REACTR_<NAME>
   REACTS_<NAME>
   REACTT_<NAME>
   
   RREACTR_<NAME>
   RREACTS_<NAME>
   RREACTT_<NAME>
   
   ROTDS_<NAME>
   
   ROTVR_<NAME>
   ROTVS_<NAME>
   ROTVT_<NAME>

The variables beginning with ``REACT`` give the reaction forces in the boundary condition's local coordinate system. Those beginning with ``RREACT`` give the reaction moments.

Only the ``S`` component is given for the rotational displacement. This is because that the other coordinate directions are poorly defined, and therefore, rotational displacements in those directions provide no value.

The variables beginning with ``ROTV`` give the rotational velocity in the local coordinate system.

For each global variable, ``<NAME>`` is the name of the rigid body controlled by this boundary condition.

.. _bou-rarotblock:

Block Command
-------------

The ``block command`` portion of the ``REFERENCE AXIS ROTATION`` command block defines a block associated with the prescribed rotation field and must include the following command line:

.. code-block:: sierrainput

   BLOCK = <string list>block_names

or

.. code-block:: sierrainput

   ASSEMBLY = <string list>assembly_names

where the assemblies must only contain element blocks.

If the element block in the ``BLOCK`` command has been defined as a rigid body, the rotation is applied to the rigid body reference node.

Alternatively, the command line:

.. code-block:: sierrainput

   RIGID BODY = <string list>rigid_body_names

may be used to specify the rotation on the reference node of the specified rigid body.

See :numref:`conditions-general-entity` for more information about the use of this command line.

.. _bou-rarotspec:

Specification Commands
----------------------

The three specification commands are required and together define a time-varying vector that gives the orientation of a reference axis for rotation. The magnitude of the vector is ignored.

Following are the command lines used to specify the reference axis rotation with a direction:

.. code-block:: sierrainput

   REFERENCE AXIS X FUNCTION = <string>function_name
   REFERENCE AXIS Y FUNCTION = <string>function_name
   REFERENCE AXIS Z FUNCTION = <string>function_name

At a given time, the function referred to by the ``REFERENCE AXIS X FUNCTION`` line command gives the x component of a vector defining the reference axis. The pattern holds for the :math:`y` and :math:`z` components as well. Since the magnitude of the resulting axis or vector is not used, the three functions do not need to describe a unit vector in time.

.. _bou-rarotrot:

Rotation Commands
-----------------

It is possible to prescribe the complete rotation of a rigid body through the use of the ``ROTATION`` or ``ROTATIONAL VELOCITY`` line commands. Without these line commands, the rigid body is free to rotate about the reference axis.

Following are the command lines to prescribe the rotation about the reference axis:

.. code-block:: sierrainput

   ROTATION = <string>function_name
   ROTATIONAL VELOCITY = <string>function_name

The function referred to by the ``ROTATION`` line command gives the magnitude of rotation in radians about the reference axis as a function of time. This function should not be changed across a restarted analysis.

The function referred to by the ``ROTATIONAL VELOCITY`` line command gives the rotational velocity in radians per second about the reference axis as a function of time. This function should not be changed across a restarted analysis.

.. _bou-rarottor:

Torque Command
--------------

A user may specify a moment about the reference axis through the use of the ``TORQUE`` line command.

.. code-block:: sierrainput

   TORQUE = <string>function_name

The function referred to by the ``TORQUE`` line command gives the torque or moment about the reference axis as a function of time.

.. _bou-rarotadd:

Additional Commands
-------------------

The ``SCALE FACTOR``, ``ACTIVE PERIODS``, and ``INACTIVE PERIODS`` command lines can optionally appear in the ``REFERENCE AXIS ROTATION`` command block:

.. code-block:: sierrainput

   SCALE FACTOR = <real>scale_factor(1.0)
   ACTIVE PERIODS = <string list>period_names
   INACTIVE PERIODS = <string list>period_names

The ``SCALE FACTOR`` command line applies the specified value as a scale factor to the rotation, rotational velocity, or torque functions.

The final two command lines can activate or deactivate the reference axis rotation for certain time periods. See :numref:`commands-functionality` for more information about these command lines.

.. _conditions-kinematic-subroutine:

Subroutine Usage for Kinematic Boundary Conditions
==================================================

The prescribed kinematic boundary conditions may be defined by a user subroutine. All these conditions use a node set subroutine. See :numref:`subroutines` for an in-depth discussion of user subroutines. The kinematic boundary conditions will be applied to nodes. The subroutine will have to return six output values per node and one output flag per node. The usage of the output values depends on the returned flag value for a node, as follows:

- If the flag value is negative, no constraint will be applied to the node.

- If the flag value is equal to zero, the constraint will be absolute. All components of the boundary condition will be specified. For example, suppose the user has specified a subroutine to be called from a prescribed displacement subroutine. The prescribed displacements are to be passed through an array ``output_values``. For a given node ``inode``, the ``output_values`` array would have the following values:

.. code-block:: sierrainput

   output_values(1,inode) = displacement in x at inode
   output_values(2,inode) = displacement in y at inode
   output_values(3,inode) = displacement in z at inode
   output_values(4,inode) = not used
   output_values(5,inode) = not used
   output_values(6,inode) = not used

- If the flag value is equal to one, the constraint will be a specified amount in a given direction. For example, suppose the user has specified a subroutine to be called from a prescribed displacement subroutine. The prescribed displacements are to be passed through an array ``output_values``. For a given node ``inode``, the ``output_values`` array would have the following values:

.. code-block:: sierrainput

   output_values(1,inode) = magnitude of displacement
   output_values(2,inode) = not used
   output_values(3,inode) = not used
   output_values(4,inode) = x component of direction vector
   output_values(5,inode) = y component of direction vector
   output_values(6,inode) = z component of direction vector

The direction in which the constraint will act is given by ``output_values`` 4 through 6 for ``inode``. The magnitude of the displacement in the specified direction is given by ``output_values`` 1 at ``inode``. To compute the constraint, Sierra/SM first normalizes the direction vector. Next, Sierra/SM multiplies the normalized direction vector by the magnitude of the displacement and applies the resultant constraint vector.

Displacements or velocities orthogonal to the prescribed direction will not be constrained. (This is true regardless of whether one uses a user subroutine for the prescribed kinematic boundary conditions.)  Take the case of a prescribed displacement condition. The displacement orthogonal to a prescribed direction of motion depends on the internal and external forces orthogonal to the prescribed direction. Displacement orthogonal to the prescribed direction may or may not be zero.
