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, <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.
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.
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.
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:
asynchronous
mode, the default concurrency of evaluations and analyses is all concurrency that is available. The evaluation_concurrency
and analysis_concurrency
specifications can be used to limit this concurrency in order to avoid machine overload or usage policy violation.evaluation_concurrency
and analysis_concurrency
specifications, a hybrid parallelism can be selected through combination of message passing parallelism with asynchronous parallelism on each server.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.
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.
Description | Keyword | Associated Data | Status | Default |
Algebraic mappings file | algebraic_mappings | string | Optional | no algebraic mappings |
Table 8.4 summarizes the interface independent controls associated with the simulator programs.
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 should be an integer multiple of the number of drivers
, and the first
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:
deactivate
active_set_vector
specification allows the user to turn off any variability in ASV values so that active set logic can be omitted in the user's simulation interface. This option trades some efficiency for simplicity in interface development. The default behavior is to request the minimum amount of data required by an algorithm at any given time, which implies that the ASV values may vary from one function evaluation to the next. Since the user's interface must return the data set requested by the ASV values, this interface must contain additional logic to account for any variations in ASV content. Deactivating this ASV control causes DAKOTA to always request a "full" data set (the full function, gradient, and Hessian data that is available from the interface as specified in the responses specification) on each function evaluation. For example, if ASV control has been deactivated and the responses section specifies four response functions, analytic gradients, and no Hessians, then the ASV on every function evaluation will be { 3 3 3 3 }, regardless of what subset of this data is currently needed. While wasteful of computations in many instances, this simplifies the interface and allows the user to return the same data set on every evaluation. Conversely, if ASV control is active (the default behavior), then the ASV requests in this example might vary from { 1 1 1 1 } to { 2 0 0 2 }, etc., according to the specific data needed on a particular function evaluation. This will require the user's interface to read the ASV requests and perform the appropriate logic in conditionally returning only the data requested. In general, the default ASV behavior is recommended for the sake of computational efficiency, unless interface development time is a critical concern. Note that in both cases, the data returned to DAKOTA from the user's interface must match the ASV passed in, or else a response recovery error will result. However, when the ASV control is deactivated, the ASV values are invariant and need not be checked on every evaluation. Note: Deactivating the ASV control can have a positive effect on load balancing for parallel DAKOTA executions. Thus, there is significant overlap in this ASV control option with speculative gradients (see Method Independent Controls). There is also overlap with the mode override approach used with certain optimizers (see SNLLOptimizer and SNLLLeastSq) to combine individual value, gradient, and Hessian requests.deactivate
evaluation_cache
specification allows the user to avoid retention of the complete function evaluation history in memory. This can be important for reducing memory requirements in large-scale applications (i.e., applications with a large number of variables or response functions) and for eliminating the overhead of searching for duplicates within the function evaluation cache prior to each new function evaluation (e.g., for improving speed in problems with 1000's of inexpensive function evaluations or for eliminating overhead when performing timing studies). However, the downside is that unnecessary computations may be performed since duplication in function evaluation requests may not be detected. For this reason, this option is not recommended when function evaluations are costly. Note: duplication detection within DAKOTA can be deactivated, but duplication detection features within specific optimizers may still be active.deactivate
restart_file
specification allows the user to eliminate the output of each new function evaluation to the binary restart file. This can increase speed and reduce disk storage requirements, but at the expense of a loss in the ability to recover and continue a run that terminates prematurely (e.g., due to a system crash or network problem). This option is not recommended when function evaluations are costly or prone to failure.system
, fork
, direct
, or grid
required group specifications. The following sections describe these group specifications in detail.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.
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
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.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.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.
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.
Description | Keyword | Associated Data | Status | Default |
Grid interface | grid | none | Required group (1 of 4 selections) | N/A
|