.. _interface-batch:

"""""
batch
"""""


Perform evaluations in batches



**Topics**


concurrency_and_parallelism


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

   interface-batch-size


**Specification**

- *Alias:* None

- *Arguments:* None

- *Default:* sequential interface usage


**Child Keywords:**

+-------------------------+--------------------+--------------------+---------------------------------------------+
| Required/Optional       | Description of     | Dakota Keyword     | Dakota Keyword Description                  |
|                         | Group              |                    |                                             |
+=========================+====================+====================+=============================================+
| Optional                                     | `size`__           | Limit the number of evaluations in a batch  |
+----------------------------------------------+--------------------+---------------------------------------------+

.. __: interface-batch-size.html



**Description**


When the optional ``batch`` keyword is used, Dakota performs
evaluations in batches. In batch mode, Dakota writes the parameters
for multiple (a batch of) evaluations to a single file, invokes
the analysis driver once for the whole batch, and expects
to find results for the entire batch in a single file after
the analysis driver has exited. Batch mode may be useful
when a user desires to take greater control over job management.
For example, the analysis driver can perform the evaluations in
the batch in any sequence or in concurrent sub-batches.

The names of the parameters file and results file are provided
as command line arguments to the analysis driver, just as in
a conventional, non-batch evaluation. By default, all currently
available evaluations will be performed in a single batch, but
the batch size can be limited using the :dakkw:`interface-batch-size`
keyword.

Batch mode has a few important limitations.


- Only one batch at a time may be executed. Asynchronous     execution of multiple concurrent batches is not supported.
- No :dakkw:`interface-analysis_drivers-input_filter` or     :dakkw:`interface-analysis_drivers-output_filter` is permitted.
- Only one ``analysis_driver`` is allowed.
- ``failure_capture`` modes are restricted to     :dakkw:`interface-failure_capture-abort` and     :dakkw:`interface-failure_capture-recover`.

Some of these restrictions may be lifted in future Dakota releases.

*File Formats*

A batch parameters file written by Dakota is simply a
concatenated set of parameters files for the set of evaluations, either
in :dakkw:`interface-analysis_drivers-fork-aprepro` or default Dakota
format.

The batch results file is also a concatenated set of results files
for the individual evaluations. However, because Dakota's results
file format is not as rich as its parameters file format,
evaluations in the batch results file must be separated by a line
that begins with the '#' character.

The order of evaluations in the batch results file must match the order
in the batch parameters file.

*Tagging and Work Directories*

When Dakota's :dakkw:`interface-analysis_drivers-fork-work_directory`
feature is enabled, one directory is created per batch. If
:dakkw:`interface-analysis_drivers-fork-file_tag` or
:dakkw:`interface-analysis_drivers-fork-work_directory-directory_tag`
is used, parameters/results files and work directories are tagged
with a batch Id, which is an integer that begins with 1 and increments
for each new batch.