.. _user_config:

.. currentmodule:: pywasp

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

PyWAsP's configuration is controlled through a configuration file, environment variables, or ``.env`` files. 
The configuration affects the download of additional files that are used for the modelling, and for the license information.

A TOML (Tom's Obvious, Minimal Language) configuration file will be sent to you with the fields filled in for your license. 
You can just copy this to the default location, which is system-dependent but follows standard user configuration directories:

* **Linux**: ``~/.config/pywasp/pywasp_config.toml``
* **macOS**: ``~/Library/Application Support/pywasp/pywasp_config.toml``
* **Windows**: ``C:\\Users\\<username>\\AppData\\Local\\DTU Wind\\pywasp\\pywasp_config.toml``

You can see the actual location of your configuration file by running the following command:

.. code-block:: python

    import pywasp as pw
    print(pw.user_config.get_config_filepath())

You can manually edit this file if you need, and some options will be provided below. 
Additionally, you can avoid using this file and use dotenv files, or environment variables instead. More on that below.

.. note::

    Quick-start: you can create a new configuration interactively by running:

    .. code-block:: python

        import pywasp as pw
        pw.user_config.create_config_interactively()
    
    This will guide you through the process of setting up your
    configuration and setting up your license. 

    For most users, the default configuration options with ``"keygen_cloud"`` licensing is the way to go. 


Configuration options
======================
The configuration options are organized into sections, each containing specific required and optional fields:

.. code-block:: toml

    [download]
    download_prompt = true  # Prompt to download global netCDF files if not present
    download_global_nc_files = true  # Automatically download global netCDF files if not present

    [licensing]
    license_type = "keygen_cloud"  # options are "keygen_cloud" or "local" 
    license_id = "your_license_id"  # required for cloud licensing
    activation_token = "your_activation_token"  # required for cloud licensing
    redirect_host = "license.windenergy.dtu.dk"  # optional for cloud licensing, to redirect through DTU's server 
    root_ca_filepath = "/path/to/ca.pem"  # optional for cloud licsensing, for custom CA bundle
    host = "my_local_license_server.com"  # required for local licensing
    port = 12345  # required for local licensing"


Configuration Hierarchy
=======================

The application loads configuration settings in a specific order of precedence, 
with the highest priority being listed first here.

1.  **Environment Variables:** System environment variables (e.g., set in your shell or Docker environment) will override
    settings from the TOML file and ``.env`` files.
2.  **.env files:** Settings defined in a ``.env`` file (e.g., ``.env``, ``.env.development``) will override settings 
    from the TOML file.
3.  **TOML Configuration File:** The primary configuration is loaded from a TOML file named ``pywasp_config.toml`` 
    located in your application's configuration directory.
4.  **Default Values:** If a setting is not found in any of the above sources, the application will use its built-in 
    default value.

.. note::
   This order means that if a setting is defined in both your ``pywasp_config.toml`` file and as an environment variable, 
   the environment variable will take precedence.


Environment Variables
----------------------

For environments like Docker containers, or for system-wide overrides, using environment variables might be more 
convenient than a TOML file. Environment variables will override settings found in your 
``pywasp_config.toml`` or ``.env`` files.

All environment variables should be prefixed with ``pywasp_``. For nested settings, use double underscores (``__``) 
to separate the sections and field names.

General Format: ``PYWASP_<SECTION>__<FIELD_NAME>=<VALUE>``

You must always have at least one of the download variables specified, and either the local or cloud licensing setup.

Examples:

* ``download_prompt`` in the ``[download]`` section:

    .. code-block:: bash

       export PYWASP_DOWNLOAD__DOWNLOAD_PROMPT=False

* Local licensing in the ``[licensing]`` section:

    .. code-block:: bash

       export PYWASP_LICENSING__HOST=127.0.0.1
       export PYWASP_LICENSING__PORT=12345


* Cloud licensing in the ``[licensing]`` section::

    .. code-block:: bash

       export PYWASP_LICENSING__LICENSE_ID=a1b2c3d4-e5f6-7890-1234-567890abcdef
       export PYWASP_LICENSING__ACTIVATION_TOKEN=your_activate_token

For windows equivalents, you can look to the Windkit documentation to see how to define these in Windows Command 
Prompt of Windows PowerShell.

dotenv file
-----------

You can also use a ``.env`` file to define your environment variables. This file must be in the directory that you 
launch your python interpreter from. The file can hold key-value pairs of that are the same as the environment variables 
listed above.


PyWAsP licensing
=================

PyWAsP offers two types of licensing, local licensing and cloud licensing. Most users will be using cloud licensing.

Use cloud licensing server
---------------------------

The cloud licensing server is used 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, the license type is listed as ``keygen_cloud``,
and you will have a ``license_id`` and ``activation_token``.  These values are secrets and should be treated like a password.

When PyWAsP starts, it will read these fields, and attempt to connect to our API provider keygen at ``api.keygen.sh``. 
If this is not acceptable from your IT department, you can instead contact DTU's server by adding a ``redirect_host`` 
line to your configuration that points at ``license.windenergy.dtu.dk``.

.. code-block:: toml

    redirect_host = "license.windenergy.dtu.dk"

Another potential cause of failure is the failure of the TLS peering. In this case you should see an SSL error. By default, 
the TLS connection uses the system's root certificates to validate peers. In some corporate environments, 
you may have a custom certificate infrastructure, that requires you to setup a custom or self-signed Certificate Authority (CA). In this case you can add a ``root_ca_filepath`` field, that points to the CA bundle that includes this additional certificate.

.. code-block:: toml

  root_ca_filepath = "/path/to/file.pem"


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

If you are using an Enterprise license, i.e. `pywasp` is installed in on-premise
servers at a research institution or a big company, your company will have a licensing server that runs on its 
internal network. In this case, you don't need to worry about the ``license_id`` and ``activation_token``, 
as those are part of the license server. Instead, you need to specify the host and port that are provided by your institution.

This means that you will need to edit the licensing part of your TOML file to look like below, 
replacing the host and port with your values.

.. code-block:: toml
    
    [licensing]
    license_type = "local"
    host = "127.0.0.1"
    port = 34523


When you import pywasp for the first time, it will check that there is a connection to this server, 
and will throw an error if it cannot be reached.

Download global netCDF files
=============================

In addition to license configuration, the configuration file controls the behavior related to downloading 
of global netCDF files. These files are used for calculating the baroclinicity, stability, and air 
density used in the PyWAsP simulations. Please refer to the WAsP documentation for further details.

Download Options
----------------

There are two options related to downloading these files. By default, both are set to ``True``, but you may chose 
to disable either for some cases, such as if you don't need the extra functionality, you don't have access to 
internet while installing, or you will copy the files manually later. In this case you can modify the 
``download_prompt`` and ``download_global_nc_files`` fields to get the behavior you desire. The different behaviors 
depending on the settings 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.get_air_density``, ``pywasp.wasp.get_climate`` ), will be prompted to download.
============== =============== ======================== =====================================================================

Configuration API
=================

PyWAsP provides a few functions for viewing information about your configuration, and license. Unfortunately, 
these only work once a configuration has been successful, so they are not intended for debugging.

These functions can be accessed via the :py:mod:`pywasp.user_config` API.

Setting up a new configuration interactively
------------------------------------------------
You can create a new configuration interactively by running the following command:
.. code-block:: python
    
    import pywasp as pw
    pw.user_config.create_config_interactively()

This will guide you through the process of setting up your configuration and setting up your license.

Seeing your configuration file location and license details
------------------------------------------------------------

To see the location of your configuration file, you can use the following command:

.. code-block:: python

    import pywasp as pw
    print(pw.user_config.get_config_filepath())

PyWAsP provides a few functions for viewing information about your configuration, and license. Unfortunately, these only work once a configuration has been successful, so they are not intended for debugging.

To view your current configuration, you can use the following command:

.. code-block:: python

    import pywasp as pw
    pw.user_config.view()
    
Get remaining runs and days until expiration
------------------------------------------------------------

To check your remaining runs, you can use the following command:

.. code-block:: python

    import pywasp as pw
    runs = pw.user_config.get_remaining_runs()
    print(f"Remaining runs: {runs}")

This only works for cloud licensing, and will return ``None`` if you are using local licensing. 

To check the days until your license expires, you can use the following command:

.. code-block:: python

    import pywasp as pw
    days = pw.user_config.days_until_license_expiry()
    print(f"Days until expiration: {days}")

This will return the number of days until your license expires, or ``None`` if you are using local licensing.