.. _interface-failure_capture:

"""""""""""""""
failure_capture
"""""""""""""""


Determine how Dakota responds to analysis driver failure



**Topics**



**Default Behavior:** If no failure capturing specification is
provided, then the default behavior is method dependent. For those
iterative algorithms that provide internal failure mitigation
strategies (currently NL2SOL), the default is to transfer the failure
information from the interface back to the algorithm for mitigation,
with no specific action taken by Dakota. For all other algorithms, the
default is to abort.



.. toctree::
   :hidden:
   :maxdepth: 1

   interface-failure_capture-abort
   interface-failure_capture-retry
   interface-failure_capture-recover
   interface-failure_capture-continuation


**Specification**

- *Alias:* None

- *Arguments:* None

- *Default:* abort


**Child Keywords:**

+-------------------------+--------------------+--------------------+---------------------------------------------+
| Required/Optional       | Description of     | Dakota Keyword     | Dakota Keyword Description                  |
|                         | Group              |                    |                                             |
+=========================+====================+====================+=============================================+
| Required (Choose One)   | Failure Mitigation | `abort`__          | (Default) Abort the Dakota job              |
|                         |                    +--------------------+---------------------------------------------+
|                         |                    | `retry`__          | Rerun failed analyses                       |
|                         |                    +--------------------+---------------------------------------------+
|                         |                    | `recover`__        | Substitute dummy values for the responses   |
|                         |                    +--------------------+---------------------------------------------+
|                         |                    | `continuation`__   | Cause Dakota to step toward the failed      |
|                         |                    |                    | "target" simulation from a nearby           |
|                         |                    |                    | successful "source"                         |
+-------------------------+--------------------+--------------------+---------------------------------------------+

.. __: interface-failure_capture-abort.html
__ interface-failure_capture-retry.html
__ interface-failure_capture-recover.html
__ interface-failure_capture-continuation.html



**Description**


Dakota can deal with analysis failure in a few ways.

The first step is that Dakota must detect analysis
failure. Importantly, Dakota always expects a results file to be
written by the analysis driver, even when a failure has occurred. If
the file does not exist when the analysis driver exits, a Dakota error
results, causing Dakota itself to terminate. The analysis driver
communicates an analysis failure to Dakota by writing a results file
beginning with the (case-insensitive) word "fail".  Any file contents
after "fail" are ignored.

Once Dakota detects analysis failure, the failure can be mitigated in four ways:

- :dakkw:`interface-failure_capture-abort` (the default)
- :dakkw:`interface-failure_capture-retry`
- :dakkw:`interface-failure_capture-recover`
- :dakkw:`interface-failure_capture-continuation`

Refer to :ref:`failure` for additional information.