.. _interface:

"""""""""
interface
"""""""""


Specifies how function evaluations will be performed in order to map
the variables into the responses.



**Topics**


block


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

   interface-id_interface
   interface-analysis_drivers
   interface-algebraic_mappings
   interface-failure_capture
   interface-deactivate
   interface-batch
   interface-asynchronous
   interface-evaluation_servers
   interface-evaluation_scheduling
   interface-processors_per_evaluation
   interface-analysis_servers
   interface-analysis_scheduling


**Specification**

- *Alias:* None

- *Arguments:* None


**Child Keywords:**

+-------------------------+--------------------+-------------------------------+-----------------------------------------------+
| Required/Optional       | Description of     | Dakota Keyword                | Dakota Keyword Description                    |
|                         | Group              |                               |                                               |
+=========================+====================+===============================+===============================================+
| Optional                                     | `id_interface`__              | Name the interface block; helpful when there  |
|                                              |                               | are multiple                                  |
+----------------------------------------------+-------------------------------+-----------------------------------------------+
| Optional                                     | `analysis_drivers`__          | Define how Dakota should run a function       |
|                                              |                               | evaluation                                    |
+----------------------------------------------+-------------------------------+-----------------------------------------------+
| Optional                                     | `algebraic_mappings`__        | Use AMPL to define algebraic input-output     |
|                                              |                               | mappings                                      |
+----------------------------------------------+-------------------------------+-----------------------------------------------+
| Optional                                     | `failure_capture`__           | Determine how Dakota responds to analysis     |
|                                              |                               | driver failure                                |
+----------------------------------------------+-------------------------------+-----------------------------------------------+
| Optional                                     | `deactivate`__                | Deactivate Dakota interface features for      |
|                                              |                               | simplicity or efficiency                      |
+-------------------------+--------------------+-------------------------------+-----------------------------------------------+
| Optional (Choose One)   | Optional (Choose   | `batch`__                     | Perform evaluations in batches                |
|                         | One)               +-------------------------------+-----------------------------------------------+
|                         |                    | `asynchronous`__              | Specify local evaluation or analysis          |
|                         |                    |                               | concurrency                                   |
+-------------------------+--------------------+-------------------------------+-----------------------------------------------+
| Optional                                     | `evaluation_servers`__        | Specify the number of evaluation servers when |
|                                              |                               | Dakota is run in parallel                     |
+----------------------------------------------+-------------------------------+-----------------------------------------------+
| Optional                                     | `evaluation_scheduling`__     | Specify the scheduling of concurrent          |
|                                              |                               | evaluations when Dakota is run in parallel    |
+----------------------------------------------+-------------------------------+-----------------------------------------------+
| Optional                                     | `processors_per_evaluation`__ | Specify the number of processors per          |
|                                              |                               | evaluation server when Dakota is run in       |
|                                              |                               | parallel                                      |
+----------------------------------------------+-------------------------------+-----------------------------------------------+
| Optional                                     | `analysis_servers`__          | Specify the number of analysis servers when   |
|                                              |                               | Dakota is run in parallel                     |
+----------------------------------------------+-------------------------------+-----------------------------------------------+
| Optional                                     | `analysis_scheduling`__       | Specify the scheduling of concurrent analyses |
|                                              |                               | when Dakota is run in parallel                |
+----------------------------------------------+-------------------------------+-----------------------------------------------+

.. __: interface-id_interface.html
__ interface-analysis_drivers.html
__ interface-algebraic_mappings.html
__ interface-failure_capture.html
__ interface-deactivate.html
__ interface-batch.html
__ interface-asynchronous.html
__ interface-evaluation_servers.html
__ interface-evaluation_scheduling.html
__ interface-processors_per_evaluation.html
__ interface-analysis_servers.html
__ interface-analysis_scheduling.html



**Description**


The interface section in a Dakota input file specifies how function
evaluations will be performed in order to map the variables into the
responses.  The term "interface" refers to the bridge between Dakota
and the underlying simulation code.

In this context, a "function evaluation" is the series of operations
that takes the variables and computes the responses. This can be
comprised of one or many codes, scripts, and glue, which are
generically referred to as "analysis drivers" (and optional
input/output filters).  The mapping actions of
:dakkw:`interface-analysis_drivers` may be combined with explicit
:dakkw:`interface-algebraic_mappings`

*Parallelism Options*


- The :dakkw:`interface-asynchronous` keyword enables concurrent local     function evaluations or analyses via operating system process     management.  Its child keywords allow tailoring the evaluation and     analysis concurency.
- The evaluation servers, scheduling mode (master, peer static or     dynamic), and processor keywords allow a user to override Dakota's     default evaluation configuration when running in parallel (MPI)     mode.
- The analysis servers and scheduling mode (master, peer static or     dynamic) keywords allow a user to override Dakota's default     analysis configuration when running in parallel (MPI) mode.

Note: see :dakkw:`interface-analysis_drivers-direct` for the specific
``processors_per_analysis`` specification supported for direct
interfaces.

The ParallelLibrary class and the :ref:`Parallel Computing section <parallel>`
provide additional details on parallel configurations.



**Theory**


Function evaluations are performed using either interfaces to
simulation codes, algebraic mappings, or a combination of the two.

When employing mappings with simulation codes, the interface invokes
the simulation using either forks, direct function invocations, or
computational grid invocations.


- In the fork case, Dakota will treat the simulation as a black-box  and communication between Dakota and the simulation occurs through  parameter and result files. This is the most common case.


- In the direct function case, the simulation is internal to Dakota  and communication occurs through the function parameter list. The  direct case can involve linked simulation codes or test functions  which are compiled into the Dakota executable. The test functions  allow for rapid testing of algorithms without process creation  overhead or engineering simulation expense.


- The grid case is deprecated, but was an experiment in interfacing  Dakota to distributed computing engines.

When employing algebraic mappings, the AMPL solver library :cite:p:`Gay97`
is used to evaluate a directed acyclic graph (DAG) specification from
a separate stub.nl file. Separate stub.col and stub.row files are also
required to declare the string identifiers of the subset of inputs and
outputs, respectively, that will be used in the algebraic mappings.