.. _conditions-prescribetemperature:

**********************
Prescribed Temperature
**********************

.. code-block:: sierrainput

   BEGIN PRESCRIBED TEMPERATURE
     #
     # block set commands
     BLOCK = <string list>block_names
     ASSEMBLY = <string list>assembly_names
     INCLUDE ALL BLOCKS
     REMOVE BLOCK = <string list>block_names
     ELEMENT = <int_list>elem_ids       
  
     NODE SET|NODESET = <string list>nodeset_names
     REMOVE NODE SET = <string list>nodeset_names
     NODE = <int_list>node_ids
     #
     # specification command
     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
     # 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
     TEMPERATURE TYPE = SOLID_ELEMENT|SHELL_ELEMENT (SOLID_ELEMENT)
     #
     # coupled analysis commands
     RECEIVE FROM TRANSFER [FIELD TYPE = NODE|ELEMENT(NODE)]
     #
     # additional commands
     SCALE FACTOR = <real>scale_factor(1.0)
     ACTIVE PERIODS = <string list>period_names
     INACTIVE PERIODS = <string list>period_names
   END [PRESCRIBED TEMPERATURE]

The ``PRESCRIBED TEMPERATURE`` command block prescribes a temperature field for a given set of nodes. The prescribed temperature is for each node in the node set. The temperature field may vary over time and space. If the temperature field has only a time-varying component, the function command in the above command block can be used to specify the temperature field. If the temperature field has both time-varying and spatially varying components, a user subroutine option can be used to specify the temperature field. Finally, the temperature may also be read as a variable from the mesh file. Only one of these options---function, user subroutine, or read variable---may be specified in a command block.

Temperature is applied to nodes, but it is frequently used at the element level, such as in the case for thermal strains. If the temperatures are used at the element level, the nodal values are averaged (depending on element) connectivity to produce an element temperature. Consequently, when contiguous element blocks have different temperatures specified then the set of elements on the boundary will have an averaged element temperature due to having different nodal temperatures on a single element.

The temperatures must be defined for all the nodes defining the connectivity for any given element. For this reason, we use block commands to derive a set of nodes at which to define temperatures. If the temperatures are used on an element basis, then the temperature at all the necessary nodes will be defined.

 The ``PRESCRIBED TEMPERATURE`` command block contains four groups of commands---block set, function, user subroutine, and read variable. 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 function command, the user subroutine option, or the read variable option. 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-ptemnode:

Block Set Commands
==================

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

.. code-block:: sierrainput

   BLOCK = <string list>block_names
   ASSEMBLY = <string list>assembly_names
   INCLUDE ALL BLOCKS
   REMOVE BLOCK = <string list>block_names
   ELEMENT = <int_list>elem_ids       
   NODE SET|NODESET = <string list>nodeset_names
   REMOVE NODE SET = <string list>nodeset_names
   NODE = <int_list>node_ids

These command lines, taken collectively, constitute a set of Boolean operators for constructing a set of nodes derived from some combination of element blocks. 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 ``BLOCK``, ``INCLUDE ALL BLOCKS``, ``ELEMENT``, ``ASSEMBLY``, ``NODE SET|NODESET``, or ``NODE`` command line in the command block. Assemblies may contain blocks, nodesets, or assemblies of these.

.. _bou-ptemspec:

Specification Command
=====================

If a simple time-dependent function is used (e.g. piecewise-linear, constant), the temperature at any given time is the same for all nodes associated with the particular ``PRESCRIBED TEMPERATURE`` command block. Alternatively, spatially-varying temperature fields may be achieved through the use of more complex analytic functions. The command line

.. code-block:: sierrainput

   FUNCTION = <string>function_name

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

.. _bou-ptemsub:

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

If the user subroutine option is used, the temperature field may vary spatially at any given time for each of the nodes in the node set associated with the particular ``PRESCRIBED TEMPERATURE`` command block. The user subroutine option allows for a more complex description of the temperature field than does the function command, but also requires writing a user subroutine to implement this capability. The user subroutine will be used to define a temperature 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 temperature 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.

Several other commands control the behavior of user subroutines: ``SUBROUTINE DEBUGGING OFF``, ``SUBROUTINE DEBUGGING ON``, ``SUBROUTINE REAL PARAMETER``, ``SUBROUTINE INTEGER PARAMETER``, and ``SUBROUTINE STRING PARAMETER``. These are described in :numref:`use-comlines`. Examples of using these command lines are provided throughout :numref:`subroutines`. 

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

See :numref:`subroutines` for more details on implementing the user subroutine option. 

.. _bou-ptemdb:

External Mesh Database Commands
===============================

.. 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
   TEMPERATURE TYPE = SOLID_ELEMENT|SHELL_ELEMENT (SOLID_ELEMENT)

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

If temperature is to be prescribed for shell elements, a linear or quadratic thermal gradient can optionally be specified through the thickness of the shells using the ``TEMPERATURE TYPE`` command line. The ``SOLID_ELEMENT`` option to this command is the default behavior, and results in a single temperature being read for each node into the ``temperature`` variable. With the ``SHELL_ELEMENT`` option, temperatures are read into the ``shell_temperature`` variable. Shell elements may potentially define a temperature gradient though the thickness, in which case there will be multiple temperatures at a node to describe the temperature gradient through the shell. The ``TEMPERATURE_TYPE`` command is only valid in conjunction with the ``READ VARIABLE`` command. 

Though-thickness shell temperatures follow the Aria convention. If there is a single shell temperature defined at a node, the temperature is constant through the thickness. 

If there are two shell temperatures defined at a node, the first is the temperature on the bottom of the shell and the second the temperature at the top. The temperature varies linearly between the top and bottom.

If there are three shell temperatures defined at node, the first is the temperature at the bottom of the shell, the second the temperature at the middle of the shell, and the third the temperature at the top of the shell. The temperature varies quadratically through the thickness.

``SOLID_ELEMENT`` and ``SHELL_ELEMENT`` temperatures may be defined simultaneously in the same analysis through two different temperature command blocks. If both are defined, the shell element temperature results override any solid element temperature results on the shell elements. 

.. _bou-tempcouple:

Coupled Analysis Commands
=========================

The ``RECEIVE FROM TRANSFER`` command provides the ability to set the temperature in a coupled analysis by transferring results from another SIERRA code, such as Aria.

.. code-block:: sierrainput

   RECEIVE FROM TRANSFER [FIELD TYPE = NODE|ELEMENT(NODE)]

If this command is used in its default form, it is expected that the temperature is transferred to a nodal field named ``temperature`` in the Sierra/SM region. Sierra/SM performs an interpolation from the nodal field to an element field named ``temperature``. The temperature can also be transferred directly to the element ``temperature`` field by using the optional ``FIELD TYPE = ELEMENT`` argument to this command.

If the ``RECEIVE FROM TRANSFER`` command is used, but the appropriate commands to perform the transfer between the two regions are missing, the temperature will be zero during the entire simulation.

It is also possible to use this line command to cause the initial temperatures obtained from a restart file to remain constant in time.

.. _bou-ptemadd:

Additional Commands
===================

These command lines in the ``PRESCRIBED TEMPERATURE`` 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 temperature values of the field defined by the function command, the user subroutine, or the read variable option. For example, if the temperature in a time history function is given as 100.5 from time 1.0 to time 2.0 and the scale factor is 0.5, then the temperature from time 1.0 to 2.0 is 50.25. 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.
