.. _output-fragments:

******************
Identify Fragments
******************

The ``IDENTIFY FRAGMENTS`` capability provides data on unique contiguous mesh fragments in a simulation. Fragments are identified based on mesh connectivity. The fragment identification algorithm accounts for topological changes including element death, element separation in an XFEM simulation. Fragment identification element field ``elem_fragment_id`` and nodal field ``node_fragment_id`` indicate the fragment number for each element and node in the simulation, respectively, and may be output in a results block, allowing for fragment visualization and other post-processing operations. Fragment numbers range from 1 to the total number of fragments, sorted in order of increasing fragment mass. Additional fragment data, including fragment mass and momentum, may be written to an optional output text file.

A nodal vector field ``fragment_force`` is provided to compute force and moment on a per-fragment basis. If using an applied ``pressure`` (:numref:`conditions-force-pressure`), the ``fragment_force`` field can be used as the ``external force contribution output name``. In a ``Zapotec`` coupled analysis the field ``force_to_apply`` might coupled with ``fragment_force`` to report force and moments on the fragments. Otherwise, ``fragment_force`` can be populated through user output methods.

Fragment identification is controlled by the ``BEGIN IDENTIFY FRAGMENTS`` block in the region scope:

.. code-block:: sierrainput

   BEGIN IDENTIFY FRAGMENTS
      OUTPUT FILE = <string>output_filename
      INCREMENT = <real>increment
      MINIMUM FRAGMENT SIZE = <int>min_element_threshold
      START TIME = <real>
   END [IDENTIFY FRAGMENTS]

The optional ``OUTPUT FILE`` command triggers output to a text file named ``output_filename`` containing fragment data. The data written to the text file include the mass, momentum, center of mass, moment of inertia, angular momentum, and names of element blocks present in each fragment. The optional ``MINIMUM FRAGMENT SIZE`` command groups fragments containing fewer than ``min_element_threshold`` elements into a single fragment with ID 0. This feature is useful, for example, in a brittle fracture simulation that results in a significant number of isolated elements. By default, the fragment identification algorithm is executed once per output step. If the optional ``INCREMENT`` command is included in the ``IDENTIFY FRAGMENTS`` block, the fragment identification algorithm is executed only at the corresponding simulation times. For example, if ``INCREMENT`` is assigned a value of 0.23, the fragment identification algorithm will be executed only when the simulation time reaches a multiple of 0.23. Limiting the number of times the fragment identification algorithm is executed reduces the associated computational expense. The optional command ``START TIME`` controls when the fragment data will start to be printed to the output file.

.. warning::

   Fragment identification is performed based only on node-to-element connectivity. If two elements share a node, those two elements are in the same fragment. Other mechanisms to connect elements, such as tied contact, MPCs, spot welds, etc., are not considered in fragment identification at this time.
