.. _conditions-pore:

*************
Pore Pressure
*************

.. code-block:: sierrainput

   BEGIN PORE PRESSURE
     #
     # block set commands
     BLOCK = <string list>block_names
     ASSEMBLY = <string list>assembly_names
     INCLUDE ALL BLOCKS
     REMOVE BLOCK = <string list>block_names
     #
     # specification command
     FUNCTION = <string>function_name
     #
     # user subroutine commands
     ELEMENT BLOCK 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
     #
     # 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 [PORE PRESSURE]

The ``PORE PRESSURE`` command block prescribes a pore pressure field for a given set of elements. The pore pressure is prescribed for each element in the block. The pore pressure field may vary over time and space. If the pore pressure field has only a time-varying component, the function command in the above command block can be used to specify the pore pressure field. If the pore pressure field has both time-varying and spatially varying components, a user subroutine option can be used to specify the pore pressure field. Finally, the pore pressure can 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.

The ``PORE PRESSURE`` 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.

Biot's coefficient can be defined when prescribing pore pressure. See :numref:`materials-commands-biot` for more information on Biot's coefficient.

.. _bou-poreelem:

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

The ``block set commands`` portion of the ``PORE PRESSURE`` command block defines a set of elements associated with the pore pressure field and can include a 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

These command lines, taken collectively, constitute a set of Boolean operators for constructing a set of elements 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 elements used by the boundary condition. There must be at least one ``BLOCK``, ``ASSEMBLY``, or ``INCLUDE ALL BLOCKS`` command line in the command block. Assemblies may contain blocks, surfaces, nodesets, or assemblies of these.

.. _bou-porespec:

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

If the ``FUNCTION`` command is used, the pore pressure at any given time is the same for all elements in the element set associated with the particular ``PORE PRESSURE`` command block, with the exception of analytic functions which provide the ability to define a spatially-varying field. 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 pore pressure as a function of time. The pore pressure can be scaled using the ``SCALE FACTOR`` command line described in :numref:`bou-poreadd`.

.. _bou-poresub:

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

If the user subroutine option is used, the pore pressure field may vary spatially at any given time for each of the elements in the element set associated with the particular ``PORE PRESSURE`` command block. The user subroutine option allows for a more complex description of the pore pressure field than does the ``FUNCTION`` command, but the user subroutine option also requires that a user subroutine be written to implement this capability. The user subroutine will be used to define a pore pressure for every element to which the boundary condition will be applied. The subroutine will be called by Sierra/SM at the appropriate time to generate the pore pressure field. 

Following are the command lines related to the user subroutine option:

.. code-block:: sierrainput

   ELEMENT BLOCK 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 ``ELEMENT BLOCK 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 pore pressure set in the user subroutine can be scaled by use of the ``SCALE FACTOR`` command line, as described in :numref:`bou-poreadd`.

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

.. _bou-poredb:

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

The pore pressure field can be read from an external mesh database. The finite element model from which pore pressures are read is defined via the ``FINITE ELEMENT MODEL`` command block described in :numref:`elements-fem`. The finite element model can either be the model used by the region for its mesh definition as specified with the ``USE FINITE ELEMENT MODEL`` command (see :numref:`commands-fem`), or it can be a different (but compatible) model. The following command lines control the use of an external mesh database to prescribe the pore pressure:

.. 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
    
See :numref:`conditions-variable-extmesh` for more details.

.. _bou-poreprescouple:

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

The ``RECEIVE FROM TRANSFER`` command provides the ability to set the pore pressure 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 pore pressure is transferred to a nodal field named ``pore_pressure`` in the Sierra/SM region. Sierra/SM performs an interpolation from the nodal field to an element field named ``pore_pressure``. The pore pressure can also be transferred directly to the element ``pore_pressure`` 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 pore pressure will be zero during the entire simulation.

.. _bou-poreadd:

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

These command lines in the ``PORE PRESSURE`` 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 pore pressure values of the field defined by the function command, the user subroutine, or the read variable option. For example, if the pore pressure 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 pore pressure 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.
