.. _output-breach:

*************
Detect Breach
*************

The breach detection capability enables automatic detection of a breach creating an open path between two user-defined surfaces via element. This capability can be used to predict when venting of a pressure vessel begins due to an open crack. The ``BEGIN DETECT BREACH`` block is defined in the region scope with the following command block:

.. code-block:: sierrainput

   BEGIN DETECT BREACH <string>breachName
     SURFACE1 = <string list>surface1_names
     ASSEMBLY1 = <string list>assembly1_names
     SURFACE2 = <string list>surface2_names
     ASSEMBLY2 = <string list>assembly2_names
   END [DETECT BREACH]

The ``breachName`` string is required, as it defines a global variable with the same name that initializes to 0 and changes to 1 when breach is detected. Within the ``DETECT BREACH`` block, two line commands are required: ``surface1 = sideset1 sideset2 ...`` or ``assembly1 = assembly1_1 assembly1_2 ...`` and ``surface2 = sideset3 sideset4 ...`` or ``assembly2 = assembly2_1 assembly2_2 ...``. Assemblies used for ``assembly1`` and ``assembly2`` may contain surfaces, or assemblies of these. These command lines set the "inner" and "outer" surfaces for detecting breach between. An arbitrary number of detect breach blocks are allowed.

The algorithm is implemented by identifying clusters of dead elements. If two dead elements share a node, then they are considered to be in the same cluster. (An alternative implementation could consider dead elements to be in the same cluster only when they share a face; however, that is not the version currently implemented.)  If a cluster of dead elements has an adjacent face in both ``surface_1`` and ``surface_2``, then we say breach has occurred between those surfaces (see Figure  :numref:`fig-breach1`).

.. _fig-breach1:

.. figure:: ../../_static/figures/breach_detection.png
   :align: center
   :scale: 15 %

   Breach detection between surfaces 1 and 2. Dead elements in red.

The death cluster id number can be output as either an element or nodal variable named ``dead_element_cluster_id``. The nodal variable version is only used for implementing the clustering algorithm, but the element variable ``dead_element_cluster_id`` can be output and used by analyst scripts to compute quantities of interest for the dead element clusters such as the volume, minimum cross-sectional area, moments of inertia, etc.

.. warning::

   This capability is currently only tested for bulk 3D elements such as hexahedra and tetrahedra. The capability will not work with shells. Additionally, the capability has no knowledge of tied contacts; thus a breach can only propagate between mesh-contiguous elements.

.. warning::

   If using detect breach variables such as the ``dead_element_cluster_id`` element variable in a user output you must add "process elements = all" to your user output block.
