Interface Commands

Interface Commands Table of Contents

Interface Description

The interface section in a DAKOTA input file specifies how function evaluations will be performed in order to map a set of parameters into a set of responses. Function evaluations are performed using either algebraic mappings, interfaces to simulation codes, or a combination of the two.

When employing algebraic mappings, the AMPL solver library [Gay, 1997] 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.

When employing mappings with simulation codes, the simulations may be available internally or externally to DAKOTA. The interface invokes the simulation using either system calls, forks, direct function invocations, or computational grid invocations. In the system call and fork cases, the simulation is external to DAKOTA and communication between DAKOTA and the simulation occurs through parameter and response files. 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 experimental and under development, but is intended to support simulations which are external to DAKOTA and geographically distributed.

Several examples follow. The first example shows a fork interface specification which specifies the names of the analysis executable and the parameters and results files, and that parameters and responses files will be tagged and saved. Refer to Fork interface for more information on the use of these options.

interface,
	fork
	  analysis_drivers = 'rosenbrock'
	  parameters_file  = 'params.in'
	  results_file     = 'results.out'
	  file_tag
	  file_save

The next example shows a similar specification, except that an external rosenbrock executable has been replaced by use of the internal rosenbrock test function from the DirectApplicInterface class. Refer to Direct function interface for more information on this specification.

interface,
	direct
	  analysis_drivers = 'rosenbrock'

The final example demonstrates an interface employing both algebraic and simulation-based mappings. The results from the individual mappings are overlaid based on the variable and response descriptors used by the individual mappings.

interface,
	algebraic_mappings = 'ampl/fma.nl'
	fork
	  analysis_driver = 'text_book'
	  parameters_file = 'tb.in'
	  results_file    = 'tb.out'
	  file_tag
	asynchronous

Interface Specification

The interface specification has the following top-level structure:

interface,
	<interface independent controls>
	<algebraic mappings specification>
	<simulation interface selection>
	  <simulation interface dependent controls>

The <interface independent controls> are those controls which are valid for all interfaces. Referring to dakota.input.summary, these controls are defined externally from the algebraic mappings and simulation interface selection blocks (before and after). Both the algebraic mappings specification and the simulation interface selection are optional specifications, allowing the use of algebraic mappings alone, simulation-based mappings alone, or a combination. The simulation interface selection blocks are all required group specifications separated by logical OR's, where the interface selection must be system, fork, direct, or grid. The <interface dependent controls> are those controls which are only meaningful for a specific simulation interface selection. These controls are defined within each interface selection block. Defaults for interface independent and simulation interface dependent controls are defined in DataInterface. The following sections provide additional detail on the interface independent controls followed by the algebraic mappings specification, the simulation interface selections, and their corresponding simulation interface dependent controls.

Interface Independent Controls

The optional set identifier specification uses the keyword id_interface to input a string for use in identifying a particular interface specification. A model can then identify the use of this interface by specifying the same string in its interface_pointer specification (see Model Commands). For example, a model whose specification contains interface_pointer = 'I1' will use an interface specification with id_interface = 'I1'. If the id_interface specification is omitted, a particular interface specification will be used by a model only if that model omits specifying a interface_pointer and if the interface set was the last set parsed (or is the only set parsed). In common practice, if only one interface set exists, then id_interface can be safely omitted from the interface specification and interface_pointer can be omitted from the model specification(s), since there is no potential for ambiguity in this case.

Table 8.1 summarizes the set identifier interface independent control.

Table 8.1 Specification detail for interface independent controls: set identifier

Description

Keyword

Associated Data

Status

Default

Interface set identifier

id_interface

string

Optional

use of last interface parsed

Table 8.2 summarizes the interface independent controls associated with parallel computing.

Table 8.2 Specification detail for interface independent controls: parallelism

Description

Keyword

Associated Data

Status

Default

Asynchronous interface usage

asynchronous

none

Optional group

synchronous interface usage

Asynchronous evaluation concurrency

evaluation_concurrency

integer

Optional

local: unlimited concurrency, hybrid: no concurrency

Self-schedule local evals

local_evaluation_self_scheduling

none

Optional (1 of 2)

self-scheduled local evals

Static-schedule local evals

local_evaluation_static_scheduling

none

Optional (1 of 2)

self-scheduled local evals

Asynchronous analysis concurrency

analysis_concurrency

integer

Optional

local: unlimited concurrency, hybrid: no concurrency

Number of evaluation servers

evaluation_servers

integer

Optional

no override of auto configure

Self scheduling of evaluations

evaluation_self_scheduling

none

Optional

no override of auto configure

Static scheduling of evaluations

evaluation_static_scheduling

none

Optional

no override of auto configure

Number of analysis servers

analysis_servers

integer

Optional

no override of auto configure

Self scheduling of analyses

analysis_self_scheduling

none

Optional

no override of auto configure

Static scheduling of analyses

analysis_static_scheduling

none

Optional

no override of auto configure

The optional asynchronous flag specifies use of asynchronous protocols (i.e., background system calls, nonblocking forks, POSIX threads) when evaluations or analyses are invoked. The evaluation_concurrency and analysis_concurrency specifications serve a dual purpose:

The optional evaluation_servers and analysis_servers specifications support user overrides of the automatic parallel configuration for the number of evaluation servers and the number of analysis servers. Similarly, the optional evaluation_self_scheduling, evaluation_static_scheduling, analysis_self_scheduling, and analysis_static_scheduling specifications can be used to override the automatic parallel configuration of scheduling approach at the evaluation and analysis parallelism levels. That is, if the automatic configuration is undesirable for some reason, the user can enforce a desired number of partitions and a desired scheduling policy at these parallelism levels. Refer to ParallelLibrary and the Parallel Computing chapter of the Users Manual [Adams et al., 2010] for additional information.

When performing asynchronous local evaluations, the local evaluation scheduling keywords control how new evaluation jobs are dispatched when one completes. If local_evaluation_self_scheduling (default) is specified, each completed evaluation will be replaced by the next in the local evaluation queue. If local_evaluation_static_scheduling is specified, each completed evaluation will be replaced by an evaluation number congruent modulo the evaluation_concurrency. This is helpful for relative node scheduling as described in Dakota/examples/parallelism. For example, assuming only local concurrency (no MPI), if the local concurrency is 7 and job 2 completes, it will be replaced with job 9. This can result in idle processors if runtimes are non-uniform.

Algebraic mappings

If desired, one can define algebraic input-output mappings using the AMPL code [Fourer et al., 2003] and save these mappings in 3 files: stub.nl, stub.col, and stub.row, where stub is a particular root name describing a particular problem. These files names can be communicated to DAKOTA using the algebraic_mappings input. This string may either specify the stub.nl filename, or alternatively, just the stub itself.

DAKOTA then uses stub.col and stub.row to extract the input and output identifier strings and employs the AMPL solver library [Gay, 1997] to process the DAG specification in stub.nl. The variable and objective function names declared within AMPL should be a subset of the variable descriptors and response descriptors used by DAKOTA (see Variables Commands and Response Labels). Ordering is not important, as DAKOTA will reorder data as needed.

Table 8.3 summarizes the algebraic mappings specification.

Table 8.3 Specification detail for algebraic mappings

Description

Keyword

Associated Data

Status

Default

Algebraic mappings file

algebraic_mappings

string

Optional

no algebraic mappings

Simulation interfaces

Each simulation interface uses one or more simulator programs, and optionally filter programs, to perform the parameter to response mapping. The simulator and filter programs are invoked with system calls, forks, direct function calls, or computational grid invocations. In the system call and fork cases, a separate process is created for the simulator program and files are used for transfer of parameter and response data between DAKOTA and the simulator program. This approach is simple and reliable and does not require any modification to simulator programs. In the direct function case, subroutine parameter lists are used to pass the parameter and response data. This approach requires modification to simulator programs so that they can be linked into DAKOTA; however it can be more efficient through the elimination of process creation overhead and deactivation of unnecessary simulator functions (e.g., output), can be less prone to loss of precision in that data can be passed directly rather than written to and read from a file, and can enable completely internal management of multiple levels of parallelism through the use of MPI communicator partitioning. In the grid case, computational grid services are utilized in order to enable distribution of simulations across different computer resources. This capability targets Condor and/or Globus services but is currently experimental and incomplete.

Table 8.4 summarizes the interface independent controls associated with the simulator programs.

Table 8.4 Specification detail for simulation interface controls: drivers, filters, failure capturing, and feature management

Description

Keyword

Associated Data

Status

Default

Analysis drivers

analysis_drivers

list of strings

Required

N/A

Additional identifiers for use by the analysis_drivers

analysis_components

list of strings

Optional

no additional identifiers

Input filter

input_filter

string

Optional

no input filter

Output filter

output_filter

string

Optional

no output filter

Failure capturing

failure_capture

abort | retry (with integer data) | recover (with list of reals data) | continuation

Optional group

abort

Feature deactivation

deactivate

active_set_vector, evaluation_cache, and/or restart_file

Optional group

Active set vector control, function evaluation cache, and restart file features are active

The required analysis_drivers specification provides the names of executable analysis programs or scripts which comprise a function evaluation. The specification can also give values to environment variables that the programs will see; for details, see the subsection on Syntax for Filter and Driver Strings in the Interfaces chapter of the Users Manual [Adams et al., 2010]. The common case of a single analysis driver is simply accommodated by specifying a list of one driver (this also provides backward compatibility with previous DAKOTA versions). The optional analysis_components specification allows the user to provide additional identifiers (e.g., mesh file names) for use by the analysis drivers. This is particularly useful when the same analysis driver is to be reused multiple times for slightly different analyses. The specific content within the strings is open-ended and can involve whatever syntax is convenient for a particular analysis driver. The number of analysis components $n_c$ should be an integer multiple of the number of drivers $n_d$, and the first $n_c/n_d$ component strings will be passed to the first driver, etc. The optional input_filter and output_filter specifications provide the names of separate pre- and post-processing programs or scripts which assist in mapping DAKOTA parameters files into analysis input files and mapping analysis output files into DAKOTA results files, respectively. If there is only a single analysis driver, then it is usually most convenient to combine pre- and post-processing requirements into a single analysis driver script and omit the separate input and output filters. However, in the case of multiple analysis drivers, the input and output filters provide a convenient location for non-repeated pre- and post-processing requirements. That is, input and output filters are only executed once per function evaluation, regardless of the number of analysis drivers, which makes them convenient locations for data processing operations that are shared among the analysis drivers.

Failure capturing in interfaces is governed by the optional failure_capture specification. Supported directives for mitigating captured failures are abort (the default), retry, recover, and continuation. The retry selection supports an integer input for specifying a limit on retries, and the recover selection supports a list of reals for specifying the dummy function values (only zeroth order information is supported) to use for the failed function evaluation. Refer to the Simulation Code Failure Capturing chapter of the Users Manual [Adams et al., 2010] for additional information.

The optional deactivate specification block includes three features which a user may deactivate in order to simplify interface development, increase execution speed, and/or reduce memory and disk requirements:

In addition to these simulation interface specifications, the type of interface involves a selection between system, fork, direct, or grid required group specifications. The following sections describe these group specifications in detail.

System call interface

Users are strongly encouraged to use the fork interface if possible, though the system interface is still supported for portability and backward compatibility. For system call interfaces, the system keyword anchors the group specification and the parameters_file, results_file, verbatim, aprepro, file_tag, and file_save are additional settings within the group specification. The parameters and results file names are supplied as strings using the parameters_file and results_file specifications. Both specifications are optional with the default data transfer files being Unix temporary files with system-generated names (e.g., /usr/tmp/aaaa08861). The parameters and results file names are passed on the command line to the analysis driver(s) and any specified input/output filters, unless the verbatim option is invoked, in which case the driver/filter invocation syntax is used verbatim without command line argument augmentation. For additional information on invocation syntax, see the Interfaces chapter of the Users Manual [Adams et al., 2010]. The format of data in the parameters files can be modified for direct usage with the APREPRO pre-processing tool [Sjaardema, 1992] using the aprepro specification (NOTE: the DPrePro pre-processing utility does not require this special formatting). File tagging (appending parameters and results files with the function evaluation number) and file saving (leaving parameters and results files in existence after their use is complete) are controlled with the file_tag and file_save flags. If these specifications are omitted, the default is no file tagging (no appended function evaluation number) and no file saving (files will be removed after a function evaluation). File tagging is most useful when multiple function evaluations are running simultaneously using files in a shared disk space, and file saving is most useful when debugging the data communication between DAKOTA and the simulation.

By default DAKOTA will remove existing results files before invoking the analysis_driver to avoid problems created by stale files in the current directory. To override this behavior and not delete existing files, specify allow_existing_files.

When performing concurrent evaluations and/or analyses, it is often necessary to cloister input and output files in separate directories to avoid conflicts. When the work_directory feature is enabled, DAKOTA will create a directory for each evaluation/analysis (with optional tagging and saving as with files), and execute the analysis driver from that working directory. If an optional template_directory and/or list of template_files is specified, DAKOTA will link (or copy) those files into each working directory. The specifications for system call interfaces are summarized in Table 8.5.

Table 8.5 Additional specifications for system call interfaces

Description

Keyword

Associated Data

Status

Default

System call interface

system

none

Required group (1 of 4 selections)

N/A

Parameters file name

parameters_file

string

Optional

Unix temp files

Results file name

results_file

string

Optional

Unix temp files

Allow existing results files

allow_existing_results

none

Optional

results files removed before each evaluation

Verbatim driver/filter invocation syntax

verbatim

none

Optional

driver/filter invocation syntax augmented with file names

Aprepro parameters file format

aprepro

none

Optional

standard parameters file format

Parameters and results file tagging

file_tag

none

Optional

no tagging

Parameters and results file saving

file_save

none

Optional

file cleanup

Create work directory

work_directory

none

Optional

no work directory

Name of work directory

named

string

Optional

workdir

Tag work directory

directory_tag

none

Optional

no work directory tagging

Save work directory

directory_save

none

Optional

remove work directory

Template directory

template_directory

string path

Optional

no template directory

Template files

template_files

list of strings

Optional

no template files

Copy template files

copy

none

Optional

link template files

Replace existing files

replace

none

Optional

do not overwrite files

Fork interface

For fork interfaces, the fork keyword anchors a group specification. The parameters_file, results_file, verbatim, aprepro, file_tag, and file_save are additional settings within this group specification and have identical meanings to those for the system call interface as summarized previously in Table 8.5.

Direct function interface

For direct function interfaces, processors_per_analysis is an additional optional setting within the required group which can be used to specify multiprocessor analysis partitions. As with the evaluation_servers, analysis_servers, evaluation_self_scheduling, evaluation_static_scheduling, analysis_self_scheduling, and analysis_static_scheduling specifications described above in Interface Independent Controls, processors_per_analysis provides a means for the user to override the automatic parallel configuration (refer to ParallelLibrary and the Parallel Computing chapter of the Users Manual [Adams et al., 2010]) for the number of processors used for each analysis partition. Note that if both analysis_servers and processors_per_analysis are specified and they are not in agreement, then analysis_servers takes precedence. The direct interface specifications are summarized in Table 8.6.

Table 8.6 Additional specifications for direct function interfaces

Description

Keyword

Associated Data

Status

Default

Direct function interface

direct

none

Required group (1 of 4 selections)

N/A

Number of processors per analysis

processors_per_analysis

integer

Optional

no override of auto configure

DAKOTA supports direct interfaces to a few select simulation codes. One example is ModelCenter, a commercial simulation management framework from Phoenix Integration. To utilize this interface, a user must first define the simulation specifics within a ModelCenter session and then save these definitions to a ModelCenter configuration file. The analysis_components specification provides the means to communicate this configuration file to DAKOTA's ModelCenter interface. A similar direct interface to The Mathworks' (http://www.mathworks.com/) Matlab (specified by analysis_driver = 'matlab' ) enables a user to employ the analysis_components specification to point to a Matlab m-file containing a function that performs the simulation. This capability is disabled by default in DAKOTA binaries, but information on enabling and using it is available in the Users Manual [Adams et al., 2010]. Contact the DAKOTA users mailing list for assistance building and using DAKOTA with Matlab simulation support. An experimental interface to Python simulation codes is also available and can be enabled when compiling DAKOTA from source.

Other direct interfaces to simulation codes include Sandia's SALINAS structural dynamics code, Sandia's SIERRA multiphysics framework, and Sandia's SAGE computational fluid dynamics code, which are available within Sandia and supported to varying degrees. In addition to interfaces with simulation codes, a common usage of the direct interface is for invoking internal test functions which are available for performing parameter to response mappings as inexpensively as possible. These problems are compiled directly into the DAKOTA executable as part of the direct function interface class and are used for algorithm testing. Refer to DirectApplicInterface for currently available testers.

Grid interface

For grid interfaces, no additional specifications are used at this time.

This capability has been used for interfaces with IDEA and JAVASpaces in the past and is currently a placeholder for future work with Condor and/or Globus services. It is not currently operational. The grid interface specification is summarized in Table 8.7.

Table 8.7 Additional specifications for grid interfaces

Description

Keyword

Associated Data

Status

Default

Grid interface

grid

none

Required group (1 of 4 selections)

N/A



Previous chapter

Next chapter

Generated on 30 Nov 2011 for DAKOTA by  doxygen 1.6.1