.. _Configuration:

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

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

* the current directory of the Matlab 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


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/>`_.
: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:`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`.

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'
   
   # Configuration for local JCMoptimizer
   jcmoptimizer_dir: '~/JCMoptimizer/'
   license_dir: '~/JCMsuite/license/'
   save_dir: '~/studies/'