.. _conditions-gravity:

*******
Gravity
*******

.. code-block:: sierrainput

   BEGIN GRAVITY
     #
     # 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
     INCLUDE ALL BLOCKS
     REMOVE NODE SET = <string list>nodelist_names
     REMOVE SURFACE = <string list>surface_names
     REMOVE BLOCK = <string list>block_names
     #
     DIRECTION = <string>defined_direction
     COMPONENT = <string>X|Y|Z 
  
     FUNCTION = <string>function_name (SIERRA_CONSTANT_FUNCTION_ONE)
     GRAVITATIONAL CONSTANT = <real>g_constant(1.0)
     SCALE FACTOR = <real>scale_factor(1.0)
     EXTERNAL FORCE CONTRIBUTION OUTPUT NAME =
       <string>variable_name
     ACTIVE PERIODS = <string list>period_names
     INACTIVE PERIODS = <string list>period_names
   END [GRAVITY]

A gravity load is generally called a body force boundary condition. A gravity load generates a force at a node that is proportional to the mass of the node. This section describes how to apply a gravity load to a body.

The ``GRAVITY`` command block specifies a gravity load that is applied to all nodes selected within a command block. The gravity load boundary condition uses the function and scale (gravitational constant and scale factor) information to generate a body force at a node based on the mass of the node. Multiple ``GRAVITY`` command blocks can be defined on different sets of nodes. If two different ``GRAVITY`` command blocks reference the same node, the node will have gravity loads applied by both of the command blocks. Care must be taken to make sure multiple gravity loads are not applied to one block if only one gravity load condition is desired.

The ``node set commands`` portion of the ``GRAVITY`` command block defines a set of nodes associated with the gravity load 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
   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``, or ``INCLUDE ALL BLOCKS`` command line in the command block. Assemblies may contain blocks, surfaces, nodesets, or assemblies of these.

The gravity load is specified along an arbitrary user-defined direction, and is defined using the ``DIRECTION`` command line. 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. Alternatively the gravity can be applied along the ``X``, ``Y``, or ``Z`` ``COMPONENT`` directions.

The strength of the gravitational field can be varied with time by using the ``FUNCTION`` command line. This command line references a ``function_name`` defined in the SIERRA scope in a ``FUNCTION`` command block. The gravity force is constant in time if the ``FUNCTION`` command line is not specified.

A gravitational constant is specified by the ``GRAVITATIONAL CONSTANT`` command line in the real value ``g_constant``. For example, the gravitational constant in units of inches and seconds would be 386.4 inches per second squared. This quantity must be set based on the actual units for the model.

The Gravity that will be applied will be a multiplication of ``SCALE FACTOR``, ``GRAVITATIONAL CONSTANT``, and ``FUNCTION`` (:math:`G = SF\times GC \times F`). For example, if ``GRAVITATIONAL CONSTANT`` = 2, ``SCALE FACTOR`` = 2, and ``FUNCTION`` has a constant value of 2 then you will get a constant gravity of 8.

 The dependent variables in the function can be scaled by the real value ``scale_factor`` in the ``SCALE FACTOR`` command line. At any given time, the strength of the gravitational field is a product of the gravitational constant, the value of the function at that time, and the scale factor. 

If the ``EXTERNAL FORCE CONTRIBUTION OUTPUT NAME`` command line appears there will be a variable created with whatever name the user specifies for ``variable_name``. The variable defines a three-dimensional vector at each node associated with this particular command block. The three-dimensional vector at each node represents the external force due solely to just this particular external force boundary contribution.

Once this variable for the external force contribution is specified, it may be used like any other nodal variable. The user can, for example, specify the variable as a nodal variable to be output in a ``RESULTS OUTPUT`` command block. Or the user can reference the variable in a user subroutine.

The ``ACTIVE PERIODS`` and ``INACTIVE PERIODS`` command lines provides an additional option for the gravity load condition. These command lines can activate or deactivate the gravity load for certain time periods. See :numref:`commands-functionality` for more information about these command lines.
