.. _rve-input:

**************
Input Commands
**************

There are several input commands that are relevant to RVEs. In the reference region, these commands include a special RVE material model and commands to define and use a local coordinate system along which an associated RVE will be aligned. In addition to the reference region, an RVE region is needed using the ``BEGIN RVE REGION`` command block. The RVE region command block uses the same nested commands as any other Sierra/SM region (with some restrictions as explained in this section) and an additional line command that relates the RVEs to their parent elements in the reference region.

.. _rve-input-femodel:

RVE Material Model
==================

.. \index{PARAMETERS FOR MODEL RVE}

In an RVE analysis, any elements of the reference mesh that use an RVE must use the RVE material model.  This model is defined similar to other material models as described in the Sierra/SM User Manual but uses the RVE keyword on the ``BEGIN PARAMETERS FOR MODEL`` command line as follows:

.. code-block:: sierrainput

   BEGIN MATERIAL <string>mat_name
     #
     DENSITY = <real>density_value
     #
     BEGIN PARAMETERS FOR MODEL RVE 
       YOUNGS MODULUS = <real>youngs_modulus
       POISSONS RATIO = <real>poissons_ratio
     END PARAMETERS FOR MODEL RVE
     #
   END [MATERIAL <string>mat_name]

Currently, the RVE material model tells the reference element not to perform a constitutive evaluation but to instead accept the stress tensor obtained from computation on an RVE. However, the use of an RVE material model still requires the input of Young's modulus and Poissons ratio. These values may be used for time step estimation and hourglass computations, even though they are not used in a constitutive evaluation.

Element blocks in the RVE region can use any material model that is supported in Sierra/SM other than RVE.

Embedded Coordinate System
==========================

The finite element model of an element block in the reference mesh that uses RVEs can use an embedded coordinate system to orient the RVE relative to the reference element, if the reference elements are uniform gradient hexes. A coordinate system is defined in the sierra scope as described in the Sierra/SM User Manual. A local coordinate system is then associated with an element block through the use of a ``COORDINATE SYSTEM`` command line within a ``BEGIN SOLID SECTION`` command block.

.. code-block:: sierrainput

   BEGIN SOLID SECTION <string>section_name
     #
     COORDINATE SYSTEM = <string>coord_sys_name
     #
   END [SOLID SECTION <string>section_name]

The string ``coord_sys_name`` must be a name associated in the input file with one of the ``COORDINATE SYSTEM`` command blocks in the sierra scope. This coordinate system will then be used on all elements of a block associated with a ``BEGIN PARAMETERS FOR BLOCK`` command block that includes the command line specifying this solid section.

.. admonition:: Known Issue
   :class: admonition warning

   Currently, the rotation of RVEs to a local element block coordinate system only works with uniform gradient hexes in the reference mesh.

.. _rve-input-rveRegion:

RVE Region
==========

.. \index{RVE REGION}
.. \index{ELEMENTS!in RVE REGION}

A representative volume element (RVE) region must be a quasistatic region specified with the RVE keyword in the ``BEGIN RVE REGION`` command line. The RVE region uses the same block commands and line commands as any other quasistatic region with the addition of line commands that define which element blocks of the reference region are associated with RVEs. There are also some restrictions on boundary conditions as described in :numref:`rve-input-bcs`.

.. code-block:: sierrainput

   BEGIN RVE REGION <string>rve_region_name
      #
      # Definition of RVEs
      ELEMENTS <integer>elem_i:<integer>elem_j 
        <integer>num_intg_pts_per_elem
        BLOCKS <integer>blk_i:<integer>blk_j 
        SURFACE|NODESET <integer> start_id INCREMENT
                  <integer> k
      #
      # Boundary Conditions
      #
      # Results Output Definition
      #
      # Solver Definition
      #
   END [RVE REGION <string>rve_region_name]


.. _rve-input-rveElem:

Definition of RVEs
==================

One or more ``ELEMENTS`` command lines are used to associate elements of the 
reference region mesh with RVEs in the RVE region. In the

.. code-block:: sierrainput

   ELEMENTS <integer>elem_i:<integer>elem_j 
     <integer>num_intg_pts_per_elem
     BLOCKS <integer>blk_i:<integer>blk_j 
     SURFACE|NODESET <integer>start_id INCREMENT 
                     <integer>incr

command line, elements numbered ``elem_i`` through ``elem_j`` of the reference mesh and their ``num_intg_pts_per_elem`` integration points will be associated with RVEs (for a total number of RVEs equal to (``elem_j`` - ``elem_i`` + 1) * ``num_intg_pts_per_elem``), and each RVE will consist of ``blk_i`` - ``blk_j`` + 1 element blocks. Each integration point will be associated with a separate RVE. The block IDs of the first RVE must be ``blk_i`` through ``blk_j`` and subsequent RVEs (if ``elem_j`` is greater than ``elem_i`` or ``num_intg_pts_per_elem`` is greater than 1) must have consecutively increasing numbers for their block IDs. 

Similarly ``start_id`` gives the ``surface_id`` of the first RVE if a single, encompassing surface is used, or the first ``surface_id`` or ``nodelist_id`` of the first RVE (the positive x surface as explained in :numref:`rve-mesh`) if six individual sidesets/nodeset are used. The remaining surfaces (nodesets) of the first RVE and all the surfaces of the following RVEs must be consecutively numbered following ``start_id`` in the mesh file as explained in :numref:`rve-mesh`.

The increment value ``incr`` indicates the number of sidesets present on the exterior of the RVEs.  This is used to determine how to increment the IDs of the sidesets from one RVE to the next and to determine how to prescribe periodic boundary conditions on the RVE.  The increment can have a value of either one or six.  A value of one indicates that each RVE has one sideset that encompasses all six faces, while a value of six specifies that six sidesets or nodesets are present, one on each face. Nodesets are not allowed for the case where ``incr`` is one.

The following example shows the use of the ``ELEMENTS`` command line:

.. code-block:: sierrainput

   elements 1:5 1 blocks 1:2 surface 7 increment 6
   elements 6:6 1 blocks 11:14 nodeset 15 increment 6

These commands generate the RVEs shown in :numref:`fig-rve-mesh`.

The first ``ELEMENTS`` command line specifies that elements with element IDs 1 through 5 in the parent region mesh each have one integration point and that each integration point has an RVE with two element blocks. The RVE associated with the integration point of element 1 of the parent region will have two element blocks starting with ``block_id`` of 1 and ending with a ``block_id`` of 2. Subsequent RVEs will have consecutively numbered element blocks. For example: the integration point of parent element 2 will be associated with an RVE that consists of element blocks 3 and 4 in the RVE region, the integration point of parent element 3 will be associated with the RVE that has element blocks 5 and 6, etc. Again, this is the case for the first five elements of the parent region mesh.  The keyword ``SURFACE`` specifies that all the periodic boundary conditions generated by the code for the RVEs for elements 1 to 5 will use sidesets in the RVE region mesh.  These sidesets will start with id 7 for the positive-x face of the RVE associated with parent element 1 and continue consecutively for the other faces of the RVE and the RVEs associated with the integration points of parent elements 2 through 5 (in the order specified in :numref:`rve-mesh`). In other words, the positive-x face of the RVE for parent element 1 is sideset 7, negative-x is sideset 8, positive-y is sideset 9, negative-y is sideset 10, positive-z is sideset 11, and negative-z is sideset 12. The sidesets for the RVE for parent element 2 will start with id 13 and continue consecutively in the same face order. The process continues for all five RVEs specified in this command line.

The second ``ELEMENTS`` line specifies that the integration point of element 6 of the parent region mesh will be associated with the RVE that consists of element blocks 11, 12, 13, and 14. The ``NODESET`` keyword says this RVE has a nodeset associated with each face of the RVE, starting with nodeset id 15 on the positive-x face, with id's increasing consecutively for the other five faces in the same order described in the paragraph above.

The six elements specified in these command lines must be in element blocks of the reference region mesh that use the RVE material model.

.. _rve-input-mpcs:

Multi-Point Constraints
=======================

In the case in which the RVE has non matching surfaces, and therefore includes a block of membrane elements on the exterior surfaces, the user must specify a set of multi-point constraints (MPCs) to tie the membranes to the surface. This is done in the input file through use of an ``MPC`` command block:

.. code-block:: sierrainput

   RESOLVE MULTIPLE MPCS = ERROR
   BEGIN TIED MPC
     TIED FACES = <string>membrane_surface_id
     TIED NODES = <string>RVE_surface_id
     SEARCH TOLERANCE = <real>tolerance
   END

In this case, the ``membrane_surface_id`` corresponds to the single sideset that encompasses the membrane block is the side-a surface and the single sideset that encompasses the exterior surfaces of the RVE is the side-b surface. While the underlying RVE may have non matching exterior surfaces, the opposing surfaces of the membrane block must have matching discretizations. More detailed information on the use of MPCs, is discussed in the Sierra/SM User Manual.

.. _rve-input-bcs:

RVE Boundary Conditions
=======================

Strain rates computed by elements in the reference region are applied through periodic prescribed velocity boundary conditions on the faces of the associated RVEs. These are generated internally by Sierra/SM so the periodic boundary conditions do not need to be in the user's input file. However, because the RVE region is quasistatic, each of the RVEs must be fixed against rigid body motion. This must be done in the input file through use of the prescribed velocity boundary conditions:

.. code-block:: sierrainput

   BEGIN PRESCRIBED VELOCITY pres_vel_name
     NODE SET = <string>nodelist_name
     FUNCTION = <string>function_name
     SCALE FACTOR = <real>scale_factor
     COMPONENT = <string>X|Y|Z
   END [PRESCRIBED VELOCITY pres_vel_name]

This type of boundary condition is described in detail in the Sierra/SM User Manual but the use for RVEs is restricted- Either the function must always evaluate to 0.0 or the ``scale_factor`` must have a value of 0. This is essentially a way of using the prescribed velocity boundary condition to fix the nodes in ``nodelist_name``. However, in order for these conditions to work with the periodic boundary conditions used to apply the strain rate, ``PRESCRIBED VELOCITY`` must be used rather than ``FIXED DISPLACEMENT`` or ``PRESCRIBED DISPLACEMENT`` boundary conditions.

Generally, three ``BEGIN PRESCRIBED VELOCITY`` command blocks will be needed, one each for X, Y, and Z components. In order to eliminate rigid body motion without over constraining the motion, each ``BEGIN PRESCRIBED VELOCITY`` block should constrain exactly one node of an RVE in one component direction. (However, ``nodelist_name`` may contain nodes from multiple RVEs. Separate boundary condition blocks are not required for each RVE.). To prevent rigid body rotations, the three constrained nodes on each RVE should not be collinear.
