.. _conditions-velocity:

***************************
Initial Velocity Conditions
***************************

.. code-block:: sierrainput

   BEGIN INITIAL 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
     #
     # direction specification commands
     COMPONENT = <string>X|Y|Z |
       DIRECTION = <string>defined_direction
     # 
     #  magnitude specification commands
     MAGNITUDE = <real>magnitude_of_velocity
     FUNCTION = <string>function_name
     SCALE FACTOR = <real>function_scale
     #
     # angular velocity specification commands
     CYLINDRICAL AXIS = <string>defined_axis
     ANGULAR VELOCITY = <real>angular_velocity
     #
     # 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
   END [INITIAL VELOCITY]

The ``INITIAL VELOCITY`` command block specifies an initial velocity field for a set of nodes. There are two simple options for specifying the initial velocity field: by direction and by angular velocity. The user subroutine option available is also available to specify an initial velocity. Only one of the available options -- direction specification, angular velocity specification, or user subroutine---may be used.

The ``INITIAL VELOCITY`` command block contains four groups of commands -- node set, direction specification, angular velocity specification, and user subroutine. Command lines associated with the node set commands must appear. As mentioned, command lines associated with one of the options must also appear. Following are descriptions of the different command groups.

.. warning::

   The ``INITIAL VELOCITY`` command block may *not* be used to set an initial rotational velocity for rigid bodies. To do this with rigid bodies, see :numref:`elements-functionality-rigid`. This block only allows the specification of translational degrees of freedom for rigid bodies.

.. warning::

   Initial velocity follows the same constraint enforcement hierarchy as other kinematic boundary conditions. Thus, if two non-orthogonal initial velocities are specified the result will not be an addition of the two velocities, rather the last boundary condition defined in the input deck will override the non-orthogonal components of previous boundary conditions. See :ref:`Appendix D <appendix-constraints>` for further details and examples.

If it is desired to set an initial spin and translational velocity on the same part a subroutine exists in the user subroutine library to accomplish this task. See :numref:`use-aup_transRot`. 

.. _bou-initvelnode:

Node Set Commands
=================

The ``node set commands`` portion of the ``INITIAL VELOCITY`` command block defines a set of nodes associated with the initial 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

For rigid bodies, the boundary condition is applied to the reference node and must be specified on the block that defines the rigid body using the ``BLOCK`` or ``RIGID BODY`` line command. 

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-initveldir:

Direction Specification Commands
================================

If the direction specification commands are used, the initial velocity is applied along a defined direction with a specific magnitude. Following are the command lines for the direction option:

.. code-block:: sierrainput

   COMPONENT = <string>X|Y|Z |
     DIRECTION = <string>defined_direction
   MAGNITUDE = <real>magnitude_of_velocity
   FUNCTION = <string>function_name
   SCALE FACTOR = <real>function_scale

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

- The ``DIRECTION`` command line is used to prescribe initial 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 initial 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 initial velocity can be given in a few ways. One option is the ``MAGNITUDE`` which defines a constant initial velocity for the boundary condition. A second option is use of a ``FUNCTION`` command. The ``FUNCTION`` is evaluated at the initial time to  set the initial velocity. Generally the ``FUNCTION`` command would be used with spatially dependent analytic functions. The ``SCALE FACTOR`` command line defines an additional multiplier on the magnitude or magnitude function.

Either the ``COMPONENT`` command line or the ``DIRECTION`` command line must be specified when using the ``MAGNITUDE`` or ``FUNCTION`` command lines.

.. _bou-initvelang:

Angular Velocity Specification Commands
=======================================

If the angular velocity specification commands are used, the initial velocity is applied as an initial angular velocity about some axis. Following are the command lines for angular velocity specification:

.. code-block:: sierrainput

   CYLINDRICAL AXIS = <string>defined_axis
   ANGULAR VELOCITY = <real>angular_velocity

The axis about which the body is initially rotating is given by the  ``CYLINDRICAL AXIS`` command line. The string ``defined_axis`` uses an ``axis_name`` that is defined in the SIERRA scope (via a ``DEFINE AXIS`` command line). 

The magnitude of the angular velocity about this axis is specified by the  ``ANGULAR VELOCITY`` command line with the real value ``angular_velocity``. This value is specified in units of radians per unit of time. Typically, the 
value for the angular velocity will be radians per second.

Both the ``CYLINDRICAL AXIS`` and ``ANGULAR VELOCITY`` command lines are required when using the angular velocity specification commands.

.. _bou-initvelsub:

User Subroutine Commands
========================

If the user subroutine option is used, the initial velocity vector may vary spatially at any given time for each of the nodes in the node set associated with the particular ``INITIAL CONDITION`` command block. The user subroutine option allows for a more complex description of the initial velocity field than do the direction and angular-velocity options, but the user subroutine option 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 initial velocity field will be applied. The subroutine will be called by Sierra/SM at the appropriate time to generate the initial 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`.

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