.. _user_config:

.. currentmodule:: pywasp

=====================================
PyWAsP License and User Configuration
=====================================

After you install `pywasp`, the first time you call ``import pywasp as pw``, you will be
prompted for the host (URL) of your licensing server. There are two types of licensing
servers, which will be described below.

Use license.windenergy.dtu.dk licensing server
----------------------------------------------

This is the case when you use a Gold, Silver or Bronze Tier license with a limit on the model runs and `pywasp`
is installed in a machine with access to internet. In this case, If you type in ``license.windenergy.dtu.dk``
when prompted for a host, `pywasp` will then ask you for a ``license_id`` and an ``activation_token``,
which will be provided by your institution. The ``license_id`` must have a UUID V4 format, whereas
the ``activation_token`` must be a string. These values are secrets and should be treated like a password.

After the input of the ``license_id`` and the ``activation_token``, `pywasp` will check whether
the server is available. If the licensing server is down, you will get an error message.


Use a local licensing server
----------------------------

This is the case when you use an Enterprise license, i.e. `pywasp` is installed for example in on-premise
servers at a research institution or a big company. The licensing server runs on the same internal network
and you need to specify a host and a port that were provided by your institution.

You need to input a valid URL as a host, e.g. ``127.0.0.1`` (without the `http` prefix). If you input an URL
that is not ``license.windenergy.dtu.dk``, ``pywasp`` will then know it is a local server and will prompt you
for a port which has to be an integer between 0 and 65535. After the input of the port and host, `pywasp` will
check whether the server is available. If you type the host or port wrong, or if the licensing server is down,
you will get an error message.


Download global netCDF files
-----------------------------

After setting up the licensing, you will be asked to download netCDF files that are
needed for some functionality in  ``pywasp``. If you type ``yes``, it will start to
download files, it takes a minute. If you select ``no``, you will be warned about having
limited `pywasp` functionality, and what you can do to download the files at a later time.


From here, you will be able to access all of the ``pywasp`` API from the ``pw`` namespace.

Configuration API
------------------

The steps mentioned in the previous section store the information in a ``.ini`` configuration file.
PyWAsP provides a configuration file for each user. This allows you to control some settings
regarding the downloading of data and the connection to your license server. The configuration can
be updated either by manually editing the file or through the :py:mod:`configuration API <pywasp.config>`.
For example, the following function calls will show the path to the configuration file and its content

.. code-block:: python

    import pywasp as pw
    # Path to file
    pw.config.get_config_filepath()
    PosixPath('/home/user/.config/pywasp/pywasp.cfg')
    # content
    pw.config.view()
    ==============================================
    GENERAL
    ==============================================
    last_modification           11/04/22 13:36:23

    ==============================================
    DOWNLOAD
    ==============================================
    download_prompt             True
    download_global_nc_files    True
    last_download

    ==============================================
    licensing
    ==============================================
    license_type                DTU
    host                        license.windenergy.dtu.dk
    license_id                  463895cb-b305-4d2b-82f9-eb99722c03c2
    activation_token            activ-a92md8ssh3lan44ls03daj

The ``Download`` section allows to control the automatic download of ``netCDF`` files needed for
some calculations (please refer to the WAsP documentation for further details). For example you
may not need the extra functionality, you may not have access to internet while installing, or
you will copy the files manually later. If so, you can edit these flags. The behavior is
summarized in the following table


============== =============== ======================== =====================================================================
files present? download_prompt download_global_nc_files behavior when importing pywasp
============== =============== ======================== =====================================================================
Yes            True            True                     Nothing happens (data exists)
Yes            True            False                    Nothing happens (data exists)
Yes            False           True                     Nothing happens (data exists)
Yes            False           False                    Nothing happens (data exists)
No             True            True                     Prompt asking to download the files.
No             True            False                    Print information about how to get files
No             False           True                     Automatic download of files
No             False           False                    Nothing happens, if trying to use the files in ( ``pywasp.wasp.get_air_density``, ``pywasp.wasp.get_climate`` ), will be prompted to download.
============== =============== ======================== =====================================================================

The ``Licensing`` section allows to set up the licensing server. The first time is set up when
calling ``import pywasp as pw``, but it can be edited later.


The configuration file can be accessed via the :py:mod:`pywasp.config` API.