***************
Command Summary
***************

In the specification of the block, one can invoke nonlocality in a state variable :math:`Z` through

.. code-block:: sierrainput

   begin parameters for block block_1
     material ductile_metal
     solid mechanics use model elasto_thermo_visco_poro_plasticity
     section = solid_1
     NONLOCAL REGULARIZATION ON <string>varName WITH LENGTH SCALE = 
     <real>length [AND STAGGERING]
     NONLOCAL REGULARIZATION PARTITIONING SCHEME = 
     {METIS|ZOLTAN_HYPERGRAPH|ZOLTAN_RCB|ZOLTAN_RIB|KMEANS} (ZOLTAN_RCB)

     # Options for k-means clustering

     NONLOCAL REGULARIZATION KMEANS CELL SIZE = <real>cell_size
     NONLOCAL REGULARIZATION KMEANS MAXIMUM ITERATIONS = <int>max_iter	
     NONLOCAL REGULARIZATION KMEANS TOLERANCE = <real>tol
    end parameters for block block_1

where the ``varName`` is the state variable :math:`Z` to be averaged and ``length`` defines the nonlocal volume :math:`V = \text{length}^{3}`. The k-means clustering employs a uniform grid having a size ``cell_size`` and tolerance for convergence ``tol``. The maximum number of iterations for k-means clustering is given by ``max_iter``. One can output the partitions through the ``NONLOCAL_ELEMENT_DOMAIN`` element variable. The output of element variables is described in the Sierra/SM User Manual. In addition, each partition and its volume is noted in the log file. The nonlocal variable :math:`\bar{Z}` can be output through the element variable ``NONLOCAL_varName_AVERAGE`` while the local variable :math:`Z` is output through ``varName``. We remind the reader that material points contain both :math:`Z` and :math:`\bar{Z}`. The energy, stress, and tangent depends on :math:`\bar{Z}`. The constitutive update evolves :math:`Z`. This process, however, is not employed when using ``AND STAGGERING``. In this specific case, local variables are averaged after each time step :math:`t_{n}` and used as the initial conditions for :math:`t_{n+1}`. Strictly speaking, ``AND STAGGERING`` approximates the variational nonlocal method. A fundamental assumption of the nonlocal method is that one is employing a constitutive model in which the state variable update is separate from the evaluation of the energy, stress, or tangent. Currently, only one model in LAMÉ, ``HYPERELASTIC_DAMAGE``, separates these functions. All the other constitutive models, however, update the internal state variables and the stress simultaneously. In an attempt to employ the majority of models that do not adhere to this separation, the ``AND STAGGERING`` option was implemented and does regularize the failure process. This approximation to the nonlocal method is more accurate for small time steps and may require limited hourglass viscosity to stabilize the evolved perturbations (post bifurcation) in uniform-gradient elements. Although we initially envisioned the ``AND STAGGERING`` option to be most applicable to explicit dynamics, simulations with nonlocal damage evolution for implicit dynamics have illustrated mesh-independent solutions.

.. warning::

   The tangent generated in Sierra/SM currently derives from :math:`Z` and is local. Future development will implement a nonlocal, finite-difference tangent.

.. warning::

   Element death for nonlocal domains is work in progress. Additionally this capability will not function with "death on inversion".
