6.1. General input
******************


6.1.1. Task
===========

The **Task** keyword specifies which type of program to run:

"Task"
   Type:
      Multiple Choice

   Default value:
      Optimization

   Options:
      [Optimization, GenerateReference, SinglePoint, Sensitivity,
      MachineLearning]

   Description:
      Task to run.                   Available options:
      •MachineLearning: Optimization for machine learning models.
      •Optimization: Global optimization powered by GloMPO
      •Generate Reference: Run jobs with reference engine to get
      reference values                   •Single Point: Evaluate the
      current configuration of jobs, training data, and parameters
      •Sensitivity: Measure the sensitivity of the loss function to
      each of the active parameters

See more information about

* Optimization

* GenerateReference

* SinglePoint

* Sensitivity


6.1.2. Job Collection Key
=========================

"JobCollection"
   Type:
      String

   Default value:
      job_collection.yaml

   Description:
      Path to JobCollection YAML file.


6.1.3. Engine Collection Key
============================

If you specify an EngineCollection in the input file, it will override
the engine collection specified inside the job_collection.yaml file.

"EngineCollection"
   Type:
      String

   Default value:
      job_collection_engines.yaml

   Description:
      Path to (optional) JobCollection Engines YAML file.


6.1.4. ParameterInterface Key
=============================

"ParameterInterface"
   Type:
      String

   Default value:
      parameter_interface.yaml

   Description:
      Path to parameter interface YAML file.


6.1.5. DataSet Key
==================

The training set, validation set, and any other data sets are
specified with the "DataSet" recurring block.

Important:

  The "name" of the first dataset **must** be "training_set", and the
  "name" of the second dataset **must** be "validation_set".

   DataSet
      BatchSize integer
      EvaluateEvery integer
      LossFunction [mae | rmse | sse | sae]
      MaxJobs integer
      MaxJobsShuffle Yes/No
      Name string
      Path string
      UsePipe Yes/No
   End

"DataSet"
   Type:
      Block

   Recurring:
      True

   Description:
      Configuration settings for each data set in the optimization.

   "BatchSize"
      Type:
         Integer

      Default value:
         0

      Description:
         Number of data set entries to be evaluated per epoch. Default
         0 means all entries.

   "EvaluateEvery"
      Type:
         Integer

      Default value:
         1

      Description:
         This data set is evaluated every n evaluations of the
         training set.                      This will always be set to
         1 for the training set. For other data sets it will be
         adjusted to the closest multiple of LoggingInterval%General,
         i.e., you cannot evaluate an extra data set more frequently
         than you log it.

   "LossFunction"
      Type:
         Multiple Choice

      Default value:
         sse

      Options:
         [mae, rmse, sse, sae]

      Description:
         Loss function used to quantify the error between model and
         reference values. This becomes the minimization task.
         Available options:                      • mae: Mean absolute
         error                      • rmse: Root mean squared error
         • sse: Sum of squared errors                      • sae: Sum
         of absolute errors

   "MaxJobs"
      Type:
         Integer

      Default value:
         0

      Description:
         Limit each evaluation to a subset of n jobs. Default 0
         meaning all jobs are used.

   "MaxJobsShuffle"
      Type:
         Bool

      Default value:
         No

      Description:
         Use a different job subset every for every evaluation.

   "Name"
      Type:
         String

      Default value:
      Description:
         Unique data set identifier.                      The first
         occurrence of DataSet will always be called training_set.
         The second will always be called validation_set.
         These cannot be overwritten.                      Later
         occurrences will default to data_set_xx where xx starts at 03
         and increments from there. This field can be used to
         customize the latter names.

   "Path"
      Type:
         String

      Description:
         Path to DataSet YAML file.

   "UsePipe"
      Type:
         Bool

      Default value:
         Yes

      Description:
         Use AMS Pipe for suitable jobs to speed-up evaluation.


6.1.6. Results Directory
========================

This key specifies the name of the directory into which the results
will be saved. ParAMS will attempt to create this directory. If it
already exists, ParAMS will automatically increment the directory
name. For example, if "results" already exists, ParAMS will attempt
"results.001". If "results.001" exists, it will attempt "results.002"
and so on.

Tip:

  To allow an existing "ResultsDirectory" to be overwritten, use the "
  --replace" flag on the command line:

     $AMSBIN/params --replace

Note:

  This key will be overwritten by the GUI which always saves results
  to "<jobname>.results".

Note:

  The "-o" or "--outdir" flag will take precedence over this key.

     $AMSBIN/params -o path/to/results

"ResultsDirectory"
   Type:
      String

   Default value:
      results

   GUI name:
      Working directory:

   Description:
      Directory in which output files will be created.
