.. _installation:

=======================
Installation
=======================

The PyWAsP system is distributed through the `conda <https://docs.conda.io/en/latest/>`_ package, dependency, and environment manager via DTU Wind Energy's WAsP Conda Channel.

.. note:: Before you can download the software, you will need an access token for the software, and access to the DTU Wind Energy license server.

Currently, PyWAsP can be installed on Linux and Windows systems. However, the windows installation is considered experimental at this stage,
so we recommend to :ref:`install PyWAsP on windows via WSL <install_via_wsl>`. In the future we expect full support for installation on Windows and MacOS as well.

.. _install_on_linux:

conda/mamba 
==============


1. To install PyWAsP on Linux, you first need a package manager. We recommend `Miniforge <https://github.com/conda-forge/miniforge>`_:

  Miniforge provides both ``conda`` and the faster ``mamba`` commands:
  
  **Linux**

    .. code-block:: bash
    
        wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh
        bash Miniforge3-Linux-x86_64.sh

    Follow the instructions and restart your terminal to activate the base environment.

  **Windows**

   Go to `<https://github.com/conda-forge/miniforge>`_ and download and run the latest ``.exe`` installer for windows.

   Complete the installation using the "default" option and follow the instructions. Then open the "miniforge" prompt which is installed with the miniforge.

   If you prefer to use powershell, run the command:

    .. code-block:: powershell

      conda init powershell

   Now open powershell, which should now have an activate conda environment.


2. Install PyWAsP using `mamba` (recommended for speed) or `conda` by creating a new environment. Replace `<env_name>` with your desired environment name:

  .. code-block:: bash

    mamba create -c https://<user>:<token>@conda.windenergy.dtu.dk/channel/wasp -n <env_name>  pywasp

  Here, `<user>` and `<token>` are your credentials from the license email. 

  .. note:: The Python source code and binaries are installed into a folder in the distribution you installed. For example, if you installed Miniforge,
            the source code is located in ``<path>/miniforge/envs/<env_name>``. Where <path> is the path to the folder where you installed Miniforge,
            and <env_name> is the name of the environment you created.

3. Optionally, you can add the WAsP Conda channel to your conda configuration to simplify future installations.:

  Replace ``<user>`` and ``<token>`` with the credentials from your license email:

  .. code-block:: bash

    mamba config --add channels https://<user>:<token>@conda.windenergy.dtu.dk/channel/wasp

  Verify your channels are configured correctly:

  .. code-block:: bash

    mamba config --show channels

  You should see::

    channels:
     - conda-forge
     - https://<user>:<token>@conda.windenergy.dtu.dk/channel/wasp

  Now you can install PyWAsP in any new environment without specifying the channel again:

    .. code-block:: bash
    
        mamba create -n <env_name> pywasp

  If other channels exist and you run into issues, you can try to remove those additional channels to prevent package conflicts:
 
  .. code-block:: bash

    mamba config --remove channels <channel_name>

4. Activate your environment:

  .. code-block:: bash

    mamba activate <env_name>

5. Verify your installation:

  .. code-block:: bash

    python -c "import pywasp; print(pywasp.__version__)"

6. Optionally, configure PyWAsP interactively by running:

  .. code-block:: bash

    python -c "import pywasp as pw; pw.user_config.create_config_interactively()"

  You'll be prompted for licensing details. For more information, see the :ref:`User Config <user_config>` section.

  If you're new to PyWAsP, explore our :ref:`Tutorials <tutorials>` and :ref:`Examples <examples>`.


pixi 
==========================

`Pixi <https://pixi.sh/>`_ is a modern package manager that provides a fast and reliable way to manage dependencies and environments.

1. First, install pixi by following the instructions at `https://pixi.sh/ <https://pixi.sh/>`_.

2. Create a new pixi project or add PyWAsP to an existing project:

    .. code-block:: bash

      mkdir my-pywasp-project  # (if you don't have a project yet)
      cd my-pywasp-project
      pixi init 
      
3. Add the WAsP conda channel and install PyWAsP:

    .. code-block:: bash

      pixi project channel add https://<user>:<token>@conda.windenergy.dtu.dk/channel/wasp
      pixi add pywasp

    Here, `<user>` and `<token>` are your credentials from the license email.

4. Run PyWAsP in the pixi environment:

    .. code-block:: bash

      pixi run python -c "import pywasp; print(pywasp.__version__)"

5. To work interactively with PyWAsP, start a shell in the pixi environment:

    .. code-block:: bash

      pixi shell

6. Configure PyWAsP interactively (optional):

    .. code-block:: bash 

      pixi run python -c "import pywasp as pw; pw.user_config.create_config_interactively()"

    For more information, see the :ref:`User Config <user_config>` section.


MacOS
=====================

.. warning:: Installation on MacOS is currently not supported. But, look for it in future releases!



Installing a newer version of PyWAsP
====================================

The PyWAsP package is updated regularly. To update your installation to the latest version we recommend installing
a new environment with the latest version of PyWAsP by following the installation instructions above and
giving the new environment a new name. 

If you use pixi, you can update your existing project by running:

.. code-block:: bash

    pixi update 

This will update all packages in your project to the latest versions available in the channels you have configured.



Optional configuration for custom or self-signed Certificate Authority (CA) certificate.
========================================================================================

In order to validate the licensing, `pywasp` must connect to a licensing server. This connection uses TLS for secure
communication. By default, it uses the system's root certificates to validate peers. If you're operating in a private
network with a custom certificate infrastructure, need to setup a custom or self-signed Certificate Authority (CA) certificate.

If you run `pywasp` in this use case, you may get an error that looks like

.. code-block:: bash

  ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate in certificate chain


Or

.. code-block:: bash

  pywasp._errors.LicenseError: DTU License Error 123: The license server is not trusted. Additional root certificates may be needed.


To setup the self-signed CA certificate, you need to add the path to the ``.pem`` file in your local machine, to the pywasp config file.
Your IT administrator should provide you this file. You can find the path to the pywasp config file by opening a python CLI and
running the command 

.. code-block:: python
  
  pywasp.user_config.get_config_filepath()
 

Then, open the file with a text editor and add the following line to the ``[licensing]`` section.

.. code-block:: ini
  
  root_ca_filepath = /path/to/file.pem

See :ref:`User Config <user_config>` for more information on the pywasp config file.


PyWAsP versions and backwards compatibility
===========================================

PyWAsP versions are numbered according to the `EffVer <https://jacobtomlinson.dev/effver/>`_ approach, 
which is versioning scheme which signals the effort required to upgrade to a new version. 
Generally, we try to avoid breaking changes, but we dont promise it, and recommend pinning the version of PyWAsP 
you use in your projects to avoid unexpected changes in behavior.