###############################################################################
#####     Definition of Evaluator Control Parameters attributes    ############
#####
##### . Each definition must be separated by at least a comment line
#####     (starting by #)
#####
##### . The definition must provide the name, type and default value
#####     (no default: '-' or 'N/A') in this order, one by line.
#####
##### . Only a single word is considered for the name,
#####     type and default value (extra is comment)
#####
##### . The short info, the help and the keywords must be provided in this
#####     order within "\(" and "\). For keywords, the plural part of a word
#####     can be put in parenthesis; both singular and plural will be keywords
#####
##### . The default value is automatically reported in the help.
#####
##### . In addition, the definition can have optional attributes:
#####       - ALGO_COMPATIBILITY_CHECK yes/no, the default is no. If yes, the
#####         value of this attribute can be used for comparing two sets of
#####         attributes for algorithm compatibility. This is used by the
#####         Runner.
#####
#####       - RESTART_ATTRIBUTE yes/no, the default is no. If yes, the
#####         value of this attribute can be modified during hot or warm
#####         restart. Otherwise, modifying this attribute during hot restart
#####         will trigger an error message.
#####
#####       - UNIQUE_ENTRY yes/no, the default is yes. If no, multiple
#####         values may be assigned to this parameter.
#####
###############################################################################
BB_MAX_BLOCK_SIZE
size_t
1
\( Size of blocks of points, to be used for parallel evaluations \)
\(
. Maximum size of a block of evaluations send to the blackbox
  executable at once. Blackbox executable can manage parallel
  evaluations on its own. Opportunistic strategies may apply after
  each block of evaluations.

. Depending on the algorithm phase, the blackbox executable will
  receive at most BB_MAX_BLOCK_SIZE points to evaluate.

. When this parameter is greater than one, the number of evaluations
  may exceed the MAX_BB_EVAL stopping criterion.

. Argument: integer > 0.

. Example: BB_MAX_BLOCK_SIZE 3
           The blackbox executable receives blocks of
           at most 3 points for evaluation.

\)
\( advanced block parallel \)
ALGO_COMPATIBILITY_CHECK yes
RESTART_ATTRIBUTE yes
################################################################################
SURROGATE_MAX_BLOCK_SIZE
size_t
1
\( Size of blocks of points, to be used for parallel evaluations \)
\(
. Maximum size of a block of evaluations send to the surrogate
  executable at once. Surrogate executable can manage parallel
  evaluations on its own.

. Depending on the algorithm phase, the surrogate executable will
  receive at most SURROGATE_MAX_BLOCK_SIZE points to evaluate.

. Argument: integer > 0.

. Example: SURROGATE_MAX_BLOCK_SIZE INF
           The surrogate executable receives blocks with
           all points evailable for evaluation.

\)
\( advanced block parallel surrogate \)
ALGO_COMPATIBILITY_CHECK yes
RESTART_ATTRIBUTE yes
################################################################################
EVAL_QUEUE_CLEAR
bool
true
\( Opportunistic strategy: Flag to clear EvaluatorControl queue between each run \)
\(

. Opportunistic strategy: If a success is found, clear evaluation queue of
  other points.

. If this flag is false, the points in the evaluation queue that are not yet
  evaluated might be evaluated later.

. If this flag is true, the points in the evaluation queue that are not yet
  evaluated will be flushed.

. Outside of opportunistic strategy, this flag has no effect.

\)
\( advanced opportunistic oppor eval(s) evaluation(s) clear flush \)
ALGO_COMPATIBILITY_CHECK yes
RESTART_ATTRIBUTE yes
#################################################################################
EVAL_SURROGATE_COST
size_t
INF
\( Cost of the surrogate function versus the true function \)
\(
  . Cost of the surrogate function relative to the true function

  . Argument: one nonnegative integer.

  . INF means there is no cost

  . Examples:
        EVAL_SURROGATE_COST 3    # three surrogate evaluations count as one blackbox
                                 # evaluation: the surrogate is three times faster
        EVAL_SURROGATE_COST INF  # set to infinity: A surrogate evaluation does
                                 # not count at all

  . See also: SURROGATE_EXE, EVAL_SURROGATE_OPTIMIZATION
\)
\( advanced static surrogate \)
ALGO_COMPATIBILITY_CHECK yes
RESTART_ATTRIBUTE no
################################################################################
MAX_BB_EVAL
size_t
INF
\( Stopping criterion on the number of blackbox evaluations \)
\(

. Maximum number of blackbox evaluations. When OpenMP is activated, this budget
maybe exceeded due to parallel evaluations.

. Argument: one positive integer.

. An INF value serves to disable the stopping criterion.

. Does not consider evaluations taken in the cache (cache hits)

. Example: MAX_BB_EVAL 1000

\)
\( basic stop(s) stopping max maximum criterion(s) blackbox(es) bb \)
ALGO_COMPATIBILITY_CHECK no
RESTART_ATTRIBUTE yes
################################################################################
MAX_BLOCK_EVAL
size_t
INF
\( Stopping criterion on the number of blocks evaluations \)
\(

. Maximum number of blocks evaluations

. Argument: one positive integer.

. An INF value serves to disable the stopping criterion.

. Example: MAX_BLOCK_EVAL 100

\)
\( advances block stop parallel \)
ALGO_COMPATIBILITY_CHECK yes
RESTART_ATTRIBUTE yes
################################################################################
MAX_EVAL
size_t
INF
\( Stopping criterion on the number of evaluations (blackbox and cache) \)
\(

. Maximum number of evaluations, including evaluations taken in the cache
  (cache hits)

. Argument: one positive integer.

. An INF value serves to disable the stopping criterion.

. Example: MAX_EVAL 1000

\)
\( advanced stop(s) stopping max maximum criterion(s) blackbox(es) bb eval(s) evaluation(s) cache \)
ALGO_COMPATIBILITY_CHECK no
RESTART_ATTRIBUTE yes
################################################################################
MAX_SURROGATE_EVAL_OPTIMIZATION
size_t
INF
\( Stopping criterion on the number of static surrogate evaluations \)
\(

. Maximum number of static surrogate evaluations

. Argument: one positive integer.

. An INF value serves to disable the stopping criterion.

. Does not consider evaluations taken in the cache (cache hits)

. Only used when EVAL_SURROGATE_OPTIMIZATION is true.

. Example: MAX_SURROGATE_EVAL_OPTIMIZATION 1000

\)
\( basic stop max maximum surrogate \)
ALGO_COMPATIBILITY_CHECK no
################################################################################
MODEL_MAX_BLOCK_SIZE
size_t
INF
\( Internal parameter for QUAD_MODEL_MAX_BLOCK_SIZE and SGTELIB_MODEL_MAX_BLOCK_SIZE \)
\(
. CANNOT BE MODIFIED BY USER. Internal parameter.
\)
\( internal \)
ALGO_COMPATIBILITY_CHECK yes
RESTART_ATTRIBUTE yes
################################################################################
MODEL_MAX_EVAL
size_t
1000
\( Internal parameter for QUAD_MODEL_MAX_EVAL and SGTELIB_MODEL_MAX_EVAL \)
\(
. CANNOT BE MODIFIED BY USER. Internal parameter.
\)
\( internal \)
ALGO_COMPATIBILITY_CHECK no
RESTART_ATTRIBUTE no
################################################################################
QUAD_MODEL_MAX_BLOCK_SIZE
size_t
INF
\( Size of blocks of points, to be used for parallel evaluations \)
\(
. Maximum size of a block of evaluations send to the quad model evaluator
  at once. Opportunistic strategies may apply after each block of evaluations.

. Depending on the algorithm phase, the quad model will
  receive at most QUAD_MODEL_MAX_BLOCK_SIZE points to evaluate.

. When this parameter is greater than one, the number of evaluations
  may exceed the QUAD_MODEL_MAX_EVAL stopping criterion.

. Argument: integer > 0.

. Example: QUAD_MODEL_MAX_BLOCK_SIZE 100
           The blackbox executable receives blocks of
           at most 100 points for evaluation.

\)
\( advanced block parallel \)
ALGO_COMPATIBILITY_CHECK yes
RESTART_ATTRIBUTE yes
################################################################################
QUAD_MODEL_MAX_EVAL
size_t
2000
\( Max number of model evaluations for optimization of the quad model problem \)
\(
. Max number of model evaluations for each optimization of the quad model problem.

. Argument: one integer > 0.

. The number of evaluations may exceed this parameter when parameter
  QUAD_MODEL_MAX_BLOCK_SIZE is greater than one.
  
. For faster quadratic model search execution this value can be reduced to 1000.
  However, this can effect the quality of trial points obtained by quad model
  search.

. Example: QUAD_MODEL_MAX_EVAL 5000
\)
\( advanced quad search model model_search \)
ALGO_COMPATIBILITY_CHECK yes
RESTART_ATTRIBUTE yes
################################################################################
SGTELIB_MODEL_MAX_BLOCK_SIZE
size_t
INF
\( Size of blocks of points, to be used for parallel evaluations \)
\(
. Maximum size of a block of evaluations send to the sgtelib model evaluator
  at once. Opportunistic strategies may apply after each block of evaluations.

. Depending on the algorithm phase, the sgtelib will
  receive at most SGTELIB_MODEL_MAX_BLOCK_SIZE points to evaluate.

. When this parameter is greater than one, the number of evaluations
  may exceed the SGTELIB_MODEL_MAX_EVAL stopping criterion.

. Argument: integer > 0.

. Example: SGTELIB_MODEL_MAX_BLOCK_SIZE 100
           The blackbox executable receives blocks of
           at most 100 points for evaluation.

\)
\( advanced block parallel \)
ALGO_COMPATIBILITY_CHECK yes
RESTART_ATTRIBUTE yes
################################################################################
SGTELIB_MODEL_MAX_EVAL
size_t
2000
\( Max number of model evaluations for each optimization of the sgtelib model problem \)
\(
. Max number of model evaluations for each optimization of the sgtelib model problem.

. Argument: one integer > 0. 

. The number of evaluations may exceed this parameter when parameter SGTELIB_MODEL_MAX_BLOCK_SIZE
  is greater than one.

. Example: SGTELIB_MODEL_MAX_EVAL 5000
\)
\( advanced sgtelib search model model_search \)
ALGO_COMPATIBILITY_CHECK yes
RESTART_ATTRIBUTE yes
################################################################################
TMP_DIR
std::string
-
\( Directory where to put temporary files \)
\(

. Temporary directory for blackbox input/output files

. Argument: one string indicating a directory

. Improved performance with a local temporary directory

. Default is empty. Input/output files are put in problem directory

. Example: TMP_DIR /tmp

\)
\( advanced \)
ALGO_COMPATIBILITY_CHECK no
RESTART_ATTRIBUTE no
################################################################################
USE_CACHE_FILE_FOR_RERUN
bool
false
\( Cache file for rerun \)
\(

. Flag to allow a cache set for rerun optimization.

. The cache for rerun is filled with evaluation points in the cache file (if 
  it is provided, otherwise the option is inactive).
  
. The cache set for rerun complements the regular cache set. The regular
  is used for testing if a point has already be evaluated 
  (but not only for that).
  
. If an algorithm proposes a new trial point (not in regular cache), that is in
  the cache for rerun, the evaluation results will be used.
  
. Points not in cache for rerun will be evaluated with blackbox. This allow to
  perform a hot restart or reset the state of an algorithm to suggest new points.

. If no cache file is provided simply revert to blackbox evaluation.

. Argument: bool

. Example: USE_CACHE_FILE_FOR_RERUN true

\)
\( advanced \)
ALGO_COMPATIBILITY_CHECK no
RESTART_ATTRIBUTE no
################################################################################
NB_THREADS_PARALLEL_EVAL
int
1
\( Max number of threads used for parallel evaluations of each algorithm \)
\(
. A value greater than 1 is possible only if code is built with OpenMP enabled.

. Argument: One positive integer, or -1. A value of -1 means OpenMP decides
  by itself.

. Example: NB_THREADS_PARALLEL_EVAL 4
\)
\( advanced parallel openmp omp evaluator evaluation \)
ALGO_COMPATIBILITY_CHECK yes
RESTART_ATTRIBUTE no
################################################################################
