.. _Configuration:

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

The Python client is looking for a configuration ``.jcmoptimizer.conf.yml`` in:

* the current directory of the Python script,
* in your home directory, which is
  
  * under Linux ``/home/<user name>/.jcmoptimizer.conf.yml``,
  * unser Windows ``C:\Users\<user name>\.jcmoptimizer.conf.yml``.

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 Python client starts a local
   server. The value can be also set on a per-server basis using
   :class:`jcmoptimizer.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/>`_.
:jcm_optimizer_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:`jcmoptimizer.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:`jcmoptimizer.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:`jcmoptimizer.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:`jcmoptimizer.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:`jcmoptimizer.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:`jcmoptimizer.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:`jcmoptimizer.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:`jcmoptimizer.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/'