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 an system call 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 System call interface for more information on the use of these options.

interface,
	system
	  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'
	system
	  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

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. The additional 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 developers for assistance building and using DAKOTA with Matlab simulation support.

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 Thu Dec 2 01:22:53 2010 for DAKOTA by  doxygen 1.4.7