.. _conditions-general:

***********************************
General Boundary Condition Concepts
***********************************

There are general principles that apply to all the available types of boundary conditions. To apply a boundary condition, a set of mesh entities and the magnitude and/or direction in which it is to be applied must be specified. Sierra/SM provides several methods for both specifying the set of mesh entities and for prescribing how the boundary condition is to be applied. The general concepts on how this is done are applicable to all the boundary condition types, and are described in the following sections.

.. _conditions-general-entity:

Mesh-Entity Assignment Commands
=============================== 
   
A number of standard command lines exist to define a set of mesh entities (node, element face, element) associated with some type of boundary, initial, or load condition. All these command lines exist within the command blocks for the various prescribed conditions, which in turn exist within the region scope. These command lines, taken collectively, constitute a set of Boolean operators for constructing sets of mesh entities.

The first set of command lines we will consider is as follows:

.. code-block:: sierrainput

   NODE SET|NODESET = <string list>nodelist_names
   NODE     = <integer list>node_ids

   SURFACE|SIDESET|SIDE SET = <string list>surface_names

   BLOCK = <string list>block_names
   ELEMENT = <integer list>element_ids

   ASSEMBLY = <string list>assembly_names

   RIGID BODY = <string list>rigid_body_names

   INCLUDE ALL BLOCKS

In the above command lines, the string list ``nodelist_names`` is used to represent one or more node sets as discussed in :numref:`introduction-exodus`. A node set is referenced as ``nodelist_id``, where id is some integer. For example, suppose there are three node lists in a model: 10, 23, and 105. To combine all these node lists so that they form one set of nodes for, say, a boundary condition or initial condition, the user would invoke the command line

.. code-block:: sierrainput

   NODE SET = nodelist_10 nodelist_23 nodelist_105

This convention applies as well to any surface-related command line that uses the string list ``surface_names``, any block-related command line that  uses the string list ``block_names``, any assembly-related command line that  uses the string list ``assembly_names``, and any rigid body command line that uses the string list ``rigid_body_names``.

The ``NODE SET|NODESET`` command line associates a set of nodes with an initial, boundary, or load condition. A condition may be applied to multiple node sets by putting multiple node set names on the command line or by repeating the command line multiple times. The ``NODE SET|NODESET`` line may not be used to apply kinematic boundary conditions to a rigid body; a ``BLOCK`` or ``RIGID BODY`` line must be used.

The ``NODE`` line adds individual nodes to the boundary by condition by their nodal ID in the input mesh. Multiple nodes may be specified on one line or this command may be specified multiple times. The ``NODE`` line may not be used to apply kinematic boundary conditions to a rigid body; a ``BLOCK`` or ``RIGID BODY`` line must be used.

The ``ELEMENT`` line adds individual elements to the boundary by condition by their element ID in the input mesh. Multiple elements may be specified on one line or this command may be specified multiple times. The ``ELEMENT`` line may not be used to apply kinematic boundary conditions to a rigid body; a ``BLOCK`` or ``RIGID BODY`` line must be used.

The ``SURFACE|SIDESET|SIDE SET`` command line associates a set of element faces or their attached nodes with a boundary, initial, or load condition. A condition may be applied to multiple surfaces by putting multiple surface names on the command line or by repeating the command line multiple times. For example, suppose we wish to use the fixed displacement kinematic boundary condition. Although this is a nodal boundary condition (the condition is applied to individual nodes), a ``SURFACE`` command line can be used to establish the set of nodes. If the command line

.. code-block:: sierrainput

   SURFACE = surface_101

appears in a fixed displacement boundary condition, then all the nodes associated with surface 101 will be associated with the boundary condition. The ``SURFACE`` line may not be used to apply kinematic boundary conditions to a rigid body; a ``BLOCK`` or ``RIGID BODY`` line must be used.

The ``BLOCK`` command line associates a set of elements and its nodes and faces with a boundary condition. A boundary condition may be applied to multiple blocks by putting multiple block names on the command line or by repeating the command line multiple times. 

For example, suppose we wish to use the fixed displacement kinematic boundary condition as in the previous example. If the command line

.. code-block:: sierrainput

   BLOCK = block_50

appears in a fixed displacement kinematic boundary condition, then all the nodes associated with block 50 will be associated with the boundary condition. 

The ``ASSEMBLY`` command line associates a set of assemblies and its nodes and faces with a boundary condition. A boundary condition may be applied to multiple assemblies by putting multiple assembly names on the command line or by repeating the command line multiple times. For example, the fixed displacement kinematic boundary condition as before can be applied to an assembly with a line command

.. code-block:: sierrainput

   ASSEMBLY = assembly_50

in a fixed displacement kinematic boundary condition. Here, ``assembly_50`` is an assembly containing ``block_50``. Assemblies may contain blocks, surfaces, nodesets, or other assemblies. The prescription of some boundary conditions is limited to certain mesh entity types. This places restrictions on the mesh entity types that an assembly may contain for these boundary conditions. For example, if a boundary condition may only be specified for an element block, a specified assembly may only contain element blocks. 

The ``RIGID BODY`` command line associates the boundary condition with a rigid body. The rigid body must have been defined in the input file within a ``BEGIN RIGID BODY`` command block. See :numref:`elements-functionality-rigid` for an explanation of how to create rigid bodies.

Either a ``BLOCK`` or a ``RIGID BODY`` command line must be used for kinematic boundary conditions on rigid bodies. If the ``block_name`` specified in the ``BLOCK`` line has been defined as a rigid body, or if the ``RIGID BODY`` is used, the specified kinematic condition will be applied to the rigid body reference node. 

The ``INCLUDE ALL BLOCKS`` command line associates all blocks and hence all elements and nodes in the model with a boundary, initial, or load condition. The block command lines associated with boundary conditions, initial conditions, and gravity will NOT generate surfaces.

Any combination of the above command lines can be used to create a union of  mesh entities. Suppose, for example, that the command lines

.. code-block:: sierrainput

   NODE SET = nodelist_2
   SURFACE = surface_3
   NODE = 7 8 15
   ELEMENT = 31

appear in a ``FIXED DISPLACEMENT`` command block for a kinematic boundary condition. The set of nodes associated with the boundary condition will be the union of the set of nodes associated with surface 3, the set of nodes associated with node set 2, the nodes with ids 7, 8 and 15, and the nodes of element 31.

When a union of mesh entities is created by using two or more of the above command lines, a node or element face may appear in more than one node set, surface or block. However, the prescribed condition is applied to each node or face only once. For example, node 67 may be a part of nodelist 2 and surface 3 but the boundary condition will only be applied to node 67 once.

The set of mesh entities associated with a boundary, initial, or load condition can be edited (mesh entities can be deleted from the set) by using the following command lines:

.. code-block:: sierrainput

   REMOVE NODE SET = <string list>nodelist_names
   REMOVE SURFACE = <string list>surface_names
   REMOVE BLOCK = <string list>block_names

The ``REMOVE NODE SET`` command line deletes the nodes in the specified node set from the set of nodes used by the condition.

The ``REMOVE SURFACE`` command line deletes a set of element faces and their associated nodes from the set of element faces used by the prescribed condition. 

The ``REMOVE BLOCK`` command line deletes a set of elements and their associated nodes from the set of elements used by the prescribed condition.

Methods for Specifying Boundary Conditions
==========================================

There are three main methods which can be used to prescribe most types of boundary conditions available in Sierra/SM. 

- The boundary condition can be prescribed using commands in the input file. These commands are categorized as "specification commands" in this document. Depending on the type of the boundary condition, it is necessary to prescribe its direction and/or magnitude. Boundary conditions can be specified this way when a set of mesh entities is to experience a similar condition with a time variation that can be expressed by a function. One of the following commands specifies the direction of the boundary condition: ``COMPONENT``, ``DIRECTION``, ``CYLINDRICAL AXIS``, or ``RADIAL AXIS``. The magnitude is defined using one of ``MAGNITUDE``, ``FUNCTION`` or ``ANGULAR VELOCITY``. These commands are used in various combinations depending on the type of the boundary condition. The details of how to use them are provided in the descriptions of the various boundary condition types.

- If the nature of the boundary condition is such its variation in time and space cannot be described easily by the combination of a function and a direction, it may be necessary to use a user-defined subroutine. User subroutines provide a general capability to define how kinematic or force boundary conditions are applied. The use of user-defined subroutines does increase the complexity of defining the model, however. The user must write and debug the subroutine and compile and link it in with Sierra/SM. Because of the added complexity, user subroutines should only be used if the needed capability is not provided by the other methods of prescribing boundary conditions.

- For some types of boundary conditions, the values of the field to be prescribed can be read in from an existing output database. This is often used as a method to transfer results from one analysis code to another. One of the common uses for this capability is to compute temperatures using a thermal code, and then transfer the temperature fields to Sierra/SM to study combined mechanical and thermal effects. This capability can be used either to read in initial values or to read in a series of values that vary over time.

In the following sections describing specific types of boundary conditions, the commands are grouped according to these three categories. There are three main methods which can be used to prescribe most types of boundary conditions available in Sierra/SM. 

- The boundary condition can be prescribed using commands in the input file. These commands are categorized as "specification commands" in this document. Depending on the type of the boundary condition, it is necessary to prescribe its direction and/or magnitude. Boundary conditions can be specified this way when a set of mesh entities is to experience a similar condition with a time variation that can be expressed by a function. One of the following commands specifies the direction of the boundary condition: ``COMPONENT``, ``DIRECTION``, ``CYLINDRICAL AXIS``, or ``RADIAL AXIS``. The magnitude is defined using one of ``MAGNITUDE``, ``FUNCTION`` or ``ANGULAR VELOCITY``. These commands are used in various combinations depending on the type of the boundary condition. The details of how to use them are provided in the descriptions of the various boundary condition types.

- If the nature of the boundary condition is such its variation in time and space cannot be described easily by the combination of a function and a direction, it may be necessary to use a user-defined subroutine. User subroutines provide a general capability to define how kinematic or force boundary conditions are applied. The use of user-defined subroutines does increase the complexity of defining the model, however. The user must write and debug the subroutine and compile and link it in with Sierra/SM. Because of the added complexity, user subroutines should only be used if the needed capability is not provided by the other methods of prescribing boundary conditions.

- For some types of boundary conditions, the values of the field to be prescribed can be read in from an existing output database. This is often used as a method to transfer results from one analysis code to another. One of the common uses for this capability is to compute temperatures using a thermal code, and then transfer the temperature fields to Sierra/SM to study combined mechanical and thermal effects. This capability can be used either to read in initial values or to read in a series of values that vary over time.

In the following sections describing specific types of boundary conditions, the commands are grouped according to these three categories.
