.. _ecm-region:

********************
Control Modes Region
********************

.. \index{CONTROL MODES REGION}
.. \index{USE FINITE ELEMENT MODEL!in Control Modes Region}
.. \index{CONTROL BLOCKS!in Control Modes Region}
.. \index{TIME STEP RATIO SCALING!in Control Modes Region}
.. \index{TIME STEP RATIO FUNCTION!in Control Modes Region}
.. \index{HIGH FREQUENCY MASS SCALING!in Control Modes Region}
.. \index{FIXED DISPLACEMENT!in Control Modes Region}

.. code-block:: sierrainput

   BEGIN CONTROL MODES REGION
      #
      # model setup
      USE FINITE ELEMENT MODEL <string>model_name
      CONTROL BLOCKS [WITH <string>coarse_block] = 
                            <string list>control_blocks
      CONTROL ASSEMBLIES [WITH <string>coarse_block] = 
                            <string list>control_assemblies
      #
      # time step control
      TIME STEP RATIO SCALING = <real>cm_time_scale(1.0)
      TIME STEP RATIO FUNCTION = <string>cm_time_func
      LANCZOS TIME STEP INTERVAL = 
                              <integer>lanczos_interval
      POWER METHOD TIME STEP INTERVAL = 
                                 <integer>pm_interval
      #
      # mass scaling
      HIGH FREQUENCY MASS SCALING = 
                               <real>cm_mass_scale(1.0)
   
      #
      # stiffness damping
      HIGH FREQUENCY STIFFNESS DAMPING COEFFICIENT = 
                                <real>cm_stiff_damp(0.0)
      #
      # kinematic boundary condition commands
      BEGIN FIXED DISPLACEMENT
                               # Parameters for 
                               # fixed displacement 
      END [FIXED DISPLACEMENT]
      #
      # output commands
      BEGIN RESULTS OUTPUT <string> results_name
                              # Parameters for 
                              # results output
      END RESULTS OUTPUT <string> results_name
   END [CONTROL MODES REGION]

The ``CONTROL MODES REGION`` command block controls the behavior of the control modes algorithm and is placed alongside a standard ``PRESTO REGION`` command block within the ``PRESTO PROCEDURE`` scope.  With the exception of the ``CONTROL BLOCKS`` and ``CONTROL ASSEMBLIES`` command  line, all the commands that can be used in this block are standard commands  that appear in the Presto region. These commands have the same meaning in  either context- they apply to the coarse mesh or to the reference mesh,  depending on the region block in which they appear. :numref:`exptim-ecmrmdl` through :numref:`exptim-ecmmass` describe the components of the ``CONTROL MODES REGION`` command block.

.. _exptim-ecmrmdl:

Model Setup Commands
====================

.. \index{USE FINITE ELEMENT MODEL!in Control Modes Region!usage in}
.. \index{CONTROL BLOCKS!in Control Modes Region!usage in}
.. \index{CONTROL ASSEMBLIES!in Control Modes Region!usage in}

.. code-block:: sierrainput

   USE FINITE ELEMENT MODEL <string>model_name
   CONTROL BLOCKS [WITH <string>coarse_block] = 
          <string list>control_blocks
   CONTROL ASSEMBLIES [WITH <string>coarse_block] = 
          <string list>control_assemblies

The command lines listed above must appear in the ``CONTROL MODES REGION`` command block if Explicit Control Modes is used.  The ``USE FINITE ELEMENT MODEL`` command line should reference the finite element model for the coarse mesh.  This command line is used in the same way that the command line is used for the reference mesh in the Sierra/SM User Manual.

The ``CONTROL BLOCKS`` and ``CONTROL ASSEMBLIES`` command lines provide a list of blocks or assemblies of blocks in the reference mesh controlled by the coarse mesh.  The block names are listed using the standard format for referencing mesh entities (see the Sierra/SM User Manual). For example, the block with an ID of 1 would be listed as ``block_1`` in this command.  Multiple ``CONTROL BLOCKS`` and ``CONTROL ASSEMBLIES`` command lines may be used.

The ``CONTROL BLOCKS`` and ``CONTROL ASSEMBLIES`` command lines do not require the coarse blocks used to control the fine blocks or fine assemblies of blocks to be listed.  In the following example, blocks :math:`10` and :math:`11` and assemblies :math:`12` and :math:`13` are controlled by the coarse mesh, but the element blocks in the coarse mesh that control those blocks are not listed:

.. code-block:: sierrainput

   CONTROL BLOCKS = block_10 block_11
   CONTROL ASSEMBLIES = assembly_12 assembly_13

If the ``CONTROL BLOCKS`` and ``CONTROL ASSEMBLIES`` command lines are used in this manner, the search for fine nodes contained within coarse elements will be conducted for all elements in the coarse mesh.  The coarse block used to control a given set of fine blocks or assemblies of blocks can optionally be specified by using the ``CONTROL BLOCKS WITH coarse_block`` or ``CONTROL ASSEMBLIES WITH coarse_block`` variants of the command.  For example, the command:

.. code-block:: sierrainput

   CONTROL BLOCKS WITH block_1 = block_10 block_11
   CONTROL ASSEMBLIES WITH block_1 = assembly_12 assembly_13

would use block :math:`1` on the coarse mesh to control blocks :math:`10` and :math:`11` and control assemblies :math:`12` and :math:`13` on the fine mesh. These variants of the commands are necessary  when the coarse blocks or assemblies of blocks overlap. It removes any ambiguity about which coarse elements control which fine nodes. This is particularly useful for contact problems where the fine block or assembly on one side of an interface should be controlled by one block, and the fine block or assembly on the other side of the interface should be controlled by a different block. Only one coarse block can be listed in a given instance of this command.  If there are multiple coarse blocks, they must be listed in separate commands.

Time Step Control Commands
==========================

The time step control commands for Explicit Control Modes are based on the Sierra/SM time step control commands (see the Sierra/SM User Guide).

.. \index{TIME STEP RATIO SCALING!in Control Modes Region!usage in}
.. \index{TIME STEP RATIO FUNCTION!in Control Modes Region!usage in}
.. \index{LANCZOS TIME STEP INTERVAL!in Control Modes Region!usage in}
.. \index{POWER METHOD TIME STEP INTERVAL!in Control Modes Region!usage in}

.. code-block:: sierrainput

   TIME STEP RATIO SCALING = <real>cm_time_scale(1.0)
   TIME STEP RATIO FUNCTION = <string>cm_time_func
   LANCZOS TIME STEP INTERVAL = <integer>lanczos_interval
   POWER METHOD TIME STEP INTERVAL = <integer>pm_interval

The control modes algorithm computes a node-based time step for the coarse mesh at each time step and uses this as the default time step.  This time step is typically larger than the critical time step for the fine mesh.

The ``TIME STEP RATIO SCALING`` and ``TIME STEP RATIO FUNCTION`` command lines allow the user to control the time step used with explicit control modes.  The ``TIME STEP RATIO SCALING`` command specifies a scale factor ``cm_time_scale``, which has a default value of 1.0.  The ``TIME STEP RATIO FUNCTION`` command specifies a function ``cm_time_func`` that is used to control the scale factor as a function of time.  At any given time, a scale factor, :math:`f_{ts}`, is computed by multiplying ``cm_time_scale`` by the current value of the function.  Both of these commands are optional and one can be used without the other.

The time step :math:`\Delta t`, is computed as a function of :math:`f_{ts}`, as well as of the time step of the fine mesh, :math:`\Delta t_f` and the time step of the coarse mesh, :math:`\Delta t_c`.

.. math::

   \Delta t = \Delta t_f + f_{ts}(\Delta t_c-\Delta t_f)

Thus, if the scale factor is zero, the time step of the fine mesh is used, and if it is one, the time step of the coarse mesh is used.

The nodal time step estimator for the coarse mesh typically works well on problems where the fine mesh overlaid by the coarse mesh is essentially isotropic.  In cases where it is not, such as when there are significant voids covered by the coarse mesh, the nodal time step can be non-conservative, resulting in stability problems.  The time step control command lines described above can be used to manually scale down the time step in such scenarios.

Here is an example of stubs for controlling the time step:

.. code-block:: sierrainput

   # Coarse/Fine mesh scaling function.
   begin function cm_time_ratio
     type is piecewise linear
     begin values
       0.0      1.0
       0.005    1.0
       0.01     1.0
     end values
   end
   begin control modes region beamCoarse
       use finite element model beamCoarse
       control blocks = block_1
       filter = mass
       time step ratio scaling = 1.0
       time step ratio function = cm_time_ratio
       high frequency mass scaling = 1.0
   end

This particular example uses the default parameters.  Non-default parameters may be accessed by changing the corresponding :math:`1.0` values.

Alternatively, either the Lanczos or Power Method global time step estimators can be applied to the coarse mesh to give an improved estimate of the stability limit. These are invoked using the ``LANCZOS TIME STEP INTERVAL`` or ``POWER METHOD`` ``TIME STEP INTERVAL`` command lines, respectively. Only one of these command lines can be used at a time, and both commands specify an interval at which the global time step estimate is calculated. When the global time step estimate is calculated, a ratio of the global estimate to the nodal estimate is calculated, and this ratio is used to scale the nodal estimate in subsequent time steps in which the global estimate is not computed.

Experience has shown that the time step predicted by the global time step estimators is typically slightly higher than the actual stability limit. For this reason, it is recommended that a scale factor of :math:`0.9` be used in conjunction with these estimators. This can be set using the ``TIME STEP SCALE FACTOR`` command line in the  ``TIME CONTROL`` block as described in the Sierra/SM User Manual.

.. _exptim-ecmmass:

Mass Scaling Commands
=====================

.. \index{HIGH FREQUENCY MASS SCALING!in Control Modes Region!usage in}

.. code-block:: sierrainput

   HIGH FREQUENCY MASS SCALING = <real>cm_mass_scale(1.0)

The ``HIGH FREQUENCY MASS SCALING`` command line allows the user to control the mass scaling applied to the high frequency component of the response. The mass scaling factor required to stably integrate the high frequency response at the time step being used is computed at every node on the fine mesh. The parameter ``cm_mass_scale`` that can optionally be supplied with this command line is applied as a multiplier to that mass scaling. If that mass scaling (multiplied by ``cm_mass_scale``) is greater than 1.0, then the scaled mass is used at that node. If not, the original nodal mass is used.

It may be useful for some models to use this command line to set ``cm_mass_scale`` to a value greater than 1.0 to stabilize the high frequency response.  Experience has shown, however, that this is rarely needed.

It is also possible to request a consistent coarse mass matrix, instead of the default lumped mass matrix.  
Here is an example illustrating the syntax.

.. code-block:: sierrainput

   begin control modes region beamCoarse
     use finite element model beamCoarse
     control blocks = block_1
     coarse mass linear solver = feti
     coarse mass matrix = consistent
     filter = consistent
     time step ratio scaling = 0.2
   end

Damping Commands
================

.. \index{HIGH FREQUENCY STIFFNESS DAMPING!in Control Modes Region!usage in}

.. code-block:: sierrainput

   HIGH FREQUENCY STIFFNESS DAMPING COEFFICIENT = <real>cm_stiff_damp(0.0)

The ``HIGH FREQUENCY STIFFNESS DAMPING COEFFICIENT`` command is used to apply stiffness-proportional damping on the high frequency portion of the response in Explicit Control Modes.  This may help reduce high frequency noise in problems that have abrupt loading such as that caused by contact. The default value of ``cm_stiff_damp`` is :math:`0.0`.  The value specified for ``cm_stiff_damp`` can be between :math:`0` and :math:`1`.  It is recommended that small values (around 0.001) be specified if this option is used.

Kinematic Boundary Condition Commands
=====================================

.. \index{FIXED DISPLACEMENT!in Control Modes Region!usage in}

.. code-block:: sierrainput

   BEGIN FIXED DISPLACEMENT
          #
          # Parameters for fixed displacement 
          #
   END FIXED DISPLACEMENT

All types of kinematic boundary conditions can be applied to the coarse mesh. This is done by inserting a kinematic boundary condition command block in the ``CONTROL MODES REGION`` command block.  The mesh entity (node set, surface, or block) to which the boundary condition is applied must exist on the coarse mesh.

This capability is potentially useful to ensure better enforcement of kinematic boundary conditions on the fine mesh by applying the same type of boundary condition on the portion of the coarse mesh that overlays the portion of the fine mesh to which boundary conditions are applied.  For example, if there is a node set on the fine mesh that has a fixed displacement boundary condition, a node set can be created on the coarse mesh that covers the same physical domain.  The same fixed displacement boundary condition could then be applied to the coarse mesh.

Although the capability to enforce boundary conditions on the coarse mesh is provided, it is not necessary to do so.  It is also often difficult to create a node set on the coarse mesh that matches the discretization of the node set on the fine mesh.  Users are advised to initially prescribe kinematic boundary conditions only on the fine mesh and only prescribe boundary conditions on the coarse if the initial results appear questionable.

Output Commands
===============

.. \index{RESULTS OUTPUT!in Control Modes Region!usage in}

.. code-block:: sierrainput

   BEGIN RESULTS OUTPUT <string> results_name
          #
          # Parameters for results output
          #
   END RESULTS OUTPUT <string> results_name

Variables can be output from the coarse mesh just as they can from the fine mesh with Explicit Control Modes.  Because the actual results of interest for the model all reside on the fine mesh, it is typically not necessary to output results on the coarse mesh. However, this can be helpful for debugging purposes.

The syntax for the results output for the coarse mesh is identical to that used for output from the fine mesh~\cite{sierraSMUsersGuide}.  The only thing that differentiates the ``RESULTS OUTPUT`` command block for the coarse mesh from that of the fine mesh is that the results output block for the coarse mesh is put in the ``CONTROL MODES REGION`` command block instead of in the ``PRESTO REGION`` command block.  The output files for the coarse and fine mesh must be different from each other, so different output file names must be used within the output blocks for the coarse and fine meshes.

One of the most useful variables to output from the coarse mesh is the nodal ``timestep``.  This variable is similar in nature to the element ``timestep``, which exists on the fine mesh, but is a nodal variable rather than an element variable and exists on the coarse mesh. The nodal ``timestep`` reports the critical time step calculated for each node on the coarse mesh. If the coarse time step is higher than expected, the output from ``nodal_time_step`` can be examined to see which region of the coarse mesh is controlling the time step.

Central difference time integration is performed on the coarse mesh in addition to the fine mesh, so the ``displacement``, ``velocity``, and ``acceleration`` variables can be requested for visualization on the coarse mesh.

.. %\subsection{Open Problems}
.. %Here's a self explanatory code fragment from the test suite.  
.. %\begin{source}
.. %begin control modes region beamCoarse
.. %      use finite element model beamCoarse
.. %      control blocks = block_1
.. %      coarse mass linear solver = feti
.. %      coarse mass matrix = consistent
.. %      filter = consistent
.. %      time step ratio scaling = 0.2
.. %end
.. %begin feti equation solver feti
.. %end
.. %\end{source}
.. %Does anyone know if this actually works?  If so, does the consistent mass matter?

ECM with Lanczos
================

As the known issue suggests that Lanczos works with ECM.  Here's an example.  

.. code-block:: sierrainput

   begin control modes region beamCoarse
     use finite element model beamCoarse
     control blocks = block_1
     filter = mass
     time step ratio scaling = 0.9
     high frequency mass scaling = 1.0
     lanczos time step interval = 100
   end

Assume for clarity that the Lanczos time step size is significantly larger than the element time step size. Initially the element time step in Lanczos is used. At the following time steps, the time step size increases the time step size by a factor of 1.1, the default value of the ``time step increase factor`` described in the Sierra/SM User Manual. When the time step size is near to time Time step from Lanczos method, Lanczos time step, a different time step is used. The maximal time step may depend on time step increase factor and other Lanczos parameters. To compare to Lanczos with no coarse grid, add to the presto region block

.. code-block:: sierrainput

   begin lanczos parameters set1
     number eigenvalues = 50
     eigenvalue convergence tolerance = 1.0e-4
     update step interval = 100
     vector scale = 1.e-8 
     debug = on
   end lanczos parameters set1

In the case at hand, the ECM increases the time step from 4e-7 to 1.5e-6.
