.. _Configuration:

Configuration
===============

The Matlab client merges configuration files in this order.
Later files override individual keys from earlier files:

1. The optional file selected by the ``JCMOPTIMIZER_CONFIG`` environment variable.
2. ``.jcmoptimizer.conf.yml`` in your home directory: typically
   ``/home/<user name>/.jcmoptimizer.conf.yml`` on Linux or
   ``C:\Users\<user name>\.jcmoptimizer.conf.yml`` on Windows.
3. ``.jcmoptimizer.conf.yml`` in the current working directory.

Explicit constructor/method arguments override the corresponding configuration
values. 

Keep personal cloud tokens in the home configuration so users can override site
defaults independently.

The YAML configuration file has the following general format:

.. code-block:: yaml

   # This is a comment
   string_key: 'string value'
   linux_directory: '/path/to/directory'
   windows_directory: 'C:\path\to\directory'
   boolean_key1: true
   boolean_key2: false
   float_key1: 1.234
   float_key2: 3.12e-6
   duration1: 01:30:00
   duration2: 00:01:30


The following configuration keys are available:

:server_location (str): Location of JCMoptimizer server.  Options: ``'cloud'`` or
   ``'local'``. Default: ``'cloud'`` if token specified otherwise ``local``.  If
   ``server_location: 'cloud'``, the JCMoptimizer server is started in the cloud.  If
   ``server_location: 'local'``, the Matlab client starts a local
   server. The value can be also set on a per-server basis using
   :class:`Server`.
:token (str): The api token of the user which is required if the host points to a
   cloud-based JCMoptimzier server. The token can be generated on the `cloud
   interface <https://optimizer.jcmwave.com/cloud/tokens/list/>`_.
:jcmoptimizer_dir (str): Directory of a local JCMoptimizer installation.
:license_dir (str): Directory containing license information for JCMsuite,
   e.g. ``'/path/to/JCMsuite/license'``.  This information is necessary for a locally
   running JCMoptimizer.
:save_dir (str): Default directory where studies of a locally running JCMoptimizer
   are saved.  The value can be also set on a per-study basis using
   :func:`Client.create_study`.
:dashboard (boolean): Default ``true``.  If true, a dashboard will be served for each
   study. The value can be also set on a per-study basis using
   :func:`Client.create_study`.
:open_browser (boolean): Default ``true``.  If true, a browser window with the
   dashboard is started when a study is reated.  The value can be also set on a
   per-study basis using
   :func:`Client.create_study`.
:output_precision (float): Default ``1e-10``.  Precision level for output of
   parameters. The value can be also set on a per-study basis using
   :func:`Client.create_study`.
:server_runtime (duration): Format ``HH:MM:SS`` (no quotation marks!),
   e.g. ``00:30:00`` corresponds to 30 minutes. Default ``00:30:00``.  The default
   runtime of a cloud-based server.
:extend_on_request (duration): Format ``HH:MM:SS`` (no quotation marks!),
   e.g. ``00:01:30`` corresponds to 1 minute and 30 seconds.  Default ``00:05:00``.
   The shutdown time of a cloud-based server is extended in each request, such that
   the server will always run for at least the specified amount after the request.
   The value can be also set on a per-study basis using
   :func:`Client.create_study`.
:extend_on_suggestion (duration): Format ``HH:MM:SS`` (no quotation marks!),
   e.g. ``01:30:00`` corresponds to 1 hour and 30 minutes.  Default ``00:30:00``.
   The shutdown time of a cloud-based server is extended in each request, such that
   the server will always run for at least the specified amount after the request.
   The value can be also set on a per-study basis using
   :func:`Client.create_study`.

.. note:: When starting a cloud-based server with default settings, its runtime is 30
   minutes. By default, the runtime is extended in each request for 5 more minutes
   and with each new suggestion for 30 more minutes. This makes sure that a
   cloud-based server does not run unused for more than 30 minutes.

   In some cases, the evaluation of a suggestion on the client side can take more
   than 30 minutes.  Then, a larger value of `extend_on_suggestion` has to be set
   either in the configuration file or in
   :func:`Client.create_study` .

   To save server runtime, we suggestion to shut down the server explicitly at the
   end of a study or if an exception occures using
   :func:`Client.shutdown_server`.
   
   
Example configuration file

.. code-block:: yaml

   # General configurations
   server_location: 'cloud'
   dashboard: true
   open_browser: false
   output_precision: 1e-9
   
   # Configuration for cloud-based JCMoptimizer
   token: '240557813dcf4407194cf016ac0db43a4bdb16978ca47831833baeb869836cbf'
   extend_on_request: 00:01:30
   extend_on_suggestion: 00:45:00
   
   # Configuration for local JCMoptimizer
   jcmoptimizer_dir: '~/JCMoptimizer/'
   license_dir: '~/JCMsuite/license/'
   save_dir: '~/studies/'