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:

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:

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:

[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.

Environment Variables: System environment variables (e.g., set in your shell or Docker environment) will override settings from the TOML file and .env files.
.env files: Settings defined in a .env file (e.g., .env, .env.development) will override settings from the TOML file.
TOML Configuration File: The primary configuration is loaded from a TOML file named pywasp_config.toml located in your application’s configuration directory.
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:

export PYWASP_DOWNLOAD__DOWNLOAD_PROMPT=False

Local licensing in the [licensing] section:

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.

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.

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.

[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 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:

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:

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:

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:

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.