.. _topic-package_scolib:

Package: SCOLIB
===============

SCOLIB (formerly known as COLINY) is a collection of nongradient-based
optimizers that support the Common Optimization Library INterface
(COLIN).  SCOLIB optimizers currently include ``coliny_cobyla``,
``coliny_direct``, ``coliny_ea``, ``coliny_pattern_search`` and
``coliny_solis_wets``.  (Yes, the input spec still has "coliny" prepended
to the method name.)  Additional SCOLIB information is available from
https://software.sandia.gov/trac/acro.

SCOLIB solvers now support bound constraints and general nonlinear
constraints.  Supported nonlinear constraints include both equality
and two-sided inequality constraints.  SCOLIB solvers do not yet
support linear constraints.  Most SCOLIB optimizers treat constraints
with a simple penalty scheme that adds ``constraint_penalty`` times the
sum of squares of the constraint violations to the objective function.
Specific exceptions to this method for handling constraint violations
are noted below.  (The default value of ``constraint_penalty`` is
1000.0, except for methods that dynamically adapt their constraint
penalty, for which the default value is 1.0.)

The method independent controls for ``max_iterations`` and
``max_function_evaluations`` limit the number of major iterations and the
number of function evaluations that can be performed during a SCOLIB
optimization, respectively. The ``convergence_tolerance`` control
defines the threshold value on relative change in the objective
function that indicates convergence. The ``output`` verbosity
specification controls the amount of information generated by SCOLIB:
the ``silent``, ``quiet``, and ``normal`` settings correspond to minimal
reporting from SCOLIB, whereas the ``verbose`` setting corresponds to a
higher level of information, and ``debug`` outputs method
initialization and a variety of internal SCOLIB diagnostics. The
majority of SCOLIB's methods perform independent function evaluations
that can directly take advantage of Dakota's parallel
capabilities. Only ``coliny_solis_wets``, ``coliny_cobyla``, and certain
configurations of ``coliny_pattern_search`` are inherently serial.
The parallel methods automatically utilize
parallel logic when the Dakota configuration supports
parallelism. Lastly, neither ``speculative`` gradients nor linear
constraints are currently supported with SCOLIB.

Some SCOLIB methods exploit parallelism through the use of Dakota's
concurrent function evaluations. The nature of the algorithms,
however, limits the amount of concurrency that can be exploited. The
maximum amount of evaluation concurrency that can be leveraged by the
various methods is as follows:


- COBYLA: one
- DIRECT: twice the number of variables
- Evolutionary Algorithms: size of the population
- Pattern Search: size of the search pattern
- Solis-Wets: one

All SCOLIB methods support the ``show_misc_options`` optional
specification which results in a dump of all the allowable method
inputs. Note that the information provided by this command refers to
optimizer parameters that are internal to SCOLIB, and which may differ
from corresponding parameters used by the Dakota interface. The
``misc_options`` optional specification provides a means for inputing
additional settings supported by the SCOLIB methods but which are not
currently mapped through the Dakota input specification. Care must be
taken in using this specification; they should only be employed by
users familiar with the full range of parameter specifications
available directly from SCOLIB and understand any differences that
exist between those specifications and the ones available through
Dakota.

Each of the SCOLIB methods supports the ``solution_target`` control,
which defines a convergence criterion in which the optimizer will
terminate if it finds an objective function value lower than the
specified target.