.. _elements-functionality:

**************************
Element-like Functionality
**************************

This section describes functionality in Sierra/SM that behaves similarly to finite elements, although are not implemented as such. The functionality described in this section are specified through command blocks that appear in the SIERRA scope and region scope, respectively.

.. _elements-functionality-rigid:

Rigid Body
==========

.. code-block:: sierrainput

   BEGIN RIGID BODY <string>rb_name
     MASS = <real>mass
     POINT MASS = <real>mass [AT <real>X <real>Y <real>Z]
     REFERENCE LOCATION = <real>X <real>Y <real>Z
     INERTIA = <real>Ixx <real>Iyy <real>Izz <real>Ixy
       <real>Iyz <real>Izx
     POINT INERTIA = <real>Ixx <real>Iyy <real>Izz <real>Ixy
       <real>Iyz <real>Izx
     MAGNITUDE = <real>magnitude_of_velocity
     DIRECTION = <string>direction_definition
     ANGULAR VELOCITY = <real>omega
     CYLINDRICAL AXIS = <string>axis_definition
     INCLUDE NODES IN <string>surface_name
       [IF <string>field_name <|<=|=|>=|> <real>value]
   END [RIGID BODY <string>rb_name]

A rigid body can consist of any combination of elements -- solid elements, structural elements, and point masses -- except SPH elements. All nodes associated with a rigid body maintain their relative position to each other as determined at time zero when there is no deformation of the body. This means that the elements associated with the rigid body can translate and rotate through space, but they cannot deform. Element blocks defining the rigid body do not have to be contiguous. They can also adjoin deformable element blocks. Multiple rigid bodies are allowed in a model.

.. warning::

   Truss elements currently do not work correctly when used in a rigid body unless the user includes the ``INERTIA`` command in the rigid body command block to specify the total mass moment of inertia of the rigid body. The code currently does not compute the inertia about the longitudinal axis  of a truss because only the area is input for a truss section. The  recommendation is to use a beam section rather than a truss section for  rigid bodies.

.. warning::

   The non-deformable nature of the rigid body can put it in conflict  with other constraints. Refer to :ref:`Appendix D <appendix-constraints>` for information on how conflicting constraints are handled.

.. warning::

   Kinematic boundary conditions prescribed on a rigid body must be  applied to the rigid body reference location, e.g., its center of mass. Kinematic boundary conditions for a rigid body that are not prescribed on  the rigid body reference location will not be enforced. Note that, unlike  non-rigid blocks, a rigid body block may rotate about the rigid body  reference location if only translational boundary conditions are prescribed,  so rotational boundary conditions may also be prescribed to constrain  rotational movement. To apply kinematic boundary conditions to a rigid body,  use the ``BLOCK =`` or the ``RIGID BODY =`` line command with the  rigid body's block id or name, respectively, in the appropriate boundary  condition command block. Refer to :numref:`conditions`.

Sierra/SM creates a new node for each rigid body in the analysis. The new nodes are true nodes in that they are associated with solution fields such as displacement, velocity, and rotational velocity. These nodes will appear in a results file along with other nodes. The global node number given to the new nodes is the total number of nodes in the mesh plus one, repeated for each new rigid body node.

If an element block is declared to be a part of a rigid body, the internal force calculations are not called for the elements in that block and element time steps for explicit dynamics are not computed.  Hence, for a model where all the element blocks are included in rigid bodies, there is no estimate for a global explicit dynamics time step. In this case an  initial time must be specified in the ``TIME CONTROL`` command block (:numref:`explicit-procedure-commands`) with the command line

.. parsed-literal::

   INITIAL TIME STEP = <real>time_step |explicit_mini|

For the completely rigid explicit dynamics case, one also should  avoid using a value larger than 1.0 for the time step scale factor (see :numref:`explicit-procedure-commands`).  A time step value of :math:`1.0\times10^{-6}` should work well for most such problems, though any time step may be specified. However since  a completely rigid problem does not impose a stability limit on the explicit dynamics time step, specifying too large of a time step could cause loss of accuracy in the solution of the problem (due to numerical integration error, large rotations over a time step, etc.) even though the problem runs to completion. The default value of the time step scale factor is 0.9.

Specification of a rigid body requires the above command block, which appears in the SIERRA scope, plus the ``RIGID BODY`` command line that appears in the various ``SECTION`` command blocks described in this chapter. Suppose, for example, ``rigidbody_1`` consists of element blocks 100, 110, and 280. The ``PARAMETERS FOR BLOCK`` command blocks for element blocks 100, 110, and 280 must all contain a ``SECTION`` command line. In each case, the Section must contain a line such as:

.. code-block:: sierrainput

   RIGID BODY = rigidbody_1

Once element block(s) have been declared a rigid body and named appropriately (through the Section chosen), that rigid body name must appear as the name in a ``RIGID BODY`` command block. In the example, a ``RIGID BODY`` command block with the value for ``rb_name`` set to ``rigidbody_1`` must exist, i.e., in the Sierra scope,

.. code-block:: sierrainput

   BEGIN RIGID BODY rigidbody_1
   END [RIGID BODY rigidbody_1]

The ``RIGID BODY`` command block has several optional command lines, comprising four groups of commands. One group consists of the ``MASS``, ``POINT MASS``, ``REFERENCE LOCATION``, ``POINT INERTIA``, and ``INERTIA`` command lines, a second group consists of the paired ``MAGNITUDE`` and ``DIRECTION`` command lines, a third group consists of the paired ``ANGULAR VELOCITY`` and ``CYLINDRICAL AXIS`` command lines, and a final group consists of the ``INCLUDE NODES IN`` command line. The command block can include none or any combination of these groups. If none of these commands is included, the command block supplies the value for ``rb_name``.

Input to the ``MASS`` command line consists of a single real number that defines the total mass of the rigid body. If this line command is not present, the mass of the rigid body will be computed using the elements in the rigid body and their densities. This is the translational mass at the reference location. This command does not change the inertia terms.

The ``POINT MASS`` command line requires a real number specifying the amount of mass added to the rigid body. Optionally, the location of that mass may be specified with three real numbers. If the location is not given, the additional mass will be placed at the reference location (and will not affect the moments and products of inertia).

The ``REFERENCE LOCATION`` command line requires three real numbers defining the reference location for the rigid body. If this line command is not present, the center of mass will be used. The center of mass is calculated from the mesh and the element densities.

Input to the ``INERTIA`` command line consists of six real numbers. If present, this command line will set the inertia for the rigid body. If it is not present, moments and products of inertia are computed for the rigid body based on the reference location of the rigid body and the element masses.

Input to the ``POINT INERTIA`` command line consists of six real numbers that define moments (``Ixx``, ``Iyy``, ``Izz``) and products (``Ixy``, ``Iyx``, ``Izx``) of inertia to be added to the inertia tensor of the rigid body. This modified inertia tensor (rather than the inertia tensor based solely on element mass) is then used to calculate the motion of the rigid body.

If a rigid body contains an element that has rotational resistance (e.g., shell, beam, etc.) the nodal moment of inertia of that element is added to the diagonal components of the rigid body's inertia tensor.

An initial, translational-only velocity for the rigid body at the reference location should be specified with the ``MAGNITUDE`` and ``DIRECTION`` command lines. The ``MAGNITUDE`` command line gives the magnitude of the initial velocity applied at the reference location, and the ``DIRECTION`` command line gives a defined direction. 

An initial rotational and translational velocity for a rigid body can be specified with the ``ANGULAR VELOCITY`` and ``CYLINDRICAL AXIS`` command lines. The ``ANGULAR VELOCITY`` command line gives the initial translational velocity of and rotational  velocity about the reference location due to an angular velocity about  some defined axis given on the ``CYLINDRICAL AXIS`` command line. If the  defined cylindrical axis passes through the reference location, this command will impart only an initial rotational velocity to the rigid body. If the  axis does not pass through the reference location, this command will  impart both an initial translational velocity and the initial rotational  velocity to the rigid body. 

The ``INCLUDE NODES IN`` command line allows a rigid body to include nodes of a surface, node set, or block of the mesh. Optionally, the nodes in the surface, node set, or block will be included in the rigid body only if the value of a field on the nodes meets a given criterion. For example, consider the rigid body block below.

.. code-block:: sierrainput

   begin rigid body rigid1
     include nodes in block_1
     include nodes in nodelist_100
     include nodes in surface_3 if height = -1.0
   end

Rigid body ``rigid1`` will include all nodes in ``block_1`` and those nodes on ``surface_3`` whose value of the ``height`` field are equal to -1.0. The optional field (``height`` in this case) must be a field known in the analysis. This field may be read in from restart, be a native field initialized upon start up, or be an initialized user-defined field. Since the entire set of nodes in ``block_1`` will be in the rigid body, internal forces and critical time steps (for explicit) will not be computed for elements in ``block_1``.

In summary, if a rigid body is used in an analysis, one or more of the following steps must be carried output:

- Include a ``RIGID BODY`` command block in the SIERRA scope. If desired, set reference location, mass, point mass, etc.

- Create a rigid body using one or more element blocks (except ``PARTICLE`` or element blocks). A ``RIGID BODY`` command line must appear in the ``SECTION`` command block used in the ``PARAMETERS FOR BLOCK`` command block for any element block associated with a rigid body.

- Include point mass element blocks with the rigid body if appropriate. To include point mass element blocks in a rigid body, a ``RIGID BODY`` command line must appear in the ``SECTION`` command block used in the ``PARAMETERS FOR BLOCK`` command block for those point mass element blocks.

- Associate an initial velocity or initial rotation about an axis with the rigid body, if appropriate. If any of the blocks associated with a rigid body have been given an initial velocity or initial rotation, the rigid body must have the same specification for the initial velocity or initial rotation.

The above steps involve many different command blocks. To demonstrate how to fully implement a rigid body, a specific example that exercises the various options available to a user is provided.

Suppose it is desired to create a rigid body named ``part_a`` consisting of three element blocks. Two of the element blocks, element block 100 and element block 535, are eight-node hexahedra; one of the element blocks, element block 600, consists of only point masses. The ``RIGID BODY`` command block, ``SECTION`` command block, and the element blocks to be associated with the rigid body are as follows:

.. code-block:: sierrainput

   begin solid section hex_section
     rigid body = part_a
   end
   begin point mass section pm_section
     rigid body = part_a
     volume = 0.1
   end
  
   begin parameters for block block_100
     material = steel
     model = elastic
     section = hex_section
   end
   begin parameters for block block_535
     material = aluminum
     model = elastic
     section = hex_section
   end
   begin parameters for block block_600
     material = mass_for_pointmass
     model = elastic
     section = pm_section
   end

Suppose it is desired to have the rigid body initially rotating at 600 radians/sec about an axis parallel to the :math:`x`-axis and passing through a point at coordinates (0, 10, 20). This axis would be defined using the following set of command lines:

.. code-block:: sierrainput

   define direction parallel_to_x with vector 2.0 0.0 0.0
   define point off_axis with coordinates 0.0 10.0 20.0
   define axis body_axis with point off_axis direction parallel_to_x

The initial angular velocity specification in the ``RIGID BODY`` command block is as follows:

.. code-block:: sierrainput

   begin rigid body part_a
     cylindrical axis = body_axis
     angular velocity = 600
   end rigid body part_a

.. _elements-multrbblock:

Multiple Rigid Bodies from a Single Block
-----------------------------------------

Typically, all the elements in a block are assigned to a single rigid body. However, it is sometimes necessary to define a large number of rigid bodies. It would be unwieldy to create a separate block for each rigid body. To avoid this, it is possible to create an element attribute in the input mesh file that contains an integer ID used to denote the rigid body in which each element should belong. The ``RIGID BODIES FROM ATTRIBUTES`` command is used to associate the attribute with the rigid body IDs. This command must be used in conjunction with the ``RIGID BODY`` command. These commands are used in the context of the section block. They are shown here in the ``SOLID SECTION`` block, but they can be used with any section type that supports rigid bodies.

.. code-block:: sierrainput

   BEGIN SOLID SECTION <string>sec_name
     RIGID BODIES FROM ATTRIBUTES = <integer>first_id to 
       <integer>last_id
     RIGID BODY = <string>rigid_body_name
   END

If the ``RIGID BODIES FROM ATTRIBUTES`` command is used, a series of rigid bodies will be created. These rigid bodies are named using the specified ``rigid_body_name``, followed by an underscore (``_``), and then by an integer ID, which ranges between the specified value of ``first_id`` and ``last_id``. Elements having an attribute value equal to a given ID are added to the corresponding rigid body.

When referencing the rigid body name for to apply boundary conditions, it is important to specify the entire name of the rigid body, including the underscore and ID. For example, a name such as ``part_a_1`` would be used in a boundary condition. Similarly, specific rigid bodies created with ``RIGID BODIES FROM ATTRIBUTES`` can be have rigid body properties ``REFERENCE LOCATION``, ``MASS ``, ``POINT MASS ``, ``INERTIA ``, and ``POINT INERTIA`` set using a name such as ``part_a_1``.

Output
======

Sierra/SM automatically outputs quantities such as displacement for the reference location of the rigid body. The name assigned to a rigid body will be used to construct variable names that give the quantities. This lets the user identify the output associated with a rigid body based on the name assigned to the rigid body.

Immediately before the results file is written, the accelerations for nodes associated with a rigid body are updated to reflect the accelerations due to the rigid-body constraints. This ensures that the accelerations sent to the results output are correct for a given time.

Sierra/SM automatically generates and outputs global data associated with the rigid body (e.g., displacement and quaternion). See :numref:`output-gneregvar` for details on global variable output. Individual field components may be output as discussed in :numref:`output-rb_varoutput` and Table :numref:`tab-output-variables-rb_globvars`. In general the field component ``fieldi`` of the rigid body named ``part_a`` will be written to the output file(s) with the name ``FIELDI_PART_A``.

In addition to being represented in the mesh file by the grouping of element objects that represent the rigid body each rigid body will also be represented by a sphere element. These rigid body elements will be placed in a new element block in the results output file named ``RigidBodyOutputPart``. Net quantities of the rigid body such as rotation rate, net force, and velocity can be plotted on these sphere elements.
