/**
\mainpage

The %Dakota software (http://dakota.sandia.gov/) delivers advanced
parametric analysis techniques enabling quantification of margins and
uncertainty, risk analysis, model calibration, and design exploration
with computational models.  Its methods include optimization,
uncertainty quantification, parameter estimation, and sensitivity
analysis, which may be used individually or as components within
surrogate-based and other advanced strategies.

\author Brian M. Adams, William J. Bohnhoff, Robert A. Canfield,
Wesley P. Coomber, Keith R. Dalbey, Mohamed S. Ebeida, John P. Eddy,
Michael S. Eldred, Gianluca Geraci, Russell W. Hooper, Patricia
D. Hough, Kenneth T. Hu, John D. Jakeman, Carson Kent, Mohammad Khalil,
Kathryn A. Maupin, Jason A. Monschke, Teresa Portone, Elliott M. Ridgway,
Ahmad A. Rushdi, D. Thomas Seidl, J. Adam Stephens, Laura P. Swiler,
Anh Tran, Dena M. Vigil, Timothy M. Wildey, and Justin G. Winokur;
with Friedrich Menhorn and Xiaoshu Zeng

<!-----
 %Dakota contains algorithms for:
\li optimization with gradient and nongradient-based
methods
\li uncertainty quantification with sampling, reliability,
stochastic expansion, and interval estimation methods
\li parameter estimation with nonlinear least squares methods
\li sensitivity/variance analysis with design of experiments and parameter
study capabilities
\li Bayesian calibration approaches

These capabilities may be used on their own
or as components within advanced algorithms such as: 
\li surrogate-based optimization
\li mixed integer nonlinear programming
\li mixed aleatory-epistemic uncertainty quantification
\li or optimization under uncertainty
----->

The Reference Manual documents all the input keywords that can appear
in a %Dakota input file to configure a %Dakota study.  Its
organization closely mirrors the structure of \c
dakota.input.summary. For more information see \ref input_spec.  For
information on software structure, refer to the Developers Manual
\cite DevMan, and for a tour of %Dakota features and capabilities,
including a tutorial, refer to the User's Manual \cite UsersMan.

Dakota 6.14 and newer include a refreshed Examples Library, ranging
from examples of Dakota input files and basic studies through complete
case studies. These can be found in binary distributions in \c
dakota/share/dakota/examples/official (\c dakota/dakota-examples in
source distributions). Legacy examples, including many from the Dakota
software manuals appear in other directories in \c
dakota/share/dakota/examples (\c dakota/examples for source).

\section main-how_to How to Use this Manual

\li To learn how to run Dakota from the command line, see \subpage running_dakota
\li To learn to how to restart Dakota studies, see \ref dakota_restart
\li To learn about the Dakota restart utility, see \ref dakota_restart_utility

To find more information about a specific keyword
-# Use the search box at the top right (currently only finds keyword names)
-# Browse the Keywords tree on the left navigation pane
-# Look at the \subpage input_spec
-# Navigate through the keyword pages, starting from the \subpage keywords

To find more information about a Dakota related topic
-# Browse the Topics Area on the left navigation pane
-# Navigate through the topics pages, starting from the \subpage topics

A small number of examples are included (see \ref input_file_examples)
along with a description of the test problems (see \ref test_problems).

A bibliography for the Reference Manual is provided in 
\ref citelist


<!--------------------------------------------------------->

\page running_dakota Running Dakota

The Dakota executable file is named \c dakota (\c dakota.exe on
Windows) and is most commonly run from a terminal or command prompt.

\section running_dakota-usage Usage

If the \c dakota command is entered at the command prompt without any
arguments, a usage message similar to the following appears:
\verbatim
usage: dakota [options and <args>]
	-help (Print this summary)
	-version (Print DAKOTA version number)
	-input <$val> (REQUIRED DAKOTA input file $val)
	-preproc [$val] (Pre-process input file with pyprepro or tool $val)
	-output <$val> (Redirect DAKOTA standard output to file $val)
	-error <$val> (Redirect DAKOTA standard error to file $val)
	-parser <$val> (Parsing technology: nidr[strict][:dumpfile])
	-no_input_echo (Do not echo DAKOTA input file)
	-check (Perform input checks)
	-pre_run [$val] (Perform pre-run (variables generation) phase)
	-run [$val] (Perform run (model evaluation) phase)
	-post_run [$val] (Perform post-run (final results) phase)
	-read_restart [$val] (Read an existing DAKOTA restart file $val)
	-stop_restart <$val> (Stop restart file processing at restart record $val)
	-write_restart [$val] (Write a new DAKOTA restart file $val)
\endverbatim

Of these command line options, only \c input is required, and the \c
-input switch can be omitted if the input file name is the final item
appearing on the command line (see Examples); all other command-line
inputs are optional.

\li \c help prints the usage message above. 

\li \c version prints version information for the executable.

\li \c check invokes a dry-run mode in which the input file is processed and
checked for errors, but the study is not performed.

\li \c input provides the name of the Dakota input file, which can
optionally be pre-processed as a template using the \c preproc option.

\li \c output and \c error options provide file
names for redirection of the Dakota standard output (stdout) and
standard error (stderr), respectively.

\li The \c parser option is for debugging and will not be further described here.

\li  By default, Dakota will echo the input file to the output stream, but 
\c no_input_echo can override this behavior.

\li \c read_restart and \c write_restart commands provide the names of
restart databases to read from and write to, respectively.

\li \c stop_restart command limits the number of restart records
read from the restart database (the default is all the records)
for those cases in which some evaluations were erroneous or
corrupted. Restart records are recorded in order of completion.
Restart management is an important technique for retaining
data from expensive engineering applications.

\li \c -pre_run, \c -run, and \c -post_run instruct Dakota to run one
or more execution phases, excluding others.  The commands must be
followed by filenames as described in \ref running_dakota-phases.

Command line switches can be abbreviated so long as the abbreviation
is unique, so the following are valid, unambiguous specifications: \c
-h, \c -v, \c -c, \c -i, \c -o, \c -e, \c -s, \c -w, \c -re, \c -ru,
and \c -po and can be used in place of the longer forms of the command
line options.

For information on restarting Dakota, see \subpage dakota_restart and
\subpage dakota_restart_utility.

\section running_dakota-examples Examples
 
To run Dakota with a particular input file, the following syntax can
be used:
\verbatim
    dakota -i dakota.in
\endverbatim
or more simply
\verbatim
    dakota dakota.in
\endverbatim

This will echo the standard output (stdout) and standard error
(stderr) messages to the terminal. To redirect stdout and stderr to
separate files, the \c -o and \c -e command line options
may be used:
\verbatim
    dakota -i dakota.in -o dakota.out -e dakota.err
\endverbatim
or
\verbatim
    dakota -o dakota.out -e dakota.err dakota.in
\endverbatim

Alternatively, any of a variety of Unix redirection variants can be
used. Refer to \cite And86 for more information on Unix redirection.
The simplest of these redirects stdout to another file:
\verbatim
    dakota dakota.in > dakota.out
\endverbatim

The specified Dakota input file may instead be an
dprepro/aprepro-style template file to be pre-processed prior to
running Dakota. For example it might contain template expressions in
curly braces:
\verbatim
# {MyLB = 2.0} {MyUB = 8.6}
variables
  uniform_uncertain 3
    upper_bounds {MyUB} {MyUB} {MyUB}
    lower_bounds {MyLB} {MyLB} {MyLB}
\endverbatim

(See the Interfaces chapter in the Dakota User's Manual \cite UserMan
for more information and use cases.) To pre-process the input file,
specify the \c preproc flag which generates an intermediate temporary
input file for use in Dakota. If Dakota's pyprepro.py utility is not
available on the execution PATH and/or additional pre-processing
options are needed, the tool location and syntax can be specified, for
example:

\verbatim
# Assumes pyprepro.py is on PATH:
dakota -i dakota_rosen.tmpl -preproc

# Specify path/name of pre-processor:
dakota -i dakota_rosen.tmpl \
  -preproc "/home/user/dakota/bin/pyprepro"

# Specify Python interpreter to use, for example on Windows
dakota -i dakota_rosen.tmpl -preproc "C:/python27/python.exe \
  C:/dakota/6.10/bin/pyprepro/pyprepro.py"

# Specify additional options to pyprepro, e.g., include file:
dakota -i dakota_rosen.tmpl -preproc "pyprepro.py -I default.params"
\endverbatim 

\section running_dakota-phases Execution Phases

Dakota has three execution phases: \c pre-run, \c run, and \c post-run.
\li \c pre-run can be used to generate variable sets
\li \c run (core run) invokes the simulation to
evaluate variables, producing responses
\li \c post-run accepts
variable/response sets and analyzes the results (for example,
calculate correlations from a set of samples). Currently only two
modes are supported and only for sampling, parameter study, and DACE
methods:

(1) pre-run only with optional tabular output of variables:
\verbatim
    dakota -i dakota.in -pre_run [::myvariables.dat]
\endverbatim

(2) post-run only with required tabular input of variables/responses:
\verbatim
    dakota -i dakota.in -post_run myvarsresponses.dat::
\endverbatim

<!--------------------------------------------------------->

\page dakota_restart Restarting Dakota Studies

Dakota is often used to solve problems that require repeatedly running
computationally expensive simulation codes. In some cases you may want
to repeat an optimization study, but with a tighter final convergence
tolerance. This would be costly if the entire optimization analysis
had to be repeated. Interruptions imposed by computer usage policies,
power outages, and system failures could also result in costly
delays. However, Dakota automatically records the variable and
response data from all function evaluations so that new executions of
Dakota can pick up where previous executions left off.  The Dakota
restart file (\c dakota.rst by default) archives the tabulated
interface evaluations in a binary format. The primary restart commands
at the command line are \c -read_restart, \c -write_restart, and \c
-stop_restart.

\section dakota_restart-writing Writing Restart Files

To write a restart file using a particular name, the
\c -write_restart command line input (may be abbreviated as
\c -w) is used:
\verbatim
    dakota -i dakota.in -write_restart my_restart_file
\endverbatim
If no \c -write_restart specification is used, then Dakota will
still write a restart file, but using the default name
\c dakota.rst instead of a user-specified name.

To turn restart recording off, the user may use the 
\ref interface-deactivate-restart_file keyword, in the \c
interface block.  This can increase execution 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. This option is
not recommended when function evaluations are costly or prone to
failure. Please note that using the \c deactivate \c restart_file
specification will result in a zero length restart file with the
default name dakota.rst, which can overwrite an exiting file.

\section dakota_restart-using Using Restart Files

To restart Dakota from a restart file, the \c -read_restart
command line input (may be abbreviated as \c -r) is used:
\verbatim
    dakota -i dakota.in -read_restart my_restart_file
\endverbatim

If no \c -read_restart specification is used, then Dakota will
not read restart information from any file (i.e., the default is no
restart processing).

To read in only a portion of a restart file, the
\c -stop_restart control (may be abbreviated as \c -s) is
used to specify the number of entries to be read from the
database. Note that this integer value corresponds to the restart
record processing counter (as can be seen when using the
\c print utility (see \ref dakota_restart_utility)
which may differ from the evaluation numbers used in the previous run
if, for example, any duplicates were detected (since these duplicates
are not recorded in the restart file). In the case of a
\c -stop_restart specification, it is usually desirable to
specify a new restart file using \c -write_restart so as to
remove the records of erroneous or corrupted function evaluations. For
example, to read in the first 50 evaluations from
\c dakota.rst:
\verbatim
    dakota -i dakota.in -r dakota.rst -s 50 -w dakota_new.rst
\endverbatim

The \c dakota_new.rst file will contain the 50 processed
evaluations from \c dakota.rst as well as any new evaluations.
All evaluations following the \f$50^{\mathrm{th}}\f$ in \c dakota.rst
have been removed from the latest restart record.

\section dakota_restart-appending Appending to a Restart File

If the \c -write_restart and \c -read_restart
specifications identify the same file (including the case where
\c -write_restart is not specified and \c -read_restart
identifies \c dakota.rst), then new evaluations will be appended
to the existing restart file.

\section dakota_restart-multiples Working with multiple Restart Files


If the \c -write_restart and
\c -read_restart specifications identify different files, then
the evaluations read from the file identified by
\c -read_restart are first written to the
\c -write_restart file. Any new evaluations are then appended
to the \c -write_restart file. In this way, restart operations
can be chained together indefinitely with the assurance that all of
the relevant evaluations are present in the latest restart file.

\section dakota_restart-works How it Works


Dakota's restart algorithm relies on its duplicate detection
capabilities. Processing a restart file populates the list of function
evaluations that have been performed. Then, when the study is
restarted, it is started from the beginning (not a warm start) and
many of the function evaluations requested by the iterator are
intercepted by the duplicate detection code. This approach has the
primary advantage of restoring the complete state of the iteration
(including the ability to correctly detect subsequent duplicates) for
all methods/iterators without the need for
iterator-specific restart code. However, the possibility exists for
numerical round-off error to cause a divergence between the
evaluations performed in the previous and restarted studies. This has
been rare in practice.

<!--------------------------------------------------------->

\page dakota_restart_utility The Dakota Restart Utility

The Dakota restart utility program provides a variety of facilities
for managing restart files from Dakota executions. The executable
program name is \c dakota_restart_util and it has the
following options, as shown by the usage message returned when
executing the utility without any options:
\verbatim
Usage:
  dakota_restart_util command <arg1> [<arg2> <arg3> ...] --options
    dakota_restart_util print <restart_file>
    dakota_restart_util to_neutral <restart_file> <neutral_file>
    dakota_restart_util from_neutral <neutral_file> <restart_file>
    dakota_restart_util to_tabular <restart_file> <text_file>
      [--custom_annotated [header] [eval_id] [interface_id]] 
      [--output_precision <int>]
    dakota_restart_util remove <double> <old_restart_file> <new_restart_file>
    dakota_restart_util remove_ids <int_1> ... <int_n> <old_restart_file> <new_restart_file>
    dakota_restart_util cat <restart_file_1> ... <restart_file_n> <new_restart_file>
options:
  --help                       show dakota_restart_util help message
  --custom_annotated arg       tabular file options: header, eval_id, 
                               interface_id
  --freeform                   tabular file: freeform format
  --output_precision arg (=10) set tabular output precision
\endverbatim

Several of these functions involve format conversions. In particular,
the binary format used for restart files can be converted to ASCII
text and printed to the screen, converted to and from a neutral file
format, or converted to a tabular format for importing into 3rd-party
plotting programs. In addition, a restart file with corrupted data can
be repaired by value or id, and multiple restart files can be combined
to create a master database.

\section dakota_restart_utility-print Print Command

The \c print option is useful to show contents of a restart file,
since the binary format is not convenient for direct inspection. The
restart data is printed in full precision, so that exact matching of
points is possible for restarted runs or corrupted data removals. For
example, the following command \verbatim dakota_restart_util print
dakota.rst \endverbatim

results in output similar to the following:
\verbatim
    ------------------------------------------
    Restart record    1  (evaluation id    1):
    ------------------------------------------
    Parameters:
                          1.8000000000000000e+00 intake_dia
                          1.0000000000000000e+00 flatness

    Active response data:
    Active set vector = { 3 3 3 3 }
                         -2.4355973813420619e+00 obj_fn
                         -4.7428486677140930e-01 nln_ineq_con_1
                         -4.5000000000000001e-01 nln_ineq_con_2
                          1.3971143170299741e-01 nln_ineq_con_3
     [ -4.3644298963447897e-01  1.4999999999999999e-01 ] obj_fn gradient
     [  1.3855136437818300e-01  0.0000000000000000e+00 ] nln_ineq_con_1 gradient
     [  0.0000000000000000e+00  1.4999999999999999e-01 ] nln_ineq_con_2 gradient
     [  0.0000000000000000e+00 -1.9485571585149869e-01 ] nln_ineq_con_3 gradient

    ------------------------------------------
    Restart record    2  (evaluation id    2):
    ------------------------------------------
    Parameters:
                          2.1640000000000001e+00 intake_dia
                          1.7169994018008317e+00 flatness

    Active response data:
    Active set vector = { 3 3 3 3 }
                         -2.4869127192988878e+00 obj_fn
                          6.9256958799989843e-01 nln_ineq_con_1
                         -3.4245008972987528e-01 nln_ineq_con_2
                          8.7142207937157910e-03 nln_ineq_con_3
     [ -4.3644298963447897e-01  1.4999999999999999e-01 ] obj_fn gradient
     [  2.9814239699997572e+01  0.0000000000000000e+00 ] nln_ineq_con_1 gradient
     [  0.0000000000000000e+00  1.4999999999999999e-01 ] nln_ineq_con_2 gradient
     [  0.0000000000000000e+00 -1.6998301774282701e-01 ] nln_ineq_con_3 gradient

    ...<snip>...

    Restart file processing completed: 11 evaluations retrieved.
\endverbatim

\section dakota_restart_utility-neutral Neutral File Format

A Dakota restart file can be converted to a neutral file format using
a command like the following:
\verbatim
    dakota_restart_util to_neutral dakota.rst dakota.neu
\endverbatim
which results in a report similar to the following:
\verbatim
    Writing neutral file dakota.neu
    Restart file processing completed: 11 evaluations retrieved.
\endverbatim

Similarly, a neutral file can be returned to binary format using a
command like the following:
\verbatim
    dakota_restart_util from_neutral dakota.neu dakota.rst
\endverbatim
which results in a report similar to the following:
\verbatim
    Reading neutral file dakota.neu
    Writing new restart file dakota.rst
    Neutral file processing completed: 11 evaluations retrieved.
\endverbatim

The contents of the generated neutral file are similar to the 
following (from the first two records for the
Cylinder example in \cite UsersMan).
\verbatim
    6 7 2 1.8000000000000000e+00 intake_dia 1.0000000000000000e+00 flatness 0 0 0 0
    NULL 4 2 1 0 3 3 3 3 1 2 obj_fn nln_ineq_con_1 nln_ineq_con_2 nln_ineq_con_3
      -2.4355973813420619e+00 -4.7428486677140930e-01 -4.5000000000000001e-01
       1.3971143170299741e-01 -4.3644298963447897e-01  1.4999999999999999e-01
       1.3855136437818300e-01  0.0000000000000000e+00  0.0000000000000000e+00
       1.4999999999999999e-01  0.0000000000000000e+00 -1.9485571585149869e-01 1
    6 7 2 2.1640000000000001e+00 intake_dia 1.7169994018008317e+00 flatness 0 0 0 0
    NULL 4 2 1 0 3 3 3 3 1 2 obj_fn nln_ineq_con_1 nln_ineq_con_2 nln_ineq_con_3
      -2.4869127192988878e+00 6.9256958799989843e-01 -3.4245008972987528e-01
       8.7142207937157910e-03 -4.3644298963447897e-01  1.4999999999999999e-01
       2.9814239699997572e+01  0.0000000000000000e+00  0.0000000000000000e+00
       1.4999999999999999e-01  0.0000000000000000e+00 -1.6998301774282701e-01 2
\endverbatim

This format is not intended for direct viewing (\c print should be
used for this purpose). Rather, the neutral file capability has been
used in the past for managing portability of restart data across
platforms (recent use of more portable binary formats has largely
eliminated this need) or for advanced repair of restart records (in
cases where the \c remove command was insufficient).

\section dakota_restart_utility-tabular Tabular Format

Conversion of a binary restart file to a tabular format enables
convenient import of this data into 3rd-party post-processing tools
such as Matlab, TECplot, Excel, etc. This facility is nearly identical
to the output activated by the \ref environment-tabular_data 
keyword in the Dakota input file specification, but
with two important differences:
-# No function evaluations are suppressed as they are with
  \c tabular_data (i.e., any internal finite
  difference evaluations are included).
-# The conversion can be performed later, i.e., for Dakota
  runs executed previously.

An example command for converting a restart file to tabular format is:
\verbatim
    dakota_restart_util to_tabular dakota.rst dakota.m
\endverbatim
which results in a report similar to the following:
\verbatim
    Writing tabular text file dakota.m
    Restart file processing completed: 10 evaluations tabulated.
\endverbatim

The contents of the generated tabular file are similar to the following 
(from the example in the Restart section of \cite UsersMan).
Note that while evaluations resulting from numerical derivative offsets would be
reported (as described above), derivatives returned as part of the
evaluations are not reported (since they do not readily fit within a
compact tabular format):
\verbatim
%eval_id interface             x1             x2         obj_fn nln_ineq_con_1 nln_ineq_con_2 
1            NO_ID            0.9            1.1         0.0002           0.26           0.76 
2            NO_ID        0.90009            1.1 0.0001996404857   0.2601620081       0.759955 
3            NO_ID        0.89991            1.1 0.0002003604863   0.2598380081       0.760045 
4            NO_ID            0.9        1.10011 0.0002004407265       0.259945   0.7602420121 
5            NO_ID            0.9        1.09989 0.0001995607255       0.260055   0.7597580121 
6            NO_ID     0.58256179   0.4772224441   0.1050555937   0.1007670171 -0.06353963386 
7            NO_ID   0.5826200462   0.4772224441   0.1050386469   0.1008348962 -0.06356876195 
8            NO_ID   0.5825035339   0.4772224441   0.1050725476   0.1006991449 -0.06351050577 
9            NO_ID     0.58256179   0.4772701663   0.1050283245    0.100743156 -0.06349408333 
10           NO_ID     0.58256179   0.4771747219   0.1050828704   0.1007908783 -0.06358517983 
...
\endverbatim

<b>Controlling tabular format:</b> The command-line options
<tt>\--freeform</tt> and <tt>\--custom_annotated</tt> give control of
headers in the resulting tabular file.  Freeform will generate a
tabular file with no leading row nor columns (variable and response
values only).  Custom annotated format accepts any or all of the
options:

\li \c header: include %-commented header row with labels
\li \c eval_id: include leading column with evaluation ID
\li \c interface_id: include leading column with interface ID

For example, to recover Dakota 6.0 tabular format, which contained a
header row, leading column with evaluation ID, but no interface ID:
\verbatim
dakota_restart_util to_tabular dakota.rst dakota.m --custom_annotated header eval_id
\endverbatim
Resulting in
\verbatim
%eval_id             x1             x2         obj_fn nln_ineq_con_1 nln_ineq_con_2 
1                   0.9            1.1         0.0002           0.26           0.76 
2               0.90009            1.1 0.0001996404857   0.2601620081       0.759955 
3               0.89991            1.1 0.0002003604863   0.2598380081       0.760045 
...
\endverbatim

Finally, <tt>\--output_precision integer</tt> will generate tabular
output with the specified integer digits of precision.

\section dakota_restart_utility-concat Concatenation of Multiple Restart Files

In some instances, it is useful to combine restart files into a single
master function evaluation database. For example, when constructing a
data fit surrogate model, data from previous studies can be pulled in
and reused to create a combined data set for the surrogate fit. An
example command for concatenating multiple restart files is:
\verbatim
    dakota_restart_util cat dakota.rst.1 dakota.rst.2 dakota.rst.3 dakota.rst.all
\endverbatim
which results in a report similar to the following:
\verbatim
    Writing new restart file dakota.rst.all
    dakota.rst.1 processing completed: 10 evaluations retrieved.
    dakota.rst.2 processing completed: 110 evaluations retrieved.
    dakota.rst.3 processing completed: 65 evaluations retrieved.
\endverbatim

The \c dakota.rst.all database now contains 185 evaluations and
can be read in for use in a subsequent Dakota study using the
\c -read_restart option to the \c dakota executable.

\section dakota_restart_utility-corrupted Removal of Corrupted Data

On occasion, a simulation or computer system failure may cause a
corruption of the Dakota restart file. For example, a simulation crash
may result in failure of a post-processor to retrieve meaningful data.
If 0's (or other erroneous data) are returned from the user's
\c analysis_driver, then this bad data will get recorded in the
restart file. If there is a clear demarcation of where corruption
initiated (typical in a process with feedback, such as gradient-based
optimization), then use of the \c -stop_restart option for the
\c dakota executable can be effective in continuing the study
from the point immediately prior to the introduction of bad data. If,
however, there are interspersed corruptions throughout the restart
database (typical in a process without feedback, such as sampling),
then the \c remove and \c remove_ids options of
\c dakota_restart_util can be useful.

An example of the command syntax for the \c remove option is:
\verbatim
    dakota_restart_util remove 2.e-04 dakota.rst dakota.rst.repaired
\endverbatim
which results in a report similar to the following:
\verbatim
    Writing new restart file dakota.rst.repaired
    Restart repair completed: 65 evaluations retrieved, 2 removed, 63 saved.
\endverbatim
where any evaluations in \c dakota.rst having an active response
function value that matches \c 2.e-04 within machine precision
are discarded when creating \c dakota.rst.repaired.

An example of the command syntax for the \c remove_ids option is:
\verbatim
    dakota_restart_util remove_ids 12 15 23 44 57 dakota.rst dakota.rst.repaired
\endverbatim
which results in a report similar to the following:
\verbatim
    Writing new restart file dakota.rst.repaired
    Restart repair completed: 65 evaluations retrieved, 5 removed, 60 saved.
\endverbatim
where evaluation ids \c 12, \c 15, \c 23,
\c 44, and \c 57 have been discarded when creating
\c dakota.rst.repaired. An important detail is that, unlike the 
\c -stop_restart option which operates on restart record numbers, 
the \c remove_ids
option operates on evaluation ids. Thus, removal is not necessarily
based on the order of appearance in the restart file. This distinction
is important when removing restart records for a run that contained
either asynchronous or duplicate evaluations, since the restart
insertion order and evaluation ids may not correspond in these cases
(asynchronous evaluations have ids assigned in the order of job
creation but are inserted in the restart file in the order of job
completion, and duplicate evaluations are not recorded which
introduces offsets between evaluation id and record number). This can
also be important if removing records from a concatenated restart
file, since the same evaluation id could appear more than once. In
this case, all evaluation records with ids matching the
\c remove_ids list will be removed.

If neither of these removal options is sufficient to handle a
particular restart repair need, then the fallback position is to
resort to direct editing of a neutral file 
to perform the necessary
modifications.
